waygraph 0.15.25 → 0.15.26

package/dist/highlights/css.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The `#wg-ring` / `#wg-ring-label` CSS (tone/size/weight variants) - the
+ * actual visual language `cli.ts`'s own demo stepper paints with. Extracted
+ * here (not left as a private `cli.ts` constant) so anything else wanting the
+ * SAME "waygraph vision" ring can import pure CSS text, not the rendering
+ * engine around it - `cli.ts` runs `main().catch(...)` unconditionally at
+ * module load with no `import.meta.url` guard, so importing anything from it
+ * is unsafe as a library dependency (see `pilot-overlay.ts`'s own doc
+ * comment for the same reasoning re: the badge/panel). This file has always
+ * been the pure, side-effect-free home for tone/size/weight - the CSS that
+ * renders them belongs alongside it for the same reason. `cli.ts` imports
+ * this constant instead of keeping its own duplicate copy.
+ */
+export declare const WAYGRAPH_RING_CSS: string;

package/dist/highlights/css.js

@@ -0,0 +1,58 @@
+// Split out of the former 2,100-line highlights.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+/**
+ * The `#wg-ring` / `#wg-ring-label` CSS (tone/size/weight variants) - the
+ * actual visual language `cli.ts`'s own demo stepper paints with. Extracted
+ * here (not left as a private `cli.ts` constant) so anything else wanting the
+ * SAME "waygraph vision" ring can import pure CSS text, not the rendering
+ * engine around it - `cli.ts` runs `main().catch(...)` unconditionally at
+ * module load with no `import.meta.url` guard, so importing anything from it
+ * is unsafe as a library dependency (see `pilot-overlay.ts`'s own doc
+ * comment for the same reasoning re: the badge/panel). This file has always
+ * been the pure, side-effect-free home for tone/size/weight - the CSS that
+ * renders them belongs alongside it for the same reason. `cli.ts` imports
+ * this constant instead of keeping its own duplicate copy.
+ */
+export const WAYGRAPH_RING_CSS = "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
+    "border:2.5px solid #7C3AED;border-radius:10px;" +
+    // Opacity fade only - NEVER transition border-color/box-shadow. Tone swaps
+    // (auto gray -> planned purple -> warning yellow) must snap instantly;
+    // color transitions read as a muddy gray/purple/yellow morph on ring 2+.
+    "box-shadow:0 0 0 4px rgba(124,58,237,.16);transition:opacity .3s ease;}" +
+    // Planned (stubs / fixtures / YAP / instruction.highlights) = purple.
+    // Automation (verify fallback, unmatched fill/click) = gray - operators
+    // can ignore engine checks and watch purple + semantic tones.
+    "#wg-ring[data-tone=planned]{border-color:#7C3AED;box-shadow:0 0 0 4px rgba(124,58,237,.16);}" +
+    "#wg-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}" +
+    "#wg-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}" +
+    "#wg-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
+    "#wg-ring[data-tone=danger]{border-color:#EF4444;box-shadow:0 0 0 4px rgba(239,68,68,.22);}" +
+    "#wg-ring[data-tone=success]{border-color:#22C55E;box-shadow:0 0 0 4px rgba(34,197,94,.22);}" +
+    // Real, direct user request: a visible color distinction between a real
+    // Playwright-driven action (auto gray, unchanged) and a pure DOM
+    // inspection (this - orange).
+    "#wg-ring[data-tone=orange]{border-color:#F97316;box-shadow:0 0 0 4px rgba(249,115,22,.22);}" +
+    // A real element, not a ::after pseudo-element - a pseudo-element's
+    // position is CSS-relative to the ring's own box (left:0 always meant
+    // "the ring's own left edge"), so it had no way to be clamped back onto
+    // screen when that box sat near a viewport edge - the label's text just
+    // ran off, invisibly, with no overflow guard at all. A real sibling can
+    // be measured (its actual rendered width) and repositioned in JS -
+    // pushed back onto screen, same width, never shrunk. See
+    // window.__wgPositionRing in cli.ts's own installOverlay.
+    "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
+    "max-width:min(360px,70vw);white-space:normal;padding:6px 10px;border-radius:7px;background:#7C3AED;color:#fff;" +
+    "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease;}" +
+    "#wg-ring-label[data-tone=planned]{background:#7C3AED;color:#fff;}" +
+    "#wg-ring-label[data-tone=auto]{background:#6B7280;color:#fff;}" +
+    "#wg-ring-label[data-tone=info]{background:#2563EB;color:#fff;}" +
+    "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
+    "#wg-ring-label[data-tone=danger]{background:#DC2626;color:#fff;}" +
+    "#wg-ring-label[data-tone=success]{background:#16A34A;color:#fff;}" +
+    "#wg-ring-label[data-tone=orange]{background:#EA580C;color:#fff;}" +
+    // size: ring pad + label font; weight: label boldness
+    "#wg-ring[data-size=sm]{border-width:1.5px;border-radius:8px;}" +
+    "#wg-ring[data-size=lg]{border-width:4px;border-radius:12px;}" +
+    "#wg-ring-label[data-size=sm]{font-size:10px;line-height:1.25;padding:4px 7px;border-radius:5px;}" +
+    "#wg-ring-label[data-size=lg]{font-size:16px;line-height:1.35;padding:8px 14px;border-radius:9px;max-width:min(480px,85vw);}" +
+    "#wg-ring-label[data-weight=bold]{font-weight:800;}" +
+    "#wg-ring-label[data-weight=normal]{font-weight:600;}";

package/dist/highlights/demo-pace.d.ts

@@ -0,0 +1,56 @@
+import type { DemoPace, FixtureDurationFields } from "./types.js";
+/** Default fixture dwell when `duration: true`. */
+export declare const FIXTURE_DURATION_MS_DEFAULT = 2000;
+/** Default fixture dwell under `--fast` when duration is enabled. */
+export declare const FIXTURE_DURATION_FAST_MS_DEFAULT = 600;
+/** Default fixture dwell under demo pace `slow` (gaps / wrongs review). */
+export declare const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
+/** @deprecated Prefer FIXTURE_DURATION_MS_DEFAULT */
+export declare const SLIDE_DURATION_MS_DEFAULT = 2000;
+/** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
+export declare const SLIDE_DURATION_FAST_MS_DEFAULT = 600;
+export declare function normalizeDemoPace(raw: unknown): DemoPace;
+/** Named / numeric pace -> scale vs normal (1 = normal). Absolute ms (>20) maps via default dwell. */
+export declare function demoPaceScale(pace: DemoPace): number;
+export declare function demoPaceIsBlitz(pace: DemoPace): boolean;
+/** True when pace should use the short-gate / fast fixture path (not slow authored). */
+export declare function demoPaceIsFast(pace: DemoPace): boolean;
+export declare function demoPaceIsSlow(pace: DemoPace): boolean;
+/** Autoplay / Next-gate ms for this pace (base is WAYGRAPH_AUTOPLAY_MS or 1800). */
+export declare function demoPaceGateMs(pace: DemoPace, baseAutoplayMs: number): number;
+/**
+ * Short chip for the demo panel (e.g. `2.5x`, `4500ms`, `slow`).
+ * Always printable - numbers speak in the UI, not only in code.
+ */
+export declare function formatDemoPaceBadge(pace: DemoPace, baseAutoplayMs?: number): string;
+/**
+ * Loud one-line pace description for panel + console
+ * (e.g. `pace 2.5x (~4500ms gates)` / `pace 4500ms gates (~2.25x)`).
+ */
+export declare function formatDemoPaceLabel(pace: DemoPace, baseAutoplayMs?: number): string;
+/**
+ * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
+ * or `null` when duration is unset (caller keeps legacy timing).
+ *
+ * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`
+ * (`gatesFast`). `--fast` only shortens when pace is unset/normal.
+ */
+export declare function resolveFixtureDwellMs(fixture: FixtureDurationFields, opts?: {
+    gatesFast?: boolean;
+    pace?: DemoPace;
+}): number | null;
+/** @deprecated Prefer {@link resolveFixtureDwellMs} */
+export declare function resolveSlideDwellMs(slide: FixtureDurationFields, opts?: {
+    gatesFast?: boolean;
+    pace?: DemoPace;
+}): number | null;
+/**
+ * Effective demo pace for a step: block override > flow episode > normal.
+ * Opaque FF / wasFastForward always win as blitz.
+ */
+export declare function resolveStepDemoPace(opts: {
+    blockPace?: DemoPace | string | number | null;
+    flowPace?: DemoPace | string | number | null;
+    fastForward?: boolean;
+    wasFastForward?: boolean;
+}): DemoPace;

package/dist/highlights/demo-pace.js

@@ -0,0 +1,184 @@
+/** Default fixture dwell when `duration: true`. */
+export const FIXTURE_DURATION_MS_DEFAULT = 2000;
+/** Default fixture dwell under `--fast` when duration is enabled. */
+export const FIXTURE_DURATION_FAST_MS_DEFAULT = 600;
+/** Default fixture dwell under demo pace `slow` (gaps / wrongs review). */
+export const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
+/** @deprecated Prefer FIXTURE_DURATION_MS_DEFAULT */
+export const SLIDE_DURATION_MS_DEFAULT = FIXTURE_DURATION_MS_DEFAULT;
+/** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
+export const SLIDE_DURATION_FAST_MS_DEFAULT = FIXTURE_DURATION_FAST_MS_DEFAULT;
+export function normalizeDemoPace(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw) && raw > 0)
+        return raw;
+    if (typeof raw === "string") {
+        const t = raw.trim().toLowerCase();
+        if (t === "blitz" || t === "ff")
+            return "blitz";
+        if (t === "fast" || t === "quick")
+            return "fast";
+        if (t === "slow" || t === "careful" || t === "review")
+            return "slow";
+        if (t === "normal" || t === "default" || t === "1x")
+            return "normal";
+        // "2x" / "0.5x"
+        if (t.endsWith("x")) {
+            const n = Number(t.slice(0, -1));
+            if (Number.isFinite(n) && n > 0)
+                return n;
+        }
+        const n = Number(t);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return "normal";
+}
+/** Named / numeric pace -> scale vs normal (1 = normal). Absolute ms (>20) maps via default dwell. */
+export function demoPaceScale(pace) {
+    if (typeof pace === "number") {
+        if (pace > 20)
+            return Math.min(10, Math.max(0.05, pace / FIXTURE_DURATION_MS_DEFAULT));
+        return Math.min(10, Math.max(0.05, pace));
+    }
+    if (pace === "blitz")
+        return 0.05;
+    if (pace === "fast")
+        return 0.33;
+    if (pace === "slow")
+        return 2;
+    return 1;
+}
+export function demoPaceIsBlitz(pace) {
+    return pace === "blitz" || (typeof pace === "number" && pace > 0 && pace <= 0.1);
+}
+/** True when pace should use the short-gate / fast fixture path (not slow authored). */
+export function demoPaceIsFast(pace) {
+    if (demoPaceIsBlitz(pace))
+        return true;
+    if (pace === "fast")
+        return true;
+    if (typeof pace === "number" && pace <= 20)
+        return pace < 0.75;
+    return false;
+}
+export function demoPaceIsSlow(pace) {
+    if (pace === "slow")
+        return true;
+    if (typeof pace === "number") {
+        if (pace > 20)
+            return pace >= 3000;
+        return pace > 1.25;
+    }
+    return false;
+}
+/** Autoplay / Next-gate ms for this pace (base is WAYGRAPH_AUTOPLAY_MS or 1800). */
+export function demoPaceGateMs(pace, baseAutoplayMs) {
+    if (demoPaceIsBlitz(pace))
+        return Math.min(80, baseAutoplayMs);
+    if (typeof pace === "number" && pace > 20) {
+        return Math.min(30000, Math.max(80, Math.round(pace)));
+    }
+    const scale = demoPaceScale(pace);
+    return Math.min(30000, Math.max(80, Math.round(baseAutoplayMs * scale)));
+}
+/**
+ * Short chip for the demo panel (e.g. `2.5x`, `4500ms`, `slow`).
+ * Always printable - numbers speak in the UI, not only in code.
+ */
+export function formatDemoPaceBadge(pace, baseAutoplayMs = 1800) {
+    const p = normalizeDemoPace(pace);
+    if (typeof p === "number" && p > 20)
+        return `${Math.round(p)}ms`;
+    if (typeof p === "number") {
+        const s = Number.isInteger(p) ? String(p) : String(Math.round(p * 100) / 100);
+        return `${s}x`;
+    }
+    if (p === "blitz")
+        return "blitz";
+    if (p === "fast")
+        return "fast";
+    if (p === "slow")
+        return "slow";
+    void baseAutoplayMs;
+    return "1x";
+}
+/**
+ * Loud one-line pace description for panel + console
+ * (e.g. `pace 2.5x (~4500ms gates)` / `pace 4500ms gates (~2.25x)`).
+ */
+export function formatDemoPaceLabel(pace, baseAutoplayMs = 1800) {
+    const p = normalizeDemoPace(pace);
+    const gate = demoPaceGateMs(p, baseAutoplayMs);
+    const scale = demoPaceScale(p);
+    const scaleTxt = Number.isInteger(scale) ? String(scale) : (Math.round(scale * 100) / 100).toString();
+    if (typeof p === "number" && p > 20) {
+        return `pace ${Math.round(p)}ms gates (~${scaleTxt}x)`;
+    }
+    if (typeof p === "number") {
+        const s = Number.isInteger(p) ? String(p) : String(Math.round(p * 100) / 100);
+        return `pace ${s}x (~${gate}ms gates)`;
+    }
+    if (p === "blitz")
+        return `pace blitz (~${gate}ms, skip theater)`;
+    if (p === "fast")
+        return `pace fast (~${scaleTxt}x, ~${gate}ms gates)`;
+    if (p === "slow")
+        return `pace slow (~${scaleTxt}x, ~${gate}ms gates)`;
+    return `pace normal (1x, ~${gate}ms gates)`;
+}
+/**
+ * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
+ * or `null` when duration is unset (caller keeps legacy timing).
+ *
+ * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`
+ * (`gatesFast`). `--fast` only shortens when pace is unset/normal.
+ */
+export function resolveFixtureDwellMs(fixture, opts) {
+    if (fixture.duration === undefined || fixture.duration === false)
+        return null;
+    const pace = opts?.pace !== undefined && opts.pace !== null
+        ? normalizeDemoPace(opts.pace)
+        : opts?.gatesFast
+            ? "fast"
+            : "normal";
+    const fastMs = typeof fixture.fastMode === "number" && Number.isFinite(fixture.fastMode) && fixture.fastMode >= 0
+        ? fixture.fastMode
+        : FIXTURE_DURATION_FAST_MS_DEFAULT;
+    const normalMs = fixture.duration === true
+        ? FIXTURE_DURATION_MS_DEFAULT
+        : typeof fixture.duration === "number" && Number.isFinite(fixture.duration) && fixture.duration >= 0
+            ? fixture.duration
+            : FIXTURE_DURATION_MS_DEFAULT;
+    if (typeof pace === "number") {
+        if (pace > 20)
+            return Math.round(pace);
+        return Math.max(0, Math.round(normalMs * Math.min(10, Math.max(0.05, pace))));
+    }
+    if (pace === "blitz" || pace === "fast")
+        return fastMs;
+    // CLI --fast only when author left pace at normal
+    if (opts?.gatesFast && pace === "normal")
+        return fastMs;
+    if (pace === "slow")
+        return Math.max(normalMs, FIXTURE_DURATION_SLOW_MS_DEFAULT);
+    return normalMs;
+}
+/** @deprecated Prefer {@link resolveFixtureDwellMs} */
+export function resolveSlideDwellMs(slide, opts) {
+    return resolveFixtureDwellMs(slide, opts);
+}
+/**
+ * Effective demo pace for a step: block override > flow episode > normal.
+ * Opaque FF / wasFastForward always win as blitz.
+ */
+export function resolveStepDemoPace(opts) {
+    if (opts.fastForward || opts.wasFastForward)
+        return "blitz";
+    if (opts.blockPace != null && opts.blockPace !== "") {
+        return normalizeDemoPace(opts.blockPace);
+    }
+    if (opts.flowPace != null && opts.flowPace !== "") {
+        return normalizeDemoPace(opts.flowPace);
+    }
+    return "normal";
+}

package/dist/highlights/device.d.ts

@@ -0,0 +1,29 @@
+import type { DeviceOrientation, DevicePreset, DeviceState, DeviceViewport } from "./types.js";
+/** Built-in preset sizes (CSS pixels) — stored in portrait for mobile/tablet. */
+export declare const DEVICE_PRESETS: Record<DevicePreset, Omit<DeviceState, "touchMode"> & {
+    touchMode?: boolean;
+}>;
+export declare function normalizeDevicePreset(raw: unknown): DevicePreset | undefined;
+export declare function normalizeDeviceOrientation(raw: unknown): DeviceOrientation | undefined;
+/** Infer orientation from box (square counts as landscape). */
+export declare function orientationFromViewport(vp: DeviceViewport): DeviceOrientation;
+/**
+ * Swap width/height so the viewport matches the requested orientation.
+ * Preserves deviceScaleFactor. No-op when already oriented.
+ */
+export declare function applyOrientation(state: DeviceState, orientation: DeviceOrientation): DeviceState;
+/** Resolve a preset name or partial state into a full DeviceState. */
+export declare function resolveDeviceState(input: DevicePreset | DeviceState | DeviceViewport | undefined, touchOverride?: boolean, orientationOverride?: DeviceOrientation): DeviceState | undefined;
+/**
+ * Carry-forward for device fixtures (mirror {@link applyTodoPhase}).
+ * - clear: hideDevice / clearDevice / device("desktop") with clear intent
+ * - set: author set device/viewport/touch this phase
+ * - keep: omit - preserve previous (whole episode remain)
+ */
+export declare function applyDevicePhase(prev: DeviceState | undefined, phase: {
+    deviceSync?: "set" | "clear" | "keep";
+    device?: DeviceState;
+}): {
+    device: DeviceState | undefined;
+    sync: "set" | "clear" | "keep";
+};

package/dist/highlights/device.js

@@ -0,0 +1,171 @@
+/** Built-in preset sizes (CSS pixels) — stored in portrait for mobile/tablet. */
+export const DEVICE_PRESETS = {
+    mobile: {
+        preset: "mobile",
+        viewport: { width: 390, height: 844, deviceScaleFactor: 2 },
+        isMobile: true,
+        hasTouch: true,
+        touchMode: true,
+        orientation: "portrait",
+    },
+    tablet: {
+        preset: "tablet",
+        viewport: { width: 768, height: 1024, deviceScaleFactor: 2 },
+        isMobile: true,
+        hasTouch: true,
+        touchMode: true,
+        orientation: "portrait",
+    },
+    desktop: {
+        preset: "desktop",
+        viewport: { width: 1280, height: 720, deviceScaleFactor: 1 },
+        isMobile: false,
+        hasTouch: false,
+        touchMode: false,
+        orientation: "landscape",
+    },
+};
+export function normalizeDevicePreset(raw) {
+    const s = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+    if (s === "mobile" || s === "phone" || s === "m")
+        return "mobile";
+    if (s === "tablet" || s === "pad" || s === "t")
+        return "tablet";
+    if (s === "desktop" || s === "desk" || s === "d" || s === "main")
+        return "desktop";
+    return undefined;
+}
+export function normalizeDeviceOrientation(raw) {
+    const s = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+    if (s === "portrait" || s === "port" || s === "tall" || s === "p")
+        return "portrait";
+    if (s === "landscape" || s === "land" || s === "wide" || s === "l")
+        return "landscape";
+    return undefined;
+}
+/** Infer orientation from box (square counts as landscape). */
+export function orientationFromViewport(vp) {
+    return vp.height > vp.width ? "portrait" : "landscape";
+}
+/**
+ * Swap width/height so the viewport matches the requested orientation.
+ * Preserves deviceScaleFactor. No-op when already oriented.
+ */
+export function applyOrientation(state, orientation) {
+    const vp = { ...state.viewport };
+    const current = orientationFromViewport(vp);
+    if (current !== orientation) {
+        const w = vp.width;
+        vp.width = vp.height;
+        vp.height = w;
+    }
+    return { ...state, viewport: vp, orientation };
+}
+/** Resolve a preset name or partial state into a full DeviceState. */
+export function resolveDeviceState(input, touchOverride, orientationOverride) {
+    if (input === undefined)
+        return undefined;
+    let resolved;
+    if (typeof input === "string") {
+        const p = normalizeDevicePreset(input);
+        if (!p)
+            return undefined;
+        const base = DEVICE_PRESETS[p];
+        const touchMode = touchOverride !== undefined ? !!touchOverride : !!base.touchMode;
+        resolved = {
+            preset: base.preset,
+            viewport: { ...base.viewport },
+            isMobile: base.isMobile,
+            hasTouch: base.hasTouch || touchMode,
+            touchMode,
+            orientation: base.orientation || orientationFromViewport(base.viewport),
+        };
+    }
+    else if ("width" in input && "height" in input && !("preset" in input)) {
+        const vp = input;
+        const touchMode = touchOverride !== undefined ? !!touchOverride : true;
+        const box = {
+            width: Math.max(200, Math.floor(vp.width)),
+            height: Math.max(200, Math.floor(vp.height)),
+            ...(vp.deviceScaleFactor !== undefined
+                ? { deviceScaleFactor: vp.deviceScaleFactor }
+                : { deviceScaleFactor: 2 }),
+        };
+        resolved = {
+            preset: "mobile",
+            viewport: box,
+            isMobile: true,
+            hasTouch: true,
+            touchMode,
+            orientation: orientationFromViewport(box),
+        };
+    }
+    else {
+        const d = input;
+        const preset = normalizeDevicePreset(d.preset) || "desktop";
+        const base = DEVICE_PRESETS[preset];
+        const touchMode = touchOverride !== undefined
+            ? !!touchOverride
+            : d.touchMode !== undefined
+                ? !!d.touchMode
+                : !!base.touchMode;
+        const viewport = d.viewport
+            ? {
+                width: Math.max(200, Math.floor(d.viewport.width)),
+                height: Math.max(200, Math.floor(d.viewport.height)),
+                ...(d.viewport.deviceScaleFactor !== undefined
+                    ? { deviceScaleFactor: d.viewport.deviceScaleFactor }
+                    : base.viewport.deviceScaleFactor !== undefined
+                        ? { deviceScaleFactor: base.viewport.deviceScaleFactor }
+                        : {}),
+            }
+            : { ...base.viewport };
+        resolved = {
+            preset,
+            viewport,
+            isMobile: d.isMobile !== undefined ? !!d.isMobile : base.isMobile,
+            hasTouch: d.hasTouch !== undefined ? !!d.hasTouch : base.hasTouch || touchMode,
+            touchMode,
+            orientation: normalizeDeviceOrientation(d.orientation) ||
+                orientationFromViewport(viewport),
+        };
+    }
+    if (!resolved)
+        return undefined;
+    const want = orientationOverride ||
+        (typeof input === "object" && input && "orientation" in input
+            ? normalizeDeviceOrientation(input.orientation)
+            : undefined);
+    if (want)
+        return applyOrientation(resolved, want);
+    if (!resolved.orientation) {
+        resolved = {
+            ...resolved,
+            orientation: orientationFromViewport(resolved.viewport),
+        };
+    }
+    return resolved;
+}
+/**
+ * Carry-forward for device fixtures (mirror {@link applyTodoPhase}).
+ * - clear: hideDevice / clearDevice / device("desktop") with clear intent
+ * - set: author set device/viewport/touch this phase
+ * - keep: omit - preserve previous (whole episode remain)
+ */
+export function applyDevicePhase(prev, phase) {
+    const sync = phase.deviceSync ||
+        (phase.device ? "set" : "keep");
+    if (sync === "clear") {
+        return { device: resolveDeviceState("desktop", false), sync: "clear" };
+    }
+    if (sync === "set") {
+        if (phase.device)
+            return { device: phase.device, sync: "set" };
+        return { device: resolveDeviceState("desktop", false), sync: "clear" };
+    }
+    return { device: prev, sync: "keep" };
+}

package/dist/highlights/merge.d.ts

@@ -0,0 +1,8 @@
+import type { HighlightStubPhase, HighlightStubPhaseName, HighlightStubPhaseOrFn, ResolvedHighlight, WaygraphHighlightFixture } from "./types.js";
+import type { Block, Checkpoint } from "../types.js";
+export declare function isStubPhase(v: unknown): v is HighlightStubPhase;
+export declare function applyDefaultZoom(slots: ResolvedHighlight[], defaultZoom?: number): ResolvedHighlight[];
+export declare function applyDefaultZoomOut(slots: ResolvedHighlight[], defaultZoomOut?: boolean): ResolvedHighlight[];
+export declare function mergePhaseMaps(phaseMap: HighlightStubPhase, fixturePhase: Record<string, WaygraphHighlightFixture> | undefined): ResolvedHighlight[];
+export declare function readStubRaw(block: Block<any, any>, phase: HighlightStubPhaseName): HighlightStubPhaseOrFn<any> | undefined;
+export declare function applyLegacyHighlightsShim(block: Block<any, any>, phase: HighlightStubPhaseName, phaseMap: HighlightStubPhase, out?: Checkpoint<string>): HighlightStubPhase;