@cueplusplus/ui 0.13.0

package/dist/elements/replay.d.ts

@@ -0,0 +1,217 @@
+import * as React from "react";
+//#region src/elements/replay.d.ts
+/**
+ * The run states a frame can be labelled with.
+ *
+ * Authored, never derived. Nothing in this library emits a run-state event —
+ * the elements family is told `running` and `open` by its caller, and a
+ * scripted thread has no clock of its own — so the only honest place for "what
+ * was happening here" is the frame itself. Seven words, chosen to cover what
+ * the teardowns actually show a person: two kinds of waiting (`queued` before
+ * the model has the turn, `thinking` while it holds it), two kinds of work
+ * (`tool-call`, `streaming`), the one state that is waiting on a *human*
+ * (`awaiting-approval`), and the two endings a transcript really has.
+ */
+type ReplayState = "queued" | "thinking" | "tool-call" | "awaiting-approval" | "streaming" | "cancelled" | "done";
+/** Every state, in the order a run normally passes through them. */
+declare const REPLAY_STATES: readonly ["queued", "thinking", "tool-call", "awaiting-approval", "streaming", "cancelled", "done"];
+/**
+ * One frame of a filmstrip: a whole scene, how long it is held, and what the
+ * run was doing while it was on screen.
+ *
+ * `scene` is the whole surface, never a delta from the frame before it. That is
+ * the property the transport is built on — seeking to frame *n* is
+ * `frames[n].scene` and nothing else, so a frame reached by scrubbing renders
+ * identically to the same frame reached by playing, and neither can drift from
+ * the other. A player whose frames accumulated (the way a typed terminal
+ * accumulates printed lines inside its own closure) can be played and it can be
+ * restarted, but it can never be scrubbed.
+ */
+interface ReplayFrame {
+  /**
+   * The surface at this point in the run — everything on screen, not the part
+   * that changed.
+   *
+   * Optional so that a script can be authored for {@link useReplay} alone,
+   * where the caller draws the scene from the index itself. A frame with no
+   * scene draws nothing in {@link ReplayPlayer}.
+   */
+  scene?: React.ReactNode;
+  /**
+   * How long this frame is held before the next one replaces it, in
+   * milliseconds of *script* time — the rate multiplier is applied on top, so a
+   * 400 ms hold is 200 ms of wall clock at 2×.
+   *
+   * The last frame's hold is never spent: the run rests there.
+   */
+  hold: number;
+  /** What the run was doing while this frame was on screen. */
+  label: ReplayState;
+  /** One short line naming what changed here, shown beside the state chip. */
+  caption?: string;
+}
+/**
+ * A filmstrip and its name.
+ *
+ * An object rather than a bare array because a script is a piece of content — a
+ * fixture catalogue hands one to a gallery page, a bench, and a test, and the
+ * three want to agree on what it is called.
+ */
+interface ReplayScript {
+  /** The frames, in order. */
+  frames: readonly ReplayFrame[];
+  /** What this run is called: the transport's accessible name unless the player is given a `label`. */
+  title?: string;
+}
+/** Everything a caller needs to drive a filmstrip, and everything it needs to draw one. */
+interface ReplayTransport {
+  /** The frame on screen, or `undefined` for an empty script. */
+  frame: ReplayFrame | undefined;
+  /** Its index. */
+  index: number;
+  /** How many frames the script has. */
+  count: number;
+  /**
+   * The whole run's length in script milliseconds.
+   *
+   * The last frame's hold is not part of it: the run rests there rather than
+   * spending it. A duration of zero is a script nothing can be played through —
+   * one frame, or a filmstrip whose holds are all zero — and the player's
+   * position controls stay live while its play control does not.
+   */
+  duration: number;
+  /** The authored state of the frame on screen; `queued` when there is no frame. */
+  state: ReplayState;
+  /** Whether the clock is running. Always `false` under reduced motion. */
+  playing: boolean;
+  /** Whether the reader asked for reduced motion, in which case nothing is ever scheduled. */
+  reduced: boolean;
+  /** The current rate multiplier. */
+  rate: number;
+  /** Start the clock, from the beginning again if the run has already finished. */
+  play: () => void;
+  /** Stop the clock, keeping the unspent part of the current frame's hold. */
+  pause: () => void;
+  /** Pause if playing, play if not. */
+  toggle: () => void;
+  /** Move by whole frames — and stop, because stepping while a clock runs is not a position. */
+  step: (delta?: number) => void;
+  /** Jump to a frame, playing or paused. Pure: the frame does not know how it was reached. */
+  seek: (index: number) => void;
+  /** Back to the first frame, playing again unless motion is reduced. */
+  restart: () => void;
+  /** Change the multiplier without losing the playhead. */
+  setRate: (rate: number) => void;
+}
+/** What {@link useReplay} accepts beyond the script itself. */
+interface ReplayOptions {
+  /** Start the clock on mount. Default `true`; ignored under reduced motion. */
+  autoPlay?: boolean;
+  /**
+   * The frame to open on — the seat a deep link asks for.
+   *
+   * Left unset, playback opens on the first frame and a reduced-motion reader
+   * opens on the last. Set, it wins in both modes: an explicit request for a
+   * frame is a request for that frame, whatever the motion preference is.
+   */
+  startAt?: number;
+  /** The rate multiplier to start at. Default `1`. */
+  rate?: number;
+}
+/**
+ * A filmstrip, a clock and a set of controls — without the controls.
+ *
+ * This is {@link ReplayPlayer} with its chrome removed, for a page that wants
+ * to draw its own transport (a state timeline, a keyboard shortcut, a play
+ * button somewhere else on the page) or to render the scene itself rather than
+ * from `frame.scene`.
+ *
+ * **One clock, not a chain of timeouts.** Every existing player in this
+ * repository schedules the next frame with `setTimeout(step, hold)`, which
+ * makes pause impossible: the time already spent inside the in-flight timeout
+ * is unrecoverable, so a resume can only start the hold again. Here the
+ * playhead is a number of *script* milliseconds and wall time reaches it
+ * through one origin — `base + (now() - origin) * rate` — so pausing is
+ * "write down the playhead", resuming is "take a new origin", and the unspent
+ * 380 ms of a 400 ms hold is still 380 ms on the other side of the pause. The
+ * same identity is what makes the rate multiplier exact rather than
+ * approximate, and what makes a seek and a play land on the same frame.
+ *
+ * **Reduced motion is a mode, not a fallback.** Under
+ * `prefers-reduced-motion: reduce` no frame is ever scheduled — not scheduled
+ * and hidden, not scheduled at speed, not scheduled at all — and the transport
+ * opens on the resting frame instead. Every control except play and rate keeps
+ * working, so a reader who has asked for stillness can still step through the
+ * run one frame at a time and read every state it passes through. That is
+ * strictly more than the two older players in this library offer, which show
+ * the end and stop.
+ *
+ * @example
+ * const { frame, index, playing, toggle, seek } = useReplay(SCRIPT);
+ * return <Thread messages={MESSAGES[index]!} onClick={toggle} />;
+ * @example
+ * // Deep-linked at a frame, paused, and half speed.
+ * const replay = useReplay(SCRIPT, { startAt: 17, autoPlay: false, rate: 0.5 });
+ */
+declare function useReplay(script: ReplayScript, options?: ReplayOptions): ReplayTransport;
+interface ReplayPlayerProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** The filmstrip to play. */
+  script: ReplayScript;
+  /** Start the clock on mount. Default `true`; ignored under reduced motion. */
+  autoPlay?: boolean;
+  /** The frame to open on — the seat a deep link asks for. Unset opens on the first frame, or on the last for a reduced-motion reader. */
+  startAt?: number;
+  /** The rate multiplier to start at. Default `1`. */
+  rate?: number;
+  /** The rates the rate control cycles through. Default `[1, 2, 4, 0.5]`. */
+  rates?: readonly number[];
+  /** Accessible name for the transport. Defaults to the script's title, then to "Replay". */
+  label?: string;
+  /** Extra classes, merged over the root's own. */
+  className?: string;
+}
+/**
+ * A scripted run, with a transport: play, pause, step, scrub, restart, rate.
+ *
+ * The player is a controller over a filmstrip rather than an animation of its
+ * own. Every frame of a {@link ReplayScript} carries the whole scene, so the
+ * component's entire rendering rule is `frames[index].scene` — which is what
+ * makes the position controls honest: frame 12 reached by scrubbing is the same
+ * DOM as frame 12 reached by watching, because there is no accumulated state
+ * for the two paths to disagree about.
+ *
+ * The transport is assembled from shipped cue components — `IconButton`s, a
+ * `Slider` for the scrubber, a `Chip` for the state — and painted with cue's
+ * own metrics even when the scene inside it is an `AgentSurface` island at
+ * upstream fidelity. That is deliberate: the chrome belongs to the console
+ * showing the run, not to the run.
+ *
+ * The playback state is legible from outside, the way `TerminalFrame` publishes
+ * `data-simulating`: `data-replay-state` carries the current frame's authored
+ * label, `data-replay-playing` says whether the clock is running, and
+ * `data-replay-frame` is the index — enough for a stylesheet, a screenshot
+ * harness or a test to say "show me the awaiting-approval frame" without
+ * reaching into React.
+ *
+ * Under `prefers-reduced-motion: reduce` the player opens on the resting frame
+ * and schedules nothing, but the step and scrub controls keep working: play and
+ * rate are the only two affordances that go away, because they are the only two
+ * that mean "move on their own".
+ *
+ * @example
+ * const SCRIPT: ReplayScript = {
+ *   title: "Patching universe 3",
+ *   frames: [
+ *     { scene: <ToolCall label="Reading the plot" running />, hold: 600, label: "tool-call" },
+ *     { scene: <StreamingText segments={ANSWER} />, hold: 400, label: "streaming" },
+ *     { scene: <StreamingText segments={ANSWER} settled />, hold: 0, label: "done" },
+ *   ],
+ * };
+ * <ReplayPlayer script={SCRIPT} />
+ * @example
+ * // Opened at a frame from the URL, paused, at half speed.
+ * <ReplayPlayer script={SCRIPT} startAt={17} autoPlay={false} rate={0.5} />
+ */
+declare const ReplayPlayer: React.ForwardRefExoticComponent<ReplayPlayerProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { REPLAY_STATES, ReplayFrame, ReplayOptions, ReplayPlayer, ReplayPlayerProps, ReplayScript, ReplayState, ReplayTransport, useReplay };