From 52b0c726a587b123fbddda821c4094c4b1237405 Mon Sep 17 00:00:00 2001 From: Mohamed Mansour Date: Tue, 8 Sep 2026 17:14:55 -0700 Subject: [PATCH 1/2] feat: bundle versioned AI guidance with WebUI Ship the canonical AI reference in the npm package and replace the installed snapshot with a minimal loader. Refresh the reference during build and packing, document one-time migration, and remove FAST-specific guidance from the AI reference. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 45307125-be11-46be-b3fe-b77df2bd3bcf --- .claude-plugin/plugin.json | 2 +- .github/skills/code-review/SKILL.md | 2 +- .github/skills/diagnostics/SKILL.md | 2 +- .github/skills/docs-sync/SKILL.md | 20 +++-- .github/skills/webui-dev/SKILL.md | 2 +- DESIGN.md | 18 ++++ ai/SKILL.md | 10 +++ crates/webui-press/README.md | 12 +-- docs/.webui-press/config.json | 3 +- docs/{ai/SKILL.md => ai.md} | 34 ++------ docs/guide/installation.md | 32 ++++++- packages/webui/.gitignore | 1 + packages/webui/README.md | 15 ++++ packages/webui/package.json | 7 +- packages/webui/scripts/prepare-ai.js | 9 ++ packages/webui/test/ai-reference.test.ts | 103 +++++++++++++++++++++++ 16 files changed, 220 insertions(+), 52 deletions(-) create mode 100644 ai/SKILL.md rename docs/{ai/SKILL.md => ai.md} (96%) create mode 100644 packages/webui/scripts/prepare-ai.js create mode 100644 packages/webui/test/ai-reference.test.ts diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 80d83a0de..b04c3a1d8 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,5 +1,5 @@ { "name": "webui", "description": "WebUI framework agent skills.", - "skills": ["./docs/ai"] + "skills": ["./ai"] } diff --git a/.github/skills/code-review/SKILL.md b/.github/skills/code-review/SKILL.md index 6c789cb6c..b28a483e5 100644 --- a/.github/skills/code-review/SKILL.md +++ b/.github/skills/code-review/SKILL.md @@ -312,7 +312,7 @@ Every behavioral change must include corresponding documentation updates. Missin |-------|-----| | **DESIGN.md updated** | If the change modifies public APIs, protocol fields, behavioral contracts, error variants, or SSR markers, `DESIGN.md` must be updated in the same commit. | | **User-facing docs updated** | If the change affects CLI flags, template syntax, component authoring, routing, or integration behavior, `docs/` must be updated. | -| **AI reference updated** | If the change affects anything a code-generation AI would need to know, `docs/ai/SKILL.md` must be updated. | +| **AI reference updated** | If the change affects anything a code-generation AI would need to know, `docs/ai.md` must be updated. | | **README links to docs portal** | Package READMEs should defer to the docs portal, not duplicate content. | | **No stale examples** | Code examples in docs must use current API signatures, flag names, and marker formats. | | **docs build passes** | `cd docs && pnpm build` must succeed (catches broken links, unescaped `{{`, missing pages). | diff --git a/.github/skills/diagnostics/SKILL.md b/.github/skills/diagnostics/SKILL.md index 3a80b46a6..047382df5 100644 --- a/.github/skills/diagnostics/SKILL.md +++ b/.github/skills/diagnostics/SKILL.md @@ -144,5 +144,5 @@ with **no** added hot-path work). (confirm with a benchmark if it sits near a hot loop). - [ ] Tests: a regression test that fails without the error, asserting on the `code` (not the prose); JSON stays plain (no `\x1b`). -- [ ] `DESIGN.md` and `docs/` (incl. `docs/ai/SKILL.md`) updated if the contract or +- [ ] `DESIGN.md` and `docs/` (incl. `docs/ai.md`) updated if the contract or a user-visible code/flag changed. diff --git a/.github/skills/docs-sync/SKILL.md b/.github/skills/docs-sync/SKILL.md index 5ee76b598..c5f00a3ad 100644 --- a/.github/skills/docs-sync/SKILL.md +++ b/.github/skills/docs-sync/SKILL.md @@ -11,11 +11,11 @@ Use this skill whenever a change touches user-visible behavior, APIs, or contrac | What changed | Update | |-------------|--------| -| CLI flags or commands | `docs/guide/cli/index.md` + `docs/ai/SKILL.md` (Build and run section) | -| Template syntax or directives | `docs/guide/concepts/directives/` + `docs/ai/SKILL.md` | -| Component authoring model | `docs/guide/concepts/interactivity.md` + `docs/ai/SKILL.md` | +| CLI flags or commands | `docs/guide/cli/index.md` + `docs/ai.md` (Build and run section) | +| Template syntax or directives | `docs/guide/concepts/directives/` + `docs/ai.md` | +| Component authoring model | `docs/guide/concepts/interactivity.md` + `docs/ai.md` | | Hydration markers or mechanism | `docs/guide/concepts/hydration.md` + `DESIGN.md` (WebUI Framework Plugin) | -| Routing behavior | `docs/guide/concepts/routing.md` + `docs/ai/SKILL.md` | +| Routing behavior | `docs/guide/concepts/routing.md` + `docs/ai.md` | | State management or path resolution | `docs/guide/concepts/state-management/index.md` | | Handler API (Rust, Node, FFI) | `docs/guide/concepts/handlers/` + `docs/guide/integrations.md` | | Protocol fields or fragment types | `DESIGN.md` (Protocol Specification) | @@ -23,7 +23,7 @@ Use this skill whenever a change touches user-visible behavior, APIs, or contrac | Performance characteristics | `docs/guide/concepts/performance.md` | | Public API (Rust crate, npm package) | `DESIGN.md` + relevant handler/integration docs | | Error variants or error messages | `DESIGN.md` | -| `@microsoft/webui-framework` decorators or API | `docs/guide/concepts/interactivity.md` + `docs/ai/SKILL.md` + `packages/webui-framework/README.md` | +| `@microsoft/webui-framework` decorators or API | `docs/guide/concepts/interactivity.md` + `docs/ai.md` + `packages/webui-framework/README.md` | | `@microsoft/webui-router` behavior | `docs/guide/concepts/routing.md` + `packages/webui-router/README.md` | ## DESIGN.md rules @@ -51,7 +51,7 @@ Update `docs/` in the same commit when the change is user-visible: ### Public API boundary Developer documentation (`docs/`, crate/package READMEs, and -`docs/ai/SKILL.md`) documents only supported public APIs and externally +`docs/ai.md`) documents only supported public APIs and externally observable contracts. Every addition must map to at least one public entry point: @@ -77,9 +77,13 @@ Every addition must help developers author, configure, debug, or integrate a WebUI application. Do not add release-note-style implementation observations to reference docs. -Keep protocol internals out of general user docs. The `docs/ai/SKILL.md` file is the single-page AI reference and should be kept in sync with all other docs. +Keep protocol internals out of general user docs. The `docs/ai.md` file is the single-page AI reference and should be kept in sync with all other docs. -`docs/ai/SKILL.md` is authoring-first by design. Keep deep reference material (full CLI flag tables, error-code lists, per-language integration snippets) in its canonical page and link to it from `docs/ai/SKILL.md` rather than duplicating it there. +`docs/ai.md` is authoring-first by design. Keep deep reference material (full CLI flag tables, error-code lists, per-language integration snippets) in its canonical page and link to it from `docs/ai.md` rather than duplicating it there. + +`ai/SKILL.md` is only the stable loader. Update `docs/ai.md` for authoring changes, +not the loader or the generated `packages/webui/ai.md`. Package build and prepack +steps refresh the generated reference. ## Validation diff --git a/.github/skills/webui-dev/SKILL.md b/.github/skills/webui-dev/SKILL.md index c03d61a1f..166cc4abb 100644 --- a/.github/skills/webui-dev/SKILL.md +++ b/.github/skills/webui-dev/SKILL.md @@ -57,6 +57,6 @@ webui serve ./src --state ./data/state.json --plugin=webui --watch The complete guide covering all template syntax, styling and animation rules, anti-patterns, routing, and a pre-flight checklist: -**[docs/ai/SKILL.md](/docs/ai/SKILL.md)** +**[docs/ai.md](/docs/ai.md)** Read that file before generating any WebUI code. diff --git a/DESIGN.md b/DESIGN.md index bc992feae..d49bd420a 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -5419,6 +5419,24 @@ The `@microsoft/webui` npm package follows the esbuild single-package model: `done`, and an optional camel-case descriptor - render currently requires the native addon; no WASM render fallback is wired +#### Versioned AI reference + +`docs/ai.md` is the canonical application-authoring reference and is served at +`/ai` on the documentation site. The npm build and prepack steps copy it verbatim +to `packages/webui/ai.md`; this generated copy is ignored by Git and included in +the package's `files` allowlist. The `@microsoft/webui/ai.md` export allows +application-relative package resolution without importing the native runtime. +Packaging fails if the canonical reference is unavailable. + +`ai/SKILL.md`, discovered through `.claude-plugin/plugin.json`, is a stable loader +installed once rather than a snapshot of the reference. It instructs agents to +read `node_modules/@microsoft/webui/ai.md` from the application's installed +dependencies and reread after upgrades, without prescribing loading commands. Missing +dependencies and older releases without `ai.md` are reported explicitly, never +silently replaced with latest-version guidance. Framework contributors read +`docs/ai.md` directly. The loader and package reference do not require runtime +network requests or install-time changes to consumers' agent configuration. + ### .NET / NuGet Distribution The `Microsoft.WebUI` package is the managed .NET binding for `webui-ffi`. It targets `net8.0` and `net9.0`, packs `dotnet/src/Microsoft.WebUI/README.md`, and publishes XML documentation generated from public API comments. diff --git a/ai/SKILL.md b/ai/SKILL.md new file mode 100644 index 000000000..b4a49cf3c --- /dev/null +++ b/ai/SKILL.md @@ -0,0 +1,10 @@ +--- +name: webui-reference +description: Use when writing or reviewing WebUI code. Load the reference for the application's installed WebUI version. +--- + +Read and follow `node_modules/@microsoft/webui/ai.md` from the application's +installed dependencies before writing or reviewing WebUI code. + +Reread it after upgrades. If unavailable, report the missing reference instead +of using cached or latest-version guidance. diff --git a/crates/webui-press/README.md b/crates/webui-press/README.md index ca0738b23..b68710a23 100644 --- a/crates/webui-press/README.md +++ b/crates/webui-press/README.md @@ -218,7 +218,7 @@ Shadow DOM components can react to the layout via `:host-context([data-layout="f "nav": [ { "text": "Guide", "link": "/guide/" }, { "text": "Tutorials", "link": "/tutorials/" }, - { "text": "AI", "link": "/ai", "source": "ai/SKILL.md" }, + { "text": "AI", "link": "/ai" }, { "text": "GitHub", "link": "https://github.com/me/proj" } ], @@ -299,13 +299,13 @@ the URL, point a `nav` entry at the file with `source` (a path relative to `contentDir`, using forward slashes): ```json -{ "text": "AI", "link": "/ai", "source": "ai/SKILL.md" } +{ "text": "Reference", "link": "/reference", "source": "reference/README.md" } ``` -That serves `ai/SKILL.md` at `/ai` instead of `/ai/SKILL`. This is what keeps a -page installable as an agent skill — the [agent-skill -spec](https://agentskills.io) requires the file be named `SKILL.md` — while -keeping its published docs URL stable. +That serves `reference/README.md` at `/reference` instead of +`/reference/README`, preserving the source filename while keeping the published +docs URL stable. Ordinary pages such as `ai.md` already map to `/ai` and do not +need a `source` override. ### Shared state diff --git a/docs/.webui-press/config.json b/docs/.webui-press/config.json index b0ee62c9b..2745bf5a8 100644 --- a/docs/.webui-press/config.json +++ b/docs/.webui-press/config.json @@ -48,8 +48,7 @@ }, { "text": "AI", - "link": "/ai", - "source": "ai/SKILL.md" + "link": "/ai" }, { "text": "GitHub", diff --git a/docs/ai/SKILL.md b/docs/ai.md similarity index 96% rename from docs/ai/SKILL.md rename to docs/ai.md index da9836d5e..7a3b904e5 100644 --- a/docs/ai/SKILL.md +++ b/docs/ai.md @@ -1,6 +1,5 @@ --- layout: page -name: webui-reference description: Authoritative WebUI framework reference for generating correct application code - template-first authoring rules, template syntax, styling, interactivity, routing, state JSON, and anti-patterns. --- @@ -10,9 +9,15 @@ description: Authoritative WebUI framework reference for generating correct appl > generate correct WebUI code. Read the Rules first - they are the constraints > that most often get violated. Deep-dive links are indexed at the bottom. > -> Install this reference into your agent with +> Install the loader skill **once** with > `npx skills add microsoft/webui --skill webui-reference` - see > [AI Coding Agents](/guide/installation#ai-coding-agents). +> It reads `node_modules/@microsoft/webui/ai.md`, so upgrading `@microsoft/webui` +> updates the reference without reinstalling the skill. +> +> Links starting with `/guide/` or `/tutorials/` refer to the +> [documentation site](https://microsoft.github.io/webui/), which tracks the +> current release rather than your installed version. ## Rules @@ -763,8 +768,6 @@ navigation adopts the response without refetching or parsing templates early. Non-router apps use `installInteractionHydration({ load })`. This policy trades first-interaction latency for lower startup JS/heap and cannot preserve transient user activation or closed-shadow click targets. -The router remains framework-agnostic: FAST or any other runtime starts through -`onIntent` and passes the same prepared handle after its own hydration is ready. | Decorator | Purpose | SSR? | Triggers DOM update? | |---|---|---|---| @@ -1018,9 +1021,6 @@ the router for routed components. Document is applied before ``. ShadowRoot-targeted Link CSS is preloaded from the head and applied inside its owning root. Static request-reachable Shadow roots are preloaded the same way. -- FAST 2/3 plugins require effective Shadow components. Any effective Light - component fails with `fast-light-dom-unsupported`; use the WebUI plugin for - global Light DOM. | Attribute | Example | Description | |---|---|---| @@ -1343,26 +1343,6 @@ resolve before component discovery and compilation; do not manually register their components elsewhere. See [WebUI Press named regions](/guide/webui-press) for the stable built-in region list and full configuration contract. -**FAST authored templates.** The `fast-v2` and `fast-v3` plugins are pinned to -FAST major versions 2 and 3, respectively; `fast` is a deprecated alias for -`fast-v2`. With either versioned plugin, a component file authored as one -`` wrapping one direct inner `