@czap/core 0.1.0

package/dist/ecs.js

@@ -0,0 +1,245 @@
+/**
+ * ECS -- Entity, Part, System, World.
+ *
+ * Composition over inheritance. Entities are bags of parts,
+ * systems operate on entities matching part queries.
+ *
+ * @module
+ */
+import { Effect, Ref } from 'effect';
+/** Brand an arbitrary string as an `EntityId`. Sanctioned single-site cast. */
+export const EntityId = (value) => value;
+import { fnv1a } from './fnv.js';
+// ---------------------------------------------------------------------------
+// Dense Component Storage -- Float64Array-backed, zero-allocation iteration
+// ---------------------------------------------------------------------------
+const DENSE_SENTINEL = -Infinity;
+function _makeDenseStore(name, capacity) {
+    const entityToIndex = new Map();
+    const indexToEntity = [];
+    const data = new Float64Array(capacity);
+    data.fill(DENSE_SENTINEL);
+    const store = {
+        name,
+        capacity,
+        _dense: true,
+        entityToIndex,
+        indexToEntity,
+        data,
+        count: 0,
+        get(entityId) {
+            const idx = entityToIndex.get(entityId);
+            if (idx === undefined)
+                return undefined;
+            return data[idx];
+        },
+        set(entityId, value) {
+            let idx = entityToIndex.get(entityId);
+            if (idx !== undefined) {
+                data[idx] = value;
+                return;
+            }
+            if (store.count >= capacity) {
+                throw new RangeError(`Dense store "${name}" at capacity (${capacity}). Cannot add entity ${entityId}.`);
+            }
+            idx = store.count;
+            entityToIndex.set(entityId, idx);
+            indexToEntity[idx] = entityId;
+            data[idx] = value;
+            store.count++;
+        },
+        has(entityId) {
+            return entityToIndex.has(entityId);
+        },
+        delete(entityId) {
+            const idx = entityToIndex.get(entityId);
+            if (idx === undefined)
+                return false;
+            const lastIdx = store.count - 1;
+            if (idx !== lastIdx) {
+                // Swap-remove: move last element into the vacated slot
+                const lastEntity = indexToEntity[lastIdx];
+                data[idx] = data[lastIdx];
+                indexToEntity[idx] = lastEntity;
+                entityToIndex.set(lastEntity, idx);
+            }
+            data[lastIdx] = DENSE_SENTINEL;
+            indexToEntity.length = lastIdx;
+            entityToIndex.delete(entityId);
+            store.count--;
+            return true;
+        },
+        reset() {
+            entityToIndex.clear();
+            indexToEntity.length = 0;
+            data.fill(DENSE_SENTINEL);
+            store.count = 0;
+        },
+        view() {
+            return data.subarray(0, store.count);
+        },
+        entities() {
+            return indexToEntity;
+        },
+    };
+    return store;
+}
+function _makeWorld() {
+    return Effect.gen(function* () {
+        const entitiesRef = yield* Ref.make(new Map());
+        const systemsRef = yield* Ref.make([]);
+        const denseStoresRef = yield* Ref.make(new Map());
+        let nextEntitySeq = 0;
+        const world = {
+            spawn(components) {
+                return Effect.gen(function* () {
+                    const seq = nextEntitySeq++;
+                    const id = EntityId(`entity-${seq}:${fnv1a(JSON.stringify(components ?? {}))}`);
+                    const componentMap = new Map();
+                    if (components) {
+                        for (const [name, value] of Object.entries(components)) {
+                            componentMap.set(name, value);
+                        }
+                    }
+                    yield* Ref.update(entitiesRef, (m) => {
+                        const next = new Map(m);
+                        next.set(id, componentMap);
+                        return next;
+                    });
+                    return id;
+                });
+            },
+            despawn(id) {
+                return Effect.gen(function* () {
+                    // Remove from entity map
+                    yield* Ref.update(entitiesRef, (m) => {
+                        const next = new Map(m);
+                        next.delete(id);
+                        return next;
+                    });
+                    // Remove from all dense stores
+                    const denseStores = yield* Ref.get(denseStoresRef);
+                    for (const store of denseStores.values()) {
+                        store.delete(id);
+                    }
+                });
+            },
+            addComponent(id, component, value) {
+                return Ref.update(entitiesRef, (m) => {
+                    const next = new Map(m);
+                    const entity = next.get(id);
+                    if (entity) {
+                        const updated = new Map(entity);
+                        updated.set(component.name, value);
+                        next.set(id, updated);
+                    }
+                    return next;
+                });
+            },
+            setComponent(id, name, value) {
+                return Ref.update(entitiesRef, (m) => {
+                    const next = new Map(m);
+                    const entity = next.get(id);
+                    if (entity) {
+                        const updated = new Map(entity);
+                        updated.set(name, value);
+                        next.set(id, updated);
+                    }
+                    return next;
+                });
+            },
+            removeComponent(id, name) {
+                return Ref.update(entitiesRef, (m) => {
+                    const next = new Map(m);
+                    const entity = next.get(id);
+                    if (entity) {
+                        const updated = new Map(entity);
+                        updated.delete(name);
+                        next.set(id, updated);
+                    }
+                    return next;
+                });
+            },
+            query(...componentNames) {
+                return Effect.gen(function* () {
+                    const entities = yield* Ref.get(entitiesRef);
+                    const results = [];
+                    for (const [id, components] of entities) {
+                        const hasAll = componentNames.every((name) => components.has(name));
+                        if (hasAll) {
+                            const componentsCopy = new Map(components);
+                            // Spread component values as direct properties so systems can access
+                            // computed output fields (e.g. `_opacity`, `_phase`, `_blend`) directly.
+                            const entity = Object.assign({ id, components: componentsCopy }, Object.fromEntries(componentsCopy));
+                            results.push(entity);
+                        }
+                    }
+                    return results;
+                });
+            },
+            addSystem(system) {
+                return Ref.update(systemsRef, (systems) => [...systems, system]);
+            },
+            addDenseStore(store) {
+                return Ref.update(denseStoresRef, (m) => {
+                    const next = new Map(m);
+                    next.set(store.name, store);
+                    return next;
+                });
+            },
+            tick() {
+                return Effect.gen(function* () {
+                    const systems = yield* Ref.get(systemsRef);
+                    const denseStores = yield* Ref.get(denseStoresRef);
+                    for (const system of systems) {
+                        if (isDenseSystem(system)) {
+                            // Dense path: collect the stores this system queries
+                            const queriedStores = new Map();
+                            for (const name of system.query) {
+                                const store = denseStores.get(name);
+                                if (store)
+                                    queriedStores.set(name, store);
+                            }
+                            // Only execute if all queried stores exist
+                            if (queriedStores.size === system.query.length) {
+                                yield* system.execute(queriedStores);
+                            }
+                        }
+                        else {
+                            // Regular path: entity-component query
+                            const matched = yield* world.query(...system.query);
+                            yield* system.execute(matched, world);
+                        }
+                    }
+                });
+            },
+        };
+        return world;
+    });
+}
+function isDenseSystem(system) {
+    return '_denseSystem' in system && system._denseSystem === true;
+}
+// ---------------------------------------------------------------------------
+// Part namespace -- factories and types
+// ---------------------------------------------------------------------------
+function _makeDensePart(name, capacity) {
+    return _makeDenseStore(name, capacity);
+}
+/**
+ * Part namespace — factories for ECS component stores.
+ *
+ * Currently exposes the dense `Float64Array`-backed store used for hot-path
+ * numeric state; sparse/object-valued parts are registered ad-hoc via
+ * {@link World}.`addComponent`.
+ */
+export const Part = {
+    /** Allocate a dense component store with fixed capacity. */
+    dense: _makeDensePart,
+};
+/** World namespace — construct the ECS world that ticks systems over entities. */
+export const World = {
+    /** Scoped Effect that produces a fresh ECS {@link World.Shape}. */
+    make: _makeWorld,
+};
+//# sourceMappingURL=ecs.js.map

package/dist/ecs.js.map

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

package/dist/fnv.d.ts

@@ -0,0 +1,14 @@
+/**
+ * FNV-1a hash utility for content addressing.
+ *
+ * Shared implementation used by Boundary, Token, Style, Theme, Component,
+ * and GenFrame modules. Produces `fnv1a:XXXXXXXX` ContentAddress values.
+ *
+ * @module
+ */
+import type { ContentAddress } from './brands.js';
+/** FNV-1a hash of a string, returned as a ContentAddress. */
+export declare function fnv1a(str: string): ContentAddress;
+/** FNV-1a hash of raw bytes, returned as a ContentAddress. */
+export declare function fnv1aBytes(bytes: Uint8Array): ContentAddress;
+//# sourceMappingURL=fnv.d.ts.map

package/dist/fnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fnv.d.ts","sourceRoot":"","sources":["../src/fnv.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,6DAA6D;AAC7D,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAOjD;AAED,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,CAO5D"}

package/dist/fnv.js

@@ -0,0 +1,28 @@
+/**
+ * FNV-1a hash utility for content addressing.
+ *
+ * Shared implementation used by Boundary, Token, Style, Theme, Component,
+ * and GenFrame modules. Produces `fnv1a:XXXXXXXX` ContentAddress values.
+ *
+ * @module
+ */
+import { ContentAddress as mkContentAddress } from './brands.js';
+/** FNV-1a hash of a string, returned as a ContentAddress. */
+export function fnv1a(str) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return mkContentAddress(`fnv1a:${(h >>> 0).toString(16).padStart(8, '0')}`);
+}
+/** FNV-1a hash of raw bytes, returned as a ContentAddress. */
+export function fnv1aBytes(bytes) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < bytes.length; i++) {
+        h ^= bytes[i];
+        h = Math.imul(h, 0x01000193);
+    }
+    return mkContentAddress(`fnv1a:${(h >>> 0).toString(16).padStart(8, '0')}`);
+}
+//# sourceMappingURL=fnv.js.map

package/dist/fnv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fnv.js","sourceRoot":"","sources":["../src/fnv.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,cAAc,IAAI,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEjE,6DAA6D;AAC7D,MAAM,UAAU,KAAK,CAAC,GAAW;IAC/B,IAAI,CAAC,GAAG,UAAU,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,gBAAgB,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAC,KAAiB;IAC1C,IAAI,CAAC,GAAG,UAAU,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAE,CAAC;QACf,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,gBAAgB,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AAC9E,CAAC"}

package/dist/frame-budget.d.ts

@@ -0,0 +1,73 @@
+/**
+ * FrameBudget -- rAF priority lanes for frame budget management.
+ *
+ * Tracks remaining frame budget per animation frame and
+ * schedules work by priority: `critical > high > low > idle`.
+ *
+ * Hot path methods (remaining, canRun, scheduleSync) are plain JS.
+ * Effect is used only for resource lifecycle (rAF cleanup) and
+ * backwards-compatible schedule() wrapper.
+ *
+ * @module
+ */
+import type { Scope } from 'effect';
+import { Effect } from 'effect';
+/**
+ * Frame-budget priority lane in descending urgency. `critical` always runs;
+ * `high` / `low` / `idle` gate based on the milliseconds remaining in the
+ * current frame.
+ */
+export type Priority = 'critical' | 'high' | 'low' | 'idle';
+interface FrameBudgetShape {
+    remaining(): number;
+    canRun(priority: Priority): boolean;
+    /** Synchronous scheduler for hot paths — no Effect overhead. */
+    scheduleSync<A>(priority: Priority, task: () => A): A | null;
+    schedule<A>(priority: Priority, task: Effect.Effect<A>): Effect.Effect<A | null>;
+    readonly fps: Effect.Effect<number>;
+    /** Synchronous FPS accessor for hot paths. */
+    readonly fpsSync: number;
+}
+/**
+ * Creates a FrameBudget tracker tied to rAF, with priority-based scheduling.
+ * Critical tasks always run; lower priorities are deferred if budget is exhausted.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const budget = yield* FrameBudget.make({ targetFps: 60 });
+ *   const remaining = budget.remaining(); // ms left in this frame
+ *   const canAnimate = budget.canRun('high'); // true if enough budget
+ *   const result = yield* budget.schedule('low', Effect.succeed('done'));
+ *   // result is 'done' if budget permits, null otherwise
+ * }));
+ * ```
+ */
+declare function _make(config?: {
+    targetFps?: number;
+}): Effect.Effect<FrameBudgetShape, never, Scope.Scope>;
+/**
+ * FrameBudget -- rAF-based frame budget manager with priority lanes.
+ * Tracks remaining time per animation frame and gates work by priority:
+ * `critical` (always runs) `> high > low > idle`.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const budget = yield* FrameBudget.make({ targetFps: 60 });
+ *   if (budget.canRun('high')) {
+ *     yield* budget.schedule('high', Effect.succeed('rendered'));
+ *   }
+ *   const fps = yield* budget.fps; // current measured FPS
+ * }));
+ * ```
+ */
+export declare const FrameBudget: {
+    make: typeof _make;
+};
+export declare namespace FrameBudget {
+    /** Structural shape of a {@link FrameBudget} instance — `canRun`, `schedule`, `remaining`, `fps`. */
+    type Shape = FrameBudgetShape;
+}
+export {};
+//# sourceMappingURL=frame-budget.d.ts.map

package/dist/frame-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-budget.d.ts","sourceRoot":"","sources":["../src/frame-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAU5D,UAAU,gBAAgB;IACxB,SAAS,IAAI,MAAM,CAAC;IACpB,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IACpC,gEAAgE;IAChE,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAC7D,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACjF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,iBAAS,KAAK,CAAC,MAAM,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAmEnG;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW;;CAAkB,CAAC;AAE3C,MAAM,CAAC,OAAO,WAAW,WAAW,CAAC;IACnC,qGAAqG;IACrG,KAAY,KAAK,GAAG,gBAAgB,CAAC;CACtC"}

package/dist/frame-budget.js

@@ -0,0 +1,114 @@
+/**
+ * FrameBudget -- rAF priority lanes for frame budget management.
+ *
+ * Tracks remaining frame budget per animation frame and
+ * schedules work by priority: `critical > high > low > idle`.
+ *
+ * Hot path methods (remaining, canRun, scheduleSync) are plain JS.
+ * Effect is used only for resource lifecycle (rAF cleanup) and
+ * backwards-compatible schedule() wrapper.
+ *
+ * @module
+ */
+import { Effect } from 'effect';
+import { DEFAULT_TARGET_FPS, MS_PER_SEC } from './defaults.js';
+// ms budget per priority lane within a 16ms frame (critical=0 runs first, high=2ms, low=6ms, idle=12ms)
+const PRIORITY_THRESHOLDS = {
+    critical: 0,
+    high: 2,
+    low: 6,
+    idle: 12,
+};
+/**
+ * Creates a FrameBudget tracker tied to rAF, with priority-based scheduling.
+ * Critical tasks always run; lower priorities are deferred if budget is exhausted.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const budget = yield* FrameBudget.make({ targetFps: 60 });
+ *   const remaining = budget.remaining(); // ms left in this frame
+ *   const canAnimate = budget.canRun('high'); // true if enough budget
+ *   const result = yield* budget.schedule('low', Effect.succeed('done'));
+ *   // result is 'done' if budget permits, null otherwise
+ * }));
+ * ```
+ */
+function _make(config) {
+    const targetFps = config?.targetFps ?? DEFAULT_TARGET_FPS;
+    if (targetFps <= 0 || !Number.isFinite(targetFps)) {
+        throw new RangeError(`FrameBudget.make: targetFps must be a positive finite number, got ${targetFps}`);
+    }
+    const frameBudgetMs = MS_PER_SEC / targetFps;
+    return Effect.gen(function* () {
+        let frameStart = typeof performance !== 'undefined' ? performance.now() : 0;
+        let currentFps = targetFps;
+        let lastFrameTime = typeof performance !== 'undefined' ? performance.now() : 0;
+        let frameCount = 0;
+        let fpsAccum = 0;
+        if (typeof requestAnimationFrame !== 'undefined') {
+            const tick = (now) => {
+                frameStart = now;
+                frameCount++;
+                fpsAccum += now - lastFrameTime;
+                lastFrameTime = now;
+                if (fpsAccum >= MS_PER_SEC) {
+                    currentFps = Math.round((frameCount * MS_PER_SEC) / fpsAccum);
+                    frameCount = 0;
+                    fpsAccum %= MS_PER_SEC;
+                }
+                rafId = requestAnimationFrame(tick);
+            };
+            let rafId = requestAnimationFrame(tick);
+            yield* Effect.addFinalizer(() => Effect.sync(() => cancelAnimationFrame(rafId)));
+        }
+        const budget = {
+            remaining() {
+                if (typeof performance === 'undefined')
+                    return frameBudgetMs;
+                return Math.max(0, frameBudgetMs - (performance.now() - frameStart));
+            },
+            canRun(priority) {
+                const rem = budget.remaining();
+                return rem >= PRIORITY_THRESHOLDS[priority];
+            },
+            scheduleSync(priority, task) {
+                if (budget.canRun(priority) || priority === 'critical') {
+                    return task();
+                }
+                return null;
+            },
+            schedule(priority, task) {
+                return Effect.gen(function* () {
+                    if (priority === 'critical' || budget.canRun(priority)) {
+                        return yield* task;
+                    }
+                    return null;
+                });
+            },
+            fps: Effect.sync(() => currentFps),
+            get fpsSync() {
+                return currentFps;
+            },
+        };
+        return budget;
+    });
+}
+/**
+ * FrameBudget -- rAF-based frame budget manager with priority lanes.
+ * Tracks remaining time per animation frame and gates work by priority:
+ * `critical` (always runs) `> high > low > idle`.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const budget = yield* FrameBudget.make({ targetFps: 60 });
+ *   if (budget.canRun('high')) {
+ *     yield* budget.schedule('high', Effect.succeed('rendered'));
+ *   }
+ *   const fps = yield* budget.fps; // current measured FPS
+ * }));
+ * ```
+ */
+export const FrameBudget = { make: _make };
+//# sourceMappingURL=frame-budget.js.map

package/dist/frame-budget.js.map

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

package/dist/gen-frame.d.ts

@@ -0,0 +1,102 @@
+/**
+ * GenFrame -- generative UI frame scheduler.
+ *
+ * Fixed-step scheduler producing "UI frames" at configurable fps
+ * from token buffer. Each frame classified as keyframe (I-frame),
+ * delta (P-frame), or interpolated (B-frame).
+ *
+ * Integrates with FrameBudget for priority scheduling and receipt
+ * chain for disconnect-resilient generative UI state.
+ *
+ * @module
+ */
+import type { ContentAddress } from './brands.js';
+import type { TokenBuffer } from './token-buffer.js';
+import type { UIQualityTier } from './ui-quality.js';
+/**
+ * Classification of a {@link UIFrame} in the generative-UI pipeline, analogous to
+ * I/P/B frames in video: `keyframe` replaces, `delta` patches, `interpolated`
+ * keeps the DOM still and animates via CSS only.
+ */
+export type FrameType = 'keyframe' | 'delta' | 'interpolated';
+/** How a {@link UIFrame} is applied to the DOM: full replace, patch, or CSS-only motion. */
+export type MorphStrategy = 'replace' | 'patch' | 'css-only';
+/**
+ * A single frame emitted by the {@link GenFrame} scheduler — the unit of work
+ * the DOM runtime consumes. Carries the drained tokens, its classification,
+ * the quality tier that produced it, and a content-addressed receipt for
+ * disconnect-resilient replay.
+ */
+export interface UIFrame {
+    readonly type: FrameType;
+    readonly tokens: readonly string[];
+    readonly qualityTier: UIQualityTier;
+    readonly morphStrategy: MorphStrategy;
+    readonly timestamp: number;
+    readonly receiptId: ContentAddress;
+    readonly bufferPosition: number;
+}
+/**
+ * Recovery plan returned by {@link GenFrame.resolveGap} when a stream disconnects:
+ * resume from a buffer position, replay cached frames, request a full restart,
+ * or do nothing.
+ */
+export type GapStrategy = {
+    readonly type: 'resume';
+    readonly bufferPosition: number;
+} | {
+    readonly type: 'replay';
+    readonly frames: readonly UIFrame[];
+} | {
+    readonly type: 're-request';
+    readonly fromScratch: true;
+} | {
+    readonly type: 'noop';
+};
+/** Transport-layer snapshot indicating whether the stream can resume from its last event. */
+export interface ResumptionInfo {
+    readonly canResume: boolean;
+    readonly lastEventId?: string;
+}
+/** Accessor bundle that exposes the receipt chain to {@link GenFrame.resolveGap}. */
+export interface ReceiptChainInfo {
+    readonly hasFramesAfter: (receiptId: ContentAddress | null) => boolean;
+    readonly getFramesAfter: (receiptId: ContentAddress | null) => readonly UIFrame[];
+}
+declare function resolveGap(lastAckReceiptId: ContentAddress | null, currentStreamPosition: number, receiptChain: ReceiptChainInfo, resumptionState: ResumptionInfo): GapStrategy;
+interface GenFrameConfig {
+    readonly fps?: number;
+    readonly tokenBuffer: TokenBuffer.Shape<string>;
+    readonly getQualityTier: () => UIQualityTier;
+}
+interface GenFrameSchedulerShape {
+    tick(): UIFrame | null;
+    readonly frameCount: number;
+    readonly lastFrame: UIFrame | null;
+    markKeyframe(): void;
+    reset(): void;
+}
+declare function _make(config: GenFrameConfig): GenFrameSchedulerShape;
+/**
+ * Generative-UI frame scheduler namespace.
+ *
+ * Turns a bursty LLM token stream into evenly-paced frames the DOM runtime
+ * can apply without stalling, and resolves disconnect gaps using the receipt
+ * chain or transport resumption.
+ */
+export declare const GenFrame: {
+    /** Create a new fixed-step scheduler bound to a {@link TokenBuffer} and quality-tier probe. */
+    make: typeof _make;
+    /** Pick a recovery {@link GapStrategy} after a stream disconnect. */
+    resolveGap: typeof resolveGap;
+};
+export declare namespace GenFrame {
+    /** Structural shape of a scheduler instance returned by {@link GenFrame.make}. */
+    type Shape = GenFrameSchedulerShape;
+    /** Configuration accepted by {@link GenFrame.make}. */
+    type Config = GenFrameConfig;
+    /** Alias for {@link UIFrame}. */
+    type Frame = UIFrame;
+}
+export {};
+//# sourceMappingURL=gen-frame.d.ts.map

package/dist/gen-frame.d.ts.map

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