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

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to my-dev-kit-lab are documented here.
 
+## [0.4.8] - 2026-09-19
+
+Locator-anchored pointer gestures for declarative browser tutorials.
+
+- Added `pointer-click` and `pointer-drag` declarative tutorial actions anchored to a single `TutorialLocatorV1` interaction surface.
+- Added normalized fraction coordinates (`coordinateSpace: "fraction"`) with inclusive `[0, 1]` bounds and zero-length pointer-drag rejection.
+- Used real Playwright mouse input (`mouse.move`, `mouse.down`, `mouse.up`) with a fixed 8-step drag movement (`POINTER_DRAG_MOVE_STEPS = 8`) and robust `mouse.up` error cleanup.
+- Preserved existing element-to-element `drag` (`source` and `target` locators via Playwright `dragTo`) and all existing scenario action/assertion behaviors without change.
+- Preserved closed security boundaries: no arbitrary JavaScript, no `page.evaluate` callbacks, no generic DOM event dispatch, no shell actions, and no unanchored page/screen coordinates.
+- Extended the generic real-browser fixture (`examples/tutorial-browser/`) with an interactive SVG pointer surface, verifying pointer clicks, pointer drags, and intermediate pointermove tracking through genuine Chromium.
+- Extended packed-package verification (`npm run verify:packed-package`) to validate and execute the new pointer actions against a clean installed-tarball consumer while maintaining package, target, and example immutability.
+- Validated downstream `my-frontend-observer` compatibility evidence as a read-only compatibility consumer (rectangle, line, arrow, point, and note gestures confirmed expressible without Observer code modifications or runtime dependencies).
+- Kept `TutorialScenarioV1`, `TutorialTargetContractV1`, `TutorialRunResultV1`, and `TutorialManifestV1` schemas at version `1.0.0`.
+
 ## [0.4.7] - 2026-09-18
 
 The v0.4.7 implementation adds generic declarative browser tutorial automation while preserving product-specific demo ownership outside this repository.

package/README.md

@@ -4,7 +4,7 @@ my-dev-kit-lab is the experiment, audit, and evidence companion for [my-dev-kit]
 
 my-dev-kit provides local repository indexing and graph-guided retrieval. my-dev-kit-lab supplies the controlled benchmarks, agent adapters, metrics, security checks, and reports needed to evaluate when that retrieval is useful. Results are evidence for a specific target and configuration; they do not guarantee token savings or security.
 
-The latest published release is v0.4.7 (declarative browser tutorial and video automation). It adds bounded browser scenarios, persistent tutorial sessions, synchronized runtime artifacts, and a packaged generic example while preserving product-specific demo ownership outside this repository. The v0.4.5 context-integrity evaluation remains intentionally frozen against the published `@dailephd/my-dev-kit@1.10.4` and `@dailephd/my-dev-kit-orchestrator@1.2.3` contracts; those versions are historical validation baselines, not a statement that they are the ecosystem's current releases. See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md).
+The latest release is v0.4.8 (locator-anchored pointer gestures for declarative browser tutorials, adding `pointer-click` and `pointer-drag` using normalized locator-relative fraction positions while existing `drag` remains element-to-element). The v0.4.5 context-integrity evaluation remains intentionally frozen against the published `@dailephd/my-dev-kit@1.10.4` and `@dailephd/my-dev-kit-orchestrator@1.2.3` contracts; those versions are historical validation baselines, not a statement that they are the ecosystem's current releases. See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md).
 
 v0.4.6 adds a supported `my-dev-kit-lab` installed CLI router (`--help`, `--version`, `security validate`, `audit`, the `experiment` family, `report render`, `plots generate`, `gallery build`, `demo final`, and the historical direct final-demo invocation form), a writable lab workspace model kept separate from the installed package and the inspected target, and a permanent packed-tarball installation/execution acceptance gate (`npm run verify:packed-package`). See [docs/ROADMAP.md](docs/ROADMAP.md) and [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for status detail and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the runtime path model. The "Installed CLI" section below documents the shipped command surface; the source-checkout `npm run` workflow in Quickstart remains available for contributors.
 
@@ -15,7 +15,7 @@ v0.4.6 adds a supported `my-dev-kit-lab` installed CLI router (`--help`, `--vers
 - **Validate CLI/package security:** inspect dependencies, package contents, path and subprocess boundaries, malformed inputs, optional static scanners, and bounded fuzz targets.
 - **Validate Android projects:** run nineteen static checks by default, with Gradle operations, external tools, and network access available only through explicit opt-in flags.
 - **Review evidence:** generate JSON and HTML reports, SVG plots, optional screenshots, visualization demos, and a static gallery.
-- **Generate declarative browser tutorials:** validate and execute bounded local browser scenarios with WebM recording, step screenshots, SRT/VTT subtitles, Markdown, and a tutorial manifest. Tutorial execution requires a compatible locally installed Chromium; see [docs/COMMANDS.md](docs/COMMANDS.md) and [docs/TUTORIAL.md](docs/TUTORIAL.md) for details.
+- **Generate declarative browser tutorials:** validate and execute bounded local browser scenarios with WebM recording, step screenshots, SRT/VTT subtitles, Markdown, and a tutorial manifest. Locator-anchored pointer gestures (`pointer-click` and `pointer-drag`) operate using normalized fraction coordinates inside a single located surface, while existing `drag` remains element-to-element. Tutorial execution requires a compatible locally installed Chromium; see [docs/COMMANDS.md](docs/COMMANDS.md) and [docs/TUTORIAL.md](docs/TUTORIAL.md) for details.
 - **Evaluate stage-context strategies:** compare the two legacy strategies against six additional bounded stage-context strategies — `architecture-context-only`, `architecture-plus-implementation-refresh`, `architecture-plus-implementation-and-test-refresh`, `full-workflow-library`, `bounded-workflow-instruction-packet`, and `combined-bounded-stage-context` — selected through programmatic configuration, not CLI flags. Each strategy's evidence is reported through bounded `report.json`, `report.html`, and `report.txt` output with an explicit `available`/`unavailable`/`not-applicable` metric-availability model and no composite score, grade, ranking, or winning strategy.
 - **Evaluate the producer-readiness bridge (v0.4.4):** optionally extend `combined-bounded-stage-context` with the frozen my-dev-kit-orchestrator supplemental implementation/test-context packet and retrieval-report documents plus an observed readiness result, all supplied programmatically (there is no CLI flag), to measure owner, allocation, truncation-cause, supplemental/raw agreement, readiness-agreement, and criticality-overlay evidence without reimplementing upstream owner-selection, allocation, producer-parity, or readiness policy.
 - **Evaluate context integrity (v0.4.5):** compare condition-aware producer evidence from my-dev-kit v1.10.4 (role condition coverage, allocation/spillover, required-evidence-loss) against my-dev-kit-orchestrator v1.2.3 run-integrity evidence (run-integrity gate, judge integrity, final-report eligibility, artifact lifecycle state), reporting agreement or contradiction between them rather than re-deriving a verdict. Evaluation runs against a frozen, hash-verified regression fixture pair — a byte-exact real historical failed run and a hand-distilled corrected-replay counterpart representing the same validated contracts — and is programmatic/test-driven only. `npm run report:context-integrity-smoke` renders both fixtures' reports for manual inspection; it takes no arguments and is a developer convenience, not a configurable evaluation CLI.
@@ -208,7 +208,8 @@ See [docs/METRICS.md](docs/METRICS.md) for full metric definitions.
 - The published upstream artifacts the stage-context strategies read do not expose considered-but-unselected reads or unnecessary-read evidence; those metrics report `unavailable` rather than zero
 - The v0.4.4 producer-readiness bridge is released. All bridge inputs are programmatic — there is no CLI flag. The coordinated upstream releases my-dev-kit@1.10.3 and orchestrator@1.2.2 were verified published before lab publication.
 - The v0.4.5 context-integrity evaluation is released. It has no CLI flags, no plots/screenshot/gallery integration, and produces no composite score, grade, ranking, or winner. Its corrected-replay fixture is a hand-distilled representation of the validated my-dev-kit v1.10.4 and my-dev-kit-orchestrator v1.2.3 contracts, not a live capture of a complete ten-stage workflow. The orchestrator agreement evidence does not read a literal upstream `promptMode` field; `stageMayRenderNormalPrompt`, derived from structured blocked-stage evidence, is the bounded substitute used instead.
-- v0.4.7 adds declarative browser tutorial validation and execution with bounded actions/assertions, persistent Chromium sessions, WebM, screenshots, SRT/VTT, Markdown, and `tutorial-manifest.json`. Chromium is a separate local runtime prerequisite; the package does not download browser binaries automatically. Gallery consumption remains future scope.
+- v0.4.7 added declarative browser tutorial validation and execution with bounded actions/assertions, persistent Chromium sessions, WebM, screenshots, SRT/VTT, Markdown, and `tutorial-manifest.json`. Chromium is a separate local runtime prerequisite; the package does not download browser binaries automatically. Gallery consumption remains future scope.
+- v0.4.8 added `pointer-click` and `pointer-drag` for normalized fraction positions inside a single located element. Existing `drag` remains element-to-element between source and target locators.
 
 ---
 

package/dist/src/tutorial/index.js

@@ -5,6 +5,7 @@ export * from "./loadTutorialContracts.js";
 export * from "./tutorialPaths.js";
 export * from "./tutorialLocators.js";
 export * from "./tutorialActions.js";
+export * from "./tutorialPointerGeometry.js";
 export * from "./tutorialAssertions.js";
 export * from "./tutorialCursor.js";
 export * from "./tutorialOverlay.js";

package/dist/src/tutorial/scenarioValidation.js

@@ -1,4 +1,4 @@
-import { MAX_STEP_PAUSE_MS, MAX_TUTORIAL_STEPS, MAX_VIEWPORT_HEIGHT, MAX_VIEWPORT_WIDTH, MIN_VIEWPORT_HEIGHT, MIN_VIEWPORT_WIDTH, TUTORIAL_ACTION_TYPES, TUTORIAL_ASSERTION_TYPES, TUTORIAL_CALLOUT_PLACEMENTS, TUTORIAL_GOTO_WAIT_UNTIL, TUTORIAL_LOCATOR_KINDS, TUTORIAL_SCHEMA_VERSION, TUTORIAL_WAIT_FOR_STATES } from "./types.js";
+import { MAX_STEP_PAUSE_MS, MAX_TUTORIAL_STEPS, MAX_VIEWPORT_HEIGHT, MAX_VIEWPORT_WIDTH, MIN_VIEWPORT_HEIGHT, MIN_VIEWPORT_WIDTH, TUTORIAL_ACTION_TYPES, TUTORIAL_ASSERTION_TYPES, TUTORIAL_CALLOUT_PLACEMENTS, TUTORIAL_GOTO_WAIT_UNTIL, TUTORIAL_LOCATOR_KINDS, TUTORIAL_POINTER_COORDINATE_SPACES, TUTORIAL_SCHEMA_VERSION, TUTORIAL_WAIT_FOR_STATES } from "./types.js";
 import { createErrorCollector, describeValue, isJsonScalar, isNonEmptyString, isNonNegativeInteger, isPlainObject, rejectUnknownKeys, validateOptionalTimeout, validateSchemaVersion, validateStableId } from "./validationPrimitives.js";
 const SCENARIO_KEYS = ["schemaVersion", "id", "title", "description", "targetId", "browser", "steps"];
 const STEP_KEYS = [
@@ -266,6 +266,29 @@ export function validateAction(errors, location, value) {
             validateLocator(errors, `${location}.target`, value.target);
             validateOptionalTimeout(errors, `${location}.timeoutMs`, value.timeoutMs);
             break;
+        case "pointer-click":
+            rejectUnknownKeys(errors, location, value, ["type", "locator", "position", "coordinateSpace", "timeoutMs"]);
+            validateLocator(errors, `${location}.locator`, value.locator);
+            validateFractionPoint(errors, `${location}.position`, value.position);
+            validatePointerCoordinateSpace(errors, `${location}.coordinateSpace`, value.coordinateSpace);
+            validateOptionalTimeout(errors, `${location}.timeoutMs`, value.timeoutMs);
+            break;
+        case "pointer-drag": {
+            rejectUnknownKeys(errors, location, value, ["type", "locator", "from", "to", "coordinateSpace", "timeoutMs"]);
+            validateLocator(errors, `${location}.locator`, value.locator);
+            const fromValid = validateFractionPoint(errors, `${location}.from`, value.from);
+            const toValid = validateFractionPoint(errors, `${location}.to`, value.to);
+            validatePointerCoordinateSpace(errors, `${location}.coordinateSpace`, value.coordinateSpace);
+            validateOptionalTimeout(errors, `${location}.timeoutMs`, value.timeoutMs);
+            if (fromValid && toValid) {
+                const from = value.from;
+                const to = value.to;
+                if (from.x === to.x && from.y === to.y) {
+                    errors.add(`${location}.to`, "pointer-drag endpoints must be distinct; zero-length drags are not allowed.");
+                }
+            }
+            break;
+        }
         case "wait-for":
             rejectUnknownKeys(errors, location, value, ["type", "locator", "state", "timeoutMs"]);
             validateLocator(errors, `${location}.locator`, value.locator);
@@ -276,6 +299,27 @@ export function validateAction(errors, location, value) {
             break;
     }
 }
+function validateFractionPoint(errors, location, value) {
+    if (!isPlainObject(value)) {
+        errors.add(location, `expected a fraction point object, received ${describeValue(value)}.`);
+        return false;
+    }
+    const startLength = errors.length;
+    rejectUnknownKeys(errors, location, value, ["x", "y"]);
+    validateFractionCoordinate(errors, `${location}.x`, value.x);
+    validateFractionCoordinate(errors, `${location}.y`, value.y);
+    return errors.length === startLength;
+}
+function validateFractionCoordinate(errors, location, value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+        errors.add(location, `expected a finite number within inclusive bounds [0, 1], received ${describeValue(value)}.`);
+    }
+}
+function validatePointerCoordinateSpace(errors, location, value) {
+    if (!TUTORIAL_POINTER_COORDINATE_SPACES.includes(value)) {
+        errors.add(location, `expected "fraction", received ${describeValue(value)}.`);
+    }
+}
 /**
  * A scenario may only navigate inside the target application's own origin, so a
  * goto path is a root-relative path, never a URL. Rejecting the URL forms here

package/dist/src/tutorial/tutorialActions.js

@@ -1,5 +1,7 @@
 import { describeTutorialLocator, resolveTutorialLocator } from "./tutorialLocators.js";
+import { resolveTutorialFractionPoint } from "./tutorialPointerGeometry.js";
 import { DEFAULT_TUTORIAL_ACTION_TIMEOUT_MS } from "./types.js";
+export const POINTER_DRAG_MOVE_STEPS = 8;
 /**
  * Resolves a scenario `goto` path against the target application's URL and
  * proves the result never leaves that origin.
@@ -72,6 +74,31 @@ async function performAction(page, action, context) {
             await source.dragTo(target, { timeout: timeoutFor(action.timeoutMs) });
             return;
         }
+        case "pointer-click": {
+            const locator = resolveTutorialLocator(page, action.locator);
+            await locator.waitFor({ state: "visible", timeout: timeoutFor(action.timeoutMs) });
+            const box = await locator.boundingBox();
+            if (!box) {
+                throw new Error("locator has no bounding box");
+            }
+            const point = resolveTutorialFractionPoint(box, action.position);
+            await page.mouse.move(point.x, point.y);
+            await runWithMouseDown(page.mouse, async () => { });
+            return;
+        }
+        case "pointer-drag": {
+            const locator = resolveTutorialLocator(page, action.locator);
+            await locator.waitFor({ state: "visible", timeout: timeoutFor(action.timeoutMs) });
+            const box = await locator.boundingBox();
+            if (!box) {
+                throw new Error("locator has no bounding box");
+            }
+            const start = resolveTutorialFractionPoint(box, action.from);
+            const end = resolveTutorialFractionPoint(box, action.to);
+            await page.mouse.move(start.x, start.y);
+            await runWithMouseDown(page.mouse, () => page.mouse.move(end.x, end.y, { steps: POINTER_DRAG_MOVE_STEPS }));
+            return;
+        }
         case "wait-for":
             await resolveTutorialLocator(page, action.locator).waitFor({
                 ...(action.state !== undefined ? { state: action.state } : {}),
@@ -80,6 +107,34 @@ async function performAction(page, action, context) {
             return;
     }
 }
+async function runWithMouseDown(mouse, operation) {
+    await mouse.down();
+    let primaryError;
+    let primaryFailed = false;
+    try {
+        await operation();
+    }
+    catch (error) {
+        primaryFailed = true;
+        primaryError = error;
+    }
+    try {
+        await mouse.up();
+    }
+    catch (cleanupError) {
+        if (primaryFailed) {
+            const primaryMessage = messageOf(primaryError);
+            const cleanupMessage = messageOf(cleanupError);
+            throw new Error(`${primaryMessage} (mouse.up cleanup also failed: ${cleanupMessage})`, {
+                cause: primaryError
+            });
+        }
+        throw cleanupError;
+    }
+    if (primaryFailed) {
+        throw primaryError;
+    }
+}
 export function timeoutFor(timeoutMs) {
     return timeoutMs ?? DEFAULT_TUTORIAL_ACTION_TIMEOUT_MS;
 }
@@ -100,6 +155,10 @@ function describeActionError(action, error) {
             return `goto ${JSON.stringify(action.path)} failed: ${message}`;
         case "drag":
             return `drag from ${describeTutorialLocator(action.source)} to ${describeTutorialLocator(action.target)} failed: ${message}`;
+        case "pointer-click":
+            return `pointer-click on ${describeTutorialLocator(action.locator)} at fraction ${describeFractionPoint(action.position)} failed: ${message}`;
+        case "pointer-drag":
+            return `pointer-drag on ${describeTutorialLocator(action.locator)} from fraction ${describeFractionPoint(action.from)} to ${describeFractionPoint(action.to)} failed: ${message}`;
         case "click":
         case "fill":
         case "press":
@@ -108,3 +167,9 @@ function describeActionError(action, error) {
             return `${action.type} on ${describeTutorialLocator(action.locator)} failed: ${message}`;
     }
 }
+function describeFractionPoint(point) {
+    return `(${String(point.x)}, ${String(point.y)})`;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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
+    };
+}

package/dist/src/tutorial/tutorialSession.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { executeTutorialAction } from "./tutorialActions.js";
 import { executeTutorialAssertion } from "./tutorialAssertions.js";
 import { resolveTutorialLocator, describeTutorialLocator } from "./tutorialLocators.js";
+import { resolveTutorialFractionPoint } from "./tutorialPointerGeometry.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";
@@ -209,9 +210,27 @@ async function moveCursorForAction(options, action, warnings, stepId, sleep) {
     if (!box) {
         return undefined;
     }
-    await runVisual(warnings, stepId, "move cursor", () => moveTutorialCursor(options.page, centerOfBox(box)));
+    let point;
+    let pointerDragEnd;
+    try {
+        if (action.type === "pointer-click") {
+            point = resolveTutorialFractionPoint(box, action.position);
+        }
+        else if (action.type === "pointer-drag") {
+            point = resolveTutorialFractionPoint(box, action.from);
+            pointerDragEnd = resolveTutorialFractionPoint(box, action.to);
+        }
+        else {
+            point = centerOfBox(box);
+        }
+    }
+    catch (error) {
+        warnings.push(`Step ${JSON.stringify(stepId)}: pointer visual for ${describeTutorialLocator(locator)} could not be planned: ${messageOf(error)}`);
+        return undefined;
+    }
+    await runVisual(warnings, stepId, "move cursor", () => moveTutorialCursor(options.page, point));
     await sleep(CURSOR_MOVE_DURATION_MS);
-    return box;
+    return { point, ...(pointerDragEnd ? { pointerDragEnd } : {}) };
 }
 /** The locator whose center the cursor points at before each action type. */
 export function cursorLocatorForAction(action) {
@@ -220,6 +239,8 @@ export function cursorLocatorForAction(action) {
         case "fill":
         case "press":
         case "hover":
+        case "pointer-click":
+        case "pointer-drag":
             return action.locator;
         case "drag":
             return action.source;
@@ -234,8 +255,8 @@ async function applyPostActionVisuals(options, step, cursorTarget, warnings, sle
     if (!action) {
         return;
     }
-    if (action.type === "click" && cursorTarget) {
-        await runVisual(warnings, step.id, "click feedback", () => showTutorialClickFeedback(options.page, centerOfBox(cursorTarget)));
+    if ((action.type === "click" || action.type === "pointer-click") && cursorTarget) {
+        await runVisual(warnings, step.id, "click feedback", () => showTutorialClickFeedback(options.page, cursorTarget.point));
         // Held only long enough for the ripple to be visible in the recording.
         await sleep(CLICK_FEEDBACK_DURATION_MS);
         return;
@@ -247,6 +268,11 @@ async function applyPostActionVisuals(options, step, cursorTarget, warnings, sle
             await runVisual(warnings, step.id, "move cursor to drag target", () => moveTutorialCursor(options.page, centerOfBox(box)));
             await sleep(CURSOR_MOVE_DURATION_MS);
         }
+        return;
+    }
+    if (action.type === "pointer-drag" && cursorTarget?.pointerDragEnd) {
+        await runVisual(warnings, step.id, "move cursor to pointer-drag endpoint", () => moveTutorialCursor(options.page, cursorTarget.pointerDragEnd));
+        await sleep(CURSOR_MOVE_DURATION_MS);
     }
 }
 async function applyStepOverlays(options, step, warnings) {

package/dist/src/tutorial/types.js

@@ -23,6 +23,7 @@ export const TUTORIAL_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
 /** The only placeholder a trusted target contract may use. */
 export const TARGET_ROOT_PLACEHOLDER = "{{targetRoot}}";
 export const TUTORIAL_LOCATOR_KINDS = ["role", "text", "css", "test-id"];
+export const TUTORIAL_POINTER_COORDINATE_SPACES = ["fraction"];
 export const TUTORIAL_ACTION_TYPES = [
     "goto",
     "click",
@@ -30,7 +31,9 @@ export const TUTORIAL_ACTION_TYPES = [
     "press",
     "hover",
     "drag",
-    "wait-for"
+    "wait-for",
+    "pointer-click",
+    "pointer-drag"
 ];
 export const TUTORIAL_GOTO_WAIT_UNTIL = ["load", "domcontentloaded", "networkidle"];
 export const TUTORIAL_WAIT_FOR_STATES = ["visible", "hidden", "attached", "detached"];

package/examples/tutorial-browser/index.html

@@ -1,47 +1,109 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Tutorial Fixture</title>
-    <style>
-      body { font: 16px/1.5 system-ui, sans-serif; margin: 0; padding: 24px; background: #f6f7f9; color: #111; }
-      h1 { margin: 0 0 16px; font-size: 28px; }
-      .panel { background: #fff; border: 1px solid #d8dbe0; border-radius: 8px; padding: 16px; margin-bottom: 16px; }
-      .row { display: flex; gap: 16px; align-items: flex-start; }
-      .col { flex: 1; }
-      button { font: inherit; padding: 8px 16px; border-radius: 6px; border: 1px solid #5a6270; background: #fff; cursor: pointer; }
-      button:hover { background: #eef1f5; }
-      input { font: inherit; padding: 8px; border: 1px solid #b8bec8; border-radius: 6px; width: 100%; box-sizing: border-box; }
-      .dropzone { min-height: 72px; border: 2px dashed #9aa3af; border-radius: 8px; padding: 12px; }
-      .card { background: #dde7ff; border: 1px solid #5f7fd6; border-radius: 6px; padding: 10px; width: 140px; }
-      .hidden { display: none; }
-      #status-banner { padding: 10px; border-radius: 6px; background: #e8f5e9; border: 1px solid #66bb6a; }
-    </style>
-  </head>
-  <body>
-    <h1 id="page-title">Tutorial Fixture</h1>
-    <div class="panel"><p id="intro-text">Welcome to the generic tutorial fixture.</p><button id="primary-action" data-testid="primary-action" data-state="idle">Activate</button> <span id="activation-count" data-testid="activation-count">0</span></div>
-    <div class="panel"><label for="name-field">Your name</label><input id="name-field" data-testid="name-field" aria-label="Your name" /><p id="greeting" data-testid="greeting"></p></div>
-    <div class="panel"><button id="hover-target" data-testid="hover-target">Hover me</button><p id="hover-readout" data-testid="hover-readout">not hovered</p></div>
-    <div class="panel row"><div class="col"><div id="drag-card" data-testid="drag-card" class="card" draggable="true">Draggable card</div></div><div class="col"><div id="drop-zone" data-testid="drop-zone" class="dropzone">Drop target</div></div></div>
-    <div class="panel"><div id="status-banner" data-testid="status-banner" class="hidden">Delayed banner is now visible</div></div>
-    <script>
-      (() => {
-        let activations = 0;
-        const primary = document.getElementById("primary-action");
-        primary.addEventListener("click", () => { activations += 1; document.getElementById("activation-count").textContent = String(activations); primary.setAttribute("data-state", "activated"); });
-        const nameField = document.getElementById("name-field");
-        const greeting = document.getElementById("greeting");
-        nameField.addEventListener("input", () => { greeting.textContent = nameField.value ? `Hello, ${nameField.value}` : ""; });
-        nameField.addEventListener("keydown", event => { if (event.key === "Enter") greeting.textContent = `Submitted: ${nameField.value}`; });
-        document.getElementById("hover-target").addEventListener("mouseenter", () => { document.getElementById("hover-readout").textContent = "hovered"; });
-        const dragCard = document.getElementById("drag-card");
-        const dropZone = document.getElementById("drop-zone");
-        dragCard.addEventListener("dragstart", event => event.dataTransfer.setData("text/plain", "drag-card"));
-        dropZone.addEventListener("dragover", event => event.preventDefault());
-        dropZone.addEventListener("drop", event => { event.preventDefault(); dropZone.textContent = "Dropped"; dropZone.setAttribute("data-dropped", "true"); });
-        window.setTimeout(() => document.getElementById("status-banner").classList.remove("hidden"), 300);
-      })();
-    </script>
-  </body>
-</html>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Tutorial Fixture</title>
+    <style>
+      body { font: 16px/1.5 system-ui, sans-serif; margin: 0; padding: 24px; background: #f6f7f9; color: #111; }
+      h1 { margin: 0 0 16px; font-size: 28px; }
+      .panel { background: #fff; border: 1px solid #d8dbe0; border-radius: 8px; padding: 16px; margin-bottom: 16px; }
+      .row { display: flex; gap: 16px; align-items: flex-start; }
+      .col { flex: 1; }
+      button { font: inherit; padding: 8px 16px; border-radius: 6px; border: 1px solid #5a6270; background: #fff; cursor: pointer; }
+      button:hover { background: #eef1f5; }
+      input { font: inherit; padding: 8px; border: 1px solid #b8bec8; border-radius: 6px; width: 100%; box-sizing: border-box; }
+      .dropzone { min-height: 72px; border: 2px dashed #9aa3af; border-radius: 8px; padding: 12px; }
+      .card { background: #dde7ff; border: 1px solid #5f7fd6; border-radius: 6px; padding: 10px; width: 140px; }
+      #pointer-surface { display: block; width: 400px; height: 240px; background: #eef4ff; box-shadow: inset 0 0 0 2px #7890c2; touch-action: none; user-select: none; }
+      .hidden { display: none; }
+      #status-banner { padding: 10px; border-radius: 6px; background: #e8f5e9; border: 1px solid #66bb6a; }
+    </style>
+  </head>
+  <body>
+    <h1 id="page-title">Tutorial Fixture</h1>
+    <div class="panel row"><div class="col"><div id="drag-card" data-testid="drag-card" class="card" draggable="true">Draggable card</div></div><div class="col"><div id="drop-zone" data-testid="drop-zone" class="dropzone">Drop target</div></div></div>
+    <div class="panel"><svg id="pointer-surface" data-testid="pointer-surface" width="400" height="240" viewBox="0 0 400 240" aria-label="Pointer gesture surface" data-pointer-click-count="0" data-last-pointer-click-zone="none" data-pointer-drag-count="0" data-pointer-drag-start-zone="none" data-pointer-drag-end-zone="none" data-pointer-drag-intermediate="false"><line id="pointer-drag-evidence" x1="0" y1="0" x2="0" y2="0" stroke="#3659a2" stroke-width="4" visibility="hidden" pointer-events="none"></line><circle id="pointer-click-evidence" cx="0" cy="0" r="8" fill="#d94f04" visibility="hidden" pointer-events="none"></circle></svg></div>
+    <div class="panel"><p id="intro-text">Welcome to the generic tutorial fixture.</p><button id="primary-action" data-testid="primary-action" data-state="idle">Activate</button> <span id="activation-count" data-testid="activation-count">0</span></div>
+    <div class="panel"><label for="name-field">Your name</label><input id="name-field" data-testid="name-field" aria-label="Your name" /><p id="greeting" data-testid="greeting"></p></div>
+    <div class="panel"><button id="hover-target" data-testid="hover-target">Hover me</button><p id="hover-readout" data-testid="hover-readout">not hovered</p></div>
+    <div class="panel"><div id="status-banner" data-testid="status-banner" class="hidden">Delayed banner is now visible</div></div>
+    <script>
+      (() => {
+        let activations = 0;
+        const primary = document.getElementById("primary-action");
+        primary.addEventListener("click", () => { activations += 1; document.getElementById("activation-count").textContent = String(activations); primary.setAttribute("data-state", "activated"); });
+        const nameField = document.getElementById("name-field");
+        const greeting = document.getElementById("greeting");
+        nameField.addEventListener("input", () => { greeting.textContent = nameField.value ? `Hello, ${nameField.value}` : ""; });
+        nameField.addEventListener("keydown", event => { if (event.key === "Enter") greeting.textContent = `Submitted: ${nameField.value}`; });
+        document.getElementById("hover-target").addEventListener("mouseenter", () => { document.getElementById("hover-readout").textContent = "hovered"; });
+        const dragCard = document.getElementById("drag-card");
+        const dropZone = document.getElementById("drop-zone");
+        dragCard.addEventListener("dragstart", event => event.dataTransfer.setData("text/plain", "drag-card"));
+        dropZone.addEventListener("dragover", event => event.preventDefault());
+        dropZone.addEventListener("drop", event => { event.preventDefault(); dropZone.textContent = "Dropped"; dropZone.setAttribute("data-dropped", "true"); });
+        const pointerSurface = document.getElementById("pointer-surface");
+        const clickEvidence = document.getElementById("pointer-click-evidence");
+        const dragEvidence = document.getElementById("pointer-drag-evidence");
+        const POINTER_CLICK_THRESHOLD = 0.01;
+        let activePointerId = null;
+        let pointerStart = null;
+        let pointerLatest = null;
+        let activeMoveCount = 0;
+        let pointerClickCount = 0;
+        let pointerDragCount = 0;
+        const fractionPoint = event => {
+          const box = pointerSurface.getBoundingClientRect();
+          return {
+            x: Math.max(0, Math.min(1, (event.clientX - box.left) / box.width)),
+            y: Math.max(0, Math.min(1, (event.clientY - box.top) / box.height))
+          };
+        };
+        const zoneFor = point => point.x < 0.5
+          ? (point.y < 0.5 ? "upper-left" : "lower-left")
+          : (point.y < 0.5 ? "upper-right" : "lower-right");
+        pointerSurface.addEventListener("pointerdown", event => {
+          activePointerId = event.pointerId;
+          pointerStart = fractionPoint(event);
+          pointerLatest = pointerStart;
+          activeMoveCount = 0;
+          pointerSurface.setPointerCapture(event.pointerId);
+        });
+        pointerSurface.addEventListener("pointermove", event => {
+          if (event.pointerId !== activePointerId || !pointerStart) return;
+          activeMoveCount += 1;
+          pointerLatest = fractionPoint(event);
+        });
+        pointerSurface.addEventListener("pointerup", event => {
+          if (event.pointerId !== activePointerId || !pointerStart) return;
+          const pointerEnd = fractionPoint(event);
+          const distance = Math.hypot(pointerEnd.x - pointerStart.x, pointerEnd.y - pointerStart.y);
+          if (distance <= POINTER_CLICK_THRESHOLD) {
+            pointerClickCount += 1;
+            pointerSurface.setAttribute("data-pointer-click-count", String(pointerClickCount));
+            pointerSurface.setAttribute("data-last-pointer-click-zone", zoneFor(pointerEnd));
+            clickEvidence.setAttribute("cx", String(pointerEnd.x * 400));
+            clickEvidence.setAttribute("cy", String(pointerEnd.y * 240));
+            clickEvidence.setAttribute("visibility", "visible");
+          } else {
+            pointerDragCount += 1;
+            pointerSurface.setAttribute("data-pointer-drag-count", String(pointerDragCount));
+            pointerSurface.setAttribute("data-pointer-drag-start-zone", zoneFor(pointerStart));
+            pointerSurface.setAttribute("data-pointer-drag-end-zone", zoneFor(pointerEnd));
+            pointerSurface.setAttribute("data-pointer-drag-intermediate", String(activeMoveCount >= 2));
+            dragEvidence.setAttribute("x1", String(pointerStart.x * 400));
+            dragEvidence.setAttribute("y1", String(pointerStart.y * 240));
+            dragEvidence.setAttribute("x2", String(pointerEnd.x * 400));
+            dragEvidence.setAttribute("y2", String(pointerEnd.y * 240));
+            dragEvidence.setAttribute("visibility", "visible");
+          }
+          pointerLatest = pointerEnd;
+          activePointerId = null;
+          pointerStart = null;
+          void pointerLatest;
+        });
+        window.setTimeout(() => document.getElementById("status-banner").classList.remove("hidden"), 300);
+      })();
+    </script>
+  </body>
+</html>

package/examples/tutorial-browser/scenario.json

@@ -1,17 +1,19 @@
-{
-  "schemaVersion": "1.0.0",
-  "id": "lab-browser-fixture",
-  "title": "Lab browser fixture tutorial",
-  "description": "A generic, lab-owned tutorial that exercises browser actions, locators, assertions and visual declarations against a local static fixture app.",
-  "targetId": "lab-browser-fixture",
-  "browser": { "viewport": { "width": 1024, "height": 768 } },
-  "steps": [
-    { "id": "open-app", "narration": "Open the fixture application in the browser.", "action": { "type": "goto", "path": "/", "waitUntil": "load" }, "highlight": { "kind": "css", "selector": "#page-title" }, "callout": { "text": "This is the fixture application.", "locator": { "kind": "css", "selector": "#page-title" }, "placement": "bottom" }, "screenshot": { "id": "app-open" }, "assertions": [ { "type": "url-path-equals", "expected": "/" }, { "type": "element-visible", "locator": { "kind": "role", "role": "heading", "name": "Tutorial Fixture" } }, { "type": "text-equals", "locator": { "kind": "css", "selector": "#page-title" }, "expected": "Tutorial Fixture" }, { "type": "file-exists", "path": "out/report.json" }, { "type": "json-file-equals", "path": "out/report.json", "pointer": "/counts/widgets", "expected": 3 }, { "type": "http-json-equals", "path": "/api/status", "pointer": "/ok", "expected": true } ] },
-    { "id": "activate", "narration": "Click the primary action button to activate the panel.", "action": { "type": "click", "locator": { "kind": "test-id", "testId": "primary-action" } }, "highlight": { "kind": "test-id", "testId": "primary-action" }, "callout": { "text": "Clicking here activates the panel.", "placement": "auto", "locator": { "kind": "test-id", "testId": "primary-action" } }, "screenshot": { "id": "activated" }, "assertions": [ { "type": "text-equals", "locator": { "kind": "test-id", "testId": "activation-count" }, "expected": "1" }, { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "primary-action" }, "name": "data-state", "expected": "activated" } ] },
-    { "id": "fill-name", "narration": "Type a name into the form field.", "action": { "type": "fill", "locator": { "kind": "test-id", "testId": "name-field" }, "value": "Ada" }, "assertions": [ { "type": "text-contains", "locator": { "kind": "test-id", "testId": "greeting" }, "expected": "Hello, Ada" } ] },
-    { "id": "submit-name", "narration": "Press Enter to submit the name.", "action": { "type": "press", "locator": { "kind": "test-id", "testId": "name-field" }, "key": "Enter" }, "screenshot": { "id": "submitted" }, "assertions": [ { "type": "text-contains", "locator": { "kind": "test-id", "testId": "greeting" }, "expected": "Submitted: Ada" } ] },
-    { "id": "hover-button", "narration": "Hover the secondary button to reveal its state.", "action": { "type": "hover", "locator": { "kind": "test-id", "testId": "hover-target" } }, "assertions": [ { "type": "text-equals", "locator": { "kind": "test-id", "testId": "hover-readout" }, "expected": "hovered" } ] },
-    { "id": "drag-card", "narration": "Drag the card onto the drop target.", "action": { "type": "drag", "source": { "kind": "test-id", "testId": "drag-card" }, "target": { "kind": "test-id", "testId": "drop-zone" } }, "highlight": { "kind": "test-id", "testId": "drop-zone" }, "screenshot": { "id": "dropped" }, "assertions": [ { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "drop-zone" }, "name": "data-dropped", "expected": "true" } ] },
-    { "id": "wait-banner", "narration": "Wait for the delayed status banner to appear.", "action": { "type": "wait-for", "locator": { "kind": "text", "text": "Delayed banner is now visible" }, "state": "visible", "timeoutMs": 5000 }, "callout": { "text": "The banner appears after a short delay." }, "screenshot": { "id": "banner-visible" }, "assertions": [ { "type": "element-visible", "locator": { "kind": "test-id", "testId": "status-banner" } } ] }
-  ]
-}
+{
+  "schemaVersion": "1.0.0",
+  "id": "lab-browser-fixture",
+  "title": "Lab browser fixture tutorial",
+  "description": "A generic, lab-owned tutorial that exercises browser actions, locators, assertions and visual declarations against a local static fixture app.",
+  "targetId": "lab-browser-fixture",
+  "browser": { "viewport": { "width": 1024, "height": 768 } },
+  "steps": [
+    { "id": "open-app", "narration": "Open the fixture application in the browser.", "action": { "type": "goto", "path": "/", "waitUntil": "load" }, "highlight": { "kind": "css", "selector": "#page-title" }, "callout": { "text": "This is the fixture application.", "locator": { "kind": "css", "selector": "#page-title" }, "placement": "bottom" }, "screenshot": { "id": "app-open" }, "assertions": [ { "type": "url-path-equals", "expected": "/" }, { "type": "element-visible", "locator": { "kind": "role", "role": "heading", "name": "Tutorial Fixture" } }, { "type": "text-equals", "locator": { "kind": "css", "selector": "#page-title" }, "expected": "Tutorial Fixture" }, { "type": "file-exists", "path": "out/report.json" }, { "type": "json-file-equals", "path": "out/report.json", "pointer": "/counts/widgets", "expected": 3 }, { "type": "http-json-equals", "path": "/api/status", "pointer": "/ok", "expected": true } ] },
+    { "id": "activate", "narration": "Click the primary action button to activate the panel.", "action": { "type": "click", "locator": { "kind": "test-id", "testId": "primary-action" } }, "highlight": { "kind": "test-id", "testId": "primary-action" }, "callout": { "text": "Clicking here activates the panel.", "placement": "auto", "locator": { "kind": "test-id", "testId": "primary-action" } }, "screenshot": { "id": "activated" }, "assertions": [ { "type": "text-equals", "locator": { "kind": "test-id", "testId": "activation-count" }, "expected": "1" }, { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "primary-action" }, "name": "data-state", "expected": "activated" } ] },
+    { "id": "fill-name", "narration": "Type a name into the form field.", "action": { "type": "fill", "locator": { "kind": "test-id", "testId": "name-field" }, "value": "Ada" }, "assertions": [ { "type": "text-contains", "locator": { "kind": "test-id", "testId": "greeting" }, "expected": "Hello, Ada" } ] },
+    { "id": "submit-name", "narration": "Press Enter to submit the name.", "action": { "type": "press", "locator": { "kind": "test-id", "testId": "name-field" }, "key": "Enter" }, "screenshot": { "id": "submitted" }, "assertions": [ { "type": "text-contains", "locator": { "kind": "test-id", "testId": "greeting" }, "expected": "Submitted: Ada" } ] },
+    { "id": "hover-button", "narration": "Hover the secondary button to reveal its state.", "action": { "type": "hover", "locator": { "kind": "test-id", "testId": "hover-target" } }, "assertions": [ { "type": "text-equals", "locator": { "kind": "test-id", "testId": "hover-readout" }, "expected": "hovered" } ] },
+    { "id": "drag-card", "narration": "Drag the card onto the drop target.", "action": { "type": "drag", "source": { "kind": "test-id", "testId": "drag-card" }, "target": { "kind": "test-id", "testId": "drop-zone" } }, "highlight": { "kind": "test-id", "testId": "drop-zone" }, "screenshot": { "id": "dropped" }, "assertions": [ { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "drop-zone" }, "name": "data-dropped", "expected": "true" } ] },
+    { "id": "pointer-click-surface", "narration": "Click a deliberate position inside the pointer gesture surface.", "action": { "type": "pointer-click", "locator": { "kind": "test-id", "testId": "pointer-surface" }, "position": { "x": 0.25, "y": 0.25 }, "coordinateSpace": "fraction" }, "highlight": { "kind": "test-id", "testId": "pointer-surface" }, "screenshot": { "id": "pointer-clicked" }, "assertions": [ { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "pointer-surface" }, "name": "data-pointer-click-count", "expected": "1" }, { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "pointer-surface" }, "name": "data-last-pointer-click-zone", "expected": "upper-left" } ] },
+    { "id": "pointer-drag-surface", "narration": "Drag across two distinct positions inside the same pointer gesture surface.", "action": { "type": "pointer-drag", "locator": { "kind": "test-id", "testId": "pointer-surface" }, "from": { "x": 0.20, "y": 0.25 }, "to": { "x": 0.80, "y": 0.75 }, "coordinateSpace": "fraction" }, "screenshot": { "id": "pointer-dragged" }, "assertions": [ { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "pointer-surface" }, "name": "data-pointer-drag-count", "expected": "1" }, { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "pointer-surface" }, "name": "data-pointer-drag-start-zone", "expected": "upper-left" }, { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "pointer-surface" }, "name": "data-pointer-drag-end-zone", "expected": "lower-right" }, { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "pointer-surface" }, "name": "data-pointer-drag-intermediate", "expected": "true" } ] },
+    { "id": "wait-banner", "narration": "Wait for the delayed status banner to appear.", "action": { "type": "wait-for", "locator": { "kind": "text", "text": "Delayed banner is now visible" }, "state": "visible", "timeoutMs": 5000 }, "callout": { "text": "The banner appears after a short delay." }, "screenshot": { "id": "banner-visible" }, "assertions": [ { "type": "element-visible", "locator": { "kind": "test-id", "testId": "status-banner" } } ] }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dailephd/my-dev-kit-lab",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "type": "module",
   "description": "Evidence, benchmark, and evaluation companion for my-dev-kit.",
   "bin": {