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

package/examples/tutorial-browser/index.html

@@ -0,0 +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; }
+      #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/prepare.mjs

@@ -0,0 +1,14 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const sourceRoot = path.dirname(fileURLToPath(import.meta.url));
+const targetRoot = process.argv[2];
+if (!targetRoot) {
+  console.error("prepare requires a target root argument");
+  process.exit(2);
+}
+fs.mkdirSync(path.join(targetRoot, "app"), { recursive: true });
+fs.mkdirSync(path.join(targetRoot, "out"), { recursive: true });
+for (const file of ["index.html", "server.mjs"]) fs.copyFileSync(path.join(sourceRoot, file), path.join(targetRoot, "app", file));
+fs.writeFileSync(path.join(targetRoot, "out", "report.json"), JSON.stringify({ prepared: true, counts: { widgets: 3 } }, null, 2), "utf8");

package/examples/tutorial-browser/scenario.json

@@ -0,0 +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": "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/examples/tutorial-browser/server.mjs

@@ -0,0 +1,14 @@
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const port = Number(process.env.TUTORIAL_FIXTURE_PORT || 0);
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  if (url.pathname === "/api/status") { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, widgets: 3 })); return; }
+  const filePath = url.pathname === "/" ? path.join(root, "index.html") : path.join(root, url.pathname);
+  fs.readFile(filePath, (error, contents) => { if (error) { res.writeHead(404); res.end("not found"); return; } res.writeHead(200, { "content-type": filePath.endsWith(".html") ? "text/html" : "application/octet-stream" }); res.end(contents); });
+});
+server.listen(port, "127.0.0.1", () => console.log("tutorial fixture listening on " + server.address().port));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dailephd/my-dev-kit-lab",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "type": "module",
   "description": "Evidence, benchmark, and evaluation companion for my-dev-kit.",
   "bin": {
@@ -13,7 +13,8 @@
     "dist/src/",
     "benchmarks/",
     "docs/METRICS.md",
-    "examples/token-savings-cases.json"
+    "examples/token-savings-cases.json",
+    "examples/tutorial-browser/"
   ],
   "repository": {
     "type": "git",
@@ -79,17 +80,20 @@
     "security:codeql": "tsx scripts/security/runCodeql.ts",
     "security:semgrep": "tsx scripts/security/runSemgrep.ts",
     "test:security": "vitest run tests/security/",
+    "test:tutorial-browser": "vitest run tests/integration/tutorialRealBrowser.spec.ts",
     "test:fuzz:smoke": "tsx scripts/security/runFuzzSmoke.ts",
     "security:validate": "tsx scripts/security/validate.ts",
     "audit": "tsx scripts/audits/runAudit.ts",
     "report:context-integrity-smoke": "tsx scripts/report-context-integrity-smoke.ts"
   },
+  "dependencies": {
+    "playwright": "1.60.0"
+  },
   "devDependencies": {
     "@types/node": "^24.0.0",
-    "playwright": "^1.54.1",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "overrides": {
     "vite": "7.3.6"