@agentdeck/bridge 0.2.3 → 1.0.0

package/dist/pixoo/pixoo-renderer.js

@@ -19,11 +19,13 @@
  */
 import { State } from '../types.js';
 import { PASSIVE_OFFLINE_LABEL } from '@agentdeck/shared';
-import { hasOpenClawSession } from '@agentdeck/shared';
+import { hasOpenClawSession, foldCodexSessionsForDisplay } from '@agentdeck/shared';
+import { layoutOctopuses, layoutCloudCreatures, layoutOpenCodeCreatures, layoutAntigravityCreatures, } from '@agentdeck/shared';
 import { drawTextCentered } from './pixoo-font.js';
-import { COLORS, setPixel, blendPixel, glowPixel, lerpColor, drawOctopus, drawJellyfish, drawOpenCode, drawAntigravity, drawCrayfish, drawTetra, drawText, getOctopusPaletteForSession, getJellyfishPaletteForSession, getOpenCodePaletteForSession, getAntigravityPaletteForSession, } from './pixoo-sprites.js';
+import { COLORS, setPixel, blendPixel, glowPixel, lerpColor, drawOfficialDotGlyph, drawTetra, drawText, getOctopusPaletteForSession, getJellyfishPaletteForSession, getOpenCodePaletteForSession, getAntigravityPaletteForSession, } from './pixoo-sprites.js';
 import { blitWithCamera, quantizeCameraPixels, updateDirector, WORLD_SIZE, ACTIVE_SIZE, } from './pixoo-camera.js';
-import { MICRO_SIZE, microStatusBg, paintMicroGlyph, } from './micro-glyphs.js';
+import { MICRO_SIZE, paintTimeboxBeacon, } from './micro-glyphs.js';
+import { OFFICIAL_DOT_GLYPHS, OFFICIAL_DOT_GLYPH_SIZE, } from './official-dot-glyphs.generated.js';
 const W = WORLD_SIZE;
 const ACTIVE_OFFSET = (WORLD_SIZE - ACTIVE_SIZE) / 2; // 16
 // Track last render time for accurate dt calculation
@@ -48,25 +50,58 @@ const JELLYFISH_AGENTS = new Set(['codex-cli', 'codex-app']);
 const OPENCODE_AGENTS = new Set(['opencode']);
 /** Agent types drawn as the Antigravity peak/arc mark. */
 const ANTIGRAVITY_AGENTS = new Set(['antigravity']);
-// Y positions by state — idle nearly on sand, active higher up
-const IDLE_Y = 0.78; // just above sand line (sleeping on ground)
-const WORKING_Y = 0.42; // mid-water (working/starburst)
-const ASKING_Y = 0.38; // slightly higher (room for "?" bubble)
-function stateY(state) {
-    if (state === 'processing')
-        return WORKING_Y;
-    if (state === 'awaiting')
-        return ASKING_Y;
-    return IDLE_Y;
-}
-function stateYForType(state, creatureType) {
-    if (creatureType !== 'antigravity')
-        return stateY(state);
-    if (state === 'processing')
-        return 0.30;
-    if (state === 'awaiting')
-        return 0.48;
-    return 0.62;
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Vertical stratification per creature type, applied on top of the band's base
+ * Y. Each type keeps its own water layer so a mixed Claude+Codex+OpenCode tank
+ * stays readable: clouds ride near the surface while working and sink to answer,
+ * octopuses hold mid-water, and everything settles to the sand when idle.
+ *
+ * Mirror of `stateY(_:kind:baseY:)` in apple/AgentDeck/Daemon/Modules/PixooRenderer.swift.
+ */
+function stateYForType(state, creatureType, baseY) {
+    switch (creatureType) {
+        case 'octopus':
+            if (state === 'processing')
+                return clamp(baseY, 0.40, 0.54);
+            if (state === 'awaiting')
+                return clamp(baseY - 0.04, 0.35, 0.48);
+            return 0.80;
+        case 'jellyfish':
+            if (state === 'processing')
+                return clamp(baseY, 0.16, 0.28);
+            if (state === 'awaiting')
+                return clamp(baseY + 0.26, 0.52, 0.64);
+            return clamp(baseY + 0.40, 0.80, 0.82);
+        case 'opencode':
+            if (state === 'processing')
+                return clamp(baseY - 0.02, 0.20, 0.34);
+            if (state === 'awaiting')
+                return clamp(baseY + 0.22, 0.50, 0.62);
+            return clamp(baseY + 0.36, 0.79, 0.81);
+        case 'antigravity':
+            if (state === 'processing')
+                return clamp(baseY - 0.04, 0.16, 0.30);
+            if (state === 'awaiting')
+                return clamp(baseY + 0.22, 0.46, 0.54);
+            return clamp(baseY + 0.34, 0.56, 0.64);
+    }
+}
+function slotsForType(creatureType, count) {
+    switch (creatureType) {
+        case 'octopus': return layoutOctopuses(count);
+        case 'jellyfish': return layoutCloudCreatures(count);
+        case 'opencode': return layoutOpenCodeCreatures(count);
+        case 'antigravity': return layoutAntigravityCreatures(count);
+    }
+}
+const FALLBACK_SLOT = { x: 0.38, y: 0.42, scale: 1.0 };
+function slotAt(slots, index) {
+    if (slots.length === 0)
+        return FALLBACK_SLOT;
+    return slots[Math.min(index, slots.length - 1)];
 }
 /** Check if agent type gets a creature. */
 function isCreatureAgent(agentType) {
@@ -82,11 +117,15 @@ function creatureTypeFor(agentType) {
     return 'octopus';
 }
 function syncCreatures(sessions, stateEvent) {
-    // Determine which sessions are alive creature agents (octopus or jellyfish)
+    // Determine which sessions are alive creature agents (octopus or jellyfish).
+    // Codex rows fold by project first: each Claude Code rescue/stop-gate spawns a
+    // fresh codex thread, so without folding one workspace lights up 4-5 cloud
+    // marks at once. Octopus / opencode are NOT folded — running several of those
+    // against one project is a deliberate user pattern.
     const aliveCoding = [];
     if (sessions) {
-        for (const s of sessions) {
-            if (s.alive && s.agentType && isCreatureAgent(s.agentType)) {
+        for (const s of foldCodexSessionsForDisplay(sessions.filter(s => s.alive))) {
+            if (s.agentType && isCreatureAgent(s.agentType)) {
                 aliveCoding.push({ id: s.id, agentType: s.agentType, state: s.state ?? 'idle' });
             }
         }
@@ -106,22 +145,40 @@ function syncCreatures(sessions, stateEvent) {
             creatureInstances.delete(id);
         }
     }
+    // Each agent type owns an X band and wraps to a second/third row as it fills,
+    // so a mixed tank clusters by agent instead of interleaving along one line.
+    const typeCounts = new Map();
+    for (const s of aliveCoding) {
+        const t = creatureTypeFor(s.agentType);
+        typeCounts.set(t, (typeCounts.get(t) ?? 0) + 1);
+    }
+    const slotsByType = new Map();
+    for (const [type, count] of typeCounts)
+        slotsByType.set(type, slotsForType(type, count));
+    const typeIndices = new Map();
+    // Band base Y per session, kept so the `_primary` refresh below can re-derive
+    // its stratified Y from the band instead of compounding onto an already
+    // stratified worldY.
+    const baseYById = new Map();
     // Add/update creatures
     for (let i = 0; i < aliveCoding.length; i++) {
         const s = aliveCoding[i];
         const existing = creatureInstances.get(s.id);
         const sessionState = mapSessionState(s.state);
         const creatureType = creatureTypeFor(s.agentType);
-        // Uniformly distribute X positions to maximize spacing and prevent overlap
-        const x = aliveCoding.length === 1
-            ? (creatureType === 'antigravity' ? 0.68 : 0.38) // single session: type-native band
-            : 0.15 + (i / (aliveCoding.length - 1)) * 0.70;
+        const slotIndex = typeIndices.get(creatureType) ?? 0;
+        typeIndices.set(creatureType, slotIndex + 1);
+        const slot = slotAt(slotsByType.get(creatureType) ?? [], slotIndex);
+        const x = slot.x;
+        baseYById.set(s.id, slot.y);
+        const worldY = stateYForType(sessionState, creatureType, slot.y);
         if (existing) {
             existing.state = sessionState;
             existing.agentType = s.agentType;
             existing.creatureType = creatureType;
             existing.worldX = x; // Update X dynamically to maintain even spacing
-            existing.worldY = stateYForType(sessionState, creatureType);
+            existing.worldY = worldY;
+            existing.sizeScale = slot.scale;
         }
         else {
             creatureInstances.set(s.id, {
@@ -130,22 +187,28 @@ function syncCreatures(sessions, stateEvent) {
                 creatureType,
                 state: sessionState,
                 worldX: x,
-                worldY: stateYForType(sessionState, creatureType),
+                worldY,
                 phaseOffset: i * 5,
+                sizeScale: slot.scale,
             });
         }
     }
-    // Override primary session state from stateEvent (more precise than polling)
-    // Only when stateEvent is from a creature agent — daemon/openclaw report stale IDLE
+    // Refresh the synthetic `_primary` creature from stateEvent — it *is* the
+    // stateEvent, so this keeps it precise before the first sessions_list lands.
+    //
+    // Real sessions are deliberately left alone. stateEvent.sessionId can name a
+    // row that folding has already collapsed into a representative, and stamping
+    // that member's state onto the representative would downgrade a group the fold
+    // resolved to `processing` down to the one idle sibling the event came from.
+    // The sessions list is daemon-pushed and already carries per-session state.
     const aType = stateEvent?.agentType;
     const isCreature = isCreatureAgent(aType ?? '');
-    if (stateEvent && isCreature && aliveCoding.length > 0) {
-        const primaryId = aliveCoding[0].id;
-        const primary = creatureInstances.get(primaryId);
+    if (stateEvent && isCreature) {
+        const primary = creatureInstances.get('_primary');
         if (primary) {
             const st = simplifiedState(stateEvent.state ?? State.IDLE);
             primary.state = st;
-            primary.worldY = stateYForType(st, primary.creatureType);
+            primary.worldY = stateYForType(st, primary.creatureType, baseYById.get('_primary') ?? primary.worldY);
         }
     }
 }
@@ -474,7 +537,7 @@ function simplifiedState(state) {
 }
 // ===== Usage HUD Helpers =====
 /** Gauge bar color based on usage percentage. */
-function gaugeColor(pct, animFrame) {
+function gaugeColor(pct, animFrame, brand) {
     if (pct >= 90) {
         // Red with pulse
         const pulse = (Math.sin(animFrame * 0.2) + 1) * 0.3;
@@ -482,9 +545,7 @@ function gaugeColor(pct, animFrame) {
     }
     if (pct >= 70)
         return COLORS.stateAwaiting; // amber
-    if (pct >= 50)
-        return [0x00, 0xC8, 0xB4]; // teal
-    return COLORS.stateProcessing; // blue
+    return brand;
 }
 /** Pixoo HUD reset time: "1h23", "4d6", "59m". */
 export function formatResetDetailed(resetsAt) {
@@ -508,78 +569,155 @@ export function formatResetDetailed(resetsAt) {
         return `${hours}h`;
     return `${mins}m`;
 }
-/** Draw Usage HUD in screen space (bottom right, zoom-independent).
- *  Single row at rows 57-63:
- *    - 7d absent: full-width, right-aligned (original behavior)
- *    - 7d present: left half [0..30]=5h  |  right half [32..63]=7d
+/** Draw Usage HUD in screen space (bottom, zoom-independent).
+ *  Each provider uses the same seven-pixel band with its official creature
+ *  silhouette, full-height usage fill, percentage and reset countdown. When both are present Claude occupies
+ *  rows 50-56 and Codex rows 57-63; a lone provider stays on rows 57-63.
+ *  Primary/5h is the left zone and secondary/7d is the right zone.
+ *  When Codex only reports 7d, its subscription date occupies the otherwise
+ *  empty primary zone.
  */
 function drawUsageHUD(buf, usageEvent, animFrame) {
-    // Hide the HUD entirely when upstream flags the data as stale — otherwise
-    // an old "12%" frozen on-screen looks authoritative to the user even though
-    // the CLI daemon isn't live to produce a fresh fetch. Matches the collapse
-    // behavior on every other surface (macOS dashboard, plugin, Android, D200H).
-    if (!usageEvent || usageEvent.fiveHourPercent == null)
-        return;
-    if (usageEvent.usageStale === true)
+    if (!usageEvent)
         return;
-    const w = Math.sqrt(buf.length / 3);
-    const textY = w === 32 ? 26 : 58;
-    const bgTop = textY - 1;
-    const bgBot = textY + 5;
-    // Full-width dark base — hides sand/terrain at HUD rows regardless of camera zoom
-    for (let y = bgTop; y <= bgBot; y++) {
-        for (let x = 0; x < w; x++) {
-            blendPixel(buf, x, y, COLORS.black, 0.55);
-        }
+    const providers = [];
+    if (usageEvent.usageStale !== true && usageEvent.fiveHourPercent != null) {
+        providers.push({
+            glyph: 'claudeCode', brand: [255, 112, 76],
+            primary: { percent: usageEvent.fiveHourPercent, resetsAt: usageEvent.fiveHourResetsAt },
+            secondary: usageEvent.sevenDayPercent == null ? undefined : {
+                percent: usageEvent.sevenDayPercent, resetsAt: usageEvent.sevenDayResetsAt,
+            },
+        });
+    }
+    // A window counts as renderable only when it is both fresh AND carries a
+    // number. "Not stale but no percent" is a malformed frame, not a zero — the
+    // gauge must stay absent rather than draw an authoritative-looking 0%.
+    // Mirror of `freshCodexWindow` in apple/AgentDeck/Daemon/Modules/PixooRenderer.swift.
+    const freshCodexWindow = (w) => w && w.stale !== true && w.usedPercent != null
+        ? { percent: w.usedPercent, resetsAt: w.resetsAt }
+        : undefined;
+    const codexPrimaryWindow = freshCodexWindow(usageEvent.codexRateLimits?.primary);
+    const codexSecondaryWindow = freshCodexWindow(usageEvent.codexRateLimits?.secondary);
+    if (codexPrimaryWindow || codexSecondaryWindow) {
+        providers.push({
+            glyph: 'codex', brand: [126, 116, 255],
+            primary: codexPrimaryWindow,
+            secondary: codexSecondaryWindow,
+            subscriptionUntil: usageEvent.codexSubscriptionActiveUntil,
+        });
     }
+    if (providers.length === 0)
+        return;
     const timeColor = [0x60, 0x70, 0x80];
-    /** Render a zone: usage background fill + two-color text (pct + time). */
-    function renderZone(pctText, timeText, pct, leftX, rightX) {
-        const color = gaugeColor(pct, animFrame);
-        const zoneW = rightX - leftX + 1;
-        const fillW = Math.round(zoneW * Math.max(0, Math.min(100, pct)) / 100);
-        // Background fill proportional to usage
-        for (let y = bgTop; y <= bgBot; y++) {
-            for (let x = leftX; x < leftX + fillW; x++) {
-                blendPixel(buf, x, y, color, 0.35);
+    const firstY = providers.length > 1 ? 50 : 57;
+    function drawCreatureMarker(provider, rowY) {
+        const mask = OFFICIAL_DOT_GLYPHS[provider.glyph];
+        const sourceSize = OFFICIAL_DOT_GLYPH_SIZE;
+        // Sample the canonical square canvas instead of cropping its occupied
+        // bounds. Claude's source silhouette is intentionally wider than it is
+        // tall; cropping and stretching those bounds to 7x7 turns the robot into
+        // a square. The 9px slot leaves one physical LED on both sides.
+        const markerSize = 7;
+        const markerX = 1;
+        for (let dy = 0; dy < 7; dy++) {
+            const sy = Math.min(sourceSize - 1, Math.floor((dy + 0.5) * sourceSize / markerSize));
+            for (let dx = 0; dx < markerSize; dx++) {
+                const sx = Math.min(sourceSize - 1, Math.floor((dx + 0.5) * sourceSize / markerSize));
+                const alpha = mask[sy * sourceSize + sx];
+                if (alpha <= 16)
+                    continue;
+                const intensity = alpha >= 96 ? 1 : 0.56;
+                setPixel(buf, markerX + dx, rowY + dy, lerpColor(COLORS.black, provider.brand, intensity));
             }
         }
-        // Two-color text: time (dimmed) right-aligned, then pct (gauge color) to its left
-        if (timeText) {
-            drawText(buf, timeText, rightX, textY, timeColor);
-            const timeW = timeText.length * 4; // 3px glyph + 1px gap per char
-            drawText(buf, pctText, rightX - timeW, textY, color);
+    }
+    function fittedReset(resetsAt, pctText, zoneWidth) {
+        const detailed = formatResetDetailed(resetsAt);
+        if (!detailed)
+            return '';
+        const maxChars = Math.floor(zoneWidth / 4);
+        if (pctText.length + detailed.length <= maxChars)
+            return detailed;
+        const unit = detailed.match(/^(\d+)[dhm]/);
+        return unit ? `${unit[1]}${unit[0].at(-1)}` : detailed.slice(0, Math.max(0, maxChars - pctText.length));
+    }
+    function subscriptionDate(until) {
+        const value = until?.trim();
+        if (!value)
+            return '';
+        const iso = value.match(/^\d{4}-(\d{1,2})-(\d{1,2})/);
+        if (iso)
+            return `${Number(iso[1])}/${Number(iso[2])}`;
+        const compact = value.match(/^~?(\d{1,2})\/(\d{1,2})$/);
+        return compact ? `${Number(compact[1])}/${Number(compact[2])}` : '';
+    }
+    function drawCenteredLabel(text, leftX, rightX, rowY) {
+        if (!text)
+            return;
+        const textWidth = text.length * 4 - 1;
+        const startX = leftX + Math.max(0, Math.floor((rightX - leftX - textWidth) / 2));
+        drawText(buf, text, startX + textWidth, rowY + 1, timeColor);
+    }
+    function renderWindow(window, leftX, rightX, rowY, brand) {
+        const pct = Math.max(0, Math.min(100, window.percent));
+        const color = gaugeColor(pct, animFrame, brand);
+        const zoneWidth = rightX - leftX;
+        const fillWidth = Math.round(zoneWidth * pct / 100);
+        // TC001-style fill: the used portion is a dim full-height color field, so
+        // the gauge reads at a glance while bright text remains crisp above it.
+        for (let y = rowY; y < rowY + 7; y++) {
+            for (let x = leftX; x < leftX + fillWidth; x++)
+                blendPixel(buf, x, y, color, 0.24);
+        }
+        const pctText = `${Math.round(pct)}%`;
+        const resetText = fittedReset(window.resetsAt, pctText, zoneWidth);
+        if (resetText) {
+            drawText(buf, resetText, rightX, rowY + 1, timeColor);
+            drawText(buf, pctText, rightX - resetText.length * 4, rowY + 1, color);
         }
         else {
-            drawText(buf, pctText, rightX, textY, color);
+            drawText(buf, pctText, rightX, rowY + 1, color);
         }
     }
-    const pct5 = usageEvent.fiveHourPercent;
-    if (w === 32) {
-        // Single compact zone for 32x32 screens
-        const r5 = formatResetDetailed(usageEvent.fiveHourResetsAt);
-        renderZone(`${Math.round(pct5)}%`, r5, pct5, 0, 31);
-        return;
-    }
-    if (usageEvent.sevenDayPercent == null) {
-        // Single full-width zone
-        const r5 = formatResetDetailed(usageEvent.fiveHourResetsAt);
-        renderZone(`${Math.round(pct5)}%`, r5, pct5, 0, 63);
-        return;
-    }
-    // Two-column layout: [5h | 7d]
-    const pct7 = usageEvent.sevenDayPercent;
-    const r5 = formatResetDetailed(usageEvent.fiveHourResetsAt);
-    const r7 = formatResetDetailed(usageEvent.sevenDayResetsAt);
-    renderZone(`${Math.round(pct5)}%`, r5, pct5, 0, 30);
-    renderZone(`${Math.round(pct7)}%`, r7, pct7, 32, 63);
+    providers.forEach((provider, index) => {
+        const rowY = firstY + index * 7;
+        for (let y = rowY; y < rowY + 7; y++) {
+            for (let x = 0; x < 64; x++) {
+                blendPixel(buf, x, y, COLORS.black, 0.70);
+                blendPixel(buf, x, y, provider.brand, 0.08);
+            }
+        }
+        // A slightly denser identity dock lets the official mark join the same
+        // color band without placing quota fill behind the silhouette itself.
+        for (let y = rowY; y < rowY + 7; y++) {
+            for (let x = 0; x < 9; x++)
+                blendPixel(buf, x, y, provider.brand, 0.12);
+        }
+        drawCreatureMarker(provider, rowY);
+        if (provider.primary && provider.secondary) {
+            for (let y = rowY + 1; y < rowY + 6; y++)
+                blendPixel(buf, 36, y, provider.brand, 0.28);
+            renderWindow(provider.primary, 9, 36, rowY, provider.brand);
+            renderWindow(provider.secondary, 37, 64, rowY, provider.brand);
+        }
+        else if (!provider.primary && provider.secondary && subscriptionDate(provider.subscriptionUntil)) {
+            for (let y = rowY + 1; y < rowY + 6; y++)
+                blendPixel(buf, 36, y, provider.brand, 0.28);
+            drawCenteredLabel(subscriptionDate(provider.subscriptionUntil), 9, 36, rowY);
+            renderWindow(provider.secondary, 37, 64, rowY, provider.brand);
+        }
+        else {
+            const only = provider.primary ?? provider.secondary;
+            if (only)
+                renderWindow(only, 9, 64, rowY, provider.brand);
+        }
+    });
 }
 /**
- * Render the micro layout natively at 11×11 using hand-authored creature glyphs,
- * then nearest-scale into the `size`×`size` output. The Timebox Mini has 121 LEDs;
- * downscaling the 32×32 terrarium bottoms out at a fuzzy silhouette, so micro draws
- * a bold per-pixel glyph (octopus/jellyfish/opencode/crayfish) on a dark
- * status-color field. The device fetches `size=11` for a pixel-perfect 1:1 frame.
+ * Render the Timebox Mini's native 11×11 Agent Beacon, then nearest-scale into
+ * the requested output. A stable 9×9 official mark carries identity while the
+ * one-pixel perimeter rail alone carries state and motion.
  */
 function renderMicroFrame(outputBuf, size, animFrame, stateEvent, sessions, usagePct) {
     // Presence-driven SSOT: the crayfish renders iff the daemon emitted an
@@ -597,28 +735,19 @@ function renderMicroFrame(outputBuf, size, animFrame, stateEvent, sessions, usag
         : dominant?.state === 'awaiting' ? 'awaiting'
             : (dominant?.state === 'processing' || (!dominant && routing)) ? 'processing'
                 : 'idle';
-    // Build the native 11×11 frame: dark status field + bold creature glyph.
     const base = new Uint8Array(MICRO_SIZE * MICRO_SIZE * 3);
-    const bg = microStatusBg(aggregate, animFrame);
-    for (let i = 0; i < MICRO_SIZE * MICRO_SIZE; i++) {
-        base[i * 3] = bg[0];
-        base[i * 3 + 1] = bg[1];
-        base[i * 3 + 2] = bg[2];
-    }
-    const glyphState = dominant?.state === 'processing' ? 'working'
-        : dominant?.state === 'awaiting' ? 'asking'
-            : 'idle';
+    let creature = null;
     if (dominant) {
-        const creature = dominant.agentType === 'antigravity' ? 'antigravity'
-            : dominant.creatureType === 'jellyfish' ? 'jellyfish'
-                : dominant.creatureType === 'opencode' ? 'opencode'
-                    : 'octopus';
-        paintMicroGlyph(base, creature, glyphState, animFrame);
+        creature =
+            dominant.agentType === 'antigravity' ? 'antigravity'
+                : dominant.creatureType === 'jellyfish' ? 'jellyfish'
+                    : dominant.creatureType === 'opencode' ? 'opencode'
+                        : 'octopus';
     }
     else if (hasGateway) {
-        paintMicroGlyph(base, 'crayfish', routing ? 'working' : 'idle', animFrame);
+        creature = 'crayfish';
     }
-    // else: no creatures at all → the solid status field is the whole signal.
+    paintTimeboxBeacon(base, creature, aggregate, animFrame);
     // Scale the 11×11 base into the size×size output (1:1 when size === 11).
     for (let y = 0; y < size; y++) {
         const sy = Math.min(MICRO_SIZE - 1, Math.floor((y * MICRO_SIZE) / size));
@@ -632,12 +761,133 @@ function renderMicroFrame(outputBuf, size, animFrame, stateEvent, sessions, usag
         }
     }
 }
+/** Native 32×32 iDotMatrix identity stage. The panel gets saturated official
+ * marks on a quiet field plus four fixed telemetry rails; no 64px scene is
+ * downsampled, so cutouts remain physical pixels. */
+function renderCompact32Frame(outputBuf, animFrame, stateEvent, sessions, usageEvent) {
+    const set = (x, y, color) => setPixel(outputBuf, x, y, color);
+    const state = String(stateEvent?.state ?? State.IDLE);
+    for (let y = 0; y < 28; y++) {
+        const t = y / 27;
+        const color = [2 + Math.round(5 * t), 7 + Math.round(10 * t), 18 + Math.round(18 * t)];
+        for (let x = 0; x < 32; x++)
+            set(x, y, color);
+    }
+    const surface = state.startsWith('awaiting') ? [255, 190, 45]
+        : state === 'processing' ? [50, 225, 255] : [38, 210, 145];
+    for (let x = 0; x < 32; x++) {
+        if ((x + Math.floor(animFrame / 4)) % (state === 'processing' ? 3 : 6) === 0)
+            set(x, 2, surface);
+    }
+    const glyphFor = (kind) => kind === 'jellyfish' ? 'codex' : kind === 'opencode' ? 'openCode'
+        : kind === 'antigravity' ? 'antigravity' : 'claudeCode';
+    const priority = (s) => s === 'awaiting' ? 0 : s === 'processing' ? 1 : 2;
+    const marks = [...creatureInstances.values()].map((c) => ({ glyph: glyphFor(c.creatureType), state: c.state }));
+    if (hasOpenClawSession(sessions ?? [])) {
+        const routing = sessions?.some((s) => s.agentType === 'openclaw' && s.state === 'processing') ?? false;
+        marks.push({ glyph: 'openClaw', state: routing ? 'processing' : 'idle' });
+    }
+    marks.sort((a, b) => priority(a.state) - priority(b.state));
+    marks.splice(3);
+    const slots = marks.length === 1 ? [{ x: 16, y: 14, size: 18 }]
+        : marks.length === 2 ? [{ x: 9, y: 14, size: 13 }, { x: 23, y: 14, size: 13 }]
+            : [{ x: 6, y: 14, size: 10 }, { x: 16, y: 14, size: 10 }, { x: 26, y: 14, size: 10 }];
+    const antigravityBands = [
+        [92, 214, 77], [245, 203, 36], [255, 132, 16], [255, 82, 65],
+        [183, 92, 182], [102, 111, 225], [36, 126, 255],
+    ];
+    const baseColor = (glyph, sx) => {
+        if (glyph === 'claudeCode')
+            return [255, 112, 76];
+        if (glyph === 'codex')
+            return [126, 116, 255];
+        if (glyph === 'openCode')
+            return [255, 246, 248];
+        if (glyph === 'openClaw')
+            return [255, 67, 84];
+        return antigravityBands[Math.min(antigravityBands.length - 1, Math.floor(sx * antigravityBands.length / OFFICIAL_DOT_GLYPH_SIZE))];
+    };
+    marks.forEach((mark, index) => {
+        const slot = slots[index];
+        const mask = OFFICIAL_DOT_GLYPHS[mark.glyph];
+        const bob = mark.state === 'processing' ? Math.round(Math.sin((animFrame + index * 5) * 0.28)) : 0;
+        const x0 = slot.x - Math.floor(slot.size / 2);
+        const y0 = slot.y - Math.floor(slot.size / 2) + bob;
+        for (let dy = 0; dy < slot.size; dy++) {
+            const sy = Math.min(OFFICIAL_DOT_GLYPH_SIZE - 1, Math.floor(dy * OFFICIAL_DOT_GLYPH_SIZE / slot.size));
+            for (let dx = 0; dx < slot.size; dx++) {
+                const sx = Math.min(OFFICIAL_DOT_GLYPH_SIZE - 1, Math.floor(dx * OFFICIAL_DOT_GLYPH_SIZE / slot.size));
+                const alpha = mask[sy * OFFICIAL_DOT_GLYPH_SIZE + sx] / 255;
+                if (alpha <= 0.04)
+                    continue;
+                const color = baseColor(mark.glyph, sx);
+                blendPixel(outputBuf, x0 + dx + 1, y0 + dy + 1, [0, 0, 0], alpha * 0.55);
+                if (alpha > 0.42) {
+                    blendPixel(outputBuf, x0 + dx - 1, y0 + dy, color, 0.055);
+                    blendPixel(outputBuf, x0 + dx + 1, y0 + dy, color, 0.055);
+                }
+                const coverage = Math.min(1, Math.pow(alpha, 0.72) * 1.12);
+                const light = 1.08 - dy / Math.max(1, slot.size - 1) * 0.12;
+                const lit = [
+                    Math.min(255, Math.round(color[0] * light)),
+                    Math.min(255, Math.round(color[1] * light)),
+                    Math.min(255, Math.round(color[2] * light)),
+                ];
+                blendPixel(outputBuf, x0 + dx, y0 + dy, lit, coverage);
+            }
+        }
+        if (mark.glyph === 'openClaw') {
+            set(x0 + Math.round(9.05 / 24 * slot.size), y0 + Math.round(7.63 / 24 * slot.size), [0, 229, 204]);
+            set(x0 + Math.round(15.38 / 24 * slot.size), y0 + Math.round(7.63 / 24 * slot.size), [0, 229, 204]);
+        }
+        if (mark.state === 'processing') {
+            for (let spark = 0; spark < 3; spark++) {
+                const angle = animFrame * 0.24 + spark * Math.PI * 2 / 3;
+                const radius = slot.size / 2 + 1;
+                set(Math.round(slot.x + Math.cos(angle) * radius), Math.round(slot.y + bob + Math.sin(angle) * radius), [110, 235, 255]);
+            }
+        }
+        else if (mark.state === 'awaiting') {
+            set(Math.min(31, x0 + slot.size), Math.max(2, y0), [255, 190, 45]);
+            set(Math.min(31, x0 + slot.size), Math.max(2, y0 + 1), [255, 190, 45]);
+        }
+    });
+    if (marks.length === 0) {
+        for (const [x, y] of [[14, 12], [15, 11], [16, 12], [17, 11], [18, 12], [15, 14], [16, 15], [17, 14]]) {
+            set(x, y, [76, 206, 220]);
+        }
+    }
+    const primary = usageEvent?.codexRateLimits?.primary?.stale === true
+        ? undefined : usageEvent?.codexRateLimits?.primary?.usedPercent;
+    const secondary = usageEvent?.codexRateLimits?.secondary?.stale === true
+        ? undefined : usageEvent?.codexRateLimits?.secondary?.usedPercent;
+    const telemetry = [
+        [usageEvent?.fiveHourPercent, [42, 220, 154]],
+        [usageEvent?.sevenDayPercent, [54, 154, 255]],
+        [primary, [185, 86, 255]],
+        [secondary, [104, 116, 255]],
+    ];
+    telemetry.forEach(([raw, brand], row) => {
+        const y = 28 + row;
+        for (let x = 0; x < 32; x++)
+            set(x, y, [5, 8, 14]);
+        if (raw == null)
+            return;
+        const pct = Math.max(0, Math.min(100, raw));
+        const color = pct >= 90 ? [255, 58, 72] : pct >= 70 ? [255, 183, 38] : brand;
+        set(0, y, brand);
+        set(1, y, brand);
+        const width = Math.round(pct / 100 * 29);
+        for (let x = 3; x < 3 + width; x++)
+            set(x, y, color);
+    });
+}
 /**
  * Render a complete frame with camera system.
  * Returns RGB buffer.
  *
- * `layout='micro'` renders a single dominant creature on a status field for
- * tiny screens (Timebox Mini 11×11); `'standard'` is the full terrarium.
+ * `layout='micro'` renders the Timebox Mini Agent Beacon;
+ * `'standard'` is the full terrarium.
  */
 export function renderFrame(stateEvent, usageEvent, sessions, timeOverrideMs, size = 64, layout = 'standard') {
     const worldBuf = new Uint8Array(W * W * 3);
@@ -649,6 +899,11 @@ export function renderFrame(stateEvent, usageEvent, sessions, timeOverrideMs, si
         renderMicroFrame(outputBuf, size, animFrame, stateEvent, sessions, usageEvent?.fiveHourPercent ?? 0);
         return outputBuf;
     }
+    if (size === 32) {
+        syncCreatures(sessions, stateEvent);
+        renderCompact32Frame(outputBuf, animFrame, stateEvent, sessions, usageEvent);
+        return outputBuf;
+    }
     const state = stateEvent?.state ?? State.IDLE;
     const usagePct = usageEvent?.fiveHourPercent ?? 0;
     const surfaceY = SURFACE_Y;
@@ -757,23 +1012,16 @@ export function renderFrame(stateEvent, usageEvent, sessions, timeOverrideMs, si
         const spriteState = c.state === 'processing' ? 'working'
             : c.state === 'awaiting' ? 'asking'
                 : 'idle'; // IDLE → idle (limbs move, body color preserved)
-        if (c.creatureType === 'jellyfish') {
-            drawJellyfish(outputBuf, c.worldX, c.worldY, spriteState, animFrame + c.phaseOffset, camera, getJellyfishPaletteForSession(sessionToneIndex));
-        }
-        else if (c.creatureType === 'opencode') {
-            drawOpenCode(outputBuf, c.worldX, c.worldY, spriteState, animFrame + c.phaseOffset, camera, getOpenCodePaletteForSession(sessionToneIndex));
-        }
-        else if (c.creatureType === 'antigravity') {
-            drawAntigravity(outputBuf, c.worldX, c.worldY, spriteState, animFrame + c.phaseOffset, camera, getAntigravityPaletteForSession(sessionToneIndex));
-        }
-        else {
-            drawOctopus(outputBuf, c.worldX, c.worldY, spriteState, animFrame + c.phaseOffset, camera, getOctopusPaletteForSession(sessionToneIndex));
-        }
+        const glyph = c.creatureType === 'jellyfish' ? 'codex'
+            : c.creatureType === 'opencode' ? 'openCode'
+                : c.creatureType === 'antigravity' ? 'antigravity'
+                    : 'claudeCode';
+        drawOfficialDotGlyph(outputBuf, glyph, c.worldX, c.worldY, spriteState, animFrame + c.phaseOffset, camera, sessionToneIndex, c.sizeScale);
     }
     // Crayfish — always drawn when gateway available; IDLE = sitting (subtle breathing only)
     if (hasGateway) {
         const gatewayHasError = stateEvent?.gatewayHasError ?? false;
-        drawCrayfish(outputBuf, cfX, cfY, crayfishRouting, animFrame, camera, gatewayHasError);
+        drawOfficialDotGlyph(outputBuf, 'openClaw', cfX, cfY, crayfishRouting ? 'working' : 'idle', animFrame, camera, 0, 1.0, gatewayHasError);
     }
     // ========================================
     // Phase 4: Screen-space overlays
@@ -820,6 +1068,27 @@ export function renderDisconnectedFrame() {
     return buf;
 }
 // ===== Preview API (re-export camera controls) =====
+/**
+ * Introspection seam: the creature set `renderFrame` would draw for this input,
+ * without rasterizing anything. Counting marks back out of a 64×64 buffer is
+ * far too fragile to assert on, so tests and the preview CLI read the resolved
+ * world placement from here instead.
+ *
+ * This runs the same `syncCreatures` the renderer runs, so it mutates the module's
+ * creature state exactly as a real frame would.
+ */
+export function getCreatureLayoutSnapshot(sessions, stateEvent) {
+    syncCreatures(sessions, stateEvent);
+    return [...creatureInstances.values()].map(c => ({
+        sessionId: c.sessionId,
+        agentType: c.agentType,
+        creatureType: c.creatureType,
+        state: c.state,
+        worldX: c.worldX,
+        worldY: c.worldY,
+        sizeScale: c.sizeScale,
+    }));
+}
 export { setZone, setOverride, resetDirector } from './pixoo-camera.js';
 export { ZONES } from './pixoo-camera.js';
 //# sourceMappingURL=pixoo-renderer.js.map