@flyingrobots/bijou-tui 2.1.0 → 3.1.0

package/dist/css/resolver.js

@@ -0,0 +1,130 @@
+/**
+ * Resolves the final styles for a component based on a CSS sheet and terminal dimensions.
+ *
+ * @param identity - The component's identity (type, id, classes).
+ * @param sheet - The parsed BCSS sheet.
+ * @param terminal - Current terminal dimensions for media query matching.
+ * @param graph - The TokenGraph for resolving var() references.
+ * @param mode - The theme mode (light/dark).
+ * @returns A record of computed style properties.
+ */
+export function resolveStyles(identity, sheet, terminal, graph, mode = 'dark') {
+    const matchedRules = [];
+    // 1. Collect rules from main sheet
+    for (const rule of sheet.rules) {
+        const specificity = getMatchSpecificity(identity, rule.selectors);
+        if (specificity > 0) {
+            matchedRules.push({ rule, specificity });
+        }
+    }
+    // 2. Collect rules from active media queries
+    for (const mq of sheet.mediaQueries) {
+        if (matchesMediaQuery(mq.condition, terminal)) {
+            for (const rule of mq.rules) {
+                const specificity = getMatchSpecificity(identity, rule.selectors);
+                if (specificity > 0) {
+                    // Media query rules have slightly higher base priority in CSS
+                    matchedRules.push({ rule, specificity: specificity + 0.1 });
+                }
+            }
+        }
+    }
+    // 3. Sort by specificity (and then order of appearance)
+    matchedRules.sort((a, b) => a.specificity - b.specificity);
+    // 4. Merge declarations into final object
+    const finalStyles = {};
+    for (const { rule } of matchedRules) {
+        for (const decl of rule.declarations) {
+            // !important handling
+            if (decl.important || !isImportant(finalStyles, decl.property)) {
+                finalStyles[decl.property] = resolveValue(decl.value, graph, mode);
+                if (decl.important) {
+                    finalStyles[`__important_${decl.property}`] = 'true';
+                }
+            }
+        }
+    }
+    return finalStyles;
+}
+/**
+ * Resolve a CSS value, handling var(token.path) references via the TokenGraph.
+ */
+function resolveValue(value, graph, mode = 'dark') {
+    if (!graph)
+        return value;
+    // Simple regex for var(path.to.token)
+    const varRegex = /var\(([^)]+)\)/g;
+    return value.replace(varRegex, (_, path) => {
+        try {
+            // Try to get as full token first, then fallback to color
+            const resolved = graph.get(path.trim(), mode);
+            return resolved.hex;
+        }
+        catch {
+            return 'inherit'; // Fallback for unresolved vars
+        }
+    });
+}
+function isImportant(styles, property) {
+    return styles[`__important_${property}`] === 'true';
+}
+/**
+ * Calculate match specificity for a component identity against a set of selectors.
+ * Returns 0 if no match, otherwise a positive number representing specificity.
+ */
+function getMatchSpecificity(identity, selectors) {
+    let maxSpecificity = 0;
+    for (const selector of selectors) {
+        let match = true;
+        let specificity = 0;
+        // Type match
+        if (selector.type && selector.type !== '*') {
+            if (identity.type !== selector.type)
+                match = false;
+            specificity += 1;
+        }
+        // ID match
+        if (selector.id) {
+            if (identity.id !== selector.id)
+                match = false;
+            specificity += 100;
+        }
+        // Class match (all classes in selector must be present on component)
+        if (selector.classes.length > 0) {
+            for (const cls of selector.classes) {
+                if (!identity.classes?.includes(cls)) {
+                    match = false;
+                    break;
+                }
+            }
+            specificity += selector.classes.length * 10;
+        }
+        if (match) {
+            maxSpecificity = Math.max(maxSpecificity, specificity);
+        }
+    }
+    return maxSpecificity;
+}
+/**
+ * Evaluate a basic media query condition like "(width < 80)" or "(height >= 24)".
+ */
+export function matchesMediaQuery(condition, terminal) {
+    // Simple regex for (property op value)
+    const regex = /\((width|height)\s*(<|>|<=|>=|==|!=)\s*(\d+)\)/;
+    const match = condition.match(regex);
+    if (!match)
+        return false;
+    const property = match[1] === 'width' ? terminal.width : terminal.height;
+    const op = match[2];
+    const value = parseInt(match[3], 10);
+    switch (op) {
+        case '<': return property < value;
+        case '>': return property > value;
+        case '<=': return property <= value;
+        case '>=': return property >= value;
+        case '==': return property === value;
+        case '!=': return property !== value;
+        default: return false;
+    }
+}
+//# sourceMappingURL=resolver.js.map

package/dist/css/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/css/resolver.ts"],"names":[],"mappings":"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"}

package/dist/css/text-style.d.ts

@@ -0,0 +1,17 @@
+import type { BijouContext } from '@flyingrobots/bijou';
+export interface StyledTextToken {
+    hex?: string;
+    bg?: string;
+    modifiers?: string[];
+}
+export interface BCSSIdentity {
+    type: string;
+    id?: string;
+    classes?: string[];
+}
+type BCSSStyles = Record<string, string>;
+export declare function mergeBCSSModifiers(base: readonly string[] | undefined, styles: BCSSStyles): string[] | undefined;
+export declare function resolveBCSSTextToken(ctx: BijouContext, identity: BCSSIdentity, base?: StyledTextToken): StyledTextToken;
+export declare function styleTextWithBCSS(text: string, ctx: BijouContext | undefined, identity: BCSSIdentity, base?: StyledTextToken): string;
+export {};
+//# sourceMappingURL=text-style.d.ts.map

package/dist/css/text-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-style.d.ts","sourceRoot":"","sources":["../../src/css/text-style.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEzC,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACnC,MAAM,EAAE,UAAU,GACjB,MAAM,EAAE,GAAG,SAAS,CAoCtB;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,YAAY,EACtB,IAAI,GAAE,eAAoB,GACzB,eAAe,CAOjB;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,YAAY,GAAG,SAAS,EAC7B,QAAQ,EAAE,YAAY,EACtB,IAAI,GAAE,eAAoB,GACzB,MAAM,CAcR"}

package/dist/css/text-style.js

@@ -0,0 +1,59 @@
+export function mergeBCSSModifiers(base, styles) {
+    const modifiers = new Set(base ?? []);
+    const fontWeight = styles['font-weight']?.trim().toLowerCase();
+    if (fontWeight === 'bold' || fontWeight === '700' || fontWeight === '800' || fontWeight === '900') {
+        modifiers.add('bold');
+    }
+    else if (fontWeight === 'normal' || fontWeight === '400') {
+        modifiers.delete('bold');
+    }
+    const fontStyle = styles['font-style']?.trim().toLowerCase();
+    if (fontStyle === 'italic') {
+        modifiers.add('italic');
+    }
+    else if (fontStyle === 'normal') {
+        modifiers.delete('italic');
+    }
+    const decoration = styles['text-decoration']?.trim().toLowerCase();
+    if (decoration === 'none') {
+        modifiers.delete('underline');
+        modifiers.delete('curly-underline');
+        modifiers.delete('dotted-underline');
+        modifiers.delete('dashed-underline');
+        modifiers.delete('strikethrough');
+        modifiers.delete('strike');
+    }
+    else if (decoration) {
+        if (decoration.includes('underline')) {
+            modifiers.add('underline');
+        }
+        if (decoration.includes('line-through')) {
+            modifiers.add('strikethrough');
+            modifiers.delete('strike');
+        }
+    }
+    return modifiers.size > 0 ? Array.from(modifiers) : undefined;
+}
+export function resolveBCSSTextToken(ctx, identity, base = {}) {
+    const styles = ctx.resolveBCSS(identity);
+    return {
+        hex: styles['color'] ?? base.hex,
+        bg: styles['background'] ?? base.bg,
+        modifiers: mergeBCSSModifiers(base.modifiers, styles),
+    };
+}
+export function styleTextWithBCSS(text, ctx, identity, base = {}) {
+    if (!ctx)
+        return text;
+    const styles = ctx.resolveBCSS(identity);
+    const token = {
+        hex: styles['color'] ?? base.hex,
+        bg: styles['background'] ?? base.bg,
+        modifiers: mergeBCSSModifiers(base.modifiers, styles),
+    };
+    if (token.hex == null && token.bg == null && (token.modifiers == null || token.modifiers.length === 0)) {
+        return text;
+    }
+    return ctx.style.styled(token, text);
+}
+//# sourceMappingURL=text-style.js.map

package/dist/css/text-style.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-style.js","sourceRoot":"","sources":["../../src/css/text-style.ts"],"names":[],"mappings":"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"}

package/dist/css/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AST types for Bijou CSS (BCSS).
+ */
+export interface BCSSDeclaration {
+    property: string;
+    value: string;
+    important: boolean;
+}
+export interface BCSSSelector {
+    type?: string;
+    id?: string;
+    classes: string[];
+    raw: string;
+}
+export interface BCSSRule {
+    selectors: BCSSSelector[];
+    declarations: BCSSDeclaration[];
+}
+export interface BCSSMediaQuery {
+    condition: string;
+    rules: BCSSRule[];
+}
+export interface BCSSSheet {
+    rules: BCSSRule[];
+    mediaQueries: BCSSMediaQuery[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/css/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/css/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,YAAY,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,YAAY,EAAE,cAAc,EAAE,CAAC;CAChC"}

package/dist/css/types.js

@@ -0,0 +1,5 @@
+/**
+ * AST types for Bijou CSS (BCSS).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/css/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/css/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/driver.d.ts

@@ -16,6 +16,7 @@
  * ```
  */
 import type { App, RunOptions } from './types.js';
+import { type Surface } from '@flyingrobots/bijou';
 /** A single step in a scripted interaction sequence. */
 export type ScriptStep<M = never> = {
     /** Key to send (raw terminal key string, e.g., 'a', '\x1b[A', '\x03'). */
@@ -30,6 +31,13 @@ export type ScriptStep<M = never> = {
     };
     /** Milliseconds to wait before sending this step. Default: 0. */
     delay?: number;
+} | {
+    /** Pulse event to emit. */
+    pulse: {
+        dt: number;
+    };
+    /** Milliseconds to wait before sending this step. Default: 0. */
+    delay?: number;
 } | {
     /** Custom message to emit directly onto the bus. */
     msg: M;
@@ -39,7 +47,9 @@ export type ScriptStep<M = never> = {
 /** Options for {@link runScript}, extending the base {@link RunOptions}. */
 export interface RunScriptOptions extends RunOptions {
     /** Capture each rendered frame. */
-    onFrame?: (frame: string, index: number) => void;
+    onFrame?: (frame: Surface, index: number) => void;
+    /** Pulse frequency used to drive animation commands. Set to `false` to disable. */
+    pulseFps?: number | false;
 }
 /**
  * Result returned by {@link runScript} after all steps have been processed.
@@ -50,7 +60,7 @@ export interface RunScriptResult<Model> {
     /** Final model state after all steps. */
     model: Model;
     /** All rendered frames in order. */
-    frames: string[];
+    frames: Surface[];
     /** Total elapsed time in milliseconds. */
     elapsed: number;
 }
@@ -65,11 +75,8 @@ export interface RunScriptResult<Model> {
  * - A command returns QUIT
  * - All script steps are exhausted (auto-quits)
  *
- * **Limitation:** Between steps the driver yields via `queueMicrotask`,
- * which only settles microtask-based async (e.g. `Promise.resolve()`).
- * Commands that use `setTimeout`, real I/O, or other macrotask-based async
- * may not have completed before the next key is dispatched. Use `delay`
- * on subsequent steps to allow time for macrotask-based commands.
+ * Between steps the driver waits for the event bus to go idle, so command
+ * chains settle deterministically without relying on microtask-only yields.
  *
  * @template Model - The application model type.
  * @template M     - The message (action) type for the TEA update cycle.

package/dist/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAa,MAAM,YAAY,CAAC;AAQ7D,wDAAwD;AACxD,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,KAAK,IAC5B;IACA,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACC;IACA,4BAA4B;IAC5B,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACC;IACA,oDAAoD;IACpD,GAAG,EAAE,CAAC,CAAC;IACP,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEJ,4EAA4E;AAC5E,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,mCAAmC;IACnC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAClD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK;IACpC,yCAAyC;IACzC,KAAK,EAAE,KAAK,CAAC;IACb,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,CAAC,EACtC,GAAG,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAClB,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EACtB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAoFjC"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAa,MAAM,YAAY,CAAC;AAI7D,OAAO,EAAE,KAAK,OAAO,EAAuB,MAAM,qBAAqB,CAAC;AAQxE,wDAAwD;AACxD,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,KAAK,IAC5B;IACA,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACC;IACA,4BAA4B;IAC5B,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACC;IACA,2BAA2B;IAC3B,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACtB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACC;IACA,oDAAoD;IACpD,GAAG,EAAE,CAAC,CAAC;IACP,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEJ,4EAA4E;AAC5E,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,mCAAmC;IACnC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK;IACpC,yCAAyC;IACzC,KAAK,EAAE,KAAK,CAAC;IACb,oCAAoC;IACpC,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,CAAC,EACtC,GAAG,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAClB,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EACtB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CA2GjC"}

package/dist/driver.js

@@ -15,8 +15,12 @@
  * console.log(result.frames);  // all rendered frames
  * ```
  */
+import { isResizeMsg } from './types.js';
 import { createEventBus } from './eventbus.js';
 import { parseKey } from './keys.js';
+import { resolveClock, sleep } from '@flyingrobots/bijou';
+import { installBCSSResolver } from './css/install.js';
+import { normalizeViewOutput } from './view-output.js';
 // ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
@@ -31,11 +35,8 @@ import { parseKey } from './keys.js';
  * - A command returns QUIT
  * - All script steps are exhausted (auto-quits)
  *
- * **Limitation:** Between steps the driver yields via `queueMicrotask`,
- * which only settles microtask-based async (e.g. `Promise.resolve()`).
- * Commands that use `setTimeout`, real I/O, or other macrotask-based async
- * may not have completed before the next key is dispatched. Use `delay`
- * on subsequent steps to allow time for macrotask-based commands.
+ * Between steps the driver waits for the event bus to go idle, so command
+ * chains settle deterministically without relying on microtask-only yields.
  *
  * @template Model - The application model type.
  * @template M     - The message (action) type for the TEA update cycle.
@@ -45,12 +46,25 @@ import { parseKey } from './keys.js';
  * @returns The final model, all rendered frames, and elapsed time.
  */
 export async function runScript(app, steps, options) {
-    const start = Date.now();
+    const clock = resolveClock(options?.ctx);
+    const start = clock.now();
     const frames = [];
-    const bus = createEventBus();
+    const bus = createEventBus({ clock });
+    const ctx = options?.ctx;
+    if (ctx != null) {
+        installBCSSResolver(ctx, options?.css);
+    }
     const [initModel, initCmds] = app.init();
     let model = initModel;
     let running = true;
+    let currentSize = {
+        width: Math.max(0, Math.floor(ctx?.runtime.columns || 80)),
+        height: Math.max(0, Math.floor(ctx?.runtime.rows || 24)),
+    };
+    // Start heartbeat for animations when enabled.
+    if (options?.pulseFps !== false) {
+        bus.startPulse(options?.pulseFps ?? ctx?.runtime.refreshRate ?? 60);
+    }
     /** Stop the scripted driver event loop. */
     function shutdown() {
         running = false;
@@ -61,7 +75,13 @@ export async function runScript(app, steps, options) {
             return;
         const [newModel, cmds] = app.update(msg, model);
         model = newModel;
-        const frame = app.view(model);
+        if (isResizeMsg(msg)) {
+            currentSize = {
+                width: Math.max(0, msg.columns),
+                height: Math.max(0, msg.rows),
+            };
+        }
+        const frame = normalizeViewOutput(app.view(model), currentSize).surface;
         frames.push(frame);
         options?.onFrame?.(frame, frames.length - 1);
         for (const cmd of cmds) {
@@ -70,21 +90,20 @@ export async function runScript(app, steps, options) {
     });
     try {
         // Capture initial frame
-        const initFrame = app.view(model);
+        const initFrame = normalizeViewOutput(app.view(model), currentSize).surface;
         frames.push(initFrame);
         options?.onFrame?.(initFrame, 0);
         // Run init commands
         for (const cmd of initCmds) {
             bus.runCmd(cmd);
         }
-        // Yield so microtask-based init commands can settle
-        await new Promise((r) => queueMicrotask(r));
+        await bus.drain();
         // Feed script steps
         for (const step of steps) {
             if (!running)
                 break;
             if (step.delay && step.delay > 0) {
-                await new Promise((r) => setTimeout(r, step.delay));
+                await sleep(clock, step.delay);
             }
             if (!running)
                 break;
@@ -92,6 +111,9 @@ export async function runScript(app, steps, options) {
                 const keyMsg = parseKey(step.key);
                 bus.emit(keyMsg);
             }
+            else if ('pulse' in step) {
+                bus.emit({ type: 'pulse', dt: step.pulse.dt });
+            }
             else if ('resize' in step) {
                 const resizeMsg = {
                     type: 'resize',
@@ -107,19 +129,18 @@ export async function runScript(app, steps, options) {
                 const _exhaustive = step;
                 throw new Error(`runScript: unhandled script step variant: ${JSON.stringify(_exhaustive)}`);
             }
-            // Yield to allow async commands to settle
-            await new Promise((r) => queueMicrotask(r));
+            await bus.drain();
         }
-        // Final yield so any trailing commands can settle
-        await new Promise((r) => queueMicrotask(r));
+        await bus.drain();
     }
     finally {
+        bus.stopPulse();
         bus.dispose();
     }
     return {
         model,
         frames,
-        elapsed: Date.now() - start,
+        elapsed: clock.now() - start,
     };
 }
 //# sourceMappingURL=driver.js.map

package/dist/driver.js.map

@@ -1 +1 @@
-{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}

package/dist/eventbus.d.ts

@@ -25,14 +25,24 @@
  * ```
  */
 import type { IOPort } from '@flyingrobots/bijou';
-import type { Cmd, KeyMsg, MouseMsg, ResizeMsg } from './types.js';
+import { type ClockPort } from '@flyingrobots/bijou';
+import type { Cmd, KeyMsg, MouseMsg, PulseMsg, ResizeMsg } from './types.js';
 /**
  * Union of all message types the bus can carry — built-in key, resize,
- * mouse messages plus any app-defined custom message type.
+ * mouse, and pulse messages plus any app-defined custom message type.
  *
  * @template M - Application-defined custom message type.
  */
-export type BusMsg<M> = KeyMsg | ResizeMsg | MouseMsg | M;
+export type BusMsg<M> = KeyMsg | ResizeMsg | MouseMsg | PulseMsg | M;
+/**
+ * Middleware function for intercepting and modifying messages.
+ *
+ * Call `next(msg)` to continue the message chain. Omitting the call
+ * halts message propagation.
+ *
+ * @template M - Application-defined custom message type.
+ */
+export type Middleware<M> = (msg: BusMsg<M>, next: (msg: BusMsg<M>) => void) => void;
 /**
  * Centralized event bus that unifies all input sources into a single
  * typed event stream for TEA applications.
@@ -87,6 +97,33 @@ export interface EventBus<M> {
      * @returns A disposable that removes this quit handler.
      */
     onQuit(handler: () => void): Disposable;
+    /**
+     * Start the system animation heartbeat at the specified frequency.
+     * Emits `PulseMsg` to all subscribers.
+     *
+     * @param fps - Frames per second. Default: 60.
+     */
+    startPulse(fps?: number): void;
+    /** Stop the system animation heartbeat. */
+    stopPulse(): void;
+    /**
+     * Register a listener for the system heartbeat pulse.
+     *
+     * @param handler - Callback invoked every pulse with the time delta.
+     * @returns A disposable that removes this pulse listener.
+     */
+    onPulse(handler: (dt: number) => void): Disposable;
+    /**
+     * Register a middleware function to intercept or modify messages.
+     *
+     * Middleware are executed in the order they are registered.
+     *
+     * @param middleware - The middleware function.
+     * @returns A disposable that removes this middleware.
+     */
+    use(middleware: Middleware<M>): Disposable;
+    /** Resolve once all in-flight commands have settled. */
+    drain(): Promise<void>;
     /** Disconnect all sources and remove all subscribers. */
     dispose(): void;
 }
@@ -96,6 +133,8 @@ export interface CreateEventBusOptions {
     onCommandRejected?: (error: unknown) => void;
     /** Called to surface error messages (replaces direct `console.error` usage). */
     onError?: (message: string, error: unknown) => void;
+    /** Clock/scheduler override for deterministic command and pulse timing. */
+    clock?: ClockPort;
 }
 /** Handle for unsubscribing or disconnecting a resource. */
 interface Disposable {

package/dist/eventbus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eventbus.d.ts","sourceRoot":"","sources":["../src/eventbus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQnE;;;;;GAKG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB;;;;;;OAMG;IACH,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,UAAU,CAAC;IAElD;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE3B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,UAAU,CAAC;IAEjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE1B;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,UAAU,CAAC;IAExC,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrD;AAED,4DAA4D;AAC5D,UAAU,UAAU;IAClB,0DAA0D;IAC1D,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,qBAAqB,GAAG,QAAQ,CAAC,CAAC,CAAC,CA+HjF"}
+{"version":3,"file":"eventbus.d.ts","sourceRoot":"","sources":["../src/eventbus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQ7E;;;;;GAKG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,CAAC,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,KAAK,IAAI,CAAC;AAErF;;;;;GAKG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB;;;;;;OAMG;IACH,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,UAAU,CAAC;IAElD;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE3B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,UAAU,CAAC;IAEjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE1B;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,UAAU,CAAC;IAExC;;;;;OAKG;IACH,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B,2CAA2C;IAC3C,SAAS,IAAI,IAAI,CAAC;IAElB;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,UAAU,CAAC;IAEnD;;;;;;;OAOG;IACH,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC;IAE3C,wDAAwD;IACxD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD,2EAA2E;IAC3E,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,4DAA4D;AAC5D,UAAU,UAAU;IAClB,0DAA0D;IAC1D,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,qBAAqB,GAAG,QAAQ,CAAC,CAAC,CAAC,CAkQjF"}