{ "name": "District Companion interaction contract", "version": "1.0.0", "status": "prototype-reference", "canvas": { "width": 240, "height": 240, "centre": 120 }, "palette": { "core": "rgb(79, 37, 157)", "signal": "rgb(180, 139, 246)", "success": "rgb(215, 188, 255)", "eyes": "rgb(242, 236, 225)" }, "timingsMs": { "wake": 850, "acknowledgement": 500, "resolution": 950, "speakingDemo": 3200, "completedHold": 1500, "actionStepDemo": 1200, "naturalBlinkCycle": 7300 }, "independentConditions": { "surfaceState": ["collapsed", "quick-actions", "expanded"], "micPermission": ["unknown", "granted", "denied"], "micEnabled": "boolean", "captureActive": "boolean", "keyboardOpen": "boolean; false by default", "completionResidual": "boolean", "activityKind": ["thinking", "searching"] }, "actionStepStatuses": ["planned", "active", "committed", "cancelled"], "events": [ "SHOW_QUICK_ACTIONS", "HIDE_QUICK_ACTIONS", "OPEN", "COLLAPSE", "WAKE_FINISHED", "START_VOICE", "REQUEST_MIC_ACCESS", "GRANT_PERMISSION", "DENY_PERMISSION", "RESET_PERMISSION", "SUBMIT_PROMPT", "BEGIN_THINKING", "RESOLVE_INPUT", "CONFIRM_ACTION", "DECLINE_ACTION", "ADVANCE_ACTION", "SPEAKING_FINISHED", "COMPLETION_FINISHED", "TOGGLE_MIC", "TOGGLE_KEYBOARD" ], "states": [ { "id": "waking", "name": "Waking up", "meaning": "The companion is becoming available after opening.", "systemBehaviour": "Play the finite wake pose, then transition to ready.", "motion": "Eyes open from a compact rest over 850 ms.", "interruption": "tap-collapse", "visual": { "bodyDiameter": 190, "eyes": [ { "x": 137.95, "y": 81.14, "width": 16.66, "height": 2.98, "rotate": -26.17 }, { "x": 178.72, "y": 71.14, "width": 11.79, "height": 2.98, "rotate": -26.17 } ] } }, { "id": "ready", "name": "What can I help with?", "meaning": "The companion is waiting for a request.", "systemBehaviour": "Show contextual prompting; do not capture until the user acts.", "motion": "Quiet breath, slow gaze drift, and an uneven periodic blink.", "interruption": "not-applicable", "visual": { "bodyDiameter": 190, "eyes": [ { "x": 137.95, "y": 81.14, "width": 16.66, "height": 37.30, "rotate": -26.17 }, { "x": 178.72, "y": 71.14, "width": 11.79, "height": 37.30, "rotate": -26.17 } ] } }, { "id": "listening", "name": "Listening", "meaning": "Voice capture is active and receiving the user’s request.", "systemBehaviour": "Keep the screen interactive; stop capture after input receipt or Mic off.", "motion": "Restrained body pulse and inward signal rings.", "interruption": "tap-or-mic-off", "visual": { "bodyDiameter": 194, "eyes": [ { "x": 99.88, "y": 113.73, "width": 19.95, "height": 42.54, "rotate": -4.35 }, { "x": 153.07, "y": 110.02, "width": 19.11, "height": 42.54, "rotate": -4.35 } ] } }, { "id": "acknowledged", "name": "Got it", "meaning": "The request was captured successfully.", "systemBehaviour": "Give immediate receipt before beginning understanding or search.", "motion": "One finite wink and a short body perk.", "interruption": "tap-collapse", "visual": { "bodyDiameter": 190, "eyes": [ { "x": 85.23, "y": 109.67, "width": 20.78, "height": 43.98, "rotate": 7.11 }, { "x": 137.75, "y": 115.86, "width": 41.77, "height": 8.44, "rotate": 7.11 } ] } }, { "id": "thinking", "name": "Searching", "meaning": "District is interpreting the request or resolving information.", "systemBehaviour": "Use activityKind to distinguish thinking from searching without adding another conversation state.", "motion": "Scanning eyes with thinking beats or a search trace.", "interruption": "tap-collapse; work-continues", "visual": { "bodyDiameter": 184, "eyes": [ { "x": 132.62, "y": 85.07, "width": 14.50, "height": 33.86, "rotate": -26.03 }, { "x": 162.80, "y": 75.74, "width": 12.05, "height": 33.86, "rotate": -26.03 } ] } }, { "id": "clarification", "name": "One detail needed", "meaning": "A required detail is missing and the companion is awaiting a clearer answer.", "systemBehaviour": "Use one canonical state with prompting and awaiting-input phases; do not create a second awaiting-clarification state.", "motion": "Wider attentive eyes and a question signal.", "interruption": "answer-or-collapse", "visual": { "bodyDiameter": 190, "eyes": [ { "x": 58.95, "y": 135.58, "width": 35.91, "height": 47.31, "rotate": -13.48 }, { "x": 114.23, "y": 122.65, "width": 47.87, "height": 47.31, "rotate": -13.48 } ] } }, { "id": "awaiting-confirmation", "name": "Ready to book", "meaning": "A consequential action is fully previewed and waiting for explicit approval.", "systemBehaviour": "Show exact action, cost, and plan; proceed only after confirmation.", "motion": "Steady attentive hold with no urgency loop.", "interruption": "confirm-decline-or-collapse", "visual": { "bodyDiameter": 190, "eyes": [ { "x": 95.40, "y": 126.34, "width": 23.86, "height": 47.38, "rotate": 0.14 }, { "x": 150.92, "y": 126.34, "width": 23.36, "height": 47.38, "rotate": 0.14 } ] } }, { "id": "taking-action", "name": "Booking tickets", "meaning": "District is carrying out confirmed app-action steps.", "systemBehaviour": "Keep the app usable and display planned, active, committed, and cancelled steps.", "motion": "Flattened eyes and a directional progress trace.", "interruption": "explicit-tap-only", "visual": { "bodyDiameter": 192, "eyes": [ { "x": 60.92, "y": 116.78, "width": 22.70, "height": 11.51, "rotate": 0.75 }, { "x": 109.99, "y": 116.78, "width": 28.64, "height": 11.51, "rotate": 0.75 } ] } }, { "id": "speaking", "name": "Here’s what I found", "meaning": "The companion is presenting a result or explaining what happened.", "systemBehaviour": "Keep the underlying screen usable; voice or tap may interrupt spoken output.", "motion": "Large eyes, outward waves, and a light-purple output glow.", "interruption": "voice-or-tap", "visual": { "bodyDiameter": 194, "eyes": [ { "x": 97.07, "y": 142.12, "width": 37.44, "height": 53.24, "rotate": -8.43 }, { "x": 161.48, "y": 142.12, "width": 34.53, "height": 53.59, "rotate": 10.62 } ] } }, { "id": "completed", "name": "Done", "meaning": "The requested action set completed successfully.", "systemBehaviour": "Hold for 1.5 seconds, return to ready, and retain a subtle completion residue until new input.", "motion": "Brief lift and light-purple success accent.", "interruption": "tap-collapse", "visual": { "bodyDiameter": 190, "eyes": [ { "x": 100.15, "y": 105.79, "width": 24.93, "height": 16.07, "rotate": 12.97 }, { "x": 155.49, "y": 105.79, "width": 23.53, "height": 16.12, "rotate": -13.77 } ] } } ], "sampleAction": { "confirmation": "Book two adjacent seats and pay ₹1,180?", "steps": [ { "id": "availability", "label": "Check 8 pm availability", "initialStatus": "planned" }, { "id": "seats", "label": "Reserve two adjacent seats", "initialStatus": "planned" }, { "id": "payment", "label": "Pay ₹1,180", "initialStatus": "planned" } ] }, "integrationBoundaries": [ "No real microphone capture or speech recognition", "No text-to-speech or model integration", "No production navigation or app-action API", "No production eligibility, background activation, analytics, or localization contract" ] }