@weasel-js/forge 1.13.0-rc.0 → 1.14.0

package/dist/chunk-STK2AZH2.js

@@ -0,0 +1,11 @@
+export { stableStringify } from '@weasel-js/core';
+
+// src/protocol/messages.ts
+var PROTOCOL_VERSION = 1;
+var DEFAULT_LAYOUT = "padded";
+var PORT_HANDOFF = "weaselforge:port";
+var FRAME_HELLO = "weaselforge:hello";
+
+export { DEFAULT_LAYOUT, FRAME_HELLO, PORT_HANDOFF, PROTOCOL_VERSION };
+//# sourceMappingURL=chunk-STK2AZH2.js.map
+//# sourceMappingURL=chunk-STK2AZH2.js.map

package/dist/chunk-STK2AZH2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol/messages.ts"],"names":[],"mappings":";;;AAEO,IAAM,gBAAA,GAAmB;AAOzB,IAAM,cAAA,GAAyB;AAgG/B,IAAM,YAAA,GAAe;AASrB,IAAM,WAAA,GAAc","file":"chunk-STK2AZH2.js","sourcesContent":["import type { SchemaDescription } from './schema.ts';\n\nexport const PROTOCOL_VERSION = 1;\n\n/** The workshop's toolbar globals as a story reads them, by name. */\nexport type Globals = Readonly<Record<string, unknown>>;\n/** How a story sits in its frame. */\nexport type Layout = 'centered' | 'padded' | 'fullscreen';\n/** The layout a story takes when it names none, in either story format. */\nexport const DEFAULT_LAYOUT: Layout = 'padded';\n/** A frame size a story asks for, in CSS pixels. */\nexport interface Viewport {\n  width: number;\n  height: number;\n}\n/** Where a frame's fault happened: loading the story, rendering it, or reading a message. */\nexport type FaultPhase = 'import' | 'render' | 'protocol';\n\n/** One custom property as the frame found it. */\nexport interface CssVarReport {\n  name: string;\n  value: string;\n  /** Whether a `vars.set` override is in force on it. */\n  overridden: boolean;\n  /** Whether the story reads it, directly or through another property it reads. */\n  used: boolean;\n}\n\n/** Visibility and validation answers, keyed by the config they were computed for. */\nexport interface ConfigAnswers {\n  /** `stableStringify(config)` of the config the frame evaluated. */\n  configKey: string;\n  hidden: string[];\n  errors: Record<string, string[]>;\n}\n\n/** One element axe faulted on, inside the frame's own document. */\nexport interface A11yNode {\n  /** The CSS selectors, outermost first, that reach the element in the frame. */\n  target: readonly string[];\n  html: string;\n  failureSummary?: string;\n  /** On a node axe could not decide: why, as axe's message key (`bgOverlap`, `pseudoContent`, …) and its own sentence. */\n  reason?: { key?: string; message?: string };\n}\n\n/** One axe rule's outcome on the story, with the elements it names. */\nexport interface A11yFinding {\n  id: string;\n  impact: 'minor' | 'moderate' | 'serious' | 'critical' | null;\n  help: string;\n  helpUrl: string;\n  description: string;\n  nodes: readonly A11yNode[];\n}\n\n/** What axe found on one story: the rules it failed, and the ones it could not decide. */\nexport interface A11yReport {\n  violations: readonly A11yFinding[];\n  incomplete: readonly A11yFinding[];\n  /** Rules that passed, and rules no element on the page could be judged by. */\n  passes: number;\n  inapplicable: number;\n}\n\n/** What an axe run in the frame came back with. */\nexport type A11yOutcome = { ok: true; report: A11yReport } | { ok: false; message: string };\n\n/** A message the workshop sends a story's frame. */\nexport type ToFrame =\n  | { type: 'init'; config: unknown; state: unknown; globals: Globals }\n  | { type: 'config'; config: unknown }\n  | { type: 'state'; state: unknown }\n  | { type: 'globals'; globals: Globals }\n  | { type: 'vars.set'; name: string; value: string | null }\n  /** Run axe over the story's own subtree. Answered by `a11y` carrying the same `id`. */\n  | { type: 'a11y.run'; id: string }\n  /** Outlines the elements each `A11yNode.target` reaches, in place of the last ones; an empty list clears. */\n  | { type: 'a11y.highlight'; targets: readonly (readonly string[])[] }\n  /** Scrolls the frame document to `left`, `top` in CSS px: a lens's copy following its trial's frame. */\n  | { type: 'scroll'; left: number; top: number };\n\n/** A message a story's frame sends the workshop. */\nexport type FromFrame =\n  | { type: 'ready'; schema: SchemaDescription; layout: Layout; viewport: Viewport | null }\n  /** Sent once, when the story's first render after `init` has committed. */\n  | { type: 'rendered' }\n  | { type: 'answers'; answers: ConfigAnswers }\n  | { type: 'setConfig'; path: string; value: unknown }\n  | { type: 'setState'; state: unknown }\n  | { type: 'vars'; vars: CssVarReport[] }\n  /** Asks the shell to show story `id` in this frame's trial in place of what it shows now. */\n  | { type: 'open'; id: string }\n  | ({ type: 'a11y'; id: string } & A11yOutcome)\n  /** Where the frame document stands, in CSS px: sent once after `ready`, then whenever it scrolls. */\n  | { type: 'scroll'; left: number; top: number }\n  /** `seq`, on a render fault only: how many `init`/`config`/`state`/`globals` messages the frame had received. */\n  | { type: 'fault'; phase: FaultPhase; message: string; stack?: string; seq?: number };\n\nexport interface Envelope<M> {\n  v: number;\n  msg: M;\n}\n\n/** Posted on the frame's window with the port transferred alongside it, as a `PortHandoff`. */\nexport const PORT_HANDOFF = 'weaselforge:port';\n\n/** What the shell posts with the port: `id` names what the frame shows, a story or an index. */\nexport interface PortHandoff {\n  type: typeof PORT_HANDOFF;\n  id: string;\n}\n\n/** Posted by a frame document to its parent as soon as its entry runs, asking for a port. */\nexport const FRAME_HELLO = 'weaselforge:hello';\n\nexport { stableStringify } from '@weasel-js/core';\n"]}

package/dist/chunk-TT4ZOYB6.js

@@ -0,0 +1,143 @@
+import { useLatest } from '@weasel-js/core';
+import { useTrialClockHandle, useTransportControl } from '@weasel-js/labkit';
+import { createContext, useSyncExternalStore, useMemo, useContext, useCallback } from 'react';
+import { createEmitter } from '@weasel-js/registry';
+import { shownInPass } from '@weasel-js/clock';
+
+// src/story/define.ts
+var NATIVE = /* @__PURE__ */ Symbol.for("weaselforge.native");
+function meta(spec) {
+  return Object.assign({}, spec, { [NATIVE]: "meta" });
+}
+function story(spec) {
+  return Object.assign({}, spec, { [NATIVE]: "story" });
+}
+function isNative(value, kind) {
+  return !!value && typeof value === "object" && value[NATIVE] === kind;
+}
+
+// src/timeline/clockSpec.ts
+var positive = (n) => typeof n === "number" && Number.isFinite(n) && n > 0;
+var lengthOf = (duration) => positive(duration) ? duration : 1;
+var startOf = (start) => typeof start === "number" && Number.isFinite(start) ? start : 0;
+function clockSpecOf(spec) {
+  return {
+    duration: lengthOf(spec.duration),
+    origin: startOf(spec.start),
+    loop: spec.loop ?? true,
+    speed: positive(spec.rate) ? spec.rate : 1
+  };
+}
+function spanOverrideOf(span) {
+  return { duration: lengthOf(span.duration), origin: startOf(span.start) };
+}
+function setLoop(clock, loop) {
+  clock.loop = loop;
+}
+var speeds = /* @__PURE__ */ new WeakMap();
+var speedChanged = createEmitter();
+function subscribeSpeed(clock, listener) {
+  return speedChanged.subscribe((changed) => {
+    if (changed === clock) listener();
+  });
+}
+function ownMoves(clock) {
+  const speed = () => speeds.get(clock) ?? (Math.abs(clock.rate) || clock.speed);
+  return {
+    speed,
+    play() {
+      if (clock.rate !== 0) return;
+      if (clock.ended) clock.seek(0);
+      clock.rate = speed();
+    },
+    pause() {
+      clock.rate = 0;
+    },
+    setSpeed(next) {
+      speeds.set(clock, next);
+      if (clock.rate !== 0) clock.rate = next;
+      else speedChanged.emit(clock);
+    }
+  };
+}
+function shownTime(clock) {
+  return shownInPass(clock.origin, clock.elapsed, clock.duration, clock.loop);
+}
+function seekShown(clock, t) {
+  const within = Number.isNaN(t) ? 0 : Math.min(Math.max(t - clock.origin, 0), clock.duration);
+  clock.seek(within, within >= clock.duration ? "end" : "start");
+}
+
+// src/timeline/context.ts
+var ClockContext = createContext(null);
+function useClock(hook) {
+  const handle = useContext(ClockContext);
+  if (!handle) {
+    throw new Error(
+      `${hook}: this story declares no timeline. Give it \`timeline: { duration }\`, or \`parameters.forge.timeline\` in CSF.`
+    );
+  }
+  return handle;
+}
+function useClockChanges(handle) {
+  return useCallback(
+    (listener) => {
+      const offChange = handle.clock.subscribe(listener);
+      const offFrame = handle.onFrame(listener);
+      const offSpeed = subscribeSpeed(handle.clock, listener);
+      return () => {
+        offChange();
+        offFrame();
+        offSpeed();
+      };
+    },
+    [handle]
+  );
+}
+function usePlayhead() {
+  const handle = useClock("usePlayhead");
+  return useSyncExternalStore(useClockChanges(handle), () => shownTime(handle.clock));
+}
+var validRate = (rate) => Number.isFinite(rate) && rate > 0;
+function usePlayMoves(handle) {
+  const resolved = useTrialClockHandle();
+  const control = useTransportControl(resolved === handle ? void 0 : null);
+  if (control === null) return ownMoves(handle.clock);
+  return { speed: () => control.speed, play: control.play, pause: control.pause, setSpeed: control.setSpeed };
+}
+function useTimeline() {
+  const handle = useClock("useTimeline");
+  const { clock } = handle;
+  const moves = usePlayMoves(handle);
+  const latest = useLatest({ moves });
+  useSyncExternalStore(
+    useClockChanges(handle),
+    () => `${shownTime(clock)}|${clock.rate}|${String(clock.loop)}|${clock.origin}|${clock.duration}|${moves.speed()}`
+  );
+  const time = shownTime(clock);
+  const playing = clock.rate !== 0;
+  const loop = clock.loop !== false;
+  const rate = moves.speed();
+  const { origin, duration } = clock;
+  const actions = useMemo(
+    () => ({
+      play: () => latest.current.moves.play(),
+      pause: () => latest.current.moves.pause(),
+      seek: (t) => seekShown(handle.clock, t),
+      setLoop: (next) => setLoop(handle.clock, next),
+      setRate: (next) => {
+        if (validRate(next)) latest.current.moves.setSpeed(next);
+      },
+      setSpan: (span) => handle.override(span ? spanOverrideOf(span) : null)
+    }),
+    [handle, latest]
+  );
+  return useMemo(
+    () => ({ time, playing, loop, rate, span: { start: origin, end: origin + duration }, ...actions }),
+    [time, playing, loop, rate, origin, duration, actions]
+  );
+}
+
+export { ClockContext, clockSpecOf, isNative, meta, shownTime, story, usePlayhead, useTimeline };
+//# sourceMappingURL=chunk-TT4ZOYB6.js.map
+//# sourceMappingURL=chunk-TT4ZOYB6.js.map

package/dist/chunk-TT4ZOYB6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/story/define.ts","../src/timeline/clockSpec.ts","../src/timeline/moves.ts","../src/timeline/shown.ts","../src/timeline/context.ts"],"names":[],"mappings":"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","file":"chunk-TT4ZOYB6.js","sourcesContent":["import type { MetaSpec, StorySpec } from './types';\n\nexport const NATIVE = Symbol.for('weaselforge.native');\n\n/** Declares a native story file's meta; default-export the result. */\nexport function meta(spec: MetaSpec): MetaSpec {\n  return Object.assign({}, spec, { [NATIVE]: 'meta' as const });\n}\n\n/** Declares one native story; export the result under the story's name. `C` and `S` come from `config` and `state`. */\nexport function story<C = Record<string, never>, S = undefined>(spec: StorySpec<C, S>): StorySpec<C, S> {\n  return Object.assign({}, spec, { [NATIVE]: 'story' as const });\n}\n\nexport function isNative(value: unknown, kind: 'meta' | 'story'): boolean {\n  return !!value && typeof value === 'object' && (value as Record<symbol, unknown>)[NATIVE] === kind;\n}\n","import type { ClockSpec } from '@weasel-js/clock';\nimport type { SpanOverride, TimelineSpec } from './types';\n\nconst positive = (n: number | undefined): n is number => typeof n === 'number' && Number.isFinite(n) && n > 0;\n\n/** A span's length, in ms: anything not a positive finite number stands as 1 ms, so a timeline can never throw. */\nconst lengthOf = (duration: number): number => (positive(duration) ? duration : 1);\n\nconst startOf = (start: number | undefined): number => (typeof start === 'number' && Number.isFinite(start) ? start : 0);\n\n/** The clock a story's timeline declares. It opens paused at the span's start, and loops unless told not to. */\nexport function clockSpecOf(spec: TimelineSpec): ClockSpec {\n  return {\n    duration: lengthOf(spec.duration),\n    origin: startOf(spec.start),\n    loop: spec.loop ?? true,\n    speed: positive(spec.rate) ? spec.rate : 1,\n  };\n}\n\n/** The clock override a story's `setSpan` asks for. */\nexport function spanOverrideOf(span: SpanOverride): { duration: number; origin: number } {\n  return { duration: lengthOf(span.duration), origin: startOf(span.start) };\n}\n","import type { Clock } from '@weasel-js/clock';\nimport { createEmitter } from '@weasel-js/registry';\n\n/** Loops the clock without end, or plays it once. */\nexport function setLoop(clock: Clock, loop: boolean): void {\n  clock.loop = loop;\n}\n\n/** Play, pause and speed, as `useTimeline` asks for them. */\nexport interface PlayMoves {\n  /** Unsigned: what a pause comes back to. */\n  speed(): number;\n  play(): void;\n  pause(): void;\n  setSpeed(speed: number): void;\n}\n\nconst speeds = new WeakMap<Clock, number>();\nconst speedChanged = createEmitter<[Clock]>();\n\n/** Calls `listener` when the speed a pause of `clock` returns to changes outside a transport. */\nexport function subscribeSpeed(clock: Clock, listener: () => void): () => void {\n  return speedChanged.subscribe((changed) => {\n    if (changed === clock) listener();\n  });\n}\n\n/** The moves on a clock no transport works, as outside a lab: the speed a pause returns to is kept here. */\nexport function ownMoves(clock: Clock): PlayMoves {\n  const speed = (): number => speeds.get(clock) ?? (Math.abs(clock.rate) || clock.speed);\n  return {\n    speed,\n    play() {\n      if (clock.rate !== 0) return;\n      // Playing from the end starts over, as a player's play button does.\n      if (clock.ended) clock.seek(0);\n      clock.rate = speed();\n    },\n    pause() {\n      clock.rate = 0;\n    },\n    setSpeed(next) {\n      speeds.set(clock, next);\n      if (clock.rate !== 0) clock.rate = next;\n      else speedChanged.emit(clock);\n    },\n  };\n}\n","import { type Clock, shownInPass } from '@weasel-js/clock';\n\n/** The time a story's playhead shows: the clock's origin plus how far it is into the current pass; see `shownInPass`. */\nexport function shownTime(clock: Clock): number {\n  return shownInPass(clock.origin, clock.elapsed, clock.duration, clock.loop);\n}\n\n/** Moves the playhead to shown time `t`, clamped to the span; the span's end stands as the end of the first pass. */\nexport function seekShown(clock: Clock, t: number): void {\n  const within = Number.isNaN(t) ? 0 : Math.min(Math.max(t - clock.origin, 0), clock.duration);\n  clock.seek(within, within >= clock.duration ? 'end' : 'start');\n}\n","import type { ClockHandle } from '@weasel-js/clock';\nimport { useLatest } from '@weasel-js/core';\nimport { useTransportControl, useTrialClockHandle } from '@weasel-js/labkit';\nimport { createContext, useCallback, useContext, useMemo, useSyncExternalStore } from 'react';\nimport { spanOverrideOf } from './clockSpec';\nimport { ownMoves, type PlayMoves, setLoop, subscribeSpeed } from './moves';\nimport { seekShown, shownTime } from './shown';\nimport type { Span, SpanOverride } from './types';\n\n/** The clock of the story rendering below it; null where the story declares no timeline. */\nexport const ClockContext = createContext<ClockHandle | null>(null);\n\n/** What `useTimeline` hands a story: where its playhead stands, and the moves the transport makes. Times in ms. */\nexport interface StoryTimeline {\n  /** The playhead, in ms, always inside `span`. */\n  time: number;\n  playing: boolean;\n  loop: boolean;\n  rate: number;\n  span: Span;\n  play(): void;\n  pause(): void;\n  seek(time: number): void;\n  setLoop(loop: boolean): void;\n  setRate(rate: number): void;\n  /** Replaces the declared span, for one the story only learns once it runs; null goes back to the declared one. */\n  setSpan(span: SpanOverride | null): void;\n}\n\nfunction useClock(hook: string): ClockHandle {\n  const handle = useContext(ClockContext);\n  if (!handle) {\n    throw new Error(\n      `${hook}: this story declares no timeline. Give it \\`timeline: { duration }\\`, or \\`parameters.forge.timeline\\` in CSF.`,\n    );\n  }\n  return handle;\n}\n\n/** Subscribes to every change of `handle`'s clock: rate, seek, loop and declare, each frame it moves, and a paused\n *  speed change. */\nfunction useClockChanges(handle: ClockHandle): (listener: () => void) => () => void {\n  return useCallback(\n    (listener) => {\n      const offChange = handle.clock.subscribe(listener);\n      const offFrame = handle.onFrame(listener);\n      const offSpeed = subscribeSpeed(handle.clock, listener);\n      return () => {\n        offChange();\n        offFrame();\n        offSpeed();\n      };\n    },\n    [handle],\n  );\n}\n\n/** The story's playhead, in ms. Re-renders only the component calling it, on every move. Throws outside a story that\n *  declares a timeline. */\nexport function usePlayhead(): number {\n  const handle = useClock('usePlayhead');\n  return useSyncExternalStore(useClockChanges(handle), () => shownTime(handle.clock));\n}\n\nconst validRate = (rate: number): boolean => Number.isFinite(rate) && rate > 0;\n\n/** Play, pause and speed through the trial's transport, so the story and the transport share one speed, or on the\n *  clock itself where no transport works it. A transport over another clock goes unread, so its frames re-render\n *  nothing here. */\nfunction usePlayMoves(handle: ClockHandle): PlayMoves {\n  const resolved = useTrialClockHandle();\n  const control = useTransportControl(resolved === handle ? undefined : null);\n  if (control === null) return ownMoves(handle.clock);\n  return { speed: () => control.speed, play: control.play, pause: control.pause, setSpeed: control.setSpeed };\n}\n\n/** The story's whole clock: playhead, span, play state, loop and rate, and the moves on them. Throws outside a story\n *  that declares a timeline. */\nexport function useTimeline(): StoryTimeline {\n  const handle = useClock('useTimeline');\n  const { clock } = handle;\n  const moves = usePlayMoves(handle);\n  const latest = useLatest({ moves });\n  useSyncExternalStore(\n    useClockChanges(handle),\n    () =>\n      `${shownTime(clock)}|${clock.rate}|${String(clock.loop)}|${clock.origin}|${clock.duration}|${moves.speed()}`,\n  );\n  const time = shownTime(clock);\n  const playing = clock.rate !== 0;\n  const loop = clock.loop !== false;\n  const rate = moves.speed();\n  const { origin, duration } = clock;\n\n  const actions = useMemo(\n    () => ({\n      play: () => latest.current.moves.play(),\n      pause: () => latest.current.moves.pause(),\n      seek: (t: number) => seekShown(handle.clock, t),\n      setLoop: (next: boolean) => setLoop(handle.clock, next),\n      setRate: (next: number) => {\n        if (validRate(next)) latest.current.moves.setSpeed(next);\n      },\n      setSpan: (span: SpanOverride | null) => handle.override(span ? spanOverrideOf(span) : null),\n    }),\n    [handle, latest],\n  );\n  return useMemo(\n    () => ({ time, playing, loop, rate, span: { start: origin, end: origin + duration }, ...actions }),\n    [time, playing, loop, rate, origin, duration, actions],\n  );\n}\n"]}

package/dist/{chunk-RKQ277P5.js → chunk-UDEUT7AG.js}

@@ -1,11 +1,12 @@
-import { GLOBALS_KEY, effectiveGlobals, storyConfig, isForgePath, PLAYHEAD_KEY, FOLLOW_APP } from './chunk-3BAM6M26.js';
-import { StoryHost, useNearViewport, IN_VIEW_MARGIN, useHostConditions, createA11yHighlighter, useStoryClock, useClockLoop, scanCssVars, auditElement } from './chunk-35DOPXHZ.js';
-import { ClockContext } from './chunk-L5XM5VKB.js';
+import { GLOBALS_KEY, effectiveGlobals, storyConfig, isForgePath, FOLLOW_APP } from './chunk-FPF2JSWB.js';
+import { StoryHost, useHostConditions, createA11yHighlighter, scanCssVars, auditElement } from './chunk-PGLOYXDP.js';
+import { ClockContext } from './chunk-TT4ZOYB6.js';
 import { createEmitter } from '@weasel-js/registry';
 import { createContext, memo, useContext, useCallback, useSyncExternalStore, useMemo, useId, useState, useRef, useLayoutEffect, useEffect } from 'react';
 import { useLatest } from '@weasel-js/core';
-import { usePersistedState, TrialIdContext, useTrialTitle, LabBoundary } from '@weasel-js/labkit';
+import { usePersistedState, TrialIdContext, useTrialClockHandle, useTrialTitle, LabBoundary } from '@weasel-js/labkit';
 import { OverlayPortalProvider } from '@weasel-js/ui/portal-host';
+import { useNearViewport } from '@weasel-js/react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { createPortal } from 'react-dom';
 import { withValueAtPath } from '@weasel-js/labkit/config';
@@ -46,6 +47,9 @@ function useTrialFrame(trialId) {
   return useSyncExternalStore(subscribe, read, read);
 }
 var StoryGlobalsContext = createContext({});
+
+// src/shell/inViewMargin.ts
+var IN_VIEW_MARGIN = "50%";
 var NONE = {};
 function useCssOverrides() {
   return usePersistedState("fg-css-overrides", NONE, { scope: "trial" });
@@ -90,6 +94,95 @@ function StoryScroller({ children }) {
     }
   );
 }
+function createStoryHosts() {
+  const refs = /* @__PURE__ */ new Map();
+  const shows = /* @__PURE__ */ new Map();
+  const ref = (trialId) => {
+    let held = refs.get(trialId);
+    if (!held) {
+      held = { current: null };
+      refs.set(trialId, held);
+    }
+    return held;
+  };
+  return {
+    ref,
+    attach(trialId, host, show) {
+      const held = ref(trialId);
+      held.current = host;
+      if (show) shows.set(trialId, { host, show });
+      return () => {
+        if (held.current === host) held.current = null;
+        if (shows.get(trialId)?.host === host) shows.delete(trialId);
+      };
+    },
+    show(trialId) {
+      return shows.get(trialId)?.show() ?? Promise.resolve(() => {
+      });
+    }
+  };
+}
+var StoryHostsContext = createContext(null);
+function useStoryHost(trialId, host, show) {
+  const hosts = useContext(StoryHostsContext);
+  useLayoutEffect(
+    () => host && hosts && trialId ? hosts.attach(trialId, host, show) : void 0,
+    [host, hosts, trialId, show]
+  );
+}
+function afterPaint(host, done) {
+  let canceled = false;
+  const finish = () => {
+    if (!canceled) done();
+  };
+  const { fonts } = host.ownerDocument;
+  if (!fonts) finish();
+  else {
+    const frame = () => requestAnimationFrame(finish);
+    void fonts.ready.then(frame, frame);
+  }
+  return () => {
+    canceled = true;
+  };
+}
+function useStoryShow(host, inView) {
+  const [held, setHeld] = useState(0);
+  const [waiters] = useState(() => []);
+  const live = inView || held > 0;
+  const show = useCallback(
+    () => new Promise((resolve) => {
+      let released = false;
+      const release = () => {
+        if (released) return;
+        released = true;
+        setHeld((n) => n - 1);
+      };
+      waiters.push(() => resolve(release));
+      setHeld((n) => n + 1);
+    }),
+    [waiters]
+  );
+  useEffect(() => {
+    if (!host || !live || waiters.length === 0) return;
+    const waiting = waiters.splice(0);
+    let settled = false;
+    const cancel = afterPaint(host, () => {
+      settled = true;
+      for (const resolve of waiting) resolve();
+    });
+    return () => {
+      cancel();
+      if (!settled) waiters.unshift(...waiting);
+    };
+  }, [host, live, held, waiters]);
+  useEffect(
+    () => () => {
+      for (const resolve of waiters.splice(0)) resolve();
+    },
+    [waiters]
+  );
+  return { live, show };
+}
 var VARS_SETTLE_MS = 100;
 function StoryContent({ host, children }) {
   return /* @__PURE__ */ jsx(LabBoundary, { children: /* @__PURE__ */ jsx(OverlayPortalProvider, { container: host, contained: true, children }) });
@@ -107,7 +200,15 @@ function TrialHost({ layout, setup, config, children, hostRef, onRendered, copy
   const [host, setHost] = useState(null);
   const elementRef = useRef(null);
   const inView = useNearViewport(elementRef, IN_VIEW_MARGIN);
+  const { live, show } = useStoryShow(host, inView);
   const [pending, setPending] = useState(true);
+  const [rendered] = useState(() => {
+    let resolve;
+    const promise = new Promise((r) => {
+      resolve = r;
+    });
+    return { promise, resolve };
+  });
   const latest = useLatest({ onRendered: copy ? void 0 : onRendered });
   const overridesRef = useHostConditions(host, { hostId, globals, overrides: persisted, setup });
   useLayoutEffect(() => {
@@ -140,6 +241,7 @@ function TrialHost({ layout, setup, config, children, hostRef, onRendered, copy
       if (lastVars?.some((v) => v.name === msg.name)) scan();
     };
     const audit = async () => {
+      await rendered.promise;
       const outcome = await auditElement(host, { page: false });
       if (trialId) frames?.reportA11y(trialId, outcome);
       return outcome;
@@ -152,28 +254,18 @@ function TrialHost({ layout, setup, config, children, hostRef, onRendered, copy
       mutations?.disconnect();
       clearTimeout(settleTimer);
     };
-  }, [host, hostId, trialId, frames, copy, overridesRef]);
+  }, [host, hostId, trialId, frames, copy, overridesRef, rendered]);
+  useStoryHost(trialId, copy ? null : host, show);
   const announced = useRef(false);
   useEffect(() => {
-    if (!host || !inView || announced.current) return;
-    let canceled = false;
-    const done = () => {
-      if (canceled) return;
+    if (!host || !live || announced.current) return;
+    return afterPaint(host, () => {
       announced.current = true;
+      rendered.resolve();
       setPending(false);
       latest.current.onRendered?.();
-    };
-    const { fonts } = host.ownerDocument;
-    if (!fonts) {
-      done();
-      return;
-    }
-    const afterPaint = () => requestAnimationFrame(done);
-    void fonts.ready.then(afterPaint, afterPaint);
-    return () => {
-      canceled = true;
-    };
-  }, [host, inView, latest]);
+    });
+  }, [host, live, latest, rendered]);
   return /* @__PURE__ */ jsx(
     "div",
     {
@@ -187,54 +279,10 @@ function TrialHost({ layout, setup, config, children, hostRef, onRendered, copy
       "data-fg-copy": copy ? "" : void 0,
       "data-fg-layout": layout,
       "data-pending": pending || void 0,
-      children: /* @__PURE__ */ jsx(StoryScroller, { children: host && inView ? /* @__PURE__ */ jsx(StoryContent, { host, children: children(globals) }) : null })
+      children: /* @__PURE__ */ jsx(StoryScroller, { children: host && live ? /* @__PURE__ */ jsx(StoryContent, { host, children: children(globals) }) : null })
     }
   );
 }
-function createTrialClocks() {
-  const clocks = /* @__PURE__ */ new Map();
-  const changed = createEmitter();
-  const notify = changed.emit;
-  return {
-    publish(trialId, clock) {
-      clocks.set(trialId, clock);
-      notify();
-      return () => {
-        if (clocks.get(trialId) !== clock) return;
-        clocks.delete(trialId);
-        notify();
-      };
-    },
-    get: (trialId) => clocks.get(trialId) ?? null,
-    subscribe: changed.subscribe
-  };
-}
-var TrialClocksContext = createContext(null);
-var NEVER = () => () => {
-};
-var NONE2 = () => null;
-function useTrialClock(trialId) {
-  const clocks = useContext(TrialClocksContext);
-  return useSyncExternalStore(clocks?.subscribe ?? NEVER, clocks ? () => clocks.get(trialId) : NONE2);
-}
-function usePersistedPlayhead(clock, persisted, write) {
-  const written = useRef(persisted);
-  const latestWrite = useLatest(write);
-  useEffect(() => {
-    if (!clock || persisted === written.current) return;
-    written.current = persisted;
-    clock.request(persisted);
-  }, [clock, persisted]);
-  useEffect(() => {
-    if (!clock) return;
-    return clock.subscribe(() => {
-      const { playing, time } = clock.get();
-      if (playing || clock.pending() !== null || time === written.current) return;
-      written.current = time;
-      latestWrite.current(time);
-    });
-  }, [clock, latestWrite]);
-}
 var StoryBody = memo(function StoryBody2({ story, config, setConfig, state, setState, globals, decorators, resetKey, onError }) {
   const storyCtx = { config, setConfig, state, setState, globals, title: story.title, name: story.name };
   return /* @__PURE__ */ jsx(StoryHost, { story, ctx: storyCtx, decorators, resetKey, onError });
@@ -288,7 +336,7 @@ function resolveContextOf(lab) {
   const prefersDark = globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches ?? false;
   return { declarations: lab.declarations, modeGlobal: lab.modeGlobal, prefersDark, labMode: lab.mode };
 }
-var NONE3 = [];
+var NONE2 = [];
 function createLiveLenses() {
   const requests = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
@@ -305,7 +353,7 @@ function createLiveLenses() {
       let found = byTrial.get(trialId);
       if (!found) {
         const mine = [...requests.values()].filter((r) => r.hit.trialId === trialId);
-        found = mine.length === 0 ? NONE3 : mine;
+        found = mine.length === 0 ? NONE2 : mine;
         byTrial.set(trialId, found);
       }
       return found;
@@ -421,8 +469,9 @@ function LiveCopies(props) {
 function FrameLensCopy({ request, trialId, trialConfig, children }) {
   const globals = useCopyGlobals(request, trialConfig);
   const id = copyId(trialId, request);
-  const { args } = request;
-  const copy = useMemo(() => ({ id, globals, args }), [id, globals, args]);
+  const { args, factor } = request;
+  const main = request.hit.host;
+  const copy = useMemo(() => ({ id, main, globals, args, factor }), [id, main, globals, args, factor]);
   return /* @__PURE__ */ jsx(LensPortal, { request, children: children(copy) });
 }
 function FrameCopies({ lenses, trialId, ...props }) {
@@ -457,15 +506,11 @@ function StoryTrial({ story, setup, ctx, hostRef, onRendered, onError }) {
   }, [latestRef]);
   const setState = useCallback((next) => latestRef.current.setState(next), [latestRef]);
   const trialId = useContext(TrialIdContext);
-  const clocks = useContext(TrialClocksContext);
   const ownHost = useRef(null);
   const host = hostRef ?? ownHost;
-  const kept = ctx.config?.[PLAYHEAD_KEY];
-  const persisted = typeof kept === "number" && Number.isFinite(kept) ? kept : null;
-  const clock = useStoryClock(story.timeline?.(config) ?? null, () => persisted);
-  useClockLoop(clock, host);
-  usePersistedPlayhead(clock, persisted, (time) => latestRef.current.setConfig(PLAYHEAD_KEY, time));
-  useEffect(() => clock && clocks && trialId ? clocks.publish(trialId, clock) : void 0, [clock, clocks, trialId]);
+  const spec = story.timeline?.(config) ?? null;
+  const trialClock = useTrialClockHandle();
+  const clock = spec ? trialClock : null;
   const decorators = setup.decorators ?? NO_DECORATORS;
   const latestError = useLatest(onError);
   const reportError = useCallback((error) => latestError.current?.(error), [latestError]);
@@ -496,6 +541,6 @@ function StoryTrial({ story, setup, ctx, hostRef, onRendered, onError }) {
   ] });
 }
 
-export { LiveCopies, LiveFrameCopies, LiveLensesContext, StoryGlobalsContext, StoryTrial, TrialClocksContext, TrialFramesContext, TrialHost, createLiveLenses, createTrialClocks, createTrialFrames, describeLens, resolveComparison, resolveContextOf, scrollerOf, trialAt, useCopyConfig, useCssOverrides, useTrialClock, useTrialFrame, withArgs };
-//# sourceMappingURL=chunk-RKQ277P5.js.map
-//# sourceMappingURL=chunk-RKQ277P5.js.map
+export { IN_VIEW_MARGIN, LiveCopies, LiveFrameCopies, LiveLensesContext, StoryGlobalsContext, StoryHostsContext, StoryTrial, TrialFramesContext, TrialHost, createLiveLenses, createStoryHosts, createTrialFrames, describeLens, resolveComparison, resolveContextOf, scrollerOf, trialAt, useCopyConfig, useCssOverrides, useTrialFrame, withArgs };
+//# sourceMappingURL=chunk-UDEUT7AG.js.map
+//# sourceMappingURL=chunk-UDEUT7AG.js.map