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

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/tutorialPointerGeometry.js

@@ -0,0 +1,16 @@
+/** Converts a validated locator-relative fraction into page coordinates. */
+export function resolveTutorialFractionPoint(box, point) {
+    if (![box.x, box.y, box.width, box.height].every(Number.isFinite)) {
+        throw new Error("Tutorial pointer bounding box values must all be finite.");
+    }
+    if (box.width <= 0 || box.height <= 0) {
+        throw new Error("Tutorial pointer bounding box must have positive width and height.");
+    }
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.y) || point.x < 0 || point.x > 1 || point.y < 0 || point.y > 1) {
+        throw new Error("Tutorial pointer fractions must be finite numbers within inclusive bounds [0, 1].");
+    }
+    return {
+        x: box.x + box.width * point.x,
+        y: box.y + box.height * point.y
+    };
+}