The Open Standard for Generative UI
import { useCallback, useRef, useState } from "react";
import { type ChunkStrategy, type StreamChunk, mulberry32, splitChunks } from "./chunker";
import type { LangModule, LibrarySchema, ParseResult } from "./types";
export interface TraceRow {
i: number;
chunkPreview: string;
delayMs: number;
rootPresent: boolean;
rootAppeared: boolean;
rootDropped: boolean;
statementCount: number;
incomplete: boolean;
unresolvedCount: number;
errorCount: number;
}
export type PlaybackStatus = "idle" | "playing" | "paused" | "done";
export interface PlaybackState {
status: PlaybackStatus;
prefix: string;
chunkIndex: number;
totalChunks: number;
trace: TraceRow[];
traceTruncated: boolean;
result: ParseResult | null;
convergence: "converged" | "diverged" | null;
emulated: boolean;
fatal: string | null;
}
const IDLE: PlaybackState = {
status: "idle",
prefix: "",
chunkIndex: 0,
totalChunks: 0,
trace: [],
traceTruncated: false,
result: null,
convergence: null,
emulated: false,
fatal: null,
};
const TRACE_CAP = 5000;
const BASE_INTERVAL_MS = 40;
interface Session {
source: string;
chunks: StreamChunk[];
strategy: ChunkStrategy;
emulated: boolean;
push: (chunk: string, prefix: string) => ParseResult | null;
getFinal: () => ParseResult | null;
prefix: string;
index: number;
lastRootPresent: boolean;
rows: TraceRow[];
truncated: boolean;
}
export interface PlaybackControls {
state: PlaybackState;
start: (opts: { strategy: ChunkStrategy; seed: number }) => void;
pause: () => void;
resume: () => void;
step: () => void;
reset: () => void;
setSpeed: (speed: number) => void;
speed: number;
}
export function usePlayback(
code: string,
lang: LangModule | null | undefined,
schema: LibrarySchema | null,
rootName: string | undefined,
): PlaybackControls {
const [state, setState] = useState<PlaybackState>(IDLE);
const [speed, setSpeedState] = useState(1);
const speedRef = useRef(1);
const generation = useRef(0);
const session = useRef<Session | null>(null);
const setSpeed = useCallback((s: number) => {
speedRef.current = s;
setSpeedState(s);
}, []);
const finish = useCallback(
(s: Session, module: LangModule) => {
let convergence: PlaybackState["convergence"] = null;
let fatal: string | null = null;
let result: ParseResult | null = null;
try {
result = s.getFinal();
if (!schema) throw new Error("No library schema");
const oneShot = module.createParser(schema, rootName).parse(s.source);
convergence =
JSON.stringify(result?.root) === JSON.stringify(oneShot?.root) ? "converged" : "diverged";
} catch (err) {
fatal = err instanceof Error ? err.message : String(err);
}
setState((prev) => ({
...prev,
status: "done",
result: result ?? prev.result,
convergence,
fatal,
}));
},
[schema, rootName],
);
const applyChunk = useCallback(
(s: Session): { result: ParseResult | null; fatal: string | null } => {
const chunk = s.chunks[s.index];
if (!chunk) return { result: null, fatal: null };
s.prefix += chunk.text;
let result: ParseResult | null = null;
let fatal: string | null = null;
try {
result = s.push(chunk.text, s.prefix);
} catch (err) {
fatal = err instanceof Error ? err.message : String(err);
}
const rootPresent = !!result?.root;
if (result) {
if (s.rows.length >= TRACE_CAP) {
s.truncated = true;
} else {
s.rows.push({
i: s.index,
chunkPreview: chunk.text.length > 40 ? `${chunk.text.slice(0, 40)}…` : chunk.text,
delayMs: chunk.delayMs,
rootPresent,
rootAppeared: rootPresent && !s.lastRootPresent,
rootDropped: !rootPresent && s.lastRootPresent,
statementCount: result.meta.statementCount,
incomplete: result.meta.incomplete,
unresolvedCount: result.meta.unresolved.length,
errorCount: result.meta.errors.length,
});
}
}
s.lastRootPresent = rootPresent;
s.index += 1;
return { result, fatal };
},
[],
);
const snapshot = useCallback(
(s: Session, status: PlaybackStatus, result: ParseResult | null, fatal: string | null) => {
setState({
status: fatal ? "done" : status,
prefix: s.prefix,
chunkIndex: s.index,
totalChunks: s.chunks.length,
trace: [...s.rows],
traceTruncated: s.truncated,
result,
convergence: null,
emulated: s.emulated,
fatal,
});
},
[],
);
const advance = useCallback(
(s: Session, status: PlaybackStatus): boolean => {
const { result, fatal } = applyChunk(s);
snapshot(s, status, result, fatal);
return !fatal;
},
[applyChunk, snapshot],
);
const chunkDelay = useCallback((s: Session, chunk: StreamChunk | undefined) => {
if (!chunk) return 0;
const base = s.strategy === "llm" ? chunk.delayMs : BASE_INTERVAL_MS;
return Math.max(0, base / speedRef.current);
}, []);
const play = useCallback(
(s: Session, module: LangModule) => {
const gen = generation.current;
// Wait *before* each chunk. Cap catch-up so a slow first paint cannot
// mark the whole stream overdue and flush it in one frame.
const MAX_PLAYBACK_MS_PER_TICK = 50;
let nextAt = performance.now() + chunkDelay(s, s.chunks[s.index]);
const tick = () => {
if (generation.current !== gen || session.current !== s) return;
if (s.index >= s.chunks.length) {
finish(s, module);
return;
}
const now = performance.now();
if (nextAt > now) {
setTimeout(tick, nextAt - now);
return;
}
let last: { result: ParseResult | null; fatal: string | null } | null = null;
let played = 0;
while (s.index < s.chunks.length && nextAt <= now && played < MAX_PLAYBACK_MS_PER_TICK) {
const appliedDelay = chunkDelay(s, s.chunks[s.index]);
last = applyChunk(s);
if (last.fatal) {
snapshot(s, "done", last.result, last.fatal);
return;
}
nextAt += chunkDelay(s, s.chunks[s.index]);
played += appliedDelay > 0 ? appliedDelay : 4;
}
if (last) snapshot(s, "playing", last.result, last.fatal);
if (s.index >= s.chunks.length) {
finish(s, module);
return;
}
const wait = nextAt - performance.now();
if (wait <= 0) requestAnimationFrame(tick);
else setTimeout(tick, wait);
};
const wait = nextAt - performance.now();
if (wait <= 0) requestAnimationFrame(tick);
else setTimeout(tick, wait);
},
[applyChunk, chunkDelay, finish, snapshot],
);
const start = useCallback(
({ strategy, seed }: { strategy: ChunkStrategy; seed: number }) => {
if (!lang || !code.trim() || schema == null) return;
generation.current += 1;
const emulated = typeof lang.createStreamingParser !== "function";
let push: Session["push"];
let getFinal: Session["getFinal"];
if (emulated) {
let last: ParseResult | null = null;
push = (_chunk, prefix) => {
last = lang.createParser(schema, rootName).parse(prefix);
return last;
};
getFinal = () => last ?? lang.createParser(schema, rootName).parse(code);
} else {
const sp = lang.createStreamingParser!(schema, rootName);
push = (chunk) => sp.push(chunk);
getFinal = () => sp.getResult(true);
}
const s: Session = {
source: code,
chunks: splitChunks(code, strategy, mulberry32(seed)),
strategy,
emulated,
push,
getFinal,
prefix: "",
index: 0,
lastRootPresent: false,
rows: [],
truncated: false,
};
session.current = s;
setState({ ...IDLE, status: "playing", totalChunks: s.chunks.length, emulated });
play(s, lang);
},
[code, lang, schema, rootName, play],
);
const pause = useCallback(() => {
generation.current += 1;
setState((prev) => (prev.status === "playing" ? { ...prev, status: "paused" } : prev));
}, []);
const resume = useCallback(() => {
const s = session.current;
if (!s || !lang) return;
generation.current += 1;
setState((prev) => (prev.status === "paused" ? { ...prev, status: "playing" } : prev));
play(s, lang);
}, [lang, play]);
const step = useCallback(() => {
const s = session.current;
if (!s || !lang) return;
if (s.index >= s.chunks.length) {
finish(s, lang);
return;
}
if (advance(s, "paused") && s.index >= s.chunks.length) finish(s, lang);
}, [advance, finish, lang]);
const reset = useCallback(() => {
generation.current += 1;
session.current = null;
setState(IDLE);
}, []);
return { state, start, pause, resume, step, reset, setSpeed, speed };
}