@mecha.im/cli 0.3.4

package/agent/dashboard/src/pixel-engine/engine/officeState.ts

@@ -0,0 +1,748 @@
+import {
+  AUTO_ON_FACING_DEPTH,
+  AUTO_ON_SIDE_DEPTH,
+  CHARACTER_HIT_HALF_WIDTH,
+  CHARACTER_HIT_HEIGHT,
+  CHARACTER_SITTING_OFFSET_PX,
+  DISMISS_BUBBLE_FAST_FADE_SEC,
+  FURNITURE_ANIM_INTERVAL_SEC,
+  HUE_SHIFT_MIN_DEG,
+  HUE_SHIFT_RANGE_DEG,
+  INACTIVE_SEAT_TIMER_MIN_SEC,
+  INACTIVE_SEAT_TIMER_RANGE_SEC,
+  PALETTE_COUNT,
+  WAITING_BUBBLE_DURATION_SEC,
+} from '../constants.js';
+import { getAnimationFrames, getCatalogEntry, getOnStateType } from '../layout/furnitureCatalog.js';
+import {
+  createDefaultLayout,
+  getBlockedTiles,
+  layoutToFurnitureInstances,
+  layoutToSeats,
+  layoutToTileMap,
+} from '../layout/layoutSerializer.js';
+import { findPath, getWalkableTiles, isWalkable } from '../layout/tileMap.js';
+import type {
+  Character,
+  FurnitureInstance,
+  OfficeLayout,
+  PlacedFurniture,
+  Seat,
+  TileType as TileTypeVal,
+} from '../types.js';
+import { CharacterState, Direction, MATRIX_EFFECT_DURATION, TILE_SIZE } from '../types.js';
+import { createCharacter, updateCharacter } from './characters.js';
+import { InteractionScheduler } from './interactionScheduler.js';
+import { matrixEffectSeeds } from './matrixEffect.js';
+
+export class OfficeState {
+  layout: OfficeLayout;
+  tileMap: TileTypeVal[][];
+  seats: Map<string, Seat>;
+  blockedTiles: Set<string>;
+  furniture: FurnitureInstance[];
+  walkableTiles: Array<{ col: number; row: number }>;
+  characters: Map<number, Character> = new Map();
+  /** Accumulated time for furniture animation frame cycling */
+  furnitureAnimTimer = 0;
+  selectedAgentId: number | null = null;
+  cameraFollowId: number | null = null;
+  hoveredAgentId: number | null = null;
+  hoveredTile: { col: number; row: number } | null = null;
+  scheduler = new InteractionScheduler();
+  /** Maps "parentId:toolId" → sub-agent character ID (negative) */
+  subagentIdMap: Map<string, number> = new Map();
+  /** Reverse lookup: sub-agent character ID → parent info */
+  subagentMeta: Map<number, { parentAgentId: number; parentToolId: string }> = new Map();
+  private nextSubagentId = -1;
+
+  constructor(layout?: OfficeLayout) {
+    this.layout = layout || createDefaultLayout();
+    this.tileMap = layoutToTileMap(this.layout);
+    this.seats = layoutToSeats(this.layout.furniture);
+    this.blockedTiles = getBlockedTiles(this.layout.furniture);
+    this.furniture = layoutToFurnitureInstances(this.layout.furniture);
+    this.walkableTiles = getWalkableTiles(this.tileMap, this.blockedTiles);
+  }
+
+  /** Rebuild all derived state from a new layout. Reassigns existing characters.
+   *  @param shift Optional pixel shift to apply when grid expands left/up */
+  rebuildFromLayout(layout: OfficeLayout, shift?: { col: number; row: number }): void {
+    this.layout = layout;
+    this.tileMap = layoutToTileMap(layout);
+    this.seats = layoutToSeats(layout.furniture);
+    this.blockedTiles = getBlockedTiles(layout.furniture);
+    this.rebuildFurnitureInstances();
+    this.walkableTiles = getWalkableTiles(this.tileMap, this.blockedTiles);
+
+    // Shift character positions when grid expands left/up, and invalidate all paths
+    for (const ch of this.characters.values()) {
+      if (shift && (shift.col !== 0 || shift.row !== 0)) {
+        ch.tileCol += shift.col;
+        ch.tileRow += shift.row;
+        ch.x += shift.col * TILE_SIZE;
+        ch.y += shift.row * TILE_SIZE;
+      }
+      // Always clear paths on layout rebuild — old paths may cross new walls/furniture
+      ch.path = [];
+      ch.moveProgress = 0;
+    }
+
+    // Clear transient scheduler state on layout rebuild
+    this.scheduler.furnitureReservations.clear();
+    this.scheduler.chatPairs.clear();
+    this.scheduler.deskClaims.clear();
+    this.scheduler.pendingRealChats = [];
+    for (const ch of this.characters.values()) {
+      ch.workDeskId = null;
+      ch.chatPartner = null;
+      ch.interactTarget = null;
+    }
+
+    // Reassign characters to new seats, preserving existing assignments when possible
+    for (const seat of this.seats.values()) {
+      seat.assigned = false;
+    }
+
+    // First pass: try to keep characters at their existing seats
+    for (const ch of this.characters.values()) {
+      if (ch.seatId && this.seats.has(ch.seatId)) {
+        const seat = this.seats.get(ch.seatId)!;
+        if (!seat.assigned) {
+          seat.assigned = true;
+          // Snap character to seat position
+          ch.tileCol = seat.seatCol;
+          ch.tileRow = seat.seatRow;
+          const cx = seat.seatCol * TILE_SIZE + TILE_SIZE / 2;
+          const cy = seat.seatRow * TILE_SIZE + TILE_SIZE / 2;
+          ch.x = cx;
+          ch.y = cy;
+          ch.dir = seat.facingDir;
+          continue;
+        }
+      }
+      ch.seatId = null; // will be reassigned below
+    }
+
+    // Second pass: assign remaining characters to free seats
+    for (const ch of this.characters.values()) {
+      if (ch.seatId) continue;
+      const seatId = this.findFreeSeat();
+      if (seatId) {
+        this.seats.get(seatId)!.assigned = true;
+        ch.seatId = seatId;
+        const seat = this.seats.get(seatId)!;
+        ch.tileCol = seat.seatCol;
+        ch.tileRow = seat.seatRow;
+        ch.x = seat.seatCol * TILE_SIZE + TILE_SIZE / 2;
+        ch.y = seat.seatRow * TILE_SIZE + TILE_SIZE / 2;
+        ch.dir = seat.facingDir;
+      }
+    }
+
+    // Relocate any characters that ended up outside bounds or on blocked/non-walkable tiles
+    for (const ch of this.characters.values()) {
+      if (ch.seatId) continue; // seated characters are fine
+      if (
+        ch.tileCol < 0 ||
+        ch.tileCol >= layout.cols ||
+        ch.tileRow < 0 ||
+        ch.tileRow >= layout.rows ||
+        this.blockedTiles.has(`${ch.tileCol},${ch.tileRow}`) ||
+        !isWalkable(ch.tileCol, ch.tileRow, this.tileMap, this.blockedTiles)
+      ) {
+        this.relocateCharacterToWalkable(ch);
+      }
+    }
+  }
+
+  /** Move a character to a random walkable tile */
+  private relocateCharacterToWalkable(ch: Character): void {
+    if (this.walkableTiles.length === 0) return;
+    const spawn = this.walkableTiles[Math.floor(Math.random() * this.walkableTiles.length)];
+    ch.tileCol = spawn.col;
+    ch.tileRow = spawn.row;
+    ch.x = spawn.col * TILE_SIZE + TILE_SIZE / 2;
+    ch.y = spawn.row * TILE_SIZE + TILE_SIZE / 2;
+    ch.path = [];
+    ch.moveProgress = 0;
+  }
+
+  getLayout(): OfficeLayout {
+    return this.layout;
+  }
+
+  /** Get the blocked-tile key for a character's own seat, or null */
+  private ownSeatKey(ch: Character): string | null {
+    if (!ch.seatId) return null;
+    const seat = this.seats.get(ch.seatId);
+    if (!seat) return null;
+    return `${seat.seatCol},${seat.seatRow}`;
+  }
+
+  /** Temporarily unblock a character's own seat, run fn, then re-block */
+  private withOwnSeatUnblocked<T>(ch: Character, fn: () => T): T {
+    const key = this.ownSeatKey(ch);
+    if (key) this.blockedTiles.delete(key);
+    const result = fn();
+    if (key) this.blockedTiles.add(key);
+    return result;
+  }
+
+  private findFreeSeat(): string | null {
+    for (const [uid, seat] of this.seats) {
+      if (!seat.assigned) return uid;
+    }
+    return null;
+  }
+
+  /**
+   * Pick a diverse palette for a new agent based on currently active agents.
+   * First 6 agents each get a unique skin (random order). Beyond 6, skins
+   * repeat in balanced rounds with a random hue shift (≥45°).
+   */
+  private pickDiversePalette(): { palette: number; hueShift: number } {
+    // Count how many non-sub-agents use each base palette (0-5)
+    const counts = new Array(PALETTE_COUNT).fill(0) as number[];
+    for (const ch of this.characters.values()) {
+      if (ch.isSubagent) continue;
+      counts[ch.palette]++;
+    }
+    const minCount = Math.min(...counts);
+    // Available = palettes at the minimum count (least used)
+    const available: number[] = [];
+    for (let i = 0; i < PALETTE_COUNT; i++) {
+      if (counts[i] === minCount) available.push(i);
+    }
+    const palette = available[Math.floor(Math.random() * available.length)];
+    // First round (minCount === 0): no hue shift. Subsequent rounds: random ≥45°.
+    let hueShift = 0;
+    if (minCount > 0) {
+      hueShift = HUE_SHIFT_MIN_DEG + Math.floor(Math.random() * HUE_SHIFT_RANGE_DEG);
+    }
+    return { palette, hueShift };
+  }
+
+  addAgent(
+    id: number,
+    preferredPalette?: number,
+    preferredHueShift?: number,
+    preferredSeatId?: string,
+    skipSpawnEffect?: boolean,
+    folderName?: string,
+  ): void {
+    if (this.characters.has(id)) return;
+
+    let palette: number;
+    let hueShift: number;
+    if (preferredPalette !== undefined) {
+      palette = preferredPalette;
+      hueShift = preferredHueShift ?? 0;
+    } else {
+      const pick = this.pickDiversePalette();
+      palette = pick.palette;
+      hueShift = pick.hueShift;
+    }
+
+    // Try preferred seat first, then any free seat
+    let seatId: string | null = null;
+    if (preferredSeatId && this.seats.has(preferredSeatId)) {
+      const seat = this.seats.get(preferredSeatId)!;
+      if (!seat.assigned) {
+        seatId = preferredSeatId;
+      }
+    }
+    if (!seatId) {
+      seatId = this.findFreeSeat();
+    }
+
+    let ch: Character;
+    if (seatId) {
+      const seat = this.seats.get(seatId)!;
+      seat.assigned = true;
+      ch = createCharacter(id, palette, seatId, seat, hueShift);
+    } else {
+      // No seats — spawn at random walkable tile
+      const spawn =
+        this.walkableTiles.length > 0
+          ? this.walkableTiles[Math.floor(Math.random() * this.walkableTiles.length)]
+          : { col: 1, row: 1 };
+      ch = createCharacter(id, palette, null, null, hueShift);
+      ch.x = spawn.col * TILE_SIZE + TILE_SIZE / 2;
+      ch.y = spawn.row * TILE_SIZE + TILE_SIZE / 2;
+      ch.tileCol = spawn.col;
+      ch.tileRow = spawn.row;
+    }
+
+    if (folderName) {
+      ch.folderName = folderName;
+    }
+    if (!skipSpawnEffect) {
+      ch.matrixEffect = 'spawn';
+      ch.matrixEffectTimer = 0;
+      ch.matrixEffectSeeds = matrixEffectSeeds();
+    }
+    this.characters.set(id, ch);
+  }
+
+  removeAgent(id: number): void {
+    const ch = this.characters.get(id);
+    if (!ch) return;
+    if (ch.matrixEffect === 'despawn') return; // already despawning
+    // Release scheduler reservations
+    this.scheduler.releaseAll(id, this.characters);
+    // Free seat and clear selection immediately
+    if (ch.seatId) {
+      const seat = this.seats.get(ch.seatId);
+      if (seat) seat.assigned = false;
+    }
+    if (this.selectedAgentId === id) this.selectedAgentId = null;
+    if (this.cameraFollowId === id) this.cameraFollowId = null;
+    // Start despawn animation instead of immediate delete
+    ch.matrixEffect = 'despawn';
+    ch.matrixEffectTimer = 0;
+    ch.matrixEffectSeeds = matrixEffectSeeds();
+    ch.bubbleType = null;
+  }
+
+  /** Find seat uid at a given tile position, or null */
+  getSeatAtTile(col: number, row: number): string | null {
+    for (const [uid, seat] of this.seats) {
+      if (seat.seatCol === col && seat.seatRow === row) return uid;
+    }
+    return null;
+  }
+
+  /** Reassign an agent from their current seat to a new seat */
+  reassignSeat(agentId: number, seatId: string): void {
+    const ch = this.characters.get(agentId);
+    if (!ch) return;
+    // Validate new seat BEFORE freeing old one
+    const seat = this.seats.get(seatId);
+    if (!seat || seat.assigned) return;
+    // Unassign old seat (now safe — new seat is confirmed available)
+    if (ch.seatId) {
+      const old = this.seats.get(ch.seatId);
+      if (old) old.assigned = false;
+    }
+    seat.assigned = true;
+    ch.seatId = seatId;
+    ch.homeSeatId = seatId;
+    // Pathfind to new seat (unblock own seat tile for this query)
+    const path = this.withOwnSeatUnblocked(ch, () =>
+      findPath(ch.tileCol, ch.tileRow, seat.seatCol, seat.seatRow, this.tileMap, this.blockedTiles),
+    );
+    if (path.length > 0) {
+      ch.path = path;
+      ch.moveProgress = 0;
+      ch.state = CharacterState.WALK;
+      ch.frame = 0;
+      ch.frameTimer = 0;
+    } else if (ch.tileCol === seat.seatCol && ch.tileRow === seat.seatRow) {
+      // Already at seat — sit down
+      ch.state = CharacterState.TYPE;
+      ch.dir = seat.facingDir;
+      ch.frame = 0;
+      ch.frameTimer = 0;
+      if (!ch.isActive) {
+        ch.seatTimer = INACTIVE_SEAT_TIMER_MIN_SEC + Math.random() * INACTIVE_SEAT_TIMER_RANGE_SEC;
+      }
+    }
+    // else: seat unreachable — stay idle, don't teleport
+  }
+
+  /** Send an agent back to their currently assigned seat */
+  sendToSeat(agentId: number): void {
+    const ch = this.characters.get(agentId);
+    if (!ch || !ch.seatId) return;
+    const seat = this.seats.get(ch.seatId);
+    if (!seat) return;
+    const path = this.withOwnSeatUnblocked(ch, () =>
+      findPath(ch.tileCol, ch.tileRow, seat.seatCol, seat.seatRow, this.tileMap, this.blockedTiles),
+    );
+    if (path.length > 0) {
+      ch.path = path;
+      ch.moveProgress = 0;
+      ch.state = CharacterState.WALK;
+      ch.frame = 0;
+      ch.frameTimer = 0;
+    } else if (ch.tileCol === seat.seatCol && ch.tileRow === seat.seatRow) {
+      // Already at seat — sit down
+      ch.state = CharacterState.TYPE;
+      ch.dir = seat.facingDir;
+      ch.frame = 0;
+      ch.frameTimer = 0;
+      if (!ch.isActive) {
+        ch.seatTimer = INACTIVE_SEAT_TIMER_MIN_SEC + Math.random() * INACTIVE_SEAT_TIMER_RANGE_SEC;
+      }
+    }
+    // else: seat unreachable — stay idle
+  }
+
+  /** Walk an agent to an arbitrary walkable tile (right-click command) */
+  walkToTile(agentId: number, col: number, row: number): boolean {
+    const ch = this.characters.get(agentId);
+    if (!ch || ch.isSubagent) return false;
+    if (!isWalkable(col, row, this.tileMap, this.blockedTiles)) {
+      // Also allow walking to own seat tile (blocked for others but not self)
+      const key = this.ownSeatKey(ch);
+      if (!key || key !== `${col},${row}`) return false;
+    }
+    const path = this.withOwnSeatUnblocked(ch, () =>
+      findPath(ch.tileCol, ch.tileRow, col, row, this.tileMap, this.blockedTiles),
+    );
+    if (path.length === 0) return false;
+    ch.path = path;
+    ch.moveProgress = 0;
+    ch.state = CharacterState.WALK;
+    ch.frame = 0;
+    ch.frameTimer = 0;
+    return true;
+  }
+
+  /** Create a sub-agent character with the parent's palette. Returns the sub-agent ID. */
+  addSubagent(parentAgentId: number, parentToolId: string): number {
+    const key = `${parentAgentId}:${parentToolId}`;
+    if (this.subagentIdMap.has(key)) return this.subagentIdMap.get(key)!;
+
+    const id = this.nextSubagentId--;
+    const parentCh = this.characters.get(parentAgentId);
+    const palette = parentCh ? parentCh.palette : 0;
+    const hueShift = parentCh ? parentCh.hueShift : 0;
+
+    // Find the free seat closest to the parent agent
+    const parentCol = parentCh ? parentCh.tileCol : 0;
+    const parentRow = parentCh ? parentCh.tileRow : 0;
+    const dist = (c: number, r: number) => Math.abs(c - parentCol) + Math.abs(r - parentRow);
+
+    let bestSeatId: string | null = null;
+    let bestDist = Infinity;
+    for (const [uid, seat] of this.seats) {
+      if (!seat.assigned) {
+        const d = dist(seat.seatCol, seat.seatRow);
+        if (d < bestDist) {
+          bestDist = d;
+          bestSeatId = uid;
+        }
+      }
+    }
+
+    let ch: Character;
+    if (bestSeatId) {
+      const seat = this.seats.get(bestSeatId)!;
+      seat.assigned = true;
+      ch = createCharacter(id, palette, bestSeatId, seat, hueShift);
+    } else {
+      // No seats — spawn at closest walkable tile to parent
+      let spawn = { col: 1, row: 1 };
+      if (this.walkableTiles.length > 0) {
+        let closest = this.walkableTiles[0];
+        let closestDist = dist(closest.col, closest.row);
+        for (let i = 1; i < this.walkableTiles.length; i++) {
+          const d = dist(this.walkableTiles[i].col, this.walkableTiles[i].row);
+          if (d < closestDist) {
+            closest = this.walkableTiles[i];
+            closestDist = d;
+          }
+        }
+        spawn = closest;
+      }
+      ch = createCharacter(id, palette, null, null, hueShift);
+      ch.x = spawn.col * TILE_SIZE + TILE_SIZE / 2;
+      ch.y = spawn.row * TILE_SIZE + TILE_SIZE / 2;
+      ch.tileCol = spawn.col;
+      ch.tileRow = spawn.row;
+    }
+    ch.isSubagent = true;
+    ch.parentAgentId = parentAgentId;
+    ch.matrixEffect = 'spawn';
+    ch.matrixEffectTimer = 0;
+    ch.matrixEffectSeeds = matrixEffectSeeds();
+    this.characters.set(id, ch);
+
+    this.subagentIdMap.set(key, id);
+    this.subagentMeta.set(id, { parentAgentId, parentToolId });
+    return id;
+  }
+
+  /** Remove a specific sub-agent character and free its seat */
+  removeSubagent(parentAgentId: number, parentToolId: string): void {
+    const key = `${parentAgentId}:${parentToolId}`;
+    const id = this.subagentIdMap.get(key);
+    if (id === undefined) return;
+
+    const ch = this.characters.get(id);
+    if (ch) {
+      if (ch.matrixEffect === 'despawn') {
+        // Already despawning — just clean up maps
+        this.subagentIdMap.delete(key);
+        this.subagentMeta.delete(id);
+        return;
+      }
+      if (ch.seatId) {
+        const seat = this.seats.get(ch.seatId);
+        if (seat) seat.assigned = false;
+      }
+      // Start despawn animation — keep character in map for rendering
+      ch.matrixEffect = 'despawn';
+      ch.matrixEffectTimer = 0;
+      ch.matrixEffectSeeds = matrixEffectSeeds();
+      ch.bubbleType = null;
+    }
+    // Clean up tracking maps immediately so keys don't collide
+    this.subagentIdMap.delete(key);
+    this.subagentMeta.delete(id);
+    if (this.selectedAgentId === id) this.selectedAgentId = null;
+    if (this.cameraFollowId === id) this.cameraFollowId = null;
+  }
+
+  /** Remove all sub-agents belonging to a parent agent */
+  removeAllSubagents(parentAgentId: number): void {
+    const toRemove: string[] = [];
+    for (const [key, id] of this.subagentIdMap) {
+      const meta = this.subagentMeta.get(id);
+      if (meta && meta.parentAgentId === parentAgentId) {
+        const ch = this.characters.get(id);
+        if (ch) {
+          if (ch.matrixEffect === 'despawn') {
+            // Already despawning — just clean up maps
+            this.subagentMeta.delete(id);
+            toRemove.push(key);
+            continue;
+          }
+          if (ch.seatId) {
+            const seat = this.seats.get(ch.seatId);
+            if (seat) seat.assigned = false;
+          }
+          // Start despawn animation
+          ch.matrixEffect = 'despawn';
+          ch.matrixEffectTimer = 0;
+          ch.matrixEffectSeeds = matrixEffectSeeds();
+          ch.bubbleType = null;
+        }
+        this.subagentMeta.delete(id);
+        if (this.selectedAgentId === id) this.selectedAgentId = null;
+        if (this.cameraFollowId === id) this.cameraFollowId = null;
+        toRemove.push(key);
+      }
+    }
+    for (const key of toRemove) {
+      this.subagentIdMap.delete(key);
+    }
+  }
+
+  /** Look up the sub-agent character ID for a given parent+toolId, or null */
+  getSubagentId(parentAgentId: number, parentToolId: string): number | null {
+    return this.subagentIdMap.get(`${parentAgentId}:${parentToolId}`) ?? null;
+  }
+
+  setAgentActive(id: number, active: boolean): void {
+    const ch = this.characters.get(id);
+    if (ch) {
+      ch.isActive = active;
+      if (!active) {
+        // Sentinel -1: signals turn just ended, skip next seat rest timer.
+        // Prevents the WALK handler from setting a 2-4 min rest on arrival.
+        ch.seatTimer = -1;
+        ch.path = [];
+        ch.moveProgress = 0;
+      }
+      this.rebuildFurnitureInstances();
+    }
+  }
+
+  /** Rebuild furniture instances with auto-state applied (active agents turn electronics ON) */
+  private rebuildFurnitureInstances(): void {
+    // Collect tiles where active agents face desks
+    const autoOnTiles = new Set<string>();
+    for (const ch of this.characters.values()) {
+      if (!ch.isActive) continue;
+      const activeSeatId = ch.workDeskId ?? ch.seatId;
+      if (!activeSeatId) continue;
+      const seat = this.seats.get(activeSeatId);
+      if (!seat) continue;
+      // Find the desk tile(s) the agent faces from their seat
+      const dCol =
+        seat.facingDir === Direction.RIGHT ? 1 : seat.facingDir === Direction.LEFT ? -1 : 0;
+      const dRow = seat.facingDir === Direction.DOWN ? 1 : seat.facingDir === Direction.UP ? -1 : 0;
+      // Check tiles in the facing direction (desk could be 1-3 tiles deep)
+      for (let d = 1; d <= AUTO_ON_FACING_DEPTH; d++) {
+        const tileCol = seat.seatCol + dCol * d;
+        const tileRow = seat.seatRow + dRow * d;
+        autoOnTiles.add(`${tileCol},${tileRow}`);
+      }
+      // Also check tiles to the sides of the facing direction (desks can be wide)
+      for (let d = 1; d <= AUTO_ON_SIDE_DEPTH; d++) {
+        const baseCol = seat.seatCol + dCol * d;
+        const baseRow = seat.seatRow + dRow * d;
+        if (dCol !== 0) {
+          // Facing left/right: check tiles above and below
+          autoOnTiles.add(`${baseCol},${baseRow - 1}`);
+          autoOnTiles.add(`${baseCol},${baseRow + 1}`);
+        } else {
+          // Facing up/down: check tiles left and right
+          autoOnTiles.add(`${baseCol - 1},${baseRow}`);
+          autoOnTiles.add(`${baseCol + 1},${baseRow}`);
+        }
+      }
+    }
+
+    if (autoOnTiles.size === 0) {
+      this.furniture = layoutToFurnitureInstances(this.layout.furniture);
+      return;
+    }
+
+    // Build modified furniture list with auto-state and animation applied
+    const animFrame = Math.floor(this.furnitureAnimTimer / FURNITURE_ANIM_INTERVAL_SEC);
+    const modifiedFurniture: PlacedFurniture[] = this.layout.furniture.map((item) => {
+      const entry = getCatalogEntry(item.type);
+      if (!entry) return item;
+      // Check if any tile of this furniture overlaps an auto-on tile
+      for (let dr = 0; dr < entry.footprintH; dr++) {
+        for (let dc = 0; dc < entry.footprintW; dc++) {
+          if (autoOnTiles.has(`${item.col + dc},${item.row + dr}`)) {
+            let onType = getOnStateType(item.type);
+            if (onType !== item.type) {
+              // Check if the on-state type has animation frames
+              const frames = getAnimationFrames(onType);
+              if (frames && frames.length > 1) {
+                const frameIdx = animFrame % frames.length;
+                onType = frames[frameIdx];
+              }
+              return { ...item, type: onType };
+            }
+            return item;
+          }
+        }
+      }
+      return item;
+    });
+
+    this.furniture = layoutToFurnitureInstances(modifiedFurniture);
+  }
+
+  setAgentTool(id: number, tool: string | null): void {
+    const ch = this.characters.get(id);
+    if (ch) {
+      ch.currentTool = tool;
+    }
+  }
+
+  showPermissionBubble(id: number): void {
+    const ch = this.characters.get(id);
+    if (ch) {
+      ch.bubbleType = 'permission';
+      ch.bubbleTimer = 0;
+    }
+  }
+
+  clearPermissionBubble(id: number): void {
+    const ch = this.characters.get(id);
+    if (ch && ch.bubbleType === 'permission') {
+      ch.bubbleType = null;
+      ch.bubbleTimer = 0;
+    }
+  }
+
+  showWaitingBubble(id: number): void {
+    const ch = this.characters.get(id);
+    if (ch) {
+      ch.bubbleType = 'waiting';
+      ch.bubbleTimer = WAITING_BUBBLE_DURATION_SEC;
+    }
+  }
+
+  /** Dismiss bubble on click — permission: instant, waiting: quick fade */
+  dismissBubble(id: number): void {
+    const ch = this.characters.get(id);
+    if (!ch || !ch.bubbleType) return;
+    if (ch.bubbleType === 'permission') {
+      ch.bubbleType = null;
+      ch.bubbleTimer = 0;
+    } else if (ch.bubbleType === 'waiting') {
+      // Trigger immediate fade (0.3s remaining)
+      ch.bubbleTimer = Math.min(ch.bubbleTimer, DISMISS_BUBBLE_FAST_FADE_SEC);
+    }
+  }
+
+  claimDeskForAgent(charId: number): Seat | null {
+    const char = this.characters.get(charId);
+    if (!char) return null;
+    return this.scheduler.claimDeskSeat(char, this.seats, this.tileMap, this.blockedTiles);
+  }
+
+  update(dt: number): void {
+    // Process pending real chats from SSE events
+    this.scheduler.processPendingChats(this.characters, this.tileMap, this.blockedTiles);
+
+    // Furniture animation cycling
+    const prevFrame = Math.floor(this.furnitureAnimTimer / FURNITURE_ANIM_INTERVAL_SEC);
+    this.furnitureAnimTimer += dt;
+    const newFrame = Math.floor(this.furnitureAnimTimer / FURNITURE_ANIM_INTERVAL_SEC);
+    if (newFrame !== prevFrame) {
+      this.rebuildFurnitureInstances();
+    }
+
+    const toDelete: number[] = [];
+    for (const ch of this.characters.values()) {
+      // Handle matrix effect animation
+      if (ch.matrixEffect) {
+        ch.matrixEffectTimer += dt;
+        if (ch.matrixEffectTimer >= MATRIX_EFFECT_DURATION) {
+          if (ch.matrixEffect === 'spawn') {
+            // Spawn complete — clear effect, resume normal FSM
+            ch.matrixEffect = null;
+            ch.matrixEffectTimer = 0;
+            ch.matrixEffectSeeds = [];
+          } else {
+            // Despawn complete — mark for deletion
+            toDelete.push(ch.id);
+          }
+        }
+        continue; // skip normal FSM while effect is active
+      }
+
+      // Temporarily unblock own seat so character can pathfind to it
+      this.withOwnSeatUnblocked(ch, () =>
+        updateCharacter(ch, dt, this.walkableTiles, this.seats, this.tileMap, this.blockedTiles, this),
+      );
+
+      // Tick bubble timer for waiting bubbles
+      if (ch.bubbleType === 'waiting') {
+        ch.bubbleTimer -= dt;
+        if (ch.bubbleTimer <= 0) {
+          ch.bubbleType = null;
+          ch.bubbleTimer = 0;
+        }
+      }
+    }
+    // Remove characters that finished despawn
+    for (const id of toDelete) {
+      this.characters.delete(id);
+    }
+  }
+
+  getCharacters(): Character[] {
+    return Array.from(this.characters.values());
+  }
+
+  /** Get character at pixel position (for hit testing). Returns id or null.
+   *  Single-pass scan: picks the frontmost (highest y) match without sorting. */
+  getCharacterAt(worldX: number, worldY: number): number | null {
+    let bestId: number | null = null;
+    let bestY = -Infinity;
+    for (const ch of this.characters.values()) {
+      if (ch.matrixEffect === 'despawn') continue;
+      const sittingOffset = (ch.state === CharacterState.TYPE || ch.state === CharacterState.SIT) ? CHARACTER_SITTING_OFFSET_PX : 0;
+      const anchorY = ch.y + sittingOffset;
+      const left = ch.x - CHARACTER_HIT_HALF_WIDTH;
+      const right = ch.x + CHARACTER_HIT_HALF_WIDTH;
+      const top = anchorY - CHARACTER_HIT_HEIGHT;
+      const bottom = anchorY;
+      if (worldX >= left && worldX <= right && worldY >= top && worldY <= bottom) {
+        if (ch.y > bestY) { bestId = ch.id; bestY = ch.y; }
+      }
+    }
+    return bestId;
+  }
+}