init

README.md

@@ -0,0 +1,83 @@
+## Visual Novel Demo
+
+Run `python main.py` (or `uv run python main.py` if you prefer `uv`) to launch a Gradio-powered visual novel sandbox.
+
+### Features
+- Register characters with sprite URLs or inline SVG data-URIs (see `create_sprite_data_url`).
+- Toggle simple idle animation per character (set `animated=True`) or point to GIF/WebP assets for full animation.
+- Change backgrounds between scenes.
+- Show, hide, and move characters between left/center/right anchors.
+- Display narration or speaker dialogue in a speech-bubble overlay anchored to the scene.
+- Navigate forward/backward through the story timeline.
+- Opt-in webcam overlay per scene: call `builder.set_camera(True|False)` to show or hide the FastRTC stream alongside your story.
+- Voice sandbox: record or upload microphone audio, forward it to a placeholder AI companion, and hear a synthetic confirmation tone back.
+- Dynamixel control (Web Serial): connect over serial to XL330 servos and send goal positions directly from the browser—no Python SDK needed.
+- **Reachy Mini robot control (WebSocket)**: connect to a Reachy Mini robot server and send real-time pose commands for head position, orientation, body yaw, and antennas.
+- Per-scene toggles: show/hide camera, voice, motor, and robot controls with `set_camera`, `set_voice`, `set_motors`, and `set_robot`.
+
+#### Customizing sprites
+- Replace the SVG data-URIs in `build_sample_story()` with your own URLs (PNG/GIF/WebP).
+- For animated sprites, provide an animated GIF/WebP URL and set `animated=True` to also enable the floaty idle motion.
+- If you need frame-based animation control, extend `CharacterDefinition` with additional fields (e.g., `animation_frames`) and update `render_scene()` accordingly.
+
+#### Camera widget
+- Grant permission when prompted; the browser's default camera is streamed with FastRTC (`WebRTC` component).
+- Scenes control whether the webcam appears. If a scene doesn't request it, you'll see a friendly notice instead of the stream.
+- Browsers typically require HTTPS (or `http://localhost`) plus user permission before the stream can start; if the feed doesn’t appear, reload after granting access.
+
+#### Voice sandbox
+- Scenes decide whether voice capture shows up. Call `builder.set_voice(True|False)` per scene; when disabled, the audio UI hides completely.
+- Use the **Voice & Audio Agent** accordion (when visible) to record or upload a clip; hit **Send to voice agent** to hand it to the (placeholder) AI hook.
+- The app echoes your recording for playback and emits a synthetic tone to represent an AI voice. Replace `process_voice_interaction()` in `main.py` with real ASR/LLM/TTS calls to integrate your model stack.
+- Default prompt text gives the agent scene context; edit it freely.
+
+#### Dynamixel XL330 control
+- The control panel lives entirely in the browser using the Web Serial API (Chrome/Edge on desktop). When prompted, select the USB/serial adapter attached to your Dynamixel bus.
+- Choose baud, motor ID, and goal angle in the **Dynamixel XL330 Control** panel; click **Connect serial** (triggers the browser port picker) then **Send goal**. Use **Torque on/off** to toggle torque.
+- Commands write Protocol 2.0 registers: torque enable (64) and goal position (116, 4 bytes). Angles 0–360° map to 0–4095 ticks.
+- Frontend code lives in `web/dxl_webserial.js` and is loaded via `file=web/dxl_webserial.js`, mirroring the structure of `feetech.js`.
+
+#### Reachy Mini robot control
+- Connect to a Reachy Mini robot via WebSocket for real-time pose control during story scenes.
+- **Requirements**: A running Reachy Mini server at `localhost:8000` with WebSocket endpoint `/api/move/ws/set_target`.
+- The connection status is shown in the robot control panel with a color-coded indicator (🔴 disconnected / 🟢 connected).
+- **Enable in scenes**: Call `builder.set_robot(True)` to show the robot control widget for specific scenes.
+- **Send poses from story**: Use `builder.send_robot_pose()` to command the robot when a scene is displayed:
+  ```python
+  builder.send_robot_pose(
+      head_x=0.0, head_y=0.0, head_z=0.02,  # Head position in meters
+      head_roll=0.0, head_pitch=-0.1, head_yaw=0.0,  # Head orientation in radians
+      body_yaw=0.0,  # Body rotation in radians
+      antenna_left=-0.2, antenna_right=0.2  # Antenna positions in radians
+  )
+  ```
+- WebSocket automatically connects when the widget becomes visible and reconnects if disconnected.
+- Poses are sent automatically when navigating to scenes with robot commands (similar to motor commands and audio).
+
+Edit `main.py` to customize `build_sample_story()` or create your own builder logic with `VisualNovelBuilder`.
+
+### Using Custom Assets
+
+Place your files in the `assets/` directory:
+- `assets/backgrounds/` - Background images (1200x800 recommended)
+- `assets/sprites/` - Character sprites (400x800 recommended, PNG with transparency)
+- `assets/audio/` - Audio files (WAV, MP3, etc.)
+
+Then use the helper functions in your story:
+
+```python
+from engine import background_asset, sprite_asset, audio_asset
+
+builder.set_background(background_asset("my_background.png"), label="My Scene")
+
+builder.set_characters([
+    CharacterDefinition(
+        name="Hero",
+        image_url=sprite_asset("hero.png"),
+        animated=False
+    ),
+])
+
+# Play audio when scene is displayed
+builder.play_sound(audio_asset("my_sound.wav"))
+```

dynamixel.py

@@ -0,0 +1,119 @@
+"""Dynamixel Protocol 2.0 implementation in Python."""
+
+from typing import List, Tuple
+
+
+def crc16_update(crc_accum: int, data: bytes) -> int:
+    """Update CRC16 with new data."""
+    crc_table = [
+        0x0000, 0x8005, 0x800F, 0x000A, 0x801B, 0x001E, 0x0014, 0x8011,
+        0x8033, 0x0036, 0x003C, 0x8039, 0x0028, 0x802D, 0x8027, 0x0022,
+        0x8063, 0x0066, 0x006C, 0x8069, 0x0078, 0x807D, 0x8077, 0x0072,
+        0x0050, 0x8055, 0x805F, 0x005A, 0x804B, 0x004E, 0x0044, 0x8041,
+        0x80C3, 0x00C6, 0x00CC, 0x80C9, 0x00D8, 0x80DD, 0x80D7, 0x00D2,
+        0x00F0, 0x80F5, 0x80FF, 0x00FA, 0x80EB, 0x00EE, 0x00E4, 0x80E1,
+        0x00A0, 0x80A5, 0x80AF, 0x00AA, 0x80BB, 0x00BE, 0x00B4, 0x80B1,
+        0x8093, 0x0096, 0x009C, 0x8099, 0x0088, 0x808D, 0x8087, 0x0082,
+        0x8183, 0x0186, 0x018C, 0x8189, 0x0198, 0x819D, 0x8197, 0x0192,
+        0x01B0, 0x81B5, 0x81BF, 0x01BA, 0x81AB, 0x01AE, 0x01A4, 0x81A1,
+        0x01E0, 0x81E5, 0x81EF, 0x01EA, 0x81FB, 0x01FE, 0x01F4, 0x81F1,
+        0x81D3, 0x01D6, 0x01DC, 0x81D9, 0x01C8, 0x81CD, 0x81C7, 0x01C2,
+        0x0140, 0x8145, 0x814F, 0x014A, 0x815B, 0x015E, 0x0154, 0x8151,
+        0x8173, 0x0176, 0x017C, 0x8179, 0x0168, 0x816D, 0x8167, 0x0162,
+        0x8123, 0x0126, 0x012C, 0x8129, 0x0138, 0x813D, 0x8137, 0x0132,
+        0x0110, 0x8115, 0x811F, 0x011A, 0x810B, 0x010E, 0x0104, 0x8101,
+        0x8303, 0x0306, 0x030C, 0x8309, 0x0318, 0x831D, 0x8317, 0x0312,
+        0x0330, 0x8335, 0x833F, 0x033A, 0x832B, 0x032E, 0x0324, 0x8321,
+        0x0360, 0x8365, 0x836F, 0x036A, 0x837B, 0x037E, 0x0374, 0x8371,
+        0x8353, 0x0356, 0x035C, 0x8359, 0x0348, 0x834D, 0x8347, 0x0342,
+        0x03C0, 0x83C5, 0x83CF, 0x03CA, 0x83DB, 0x03DE, 0x03D4, 0x83D1,
+        0x83F3, 0x03F6, 0x03FC, 0x83F9, 0x03E8, 0x83ED, 0x83E7, 0x03E2,
+        0x83A3, 0x03A6, 0x03AC, 0x83A9, 0x03B8, 0x83BD, 0x83B7, 0x03B2,
+        0x0390, 0x8395, 0x839F, 0x039A, 0x838B, 0x038E, 0x0384, 0x8381,
+        0x0280, 0x8285, 0x828F, 0x028A, 0x829B, 0x029E, 0x0294, 0x8291,
+        0x82B3, 0x02B6, 0x02BC, 0x82B9, 0x02A8, 0x82AD, 0x82A7, 0x02A2,
+        0x82E3, 0x02E6, 0x02EC, 0x82E9, 0x02F8, 0x82FD, 0x82F7, 0x02F2,
+        0x02D0, 0x82D5, 0x82DF, 0x02DA, 0x82CB, 0x02CE, 0x02C4, 0x82C1,
+        0x8243, 0x0246, 0x024C, 0x8249, 0x0258, 0x825D, 0x8257, 0x0252,
+        0x0270, 0x8275, 0x827F, 0x027A, 0x826B, 0x026E, 0x0264, 0x8261,
+        0x0220, 0x8225, 0x822F, 0x022A, 0x823B, 0x023E, 0x0234, 0x8231,
+        0x8213, 0x0216, 0x021C, 0x8219, 0x0208, 0x820D, 0x8207, 0x0202
+    ]
+
+    for byte in data:
+        i = ((crc_accum >> 8) ^ byte) & 0xFF
+        crc_accum = ((crc_accum << 8) ^ crc_table[i]) & 0xFFFF
+
+    return crc_accum
+
+
+def build_packet(motor_id: int, instruction: int, params: List[int]) -> bytes:
+    """Build a Dynamixel Protocol 2.0 packet."""
+    # Header
+    packet = bytearray([0xFF, 0xFF, 0xFD, 0x00])
+
+    # ID
+    packet.append(motor_id)
+
+    # Length (instruction + params + CRC)
+    length = len(params) + 3
+    packet.append(length & 0xFF)
+    packet.append((length >> 8) & 0xFF)
+
+    # Instruction
+    packet.append(instruction)
+
+    # Parameters
+    packet.extend(params)
+
+    # CRC
+    crc = crc16_update(0, bytes(packet))
+    packet.append(crc & 0xFF)
+    packet.append((crc >> 8) & 0xFF)
+
+    return bytes(packet)
+
+
+def ping_packet(motor_id: int) -> bytes:
+    """Create a ping packet."""
+    return build_packet(motor_id, 0x01, [])
+
+
+def torque_enable_packet(motor_id: int, enable: bool) -> bytes:
+    """Create a torque enable/disable packet."""
+    # Write instruction: Address (2 bytes) + Data
+    # Address 64 (Torque Enable), 1 byte data
+    return build_packet(motor_id, 0x03, [64, 0, 1 if enable else 0])
+
+
+def goal_position_packet(motor_id: int, position: int) -> bytes:
+    """Create a goal position packet."""
+    # Write instruction: Address (2 bytes) + Data (4 bytes)
+    # Address 116 (Goal Position)
+    return build_packet(motor_id, 0x03, [
+        116, 0,  # Address (low byte, high byte)
+        position & 0xFF,
+        (position >> 8) & 0xFF,
+        (position >> 16) & 0xFF,
+        (position >> 24) & 0xFF
+    ])
+
+
+def parse_status_packet(data: bytes) -> Tuple[bool, str]:
+    """Parse a status packet and return (success, message)."""
+    if len(data) < 11:
+        return False, f"Packet too short: {len(data)} bytes"
+
+    # Check header
+    if data[0] != 0xFF or data[1] != 0xFF or data[2] != 0xFD or data[3] != 0x00:
+        return False, "Invalid header"
+
+    motor_id = data[4]
+    length = data[5] | (data[6] << 8)
+    instruction = data[7]
+    error = data[8]
+
+    if error != 0:
+        return False, f"Motor error: {error:#04x}"
+
+    return True, f"OK (ID: {motor_id})"

engine.py

@@ -0,0 +1,364 @@
+"""Visual Novel Engine - Core classes and builder for creating interactive stories."""
+
+from __future__ import annotations
+
+import copy
+import os
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+DEFAULT_BACKGROUND = "https://images.unsplash.com/photo-1506744038136-46273834b3fb?auto=format&fit=crop&w=1200&q=80"
+POSITION_OFFSETS = {
+    "left": "20%",
+    "center": "50%",
+    "right": "80%",
+}
+
+
+# Asset helper functions
+def background_asset(filename: str) -> str:
+    """Get the URL to a background image in the assets directory."""
+    return os.path.join("user-assets", "backgrounds", filename)
+
+
+def sprite_asset(filename: str) -> str:
+    """Get the URL to a sprite image in the assets directory."""
+    return os.path.join("user-assets", "sprites", filename)
+
+
+def audio_asset(filename: str) -> str:
+    """Get the URL to an audio file in the assets directory."""
+    return os.path.join("user-assets", "audio", filename)
+
+
+def create_sprite_data_url(bg_color: str = "#fef3c7", border_color: str = "#ea580c") -> str:
+    """Create a simple inline SVG data-URI for a character sprite."""
+    svg = f"""<svg xmlns="http://www.w3.org/2000/svg" width="200" height="400" viewBox="0 0 200 400">
+      <rect width="200" height="400" fill="{bg_color}" rx="20"/>
+      <circle cx="100" cy="120" r="50" fill="{border_color}" opacity="0.6"/>
+      <rect x="60" y="180" width="80" height="140" fill="{border_color}" opacity="0.4" rx="10"/>
+    </svg>"""
+    encoded = svg.replace('"', '%22').replace('#', '%23').replace('<', '%3C').replace('>', '%3E')
+    return f"data:image/svg+xml,{encoded}"
+
+
+@dataclass
+class CharacterDefinition:
+    name: str
+    image_url: str
+    animated: bool = False
+
+
+@dataclass
+class CharacterSprite:
+    name: str
+    image_url: str
+    position: str = "center"
+    visible: bool = False
+    animation: str = ""  # Animation type: "", "idle", "shake", "bounce", "pulse"
+    scale: float = 1.0  # Scale multiplier (1.0 = 100%, 0.5 = 50%, 2.0 = 200%)
+
+
+@dataclass
+class Choice:
+    text: str
+    next_scene_index: int
+
+
+@dataclass
+class InputRequest:
+    prompt: str
+    variable_name: str
+
+
+@dataclass
+class MotorCommand:
+    motor_id: int
+    position: int  # Position in degrees (0-360)
+
+
+@dataclass
+class RobotPose:
+    """Robot pose command for Reachy Mini control."""
+    head_x: float = 0.0  # meters
+    head_y: float = 0.0  # meters
+    head_z: float = 0.0  # meters
+    head_roll: float = 0.0  # radians
+    head_pitch: float = 0.0  # radians
+    head_yaw: float = 0.0  # radians
+    body_yaw: float = 0.0  # radians
+    antenna_left: float = 0.0  # radians
+    antenna_right: float = 0.0  # radians
+
+
+@dataclass
+class SceneState:
+    background_url: str
+    background_label: str
+    characters: Dict[str, CharacterSprite]
+    speaker: str
+    text: str
+    note: str
+    show_camera: bool = False
+    show_voice: bool = False
+    show_motors: bool = False
+    show_robot: bool = False  # Show robot control widget
+    background_blur: int = 0  # Blur amount in pixels (0 = no blur, 5-10 = good range)
+    stage_url: str = ""  # Stage image on top of background, below characters
+    stage_blur: int = 0  # Blur amount for stage layer
+    choices: Optional[List[Choice]] = None
+    input_request: Optional[InputRequest] = None
+    path: Optional[str] = None  # Which story branch this scene belongs to
+    motor_commands: List[MotorCommand] = field(default_factory=list)  # Commands to execute on scene entry
+    audio_file: Optional[str] = None  # Audio file to play when scene is displayed
+    robot_pose: Optional[RobotPose] = None  # Robot pose to send when scene is displayed
+
+
+class VisualNovelBuilder:
+    """Builder to construct a linear or branching visual novel scene-by-scene."""
+
+    def __init__(self) -> None:
+        self._states: List[SceneState] = []
+        self._character_defs: Dict[str, CharacterDefinition] = {}
+        self._current_background: str = DEFAULT_BACKGROUND
+        self._current_label: str = ""
+        self._current_sprites: Dict[str, CharacterSprite] = {}
+        self._current_show_camera: bool = False
+        self._current_show_voice: bool = False
+        self._current_show_motors: bool = False
+        self._current_show_robot: bool = False
+        self._current_background_blur: int = 0
+        self._current_stage: str = ""
+        self._current_stage_blur: int = 0
+        self._current_path: Optional[str] = None
+
+    def set_characters(self, characters: List[CharacterDefinition]) -> None:
+        """Register character definitions (name, image_url, animated)."""
+        for char in characters:
+            self._character_defs[char.name] = char
+            self._current_sprites[char.name] = CharacterSprite(
+                name=char.name,
+                image_url=char.image_url,
+                position="center",
+                visible=False,
+                animation="idle" if char.animated else "",
+            )
+
+    def set_background(self, image_url: str, label: str = "") -> None:
+        """Change the background image and optionally set a label."""
+        state = self._clone_state()
+        state.background_url = image_url
+        state.background_label = label
+        state.note = f"Background: {label or 'custom'}"
+        self._push_state(state)
+
+    def set_camera(self, show: bool) -> None:
+        """Toggle the camera display for the next scene."""
+        self._current_show_camera = show
+
+    def set_voice(self, show: bool) -> None:
+        """Toggle the voice capture UI for the next scene."""
+        self._current_show_voice = show
+
+    def set_motors(self, show: bool) -> None:
+        """Toggle the motor control UI for the next scene."""
+        self._current_show_motors = show
+
+    def set_robot(self, show: bool) -> None:
+        """Toggle the robot control UI for the next scene."""
+        self._current_show_robot = show
+
+    def set_background_blur(self, blur_amount: int) -> None:
+        """Set the background blur amount in pixels (0 = no blur, 5-10 is typical range)."""
+        self._current_background_blur = blur_amount
+
+    def set_stage(self, image_url: str) -> None:
+        """Set the stage image (layer between background and characters)."""
+        self._current_stage = image_url
+
+    def set_stage_blur(self, blur_amount: int) -> None:
+        """Set the stage blur amount in pixels (0 = no blur, 5-10 is typical range)."""
+        self._current_stage_blur = blur_amount
+
+    def set_path(self, path: Optional[str]) -> None:
+        """Set the story path for subsequent scenes."""
+        self._current_path = path
+
+    def show_character(self, name: str, position: str = "center") -> None:
+        """Display a character at a specific position."""
+        state = self._clone_state()
+        if name in state.characters:
+            state.characters[name].visible = True
+            state.characters[name].position = position
+        state.note = f"Show {name} at {position}"
+        self._push_state(state)
+
+    def hide_character(self, name: str) -> None:
+        """Hide a character from the scene."""
+        state = self._clone_state()
+        if name in state.characters:
+            state.characters[name].visible = False
+        state.note = f"Hide {name}"
+        self._push_state(state)
+
+    def move_character(self, name: str, position: str) -> None:
+        """Move a character to a new position."""
+        state = self._clone_state()
+        if name in state.characters:
+            state.characters[name].position = position
+        state.note = f"Move {name} to {position}"
+        self._push_state(state)
+
+    def change_character_sprite(self, name: str, image_url: str) -> None:
+        """Change a character's sprite image (e.g., for different emotions)."""
+        state = self._clone_state()
+        if name in state.characters:
+            state.characters[name].image_url = image_url
+        state.note = f"Change {name} sprite"
+        self._push_state(state)
+
+    def set_character_animation(self, name: str, animation: str) -> None:
+        """Set character animation. Options: '', 'idle', 'shake', 'bounce', 'pulse'."""
+        state = self._clone_state()
+        if name in state.characters:
+            state.characters[name].animation = animation
+        state.note = f"{name} animation: {animation or 'none'}"
+        self._push_state(state)
+
+    def set_character_scale(self, name: str, scale: float) -> None:
+        """Set character scale. 1.0 = 100%, 0.5 = 50%, 2.0 = 200%."""
+        state = self._clone_state()
+        if name in state.characters:
+            state.characters[name].scale = scale
+        state.note = f"{name} scale: {scale}"
+        self._push_state(state)
+
+    def dialogue(self, speaker: str, text: str) -> None:
+        """Add a dialogue line."""
+        state = self._clone_state()
+        state.speaker = speaker
+        state.text = text
+        state.note = f"{speaker}: {text[:30]}..."
+        self._push_state(state)
+
+    def narration(self, text: str) -> None:
+        """Add narration (no speaker)."""
+        state = self._clone_state()
+        state.speaker = ""
+        state.text = text
+        state.note = f"Narration: {text[:30]}..."
+        self._push_state(state)
+
+    def request_input(self, prompt: str, variable_name: str) -> None:
+        """Request text input from the user."""
+        state = self._clone_state()
+        state.input_request = InputRequest(prompt=prompt, variable_name=variable_name)
+        state.note = f"Input: {variable_name}"
+        self._push_state(state)
+
+    def send_motor_command(self, motor_id: int, position: int) -> None:
+        """Send a motor command when this scene is displayed."""
+        state = self._clone_state()
+        state.motor_commands.append(MotorCommand(motor_id=motor_id, position=position))
+        state.note = f"Motor {motor_id} → {position}°"
+        self._push_state(state)
+
+    def send_motor_commands(self, commands: List[tuple[int, int]]) -> None:
+        """Send multiple motor commands when this scene is displayed.
+
+        Args:
+            commands: List of (motor_id, position) tuples
+        """
+        state = self._clone_state()
+        for motor_id, position in commands:
+            state.motor_commands.append(MotorCommand(motor_id=motor_id, position=position))
+        state.note = f"Motors: {len(commands)} commands"
+        self._push_state(state)
+
+    def send_robot_pose(
+        self,
+        head_x: float = 0.0,
+        head_y: float = 0.0,
+        head_z: float = 0.0,
+        head_roll: float = 0.0,
+        head_pitch: float = 0.0,
+        head_yaw: float = 0.0,
+        body_yaw: float = 0.0,
+        antenna_left: float = 0.0,
+        antenna_right: float = 0.0,
+    ) -> None:
+        """Send a robot pose command when this scene is displayed.
+
+        Args:
+            head_x: X position in meters
+            head_y: Y position in meters
+            head_z: Z position in meters
+            head_roll: Roll angle in radians
+            head_pitch: Pitch angle in radians
+            head_yaw: Yaw angle in radians
+            body_yaw: Body yaw angle in radians
+            antenna_left: Left antenna angle in radians
+            antenna_right: Right antenna angle in radians
+        """
+        state = self._clone_state()
+        state.robot_pose = RobotPose(
+            head_x=head_x,
+            head_y=head_y,
+            head_z=head_z,
+            head_roll=head_roll,
+            head_pitch=head_pitch,
+            head_yaw=head_yaw,
+            body_yaw=body_yaw,
+            antenna_left=antenna_left,
+            antenna_right=antenna_right,
+        )
+        state.note = "Robot pose command"
+        self._push_state(state)
+
+    def play_sound(self, audio_file: str) -> None:
+        """Play an audio file when this scene is displayed.
+
+        Args:
+            audio_file: Path to audio file (relative to assets/audio/ or absolute path)
+        """
+        state = self._clone_state()
+        state.audio_file = audio_file
+        state.note = f"Audio: {audio_file}"
+        self._push_state(state)
+
+    def add_choice(self, text: str, next_scene_index: int) -> None:
+        """Add a choice to the current scene (for branching)."""
+        if self._states:
+            if self._states[-1].choices is None:
+                self._states[-1].choices = []
+            self._states[-1].choices.append(Choice(text=text, next_scene_index=next_scene_index))
+
+    def _clone_state(self) -> SceneState:
+        """Clone the current state for the next scene."""
+        return SceneState(
+            background_url=self._current_background,
+            background_label=self._current_label,
+            characters=copy.deepcopy(self._current_sprites),
+            speaker="",
+            text="",
+            note="",
+            show_camera=self._current_show_camera,
+            show_voice=self._current_show_voice,
+            show_motors=self._current_show_motors,
+            show_robot=self._current_show_robot,
+            background_blur=self._current_background_blur,
+            stage_url=self._current_stage,
+            stage_blur=self._current_stage_blur,
+            path=self._current_path,
+        )
+
+    def _push_state(self, state: SceneState) -> None:
+        """Push a new state and update internal tracking."""
+        self._states.append(state)
+        self._current_background = state.background_url
+        self._current_label = state.background_label
+        self._current_sprites = copy.deepcopy(state.characters)
+
+    def build(self) -> List[SceneState]:
+        """Return the finalized list of scene states."""
+        return self._states

main.py

@@ -0,0 +1,1448 @@
+"""Visual Novel Gradio App - Main application with UI and handlers."""
+
+from __future__ import annotations
+
+import os
+import urllib.parse
+import numpy as np
+from typing import Optional
+
+import gradio as gr
+from fastrtc import WebRTC
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from engine import SceneState, POSITION_OFFSETS, Choice, InputRequest
+from story import build_sample_story
+
+
+def passthrough_stream(frame):
+    """Return the incoming frame untouched so the user sees their feed."""
+    return frame
+
+
+def camera_hint_text(show_camera: bool) -> str:
+    if show_camera:
+        return "🎥 Webcam overlay is active for this scene."
+    return "🕹️ Webcam is hidden for this scene."
+
+
+def voice_hint_text(show_voice: bool) -> str:
+    if show_voice:
+        return "🎤 Voice capture is available in this scene."
+    return "🔇 Voice capture is hidden for this scene."
+
+
+def motor_hint_text(show_motors: bool) -> str:
+    if show_motors:
+        return "🤖 Motor control is available in this scene."
+    return "🛑 Motor control hidden for this scene."
+
+
+def robot_hint_text(show_robot: bool) -> str:
+    if show_robot:
+        return "🤖 Robot control is available in this scene."
+    return "🔒 Robot control hidden for this scene."
+
+
+# Dynamixel control functions using Python protocol implementation
+def dxl_build_ping_packet(motor_id: int) -> list[int]:
+    """Build a ping packet and return as list of bytes."""
+    import dynamixel
+    packet = dynamixel.ping_packet(motor_id)
+    return list(packet)
+
+
+def dxl_build_torque_packet(motor_id: int, enable: bool) -> list[int]:
+    """Build a torque enable/disable packet and return as list of bytes."""
+    import dynamixel
+    packet = dynamixel.torque_enable_packet(motor_id, enable)
+    return list(packet)
+
+
+def dxl_build_goal_position_packet(motor_id: int, degrees: float) -> list[int]:
+    """Build a goal position packet and return as list of bytes."""
+    import dynamixel
+    # Convert degrees to ticks (0-360° -> 0-4095)
+    clamped_deg = max(0.0, min(360.0, degrees))
+    ticks = int((clamped_deg / 360.0) * 4095)
+    packet = dynamixel.goal_position_packet(motor_id, ticks)
+    return list(packet)
+
+
+def dxl_parse_response(response_bytes: list[int]) -> str:
+    """Parse a status packet response and return human-readable result."""
+    import dynamixel
+    if not response_bytes:
+        return "❌ No response received"
+    success, message = dynamixel.parse_status_packet(bytes(response_bytes))
+    if success:
+        return f"✅ {message}"
+    else:
+        return f"❌ {message}"
+
+
+def get_scene_motor_packets(story_state: dict) -> list:
+    """Extract motor commands from current scene and build packets."""
+    scenes = story_state["scenes"]
+    current_index = story_state["index"]
+    if 0 <= current_index < len(scenes):
+        scene = scenes[current_index]
+        # Build packet for each motor command
+        packets = []
+        for cmd in scene.motor_commands:
+            packet = dxl_build_goal_position_packet(cmd.motor_id, cmd.position)
+            packets.append(packet)
+        return packets
+    return []
+
+
+def get_scene_audio(story_state: dict) -> Optional[str]:
+    """Extract audio file from current scene."""
+    scenes = story_state["scenes"]
+    current_index = story_state["index"]
+    if 0 <= current_index < len(scenes):
+        scene = scenes[current_index]
+        return scene.audio_file
+    return None
+
+
+def get_scene_robot_pose(story_state: dict) -> Optional[dict]:
+    """Extract robot pose from current scene."""
+    scenes = story_state["scenes"]
+    current_index = story_state["index"]
+    if 0 <= current_index < len(scenes):
+        scene = scenes[current_index]
+        if scene.robot_pose:
+            return {
+                "target_head_pose": {
+                    "x": scene.robot_pose.head_x,
+                    "y": scene.robot_pose.head_y,
+                    "z": scene.robot_pose.head_z,
+                    "roll": scene.robot_pose.head_roll,
+                    "pitch": scene.robot_pose.head_pitch,
+                    "yaw": scene.robot_pose.head_yaw,
+                },
+                "target_body_yaw": scene.robot_pose.body_yaw,
+                "target_antennas": [scene.robot_pose.antenna_left, scene.robot_pose.antenna_right],
+            }
+    return None
+
+
+def synthesize_tone(sample_rate: int = 16000, duration: float = 1.25) -> tuple[int, np.ndarray]:
+    """Generate a short confirmation tone to play back as the AI voice."""
+    samples = np.linspace(0, duration, int(sample_rate * duration), endpoint=False)
+    carrier = np.sin(2 * np.pi * 520 * samples) + 0.4 * np.sin(2 * np.pi * 880 * samples)
+    fade_len = int(sample_rate * 0.08)
+    envelope = np.ones_like(carrier)
+    envelope[:fade_len] *= np.linspace(0.0, 1.0, fade_len)
+    envelope[-fade_len:] *= np.linspace(1.0, 0.0, fade_len)
+    tone = 0.18 * carrier * envelope
+    return sample_rate, tone.astype(np.float32)
+
+
+def describe_audio_clip(audio: Optional[tuple[int, np.ndarray]]) -> str:
+    if audio is None:
+        return "No audio captured yet. Hit record to speak with the companion."
+    sample_rate, samples = audio
+    num_samples = len(samples) if samples is not None else 0
+    if num_samples == 0:
+        return "Audio appears empty. Please re-record."
+    duration = num_samples / float(sample_rate or 1)
+    rms = float(np.sqrt(np.mean(np.square(samples))))
+    return f"Captured {duration:.2f}s of audio (RMS ~{rms:.3f}). Ready for the AI."
+
+
+def process_voice_interaction(
+    audio: Optional[tuple[int, np.ndarray]], prompt: str
+) -> tuple[str, Optional[tuple[int, np.ndarray]], str, tuple[int, np.ndarray]]:
+    summary = describe_audio_clip(audio)
+    user_prompt = (prompt or "React to the current scene.").strip()
+    if audio is None:
+        ai_line = (
+            "AI response pending: record or upload an audio clip so the agent can react."
+        )
+        response_audio = synthesize_tone()
+        return summary, None, ai_line, response_audio
+    ai_line = (
+        "Imaginary AI companion: I'm using your latest microphone input "
+        f"and the prompt \"{user_prompt}\" to craft a response."
+    )
+    response_audio = synthesize_tone()
+    return summary, audio, ai_line, response_audio
+
+
+def render_scene(
+    scene: SceneState, index: int, total: int, variables: dict
+) -> tuple[str, str, str, bool, bool, bool, bool, Optional[List[Choice]], Optional[InputRequest]]:
+    """Generate the HTML stage, dialogue text, and metadata."""
+    char_layers = []
+    for sprite in scene.characters.values():
+        if not sprite.visible:
+            continue
+        offset = POSITION_OFFSETS.get(sprite.position, "50%")
+        # Build class names with animation
+        class_names = "character"
+        if sprite.animation:
+            class_names += f" anim-{sprite.animation}"
+        # Apply scale using CSS variable (so animations can use it)
+        char_layers.append(
+            f"""
+            <div class="{class_names}" style="
+                left:{offset};
+                background-image:url('{sprite.image_url}');
+                --char-scale:{sprite.scale};
+            " title="{sprite.name}"></div>
+            """
+        )
+    dialogue_markdown = (
+        "" if scene.text else ""
+    )  # Avoid duplicating the speech bubble content below the stage.
+    metadata = f"{scene.background_label or 'Scene'} · {index + 1} / {total}"
+    bubble_html = ""
+    text_content = (scene.text or "").strip()
+
+    # Substitute variables in text (e.g., {player_name})
+    for var_name, var_value in variables.items():
+        text_content = text_content.replace(f"{{{var_name}}}", str(var_value))
+
+    if text_content:
+        speaker_html = (
+            f'<div class="bubble-speaker">{scene.speaker}</div>'
+            if scene.speaker
+            else ""
+        )
+        bubble_html = f"""
+            <div class="speech-bubble">
+                {speaker_html}
+                <div class="bubble-text">{text_content}</div>
+            </div>
+        """
+    # Apply blur filters to background and stage
+    bg_blur_style = f"filter: blur({scene.background_blur}px);" if scene.background_blur > 0 else ""
+    stage_blur_style = f"filter: blur({scene.stage_blur}px);" if scene.stage_blur > 0 else ""
+
+    # Build stage layer HTML if stage image is set
+    stage_layer_html = ""
+    if scene.stage_url:
+        stage_layer_html = f'<div class="stage-layer" style="background-image:url(\'{scene.stage_url}\'); {stage_blur_style}"></div>'
+
+    stage_html = f"""
+        <div class="stage">
+            <div class="stage-background" style="background-image:url('{scene.background_url}'); {bg_blur_style}"></div>
+            {stage_layer_html}
+            {''.join(char_layers)}
+            {bubble_html}
+        </div>
+    """
+    return (
+        stage_html,
+        dialogue_markdown,
+        metadata,
+        scene.show_camera,
+        scene.show_voice,
+        scene.show_motors,
+        scene.show_robot,
+        scene.choices,
+        scene.input_request,
+    )
+
+
+def is_scene_accessible(scene: SceneState, active_paths: set) -> bool:
+    """Check if a scene is accessible given the active story paths."""
+    # Scenes with no path are always accessible (main path)
+    if scene.path is None:
+        return True
+    # Scenes with a specific path are only accessible if that path is active
+    return scene.path in active_paths
+
+
+def change_scene(
+    story_state: dict, direction: int
+) -> tuple[dict, str, str, str, str, dict, str, dict, str, dict, str, dict, dict, str, dict, dict, dict, dict]:
+    scenes: List[SceneState] = story_state["scenes"]
+    variables = story_state.get("variables", {})
+    active_paths = story_state.get("active_paths", set())
+
+    if not scenes:
+        return (
+            story_state,
+            "",
+            "No scenes available.",
+            "",
+            camera_hint_text(False),
+            gr.update(visible=False),
+            voice_hint_text(False),
+            gr.update(visible=False),
+            motor_hint_text(False),
+            gr.update(visible=False),
+            robot_hint_text(False),
+            gr.update(visible=False),
+            gr.update(visible=False, choices=[]),
+            gr.update(visible=False),
+            gr.update(interactive=True),
+            gr.update(interactive=True),
+            gr.update(visible=False),  # right_column
+        )
+
+    total = len(scenes)
+    current_index = story_state["index"]
+
+    # Find the next accessible scene in the given direction
+    new_index = current_index
+    search_index = current_index + direction
+
+    while 0 <= search_index < total:
+        if is_scene_accessible(scenes[search_index], active_paths):
+            new_index = search_index
+            break
+        search_index += direction
+
+    story_state["index"] = new_index
+    html, dialogue, meta, show_camera, show_voice, show_motors, show_robot, choices, input_req = render_scene(
+        scenes[story_state["index"]], story_state["index"], total, variables
+    )
+
+    # Disable navigation when choices or input are present
+    nav_enabled = not bool(choices) and not bool(input_req)
+
+    # Show right column if any feature is active
+    right_column_visible = show_camera or show_voice or show_motors or show_robot
+
+    return (
+        story_state,
+        html,
+        dialogue,
+        meta,
+        camera_hint_text(show_camera),
+        gr.update(visible=show_camera),
+        voice_hint_text(show_voice),
+        gr.update(visible=show_voice),
+        motor_hint_text(show_motors),
+        gr.update(visible=show_motors),
+        robot_hint_text(show_robot),
+        gr.update(visible=show_robot),
+        gr.update(visible=bool(choices), choices=[(c.text, i) for i, c in enumerate(choices)] if choices else [], value=None),
+        f"### {input_req.prompt}" if input_req else "",
+        gr.update(visible=bool(input_req)),
+        gr.update(interactive=nav_enabled),
+        gr.update(interactive=nav_enabled),
+        gr.update(visible=right_column_visible),  # right_column
+    )
+
+
+def handle_choice(story_state: dict, choice_index: int) -> tuple[dict, str, str, str, str, dict, str, dict, str, dict, str, dict, dict, str, dict, dict, dict, dict]:
+    """Navigate to the scene selected by the choice."""
+    scenes: List[SceneState] = story_state["scenes"]
+    variables = story_state.get("variables", {})
+    active_paths = story_state.get("active_paths", set())
+    current_scene = scenes[story_state["index"]]
+
+    if current_scene.choices and 0 <= choice_index < len(current_scene.choices):
+        chosen = current_scene.choices[choice_index]
+        story_state["index"] = chosen.next_scene_index
+
+        # Activate the path of the chosen scene
+        target_scene = scenes[chosen.next_scene_index]
+        if target_scene.path:
+            active_paths = set(active_paths)  # Copy the set
+            active_paths.add(target_scene.path)
+            story_state["active_paths"] = active_paths
+
+        html, dialogue, meta, show_camera, show_voice, show_motors, show_robot, choices, input_req = render_scene(
+            scenes[story_state["index"]], story_state["index"], len(scenes), variables
+        )
+
+        nav_enabled = not bool(choices) and not bool(input_req)
+        right_column_visible = show_camera or show_voice or show_motors or show_robot
+
+        return (
+            story_state,
+            html,
+            dialogue,
+            meta,
+            camera_hint_text(show_camera),
+            gr.update(visible=show_camera),
+            voice_hint_text(show_voice),
+            gr.update(visible=show_voice),
+            motor_hint_text(show_motors),
+            gr.update(visible=show_motors),
+            robot_hint_text(show_robot),
+            gr.update(visible=show_robot),
+            gr.update(visible=bool(choices), choices=[(c.text, i) for i, c in enumerate(choices)] if choices else [], value=None),
+            f"### {input_req.prompt}" if input_req else "",
+            gr.update(visible=bool(input_req)),
+            gr.update(interactive=nav_enabled),
+            gr.update(interactive=nav_enabled),
+            gr.update(visible=right_column_visible),  # right_column
+        )
+    return change_scene(story_state, 0)
+
+
+def handle_input(story_state: dict, user_input: str) -> tuple[dict, str, str, str, str, dict, str, dict, str, dict, str, dict, dict, str, dict, dict, dict, dict]:
+    """Store user input and advance to next scene."""
+    scenes: List[SceneState] = story_state["scenes"]
+    variables = story_state.get("variables", {})
+    current_scene = scenes[story_state["index"]]
+
+    if current_scene.input_request and user_input:
+        variables[current_scene.input_request.variable_name] = user_input
+        story_state["variables"] = variables
+
+    # Advance to next scene
+    story_state["index"] = min(story_state["index"] + 1, len(scenes) - 1)
+
+    html, dialogue, meta, show_camera, show_voice, show_motors, show_robot, choices, input_req = render_scene(
+        scenes[story_state["index"]], story_state["index"], len(scenes), variables
+    )
+
+    nav_enabled = not bool(choices) and not bool(input_req)
+    right_column_visible = show_camera or show_voice or show_motors or show_robot
+
+    return (
+        story_state,
+        html,
+        dialogue,
+        meta,
+        camera_hint_text(show_camera),
+        gr.update(visible=show_camera),
+        voice_hint_text(show_voice),
+        gr.update(visible=show_voice),
+        motor_hint_text(show_motors),
+        gr.update(visible=show_motors),
+        robot_hint_text(show_robot),
+        gr.update(visible=show_robot),
+        gr.update(visible=bool(choices), choices=[(c.text, i) for i, c in enumerate(choices)] if choices else [], value=None),
+        f"### {input_req.prompt}" if input_req else "",
+        gr.update(visible=bool(input_req)),
+        gr.update(interactive=nav_enabled),
+        gr.update(interactive=nav_enabled),
+        gr.update(visible=right_column_visible),  # right_column
+    )
+
+
+def load_initial_state() -> tuple[dict, str, str, str, str, dict, str, dict, str, dict, str, dict, dict, str, dict, dict, dict, dict]:
+    scenes = build_sample_story()
+    story_state = {"scenes": scenes, "index": 0, "variables": {}, "active_paths": set()}
+    if scenes:
+        html, dialogue, meta, show_camera, show_voice, show_motors, show_robot, choices, input_req = render_scene(
+            scenes[0], 0, len(scenes), {}
+        )
+    else:
+        html, dialogue, meta, show_camera, show_voice, show_motors, show_robot, choices, input_req = (
+            "",
+            "No scenes available.",
+            "",
+            False,
+            False,
+            False,
+            False,
+            None,
+            None,
+        )
+
+    nav_enabled = not bool(choices) and not bool(input_req)
+    right_column_visible = show_camera or show_voice or show_motors or show_robot
+
+    return (
+        story_state,
+        html,
+        dialogue,
+        meta,
+        camera_hint_text(show_camera),
+        gr.update(visible=show_camera),
+        voice_hint_text(show_voice),
+        gr.update(visible=show_voice),
+        motor_hint_text(show_motors),
+        gr.update(visible=show_motors),
+        robot_hint_text(show_robot),
+        gr.update(visible=show_robot),
+        gr.update(visible=bool(choices), choices=[(c.text, i) for i, c in enumerate(choices)] if choices else [], value=None),
+        f"### {input_req.prompt}" if input_req else "",
+        gr.update(visible=bool(input_req)),
+        gr.update(interactive=nav_enabled),
+        gr.update(interactive=nav_enabled),
+        gr.update(visible=right_column_visible),  # right_column
+    )
+
+
+CUSTOM_CSS = """
+/* Override Gradio's height constraints for stage container */
+#stage-container {
+    height: auto !important;
+    max-height: none !important;
+}
+#stage-container > div {
+    height: auto !important;
+}
+.stage {
+    width: 100%;
+    height: 80vh;
+    min-height: 600px;
+    border-radius: 0;
+    position: relative;
+    overflow: hidden;
+    box-shadow: 0 12px 32px rgba(15,23,42,0.45);
+    display: flex;
+    align-items: flex-end;
+    justify-content: center;
+}
+/* Ensure background layers fill the stage */
+.stage-background,
+.stage-layer {
+    max-height: none !important;
+}
+.stage-background {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background-size: contain;
+    background-position: center;
+    background-repeat: no-repeat;
+    z-index: 0;
+}
+.stage-layer {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background-size: contain;
+    background-position: center;
+    background-repeat: no-repeat;
+    z-index: 5;
+}
+.character {
+    position: absolute;
+    bottom: 0;
+    width: 200px;
+    height: 380px;
+    background-size: contain;
+    background-repeat: no-repeat;
+    --char-scale: 1.0;
+    transform: translateX(-50%) scale(var(--char-scale));
+    transition: transform 0.4s ease;
+    z-index: 10;
+}
+/* Character animations */
+.character.anim-idle {
+    animation: anim-idle 4s ease-in-out infinite;
+}
+.character.anim-shake {
+    animation: anim-shake 0.5s ease-in-out;
+}
+.character.anim-bounce {
+    animation: anim-bounce 0.6s ease-in-out;
+}
+.character.anim-pulse {
+    animation: anim-pulse 1s ease-in-out infinite;
+}
+.speech-bubble {
+    position: absolute;
+    bottom: 18px;
+    left: 50%;
+    transform: translateX(-50%);
+    min-width: 60%;
+    max-width: 90%;
+    padding: 20px 24px;
+    border-radius: 20px;
+    background: rgba(15,23,42,0.88);
+    color: #f8fafc;
+    font-family: "Atkinson Hyperlegible", system-ui, sans-serif;
+    box-shadow: 0 10px 28px rgba(0,0,0,0.35);
+    z-index: 20;
+}
+.speech-bubble::after {
+    content: "";
+    position: absolute;
+    bottom: -16px;
+    left: 50%;
+    transform: translateX(-50%);
+    border-width: 16px 12px 0 12px;
+    border-style: solid;
+    border-color: rgba(15,23,42,0.88) transparent transparent transparent;
+}
+.bubble-speaker {
+    font-size: 0.85rem;
+    letter-spacing: 0.08em;
+    font-weight: 700;
+    text-transform: uppercase;
+    color: #facc15;
+    margin-bottom: 6px;
+}
+.bubble-text {
+    font-size: 1.05rem;
+    line-height: 1.5;
+}
+.camera-column {
+    position: relative;
+    min-height: 360px;
+    gap: 0.75rem;
+}
+.camera-hint {
+    font-size: 0.85rem;
+    color: #cbd5f5;
+    margin-bottom: 0.4rem;
+}
+#camera-wrapper {
+    width: 100%;
+    max-width: 320px;
+}
+#camera-wrapper > div {
+    border-radius: 18px;
+    background: rgba(15,23,42,0.88);
+    padding: 6px;
+    box-shadow: 0 12px 26px rgba(15,23,42,0.55);
+}
+#camera-wrapper video {
+    border-radius: 14px;
+    object-fit: cover;
+    box-shadow: 0 10px 30px rgba(0,0,0,0.4);
+}
+.dxl-card {
+    margin-top: 0.5rem;
+    padding: 1rem 1.2rem;
+    border-radius: 14px;
+    background: rgba(15,23,42,0.85);
+    color: #e2e8f0;
+    box-shadow: 0 10px 26px rgba(0,0,0,0.45);
+}
+.dxl-card h3 {
+    margin: 0 0 0.35rem 0;
+}
+.dxl-row {
+    display: flex;
+    gap: 0.6rem;
+    align-items: center;
+    margin-bottom: 0.5rem;
+    flex-wrap: wrap;
+}
+.dxl-row label {
+    font-size: 0.9rem;
+    color: #cbd5e1;
+}
+.dxl-row input[type="number"],
+.dxl-row select,
+.dxl-row input[type="range"] {
+    flex: 1;
+    min-width: 120px;
+}
+.dxl-btn {
+    padding: 0.5rem 0.8rem;
+    border-radius: 10px;
+    border: 1px solid rgba(148,163,184,0.4);
+    background: rgba(255,255,255,0.05);
+    color: #e2e8f0;
+    cursor: pointer;
+    transition: transform 0.1s ease, background 0.15s ease;
+}
+.dxl-btn.primary {
+    background: linear-gradient(120deg, #06b6d4, #2563eb);
+    border-color: rgba(59,130,246,0.5);
+}
+.dxl-btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+.dxl-btn:not(:disabled):hover {
+    transform: translateY(-1px);
+}
+.dxl-status {
+    font-size: 0.9rem;
+    color: #a5b4fc;
+    min-height: 1.2rem;
+}
+.input-prompt {
+    font-size: 1.1rem;
+    font-weight: 600;
+    color: #1e293b;
+    margin-bottom: 0.5rem;
+}
+@keyframes anim-idle {
+    0% { transform: translate(-50%, 0px) scale(var(--char-scale)); }
+    50% { transform: translate(-50%, 12px) scale(var(--char-scale)); }
+    100% { transform: translate(-50%, 0px) scale(var(--char-scale)); }
+}
+@keyframes anim-shake {
+    0%, 100% { transform: translate(-50%, 0) rotate(0deg) scale(var(--char-scale)); }
+    10%, 30%, 50%, 70%, 90% { transform: translate(-52%, 0) rotate(-2deg) scale(var(--char-scale)); }
+    20%, 40%, 60%, 80% { transform: translate(-48%, 0) rotate(2deg) scale(var(--char-scale)); }
+}
+@keyframes anim-bounce {
+    0%, 100% { transform: translate(-50%, 0) scale(var(--char-scale)); }
+    25% { transform: translate(-50%, -30px) scale(var(--char-scale)); }
+    50% { transform: translate(-50%, 0) scale(var(--char-scale)); }
+    75% { transform: translate(-50%, -15px) scale(var(--char-scale)); }
+}
+@keyframes anim-pulse {
+    0%, 100% { transform: translate(-50%, 0) scale(var(--char-scale)); }
+    50% { transform: translate(-50%, 0) scale(calc(var(--char-scale) * 1.05)); }
+}
+"""
+
+ENUMERATE_CAMERAS_JS = """
+async (currentDevices) => {
+    if (!navigator.mediaDevices?.enumerateDevices) {
+        return currentDevices || [];
+    }
+    try {
+        const devices = await navigator.mediaDevices.enumerateDevices();
+        return devices
+            .filter((device) => device.kind === "videoinput")
+            .map((device, index) => ({
+                label: device.label || `Camera ${index + 1}`,
+                deviceId: device.deviceId || null,
+            }));
+    } catch (error) {
+        console.warn("enumerateDevices failed", error);
+        return currentDevices || [];
+    }
+}
+"""
+
+def load_dxl_script_js() -> str:
+    """Generate JavaScript to dynamically load the DXL script from static files."""
+    import time
+    timestamp = int(time.time())
+    return f"""
+() => {{
+    const script = document.createElement('script');
+    script.type = 'module';
+    script.src = '/web/dxl_webserial.js?v={timestamp}';
+    script.onerror = () => console.error("[DXL] Failed to load motor control script");
+    document.head.appendChild(script);
+}}
+"""
+
+
+def dxl_send_and_receive_js() -> str:
+    """JavaScript to send packet bytes and receive response via Web Serial."""
+    return """
+async (packet_bytes) => {
+    // Check if dxlSerial is available and connected
+    if (typeof window.dxlSerial === 'undefined' || !window.dxlSerial) {
+        console.error("[DXL] Serial not available - connect first");
+        return [];
+    }
+
+    if (!window.dxlSerial.connected) {
+        console.error("[DXL] Not connected to serial port");
+        return [];
+    }
+
+    try {
+        await window.dxlSerial.writeBytes(packet_bytes);
+        const response = await window.dxlSerial.readPacket(800);
+        return response;
+    } catch (err) {
+        console.error("[DXL] Communication error:", err.message);
+        return [];
+    }
+}
+"""
+
+
+def execute_motor_packets_js() -> str:
+    """JavaScript to execute pre-built motor packets."""
+    return """
+async (packets) => {
+    if (!packets || packets.length === 0) {
+        return;  // No packets to execute
+    }
+
+    // Check if serial is available
+    if (typeof window.dxlSerial === 'undefined' || !window.dxlSerial || !window.dxlSerial.connected) {
+        return;  // Silently skip if not connected
+    }
+
+    // Execute each packet sequentially
+    for (const pkt of packets) {
+        try {
+            await window.dxlSerial.writeBytes(pkt);
+            await window.dxlSerial.readPacket(800);
+        } catch (err) {
+            console.error(`[Motors] Error:`, err.message);
+        }
+    }
+}
+"""
+
+
+def play_scene_audio_js() -> str:
+    """JavaScript to play audio file."""
+    return """
+(audio_path) => {
+    if (!audio_path || audio_path === '') {
+        return;  // No audio to play
+    }
+
+    // Create or reuse audio element
+    let audio = document.getElementById('scene-audio-player');
+    if (!audio) {
+        audio = new Audio();
+        audio.id = 'scene-audio-player';
+    }
+
+    console.log('[Audio] Playing:', audio_path);
+    audio.src = audio_path;
+    audio.play().catch(err => console.error('[Audio] Playback failed:', err));
+}
+"""
+
+
+def load_robot_ws_script_js() -> str:
+    """JavaScript to initialize WebSocket connection to Reachy Mini robot."""
+    return """
+() => {
+    console.log('[Robot] Initializing WebSocket connection...');
+
+    // Define global initialization function if not already defined
+    if (!window.loadRobotWebSocket) {
+        window.loadRobotWebSocket = function() {
+    const hostDiv = document.getElementById('robot-ws-host');
+    if (!hostDiv) {
+        console.error('[Robot] Cannot initialize - host div not found');
+        return;
+    }
+
+    const ROBOT_URL = 'localhost:8000';
+    const WS_URL = `ws://${ROBOT_URL}/api/move/ws/set_target`;
+
+    console.log('[Robot] Connecting to:', WS_URL);
+
+    // Global robot state
+    window.reachyRobot = {
+        ws: null,
+        connected: false
+    };
+
+    // Create UI
+    hostDiv.innerHTML = `
+        <div id="robot-connection-status" style="padding: 8px; border-radius: 4px; background: #f8d7da; color: #721c24; margin-bottom: 10px;">
+            <span id="robot-status-dot" style="display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: #dc3545; margin-right: 6px;"></span>
+            <span id="robot-status-text">Disconnected - Trying to connect...</span>
+        </div>
+    `;
+
+    function updateStatus(connected) {
+        const statusDiv = document.getElementById('robot-connection-status');
+        const dot = document.getElementById('robot-status-dot');
+        const text = document.getElementById('robot-status-text');
+
+        if (connected) {
+            statusDiv.style.background = '#d4edda';
+            statusDiv.style.color = '#155724';
+            dot.style.background = '#28a745';
+            dot.style.boxShadow = '0 0 10px #28a745';
+            text.textContent = 'Connected to robot';
+        } else {
+            statusDiv.style.background = '#f8d7da';
+            statusDiv.style.color = '#721c24';
+            dot.style.background = '#dc3545';
+            dot.style.boxShadow = 'none';
+            text.textContent = 'Disconnected - Reconnecting...';
+        }
+    }
+
+    function connectWebSocket() {
+        console.log('[Robot] Connecting to WebSocket:', WS_URL);
+
+        window.reachyRobot.ws = new WebSocket(WS_URL);
+
+        window.reachyRobot.ws.onopen = () => {
+            console.log('[Robot] WebSocket connected');
+            window.reachyRobot.connected = true;
+            updateStatus(true);
+        };
+
+        window.reachyRobot.ws.onclose = () => {
+            console.log('[Robot] WebSocket disconnected');
+            window.reachyRobot.connected = false;
+            updateStatus(false);
+            // Reconnect after 2 seconds
+            setTimeout(connectWebSocket, 2000);
+        };
+
+        window.reachyRobot.ws.onerror = (error) => {
+            console.error('[Robot] WebSocket error:', error);
+        };
+
+        window.reachyRobot.ws.onmessage = (event) => {
+            try {
+                const message = JSON.parse(event.data);
+                if (message.status === 'error') {
+                    console.error('[Robot] Server error:', message.detail);
+                }
+            } catch (e) {
+                console.error('[Robot] Failed to parse message:', e);
+            }
+        };
+    }
+
+    connectWebSocket();
+        };  // End of window.loadRobotWebSocket definition
+    }
+
+    // Try to initialize (with multiple retries)
+    let retryCount = 0;
+    const maxRetries = 10;
+
+    function tryInit() {
+        const hostDiv = document.getElementById('robot-ws-host');
+        if (!hostDiv) {
+            retryCount++;
+            if (retryCount <= maxRetries) {
+                console.warn(`[Robot] Host div not found, retry ${retryCount}/${maxRetries} in 1 second`);
+                setTimeout(tryInit, 1000);
+            } else {
+                console.warn('[Robot] Gave up waiting for robot widget div. Will initialize on first use.');
+            }
+            return;
+        }
+
+        if (window.reachyRobot) {
+            console.log('[Robot] Already initialized');
+            return;
+        }
+
+        // Initialize now
+        console.log('[Robot] Found host div, initializing...');
+        window.loadRobotWebSocket();
+    }
+
+    tryInit();
+}
+"""
+
+
+def send_robot_pose_js() -> str:
+    """JavaScript to send robot pose via WebSocket."""
+    return """
+async (pose_data) => {
+    if (!pose_data) {
+        return;  // No pose to send
+    }
+
+    // Initialize WebSocket if not already done (lazy initialization)
+    if (!window.reachyRobot) {
+        console.log('[Robot] Lazy initialization on first pose send');
+        if (window.loadRobotWebSocket) {
+            window.loadRobotWebSocket();
+            // Wait a bit for connection to establish
+            await new Promise(resolve => setTimeout(resolve, 500));
+        }
+    }
+
+    if (!window.reachyRobot || !window.reachyRobot.connected || !window.reachyRobot.ws || window.reachyRobot.ws.readyState !== WebSocket.OPEN) {
+        console.warn('[Robot] WebSocket not connected, skipping pose command');
+        return;
+    }
+
+    try {
+        console.log('[Robot] Sending pose:', pose_data);
+        window.reachyRobot.ws.send(JSON.stringify(pose_data));
+    } catch (error) {
+        console.error('[Robot] Failed to send pose:', error);
+    }
+}
+"""
+
+
+
+def build_app() -> gr.Blocks:
+    with gr.Blocks(title="Gradio Visual Novel") as demo:
+        gr.HTML(f"<style>{CUSTOM_CSS}</style>", elem_id="vn-styles")
+        story_state = gr.State()
+
+        with gr.Row():
+            with gr.Column(scale=3, min_width=640):
+                stage = gr.HTML(label="Stage", elem_id="stage-container")
+                dialogue = gr.Markdown(label="Dialogue")
+                meta = gr.Markdown(label="Scene Info", elem_id="scene-info")
+
+                # Choice selection
+                choice_radio = gr.Radio(label="Make a choice", visible=False)
+
+                # Text input
+                with gr.Group(visible=False) as input_group:
+                    input_prompt = gr.Markdown("", elem_classes=["input-prompt"])
+                    with gr.Row():
+                        user_input = gr.Textbox(label="Your answer", scale=4)
+                        input_submit_btn = gr.Button("Submit", variant="primary", scale=1)
+
+                with gr.Row():
+                    prev_btn = gr.Button("⟵ Back", variant="secondary")
+                    next_btn = gr.Button("Next ⟶", variant="primary")
+            with gr.Column(scale=1, min_width=320, elem_classes=["camera-column"], visible=False) as right_column:
+                gr.Markdown("### Live Camera (WebRTC)")
+                camera_hint = gr.Markdown(
+                    camera_hint_text(False), elem_classes=["camera-hint"]
+                )
+                gr.Markdown(
+                    "Allow camera access when prompted. The webcam appears only in scenes that request it.",
+                    elem_classes=["camera-hint"],
+                )
+                with gr.Group(elem_id="camera-wrapper"):
+                    webrtc_component = WebRTC(
+                        label="Webcam Stream",
+                        mode="send-receive",
+                        modality="video",
+                        full_screen=False,
+                        visible=False,
+                    )
+                webrtc_component.stream(
+                    fn=passthrough_stream,
+                    inputs=[webrtc_component],
+                    outputs=[webrtc_component],
+                )
+                voice_hint = gr.Markdown(
+                    voice_hint_text(False), elem_classes=["camera-hint"]
+                )
+                with gr.Group(visible=False, elem_id="voice-wrapper") as voice_section:
+                    with gr.Accordion("Voice & Audio Agent", open=True):
+                        gr.Markdown(
+                            "Record a short line to pass to your AI companion. "
+                            "We play back your clip and a synthetic confirmation tone.",
+                            elem_classes=["camera-hint"],
+                        )
+                        voice_prompt = gr.Textbox(
+                            label="Prompt/context",
+                            value="React to the current scene with a friendly reply.",
+                            lines=2,
+                        )
+                        mic = gr.Audio(
+                            sources=["microphone", "upload"],
+                            type="numpy",
+                            label="Record or upload audio",
+                        )
+                        send_voice_btn = gr.Button(
+                            "Send to voice agent", variant="secondary"
+                        )
+                        voice_summary = gr.Markdown("No audio captured yet.")
+                        playback = gr.Audio(label="Your recording", interactive=False)
+                        ai_voice_text = gr.Markdown("AI response will appear here.")
+                        ai_voice_audio = gr.Audio(
+                            label="AI voice reply (synthetic tone)", interactive=False
+                        )
+                        send_voice_btn.click(
+                            fn=process_voice_interaction,
+                            inputs=[mic, voice_prompt],
+                            outputs=[
+                                voice_summary,
+                                playback,
+                                ai_voice_text,
+                                ai_voice_audio,
+                            ],
+                        )
+                motor_hint = gr.Markdown(
+                    motor_hint_text(False), elem_classes=["camera-hint"]
+                )
+                with gr.Group(visible=False, elem_id="dxl-panel-container") as motor_group:
+                    with gr.Accordion("Dynamixel XL330 Control", open=True):
+                        gr.Markdown(
+                            "**Web Serial Control** - Use Chrome/Edge desktop. Connect to serial port, then control motors.",
+                            elem_classes=["camera-hint"],
+                        )
+
+                        # Serial connection panel (still handled by JavaScript)
+                        gr.HTML('<div id="dxl-panel-host"></div>', elem_id="dxl-panel-host-wrapper")
+
+                        # Motor control inputs (Python-based)
+                        with gr.Row():
+                            motor_id_input = gr.Number(
+                                label="Motor ID",
+                                value=1,
+                                minimum=0,
+                                maximum=252,
+                                precision=0,
+                            )
+                        with gr.Row():
+                            goal_slider = gr.Slider(
+                                label="Goal Position (degrees)",
+                                minimum=0,
+                                maximum=360,
+                                value=90,
+                                step=1,
+                            )
+                        with gr.Row():
+                            ping_btn = gr.Button("Ping", size="sm")
+                            torque_on_btn = gr.Button("Torque ON", size="sm", variant="secondary")
+                            torque_off_btn = gr.Button("Torque OFF", size="sm")
+                        with gr.Row():
+                            send_goal_btn = gr.Button("Send Goal Position", variant="primary")
+                        motor_status = gr.Markdown("Status: Ready")
+
+                # Robot Control (Reachy Mini via WebSocket)
+                robot_hint = gr.Markdown(
+                    robot_hint_text(False), elem_classes=["camera-hint"]
+                )
+                with gr.Group(visible=False, elem_id="robot-panel-container") as robot_group:
+                    with gr.Accordion("Reachy Mini Robot Control", open=True):
+                        gr.Markdown(
+                            "**WebSocket Control** - Connects to localhost:8000 for real-time robot control.",
+                            elem_classes=["camera-hint"],
+                        )
+
+                        # WebSocket connection area (will be managed by JavaScript)
+                        # Status is shown dynamically by JavaScript inside this div
+                        gr.HTML('<div id="robot-ws-host"></div>', elem_id="robot-ws-host-wrapper")
+
+        # Wire up event handlers
+        all_outputs = [
+            story_state,
+            stage,
+            dialogue,
+            meta,
+            camera_hint,
+            webrtc_component,
+            voice_hint,
+            voice_section,
+            motor_hint,
+            motor_group,
+            robot_hint,
+            robot_group,
+            choice_radio,
+            input_prompt,
+            input_group,
+            prev_btn,
+            next_btn,
+            right_column,
+        ]
+
+        # Hidden JSON for passing packet bytes between Python and JavaScript
+        # Note: gr.State doesn't work well with JavaScript, so we use JSON
+        packet_bytes_json = gr.JSON(visible=False, value=[])
+        response_bytes_json = gr.JSON(visible=False, value=[])
+        motor_packets_json = gr.JSON(visible=False, value=[])  # For scene motor commands
+
+        # Hidden textbox for passing audio path to JavaScript
+        audio_path_box = gr.Textbox(visible=False, value="")
+
+        # Hidden JSON for passing robot pose to JavaScript
+        robot_pose_json = gr.JSON(visible=False, value=None)
+
+        # Load initialization scripts
+        combined_init_js = f"""
+() => {{
+    // Initialize Dynamixel
+    ({load_dxl_script_js()})();
+    // Initialize Robot WebSocket
+    ({load_robot_ws_script_js()})();
+}}
+"""
+
+        demo.load(
+            fn=load_initial_state,
+            inputs=None,
+            outputs=all_outputs,
+            js=combined_init_js,
+        )
+
+        # Navigation buttons with automatic motor command execution, audio playback, and robot control
+        # Create parallel chains for audio, motors, and robot to ensure all get the updated state
+
+        # Previous button
+        prev_event = prev_btn.click(
+            fn=lambda state: change_scene(state, -1),
+            inputs=story_state,
+            outputs=all_outputs,
+        )
+        # Audio chain
+        prev_event.then(
+            fn=get_scene_audio,
+            inputs=[story_state],
+            outputs=[audio_path_box],
+        ).then(
+            fn=None,
+            inputs=[audio_path_box],
+            outputs=[],
+            js=play_scene_audio_js(),
+        )
+        # Motor chain (parallel)
+        prev_event.then(
+            fn=get_scene_motor_packets,
+            inputs=[story_state],
+            outputs=[motor_packets_json],
+        ).then(
+            fn=None,
+            inputs=[motor_packets_json],
+            outputs=[],
+            js=execute_motor_packets_js(),
+        )
+        # Robot chain (parallel)
+        prev_event.then(
+            fn=get_scene_robot_pose,
+            inputs=[story_state],
+            outputs=[robot_pose_json],
+        ).then(
+            fn=None,
+            inputs=[robot_pose_json],
+            outputs=[],
+            js=send_robot_pose_js(),
+        )
+
+        # Next button
+        next_event = next_btn.click(
+            fn=lambda state: change_scene(state, 1),
+            inputs=story_state,
+            outputs=all_outputs,
+        )
+        # Audio chain
+        next_event.then(
+            fn=get_scene_audio,
+            inputs=[story_state],
+            outputs=[audio_path_box],
+        ).then(
+            fn=None,
+            inputs=[audio_path_box],
+            outputs=[],
+            js=play_scene_audio_js(),
+        )
+        # Motor chain (parallel)
+        next_event.then(
+            fn=get_scene_motor_packets,
+            inputs=[story_state],
+            outputs=[motor_packets_json],
+        ).then(
+            fn=None,
+            inputs=[motor_packets_json],
+            outputs=[],
+            js=execute_motor_packets_js(),
+        )
+        # Robot chain (parallel)
+        next_event.then(
+            fn=get_scene_robot_pose,
+            inputs=[story_state],
+            outputs=[robot_pose_json],
+        ).then(
+            fn=None,
+            inputs=[robot_pose_json],
+            outputs=[],
+            js=send_robot_pose_js(),
+        )
+
+        # Choice handler
+        choice_event = choice_radio.change(
+            fn=handle_choice,
+            inputs=[story_state, choice_radio],
+            outputs=all_outputs,
+        )
+        # Audio chain
+        choice_event.then(
+            fn=get_scene_audio,
+            inputs=[story_state],
+            outputs=[audio_path_box],
+        ).then(
+            fn=None,
+            inputs=[audio_path_box],
+            outputs=[],
+            js=play_scene_audio_js(),
+        )
+        # Motor chain (parallel)
+        choice_event.then(
+            fn=get_scene_motor_packets,
+            inputs=[story_state],
+            outputs=[motor_packets_json],
+        ).then(
+            fn=None,
+            inputs=[motor_packets_json],
+            outputs=[],
+            js=execute_motor_packets_js(),
+        )
+        # Robot chain (parallel)
+        choice_event.then(
+            fn=get_scene_robot_pose,
+            inputs=[story_state],
+            outputs=[robot_pose_json],
+        ).then(
+            fn=None,
+            inputs=[robot_pose_json],
+            outputs=[],
+            js=send_robot_pose_js(),
+        )
+
+        # Input submit button
+        input_submit_event = input_submit_btn.click(
+            fn=handle_input,
+            inputs=[story_state, user_input],
+            outputs=all_outputs,
+        )
+        # Audio chain
+        input_submit_event.then(
+            fn=get_scene_audio,
+            inputs=[story_state],
+            outputs=[audio_path_box],
+        ).then(
+            fn=None,
+            inputs=[audio_path_box],
+            outputs=[],
+            js=play_scene_audio_js(),
+        )
+        # Motor chain (parallel)
+        input_submit_event.then(
+            fn=get_scene_motor_packets,
+            inputs=[story_state],
+            outputs=[motor_packets_json],
+        ).then(
+            fn=None,
+            inputs=[motor_packets_json],
+            outputs=[],
+            js=execute_motor_packets_js(),
+        )
+        # Robot chain (parallel)
+        input_submit_event.then(
+            fn=get_scene_robot_pose,
+            inputs=[story_state],
+            outputs=[robot_pose_json],
+        ).then(
+            fn=None,
+            inputs=[robot_pose_json],
+            outputs=[],
+            js=send_robot_pose_js(),
+        )
+
+        # Input enter key
+        input_enter_event = user_input.submit(
+            fn=handle_input,
+            inputs=[story_state, user_input],
+            outputs=all_outputs,
+        )
+        # Audio chain
+        input_enter_event.then(
+            fn=get_scene_audio,
+            inputs=[story_state],
+            outputs=[audio_path_box],
+        ).then(
+            fn=None,
+            inputs=[audio_path_box],
+            outputs=[],
+            js=play_scene_audio_js(),
+        )
+        # Motor chain (parallel)
+        input_enter_event.then(
+            fn=get_scene_motor_packets,
+            inputs=[story_state],
+            outputs=[motor_packets_json],
+        ).then(
+            fn=None,
+            inputs=[motor_packets_json],
+            outputs=[],
+            js=execute_motor_packets_js(),
+        )
+        # Robot chain (parallel)
+        input_enter_event.then(
+            fn=get_scene_robot_pose,
+            inputs=[story_state],
+            outputs=[robot_pose_json],
+        ).then(
+            fn=None,
+            inputs=[robot_pose_json],
+            outputs=[],
+            js=send_robot_pose_js(),
+        )
+
+        # Motor control event handlers
+        # Pattern: Python builds packet -> JS sends/receives -> Python parses
+
+        # Ping button
+        ping_btn.click(
+            fn=dxl_build_ping_packet,
+            inputs=[motor_id_input],
+            outputs=[packet_bytes_json],
+        ).then(
+            fn=None,
+            inputs=[packet_bytes_json],
+            outputs=[response_bytes_json],
+            js=dxl_send_and_receive_js(),
+        ).then(
+            fn=dxl_parse_response,
+            inputs=[response_bytes_json],
+            outputs=[motor_status],
+        )
+
+        # Torque ON button
+        torque_on_btn.click(
+            fn=lambda motor_id: dxl_build_torque_packet(motor_id, True),
+            inputs=[motor_id_input],
+            outputs=[packet_bytes_json],
+        ).then(
+            fn=None,
+            inputs=[packet_bytes_json],
+            outputs=[response_bytes_json],
+            js=dxl_send_and_receive_js(),
+        ).then(
+            fn=dxl_parse_response,
+            inputs=[response_bytes_json],
+            outputs=[motor_status],
+        )
+
+        # Torque OFF button
+        torque_off_btn.click(
+            fn=lambda motor_id: dxl_build_torque_packet(motor_id, False),
+            inputs=[motor_id_input],
+            outputs=[packet_bytes_json],
+        ).then(
+            fn=None,
+            inputs=[packet_bytes_json],
+            outputs=[response_bytes_json],
+            js=dxl_send_and_receive_js(),
+        ).then(
+            fn=dxl_parse_response,
+            inputs=[response_bytes_json],
+            outputs=[motor_status],
+        )
+
+        # Send goal position button
+        send_goal_btn.click(
+            fn=dxl_build_goal_position_packet,
+            inputs=[motor_id_input, goal_slider],
+            outputs=[packet_bytes_json],
+        ).then(
+            fn=None,
+            inputs=[packet_bytes_json],
+            outputs=[response_bytes_json],
+            js=dxl_send_and_receive_js(),
+        ).then(
+            fn=dxl_parse_response,
+            inputs=[response_bytes_json],
+            outputs=[motor_status],
+        )
+
+    return demo
+
+
+def main() -> None:
+    """Launch the Visual Novel Gradio app with FastAPI for static file serving."""
+    # Create FastAPI app
+    fastapi_app = FastAPI()
+
+    # Mount static files for assets and web scripts
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    assets_dir = os.path.join(script_dir, "assets")
+    web_dir = os.path.join(script_dir, "web")
+    fastapi_app.mount("/user-assets", StaticFiles(directory=assets_dir), name="user-assets")
+    fastapi_app.mount("/web", StaticFiles(directory=web_dir), name="web")
+
+    # Build and mount Gradio app
+    gradio_app = build_app()
+    fastapi_app = gr.mount_gradio_app(fastapi_app, gradio_app, path="/")
+
+    # Launch with proper shutdown handling
+    import uvicorn
+    try:
+        uvicorn.run(
+            fastapi_app,
+            host="127.0.0.1",
+            port=7860,
+            log_level="info",
+            timeout_graceful_shutdown=1  # Quick shutdown
+        )
+    except KeyboardInterrupt:
+        print("\n[INFO] Server stopped")
+
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "test-vn"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "gradio>=4.44.0",
+    "fastrtc>=0.0.34",
+    "numpy>=1.26.0",
+]

story.py

@@ -0,0 +1,238 @@
+"""Sample Story - Example visual novel story with branching paths."""
+
+import copy
+from typing import List
+
+from engine import (
+    VisualNovelBuilder,
+    SceneState,
+    CharacterDefinition,
+    Choice,
+    background_asset,
+    sprite_asset,
+    audio_asset,
+    create_sprite_data_url,
+)
+
+
+def build_sample_story() -> List[SceneState]:
+    """Build the sample story with branching paths."""
+    builder = VisualNovelBuilder()
+    builder.set_characters(
+        [
+            CharacterDefinition(
+                name="Ari",
+                image_url=sprite_asset('reachy-mini-cartoon.svg'),
+            ),
+            CharacterDefinition(
+                name="Bo",
+                image_url=sprite_asset('ReachyMini_emotions_happy.svg'),
+                animated=True,
+            ),
+        ]
+    )
+    builder.set_background(
+        background_asset('workshop_bg.png'),
+    )
+    builder.set_stage(background_asset("p60-back-cover.png"))
+
+    builder.narration("A hush falls over the academy courtyard as the gates creak open.")
+    builder.set_stage(
+        background_asset('p3.png'),
+    )
+    # Request player name
+    builder.request_input("What is your name, traveler?", "player_name")
+
+    # After input, create a new state without input_request
+    state = builder._clone_state()
+    state.input_request = None  # Clear the input request
+    state.note = "Continuing story"
+    builder._push_state(state)
+
+    builder.show_character("Ari", position="left")
+    builder.play_sound(audio_asset("wake_up.wav"))
+    builder.dialogue("Ari", "Welcome, {player_name}! I'm Ari, and this is Bo.")
+    builder.show_character("Bo", position="right")
+    builder.dialogue("Bo", "Nice to meet you, {player_name}. We're on a quest to find the star fragment.")
+    builder.dialogue("Ari", "Will you help us on our quest?")
+
+    # ACCEPT BRANCH - tag all scenes with path="accept"
+    accept_index = len(builder._states)
+    builder.set_path("accept")
+    builder.dialogue("Bo", "Excellent! We knew we could count on you, {player_name}!")
+    builder.move_character("Ari", position="center")
+    builder.narration("You join Ari and Bo on their adventure...")
+
+    # Demonstrate camera feature
+    builder.set_camera(True)
+    builder.dialogue("Ari", "First, let me see your face, {player_name}. The camera will help us verify your identity.")
+    builder.narration("The camera activates, showing your live feed...")
+
+    # Demonstrate voice feature
+    builder.set_camera(False)
+    builder.set_voice(True)
+    builder.dialogue("Bo", "Now, tell us about yourself using the voice recorder.")
+    builder.narration("You can now record or upload audio to interact with the companions.")
+
+    # Demonstrate motors feature
+    builder.set_voice(False)
+    builder.set_motors(True)
+    builder.dialogue("Ari", "Finally, we need to test the portal controls. Use the motor panel to align the crystals.")
+    builder.narration("Motor controls are now available. Adjust the servos to proceed.")
+
+    # Example: Send motor commands from the story
+    builder.send_motor_command(1, 90)  # Move motor ID 1 to 90 degrees
+    builder.dialogue("Ari", "Watch as the first crystal aligns itself!")
+
+    # Example: Send multiple motor commands at once
+    builder.send_motor_commands([(1, 180), (2, 90)])  # Move motors 1 and 2
+    builder.dialogue("Ari", "Now the portal crystals are synchronizing!")
+
+    # Example: Play sound effect
+    builder.play_sound(audio_asset("confused1.wav"))  # Uncomment when you add audio files
+    builder.dialogue("Ari", "Listen! The portal resonates with magical energy!")
+
+    # Demonstrate robot control (Reachy Mini)
+    builder.set_motors(False)
+    builder.set_robot(True)
+    builder.dialogue("Bo", "Now let's test the Reachy Mini robot! It should be at localhost:8000.")
+    builder.narration("The robot control panel appears. Make sure your Reachy Mini server is running.")
+
+    # Send robot pose command - head looking up and antennas raised
+    builder.send_robot_pose(
+        head_x=0.0,
+        head_y=0.0,
+        head_z=0.02,  # Raise head 2cm
+        head_pitch=-0.1,  # Look up (negative pitch)
+        antenna_left=-0.2,  # Raise left antenna
+        antenna_right=0.2,  # Raise right antenna
+    )
+    builder.dialogue("Ari", "Watch! The robot looks up in wonder!")
+
+    # Send another pose - head tilted
+    builder.send_robot_pose(
+        head_z=-0.04,  # Raise head 2cm
+        head_roll=0.1,  # Tilt head to the side
+        head_yaw=0.1,  # Turn head slightly
+        antenna_left=-0.3,  # Lower left antenna
+        antenna_right=0.8,  # Raise right antenna more
+    )
+    builder.dialogue("Bo", "The robot is expressing curiosity!")
+
+    # Demonstrate stage layer with separate blur
+    builder.set_robot(False)
+    builder.set_stage(background_asset('p3.png'))  # Add a stage layer
+    builder.dialogue("Ari", "Look! The portal is opening...")
+    builder.narration("A mystical stage appears between you and the background.")
+
+    # Demonstrate separate blur controls
+    builder.set_background_blur(8)
+    builder.set_stage_blur(3)
+    builder.dialogue("Ari", "Wait! Do you sense that? Something magical is happening...")
+    builder.narration("The background and stage blur independently as Ari steps forward.")
+
+    # Clear stage and blur
+    builder.set_background_blur(0)
+    builder.set_stage_blur(0)
+    builder.set_stage("")  # Remove stage layer
+
+    # Demonstrate character animations and sprite changes
+    builder.set_character_animation("Bo", "shake")
+    builder.dialogue("Bo", "Whoa! Did you feel that tremor?!")
+
+    builder.set_character_animation("Bo", "bounce")
+    builder.dialogue("Bo", "This is so exciting! We're getting close!")
+
+    builder.set_character_animation("Bo", "")
+    builder.set_character_animation("Ari", "pulse")
+    builder.dialogue("Ari", "The star fragment... I can feel its power pulsing nearby.")
+
+    # Demonstrate character scaling
+    builder.set_character_animation("Ari", "")
+    builder.set_character_scale("Ari", 1.5)
+    builder.dialogue("Ari", "The power... it's making me grow stronger!")
+
+    builder.set_character_scale("Bo", 0.7)
+    builder.dialogue("Bo", "Whoa, you're getting really big! Or am I shrinking?")
+
+    # Reset scales
+    builder.set_character_scale("Ari", 1.0)
+    builder.set_character_scale("Bo", 1.0)
+
+    # Turn off all features
+    builder.set_motors(False)
+    builder.dialogue("Ari", "The portal is ready! But wait...")
+    builder.dialogue("Bo", "The path splits here! We need to split up to cover more ground.")
+    builder.dialogue("Ari", "You'll need to choose who to follow, {player_name}.")
+
+    # SECOND CHOICE - Follow Ari or Bo
+    # Remember the index before the branches
+    follow_ari_index = len(builder._states)
+
+    # FOLLOW ARI SUB-BRANCH
+    builder.set_path("accept.follow_ari")
+    builder.dialogue("Ari", "Wise choice! My path leads through the ancient library.")
+    builder.hide_character("Bo")
+    builder.move_character("Ari", position="center")
+    builder.set_background(background_asset('p3.png'))
+    builder.narration("Bo waves goodbye as you follow Ari into the misty corridors...")
+    builder.dialogue("Ari", "The fragment's energy is strongest here. Stay close!")
+    builder.set_character_animation("Ari", "pulse")
+    builder.send_motor_command(1, 45)  # Different motor position for this path
+    builder.dialogue("Ari", "The ancient mechanisms are responding!")
+    builder.set_character_animation("Ari", "")
+    builder.narration("You discover the star fragment hidden in an ancient tome.")
+    builder.dialogue("Ari", "We did it, {player_name}! The knowledge was the key all along.")
+    builder.play_sound(audio_asset("wake_up.wav"))
+    builder.narration("✨ Ending: The Scholar's Path (Follow Ari)")
+
+    # FOLLOW BO SUB-BRANCH
+    follow_bo_index = len(builder._states)
+    builder.set_path("accept.follow_bo")
+    builder.dialogue("Bo", "Adventure time! My route goes through the crystal caves!")
+    builder.hide_character("Ari")
+    builder.move_character("Bo", position="center")
+    builder.set_background(background_asset('workshop_bg.png'))
+    builder.narration("Ari nods encouragingly as you follow Bo into the glowing caves...")
+    builder.dialogue("Bo", "Can you feel the energy? It's electric!")
+    builder.set_character_animation("Bo", "bounce")
+    builder.send_motor_commands([(1, 135), (2, 135)])  # Different motor positions
+    builder.dialogue("Bo", "The crystals are resonating! We're so close!")
+    builder.set_character_animation("Bo", "shake")
+    builder.narration("A powerful tremor shakes the cavern as the fragment reveals itself!")
+    builder.dialogue("Bo", "Whoa! Grab it, {player_name}!")
+    builder.set_character_animation("Bo", "")
+    builder.play_sound(audio_asset("wake_up.wav"))
+    builder.narration("✨ Ending: The Adventurer's Path (Follow Bo)")
+
+    # Insert the second choice scene before the sub-branches
+    second_choice_scene = copy.deepcopy(builder._states[follow_ari_index - 1])
+    second_choice_scene.choices = [
+        Choice(text="Follow Ari (Library)", next_scene_index=follow_ari_index),
+        Choice(text="Follow Bo (Caves)", next_scene_index=follow_bo_index),
+    ]
+    second_choice_scene.note = "Second Choice (2 paths)"
+    second_choice_scene.input_request = None
+    second_choice_scene.path = "accept"  # This choice is within the accept path
+    builder._states[follow_ari_index - 1] = second_choice_scene
+
+    # DECLINE BRANCH - tag all scenes with path="decline"
+    decline_index = len(builder._states)
+    builder.set_path("decline")
+    builder.dialogue("Ari", "That's... disappointing, {player_name}.")
+    builder.hide_character("Bo")
+    builder.dialogue("Ari", "I guess we're on our own, Bo.")
+    builder.narration("Ari and Bo leave without you... (Decline path)")
+
+    # Insert the choice scene before the branches
+    choice_scene = copy.deepcopy(builder._states[accept_index - 1])
+    choice_scene.choices = [
+        Choice(text="Yes, I'll help!", next_scene_index=accept_index),
+        Choice(text="No, sorry.", next_scene_index=decline_index),
+    ]
+    choice_scene.note = "Choice (2 options)"
+    choice_scene.input_request = None  # Make sure no input request on choice scene
+    choice_scene.path = None  # Choice scene is on the main path
+    builder._states[accept_index - 1] = choice_scene
+
+    return builder.build()

web/dxl_webserial.js

@@ -0,0 +1,187 @@
+/**
+ * Dynamixel Web Serial - Low-level serial port I/O only.
+ * Protocol logic handled in Python (dynamixel.py).
+ */
+
+const PANEL_HTML = `
+  <div class="dxl-card" id="dxl-panel">
+    <h3>Dynamixel XL330 Control (Web Serial)</h3>
+    <p class="camera-hint">
+      Use Chrome/Edge desktop. Click Connect to pick your serial/USB adapter.
+    </p>
+    <div class="dxl-row">
+      <label for="dxl-baud">Baud</label>
+      <select id="dxl-baud">
+        <option value="57600">57600</option>
+        <option value="115200">115200</option>
+        <option value="1000000" selected>1000000</option>
+        <option value="2000000">2000000</option>
+      </select>
+      <button class="dxl-btn" id="dxl-connect">Connect serial</button>
+    </div>
+    <div class="dxl-status" id="dxl-status">Web Serial idle.</div>
+  </div>
+`;
+
+class DxlWebSerial {
+  constructor(statusNode) {
+    this.statusNode = statusNode;
+    this.port = null;
+    this.writer = null;
+    this.reader = null;
+    this.connected = false;
+  }
+
+  status(msg) {
+    if (this.statusNode) this.statusNode.textContent = msg;
+  }
+
+  async connect(baud) {
+    if (!("serial" in navigator)) {
+      this.status("Web Serial not supported.");
+      return false;
+    }
+    if (this.connected) {
+      await this.disconnect();
+    }
+    try {
+      this.port = await navigator.serial.requestPort();
+      await this.port.open({ baudRate: Number(baud) });
+      this.writer = this.port.writable.getWriter();
+      this.reader = this.port.readable.getReader();
+      this.connected = true;
+      this.status(`Connected at ${baud} bps.`);
+      return true;
+    } catch (err) {
+      console.error(err);
+      this.status(`Connect failed: ${err.message}`);
+      this.connected = false;
+      return false;
+    }
+  }
+
+  async disconnect() {
+    try {
+      if (this.writer) this.writer.releaseLock();
+      if (this.reader) this.reader.releaseLock();
+      if (this.port) await this.port.close();
+    } catch (err) {
+      console.warn("Close error", err);
+    } finally {
+      this.writer = null;
+      this.reader = null;
+      this.port = null;
+      this.connected = false;
+      this.status("Disconnected.");
+    }
+  }
+
+  async writeBytes(bytes) {
+    if (!this.writer) throw new Error("Not connected.");
+    await this.writer.write(new Uint8Array(bytes));
+  }
+
+  async readPacket(timeoutMs = 800) {
+    if (!this.reader) throw new Error("No reader");
+    const deadline = Date.now() + timeoutMs;
+    const buf = [];
+
+    while (Date.now() < deadline) {
+      const { value, done } = await this.reader.read();
+      if (done) break;
+      if (value) buf.push(...value);
+
+      // Look for Dynamixel Protocol 2.0 header and extract complete packet
+      for (let i = 0; i < buf.length - 7; i += 1) {
+        if (
+          buf[i] === 0xff &&
+          buf[i + 1] === 0xff &&
+          buf[i + 2] === 0xfd &&
+          buf[i + 3] === 0x00
+        ) {
+          const len = buf[i + 5] | (buf[i + 6] << 8);
+          const end = i + 7 + len - 1;
+          if (buf.length >= end + 1) {
+            return buf.slice(i, end + 1);
+          }
+        }
+      }
+    }
+    throw new Error("No response");
+  }
+}
+
+// Global instance - expose on window for access from Gradio event handlers
+let dxlSerial = null;
+window.dxlSerial = null;
+
+function mountDxlPanel() {
+  const host = document.getElementById("dxl-panel-host");
+
+  if (!host) return;
+
+  // If already mounted, just ensure window.dxlSerial exists
+  if (host.dataset.mounted === "1") {
+    if (!window.dxlSerial) {
+      const statusEl = document.getElementById("dxl-status");
+      if (statusEl) {
+        dxlSerial = new DxlWebSerial(statusEl);
+        window.dxlSerial = dxlSerial;
+      }
+    }
+    return;
+  }
+
+  host.dataset.mounted = "1";
+  host.innerHTML = PANEL_HTML;
+
+  const statusEl = document.getElementById("dxl-status");
+  const connectBtn = document.getElementById("dxl-connect");
+  const baudSelect = document.getElementById("dxl-baud");
+
+  dxlSerial = new DxlWebSerial(statusEl);
+  window.dxlSerial = dxlSerial;  // Expose globally
+
+  connectBtn?.addEventListener("click", async () => {
+    const baud = Number(baudSelect.value);
+    if (dxlSerial.connected) {
+      await dxlSerial.disconnect();
+      connectBtn.textContent = "Connect serial";
+      connectBtn.classList.remove("primary");
+    } else {
+      const connected = await dxlSerial.connect(baud);
+      if (connected) {
+        connectBtn.textContent = "Disconnect";
+        connectBtn.classList.add("primary");
+      }
+    }
+  });
+}
+
+function mountWhenReady() {
+  mountDxlPanel();
+
+  const observer = new MutationObserver(() => {
+    mountDxlPanel();
+  });
+  observer.observe(document.body, { childList: true, subtree: true });
+
+  const pollInterval = setInterval(() => {
+    const host = document.getElementById("dxl-panel-host");
+    if (host && !host.dataset.mounted) {
+      const rect = host.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) {
+        mountDxlPanel();
+      }
+    }
+    if (host?.dataset.mounted === "1") {
+      clearInterval(pollInterval);
+    }
+  }, 500);
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", mountWhenReady);
+} else {
+  mountWhenReady();
+}