waygraph 0.15.25 → 0.15.26

package/dist/highlights/merge.js

@@ -0,0 +1,173 @@
+import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "./style.js";
+export function isStubPhase(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function pickDurationFields(base, patch) {
+    const out = {};
+    const duration = patch?.duration !== undefined ? patch.duration : base?.duration;
+    const fastMode = patch?.fastMode !== undefined ? patch.fastMode : base?.fastMode;
+    if (duration !== undefined)
+        out.duration = duration;
+    if (fastMode !== undefined)
+        out.fastMode = fastMode;
+    return out;
+}
+function pickStyleFields(base, patch) {
+    const out = {};
+    const tone = patch?.tone !== undefined ? patch.tone : base?.tone;
+    const size = patch?.size !== undefined ? patch.size : base?.size;
+    const weight = patch?.weight !== undefined ? patch.weight : base?.weight;
+    if (tone !== undefined)
+        out.tone = normalizeHighlightTone(tone);
+    if (size !== undefined)
+        out.size = normalizeHighlightSize(size);
+    if (weight !== undefined)
+        out.weight = normalizeHighlightWeight(weight);
+    return out;
+}
+function pickZoom(base, patch) {
+    const zoom = patch?.zoom !== undefined ? patch.zoom : base?.zoom;
+    if (zoom !== undefined && Number.isFinite(zoom) && zoom > 0)
+        return { zoom };
+    return {};
+}
+function pickFxFields(base, patch) {
+    const out = {};
+    const focus = patch?.focus !== undefined ? patch.focus : base?.focus;
+    const color = patch?.color !== undefined ? patch.color : base?.color;
+    const cursor = patch?.cursor !== undefined ? patch.cursor : base?.cursor;
+    const todo = patch?.todo !== undefined ? patch.todo : base?.todo;
+    const gesture = patch?.gesture !== undefined ? patch.gesture : base?.gesture;
+    if (focus !== undefined)
+        out.focus = !!focus;
+    if (color !== undefined && String(color).trim())
+        out.color = String(color).trim();
+    if (cursor !== undefined)
+        out.cursor = !!cursor;
+    if (todo !== undefined && String(todo).trim())
+        out.todo = String(todo).trim();
+    if (gesture === "tap" || gesture === "hold" || gesture === "click" || gesture === "swipe") {
+        out.gesture = gesture;
+    }
+    return out;
+}
+function mergeSlot(base, patch) {
+    if (!base && !patch)
+        return null;
+    const dwell = pickDurationFields(base, patch);
+    const style = pickStyleFields(base, patch);
+    const zoom = pickZoom(base, patch);
+    const fx = pickFxFields(base, patch);
+    if (!base && patch) {
+        if (!patch.selector)
+            return null;
+        return {
+            selector: patch.selector,
+            label: patch.label,
+            ...(patch.detail ? { detail: patch.detail } : {}),
+            ...(patch.tag ? { tag: patch.tag } : {}),
+            ...style,
+            ...dwell,
+            ...zoom,
+            ...fx,
+        };
+    }
+    if (base && !patch) {
+        return {
+            ...base,
+            ...(base.tone ? { tone: normalizeHighlightTone(base.tone) } : {}),
+            ...(base.size ? { size: normalizeHighlightSize(base.size) } : {}),
+            ...(base.weight ? { weight: normalizeHighlightWeight(base.weight) } : {}),
+            ...pickZoom(base, undefined),
+            ...pickFxFields(base, undefined),
+        };
+    }
+    return {
+        selector: patch.selector ?? base.selector,
+        label: patch.label,
+        ...(patch.detail !== undefined
+            ? { detail: patch.detail }
+            : base.detail
+                ? { detail: base.detail }
+                : {}),
+        ...(patch.tag !== undefined ? { tag: patch.tag } : base.tag ? { tag: base.tag } : {}),
+        ...style,
+        ...dwell,
+        ...zoom,
+        ...fx,
+    };
+}
+export function applyDefaultZoom(slots, defaultZoom) {
+    if (defaultZoom === undefined || !(defaultZoom > 0))
+        return slots;
+    return slots.map((h) => (h.zoom !== undefined && h.zoom > 0 ? h : { ...h, zoom: defaultZoom }));
+}
+export function applyDefaultZoomOut(slots, defaultZoomOut) {
+    if (defaultZoomOut === undefined)
+        return slots;
+    return slots.map((h) => h.zoomOut !== undefined ? h : { ...h, zoomOut: defaultZoomOut });
+}
+export function mergePhaseMaps(phaseMap, fixturePhase) {
+    const phaseKeys = Object.keys(phaseMap);
+    const fixtureKeys = Object.keys(fixturePhase || {});
+    const allKeys = [...new Set([...phaseKeys, ...fixtureKeys])];
+    const allNumeric = allKeys.length > 0 && allKeys.every((k) => Number.isFinite(Number(k)) && String(Number(k)) === k);
+    // Numeric stub ids (legacy "0","1") sort by number. Named stubs keep author
+    // insertion order - localeCompare used to reorder password/submit/username
+    // and advance the wrong todo index on fill.
+    const ordered = allNumeric
+        ? [...allKeys].sort((a, b) => Number(a) - Number(b))
+        : [...phaseKeys, ...fixtureKeys.filter((k) => !phaseKeys.includes(k))];
+    const resolved = [];
+    for (const id of ordered) {
+        const merged = mergeSlot(phaseMap[id], fixturePhase?.[id]);
+        if (merged) {
+            resolved.push({
+                ...merged,
+                slotId: id,
+                ...(merged.todo ? { todo: merged.todo } : {}),
+            });
+        }
+    }
+    return resolved;
+}
+function phaseFromLegacyHighlights(highlights) {
+    const out = {};
+    if (!highlights)
+        return out;
+    highlights.forEach((h, i) => {
+        if (h && typeof h.selector === "string" && typeof h.label === "string") {
+            out[String(i)] = {
+                selector: h.selector,
+                label: h.label,
+                ...(h.tone ? { tone: normalizeHighlightTone(h.tone) } : {}),
+            };
+        }
+    });
+    return out;
+}
+export function readStubRaw(block, phase) {
+    const instr = block.instruction;
+    if (phase === "stubBefore")
+        return instr.stubBefore;
+    if (phase === "stubAfter")
+        return instr.stubAfter;
+    return instr.stubOnError;
+}
+export function applyLegacyHighlightsShim(block, phase, phaseMap, out) {
+    if (phase !== "stubAfter" || Object.keys(phaseMap).length > 0)
+        return phaseMap;
+    const instr = block.instruction;
+    if (!instr.highlights)
+        return phaseMap;
+    let legacy = instr.highlights;
+    if (typeof legacy === "function") {
+        try {
+            legacy = legacy(out ?? { __state: "" });
+        }
+        catch {
+            legacy = [];
+        }
+    }
+    return phaseFromLegacyHighlights(Array.isArray(legacy) ? legacy : []);
+}

package/dist/highlights/run-phase.d.ts

@@ -0,0 +1,43 @@
+import type { HighlightFixtureMap, HighlightStubPhaseName, ResolvedHighlight, StubPhaseResult, WaygraphSlide } from "./types.js";
+import type { Block, Checkpoint } from "../types.js";
+import type { MemPage } from "../mem-page.js";
+/**
+ * Run an open stub lifecycle (preferred) or resolve a static slot map.
+ * Returns rings + episode fixtures (todos / todoIndex / zoom).
+ *
+ * @example
+ * const before = await runStubPhase(block, "stubBefore", { fixtures });
+ * // before.todos, before.highlights
+ */
+export declare function runStubPhase(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
+    out?: Checkpoint<string>;
+    error?: unknown;
+    mem?: MemPage;
+    fixtures?: HighlightFixtureMap;
+}): Promise<StubPhaseResult>;
+/**
+ * Sync resolve of highlight slots. Prefer {@link runStubPhase} for open
+ * async lifecycles + episode fixtures (todos/zoom).
+ */
+export declare function resolveHighlightSlots(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
+    out?: Checkpoint<string>;
+    fixtures?: HighlightFixtureMap;
+}): ResolvedHighlight[];
+/**
+ * Resolve multi-step yap slides: flow fixture `slides` wins when present,
+ * else `instruction.slides` (function form allowed).
+ */
+export declare function resolveSlides(block: Block<any, any>, opts?: {
+    out?: Checkpoint<string>;
+    fixtures?: HighlightFixtureMap;
+}): WaygraphSlide[];
+/**
+ * True when the block authored stubAfter (lifecycle fn, slots, fixtures, or legacy highlights).
+ * When true, demo should not use verify-trait fallback.
+ */
+export declare function hasAuthoredStubAfter(block: Block<any, any>, out?: Checkpoint<string>, fixtures?: HighlightFixtureMap): boolean;
+/**
+ * True when stubOnError is authored (lifecycle fn and/or rings).
+ * Demo fail path only - success never consults this.
+ */
+export declare function hasAuthoredStubOnError(block: Block<any, any>, fixtures?: HighlightFixtureMap): boolean;

package/dist/highlights/run-phase.js

@@ -0,0 +1,211 @@
+import { createStubCtx, liftLegacySlotTodos } from "./stub-ctx.js";
+import { applyDefaultZoom, applyDefaultZoomOut, applyLegacyHighlightsShim, isStubPhase, mergePhaseMaps, readStubRaw } from "./merge.js";
+import { buildTodoDock, normalizeTodoStyle, normalizeTodos } from "./todo-dock.js";
+import { resolveDeviceState } from "./device.js";
+/**
+ * Run an open stub lifecycle (preferred) or resolve a static slot map.
+ * Returns rings + episode fixtures (todos / todoIndex / zoom).
+ *
+ * @example
+ * const before = await runStubPhase(block, "stubBefore", { fixtures });
+ * // before.todos, before.highlights
+ */
+export async function runStubPhase(block, phase, opts) {
+    const bag = { highlights: {} };
+    const ctx = createStubCtx(bag, {
+        ...(opts?.out !== undefined ? { out: opts.out } : {}),
+        ...(opts?.error !== undefined ? { error: opts.error } : {}),
+        ...(opts?.mem !== undefined ? { mem: opts.mem } : {}),
+    });
+    const raw = readStubRaw(block, phase);
+    if (typeof raw === "function") {
+        try {
+            const ret = await raw(ctx);
+            if (isStubPhase(ret)) {
+                bag.highlights = { ...bag.highlights, ...ret };
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+        // Compat: legacy `(out) => map` that expected Checkpoint (__state on arg)
+        if (Object.keys(bag.highlights).length === 0 && !bag.todos) {
+            try {
+                const legacyOut = (opts?.out ?? { __state: "" });
+                const ret2 = raw(legacyOut);
+                if (isStubPhase(ret2))
+                    bag.highlights = { ...ret2 };
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    else if (isStubPhase(raw)) {
+        bag.highlights = { ...raw };
+    }
+    bag.highlights = applyLegacyHighlightsShim(block, phase, bag.highlights, opts?.out);
+    liftLegacySlotTodos(bag);
+    const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
+    let highlights = mergePhaseMaps(bag.highlights, fixturePhase);
+    highlights = applyDefaultZoom(highlights, bag.zoom);
+    highlights = applyDefaultZoomOut(highlights, bag.zoomOut);
+    const todoDock = bag.hideTodos
+        ? undefined
+        : buildTodoDock({
+            todos: bag.todos,
+            todoIndex: bag.todoIndex,
+            todoTitle: bag.todoTitle,
+            todoId: bag.todoId,
+            todoStyle: bag.todoStyle,
+            todoGroups: bag.todoGroups,
+            todoPos: bag.todoPos,
+        });
+    const todos = todoDock?.groups[0]?.items ||
+        (bag.hideTodos
+            ? []
+            : normalizeTodos(bag.todos, bag.todoIndex, normalizeTodoStyle(bag.todoStyle) || "sequential"));
+    // Omit todos entirely => keep previous dock. Explicit empty / hideTodos => clear.
+    const todoSync = bag.hideTodos
+        ? "clear"
+        : bag.todoTouched && todoDock
+            ? "set"
+            : bag.todoTouched && !todoDock
+                ? "clear"
+                : "keep";
+    let deviceState;
+    if (bag.hideDevice) {
+        deviceState = resolveDeviceState("desktop", false);
+    }
+    else if (bag.device) {
+        deviceState = bag.touchOverride !== undefined
+            ? {
+                ...bag.device,
+                touchMode: bag.touchOverride,
+                hasTouch: bag.device.hasTouch || bag.touchOverride,
+            }
+            : bag.device;
+    }
+    else if (bag.touchOverride !== undefined) {
+        deviceState = resolveDeviceState("desktop", bag.touchOverride);
+    }
+    const deviceSync = bag.hideDevice
+        ? "clear"
+        : bag.deviceTouched && deviceState
+            ? "set"
+            : bag.deviceTouched && !deviceState
+                ? "clear"
+                : "keep";
+    return {
+        highlights,
+        todos,
+        todoSync,
+        deviceSync,
+        ...(bag.todoIndex !== undefined ? { todoIndex: bag.todoIndex } : {}),
+        ...(todoDock ? { todoDock } : {}),
+        ...(deviceState ? { device: deviceState } : {}),
+        ...(bag.zoom !== undefined ? { zoom: bag.zoom } : {}),
+        ...(bag.zoomOut !== undefined ? { zoomOut: bag.zoomOut } : {}),
+        ...(bag.title !== undefined && bag.title !== "" ? { title: bag.title } : {}),
+        ...(bag.todoPos !== undefined ? { todoPos: bag.todoPos } : {}),
+        ...(bag.todoDockUi !== undefined ? { todoDockUi: bag.todoDockUi } : {}),
+        ...(bag.todoParallel === true ? { todoParallel: true } : {}),
+    };
+}
+/**
+ * Sync resolve of highlight slots. Prefer {@link runStubPhase} for open
+ * async lifecycles + episode fixtures (todos/zoom).
+ */
+export function resolveHighlightSlots(block, phase, opts) {
+    const bag = { highlights: {} };
+    const raw = readStubRaw(block, phase);
+    if (typeof raw === "function") {
+        try {
+            const ctx = createStubCtx(bag, {
+                ...(opts?.out !== undefined ? { out: opts.out } : {}),
+            });
+            const ret = raw(ctx);
+            if (isStubPhase(ret)) {
+                bag.highlights = { ...bag.highlights, ...ret };
+            }
+        }
+        catch {
+            try {
+                const legacyOut = (opts?.out ?? { __state: "" });
+                const ret2 = raw(legacyOut);
+                if (isStubPhase(ret2))
+                    bag.highlights = { ...ret2 };
+            }
+            catch {
+                bag.highlights = {};
+            }
+        }
+    }
+    else if (isStubPhase(raw)) {
+        bag.highlights = { ...raw };
+    }
+    bag.highlights = applyLegacyHighlightsShim(block, phase, bag.highlights, opts?.out);
+    liftLegacySlotTodos(bag);
+    const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
+    return applyDefaultZoom(mergePhaseMaps(bag.highlights, fixturePhase), bag.zoom);
+}
+/**
+ * Resolve multi-step yap slides: flow fixture `slides` wins when present,
+ * else `instruction.slides` (function form allowed).
+ */
+export function resolveSlides(block, opts) {
+    const fromFixture = opts?.fixtures?.[block.name]?.slides;
+    if (fromFixture && fromFixture.length > 0) {
+        return [...fromFixture];
+    }
+    const instr = block.instruction;
+    let raw = instr.slides;
+    if (typeof raw === "function") {
+        try {
+            raw = raw(opts?.out ?? { __state: "" });
+        }
+        catch {
+            raw = [];
+        }
+    }
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((s) => s && typeof s.caption === "string" && s.caption.length > 0);
+}
+function stubPhaseLooksAuthored(block, phase, fixtures) {
+    const raw = readStubRaw(block, phase);
+    if (typeof raw === "function")
+        return true;
+    if (isStubPhase(raw) && Object.keys(raw).length > 0)
+        return true;
+    const fx = fixtures?.[block.name]?.[phase];
+    if (fx && Object.keys(fx).length > 0)
+        return true;
+    return false;
+}
+/**
+ * True when the block authored stubAfter (lifecycle fn, slots, fixtures, or legacy highlights).
+ * When true, demo should not use verify-trait fallback.
+ */
+export function hasAuthoredStubAfter(block, out, fixtures) {
+    if (stubPhaseLooksAuthored(block, "stubAfter", fixtures))
+        return true;
+    const instr = block.instruction;
+    if (instr.highlights)
+        return true;
+    return resolveHighlightSlots(block, "stubAfter", {
+        ...(out !== undefined ? { out } : {}),
+        ...(fixtures !== undefined ? { fixtures } : {}),
+    }).length > 0;
+}
+/**
+ * True when stubOnError is authored (lifecycle fn and/or rings).
+ * Demo fail path only - success never consults this.
+ */
+export function hasAuthoredStubOnError(block, fixtures) {
+    if (stubPhaseLooksAuthored(block, "stubOnError", fixtures))
+        return true;
+    return (resolveHighlightSlots(block, "stubOnError", {
+        ...(fixtures !== undefined ? { fixtures } : {}),
+    }).length > 0);
+}

package/dist/highlights/stub-ctx.d.ts

@@ -0,0 +1,10 @@
+import type { StubBagState, StubCtx } from "./types.js";
+import type { Checkpoint } from "../types.js";
+import type { MemPage } from "../mem-page.js";
+export declare function createStubCtx<Out extends Checkpoint<string>>(bag: StubBagState, opts: {
+    out?: Out;
+    error?: unknown;
+    mem?: MemPage;
+}): StubCtx<Out>;
+/** Lift legacy per-slot todos (0.12.23) onto the phase bag once. */
+export declare function liftLegacySlotTodos(bag: StubBagState): void;