@dailephd/my-dev-kit-lab 0.4.6 → 0.4.7

package/dist/src/tutorial/tutorialOverlay.js

@@ -0,0 +1,180 @@
+import { TUTORIAL_VISUAL_ROOT_ID } from "./tutorialCursor.js";
+/**
+ * Deterministic highlight and callout overlays.
+ *
+ * Both are drawn as tutorial-owned fixed-position siblings derived from the
+ * target's bounding box. Nothing is inserted into the target element and no
+ * class list is touched, so the application's own DOM and state are unchanged
+ * and an assertion can never accidentally observe an overlay as application
+ * content. Both use `pointer-events: none`.
+ */
+export const TUTORIAL_HIGHLIGHT_ID = "__my_dev_kit_lab_tutorial_highlight__";
+export const TUTORIAL_CALLOUT_ID = "__my_dev_kit_lab_tutorial_callout__";
+/** Gap between the target box and the callout, and callout sizing bounds. */
+const CALLOUT_GAP_PX = 12;
+const CALLOUT_MAX_WIDTH_PX = 320;
+const HIGHLIGHT_PADDING_PX = 4;
+/**
+ * Deterministic "auto" placement, in this exact branch order:
+ *
+ * 1. target mainly left of viewport center  -> "right"
+ * 2. target mainly right of viewport center -> "left"
+ * 3. target near horizontal center, in the upper half -> "bottom"
+ * 4. otherwise -> "top"
+ *
+ * "Mainly left/right" means the target's own center sits outside the middle
+ * third of the viewport. No search, no scoring, no randomness.
+ */
+export function resolveCalloutPlacement(placement, box, viewport) {
+    if (placement !== undefined && placement !== "auto") {
+        return placement;
+    }
+    if (!box) {
+        // Nothing to be relative to; a viewport callout sits at the bottom.
+        return "bottom";
+    }
+    const targetCenterX = box.x + box.width / 2;
+    const targetCenterY = box.y + box.height / 2;
+    const leftThird = viewport.width / 3;
+    const rightThird = (viewport.width * 2) / 3;
+    if (targetCenterX < leftThird) {
+        return "right";
+    }
+    if (targetCenterX > rightThird) {
+        return "left";
+    }
+    if (targetCenterY < viewport.height / 2) {
+        return "bottom";
+    }
+    return "top";
+}
+export function applyHighlightInPage(arg) {
+    const doc = globalThis.document;
+    const root = doc?.getElementById(arg.rootId);
+    if (!doc || !root) {
+        return false;
+    }
+    const stale = doc.getElementById(arg.highlightId);
+    if (stale) {
+        stale.remove();
+    }
+    const highlight = doc.createElement("div");
+    highlight.id = arg.highlightId;
+    highlight.setAttribute("aria-hidden", "true");
+    highlight.style.setProperty("position", "fixed");
+    highlight.style.setProperty("left", `${arg.box.x - arg.paddingPx}px`);
+    highlight.style.setProperty("top", `${arg.box.y - arg.paddingPx}px`);
+    highlight.style.setProperty("width", `${arg.box.width + arg.paddingPx * 2}px`);
+    highlight.style.setProperty("height", `${arg.box.height + arg.paddingPx * 2}px`);
+    // An outline plus a translucent wash keeps the target's own content readable.
+    highlight.style.setProperty("border", "3px solid rgba(255, 176, 0, 0.95)");
+    highlight.style.setProperty("border-radius", "6px");
+    highlight.style.setProperty("background", "rgba(255, 176, 0, 0.12)");
+    highlight.style.setProperty("box-shadow", "0 0 0 9999px rgba(0, 0, 0, 0.08)");
+    highlight.style.setProperty("pointer-events", "none");
+    highlight.style.setProperty("z-index", "2147483645");
+    root.appendChild(highlight);
+    return true;
+}
+export function applyCalloutInPage(arg) {
+    const doc = globalThis.document;
+    const root = doc?.getElementById(arg.rootId);
+    if (!doc || !root) {
+        return false;
+    }
+    const stale = doc.getElementById(arg.calloutId);
+    if (stale) {
+        stale.remove();
+    }
+    const callout = doc.createElement("div");
+    callout.id = arg.calloutId;
+    callout.setAttribute("aria-hidden", "true");
+    callout.textContent = arg.text;
+    callout.style.setProperty("position", "fixed");
+    callout.style.setProperty("max-width", `${arg.maxWidthPx}px`);
+    callout.style.setProperty("padding", "10px 14px");
+    callout.style.setProperty("border-radius", "8px");
+    callout.style.setProperty("background", "rgba(17, 17, 17, 0.92)");
+    callout.style.setProperty("color", "#ffffff");
+    callout.style.setProperty("font", "16px/1.4 system-ui, sans-serif");
+    callout.style.setProperty("box-shadow", "0 6px 20px rgba(0, 0, 0, 0.35)");
+    callout.style.setProperty("pointer-events", "none");
+    callout.style.setProperty("z-index", "2147483647");
+    if (!arg.box) {
+        // No locator: a deterministic viewport position, bottom-center.
+        callout.style.setProperty("left", "50%");
+        callout.style.setProperty("bottom", `${arg.gapPx * 2}px`);
+        callout.style.setProperty("transform", "translateX(-50%)");
+        root.appendChild(callout);
+        return true;
+    }
+    const box = arg.box;
+    const centerX = box.x + box.width / 2;
+    const centerY = box.y + box.height / 2;
+    if (arg.placement === "top") {
+        callout.style.setProperty("left", `${centerX}px`);
+        callout.style.setProperty("top", `${box.y - arg.gapPx}px`);
+        callout.style.setProperty("transform", "translate(-50%, -100%)");
+    }
+    else if (arg.placement === "bottom") {
+        callout.style.setProperty("left", `${centerX}px`);
+        callout.style.setProperty("top", `${box.y + box.height + arg.gapPx}px`);
+        callout.style.setProperty("transform", "translateX(-50%)");
+    }
+    else if (arg.placement === "left") {
+        callout.style.setProperty("left", `${box.x - arg.gapPx}px`);
+        callout.style.setProperty("top", `${centerY}px`);
+        callout.style.setProperty("transform", "translate(-100%, -50%)");
+    }
+    else {
+        callout.style.setProperty("left", `${box.x + box.width + arg.gapPx}px`);
+        callout.style.setProperty("top", `${centerY}px`);
+        callout.style.setProperty("transform", "translateY(-50%)");
+    }
+    root.appendChild(callout);
+    return true;
+}
+export function clearStepOverlaysInPage(arg) {
+    const doc = globalThis.document;
+    if (!doc) {
+        return 0;
+    }
+    let removed = 0;
+    for (const id of [arg.highlightId, arg.calloutId]) {
+        const node = doc.getElementById(id);
+        if (node) {
+            node.remove();
+            removed += 1;
+        }
+    }
+    return removed;
+}
+// ---------------------------------------------------------------------------
+// Host-side helpers
+// ---------------------------------------------------------------------------
+export async function applyTutorialHighlight(page, box) {
+    return page.evaluate(applyHighlightInPage, {
+        rootId: TUTORIAL_VISUAL_ROOT_ID,
+        highlightId: TUTORIAL_HIGHLIGHT_ID,
+        box,
+        paddingPx: HIGHLIGHT_PADDING_PX
+    });
+}
+export async function applyTutorialCallout(page, options) {
+    return page.evaluate(applyCalloutInPage, {
+        rootId: TUTORIAL_VISUAL_ROOT_ID,
+        calloutId: TUTORIAL_CALLOUT_ID,
+        text: options.text,
+        placement: options.placement,
+        box: options.box,
+        viewport: options.viewport,
+        gapPx: CALLOUT_GAP_PX,
+        maxWidthPx: CALLOUT_MAX_WIDTH_PX
+    });
+}
+export async function clearTutorialStepOverlays(page) {
+    return page.evaluate(clearStepOverlaysInPage, {
+        highlightId: TUTORIAL_HIGHLIGHT_ID,
+        calloutId: TUTORIAL_CALLOUT_ID
+    });
+}

package/dist/src/tutorial/tutorialPaths.js

@@ -0,0 +1,86 @@
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinRoot } from "../core/pathSafety.js";
+/**
+ * Output ownership for a tutorial run.
+ *
+ * A run owns exactly one directory tree. The inspected/source repository that
+ * supplied the target contract is never an output location: `targetRoot` is a
+ * run-owned disposable working copy that only the trusted prepare command
+ * populates.
+ */
+export const TUTORIAL_WORKSPACE_DIR_NAME = "tutorials";
+/**
+ * Generates a collision-resistant run id that is also a safe single path
+ * segment (matches the tutorial id pattern).
+ */
+export function generateTutorialRunId(now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "z").toLowerCase();
+    return `${stamp}-${randomUUID().slice(0, 8)}`;
+}
+export function buildTutorialRunPaths(options) {
+    const runRoot = resolveRunRoot(options);
+    return {
+        runRoot,
+        targetRoot: path.join(runRoot, "target"),
+        artifactsRoot: path.join(runRoot, "artifacts"),
+        screenshotsRoot: path.join(runRoot, "screenshots"),
+        logsRoot: path.join(runRoot, "logs"),
+        temporaryRoot: path.join(runRoot, "temporary")
+    };
+}
+function resolveRunRoot(options) {
+    if (options.outDir !== undefined && options.outDir.trim().length > 0) {
+        // An explicit --out is honored exactly as given. It is deliberately NOT
+        // relocated beneath workspaceRoot: the caller chose the location.
+        return path.isAbsolute(options.outDir)
+            ? path.resolve(options.outDir)
+            : path.resolve(options.invocationCwd, options.outDir);
+    }
+    return path.join(path.resolve(options.workspaceRoot), TUTORIAL_WORKSPACE_DIR_NAME, options.scenarioId, options.runId);
+}
+/**
+ * Creates the full run layout up front so every later stage writes into a
+ * directory that already exists, and so the layout is stable even for a run that
+ * fails early.
+ */
+export async function createTutorialRunDirectories(paths) {
+    await mkdir(paths.runRoot, { recursive: true });
+    for (const directory of [
+        paths.artifactsRoot,
+        paths.screenshotsRoot,
+        paths.logsRoot,
+        paths.temporaryRoot
+    ]) {
+        await mkdir(directory, { recursive: true });
+    }
+}
+/**
+ * Resolves a scenario-declared file path beneath the run-owned target root.
+ *
+ * Uses path-semantics containment (`resolveWithinRoot`), not string-prefix
+ * matching, so a sibling directory such as `<root>-other` is correctly treated
+ * as outside. Absolute paths are rejected outright even when they happen to
+ * point inside the root, because a scenario has no business naming absolute
+ * locations on the host.
+ */
+export function resolveTargetFilePath(targetRoot, suppliedPath) {
+    if (typeof suppliedPath !== "string" || suppliedPath.trim().length === 0) {
+        throw new Error("File assertion path must be a non-empty path relative to targetRoot.");
+    }
+    if (path.isAbsolute(suppliedPath) || path.win32.isAbsolute(suppliedPath) || path.posix.isAbsolute(suppliedPath)) {
+        throw new Error(`File assertion path must be relative to targetRoot; received absolute path: ${suppliedPath}`);
+    }
+    // Catches a Windows drive-qualified relative form such as "C:file" that is
+    // not absolute by either isAbsolute check but still escapes the root.
+    if (/^[A-Za-z]:/.test(suppliedPath)) {
+        throw new Error(`File assertion path must not be drive-qualified: ${suppliedPath}`);
+    }
+    try {
+        return resolveWithinRoot(targetRoot, suppliedPath);
+    }
+    catch {
+        throw new Error(`File assertion path escapes targetRoot: ${suppliedPath}`);
+    }
+}

package/dist/src/tutorial/tutorialSession.js

@@ -0,0 +1,398 @@
+import { existsSync } from "node:fs";
+import { executeTutorialAction } from "./tutorialActions.js";
+import { executeTutorialAssertion } from "./tutorialAssertions.js";
+import { resolveTutorialLocator, describeTutorialLocator } from "./tutorialLocators.js";
+import { buildScreenshotPath, toRunRelativePosixPath, verifyArtifactFile } from "./tutorialArtifacts.js";
+import { CLICK_FEEDBACK_DURATION_MS, CURSOR_MOVE_DURATION_MS, centerOfBox, installTutorialCursor, moveTutorialCursor, removeTutorialVisuals, showTutorialClickFeedback } from "./tutorialCursor.js";
+import { applyTutorialCallout, applyTutorialHighlight, clearTutorialStepOverlays, resolveCalloutPlacement } from "./tutorialOverlay.js";
+export async function openTutorialSession(browser, options) {
+    if (typeof browser.newContext !== "function") {
+        return {
+            ok: false,
+            error: "Tutorial browser runtime does not support browser contexts, which a persistent tutorial session requires."
+        };
+    }
+    const viewport = { width: options.viewport.width, height: options.viewport.height };
+    let context;
+    try {
+        context = await browser.newContext({
+            viewport,
+            // Recording size matches the scenario viewport: no invented dimensions.
+            ...(options.recordVideoDir !== undefined
+                ? { recordVideo: { dir: options.recordVideoDir, size: { ...viewport } } }
+                : {})
+        });
+    }
+    catch (error) {
+        return { ok: false, error: `Tutorial browser context could not be created: ${messageOf(error)}` };
+    }
+    try {
+        const page = await context.newPage();
+        let video = null;
+        if (typeof page.video === "function") {
+            try {
+                video = page.video();
+            }
+            catch (error) {
+                // A runtime without video must not prevent the tutorial from running;
+                // the missing recording is reported later as an artifact outcome.
+                video = null;
+                void error;
+            }
+        }
+        return { ok: true, session: { context, page, video } };
+    }
+    catch (error) {
+        await closeQuietly(() => context.close());
+        return { ok: false, error: `Tutorial page could not be created: ${messageOf(error)}` };
+    }
+}
+/**
+ * Closes the page and context. Playwright only finalizes a recording when the
+ * page closes, so the caller finalizes video after this returns.
+ *
+ * Returns cleanup errors rather than throwing so the caller can preserve a
+ * primary failure and still record what went wrong during teardown.
+ */
+export async function closeTutorialSession(session) {
+    const errors = [];
+    if (typeof session.page.close === "function") {
+        const pageError = await closeQuietly(() => session.page.close());
+        if (pageError) {
+            errors.push(`Tutorial page close failed: ${pageError}`);
+        }
+    }
+    const contextError = await closeQuietly(() => session.context.close());
+    if (contextError) {
+        errors.push(`Tutorial browser context close failed: ${contextError}`);
+    }
+    return errors;
+}
+/**
+ * Runs every step in declared order against one page.
+ *
+ * Failure semantics, in the planner's order: an action failure skips that step's
+ * assertions; assertion failures do not short-circuit each other within the same
+ * step (all are collected so a reader sees the full picture); either kind of
+ * failure stops later steps, which are reported as "not-run" rather than omitted
+ * or reported as passed.
+ *
+ * Per-step ordering with visuals enabled:
+ *   clear previous overlays -> pauseBefore -> cursor move -> real action ->
+ *   click feedback -> assertions -> highlight + callout -> pauseAfter ->
+ *   screenshot
+ * so a screenshot always shows the final intended state of its step.
+ */
+export async function executeTutorialSteps(options) {
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? Date.now;
+    const timelineOrigin = now();
+    const steps = [];
+    const screenshots = [];
+    const visualWarnings = [];
+    let failedStepId;
+    let failureMessage;
+    /**
+     * Installing is idempotent, and a navigation replaces the whole document, so
+     * the tutorial-owned visual root has to be re-established rather than assumed
+     * to survive. Calling this at the start of every step and again after a
+     * successful goto keeps the cursor present without tracking navigations.
+     */
+    const ensureVisuals = async (stepId) => {
+        if (!options.visuals) {
+            return;
+        }
+        await runVisual(visualWarnings, stepId, "install cursor", () => installTutorialCursor(options.page));
+    };
+    await ensureVisuals("<session>");
+    for (const step of options.scenario.steps) {
+        if (failedStepId !== undefined) {
+            steps.push(notRunStepResult(step));
+            continue;
+        }
+        const startedAtMs = Date.now();
+        const timelineStartMs = Math.max(0, now() - timelineOrigin);
+        const result = {
+            id: step.id,
+            status: "passed",
+            startedAt: new Date(startedAtMs).toISOString(),
+            timelineStartMs,
+            assertions: [],
+            screenshotRequested: step.screenshot !== undefined,
+            highlightRequested: step.highlight !== undefined,
+            calloutRequested: step.callout !== undefined
+        };
+        if (options.visuals) {
+            // Each step starts from a clean visual slate, on a guaranteed-present root.
+            await ensureVisuals(step.id);
+            await runVisual(visualWarnings, step.id, "clear overlays", () => clearTutorialStepOverlays(options.page));
+        }
+        if (step.pauseBeforeMs !== undefined && step.pauseBeforeMs > 0) {
+            await sleep(step.pauseBeforeMs);
+        }
+        let actionPhaseCompleted = true;
+        if (step.action) {
+            const cursorTarget = options.visuals
+                ? await moveCursorForAction(options, step.action, visualWarnings, step.id, sleep)
+                : undefined;
+            const actionResult = await executeTutorialAction(options.page, step.action, {
+                applicationUrl: options.applicationUrl
+            });
+            result.action = actionResult;
+            if (actionResult.status === "failed") {
+                actionPhaseCompleted = false;
+                result.status = "failed";
+                result.error = `Step ${JSON.stringify(step.id)} failed because the ${step.action.type} action failed: ${actionResult.error ?? "unknown error"}`;
+            }
+            else if (options.visuals) {
+                if (step.action.type === "goto") {
+                    // The new document has none of the tutorial's DOM.
+                    await ensureVisuals(step.id);
+                }
+                await applyPostActionVisuals(options, step, cursorTarget, visualWarnings, sleep);
+            }
+        }
+        if (actionPhaseCompleted) {
+            const assertionResults = await runStepAssertions(step, options);
+            result.assertions = assertionResults;
+            const failedAssertions = assertionResults.filter((assertion) => assertion.status === "failed");
+            if (failedAssertions.length > 0) {
+                result.status = "failed";
+                result.error = `Step ${JSON.stringify(step.id)} failed because ${failedAssertions.length} of ${assertionResults.length} assertions failed: ${failedAssertions
+                    .map((assertion) => `${assertion.type}: ${assertion.error ?? "unknown error"}`)
+                    .join("; ")}`;
+            }
+            if (options.visuals) {
+                await applyStepOverlays(options, step, visualWarnings);
+            }
+            if (step.pauseAfterMs !== undefined && step.pauseAfterMs > 0) {
+                await sleep(step.pauseAfterMs);
+            }
+        }
+        if (step.screenshot) {
+            screenshots.push(await captureStepScreenshot(options, step, actionPhaseCompleted));
+        }
+        const endedAtMs = Date.now();
+        result.endedAt = new Date(endedAtMs).toISOString();
+        result.durationMs = endedAtMs - startedAtMs;
+        result.timelineEndMs = Math.max(timelineStartMs, now() - timelineOrigin);
+        steps.push(result);
+        if (result.status === "failed") {
+            failedStepId = step.id;
+            failureMessage = result.error;
+        }
+    }
+    if (options.visuals) {
+        await runVisual(visualWarnings, "<cleanup>", "remove tutorial visuals", () => removeTutorialVisuals(options.page));
+    }
+    return {
+        steps,
+        screenshots,
+        visualWarnings,
+        ...(failedStepId !== undefined ? { failedStepId } : {}),
+        ...(failureMessage !== undefined ? { error: failureMessage } : {})
+    };
+}
+/**
+ * Moves the synthetic cursor onto the action's target before the real action.
+ *
+ * `goto` and `wait-for` have no pointer target, so the cursor is left alone. A
+ * missing bounding box is recorded as a visual warning and the real action still
+ * runs -- presentation never gates correctness.
+ */
+async function moveCursorForAction(options, action, warnings, stepId, sleep) {
+    const locator = cursorLocatorForAction(action);
+    if (!locator) {
+        return undefined;
+    }
+    const box = await readBoundingBox(options.page, locator, warnings, stepId);
+    if (!box) {
+        return undefined;
+    }
+    await runVisual(warnings, stepId, "move cursor", () => moveTutorialCursor(options.page, centerOfBox(box)));
+    await sleep(CURSOR_MOVE_DURATION_MS);
+    return box;
+}
+/** The locator whose center the cursor points at before each action type. */
+export function cursorLocatorForAction(action) {
+    switch (action.type) {
+        case "click":
+        case "fill":
+        case "press":
+        case "hover":
+            return action.locator;
+        case "drag":
+            return action.source;
+        // goto has no element target; wait-for deliberately does not move the cursor.
+        case "goto":
+        case "wait-for":
+            return undefined;
+    }
+}
+async function applyPostActionVisuals(options, step, cursorTarget, warnings, sleep) {
+    const action = step.action;
+    if (!action) {
+        return;
+    }
+    if (action.type === "click" && cursorTarget) {
+        await runVisual(warnings, step.id, "click feedback", () => showTutorialClickFeedback(options.page, centerOfBox(cursorTarget)));
+        // Held only long enough for the ripple to be visible in the recording.
+        await sleep(CLICK_FEEDBACK_DURATION_MS);
+        return;
+    }
+    if (action.type === "drag") {
+        // The cursor follows to the drop target after the real drag completed.
+        const box = await readBoundingBox(options.page, action.target, warnings, step.id);
+        if (box) {
+            await runVisual(warnings, step.id, "move cursor to drag target", () => moveTutorialCursor(options.page, centerOfBox(box)));
+            await sleep(CURSOR_MOVE_DURATION_MS);
+        }
+    }
+}
+async function applyStepOverlays(options, step, warnings) {
+    if (step.highlight) {
+        const box = await readBoundingBox(options.page, step.highlight, warnings, step.id);
+        if (box) {
+            await runVisual(warnings, step.id, "apply highlight", () => applyTutorialHighlight(options.page, box));
+        }
+    }
+    if (step.callout) {
+        const box = step.callout.locator
+            ? await readBoundingBox(options.page, step.callout.locator, warnings, step.id)
+            : undefined;
+        const viewport = options.scenario.browser.viewport;
+        const placement = resolveCalloutPlacement(step.callout.placement, box, viewport);
+        await runVisual(warnings, step.id, "apply callout", () => applyTutorialCallout(options.page, {
+            text: step.callout.text,
+            placement,
+            box: box ?? null,
+            viewport
+        }));
+    }
+}
+/**
+ * Captures a requested screenshot from the already-open tutorial page.
+ *
+ * Never launches a browser and never re-navigates: the point of the capture is
+ * the live state this session just produced.
+ */
+async function captureStepScreenshot(options, step, actionPhaseCompleted) {
+    const screenshot = step.screenshot;
+    if (!options.paths) {
+        return {
+            kind: "screenshot",
+            id: screenshot.id,
+            status: "failed",
+            error: `Screenshot ${JSON.stringify(screenshot.id)} was requested but the tutorial run has no screenshot output directory.`
+        };
+    }
+    const absolutePath = buildScreenshotPath(options.paths, screenshot.id);
+    const relativePath = toRunRelativePosixPath(options.paths.runRoot, absolutePath);
+    if (!actionPhaseCompleted) {
+        // The step never reached a usable state; fabricating an image would misrepresent it.
+        return {
+            kind: "screenshot",
+            id: screenshot.id,
+            status: "skipped",
+            path: relativePath,
+            error: `Screenshot ${JSON.stringify(screenshot.id)} was not captured because step ${JSON.stringify(step.id)} failed before reaching a usable state.`
+        };
+    }
+    if (existsSync(absolutePath)) {
+        // Canonical screenshot identity is stable; silently overwriting or adding a
+        // suffix would both hide a real problem.
+        return {
+            kind: "screenshot",
+            id: screenshot.id,
+            status: "failed",
+            path: relativePath,
+            error: `Screenshot ${JSON.stringify(screenshot.id)} already exists at ${relativePath}; refusing to overwrite a canonical tutorial artifact.`
+        };
+    }
+    try {
+        await options.page.screenshot({ path: absolutePath, fullPage: screenshot.fullPage ?? false });
+    }
+    catch (error) {
+        return {
+            kind: "screenshot",
+            id: screenshot.id,
+            status: "failed",
+            path: relativePath,
+            error: `Screenshot ${JSON.stringify(screenshot.id)} could not be captured: ${messageOf(error)}`
+        };
+    }
+    const check = await verifyArtifactFile(absolutePath);
+    if (!check.ok) {
+        return { kind: "screenshot", id: screenshot.id, status: "failed", path: relativePath, error: check.error };
+    }
+    return {
+        kind: "screenshot",
+        id: screenshot.id,
+        status: "written",
+        path: relativePath,
+        sizeBytes: check.sizeBytes
+    };
+}
+async function readBoundingBox(page, locator, warnings, stepId) {
+    try {
+        const box = await resolveTutorialLocator(page, locator).boundingBox();
+        if (!box) {
+            warnings.push(`Step ${JSON.stringify(stepId)}: ${describeTutorialLocator(locator)} has no bounding box, so its tutorial visual was skipped.`);
+            return undefined;
+        }
+        return box;
+    }
+    catch (error) {
+        warnings.push(`Step ${JSON.stringify(stepId)}: bounding box for ${describeTutorialLocator(locator)} could not be read: ${messageOf(error)}`);
+        return undefined;
+    }
+}
+/**
+ * Runs one presentation operation. A failure here is recorded as a visual
+ * warning, never swallowed and never promoted into an action/assertion outcome.
+ */
+async function runVisual(warnings, stepId, description, operation) {
+    try {
+        await operation();
+    }
+    catch (error) {
+        warnings.push(`Step ${JSON.stringify(stepId)}: tutorial visual "${description}" failed: ${messageOf(error)}`);
+    }
+}
+async function runStepAssertions(step, options) {
+    const results = [];
+    for (const assertion of step.assertions ?? []) {
+        results.push(await executeTutorialAssertion(options.page, assertion, {
+            applicationUrl: options.applicationUrl,
+            targetRoot: options.targetRoot
+        }));
+    }
+    return results;
+}
+function notRunStepResult(step) {
+    return {
+        id: step.id,
+        status: "not-run",
+        assertions: [],
+        screenshotRequested: step.screenshot !== undefined,
+        highlightRequested: step.highlight !== undefined,
+        calloutRequested: step.callout !== undefined
+    };
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function closeQuietly(close) {
+    try {
+        await close();
+        return undefined;
+    }
+    catch (error) {
+        return messageOf(error);
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}