Web SDK Phase 8.1: @skilly/web embed widget (skeleton)

AGENTS.md

@@ -211,7 +211,20 @@ Browser sibling of `core/mobile-sdk`: the shared core (`policy`, `realtime`, `sk
 | `scripts/build-web-sdk.sh` | `wasm-pack build` → `sdk/web/generated/`. |
 | `sdk/web/` | Browser SDK artifacts (sibling of `sdk/ios`, `sdk/android`). |
 
-> The `wasm-bindgen`/`serde-wasm-bindgen` deps are `wasm32`-only, so `cargo test --workspace` stays green on macOS with no wasm toolchain. Host-validated: `cargo test -p skilly-core-web-sdk` (4 tests, incl. `compose_prompt` parity vs the shared `core/skills` fixture). The actual wasm compile runs via `wasm-pack`/CI. The `@skilly/web` widget (Shadow-DOM overlay, DOM digest, selector pointing, voice) is Phase 8.1+.
+> The `wasm-bindgen`/`serde-wasm-bindgen` deps are `wasm32`-only, so `cargo test --workspace` stays green on macOS with no wasm toolchain. Host-validated: `cargo test -p skilly-core-web-sdk` (4 tests, incl. `compose_prompt` parity vs the shared `core/skills` fixture). The actual wasm compile runs via `wasm-pack`/CI.
+
+### `@skilly/web` embed widget (`sdk/web`) — Web SDK Phase 8.1
+
+The embeddable companion: a **vanilla-TS + Shadow-DOM** widget (no framework — embeds must be tiny + style-isolated) that site owners drop into their web app via one `<script>`. Builds to a ~7KB IIFE (`window.Skilly`) + an ESM build via `tsup`.
+
+| File | Purpose |
+|------|---------|
+| `sdk/web/src/index.ts` | Public `Skilly` API (`init`/`start`/`on`/`identify`/`destroy`) + auto-init from `data-skilly-*` script attrs + typed event emitter. |
+| `sdk/web/src/widget.ts` | Shadow-DOM UI: launcher button, response bubble, blue cursor element + `moveCursorTo`. |
+| `sdk/web/src/core.ts` | Lazy, tolerant loader for the `core/web-sdk` WASM (widget runs UI-only if absent). |
+| `sdk/web/demo/index.html` | Demo host page (`bun run demo`). |
+
+> 8.1 is the embed SKELETON with a simulated turn lifecycle (listening→thinking→speaking→complete). Validated: `bun run typecheck` + `bun run build` clean; Playwright confirms the widget mounts, the launcher renders, and `start()` shows the bubble + cursor. Next: **8.2** DOM digest + selector pointing · **8.3** OpenAI Realtime voice · **8.4+** multi-tenant Next.js backend. `dist/`, `node_modules/`, `generated/` are gitignored.
 
 ### Skill Files
 

sdk/web/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

sdk/web/README.md

@@ -1,22 +1,61 @@
-# Skilly Web SDK (`sdk/web`)
+# @skilly/web
 
-Browser SDK artifacts — sibling of `sdk/ios` and `sdk/android`. The WASM + JS
-bindings generated from `core/web-sdk` land in `sdk/web/generated/` (built by
-`scripts/build-web-sdk.sh` via `wasm-pack`, mirroring how `sdk/{ios,android}`
-are generated by the mobile-sdk bindgen script).
+Embeddable Skilly companion for websites — guided onboarding + live support that
+sees the page, points at UI elements, and talks the user through it. Site owners
+install it on their own web app; their visitors get the companion. See
+`docs/architecture/web-sdk-prd.md`.
 
-This is **Phase 8.0** (WASM core) of the Web SDK plan — the shared Rust core
-compiled for the browser. The end-user widget package (`@skilly/web`: Shadow-DOM
-overlay, DOM digest, selector pointing, voice pipeline) is **Phase 8.1+** and is
-not part of this slice. See `docs/architecture/web-sdk-prd.md`.
+This package consumes the shared Rust core compiled to WASM (`core/web-sdk`,
+output in `sdk/web/generated/`).
 
-## Layout (target)
+## Status — Phase 8.1 (embed skeleton)
 
+What's here:
+- `@skilly/web` package: Shadow-DOM widget (launcher, response bubble, blue
+  cursor), the public `Skilly` API, and the lazy WASM-core loader.
+- A simulated turn lifecycle (listening → thinking → speaking → complete) so the
+  embed is demonstrable end-to-end.
+
+Layered on next: **8.2** DOM digest + selector-based pointing · **8.3** OpenAI
+Realtime voice pipeline · **8.4+** multi-tenant Next.js backend (keys, metering,
+SKILL.md serving).
+
+## Install / embed
+
+Script tag (auto-inits from `data-skilly-*`):
+
+```html
+<script src="https://cdn.tryskilly.app/web/v1.js"
+        data-skilly-key="pk_live_..." data-skilly-skill="acme-onboarding" defer></script>
 ```
-sdk/web/
-├── generated/        # wasm-pack output (skilly_core_web_sdk.js + .wasm + .d.ts)
-└── sample/           # (8.1+) minimal browser usage example
+
+npm:
+
+```ts
+import { init, start, on } from "@skilly/web";
+init({ key: "pk_live_...", skill: "acme-onboarding" });
+on("complete", () => console.log("turn done"));
+```
+
+## Public API
+
+| Call | Purpose |
+|------|---------|
+| `init(config)` | Mount the widget. `config`: `key` (required), `skill`, `accentColor`, `locale`, `coreUrl`, `backendUrl`. |
+| `start(goal?)` | Open the companion and run a turn. |
+| `on(event, cb)` | Subscribe to `turn` / `point` / `complete` / `error`. Returns an unsubscribe fn. |
+| `identify(id, traits?)` | Associate the end-user (analytics — wired in 8.4+). |
+| `destroy()` | Tear down the widget. |
+
+## Develop
+
+```bash
+cd sdk/web
+bun install         # or npm install
+bun run typecheck   # tsc --noEmit
+bun run build       # tsup → dist/ (ESM + IIFE + .d.ts)
+bun run demo        # build + serve demo/ at http://localhost:4321
 ```
 
-`generated/` is machine-produced — regenerate via `scripts/build-web-sdk.sh`,
-never hand-edit.
+`dist/` and `node_modules/` are gitignored; `generated/` holds the wasm core
+(built by `scripts/build-web-sdk.sh`).