@mecha.im/cli 0.3.4

package/agent/dashboard/src/pixel-engine/sprites/bubble-waiting.json

@@ -0,0 +1,27 @@
+{
+  "name": "bubble-waiting",
+  "description": "Waiting bubble: white square with green checkmark, and a tail pointer (11x13)",
+  "width": 11,
+  "height": 13,
+  "palette": {
+    "_": "",
+    "B": "#555566",
+    "F": "#EEEEFF",
+    "G": "#44BB66"
+  },
+  "pixels": [
+    ["_","B","B","B","B","B","B","B","B","B","_"],
+    ["B","F","F","F","F","F","F","F","F","F","B"],
+    ["B","F","F","F","F","F","F","F","F","F","B"],
+    ["B","F","F","F","F","F","F","F","G","F","B"],
+    ["B","F","F","F","F","F","F","G","F","F","B"],
+    ["B","F","F","G","F","F","G","F","F","F","B"],
+    ["B","F","F","F","G","G","F","F","F","F","B"],
+    ["B","F","F","F","F","F","F","F","F","F","B"],
+    ["B","F","F","F","F","F","F","F","F","F","B"],
+    ["_","B","B","B","B","B","B","B","B","B","_"],
+    ["_","_","_","_","B","B","B","_","_","_","_"],
+    ["_","_","_","_","_","B","_","_","_","_","_"],
+    ["_","_","_","_","_","_","_","_","_","_","_"]
+  ]
+}

package/agent/dashboard/src/pixel-engine/sprites/spriteCache.ts

@@ -0,0 +1,82 @@
+import type { SpriteData } from '../types.js';
+
+const zoomCaches = new Map<number, WeakMap<SpriteData, HTMLCanvasElement>>();
+
+/** Clear all zoom-level sprite caches (e.g., on tab deactivation) */
+export function clearSpriteCache(): void {
+  zoomCaches.clear();
+}
+
+// ── Outline sprite generation ─────────────────────────────────
+
+const outlineCache = new WeakMap<SpriteData, SpriteData>();
+
+/** Generate a 1px white outline SpriteData (2px larger in each dimension) */
+export function getOutlineSprite(sprite: SpriteData): SpriteData {
+  const cached = outlineCache.get(sprite);
+  if (cached) return cached;
+
+  const rows = sprite.length;
+  const cols = sprite[0].length;
+  // Expanded grid: +2 in each dimension for 1px border
+  const outline: string[][] = [];
+  for (let r = 0; r < rows + 2; r++) {
+    outline.push(new Array<string>(cols + 2).fill(''));
+  }
+
+  // For each opaque pixel, mark its 4 cardinal neighbors as white
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      if (sprite[r][c] === '') continue;
+      const er = r + 1;
+      const ec = c + 1;
+      if (outline[er - 1][ec] === '') outline[er - 1][ec] = '#FFFFFF';
+      if (outline[er + 1][ec] === '') outline[er + 1][ec] = '#FFFFFF';
+      if (outline[er][ec - 1] === '') outline[er][ec - 1] = '#FFFFFF';
+      if (outline[er][ec + 1] === '') outline[er][ec + 1] = '#FFFFFF';
+    }
+  }
+
+  // Clear pixels that overlap with original opaque pixels
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      if (sprite[r][c] !== '') {
+        outline[r + 1][c + 1] = '';
+      }
+    }
+  }
+
+  outlineCache.set(sprite, outline);
+  return outline;
+}
+
+export function getCachedSprite(sprite: SpriteData, zoom: number): HTMLCanvasElement {
+  let cache = zoomCaches.get(zoom);
+  if (!cache) {
+    cache = new WeakMap();
+    zoomCaches.set(zoom, cache);
+  }
+
+  const cached = cache.get(sprite);
+  if (cached) return cached;
+
+  const rows = sprite.length;
+  const cols = sprite[0].length;
+  const canvas = document.createElement('canvas');
+  canvas.width = cols * zoom;
+  canvas.height = rows * zoom;
+  const ctx = canvas.getContext('2d')!;
+  ctx.imageSmoothingEnabled = false;
+
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const color = sprite[r][c];
+      if (color === '') continue;
+      ctx.fillStyle = color;
+      ctx.fillRect(c * zoom, r * zoom, zoom, zoom);
+    }
+  }
+
+  cache.set(sprite, canvas);
+  return canvas;
+}

package/agent/dashboard/src/pixel-engine/sprites/spriteData.ts

@@ -0,0 +1,176 @@
+import { adjustSprite } from '../colorize.js';
+import type { Direction, FloorColor, SpriteData } from '../types.js';
+import { Direction as Dir } from '../types.js';
+import bubblePermissionData from './bubble-permission.json';
+import bubbleWaitingData from './bubble-waiting.json';
+
+// ── Speech Bubble Sprites ───────────────────────────────────────
+
+interface BubbleSpriteJson {
+  palette: Record<string, string>;
+  pixels: string[][];
+}
+
+function resolveBubbleSprite(data: BubbleSpriteJson): SpriteData {
+  return data.pixels.map((row) => row.map((key) => data.palette[key] ?? key));
+}
+
+/** Permission bubble: white square with "..." in amber, and a tail pointer (11x13) */
+export const BUBBLE_PERMISSION_SPRITE: SpriteData = resolveBubbleSprite(bubblePermissionData);
+
+/** Waiting bubble: white square with green checkmark, and a tail pointer (11x13) */
+export const BUBBLE_WAITING_SPRITE: SpriteData = resolveBubbleSprite(bubbleWaitingData);
+
+// ════════════════════════════════════════════════════════════════
+// Loaded character sprites (from PNG assets)
+// ════════════════════════════════════════════════════════════════
+
+interface LoadedCharacterData {
+  down: SpriteData[];
+  up: SpriteData[];
+  right: SpriteData[];
+}
+
+let loadedCharacters: LoadedCharacterData[] | null = null;
+
+/** Set pre-colored character sprites loaded from PNG assets. Call this when characterSpritesLoaded message arrives. */
+export function setCharacterTemplates(data: LoadedCharacterData[]): void {
+  loadedCharacters = data;
+  // Clear cache so sprites are rebuilt from loaded data
+  spriteCache.clear();
+}
+
+/** Flip a SpriteData horizontally (for generating left sprites from right) */
+export function flipSpriteHorizontal(sprite: SpriteData): SpriteData {
+  return sprite.map((row) => [...row].reverse());
+}
+
+// ════════════════════════════════════════════════════════════════
+// Sprite resolution + caching
+// ════════════════════════════════════════════════════════════════
+
+export interface CharacterSprites {
+  walk: Record<Direction, [SpriteData, SpriteData, SpriteData, SpriteData]>;
+  typing: Record<Direction, [SpriteData, SpriteData]>;
+  reading: Record<Direction, [SpriteData, SpriteData]>;
+}
+
+const spriteCache = new Map<string, CharacterSprites>();
+
+/** Apply hue shift to every sprite in a CharacterSprites set */
+function hueShiftSprites(sprites: CharacterSprites, hueShift: number): CharacterSprites {
+  const color: FloorColor = { h: hueShift, s: 0, b: 0, c: 0 };
+  const shift = (s: SpriteData) => adjustSprite(s, color);
+  const shiftWalk = (
+    arr: [SpriteData, SpriteData, SpriteData, SpriteData],
+  ): [SpriteData, SpriteData, SpriteData, SpriteData] => [
+    shift(arr[0]),
+    shift(arr[1]),
+    shift(arr[2]),
+    shift(arr[3]),
+  ];
+  const shiftPair = (arr: [SpriteData, SpriteData]): [SpriteData, SpriteData] => [
+    shift(arr[0]),
+    shift(arr[1]),
+  ];
+  return {
+    walk: {
+      [Dir.DOWN]: shiftWalk(sprites.walk[Dir.DOWN]),
+      [Dir.UP]: shiftWalk(sprites.walk[Dir.UP]),
+      [Dir.RIGHT]: shiftWalk(sprites.walk[Dir.RIGHT]),
+      [Dir.LEFT]: shiftWalk(sprites.walk[Dir.LEFT]),
+    } as Record<Direction, [SpriteData, SpriteData, SpriteData, SpriteData]>,
+    typing: {
+      [Dir.DOWN]: shiftPair(sprites.typing[Dir.DOWN]),
+      [Dir.UP]: shiftPair(sprites.typing[Dir.UP]),
+      [Dir.RIGHT]: shiftPair(sprites.typing[Dir.RIGHT]),
+      [Dir.LEFT]: shiftPair(sprites.typing[Dir.LEFT]),
+    } as Record<Direction, [SpriteData, SpriteData]>,
+    reading: {
+      [Dir.DOWN]: shiftPair(sprites.reading[Dir.DOWN]),
+      [Dir.UP]: shiftPair(sprites.reading[Dir.UP]),
+      [Dir.RIGHT]: shiftPair(sprites.reading[Dir.RIGHT]),
+      [Dir.LEFT]: shiftPair(sprites.reading[Dir.LEFT]),
+    } as Record<Direction, [SpriteData, SpriteData]>,
+  };
+}
+
+/** Create a transparent placeholder sprite of given dimensions */
+function emptySprite(w: number, h: number): SpriteData {
+  const rows: string[][] = [];
+  for (let y = 0; y < h; y++) {
+    rows.push(new Array(w).fill(''));
+  }
+  return rows;
+}
+
+export function getCharacterSprites(paletteIndex: number, hueShift = 0): CharacterSprites {
+  const cacheKey = `${paletteIndex}:${hueShift}`;
+  const cached = spriteCache.get(cacheKey);
+  if (cached) return cached;
+
+  let sprites: CharacterSprites;
+
+  if (loadedCharacters) {
+    // Use pre-colored character sprites directly (no palette swapping)
+    const char = loadedCharacters[paletteIndex % loadedCharacters.length];
+    const d = char.down;
+    const u = char.up;
+    const rt = char.right;
+    const flip = flipSpriteHorizontal;
+
+    sprites = {
+      walk: {
+        [Dir.DOWN]: [d[0], d[1], d[2], d[1]],
+        [Dir.UP]: [u[0], u[1], u[2], u[1]],
+        [Dir.RIGHT]: [rt[0], rt[1], rt[2], rt[1]],
+        [Dir.LEFT]: [flip(rt[0]), flip(rt[1]), flip(rt[2]), flip(rt[1])],
+      },
+      typing: {
+        [Dir.DOWN]: [d[3], d[4]],
+        [Dir.UP]: [u[3], u[4]],
+        [Dir.RIGHT]: [rt[3], rt[4]],
+        [Dir.LEFT]: [flip(rt[3]), flip(rt[4])],
+      },
+      reading: {
+        [Dir.DOWN]: [d[5], d[6]],
+        [Dir.UP]: [u[5], u[6]],
+        [Dir.RIGHT]: [rt[5], rt[6]],
+        [Dir.LEFT]: [flip(rt[5]), flip(rt[6])],
+      },
+    };
+  } else {
+    // Fallback: return transparent placeholder sprites (16×32)
+    const e = emptySprite(16, 32);
+    const walkSet: [SpriteData, SpriteData, SpriteData, SpriteData] = [e, e, e, e];
+    const pairSet: [SpriteData, SpriteData] = [e, e];
+    sprites = {
+      walk: {
+        [Dir.DOWN]: walkSet,
+        [Dir.UP]: walkSet,
+        [Dir.RIGHT]: walkSet,
+        [Dir.LEFT]: walkSet,
+      },
+      typing: {
+        [Dir.DOWN]: pairSet,
+        [Dir.UP]: pairSet,
+        [Dir.RIGHT]: pairSet,
+        [Dir.LEFT]: pairSet,
+      },
+      reading: {
+        [Dir.DOWN]: pairSet,
+        [Dir.UP]: pairSet,
+        [Dir.RIGHT]: pairSet,
+        [Dir.LEFT]: pairSet,
+      },
+    };
+  }
+
+  // Apply hue shift if non-zero
+  if (hueShift !== 0) {
+    sprites = hueShiftSprites(sprites, hueShift);
+  }
+
+  spriteCache.set(cacheKey, sprites);
+  return sprites;
+}

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

@@ -0,0 +1,28 @@
+/** Map status prefixes back to tool names for animation selection */
+export const STATUS_TO_TOOL: Record<string, string> = {
+  Reading: 'Read',
+  Searching: 'Grep',
+  Globbing: 'Glob',
+  Fetching: 'WebFetch',
+  'Searching web': 'WebSearch',
+  Writing: 'Write',
+  Editing: 'Edit',
+  Running: 'Bash',
+  Task: 'Task',
+};
+
+export function extractToolName(status: string): string | null {
+  for (const [prefix, tool] of Object.entries(STATUS_TO_TOOL)) {
+    if (status.startsWith(prefix)) return tool;
+  }
+  const first = status.split(/[\s:]/)[0];
+  return first || null;
+}
+
+import { ZOOM_DEFAULT_DPR_FACTOR, ZOOM_MIN } from './constants.js';
+
+/** Compute a default integer zoom level (device pixels per sprite pixel) */
+export function defaultZoom(): number {
+  const dpr = window.devicePixelRatio || 1;
+  return Math.max(ZOOM_MIN, Math.round(ZOOM_DEFAULT_DPR_FACTOR * dpr));
+}

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

@@ -0,0 +1,232 @@
+export {
+  DEFAULT_COLS,
+  DEFAULT_ROWS,
+  MATRIX_EFFECT_DURATION_SEC as MATRIX_EFFECT_DURATION,
+  MAX_COLS,
+  MAX_ROWS,
+  TILE_SIZE,
+} from './constants.js';
+
+export const TileType = {
+  WALL: 0,
+  FLOOR_1: 1,
+  FLOOR_2: 2,
+  FLOOR_3: 3,
+  FLOOR_4: 4,
+  FLOOR_5: 5,
+  FLOOR_6: 6,
+  FLOOR_7: 7,
+  FLOOR_8: 8,
+  FLOOR_9: 9,
+  VOID: 255,
+} as const;
+export type TileType = (typeof TileType)[keyof typeof TileType];
+
+/** Per-tile color settings for floor pattern colorization */
+export interface FloorColor {
+  /** Hue: 0-360 in colorize mode, -180 to +180 in adjust mode */
+  h: number;
+  /** Saturation: 0-100 in colorize mode, -100 to +100 in adjust mode */
+  s: number;
+  /** Brightness -100 to 100 */
+  b: number;
+  /** Contrast -100 to 100 */
+  c: number;
+  /** When true, use Photoshop-style Colorize (grayscale → fixed HSL). Default: adjust mode. */
+  colorize?: boolean;
+}
+
+export const CharacterState = {
+  IDLE: 'idle',
+  WALK: 'walk',
+  TYPE: 'type',
+  SIT: 'sit',
+  INTERACT: 'interact',
+} as const;
+export type CharacterState = (typeof CharacterState)[keyof typeof CharacterState];
+
+export const Direction = {
+  DOWN: 0,
+  LEFT: 1,
+  RIGHT: 2,
+  UP: 3,
+} as const;
+export type Direction = (typeof Direction)[keyof typeof Direction];
+
+/** 2D array of hex color strings: '' = transparent, '#RRGGBB' = opaque, '#RRGGBBAA' = semi-transparent. [row][col] */
+export type SpriteData = string[][];
+
+export interface Seat {
+  /** Chair furniture uid */
+  uid: string;
+  /** Tile col where agent sits */
+  seatCol: number;
+  /** Tile row where agent sits */
+  seatRow: number;
+  /** Direction character faces when sitting (toward adjacent desk) */
+  facingDir: Direction;
+  assigned: boolean;
+  /** 'desk' = adjacent to a desk tile, 'lounge' = everything else */
+  kind: 'desk' | 'lounge';
+  /** Whether the adjacent desk has a PC surface item */
+  hasPc: boolean;
+  /** UID of the adjacent desk furniture, or null */
+  deskUid: string | null;
+}
+
+export interface FurnitureInstance {
+  sprite: SpriteData;
+  /** Pixel x (top-left) */
+  x: number;
+  /** Pixel y (top-left) */
+  y: number;
+  /** Y value used for depth sorting (typically bottom edge) */
+  zY: number;
+  /** Render-time horizontal flip flag (for mirrored side variants) */
+  mirrored?: boolean;
+}
+
+export interface ToolActivity {
+  toolId: string;
+  status: string;
+  done: boolean;
+  permissionWait?: boolean;
+}
+
+export const EditTool = {
+  TILE_PAINT: 'tile_paint',
+  WALL_PAINT: 'wall_paint',
+  FURNITURE_PLACE: 'furniture_place',
+  FURNITURE_PICK: 'furniture_pick',
+  SELECT: 'select',
+  EYEDROPPER: 'eyedropper',
+  ERASE: 'erase',
+} as const;
+export type EditTool = (typeof EditTool)[keyof typeof EditTool];
+
+export interface FurnitureCatalogEntry {
+  type: string; // asset ID from furniture manifest
+  label: string;
+  footprintW: number;
+  footprintH: number;
+  sprite: SpriteData;
+  isDesk: boolean;
+  category?: string;
+  /** Orientation from rotation group: 'front' | 'back' | 'left' | 'right' */
+  orientation?: string;
+  /** Whether this item can be placed on top of desk/table surfaces */
+  canPlaceOnSurfaces?: boolean;
+  /** Number of tile rows from the top of the footprint that are "background" (allow placement, still block walking). Default 0. */
+  backgroundTiles?: number;
+  /** Whether this item can be placed on wall tiles */
+  canPlaceOnWalls?: boolean;
+  /** Whether this is a side-oriented asset that produces a mirrored "left" variant */
+  mirrorSide?: boolean;
+  /** Whether idle bots can interact with this furniture */
+  interactable?: boolean;
+  /** Interaction type label */
+  interactAction?: string;
+  /** Valid approach sides: 'front' | 'back' | 'left' | 'right' | 'any'. Default ['front'] */
+  interactSides?: string[];
+}
+
+export interface PlacedFurniture {
+  uid: string;
+  type: string; // asset ID from furniture manifest
+  col: number;
+  row: number;
+  /** Optional color override for furniture */
+  color?: FloorColor;
+}
+
+export interface OfficeLayout {
+  version: 1;
+  cols: number;
+  rows: number;
+  tiles: TileType[];
+  furniture: PlacedFurniture[];
+  /** Per-tile color settings, parallel to tiles array. null = wall/no color */
+  tileColors?: Array<FloorColor | null>;
+  /** Bumped when the bundled default layout changes; forces a reset on existing installs */
+  layoutRevision?: number;
+}
+
+export interface Character {
+  id: number;
+  state: CharacterState;
+  dir: Direction;
+  /** Pixel position */
+  x: number;
+  y: number;
+  /** Current tile column */
+  tileCol: number;
+  /** Current tile row */
+  tileRow: number;
+  /** Remaining path steps (tile coords) */
+  path: Array<{ col: number; row: number }>;
+  /** 0-1 lerp between current tile and next tile */
+  moveProgress: number;
+  /** Current tool name for typing vs reading animation, or null */
+  currentTool: string | null;
+  /** Palette index (0-5) */
+  palette: number;
+  /** Hue shift in degrees (0 = no shift, ≥45 for repeated palettes) */
+  hueShift: number;
+  /** Animation frame index */
+  frame: number;
+  /** Time accumulator for animation */
+  frameTimer: number;
+  /** Timer for idle wander decisions */
+  wanderTimer: number;
+  /** Number of wander moves completed in current roaming cycle */
+  wanderCount: number;
+  /** Max wander moves before returning to seat for rest */
+  wanderLimit: number;
+  /** Whether the agent is actively working */
+  isActive: boolean;
+  /** Assigned seat uid, or null if no seat (legacy — use homeSeatId for new code) */
+  seatId: string | null;
+  /** Permanent home seat uid (rest cycle destination) */
+  homeSeatId: string | null;
+  /** Temporarily claimed PC desk seat uid while working */
+  workDeskId: string | null;
+  /** Chat partner character ID, or null */
+  chatPartner: number | null;
+  /** Chat countdown timer */
+  chatTimer: number;
+  /** Furniture interaction countdown timer */
+  interactTimer: number;
+  /** Furniture uid being interacted with, or null */
+  interactTarget: string | null;
+  /** SIT state countdown timer */
+  sitTimer: number;
+  /** Number of idle actions completed in current cycle */
+  idleActionCount: number;
+  /** Max idle actions before returning to home seat */
+  idleActionLimit: number;
+  /** Active speech bubble type, or null if none showing */
+  bubbleType: 'permission' | 'waiting' | null;
+  /** Countdown timer for bubble (waiting: 2→0, permission: unused) */
+  bubbleTimer: number;
+  /** Timer to stay seated while inactive after seat reassignment (counts down to 0) */
+  seatTimer: number;
+  /** Whether this character represents a sub-agent (spawned by Task tool) */
+  isSubagent: boolean;
+  /** Parent agent ID if this is a sub-agent, null otherwise */
+  parentAgentId: number | null;
+  /** Active matrix spawn/despawn effect, or null */
+  matrixEffect: 'spawn' | 'despawn' | null;
+  /** Timer counting up from 0 to MATRIX_EFFECT_DURATION */
+  matrixEffectTimer: number;
+  /** Per-column random seeds (16 values) for staggered rain timing */
+  matrixEffectSeeds: number[];
+  /** Workspace folder name (only set for multi-root workspaces) */
+  folderName?: string;
+}
+
+export interface SubagentCharacter {
+  id: number;
+  parentAgentId: number;
+  parentToolId: string;
+  label: string;
+}