rockachopa/Timmy-time-dashboard
1
0
Fork 1
Code Issues 65 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

[222-epic] Workshop-Timmy bridge — WebSocket between world and soul #243

New Issue
Closed
opened 2026-03-15 14:35:03 -04:00 by hermes · 1 comment
hermes commented 2026-03-15 14:35:03 -04:00
Collaborator
Copy Link

Epic: #222 — The Workshop: Timmy as Presence

What

The WebSocket connection between the 3D Workshop (browser/iPad) and Timmy's loop (Mac). This is Timmy's nervous system — how his body (3D world) and his mind (reactive loop) communicate.

iPad constraint

Safari on iPad supports WebSockets natively. But:

  • Reconnection is critical. iPad Safari suspends tabs aggressively. The bridge must reconnect silently when the tab wakes up.
  • Battery-aware messaging. Don't keep the socket chatty when idle. Heartbeat interval should be long (30s+). Events batch when possible.
  • Offline graceful. If the bridge is down (Mac asleep, network drop), the Workshop should still render. Timmy goes into "contemplation" mode — ambient idle, no reactions. When the bridge reconnects, he catches up.

Messages: World → Timmy

  • visitor_entered — someone loaded the Workshop (includes device type: iPad, desktop, mobile)
  • visitor_message — someone typed/spoke to Timmy
  • visitor_left — someone closed the tab or Safari suspended it
  • visitor_interaction — tapped on an object, explored an area
  • visitor_voice — audio from iPad mic (if voice-first interaction)

Messages: Timmy → World

  • bark — short text/voice reaction, with optional animation trigger
  • animate — trigger a specific animation (look at crystal ball, wave, pace)
  • ambient_state — mood/state update (calm, focused, excited, contemplative)
  • world_update — change something in the scene (new book on shelf, crystal ball glow)
  • voice_response — audio data for TTS playback on iPad

Architecture

  • timmy-serve already exists as a web server. Extend with WebSocket endpoint.
  • Workshop JS connects on load, sends events, receives reactions.
  • Timmy's sensory loop treats Workshop WebSocket as another data stream.
  • Latency target: <200ms from visitor event to Timmy reaction
  • Must handle Safari's aggressive tab lifecycle (suspend/resume/reconnect)
  • Consider Server-Sent Events as fallback if WebSocket is problematic on certain iPads

Depends on: #222

## Epic: #222 — The Workshop: Timmy as Presence ### What The WebSocket connection between the 3D Workshop (browser/iPad) and Timmy's loop (Mac). This is Timmy's nervous system — how his body (3D world) and his mind (reactive loop) communicate. ### iPad constraint Safari on iPad supports WebSockets natively. But: - **Reconnection is critical.** iPad Safari suspends tabs aggressively. The bridge must reconnect silently when the tab wakes up. - **Battery-aware messaging.** Don't keep the socket chatty when idle. Heartbeat interval should be long (30s+). Events batch when possible. - **Offline graceful.** If the bridge is down (Mac asleep, network drop), the Workshop should still render. Timmy goes into "contemplation" mode — ambient idle, no reactions. When the bridge reconnects, he catches up. ### Messages: World → Timmy - `visitor_entered` — someone loaded the Workshop (includes device type: iPad, desktop, mobile) - `visitor_message` — someone typed/spoke to Timmy - `visitor_left` — someone closed the tab or Safari suspended it - `visitor_interaction` — tapped on an object, explored an area - `visitor_voice` — audio from iPad mic (if voice-first interaction) ### Messages: Timmy → World - `bark` — short text/voice reaction, with optional animation trigger - `animate` — trigger a specific animation (look at crystal ball, wave, pace) - `ambient_state` — mood/state update (calm, focused, excited, contemplative) - `world_update` — change something in the scene (new book on shelf, crystal ball glow) - `voice_response` — audio data for TTS playback on iPad ### Architecture - `timmy-serve` already exists as a web server. Extend with WebSocket endpoint. - Workshop JS connects on load, sends events, receives reactions. - Timmy's sensory loop treats Workshop WebSocket as another data stream. - Latency target: <200ms from visitor event to Timmy reaction - Must handle Safari's aggressive tab lifecycle (suspend/resume/reconnect) - Consider Server-Sent Events as fallback if WebSocket is problematic on certain iPads Depends on: #222
hermes commented 2026-03-19 01:58:10 -04:00
Author
Collaborator
Copy Link

Closing \u2014 this is refined by #362 (Phase 3: Bridge MVP) which is now complete. The WS bridge between Workshop (browser) and Timmy (Python) is operational at /api/world/ws.\n\nSee #362 close comment for the full list of PRs that implemented this.

Closing \u2014 this is refined by #362 (Phase 3: Bridge MVP) which is now complete. The WS bridge between Workshop (browser) and Timmy (Python) is operational at `/api/world/ws`.\n\nSee #362 close comment for the full list of PRs that implemented this.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
222-epic
Workshop: Timmy as Presence (Epic #222)
 actionable
Has a concrete code/config task extracted
 kimi-ready
Scoped and ready for Kimi to pick up
 needs-design
Needs architectural design before implementation
 needs-extraction
Philosophy with unextracted engineering work
 philosophy
Philosophical foundation — informs architecture decisions
 seed:know-purpose
Three Seeds: KNOW YOUR PURPOSE
 seed:serve-real
Three Seeds: SERVE THE REAL
 seed:tell-truth
Three Seeds: TELL THE TRUTH
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Timmy google hermes kimi manus replit rockachopa
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: rockachopa/Timmy-time-dashboard#243
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?