District Companion

Interaction contract · prototype v1

A voice-first companion developers can inspect, replay, and implement.

One reference for the companion’s ten conversation states, independent capability conditions, action-safety rules, transitions, timing, and native implementation boundaries.

Open interactive prototype Download complete package

Deterministic product reference. No live microphone, speech model, navigation, or app-action API is included.

01 / 10 ready
What can I help with? Quiet idle state, waiting for voice input.
What can I help with? Waiting for a request.

Conversation state

Ten distinct moments, one calm character

Choose a state to inspect its expression, purpose, transition, and interruption rule. Microphone and surface conditions remain separate.

Implementation model

Conversation is only one axis

Do not encode permission, capture, keyboard, or surface visibility into the conversation enum. Those conditions change independently.

01

Conversation

Waking → ready → listening → acknowledged → thinking → result, clarification, or confirmation.

conversationState
02

Microphone

Permission and Mic on/off are distinct. Bot audio can remain available while capture is off.

permission + micEnabled
03

Surface

The draggable entry persists across app pages and is clamped inside the visible screen. Tapping it reveals adjacent Listen, Type, and Dismiss actions before the expanded non-modal overlay.

collapsed | quick-actions | expanded
04

Input

Voice leads. Keyboard is closed by default and joins the same reducer path only after the user opens it.

captureActive + keyboardOpen

Default sequence

From entry to resolution

Safe search path
  1. 1ReadyPrompt
  2. 2ListeningCapture
  3. 3Got itReceipt
  4. 4SearchingResolve
  5. 5SpeakingOutput

Consequential actions

Preview before committing

Purchases, bookings, cancellations, and account changes stop at awaiting-confirmation. Show the exact action and material consequence before proceeding.

Interruption

The screen never locks

District remains usable while the companion works. Speech output can be interrupted by voice or tap; app actions should only stop from an explicit tap.

Partial completion

Report committed work honestly

Never imply an external side effect was undone. Keep committed steps, cancel only future steps, then ask what the user wants to do next.

Developer package

Platform-neutral source files

The ZIP contains the same individual files below. Treat the Swift model as implementation guidance, then connect it to District’s production voice and action systems.

district-companion-handoff.zip Complete package · JSON, Swift, SVG, motion notes, README
JSON State contractStates, events, conditions, timing, and sample action steps. SWIFT Native reference typesCodable enums, state snapshot, action steps, and timing constants. SVG Vector state spriteReusable symbols for all ten pupil-free face poses. MD Motion specificationDurations, loops, reduced-motion behavior, and transition guidance. MD Integration guideBoundaries, recommended architecture, and implementation checklist.