Skip to content

The Open Standard for Generative UI

9.0 KB
Raw Blame
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 };
}