Skip to content

The Open Standard for Generative UI

8.0 KB
Raw Blame
"use client";

import { useCallback, useRef, useState } from "react";
import { normalizeResult } from "../parse";
import type { LoadedLangCore, ParseResult, StreamParserLike } from "../versions/types";
import { type ChunkStrategy, type StreamChunk, mulberry32, splitChunks } from "./chunker";

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;
  /** Accumulated source text pushed so far — feed this to the Renderer. */
  prefix: string;
  chunkIndex: number;
  totalChunks: number;
  trace: TraceRow[];
  traceTruncated: boolean;
  result: ParseResult | null;
  /** Streaming result vs one-shot parse of the full source, checked on finish. */
  convergence: "converged" | "diverged" | null;
  /** True when the selected version has no createStreamingParser (re-parse per chunk). */
  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 {
  /** Snapshot of the editor content when playback started. */
  source: string;
  chunks: StreamChunk[];
  strategy: ChunkStrategy;
  emulated: boolean;
  push: (chunk: string, prefix: string) => ParseResult;
  getFinal: () => ParseResult;
  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,
  loaded: LoadedLangCore | null,
  schema: unknown,
  rootName: string | undefined,
): PlaybackControls {
  const [state, setState] = useState<PlaybackState>(IDLE);
  const [speed, setSpeedState] = useState(1);
  const speedRef = useRef(1);
  // Incremented on pause/reset/start — in-flight timeout callbacks bail when stale.
  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, l: LoadedLangCore) => {
      let convergence: PlaybackState["convergence"] = null;
      let fatal: string | null = null;
      let result: ParseResult | null = null;
      try {
        result = normalizeResult(s.getFinal());
        const oneShot = normalizeResult(l.mod.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],
  );

  /** Parse one chunk, record a trace row, publish state. Returns false on fatal error. */
  const advance = useCallback(
    (s: Session, status: PlaybackStatus): boolean => {
      const chunk = s.chunks[s.index];
      s.prefix += chunk.text;
      let result: ParseResult | null = null;
      let fatal: string | null = null;
      try {
        result = normalizeResult(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;
      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,
      });
      return !fatal;
    },
    [],
  );

  const play = useCallback(
    (s: Session, l: LoadedLangCore) => {
      const gen = generation.current;
      const tick = () => {
        if (generation.current !== gen || session.current !== s) return;
        if (s.index >= s.chunks.length) {
          finish(s, l);
          return;
        }
        if (!advance(s, "playing")) return;
        if (s.index >= s.chunks.length) {
          finish(s, l);
          return;
        }
        schedule();
      };
      const schedule = () => {
        const next = s.chunks[s.index];
        const base = s.strategy === "llm" && next ? next.delayMs : BASE_INTERVAL_MS;
        setTimeout(tick, Math.max(0, base / speedRef.current));
      };
      schedule();
    },
    [advance, finish],
  );

  const start = useCallback(
    ({ strategy, seed }: { strategy: ChunkStrategy; seed: number }) => {
      if (!loaded?.compatible || !loaded.mod.createParser || !code.trim()) return;
      generation.current += 1;

      const emulated = !loaded.capabilities.streaming;
      let push: Session["push"];
      let getFinal: Session["getFinal"];
      if (emulated) {
        // O(n²) full re-parse per chunk — fine at playground scale.
        let last: ParseResult | null = null;
        push = (_chunk, prefix) => {
          last = loaded.mod.createParser!(schema, rootName).parse(prefix);
          return last;
        };
        getFinal = () => last ?? loaded.mod.createParser!(schema, rootName).parse(code);
      } else {
        const sp: StreamParserLike = loaded.mod.createStreamingParser!(schema, rootName);
        push = (chunk) => sp.push(chunk);
        getFinal = () => sp.getResult();
      }

      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, loaded);
    },
    [code, loaded, 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 || !loaded) return;
    generation.current += 1;
    setState((prev) => (prev.status === "paused" ? { ...prev, status: "playing" } : prev));
    play(s, loaded);
  }, [loaded, play]);

  const step = useCallback(() => {
    const s = session.current;
    if (!s || !loaded) return;
    if (s.index >= s.chunks.length) {
      finish(s, loaded);
      return;
    }
    if (advance(s, "paused") && s.index >= s.chunks.length) finish(s, loaded);
  }, [advance, finish, loaded]);

  const reset = useCallback(() => {
    generation.current += 1;
    session.current = null;
    setState(IDLE);
  }, []);

  return { state, start, pause, resume, step, reset, setSpeed, speed };
}