From 6adeb770bf9f3465693d3e6372aa7fcaf1a70616 Mon Sep 17 00:00:00 2001
From: jlightner <jlightner@users.noreply.github.com>
Date: Thu, 26 Mar 2026 07:03:02 +0000
Subject: [PATCH] =?UTF-8?q?test:=20Added=20embed=20demo=20page=20with=20st?=
 =?UTF-8?q?yle-isolation=20proof,=206=20setEngineBase=E2=80=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- "examples/embed-demo.html"
- "app/src/api/__tests__/engine.test.ts"
- "vite.embed.config.ts"
- ".gitignore"

GSD-Task: S03/T02
---
 .gitignore                                    |  1 +
 .gsd/event-log.jsonl                          |  1 +
 .gsd/milestones/M003/slices/S03/S03-PLAN.md   |  2 +-
 .../M003/slices/S03/tasks/T01-VERIFY.json     | 42 ++++++++
 .../M003/slices/S03/tasks/T02-SUMMARY.md      | 85 ++++++++++++++++
 .gsd/state-manifest.json                      | 97 ++++++++++++++++---
 app/src/api/__tests__/engine.test.ts          | 74 +++++++++++++-
 examples/embed-demo.html                      | 80 +++++++++++++++
 vite.embed.config.ts                          | 40 ++++++++
 9 files changed, 408 insertions(+), 14 deletions(-)
 create mode 100644 .gsd/milestones/M003/slices/S03/tasks/T01-VERIFY.json
 create mode 100644 .gsd/milestones/M003/slices/S03/tasks/T02-SUMMARY.md
 create mode 100644 examples/embed-demo.html
 create mode 100644 vite.embed.config.ts

diff --git a/.gitignore b/.gitignore
index 295b77e..6c95176 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,6 +14,7 @@ Thumbs.db
 node_modules/
 .next/
 dist/
+dist-embed/
 build/
 __pycache__/
 *.pyc
diff --git a/.gsd/event-log.jsonl b/.gsd/event-log.jsonl
index dafb7fe..2533470 100644
--- a/.gsd/event-log.jsonl
+++ b/.gsd/event-log.jsonl
@@ -42,3 +42,4 @@
 {"cmd":"complete-slice","params":{"milestoneId":"M003","sliceId":"S02"},"ts":"2026-03-26T06:48:34.805Z","actor":"agent","hash":"b305679ef7f0a27b","session_id":"49f8e0fe-34a0-4608-b519-eca93850ed7c"}
 {"cmd":"plan-slice","params":{"milestoneId":"M003","sliceId":"S03"},"ts":"2026-03-26T06:54:15.756Z","actor":"agent","hash":"eaf42bd487467df8","session_id":"49f8e0fe-34a0-4608-b519-eca93850ed7c"}
 {"cmd":"complete-task","params":{"milestoneId":"M003","sliceId":"S03","taskId":"T01"},"ts":"2026-03-26T06:59:26.868Z","actor":"agent","hash":"a47a8fb4b4e7bb97","session_id":"49f8e0fe-34a0-4608-b519-eca93850ed7c"}
+{"cmd":"complete-task","params":{"milestoneId":"M003","sliceId":"S03","taskId":"T02"},"ts":"2026-03-26T07:02:59.395Z","actor":"agent","hash":"3e4362f2d0a5550b","session_id":"49f8e0fe-34a0-4608-b519-eca93850ed7c"}
diff --git a/.gsd/milestones/M003/slices/S03/S03-PLAN.md b/.gsd/milestones/M003/slices/S03/S03-PLAN.md
index 9106011..1675d57 100644
--- a/.gsd/milestones/M003/slices/S03/S03-PLAN.md
+++ b/.gsd/milestones/M003/slices/S03/S03-PLAN.md
@@ -22,7 +22,7 @@ The Vite library config must:
   - Estimate: 1h30m
   - Files: app/src/api/engine.ts, app/src/embed.tsx, app/vite.embed.config.ts, app/tsconfig.node.json
   - Verify: cd app && npx vite build --config vite.embed.config.ts && test -f dist-embed/kerf-embed.js && test -f dist-embed/style.css && echo 'Build OK'
-- [ ] **T02: Add demo page, unit tests for API configurability, and verify full build** — Create the embed demo HTML page and unit tests, then run full verification.
+- [x] **T02: Added embed demo page with style-isolation proof, 6 setEngineBaseUrl unit tests, and root-level vite.embed.config.ts so embed build works from project root** — Create the embed demo HTML page and unit tests, then run full verification.
 
 1. Create `examples/embed-demo.html` — a plain HTML page that loads the embed bundle via `<script>` tag and uses `<kerf-embed engine-url="http://localhost:8000">`. The page must have its own competing styles (Comic Sans font, bright background, custom colors) to demonstrate style isolation works.
 
diff --git a/.gsd/milestones/M003/slices/S03/tasks/T01-VERIFY.json b/.gsd/milestones/M003/slices/S03/tasks/T01-VERIFY.json
new file mode 100644
index 0000000..b7ab23e
--- /dev/null
+++ b/.gsd/milestones/M003/slices/S03/tasks/T01-VERIFY.json
@@ -0,0 +1,42 @@
+{
+  "schemaVersion": 1,
+  "taskId": "T01",
+  "unitId": "M003/S03/T01",
+  "timestamp": 1774508389230,
+  "passed": false,
+  "discoverySource": "task-plan",
+  "checks": [
+    {
+      "command": "cd app",
+      "exitCode": 0,
+      "durationMs": 4,
+      "verdict": "pass"
+    },
+    {
+      "command": "npx vite build --config vite.embed.config.ts",
+      "exitCode": 1,
+      "durationMs": 372,
+      "verdict": "fail"
+    },
+    {
+      "command": "test -f dist-embed/kerf-embed.js",
+      "exitCode": 1,
+      "durationMs": 6,
+      "verdict": "fail"
+    },
+    {
+      "command": "test -f dist-embed/style.css",
+      "exitCode": 1,
+      "durationMs": 4,
+      "verdict": "fail"
+    },
+    {
+      "command": "echo 'Build OK'",
+      "exitCode": 0,
+      "durationMs": 5,
+      "verdict": "pass"
+    }
+  ],
+  "retryAttempt": 1,
+  "maxRetries": 2
+}
diff --git a/.gsd/milestones/M003/slices/S03/tasks/T02-SUMMARY.md b/.gsd/milestones/M003/slices/S03/tasks/T02-SUMMARY.md
new file mode 100644
index 0000000..869cd3b
--- /dev/null
+++ b/.gsd/milestones/M003/slices/S03/tasks/T02-SUMMARY.md
@@ -0,0 +1,85 @@
+---
+id: T02
+parent: S03
+milestone: M003
+provides: []
+requires: []
+affects: []
+key_files: ["examples/embed-demo.html", "app/src/api/__tests__/engine.test.ts", "vite.embed.config.ts", ".gitignore"]
+key_decisions: ["Add root-level vite.embed.config.ts that delegates to app/ sources so embed build runs from project root"]
+patterns_established: []
+drill_down_paths: []
+observability_surfaces: []
+duration: ""
+verification_result: "TypeScript compiles clean (npx tsc -b --noEmit, exit 0). All 126 tests pass (npx vitest run, exit 0). Embed build succeeds from project root (npx vite build --config vite.embed.config.ts, exit 0). Output files dist-embed/kerf-embed.js and dist-embed/style.css exist. Demo page examples/embed-demo.html exists."
+completed_at: 2026-03-26T07:02:59.357Z
+blocker_discovered: false
+---
+
+# T02: Added embed demo page with style-isolation proof, 6 setEngineBaseUrl unit tests, and root-level vite.embed.config.ts so embed build works from project root
+
+> Added embed demo page with style-isolation proof, 6 setEngineBaseUrl unit tests, and root-level vite.embed.config.ts so embed build works from project root
+
+## What Happened
+---
+id: T02
+parent: S03
+milestone: M003
+key_files:
+  - examples/embed-demo.html
+  - app/src/api/__tests__/engine.test.ts
+  - vite.embed.config.ts
+  - .gitignore
+key_decisions:
+  - Add root-level vite.embed.config.ts that delegates to app/ sources so embed build runs from project root
+duration: ""
+verification_result: passed
+completed_at: 2026-03-26T07:02:59.362Z
+blocker_discovered: false
+---
+
+# T02: Added embed demo page with style-isolation proof, 6 setEngineBaseUrl unit tests, and root-level vite.embed.config.ts so embed build works from project root
+
+**Added embed demo page with style-isolation proof, 6 setEngineBaseUrl unit tests, and root-level vite.embed.config.ts so embed build works from project root**
+
+## What Happened
+
+The verification gate failed because `npx vite build --config vite.embed.config.ts` ran from the project root but the config only existed in `app/`. Created a root-level `vite.embed.config.ts` that sets `root: 'app'` and outputs to `dist-embed/` at project root, fixing all three gate failures. Created `examples/embed-demo.html` with competing Comic Sans/magenta/neon styles to prove Shadow DOM isolation. Added 6 unit tests for `setEngineBaseUrl` covering URL propagation to all API functions, trailing slash stripping, and reset behavior — test count went from 120 to 126. Added `dist-embed/` to `.gitignore`.
+
+## Verification
+
+TypeScript compiles clean (npx tsc -b --noEmit, exit 0). All 126 tests pass (npx vitest run, exit 0). Embed build succeeds from project root (npx vite build --config vite.embed.config.ts, exit 0). Output files dist-embed/kerf-embed.js and dist-embed/style.css exist. Demo page examples/embed-demo.html exists.
+
+## Verification Evidence
+
+| # | Command | Exit Code | Verdict | Duration |
+|---|---------|-----------|---------|----------|
+| 1 | `npx tsc -b --noEmit` | 0 | ✅ pass | 7400ms |
+| 2 | `npx vitest run` | 0 | ✅ pass | 2800ms |
+| 3 | `npx vite build --config vite.embed.config.ts` | 0 | ✅ pass | 1500ms |
+| 4 | `test -f dist-embed/kerf-embed.js` | 0 | ✅ pass | 10ms |
+| 5 | `test -f dist-embed/style.css` | 0 | ✅ pass | 10ms |
+| 6 | `test -f examples/embed-demo.html` | 0 | ✅ pass | 10ms |
+
+
+## Deviations
+
+Created root-level vite.embed.config.ts (not in original task plan) to fix verification gate failure where build commands run from project root.
+
+## Known Issues
+
+None.
+
+## Files Created/Modified
+
+- `examples/embed-demo.html`
+- `app/src/api/__tests__/engine.test.ts`
+- `vite.embed.config.ts`
+- `.gitignore`
+
+
+## Deviations
+Created root-level vite.embed.config.ts (not in original task plan) to fix verification gate failure where build commands run from project root.
+
+## Known Issues
+None.
diff --git a/.gsd/state-manifest.json b/.gsd/state-manifest.json
index df31c16..c3b14fd 100644
--- a/.gsd/state-manifest.json
+++ b/.gsd/state-manifest.json
@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "exported_at": "2026-03-26T06:59:26.866Z",
+  "exported_at": "2026-03-26T07:02:59.392Z",
   "milestones": [
     {
       "id": "M001",
@@ -1779,19 +1779,26 @@
       "milestone_id": "M003",
       "slice_id": "S03",
       "id": "T02",
-      "title": "Add demo page, unit tests for API configurability, and verify full build",
-      "status": "pending",
-      "one_liner": "",
-      "narrative": "",
-      "verification_result": "",
+      "title": "Added embed demo page with style-isolation proof, 6 setEngineBaseUrl unit tests, and root-level vite.embed.config.ts so embed build works from project root",
+      "status": "complete",
+      "one_liner": "Added embed demo page with style-isolation proof, 6 setEngineBaseUrl unit tests, and root-level vite.embed.config.ts so embed build works from project root",
+      "narrative": "The verification gate failed because `npx vite build --config vite.embed.config.ts` ran from the project root but the config only existed in `app/`. Created a root-level `vite.embed.config.ts` that sets `root: 'app'` and outputs to `dist-embed/` at project root, fixing all three gate failures. Created `examples/embed-demo.html` with competing Comic Sans/magenta/neon styles to prove Shadow DOM isolation. Added 6 unit tests for `setEngineBaseUrl` covering URL propagation to all API functions, trailing slash stripping, and reset behavior — test count went from 120 to 126. Added `dist-embed/` to `.gitignore`.",
+      "verification_result": "TypeScript compiles clean (npx tsc -b --noEmit, exit 0). All 126 tests pass (npx vitest run, exit 0). Embed build succeeds from project root (npx vite build --config vite.embed.config.ts, exit 0). Output files dist-embed/kerf-embed.js and dist-embed/style.css exist. Demo page examples/embed-demo.html exists.",
       "duration": "",
-      "completed_at": null,
+      "completed_at": "2026-03-26T07:02:59.357Z",
       "blocker_discovered": false,
-      "deviations": "",
-      "known_issues": "",
-      "key_files": [],
-      "key_decisions": [],
-      "full_summary_md": "",
+      "deviations": "Created root-level vite.embed.config.ts (not in original task plan) to fix verification gate failure where build commands run from project root.",
+      "known_issues": "None.",
+      "key_files": [
+        "examples/embed-demo.html",
+        "app/src/api/__tests__/engine.test.ts",
+        "vite.embed.config.ts",
+        ".gitignore"
+      ],
+      "key_decisions": [
+        "Add root-level vite.embed.config.ts that delegates to app/ sources so embed build runs from project root"
+      ],
+      "full_summary_md": "---\nid: T02\nparent: S03\nmilestone: M003\nkey_files:\n  - examples/embed-demo.html\n  - app/src/api/__tests__/engine.test.ts\n  - vite.embed.config.ts\n  - .gitignore\nkey_decisions:\n  - Add root-level vite.embed.config.ts that delegates to app/ sources so embed build runs from project root\nduration: \"\"\nverification_result: passed\ncompleted_at: 2026-03-26T07:02:59.362Z\nblocker_discovered: false\n---\n\n# T02: Added embed demo page with style-isolation proof, 6 setEngineBaseUrl unit tests, and root-level vite.embed.config.ts so embed build works from project root\n\n**Added embed demo page with style-isolation proof, 6 setEngineBaseUrl unit tests, and root-level vite.embed.config.ts so embed build works from project root**\n\n## What Happened\n\nThe verification gate failed because `npx vite build --config vite.embed.config.ts` ran from the project root but the config only existed in `app/`. Created a root-level `vite.embed.config.ts` that sets `root: 'app'` and outputs to `dist-embed/` at project root, fixing all three gate failures. Created `examples/embed-demo.html` with competing Comic Sans/magenta/neon styles to prove Shadow DOM isolation. Added 6 unit tests for `setEngineBaseUrl` covering URL propagation to all API functions, trailing slash stripping, and reset behavior — test count went from 120 to 126. Added `dist-embed/` to `.gitignore`.\n\n## Verification\n\nTypeScript compiles clean (npx tsc -b --noEmit, exit 0). All 126 tests pass (npx vitest run, exit 0). Embed build succeeds from project root (npx vite build --config vite.embed.config.ts, exit 0). Output files dist-embed/kerf-embed.js and dist-embed/style.css exist. Demo page examples/embed-demo.html exists.\n\n## Verification Evidence\n\n| # | Command | Exit Code | Verdict | Duration |\n|---|---------|-----------|---------|----------|\n| 1 | `npx tsc -b --noEmit` | 0 | ✅ pass | 7400ms |\n| 2 | `npx vitest run` | 0 | ✅ pass | 2800ms |\n| 3 | `npx vite build --config vite.embed.config.ts` | 0 | ✅ pass | 1500ms |\n| 4 | `test -f dist-embed/kerf-embed.js` | 0 | ✅ pass | 10ms |\n| 5 | `test -f dist-embed/style.css` | 0 | ✅ pass | 10ms |\n| 6 | `test -f examples/embed-demo.html` | 0 | ✅ pass | 10ms |\n\n\n## Deviations\n\nCreated root-level vite.embed.config.ts (not in original task plan) to fix verification gate failure where build commands run from project root.\n\n## Known Issues\n\nNone.\n\n## Files Created/Modified\n\n- `examples/embed-demo.html`\n- `app/src/api/__tests__/engine.test.ts`\n- `vite.embed.config.ts`\n- `.gitignore`\n",
       "description": "Create the embed demo HTML page and unit tests, then run full verification.\n\n1. Create `examples/embed-demo.html` — a plain HTML page that loads the embed bundle via `<script>` tag and uses `<kerf-embed engine-url=\"http://localhost:8000\">`. The page must have its own competing styles (Comic Sans font, bright background, custom colors) to demonstrate style isolation works.\n\n2. Add/update unit tests for the `setEngineBaseUrl` functionality in `app/src/api/__tests__/engine.test.ts` — verify that after calling `setEngineBaseUrl('http://example.com/api')`, fetch calls use the new base URL, and that it can be reset.\n\n3. Run full verification: `npx vitest run` (all tests pass), `npx tsc -b --noEmit` (TypeScript clean), embed build succeeds.",
       "estimate": "45m",
       "files": [
@@ -2576,6 +2583,72 @@
       "verdict": "✅ pass",
       "duration_ms": 2900,
       "created_at": "2026-03-26T06:59:26.823Z"
+    },
+    {
+      "id": 59,
+      "task_id": "T02",
+      "slice_id": "S03",
+      "milestone_id": "M003",
+      "command": "npx tsc -b --noEmit",
+      "exit_code": 0,
+      "verdict": "✅ pass",
+      "duration_ms": 7400,
+      "created_at": "2026-03-26T07:02:59.357Z"
+    },
+    {
+      "id": 60,
+      "task_id": "T02",
+      "slice_id": "S03",
+      "milestone_id": "M003",
+      "command": "npx vitest run",
+      "exit_code": 0,
+      "verdict": "✅ pass",
+      "duration_ms": 2800,
+      "created_at": "2026-03-26T07:02:59.357Z"
+    },
+    {
+      "id": 61,
+      "task_id": "T02",
+      "slice_id": "S03",
+      "milestone_id": "M003",
+      "command": "npx vite build --config vite.embed.config.ts",
+      "exit_code": 0,
+      "verdict": "✅ pass",
+      "duration_ms": 1500,
+      "created_at": "2026-03-26T07:02:59.357Z"
+    },
+    {
+      "id": 62,
+      "task_id": "T02",
+      "slice_id": "S03",
+      "milestone_id": "M003",
+      "command": "test -f dist-embed/kerf-embed.js",
+      "exit_code": 0,
+      "verdict": "✅ pass",
+      "duration_ms": 10,
+      "created_at": "2026-03-26T07:02:59.357Z"
+    },
+    {
+      "id": 63,
+      "task_id": "T02",
+      "slice_id": "S03",
+      "milestone_id": "M003",
+      "command": "test -f dist-embed/style.css",
+      "exit_code": 0,
+      "verdict": "✅ pass",
+      "duration_ms": 10,
+      "created_at": "2026-03-26T07:02:59.357Z"
+    },
+    {
+      "id": 64,
+      "task_id": "T02",
+      "slice_id": "S03",
+      "milestone_id": "M003",
+      "command": "test -f examples/embed-demo.html",
+      "exit_code": 0,
+      "verdict": "✅ pass",
+      "duration_ms": 10,
+      "created_at": "2026-03-26T07:02:59.357Z"
     }
   ]
 }
\ No newline at end of file
diff --git a/app/src/api/__tests__/engine.test.ts b/app/src/api/__tests__/engine.test.ts
index 4d75f20..136ec75 100644
--- a/app/src/api/__tests__/engine.test.ts
+++ b/app/src/api/__tests__/engine.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { getPresets, traceImage, simplifyVector, exportAsDxf } from '../engine';
+import { getPresets, traceImage, simplifyVector, exportAsDxf, setEngineBaseUrl } from '../engine';
 
 // ---------- helpers ----------
 
@@ -216,3 +216,75 @@ describe('exportAsDxf', () => {
     ).rejects.toThrow(/DXF export.*failed.*500/i);
   });
 });
+
+// ---------- setEngineBaseUrl ----------
+
+describe('setEngineBaseUrl', () => {
+  afterEach(() => {
+    // Reset to default after each test so other suites are unaffected
+    setEngineBaseUrl('/engine');
+  });
+
+  it('changes the base URL used by subsequent API calls', async () => {
+    globalThis.fetch = mockFetchOk({ presets: {} });
+
+    setEngineBaseUrl('http://example.com/api');
+    await getPresets();
+
+    const [url] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(url).toBe('http://example.com/api/presets');
+  });
+
+  it('strips trailing slashes from the provided URL', async () => {
+    globalThis.fetch = mockFetchOk({ presets: {} });
+
+    setEngineBaseUrl('http://example.com/api///');
+    await getPresets();
+
+    const [url] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(url).toBe('http://example.com/api/presets');
+  });
+
+  it('can be reset back to the default /engine path', async () => {
+    globalThis.fetch = mockFetchOk({ presets: {} });
+
+    setEngineBaseUrl('http://remote.host/v2');
+    setEngineBaseUrl('/engine');
+    await getPresets();
+
+    const [url] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(url).toBe('/engine/presets');
+  });
+
+  it('affects traceImage calls', async () => {
+    globalThis.fetch = mockFetchOk({ output: '<svg/>', format: 'svg', metadata: {} });
+
+    setEngineBaseUrl('https://kerf.example.com/engine');
+    const file = new File(['px'], 'img.png', { type: 'image/png' });
+    await traceImage(file, 'sign', {});
+
+    const [url] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(url).toBe('https://kerf.example.com/engine/trace');
+  });
+
+  it('affects simplifyVector calls', async () => {
+    globalThis.fetch = mockFetchOk({ output: '<svg/>', format: 'svg', metadata: {} });
+
+    setEngineBaseUrl('https://kerf.example.com/engine');
+    const file = new File(['<svg></svg>'], 'input.svg', { type: 'image/svg+xml' });
+    await simplifyVector(file, 2.0);
+
+    const [url] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(url).toBe('https://kerf.example.com/engine/simplify');
+  });
+
+  it('affects exportAsDxf calls', async () => {
+    globalThis.fetch = mockFetchBlob('DXF');
+
+    setEngineBaseUrl('https://kerf.example.com/engine');
+    await exportAsDxf('<svg/>', 'inches', 1.0);
+
+    const [url] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(url).toBe('https://kerf.example.com/engine/simplify');
+  });
+});
diff --git a/examples/embed-demo.html b/examples/embed-demo.html
new file mode 100644
index 0000000..e081865
--- /dev/null
+++ b/examples/embed-demo.html
@@ -0,0 +1,80 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Kerf Embed Demo — Style Isolation Test</title>
+
+  <!--
+    Host-page styles intentionally use Comic Sans, a bright background,
+    and aggressive color overrides. If Shadow DOM isolation works correctly,
+    none of these styles should bleed into the <kerf-embed> component.
+  -->
+  <style>
+    * {
+      font-family: "Comic Sans MS", "Comic Sans", cursive !important;
+      color: #ff00ff !important;
+    }
+    body {
+      background: #fffb00;
+      margin: 0;
+      padding: 2rem;
+    }
+    h1, h2, h3, p, span, div, label, button, input, select {
+      font-family: "Comic Sans MS", "Comic Sans", cursive !important;
+      color: #ff00ff !important;
+      border-color: #00ff00 !important;
+    }
+    a {
+      color: #ff0000 !important;
+      text-decoration: underline wavy #00ff00 !important;
+    }
+    button {
+      background: #00ff00 !important;
+      border: 3px solid #ff0000 !important;
+      border-radius: 0 !important;
+      padding: 12px 24px !important;
+      font-size: 18px !important;
+    }
+    input, select, textarea {
+      background: #ff00ff !important;
+      color: #00ff00 !important;
+      border: 3px dashed #ff0000 !important;
+    }
+  </style>
+</head>
+<body>
+
+  <h1>🔧 Kerf Embed Demo</h1>
+  <p>
+    This page uses <strong>Comic Sans</strong>, a bright yellow background,
+    magenta text, and neon green buttons. If you can see the Kerf app below
+    with its <em>own</em> styling (not Comic Sans, not magenta), then
+    <strong>Shadow DOM style isolation is working correctly</strong>.
+  </p>
+
+  <h2>Host-page controls (should look garish):</h2>
+  <button onclick="alert('Host button clicked')">Host Button</button>
+  <input type="text" placeholder="Host input field" />
+
+  <hr style="border: 2px dashed #ff0000; margin: 2rem 0;" />
+
+  <h2>Embedded Kerf Component:</h2>
+
+  <!-- The embed component — should render with its own isolated styles -->
+  <kerf-embed engine-url="http://localhost:8000/engine"></kerf-embed>
+
+  <hr style="border: 2px dashed #ff0000; margin: 2rem 0;" />
+
+  <h2>More host content (should still look garish):</h2>
+  <p>
+    This paragraph proves that host styles persist after the embed.
+    Everything outside <code>&lt;kerf-embed&gt;</code> should use
+    Comic Sans and magenta colors.
+  </p>
+
+  <!-- Load the embed bundle (IIFE for broadest compatibility) -->
+  <script src="../dist-embed/kerf-embed.iife.js"></script>
+
+</body>
+</html>
diff --git a/vite.embed.config.ts b/vite.embed.config.ts
new file mode 100644
index 0000000..109bb19
--- /dev/null
+++ b/vite.embed.config.ts
@@ -0,0 +1,40 @@
+/// <reference types="vite/client" />
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { resolve } from 'path';
+
+/**
+ * Root-level Vite library-mode config for the <kerf-embed> Web Component.
+ *
+ * Mirrors app/vite.embed.config.ts but resolves paths relative to the
+ * monorepo root so `npx vite build --config vite.embed.config.ts` works
+ * from the project root directory.
+ */
+export default defineConfig({
+  root: resolve(__dirname, 'app'),
+  plugins: [react()],
+  build: {
+    outDir: resolve(__dirname, 'dist-embed'),
+    emptyOutDir: true,
+    lib: {
+      entry: resolve(__dirname, 'app/src/embed.tsx'),
+      name: 'KerfEmbed',
+      formats: ['es', 'iife'],
+      fileName: (format) => {
+        if (format === 'es') return 'kerf-embed.js';
+        return 'kerf-embed.iife.js';
+      },
+    },
+    cssCodeSplit: false,
+    rollupOptions: {
+      external: [],
+      output: {
+        codeSplitting: false,
+        assetFileNames: (assetInfo) => {
+          if (assetInfo.names?.[0]?.endsWith('.css')) return 'style.css';
+          return assetInfo.names?.[0] ?? '[name][extname]';
+        },
+      },
+    },
+  },
+});