@reqvire-org/ads 0.3.10 → 0.3.11

package/dist/skills/ads-break-ui/references/scenarios.md

@@ -3,6 +3,21 @@
 Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
+All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
+link instead of inferring a section from an ID's directory: an owner-local token
+scenario may live under `components/` or `patterns/`, with `kind: "tokens"`.
+Legacy `?category=` links remain aliases. The `ads_show_tokens` tool retains its
+`category` argument; both preview tools return canonical `?scenario=` links.
+
+After an edit, check the build's `current`/`stale` fields and `sourceRevision`.
+Source evidence is captured before compilation and checked against current project
+inputs; an unchanged artifact or running watcher cannot establish freshness.
+`ADS_PREVIEW_STALE_SOURCE` means the retained output awaits a current build.
+Guarded writes explicitly invalidate the compiler, and content reconciliation
+recovers missed atomic replacements. Do not touch source to force freshness;
+inspect build diagnostics. Upgrade the project's compiler dependency together
+with MCP when an older reporter lacks source evidence.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.

package/dist/skills/ads-designer/references/scenarios.md

@@ -3,6 +3,21 @@
 Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
+All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
+link instead of inferring a section from an ID's directory: an owner-local token
+scenario may live under `components/` or `patterns/`, with `kind: "tokens"`.
+Legacy `?category=` links remain aliases. The `ads_show_tokens` tool retains its
+`category` argument; both preview tools return canonical `?scenario=` links.
+
+After an edit, check the build's `current`/`stale` fields and `sourceRevision`.
+Source evidence is captured before compilation and checked against current project
+inputs; an unchanged artifact or running watcher cannot establish freshness.
+`ADS_PREVIEW_STALE_SOURCE` means the retained output awaits a current build.
+Guarded writes explicitly invalidate the compiler, and content reconciliation
+recovers missed atomic replacements. Do not touch source to force freshness;
+inspect build diagnostics. Upgrade the project's compiler dependency together
+with MCP when an older reporter lacks source evidence.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.

package/dist/skills/ads-import/references/scenarios.md

@@ -3,6 +3,21 @@
 Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
+All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
+link instead of inferring a section from an ID's directory: an owner-local token
+scenario may live under `components/` or `patterns/`, with `kind: "tokens"`.
+Legacy `?category=` links remain aliases. The `ads_show_tokens` tool retains its
+`category` argument; both preview tools return canonical `?scenario=` links.
+
+After an edit, check the build's `current`/`stale` fields and `sourceRevision`.
+Source evidence is captured before compilation and checked against current project
+inputs; an unchanged artifact or running watcher cannot establish freshness.
+`ADS_PREVIEW_STALE_SOURCE` means the retained output awaits a current build.
+Guarded writes explicitly invalidate the compiler, and content reconciliation
+recovers missed atomic replacements. Do not touch source to force freshness;
+inspect build diagnostics. Upgrade the project's compiler dependency together
+with MCP when an older reporter lacks source evidence.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.

package/dist/skills/ads-migrate/references/scenarios.md

@@ -3,6 +3,21 @@
 Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
+All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
+link instead of inferring a section from an ID's directory: an owner-local token
+scenario may live under `components/` or `patterns/`, with `kind: "tokens"`.
+Legacy `?category=` links remain aliases. The `ads_show_tokens` tool retains its
+`category` argument; both preview tools return canonical `?scenario=` links.
+
+After an edit, check the build's `current`/`stale` fields and `sourceRevision`.
+Source evidence is captured before compilation and checked against current project
+inputs; an unchanged artifact or running watcher cannot establish freshness.
+`ADS_PREVIEW_STALE_SOURCE` means the retained output awaits a current build.
+Guarded writes explicitly invalidate the compiler, and content reconciliation
+recovers missed atomic replacements. Do not touch source to force freshness;
+inspect build diagnostics. Upgrade the project's compiler dependency together
+with MCP when an older reporter lacks source evidence.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.

package/dist/skills/ads-motion/references/scenarios.md

@@ -3,6 +3,21 @@
 Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
+All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
+link instead of inferring a section from an ID's directory: an owner-local token
+scenario may live under `components/` or `patterns/`, with `kind: "tokens"`.
+Legacy `?category=` links remain aliases. The `ads_show_tokens` tool retains its
+`category` argument; both preview tools return canonical `?scenario=` links.
+
+After an edit, check the build's `current`/`stale` fields and `sourceRevision`.
+Source evidence is captured before compilation and checked against current project
+inputs; an unchanged artifact or running watcher cannot establish freshness.
+`ADS_PREVIEW_STALE_SOURCE` means the retained output awaits a current build.
+Guarded writes explicitly invalidate the compiler, and content reconciliation
+recovers missed atomic replacements. Do not touch source to force freshness;
+inspect build diagnostics. Upgrade the project's compiler dependency together
+with MCP when an older reporter lacks source evidence.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.

package/dist/verification.mjs

@@ -171,8 +171,8 @@ export function createVerificationController(root) {
             const { startAdsMcp } = await import("./mcp/server.mjs");
             host ??= await startAdsMcp(root, { stdio: false, showcase: true });
             for (const check of group.filter(check => check.scenario)) {
-              const url = new URL(host.url), scenario = context.scenarios.find(entry => entry.id === check.scenario);
-              url.searchParams.set(scenario?.kind === "tokens" ? "category" : "scenario", check.scenario);
+              const url = new URL(host.url);
+              url.searchParams.set("scenario", check.scenario);
               scenarios[check.scenario] = url.href;
             }
           }

package/docs/ARCHITECTURE.md

@@ -288,7 +288,10 @@ Reassembling a second screen from shared primitives still allows design drift.
 The server discovers one path-derived scenario registry. The showcase's four
 sections—Tokens, Components, Patterns and Composition—browse that same registry
 through MCP results. They do not initialize the entry or define
-its UI. The host supplies theme and available space; the public implementation
+its UI. Every preview uses `?scenario=<id>`; discovered `kind` selects its section,
+including token scenarios colocated with component/pattern owners. Existing
+`?category=` links remain compatibility aliases. The host supplies theme and
+available space; the public implementation
 supplies presentation. Several related public parts may share a scenario with
 their required parent. Every declared token and every public renderable component
 and pattern needs addressable coverage. Token references must exist in the real
@@ -304,8 +307,12 @@ The skill-local [scenario guide](../skills/ads-designer/references/scenarios.md)
 explains evidence, limits and diagnostics.
 
 After source changes, validation and compilation must both succeed before a new
-graph becomes current. MCP announces build/resource updates. The built-in client
-refreshes discovery and sends the current selection to the existing App, whose
+graph becomes current. MCP announces build/resource updates.
+Build success records the project input digest captured before compilation;
+status reads independently verify that digest and the output bytes. Guarded
+publication invalidates the compiler explicitly. Content reconciliation recovers
+missed atomic file replacements, so OS watch delivery cannot establish freshness.
+The built-in client refreshes discovery and sends the current selection to the existing App, whose
 loader mounts the new module graph. Failed builds retain the previous view with
 visible stale diagnostics. Invalid scenario metadata at startup and later source
 failures stay in the watcher's recoverable diagnostic path. Fixing source triggers validation again.

package/docs/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.3.11
+
+- Bind preview success to project input content as well as artifact bytes. Source
+  edits immediately mark older output stale, including edits missed by OS watches
+  and changes made during a build; reject reports without source evidence.
+- Recover missed atomic replacements with one-second input reconciliation and
+  explicitly invalidate the live compiler after accepted single/coupled edits.
+  Retain the same process and verify repeated replacements with generic fixtures.
+- Use canonical `?scenario=<id>` links for every preview kind and select the
+  showcase section from discovered metadata. Preserve legacy `?category=` links
+  as aliases, unify MCP preview and browser-check links, and cover all kinds,
+  owner-local tokens, navigation and reloads in a real sandboxed-App regression.
+
 ## 0.3.10
 
 - Attach registered owner-local token sheets to independently compiled token

package/docs/MCP.md

@@ -15,6 +15,14 @@ The agent keeps its stdio connection; the browser connects to `/mcp` on the same
 runtime using HTTP and the current modern protocol. Both share the configured
 preview watcher and artifacts. Stdout remains exclusively JSON-RPC.
 
+Every registered preview uses `?scenario=<discovered-id>`, including token
+previews colocated under components or patterns. The client selects its section
+from the scenario's discovered `kind`, never from the ID's path prefix. Existing
+`?category=<id>` links remain accepted and normalize to `?scenario=`; an explicit
+`scenario` parameter takes precedence when both are present. `ads_show_tokens`
+keeps its `category` tool argument and returns the same canonical showcase link
+as `ads_show_scenario` for that ID.
+
 For browser-only work, run `ads showcase` inside the project. It starts the same
 runtime without stdio. `--port 4185` selects a port; otherwise the OS chooses an
 available one. For a stable address, add `"--port", "4191"` to the server's `args`
@@ -701,7 +709,18 @@ Tool summaries include the first three diagnostics per preview, capped at 1,000
 characters each, with counts and truncation flags; the build resource retains
 the complete bounded report.
 A watcher session separates revisions across restarts, and an artifact digest
-checks that the served output matches the reported successful build.
+checks that the served output matches the reported successful build. Each build
+captures a `sourceRevision` before compilation. Status reads compare that content
+digest with current project inputs; unchanged output cannot remain current after
+source changes. Such previews retain their last successful revision and output,
+but report `current: false`, `stale: true` and `ADS_PREVIEW_STALE_SOURCE` while
+awaiting the current build. Changes during compilation also invalidate success.
+
+Guarded single-owner edits and transactions explicitly invalidate the managed
+compiler after publication. Filesystem events provide fast updates; one-second
+input reconciliation recovers missed atomic replacements without touching source
+or restarting MCP. Keep the project compiler's ADS dependency and the MCP package
+updated together: older reports without source evidence cannot establish freshness.
 
 On each status transition MCP sends `notifications/resources/updated` to build
 resource subscribers. Legacy connections use `resources/subscribe`; modern

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {