@flyingrobots/bijou-tui 1.8.0 → 3.0.0

package/dist/runtime.js

@@ -1,12 +1,18 @@
-import { getDefaultContext } from '@flyingrobots/bijou';
-import { isKeyMsg } from './types.js';
-import { enterScreen, exitScreen, renderFrame } from './screen.js';
+import { getDefaultContext, createSurface, surfaceToString } from '@flyingrobots/bijou';
+import { isKeyMsg, isPulseMsg, isResizeMsg } from './types.js';
+import { clearAndHome, enterScreen, exitScreen, renderSurfaceFrame } from './screen.js';
 import { createEventBus } from './eventbus.js';
+import { createPipeline } from './pipeline/pipeline.js';
+import { bcssMiddleware } from './pipeline/middleware/css.js';
+import { motionMiddleware } from './pipeline/middleware/motion.js';
+import { paintMiddleware } from './pipeline/middleware/paint.js';
+import { installBCSSResolver } from './css/install.js';
+import { normalizeViewOutput, wrapViewOutputAsLayoutRoot } from './view-output.js';
 /**
  * Disable mouse reporting sequences that terminals may send.
  * Some terminals auto-enable mouse tracking in alt screen mode.
  */
-const DISABLE_MOUSE = '\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l';
+const DISABLE_MOUSE = '\x1b[?1000l\x1b[?1002l\x1b[?1006l';
 /**
  * Enable SGR mouse reporting.
  * 1000 = basic press/release, 1002 = button-event tracking (drag),
@@ -31,13 +37,27 @@ const ENABLE_MOUSE = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
  */
 export async function run(app, options) {
     const ctx = options?.ctx ?? getDefaultContext();
+    installRuntimeOverlay(ctx);
     const useAltScreen = options?.altScreen ?? true;
     const useHideCursor = options?.hideCursor ?? true;
     const useMouse = options?.mouse ?? false;
+    installBCSSResolver(ctx, options?.css);
     const [initModel, initCmds] = app.init();
     // Non-interactive: render once and return
     if (ctx.mode !== 'interactive') {
-        ctx.io.write(app.view(initModel));
+        const viewOutput = app.view(initModel);
+        let output;
+        if (typeof viewOutput === 'string') {
+            output = viewOutput;
+        }
+        else {
+            const normalized = normalizeViewOutput(viewOutput, {
+                width: sanitizeDimension(ctx.runtime.columns),
+                height: sanitizeDimension(ctx.runtime.rows),
+            });
+            output = surfaceToString(normalized.surface, ctx.style);
+        }
+        ctx.io.write(output);
         return;
     }
     // Interactive mode
@@ -45,6 +65,10 @@ export async function run(app, options) {
     let running = true;
     let lastCtrlC = 0;
     let resolveQuit = null;
+    let currentDt = 0.016; // Default to 60fps for first frame
+    let fatalError = null;
+    // Double Buffering: track what is currently on screen
+    let currentSurface = createSurface(sanitizeDimension(ctx.runtime.columns), sanitizeDimension(ctx.runtime.rows));
     const bus = createEventBus({
         onCommandRejected(error) {
             const message = error instanceof Error
@@ -53,8 +77,46 @@ export async function run(app, options) {
             writeErrorLine(ctx.io, `[EventBus] Command rejected: ${message}\n`);
         },
     });
+    // Setup Programmable Rendering Pipeline
+    const pipeline = createPipeline();
+    // 1. Layout Logic Stage
+    pipeline.use('Layout', (state, next) => {
+        const viewOutput = app.view(state.model);
+        state.layoutRoot = wrapViewOutputAsLayoutRoot(viewOutput, {
+            width: sanitizeDimension(ctx.runtime.columns),
+            height: sanitizeDimension(ctx.runtime.rows),
+        });
+        next();
+    });
+    // 2. Motion Interpolation Stage
+    pipeline.use('Layout', motionMiddleware());
+    if (options?.css) {
+        pipeline.use('Layout', bcssMiddleware(options.css));
+    }
+    // 3. Paint Stage
+    pipeline.use('Paint', paintMiddleware());
+    // Add default Diff stage (double-buffering)
+    pipeline.use('Diff', (state, next) => {
+        renderSurfaceFrame(state.ctx.io, state.currentSurface, state.targetSurface, state.ctx.style);
+        next();
+    });
+    // Add default Output stage (sync current surface)
+    pipeline.use('Output', (state, next) => {
+        currentSurface = state.targetSurface.clone();
+        next();
+    });
+    options?.configurePipeline?.(pipeline);
+    // Register user middleware
+    if (options?.middlewares) {
+        for (const mw of options.middlewares) {
+            bus.use(mw);
+        }
+    }
     /** Tear down the run loop and signal the quit promise. */
-    function shutdown() {
+    function shutdown(error) {
+        if (error !== undefined && fatalError === null) {
+            fatalError = error;
+        }
         if (!running)
             return;
         running = false;
@@ -72,11 +134,34 @@ export async function run(app, options) {
         ctx.io.write(DISABLE_MOUSE);
     }
     // Render helper
+    let renderRequested = false;
     /** Render the current model's view to the terminal. */
     function render() {
-        if (!running)
+        if (!running || renderRequested)
             return;
-        renderFrame(ctx.io, app.view(model));
+        renderRequested = true;
+        setTimeout(() => {
+            try {
+                const targetSurface = createSurface(sanitizeDimension(ctx.runtime.columns), sanitizeDimension(ctx.runtime.rows));
+                const renderState = {
+                    model,
+                    ctx,
+                    dt: currentDt,
+                    currentSurface,
+                    targetSurface,
+                    layoutMap: new Map(),
+                    data: {},
+                };
+                pipeline.execute(renderState);
+            }
+            catch (error) {
+                writeErrorLine(ctx.io, `[Runtime Error] ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+                shutdown(error);
+            }
+            finally {
+                renderRequested = false;
+            }
+        }, 0);
     }
     // Execute commands through the bus
     /** Submit TEA commands to the event bus for async execution. */
@@ -89,10 +174,22 @@ export async function run(app, options) {
     bus.connectIO(ctx.io, { mouse: useMouse });
     // Handle quit signals from commands
     bus.onQuit(shutdown);
+    // Start heartbeat for animations
+    bus.startPulse(ctx.runtime.refreshRate);
     // Single subscription drives the entire update cycle
     bus.on((msg) => {
         if (!running)
             return;
+        // Track time delta from pulse
+        if (isPulseMsg(msg)) {
+            currentDt = msg.dt;
+        }
+        if (isResizeMsg(msg)) {
+            ctx.runtime.columns = sanitizeDimension(msg.columns);
+            ctx.runtime.rows = sanitizeDimension(msg.rows);
+            currentSurface = createSurface(ctx.runtime.columns, ctx.runtime.rows);
+            clearAndHome(ctx.io);
+        }
         // Double Ctrl+C force-quit
         if (isKeyMsg(msg) && msg.key === 'c' && msg.ctrl) {
             const now = Date.now();
@@ -116,6 +213,9 @@ export async function run(app, options) {
     };
     const [resizedModel, resizeCmds] = app.update(initialResize, model);
     model = resizedModel;
+    // After a potential resize in update, ensure currentSurface matches size
+    // to avoid diffing mismatched grids.
+    currentSurface = createSurface(sanitizeDimension(ctx.runtime.columns), sanitizeDimension(ctx.runtime.rows));
     // Initial render + startup commands
     render();
     executeCommands(initCmds);
@@ -126,7 +226,14 @@ export async function run(app, options) {
         if (!running)
             resolve();
     });
+    // Ensure any pending render is flushed before exiting
+    if (renderRequested) {
+        await new Promise((resolve) => {
+            setTimeout(resolve, 0);
+        });
+    }
     // Cleanup — bus disposes all I/O connections
+    bus.stopPulse();
     bus.dispose();
     if (useMouse) {
         ctx.io.write(DISABLE_MOUSE);
@@ -134,6 +241,9 @@ export async function run(app, options) {
     if (useAltScreen || useHideCursor) {
         exitScreen(ctx.io);
     }
+    if (fatalError != null) {
+        throw fatalError instanceof Error ? fatalError : new Error(String(fatalError));
+    }
 }
 /** Clamp a terminal dimension to a non-negative integer. */
 function sanitizeDimension(value) {
@@ -141,6 +251,41 @@ function sanitizeDimension(value) {
         return 0;
     return Math.max(0, Math.floor(value));
 }
+function installRuntimeOverlay(ctx) {
+    const baseRuntime = ctx.runtime;
+    const state = {
+        columns: sanitizeDimension(baseRuntime.columns),
+        rows: sanitizeDimension(baseRuntime.rows),
+    };
+    const runtime = {
+        env(key) {
+            return baseRuntime.env(key);
+        },
+        get stdoutIsTTY() {
+            return baseRuntime.stdoutIsTTY;
+        },
+        get stdinIsTTY() {
+            return baseRuntime.stdinIsTTY;
+        },
+        get columns() {
+            return state.columns;
+        },
+        set columns(value) {
+            state.columns = sanitizeDimension(value);
+        },
+        get rows() {
+            return state.rows;
+        },
+        set rows(value) {
+            state.rows = sanitizeDimension(value);
+        },
+        get refreshRate() {
+            return baseRuntime.refreshRate;
+        },
+    };
+    ctx.runtime = runtime;
+    return runtime;
+}
 /** Write an error message to stderr if available, otherwise stdout. */
 function writeErrorLine(io, data) {
     if (io.writeError != null) {

package/dist/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;GAGG;AACH,MAAM,aAAa,GAAG,8CAA8C,CAAC;AAErE;;;;GAIG;AACH,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,GAAkB,EAClB,OAAoB;IAEpB,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,iBAAiB,EAAE,CAAC;IAChD,MAAM,YAAY,GAAG,OAAO,EAAE,SAAS,IAAI,IAAI,CAAC;IAChD,MAAM,aAAa,GAAG,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC;IAClD,MAAM,QAAQ,GAAG,OAAO,EAAE,KAAK,IAAI,KAAK,CAAC;IAEzC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAEzC,0CAA0C;IAC1C,IAAI,GAAG,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QAC/B,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QAClC,OAAO;IACT,CAAC;IAED,mBAAmB;IACnB,IAAI,KAAK,GAAG,SAAS,CAAC;IACtB,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,WAAW,GAAwB,IAAI,CAAC;IAE5C,MAAM,GAAG,GAAG,cAAc,CAAI;QAC5B,iBAAiB,CAAC,KAAK;YACrB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK;gBACpC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE;gBACnC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAClB,cAAc,CAAC,GAAG,CAAC,EAAE,EAAE,gCAAgC,OAAO,IAAI,CAAC,CAAC;QACtE,CAAC;KACF,CAAC,CAAC;IAEH,0DAA0D;IAC1D,SAAS,QAAQ;QACf,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,OAAO,GAAG,KAAK,CAAC;QAChB,IAAI,WAAW;YAAE,WAAW,EAAE,CAAC;IACjC,CAAC;IAED,eAAe;IACf,IAAI,YAAY,IAAI,aAAa,EAAE,CAAC;QAClC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACb,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC7B,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAC9B,CAAC;IAED,gBAAgB;IAChB,uDAAuD;IACvD,SAAS,MAAM;QACb,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,mCAAmC;IACnC,gEAAgE;IAChE,SAAS,eAAe,CAAC,IAAc;QACrC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,qFAAqF;IACrF,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE3C,oCAAoC;IACpC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAErB,qDAAqD;IACrD,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,EAAE;QACb,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,2BAA2B;QAC3B,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YACjD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,IAAI,GAAG,GAAG,SAAS,GAAG,IAAI,EAAE,CAAC;gBAC3B,QAAQ,EAAE,CAAC;gBACX,OAAO;YACT,CAAC;YACD,SAAS,GAAG,GAAG,CAAC;QAClB,CAAC;QAED,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAChD,KAAK,GAAG,QAAQ,CAAC;QACjB,MAAM,EAAE,CAAC;QACT,eAAe,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,0DAA0D;IAC1D,sEAAsE;IACtE,MAAM,aAAa,GAAc;QAC/B,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC;QAC/C,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;KAC1C,CAAC;IACF,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IACpE,KAAK,GAAG,YAAY,CAAC;IAErB,oCAAoC;IACpC,MAAM,EAAE,CAAC;IACT,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC1B,eAAe,CAAC,UAAU,CAAC,CAAC;IAE5B,uBAAuB;IACvB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClC,WAAW,GAAG,OAAO,CAAC;QACtB,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,6CAA6C;IAC7C,GAAG,CAAC,OAAO,EAAE,CAAC;IACd,IAAI,QAAQ,EAAE,CAAC;QACb,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAC9B,CAAC;IACD,IAAI,YAAY,IAAI,aAAa,EAAE,CAAC;QAClC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrB,CAAC;AACH,CAAC;AAED,4DAA4D;AAC5D,SAAS,iBAAiB,CAAC,KAAa;IACtC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,uEAAuE;AACvE,SAAS,cAAc,CAAC,EAAa,EAAE,IAAY;IACjD,IAAI,EAAE,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC;QAC1B,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACpB,OAAO;IACT,CAAC;IACD,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACjB,CAAC"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/screen.d.ts

@@ -6,7 +6,7 @@
  *
  * @module screen
  */
-import { HIDE_CURSOR, SHOW_CURSOR, type IOPort } from '@flyingrobots/bijou';
+import { HIDE_CURSOR, SHOW_CURSOR, type IOPort, type Surface, type StylePort } from '@flyingrobots/bijou';
 /** ANSI escape: enter alternate screen buffer (DEC Private Mode 1049). */
 export declare const ENTER_ALT_SCREEN = "\u001B[?1049h";
 /** ANSI escape: exit alternate screen buffer (DEC Private Mode 1049). */
@@ -76,8 +76,19 @@ export declare function exitScreen(io: IOPort): void;
  * @param io - The I/O port to write escape sequences to.
  */
 export declare function clearAndHome(io: IOPort): void;
+/**
+ * Optimized double-buffered render: diff two surfaces and write the minimal
+ * set of CUP/SGR escape codes to the terminal.
+ *
+ * @param io      - The I/O port to write the composed frame to.
+ * @param current - The surface currently on screen.
+ * @param target  - The new surface to render.
+ * @param style   - Style port for color resolution.
+ */
+export declare function renderSurfaceFrame(io: IOPort, current: Surface, target: Surface, style: StylePort): void;
 /**
  * Flicker-free render: move cursor home, write content line-by-line,
+...
  * clearing from the end of each line to the terminal edge.
  *
  * Disabling wrap in enterScreen() ensures the terminal won't scroll

package/dist/screen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screen.d.ts","sourceRoot":"","sources":["../src/screen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE5E,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,kBAAgB,CAAC;AAC9C,yEAAyE;AACzE,eAAO,MAAM,eAAe,kBAAgB,CAAC;AAE7C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;AACpC,+DAA+D;AAC/D,eAAO,MAAM,YAAY,eAAa,CAAC;AACvC,8DAA8D;AAC9D,eAAO,MAAM,WAAW,eAAa,CAAC;AACtC,+CAA+C;AAC/C,eAAO,MAAM,YAAY,cAAY,CAAC;AACtC,8DAA8D;AAC9D,eAAO,MAAM,YAAY,aAAW,CAAC;AACrC,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,aAAW,CAAC;AAC1C,yDAAyD;AACzD,eAAO,MAAM,IAAI,aAAW,CAAC;AAC7B,qDAAqD;AACrD,eAAO,MAAM,UAAU,cAAY,CAAC;AAIpC,oDAAoD;AACpD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,WAAW,GAAG,KAAK,CAAC;AAExD,qDAAqD;AACrD,eAAO,MAAM,YAAY,eAAa,CAAC;AACvC,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,eAAa,CAAC;AAC3C,mDAAmD;AACnD,eAAO,MAAM,UAAU,eAAa,CAAC;AACrC,wFAAwF;AACxF,eAAO,MAAM,YAAY,eAAa,CAAC;AASvC;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAGlG;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAI7D"}
+{"version":3,"file":"screen.d.ts","sourceRoot":"","sources":["../src/screen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAc,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEtH,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,kBAAgB,CAAC;AAC9C,yEAAyE;AACzE,eAAO,MAAM,eAAe,kBAAgB,CAAC;AAE7C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;AACpC,+DAA+D;AAC/D,eAAO,MAAM,YAAY,eAAa,CAAC;AACvC,8DAA8D;AAC9D,eAAO,MAAM,WAAW,eAAa,CAAC;AACtC,+CAA+C;AAC/C,eAAO,MAAM,YAAY,cAAY,CAAC;AACtC,8DAA8D;AAC9D,eAAO,MAAM,YAAY,aAAW,CAAC;AACrC,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,aAAW,CAAC;AAC1C,yDAAyD;AACzD,eAAO,MAAM,IAAI,aAAW,CAAC;AAC7B,qDAAqD;AACrD,eAAO,MAAM,UAAU,cAAY,CAAC;AAIpC,oDAAoD;AACpD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,WAAW,GAAG,KAAK,CAAC;AAExD,qDAAqD;AACrD,eAAO,MAAM,YAAY,eAAa,CAAC;AACvC,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,eAAa,CAAC;AAC3C,mDAAmD;AACnD,eAAO,MAAM,UAAU,eAAa,CAAC;AACrC,wFAAwF;AACxF,eAAO,MAAM,YAAY,eAAa,CAAC;AASvC;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAGlG;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7C;AACD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,SAAS,GACf,IAAI,CAEN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAI7D"}

package/dist/screen.js

@@ -6,7 +6,7 @@
  *
  * @module screen
  */
-import { HIDE_CURSOR, SHOW_CURSOR } from '@flyingrobots/bijou';
+import { HIDE_CURSOR, SHOW_CURSOR, renderDiff } from '@flyingrobots/bijou';
 /** ANSI escape: enter alternate screen buffer (DEC Private Mode 1049). */
 export const ENTER_ALT_SCREEN = '\x1b[?1049h';
 /** ANSI escape: exit alternate screen buffer (DEC Private Mode 1049). */
@@ -89,8 +89,21 @@ export function exitScreen(io) {
 export function clearAndHome(io) {
     io.write(CLEAR_SCREEN + HOME);
 }
+/**
+ * Optimized double-buffered render: diff two surfaces and write the minimal
+ * set of CUP/SGR escape codes to the terminal.
+ *
+ * @param io      - The I/O port to write the composed frame to.
+ * @param current - The surface currently on screen.
+ * @param target  - The new surface to render.
+ * @param style   - Style port for color resolution.
+ */
+export function renderSurfaceFrame(io, current, target, style) {
+    renderDiff(current, target, io, style);
+}
 /**
  * Flicker-free render: move cursor home, write content line-by-line,
+...
  * clearing from the end of each line to the terminal edge.
  *
  * Disabling wrap in enterScreen() ensures the terminal won't scroll

package/dist/screen.js.map

@@ -1 +1 @@
-{"version":3,"file":"screen.js","sourceRoot":"","sources":["../src/screen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAe,MAAM,qBAAqB,CAAC;AAE5E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAC9C,yEAAyE;AACzE,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAE7C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;AACpC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AACvC,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AACtC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAC;AACtC,8DAA8D;AAC9D,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC;AACrC,oEAAoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAC1C,yDAAyD;AACzD,MAAM,CAAC,MAAM,IAAI,GAAG,QAAQ,CAAC;AAC7B,qDAAqD;AACrD,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AAOpC,qDAAqD;AACrD,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AACvC,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAC3C,mDAAmD;AACnD,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC;AACrC,wFAAwF;AACxF,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AAEvC,0EAA0E;AAC1E,MAAM,iBAAiB,GAAgC;IACrD,KAAK,EAAE,CAAC;IACR,SAAS,EAAE,CAAC;IACZ,GAAG,EAAE,CAAC;CACP,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,EAAU,EAAE,KAAkB,EAAE,OAA6B;IAC1F,MAAM,IAAI,GAAG,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACtF,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAU;IACzC,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,EAAE,CAAC,KAAK,CAAC,gBAAgB,GAAG,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,IAAI,CAAC,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,EAAE,CAAC,KAAK,CAAC,WAAW,GAAG,WAAW,GAAG,eAAe,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,EAAE,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU,EAAE,OAAe;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC;IAC7F,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"screen.js","sourceRoot":"","sources":["../src/screen.ts"],"names":[],"mappings":"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"}

package/dist/subapp/mount.d.ts

@@ -0,0 +1,67 @@
+import type { App, Cmd } from '../types.js';
+import type { ViewOutput } from '../view-output.js';
+/**
+ * Options for mounting a sub-app.
+ *
+ * @template SubModel - The sub-app's model type.
+ * @template SubMsg - The sub-app's message type.
+ * @template ParentMsg - The parent app's message type.
+ */
+export interface MountOptions<SubModel, SubMsg, ParentMsg> {
+    /** The current state of the sub-app. */
+    model: SubModel;
+    /** Function to map a sub-app message into a parent message. */
+    onMsg: (msg: SubMsg) => ParentMsg;
+    /**
+     * Optional function to intercept and handle `Cmd`s emitted by the sub-app.
+     * If not provided, commands are automatically mapped using `onMsg`.
+     */
+    mapCmd?: (cmd: Cmd<SubMsg>) => Cmd<ParentMsg>;
+}
+/**
+ * A mounted sub-app instance ready to be rendered.
+ *
+ * This is typically returned by the parent's `view` function
+ * and blitted onto the parent's surface.
+ */
+export interface MountedApp<SubMsg> {
+    /** The rendered surface or layout tree of the sub-app. */
+    surfaceOrNode: ViewOutput;
+    /**
+     * Any TEA commands the sub-app needs to execute.
+     * These should be dispatched by the parent during its update cycle.
+     */
+    cmds: Cmd<SubMsg>[];
+}
+/**
+ * Mount a sub-app, returning its rendered surface and any pending commands.
+ *
+ * @template SubModel - The sub-app's model type.
+ * @template SubMsg - The sub-app's message type.
+ * @template ParentMsg - The parent app's message type.
+ *
+ * @param app - The TEA application to mount.
+ * @param options - Configuration for the mounted instance.
+ * @returns A tuple of `[Surface | LayoutNode, mapped Cmds]`.
+ */
+export declare function mount<SubModel, SubMsg, ParentMsg>(app: App<SubModel, SubMsg>, options: MountOptions<SubModel, SubMsg, ParentMsg>): [ViewOutput, Cmd<ParentMsg>[]];
+export interface SubAppOptions<SubMsg, ParentMsg> {
+    /** Function to map a sub-app message into a parent message. */
+    onMsg: (msg: SubMsg) => ParentMsg;
+    /**
+     * Optional function to intercept and handle `Cmd`s emitted by the sub-app.
+     * If not provided, commands are automatically mapped using `onMsg`.
+     */
+    mapCmd?: (cmd: Cmd<SubMsg>) => Cmd<ParentMsg>;
+}
+export declare function initSubApp<SubModel, SubMsg, ParentMsg>(app: App<SubModel, SubMsg>, options: SubAppOptions<SubMsg, ParentMsg>): [SubModel, Cmd<ParentMsg>[]];
+export declare function updateSubApp<SubModel, SubMsg, ParentMsg>(app: App<SubModel, SubMsg>, msg: SubMsg, model: SubModel, options: SubAppOptions<SubMsg, ParentMsg>): [SubModel, Cmd<ParentMsg>[]];
+/**
+ * Helper to map an array of sub-app commands into parent commands.
+ *
+ * @param cmds - The sub-app commands to map.
+ * @param mapper - The message mapping function.
+ * @returns An array of commands that emit parent messages.
+ */
+export declare function mapCmds<SubMsg, ParentMsg>(cmds: Cmd<SubMsg>[], mapper: (msg: SubMsg) => ParentMsg): Cmd<ParentMsg>[];
+//# sourceMappingURL=mount.d.ts.map

package/dist/subapp/mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/subapp/mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAc,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS;IACvD,wCAAwC;IACxC,KAAK,EAAE,QAAQ,CAAC;IAChB,+DAA+D;IAC/D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,MAAM;IAChC,0DAA0D;IAC1D,aAAa,EAAE,UAAU,CAAC;IAC1B;;;OAGG;IACH,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAC/C,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC1B,OAAO,EAAE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,GACjD,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAMhC;AAED,MAAM,WAAW,aAAa,CAAC,MAAM,EAAE,SAAS;IAC9C,+DAA+D;IAC/D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EACpD,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC1B,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,GACxC,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAG9B;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EACtD,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC1B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,GACxC,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAG9B;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,EACvC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,EACnB,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,GACjC,GAAG,CAAC,SAAS,CAAC,EAAE,CAElB"}

package/dist/subapp/mount.js

@@ -0,0 +1,60 @@
+/**
+ * Mount a sub-app, returning its rendered surface and any pending commands.
+ *
+ * @template SubModel - The sub-app's model type.
+ * @template SubMsg - The sub-app's message type.
+ * @template ParentMsg - The parent app's message type.
+ *
+ * @param app - The TEA application to mount.
+ * @param options - Configuration for the mounted instance.
+ * @returns A tuple of `[Surface | LayoutNode, mapped Cmds]`.
+ */
+export function mount(app, options) {
+    const { model } = options;
+    const surfaceOrNode = app.view(model);
+    return [surfaceOrNode, []];
+}
+export function initSubApp(app, options) {
+    const [model, cmds] = app.init();
+    return [model, mapSubAppCmds(cmds, options)];
+}
+export function updateSubApp(app, msg, model, options) {
+    const [nextModel, cmds] = app.update(msg, model);
+    return [nextModel, mapSubAppCmds(cmds, options)];
+}
+/**
+ * Helper to map an array of sub-app commands into parent commands.
+ *
+ * @param cmds - The sub-app commands to map.
+ * @param mapper - The message mapping function.
+ * @returns An array of commands that emit parent messages.
+ */
+export function mapCmds(cmds, mapper) {
+    return cmds.map((cmd) => mapSingleCmd(cmd, mapper));
+}
+function mapSubAppCmds(cmds, options) {
+    if (options.mapCmd != null) {
+        return cmds.map((cmd) => options.mapCmd(cmd));
+    }
+    return mapCmds(cmds, options.onMsg);
+}
+/**
+ * Map a single sub-app command to a parent command.
+ */
+function mapSingleCmd(cmd, mapper) {
+    return async (emit, caps) => {
+        // We intercept the sub-app's `emit` call to wrap its messages
+        const mappedEmit = (subMsg) => {
+            emit(mapper(subMsg));
+        };
+        const result = await cmd(mappedEmit, caps);
+        // If the command resolves to a final message, map it.
+        // Quit signals are passed through unaltered.
+        if (result === undefined)
+            return undefined;
+        if (typeof result === 'symbol')
+            return result; // QUIT
+        return mapper(result);
+    };
+}
+//# sourceMappingURL=mount.js.map

package/dist/subapp/mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.js","sourceRoot":"","sources":["../../src/subapp/mount.ts"],"names":[],"mappings":"AAsCA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,KAAK,CACnB,GAA0B,EAC1B,OAAkD;IAElD,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAE1B,MAAM,aAAa,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEtC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAYD,MAAM,UAAU,UAAU,CACxB,GAA0B,EAC1B,OAAyC;IAEzC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACjC,OAAO,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,GAA0B,EAC1B,GAAW,EACX,KAAe,EACf,OAAyC;IAEzC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjD,OAAO,CAAC,SAAS,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CACrB,IAAmB,EACnB,MAAkC;IAElC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,aAAa,CACpB,IAAmB,EACnB,OAAyC;IAEzC,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,MAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CACnB,GAAgB,EAChB,MAAkC;IAElC,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QAC1B,8DAA8D;QAC9D,MAAM,UAAU,GAAG,CAAC,MAAc,EAAE,EAAE;YACpC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACvB,CAAC,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAE3C,sDAAsD;QACtD,6CAA6C;QAC7C,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC3C,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,MAAoB,CAAC,CAAC,OAAO;QACpE,OAAO,MAAM,CAAC,MAAgB,CAAC,CAAC;IAClC,CAAC,CAAC;AACJ,CAAC"}

package/dist/transition-shaders.d.ts

@@ -1,8 +1,15 @@
 /**
  * Transition shader system — composable pure functions for page transitions.
  *
- * Each shader receives cell metadata (position, dimensions, progress, random)
- * and returns whether to show the next page or optionally override the character.
+ * Each shader receives cell metadata (position, dimensions, progress, random,
+ * frame counter) and returns whether to show the next page or optionally
+ * override the character.
+ *
+ * ## Shader types
+ *
+ * - **Instances** (`wipeShader`, `dissolveShader`, …) — zero-config, ready to use.
+ * - **Factories** (`wipe()`, `radial()`, `blinds()`, …) — parameterized, return a shader.
+ * - **Combinators** (`reverse()`, `chain()`, `overlay()`) — transform or compose shaders.
  */
 import type { BijouContext } from '@flyingrobots/bijou';
 /** Input provided to a transition shader for each cell. */
@@ -12,18 +19,35 @@ export interface TransitionCell {
     readonly width: number;
     readonly height: number;
     readonly progress: number;
+    /** Stable pseudo-random [0, 1] based on coordinates — constant across frames. */
     readonly rand: number;
+    /** Monotonic frame counter for temporal effects (glitch, static, etc.). */
+    readonly frame: number;
     readonly ctx: BijouContext;
 }
+/**
+ * Semantic role of a character override.
+ *
+ * - `'decoration'` — ambient visual noise (glitch blocks, static, scramble).
+ *   Survives progress remapping in combinators like `reverse()` and `chain()`.
+ * - `'marker'` — positional indicator tied to the shader's progress direction
+ *   (e.g., typewriter cursor). Dropped by combinators that remap progress,
+ *   since the marker's position becomes meaningless in the new space.
+ */
+export type CharRole = 'decoration' | 'marker';
 /** Output from a transition shader for a single cell. */
 export interface TransitionResult {
     readonly showNext: boolean;
     readonly char?: string;
+    /** Semantic role of the char override. Defaults to `'decoration'` if omitted. */
+    readonly charRole?: CharRole;
 }
 /** A pure function that determines how each cell transitions between pages. */
 export type TransitionShaderFn = (cell: TransitionCell) => TransitionResult;
+/** Direction for axis-aligned wipes and blinds. */
+export type WipeDirection = 'left' | 'right' | 'up' | 'down';
 /** Built-in transition names. */
-export type BuiltinTransition = 'none' | 'wipe' | 'dissolve' | 'grid' | 'fade' | 'melt' | 'matrix' | 'scramble';
+export type BuiltinTransition = 'none' | 'wipe' | 'dissolve' | 'grid' | 'fade' | 'melt' | 'matrix' | 'scramble' | 'radial' | 'diamond' | 'spiral' | 'blinds' | 'curtain' | 'pixelate' | 'typewriter' | 'glitch' | 'static';
 /** Left-to-right wipe. */
 export declare const wipeShader: TransitionShaderFn;
 /** Random pixel dissolve. */
@@ -38,6 +62,80 @@ export declare const meltShader: TransitionShaderFn;
 export declare const matrixShader: TransitionShaderFn;
 /** Scramble noise that resolves at midpoint. */
 export declare const scrambleShader: TransitionShaderFn;
+/** Directional wipe factory. Default: left-to-right. */
+export declare function wipe(direction?: WipeDirection): TransitionShaderFn;
+/** Circle expanding from an origin point. Default: center. */
+export declare function radial(originX?: number, originY?: number): TransitionShaderFn;
+/** Diamond/rhombus shape expanding from center. */
+export declare function diamond(originX?: number, originY?: number): TransitionShaderFn;
+/** Angular sweep that spirals outward from center. */
+export declare function spiral(turns?: number, originX?: number, originY?: number): TransitionShaderFn;
+/** Venetian blinds (horizontal or vertical bands). */
+export declare function blinds(count?: number, direction?: 'horizontal' | 'vertical'): TransitionShaderFn;
+/** Two halves sliding apart from center (vertical split). */
+export declare function curtain(direction?: 'horizontal' | 'vertical'): TransitionShaderFn;
+/** Progressively shrinking block pixelation that resolves to the next page. */
+export declare function pixelate(maxBlockSize?: number): TransitionShaderFn;
+/**
+ * Left-to-right, top-to-bottom typewriter reveal.
+ * Shows a cursor character at the leading edge.
+ */
+export declare function typewriter(cursor?: string): TransitionShaderFn;
+/**
+ * Horizontal glitch displacement with RGB-split-style character noise.
+ * Uses the frame counter for temporal variation.
+ */
+export declare function glitch(intensity?: number): TransitionShaderFn;
+/**
+ * TV static noise that clears to reveal the next page.
+ * Uses the frame counter for flickering.
+ */
+export declare function tvStatic(density?: number): TransitionShaderFn;
+/** Circle expanding from center. */
+export declare const radialShader: TransitionShaderFn;
+/** Diamond expanding from center. */
+export declare const diamondShader: TransitionShaderFn;
+/** Spiral sweep from center. */
+export declare const spiralShader: TransitionShaderFn;
+/** 8-band horizontal blinds. */
+export declare const blindsShader: TransitionShaderFn;
+/** Vertical curtain split from center. */
+export declare const curtainShader: TransitionShaderFn;
+/** Block pixelation with 16px max block size. */
+export declare const pixelateShader: TransitionShaderFn;
+/** Typewriter reveal with ▌ cursor. */
+export declare const typewriterShader: TransitionShaderFn;
+/** Horizontal glitch at 50% intensity. */
+export declare const glitchShader: TransitionShaderFn;
+/** TV static noise at 70% density. */
+export declare const staticShader: TransitionShaderFn;
+/**
+ * Reverse a shader's spatial reveal order.
+ *
+ * Cells that would be revealed last are revealed first, and vice versa.
+ * At progress=0 nothing is revealed; at progress=1 everything is revealed.
+ */
+export declare function reverse(shader: TransitionShaderFn): TransitionShaderFn;
+/**
+ * Chain two shaders sequentially: `a` runs during progress [0, 0.5],
+ * `b` runs during (0.5, 1]. Each sub-shader receives a normalized 0→1
+ * progress for its half.
+ *
+ * **Note:** There is a hard cut at the midpoint — shader `a` completes
+ * (all cells revealed) then shader `b` starts from scratch (no cells
+ * revealed). This is intentional for effects like "dissolve out → wipe in"
+ * but will flash if both shaders reveal in the same direction.
+ */
+export declare function chain(a: TransitionShaderFn, b: TransitionShaderFn): TransitionShaderFn;
+/**
+ * Overlay two shaders: `top` shader's char override wins when present,
+ * otherwise falls through to `base` shader's result.
+ *
+ * `showNext` uses OR semantics — the composite reveals a cell if *either*
+ * shader reveals it. This means the composite always reveals at least as
+ * much as either shader alone.
+ */
+export declare function overlay(base: TransitionShaderFn, top: TransitionShaderFn): TransitionShaderFn;
 /** Registry mapping built-in transition names to shader functions. `none` maps to `undefined`. */
 export declare const TRANSITION_SHADERS: Record<BuiltinTransition, TransitionShaderFn | undefined>;
 //# sourceMappingURL=transition-shaders.d.ts.map

package/dist/transition-shaders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transition-shaders.d.ts","sourceRoot":"","sources":["../src/transition-shaders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;CAC5B;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,gBAAgB,CAAC;AAE5E,iCAAiC;AACjC,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhH,0BAA0B;AAC1B,eAAO,MAAM,UAAU,EAAE,kBAEvB,CAAC;AAEH,6BAA6B;AAC7B,eAAO,MAAM,cAAc,EAAE,kBAE3B,CAAC;AAEH,iCAAiC;AACjC,eAAO,MAAM,UAAU,EAAE,kBAIxB,CAAC;AAEF,4BAA4B;AAC5B,eAAO,MAAM,UAAU,EAAE,kBAEvB,CAAC;AAEH,0DAA0D;AAC1D,eAAO,MAAM,UAAU,EAAE,kBAIxB,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,YAAY,EAAE,kBAY1B,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,cAAc,EAAE,kBAQ5B,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,iBAAiB,EAAE,kBAAkB,GAAG,SAAS,CASxF,CAAC"}
+{"version":3,"file":"transition-shaders.d.ts","sourceRoot":"","sources":["../src/transition-shaders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMxD,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,QAAQ,CAAC;AAE/C,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B;AAED,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,gBAAgB,CAAC;AAE5E,mDAAmD;AACnD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,CAAC;AAE7D,iCAAiC;AACjC,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,MAAM,GACN,UAAU,GACV,MAAM,GACN,MAAM,GACN,MAAM,GACN,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,UAAU,GACV,YAAY,GACZ,QAAQ,GACR,QAAQ,CAAC;AAgDb,0BAA0B;AAC1B,eAAO,MAAM,UAAU,EAAE,kBAEvB,CAAC;AAEH,6BAA6B;AAC7B,eAAO,MAAM,cAAc,EAAE,kBAE3B,CAAC;AAEH,iCAAiC;AACjC,eAAO,MAAM,UAAU,EAAE,kBAIxB,CAAC;AAEF,4BAA4B;AAC5B,eAAO,MAAM,UAAU,EAAE,kBAEvB,CAAC;AAEH,0DAA0D;AAC1D,eAAO,MAAM,UAAU,EAAE,kBAIxB,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,YAAY,EAAE,kBAY1B,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,cAAc,EAAE,kBAQ5B,CAAC;AAMF,wDAAwD;AACxD,wBAAgB,IAAI,CAAC,SAAS,GAAE,aAAuB,GAAG,kBAAkB,CAQ3E;AAED,8DAA8D;AAC9D,wBAAgB,MAAM,CAAC,OAAO,SAAM,EAAE,OAAO,SAAM,GAAG,kBAAkB,CAKvE;AAED,mDAAmD;AACnD,wBAAgB,OAAO,CAAC,OAAO,SAAM,EAAE,OAAO,SAAM,GAAG,kBAAkB,CAUxE;AAED,sDAAsD;AACtD,wBAAgB,MAAM,CAAC,KAAK,SAAI,EAAE,OAAO,SAAM,EAAE,OAAO,SAAM,GAAG,kBAAkB,CAQlF;AAED,sDAAsD;AACtD,wBAAgB,MAAM,CACpB,KAAK,SAAI,EACT,SAAS,GAAE,YAAY,GAAG,UAAyB,GAClD,kBAAkB,CAMpB;AAED,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,SAAS,GAAE,YAAY,GAAG,UAAuB,GAAG,kBAAkB,CAM7F;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,YAAY,SAAK,GAAG,kBAAkB,CAqB9D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,SAAM,GAAG,kBAAkB,CAW3D;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,SAAS,SAAM,GAAG,kBAAkB,CAwB1D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,SAAM,GAAG,kBAAkB,CAsB1D;AAMD,oCAAoC;AACpC,eAAO,MAAM,YAAY,EAAE,kBAA6B,CAAC;AAEzD,qCAAqC;AACrC,eAAO,MAAM,aAAa,EAAE,kBAA8B,CAAC;AAE3D,gCAAgC;AAChC,eAAO,MAAM,YAAY,EAAE,kBAA6B,CAAC;AAEzD,gCAAgC;AAChC,eAAO,MAAM,YAAY,EAAE,kBAA6B,CAAC;AAEzD,0CAA0C;AAC1C,eAAO,MAAM,aAAa,EAAE,kBAA8B,CAAC;AAE3D,iDAAiD;AACjD,eAAO,MAAM,cAAc,EAAE,kBAA+B,CAAC;AAE7D,uCAAuC;AACvC,eAAO,MAAM,gBAAgB,EAAE,kBAAiC,CAAC;AAEjE,0CAA0C;AAC1C,eAAO,MAAM,YAAY,EAAE,kBAA6B,CAAC;AAEzD,sCAAsC;AACtC,eAAO,MAAM,YAAY,EAAE,kBAA+B,CAAC;AAM3D;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAWtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,CAOtF;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,kBAAkB,EAAE,GAAG,EAAE,kBAAkB,GAAG,kBAAkB,CAW7F;AAMD,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,iBAAiB,EAAE,kBAAkB,GAAG,SAAS,CAkBxF,CAAC"}