@scenar/mcp-server 0.2.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Scenar Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,56 @@
+# @scenar/mcp-server
+
+The [Model Context Protocol](https://modelcontextprotocol.io) server for
+[Scenar](https://github.com/stigmer/scenar) — it lets AI editors (Cursor, Claude
+Desktop, etc.) scan a React app, author a scenario tour, narrate it, pack it, and
+serve or publish the embed. A thin, type-safe wrapper over the `@scenar/cli`
+programmatic API.
+
+## Install in Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "scenar": { "command": "npx", "args": ["-y", "@scenar/mcp-server"] }
+  }
+}
+```
+
+Then add the bundled authoring skill so the model knows the scenario model:
+
+```bash
+mkdir -p .cursor/skills
+cp -R node_modules/@scenar/mcp-server/skill .cursor/skills/scenar
+```
+
+Restart your editor.
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `scenar_preview_init` | Scan a React project → `.scenar/` registry + report |
+| `scenar_preview_sync` | Re-scan after code changes (preserves your edits) |
+| `scenar_validate` | Validate a scenario YAML or directory |
+| `scenar_narrate` | Synthesize TTS audio for a scenario |
+| `scenar_pack` | Bundle a scenario into a static embed |
+| `scenar_serve` | Serve a packed bundle locally; returns the URL |
+| `scenar_stop_serve` | Stop a server started by `scenar_serve` |
+| `scenar_publish` | Deploy a packed bundle to GitHub Pages; returns the URL |
+| `scenar_render` | Render a scenario to MP4 |
+
+## Resources
+
+`scenar://registry/views`, `scenar://registry/report`,
+`scenar://registry/providers`, `scenar://scenario/{name}/steps`, and
+`scenar://scenario/{name}/manifest` expose read-only context the model can
+inspect.
+
+See the [Scenar docs](https://github.com/stigmer/scenar/blob/main/docs/mcp-server.md)
+for configuration in other editors.
+
+## License
+
+Apache-2.0

package/bin/scenar-mcp.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=scenar-mcp.d.ts.map

package/bin/scenar-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenar-mcp.d.ts","sourceRoot":"","sources":["../../bin/scenar-mcp.ts"],"names":[],"mappings":""}

package/bin/scenar-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/index.js";
+main().catch((error) => {
+    process.stderr.write(`scenar-mcp: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=scenar-mcp.js.map

package/bin/scenar-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenar-mcp.js","sourceRoot":"","sources":["../../bin/scenar-mcp.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@scenar/mcp-server",
+  "version": "0.2.0",
+  "description": "Model Context Protocol server for Scenar — lets AI editors scan, author, narrate, pack, serve, and publish scenario tours.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stigmer/scenar.git",
+    "directory": "packages/mcp-server"
+  },
+  "keywords": [
+    "scenar",
+    "mcp",
+    "model-context-protocol",
+    "cursor",
+    "ai",
+    "scenario",
+    "tour"
+  ],
+  "bin": {
+    "scenar-mcp": "./bin/scenar-mcp.js"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@scenar/cli": "0.2.0",
+    "@scenar/preview": "0.2.0",
+    "zod": "^3.23.8"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: scenar
+description: >-
+  Author Scenar scenario tours from a React app: scan components with `scenar
+  preview`, write steps.ts + index.tsx (or use the createScenario SDK), add
+  cursor/scroll/type interactions and narration, then pack, serve, and publish
+  the embed. Use when the user wants to build a product tour, demo, or
+  interactive embed with Scenar; mentions the @scenar/* packages; or asks to run
+  scenar preview/validate/narrate/pack/serve/publish (directly or via the
+  @scenar/mcp-server tools scenar_preview_init, scenar_pack, scenar_serve,
+  scenar_publish, etc.).
+---
+
+# Authoring Scenar Scenarios
+
+Scenar turns a React app into a narrated, interactive embed (and an MP4). You,
+the AI, are the authoring engine: you scan the app, write the scenario, and run
+the pipeline. This skill is the source of truth for the model and the workflow.
+
+## The pipeline
+
+```
+scan → wire providers → author → narrate → pack → serve / publish
+```
+
+| Step | CLI | MCP tool |
+|------|-----|----------|
+| Scan a React app into a view registry | `scenar preview init` | `scenar_preview_init` |
+| Re-scan after code changes | `scenar preview sync` | `scenar_preview_sync` |
+| Validate a scenario YAML | `scenar validate` | `scenar_validate` |
+| Generate narration audio (TTS) | `scenar narrate` | `scenar_narrate` |
+| Bundle into a static embed | `scenar pack` | `scenar_pack` |
+| Preview locally | `scenar serve` | `scenar_serve` |
+| Publish to GitHub Pages | `scenar publish` | `scenar_publish` |
+| Render an MP4 | `scenar render` | `scenar_render` |
+
+Prefer the MCP tools when available; they call the same code and return
+structured results. Paths are resolved against the project root.
+
+## Two authoring paths
+
+- **Path A — real components (recommended for real tours).** Run
+  `scenar preview init --source ./src`. It scans the project and writes a
+  `.scenar/` registry (`views.ts`, `views.custom.tsx`, `providers.tsx`,
+  `report.md`) plus an MSW service worker. You then author a scenario that
+  renders the user's *actual* components. The hard part is wiring
+  `.scenar/providers.tsx` (theme/router/data) and MSW handlers so the components
+  render without a live backend — do this deliberately, with the user.
+- **Path B — illustrative components (fastest for generic flows).** Compose the
+  `@scenar/react` shells and page templates (no scan needed). The bundled
+  `welcome-tour` example is Path B; study it before authoring.
+
+Both paths produce the same artifact: a **scenario directory**.
+
+## A scenario directory
+
+```
+my-tour/
+├── steps.ts      # the timeline (data + timing + captions + interactions)
+├── index.tsx     # renderStep(data, stepIndex) → ReactNode
+└── narration/    # generated by `scenar narrate` (do not hand-write)
+```
+
+`pack`, `render`, and `preview` all consume this exact shape.
+
+### steps.ts — the timeline
+
+Export `steps`, an array of `ScenarioStep<T>` where `T` is your per-step data:
+
+```ts
+import type { ScenarioStep } from "@scenar/core";
+
+export interface StepData { url: string; screen: "login" | "dashboard"; }
+
+export const steps: ScenarioStep<StepData>[] = [
+  {
+    delayMs: 0,                       // dwell before reveal; first step is 0
+    caption: "Sign in to Acme Cloud", // short label under the player
+    narration: "Start by signing in to your workspace.", // TTS script (build-time)
+    data: { url: "app.acme.cloud/login", screen: "login" },
+    interactions: [                   // optional timed actions (see below)
+      { atPercent: 0.4, type: "type", target: "email", text: "jordan@acme.cloud" },
+      { atPercent: 0.9, type: "click", target: "submit" },
+    ],
+  },
+  // ...more steps
+];
+```
+
+Fields: `delayMs` (required), `data` (required), `caption?`, `narration?`,
+`interactions?`. Keep one idea per step.
+
+### index.tsx — the render function
+
+Export `renderStep(data, stepIndex): ReactNode`. Switch on the data to render a
+**shell** wrapping the screen content:
+
+```tsx
+import type { ReactNode } from "react";
+import { BrowserView, LoginCardPage } from "@scenar/react";
+import type { StepData } from "./steps";
+
+export function renderStep(data: StepData, stepIndex: number): ReactNode {
+  return (
+    <BrowserView url={`https://${data.url}`} contentKey={String(stepIndex)}>
+      {data.screen === "login" ? <LoginCardPage appName="Acme Cloud" /* ... */ /> : /* ... */}
+    </BrowserView>
+  );
+}
+```
+
+`renderStep` must be **pure** `(data, stepIndex) → ReactNode`. Pass
+`contentKey={String(stepIndex)}` so the shell animates between steps.
+
+## Interactions (cursor, type, scroll, zoom)
+
+Add interactions to a step's `interactions` array. The engine drives a synthetic
+cursor over elements you mark with data attributes in `renderStep`:
+
+- `data-cursor-target="id"` — target for `set_cursor`, `click`, `type`, `hover`, `drag`
+- `data-scroll-target="id"` — target for `scroll_to`
+
+`StepAction` fields: `atPercent` (0.0–1.0 of the step's narration duration; falls
+back to the next step's `delayMs` when muted), `type`, `target`, `dragTarget`
+(drag destination), `text` + `typeDelay` (for `type`), `hoverDuration`,
+`viewportZoom` + `viewportReset` (for `viewport_transition`).
+
+`ActionType`: `set_cursor`, `clear_cursor`, `click`, `type`, `hover`, `drag`,
+`scroll_to`, `viewport_transition`.
+
+```tsx
+// in renderStep:
+<button data-cursor-target="submit">Sign in</button>
+<input data-cursor-target="email" />
+```
+```ts
+// in steps.ts:
+interactions: [
+  { atPercent: 0.2, type: "set_cursor", target: "email" },
+  { atPercent: 0.3, type: "type", target: "email", text: "jordan@acme.cloud" },
+  { atPercent: 0.8, type: "click", target: "submit" },
+]
+```
+
+The engine sets `data-hover` during `hover` and `data-dragging` during `drag` —
+style against these for realistic feedback.
+
+## Narration
+
+Write `narration` as one or two plain sentences per step — concise, one idea
+each, present tense. Then run `scenar narrate ./my-tour` (or `scenar_narrate`) to
+synthesize audio into `narration/`. Interaction timing (`atPercent`) is measured
+against each step's narration duration, so narration and motion stay in sync.
+Do not hand-write the `narration/` folder.
+
+## Shells & page templates (`@scenar/react`)
+
+Pick the shell that frames the medium, then fill it with page primitives or
+templates. Common shells: `BrowserView`, `TerminalView`, `CodeEditorView`,
+`MobileView`, `ChatView`, `SlideView`, `DashboardView`, `APIClientView`,
+`DesktopView`. Common page parts: `LoginCardPage`, `DashboardPage`,
+`SettingsFormPage`, `AdminListPage`, and primitives `AppBar`, `SideNav`,
+`FormCard`, `DataTable`, `StatusBadge`, `PulseHighlight`.
+
+See [reference.md](reference.md) for the full catalog, the `createScenario` SDK
+(type-safe Path B), provider/MSW wiring for Path A, and the bundle constraints.
+
+## The one hard constraint: the bundle allowlist
+
+`scenar pack` only ships: `html`, `js`, `css`, `json`, `mp3`, raster images
+(`png`/`jpg`/`jpeg`/`gif`/`webp`/`avif`), and `woff2`/`woff`. **SVG is not a
+served file** — inline it as a React component or a `data:` URI. Prefer
+CSS-drawn UI; import raster assets normally (Vite hashes them at pack time).
+
+## Workflow checklist
+
+```
+- [ ] Path A: scenar_preview_init, review report.md, wire providers.tsx + MSW
+- [ ] Write steps.ts (timeline, captions, narration, interactions)
+- [ ] Write index.tsx (renderStep with shells + data-cursor-target hooks)
+- [ ] scenar_narrate to synthesize audio
+- [ ] scenar_pack to bundle
+- [ ] scenar_serve to preview, iterate on timing/captions
+- [ ] scenar_publish for a public URL (or scenar_render for an MP4)
+```
+
+Author for quality: realistic copy, sensible pacing (2–3s dwell per step),
+captions that read as a story, and interactions that mirror what a real user
+would do.

package/skill/reference.md

@@ -0,0 +1,153 @@
+# Scenar Authoring Reference
+
+Deep reference for the [scenar skill](SKILL.md): the shell catalog, page parts,
+the `createScenario` SDK (Path B), provider/MSW wiring (Path A), the proto/YAML
+shape, and bundle constraints.
+
+## Canonical example
+
+The bundled example is the best reference — read it before authoring:
+
+- `packages/cli/examples/welcome-tour/steps.ts` — a four-step `ScenarioStep<T>[]`
+- `packages/cli/examples/welcome-tour/index.tsx` — `renderStep` switching on
+  `data.screen`, wrapping `@scenar/react` page templates in a `BrowserView`
+
+## Shell catalog (`@scenar/react`)
+
+Every shell takes `contentKey: string` (pass `String(stepIndex)`) and an
+optional `slideDirection?: "forward" | "backward"`.
+
+| Shell | Frames | Key props |
+|-------|--------|-----------|
+| `BrowserView` | a web app | `url`, `children`, `zoom?` |
+| `TerminalView` | a CLI session | `lines: TerminalLine[]`, `cwd?`, `title?`, `fontSize?` |
+| `CodeEditorView` | an IDE | `files: FileTreeEntry[]`, plus active file/content |
+| `MobileView` | a phone app | mobile chrome + `children` |
+| `ChatView` | a messaging UI | messages; pair with `ChatBubble`, `TypingIndicator` |
+| `SlideView` | a presentation slide | slide content |
+| `DashboardView` | an app with sidebar | `sidebarItems: SidebarItem[]`, `children` |
+| `APIClientView` | a Postman-style client | `method: HttpMethod`, request/response |
+| `DesktopView` | a desktop window | window chrome + `children` |
+
+`TerminalLine` is `{ type: "prompt" | "output" | "error" | "success" | "blank"; text: string }`.
+
+## Page primitives & templates
+
+Use inside a `BrowserView`/`DashboardView` to draw realistic app screens
+(all CSS-drawn; lucide icons inline as components):
+
+- **Templates**: `LoginCardPage`, `DashboardPage`, `SettingsFormPage`, `AdminListPage`
+- **Primitives**: `PageLayout`, `AppBar` (`navLinks: NavLink[]`), `SideNav`
+  (`items: SideNavItem[]`), `FormCard` (`fields: FormField[]`), `DataTable`
+  (`columns`, `rows`), `SettingsForm`, `Breadcrumb`, `StatusBadge`
+  (`variant: "success" | "info" | "warning" | ...`), `PulseHighlight` (draws
+  attention to a region).
+
+`DashboardPage` props (as used by welcome-tour): `appName`, `userName`,
+`navLinks: NavLink[]`, `sidebarItems: SideNavItem[]`, `children`. A `NavLink` is
+`{ label: string; active?: boolean }`; a `SideNavItem` adds `isSection?: boolean`.
+
+## Interactions — full `StepAction` shape
+
+```ts
+interface StepAction {
+  atPercent: number;          // 0.0–1.0 of the step's narration duration
+  type: ActionType;
+  target?: string;            // matches data-cursor-target / data-scroll-target
+  dragTarget?: string;        // drag destination (data-cursor-target)
+  text?: string;              // for "type"
+  typeDelay?: number;         // ms/char (default 50)
+  hoverDuration?: number;     // ms held during "hover" (default 1500)
+  viewportZoom?: number;      // for "viewport_transition" (>1 zooms in; default 1.5)
+  viewportReset?: boolean;    // reset viewport to identity (ignores target/zoom)
+}
+```
+
+`ActionType`: `set_cursor`, `clear_cursor`, `click`, `type`, `hover`, `drag`,
+`scroll_to`, `viewport_transition`.
+
+Targeting attributes (set them in `renderStep` output):
+- `data-cursor-target="id"` — cursor actions (`set_cursor`/`click`/`type`/`hover`/`drag`)
+- `data-scroll-target="id"` — `scroll_to`
+- The engine sets `data-hover` during a hover and `data-dragging` during a drag;
+  style against them for feedback.
+
+Timing rule: with narration, `atPercent` maps onto the clip's real duration; when
+muted, it maps onto the next step's `delayMs`. So author narration first for
+tight sync, or set deliberate `delayMs` values for muted tours.
+
+## Path B — the `createScenario` SDK (type-safe)
+
+For code-authored scenarios, `createScenario` gives compile-time prop checking:
+each step's `props` is typed against the component registered under its `view`.
+
+```ts
+import { createScenario } from "@scenar/sdk";
+import { LoginScreen, Dashboard } from "./screens";
+
+export default createScenario({
+  viewport: { width: 896, height: 480 },
+  views: { login: LoginScreen, dashboard: Dashboard },
+  steps: [
+    { view: "login", delayMs: 0, caption: "Sign in",
+      narrationText: "Sign in to your workspace.",
+      props: { email: "jordan@acme.cloud" } },          // typed to LoginScreen's props
+    { view: "dashboard", delayMs: 2400, caption: "Your dashboard",
+      props: { userName: "Jordan" } },
+  ],
+});
+```
+
+`StepInput` uses `narrationText` (not `narration`) and carries `props` instead of
+a free-form `data`. The output plugs straight into `<ScenarioPlayer>`.
+
+## Path A — real components: provider + MSW wiring
+
+`scenar preview init --source ./src` writes `.scenar/`:
+
+- `views.generated.ts` — scanner-owned; never edit
+- `views.custom.tsx` — your hand-added views
+- `views.ts` — the merged registry you author against
+- `providers.tsx` — **you wire this**: wrap components in the theme/router/data
+  providers they need to render in isolation
+- `report.md` — what was discovered/skipped and why (read this first)
+
+Also generates an MSW service worker. Add MSW handlers so components that fetch
+data render with realistic fixtures (no live backend). This wiring is the one
+step that can't be automated — do it explicitly with the user, using `report.md`
+to see what each component expects. Re-run `scenar preview sync` after code
+changes (it preserves `views.custom.tsx` and `providers.tsx`).
+
+## YAML / proto scenarios
+
+`scenar validate` checks a scenario **YAML** against the proto schema
+(`ai.scenar.scenario.v1`). `ActionType` values match the proto enum names
+verbatim, so YAML interactions use the same `scroll_to`/`set_cursor`/... strings.
+Most authoring is TS-first (directory form); YAML is for proto-driven pipelines.
+
+## Bundle constraints (`scenar pack`)
+
+The packed bundle must satisfy the deploy allowlist (enforced at pack time):
+
+- Allowed file types: `html`, `js`, `css`, `json`, `mp3`, raster images
+  (`png`/`jpg`/`jpeg`/`gif`/`webp`/`avif`), `woff2`/`woff`.
+- **No SVG files** — SVG is active content. Inline SVG as a React component or a
+  `data:` URI instead. (lucide-react icons are already inline components.)
+- Prefer CSS-drawn UI. Import raster assets with a normal `import logo from
+  "./logo.png"` — Vite emits a hashed file at pack time.
+- Relative asset URLs only (the bundle is served from an origin/subpath root):
+  pack sets Vite `base: "./"` for you.
+- `scenar pack` writes `scenario.json` (records the canonical viewport for the
+  embed aspect ratio) and `pack-manifest.json` (every file + sha256 + content
+  type). Don't hand-edit these.
+
+## Hosting the embed
+
+- `scenar serve <bundle>` → `http://localhost:4173/` (ephemeral local preview).
+- `scenar publish <bundle>` → `https://<owner>.github.io/scenar-embeds/<slug>/`
+  (GitHub Pages; needs the `gh` CLI authenticated). Public and permanent. Many
+  tours share one repo (`--repo`, default `scenar-embeds`), each under its slug
+  (`--path`, default the scenario slug; `--path /` for the repo root); publishing
+  one tour preserves its siblings.
+- Both print a responsive `<iframe>` snippet pinned to the bundle's aspect ratio.
+- `scenar render <dir>` → an MP4 (same source, via Remotion).