@reqvire-org/ads 0.3.9 → 0.3.11

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

@@ -1,8 +1,38 @@
-# Scenario render evidence and public class helpers
+# Scenario rendering, token previews and public class helpers
 
 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.
+A colocated `kind: "tokens"` scenario may render only the public review pattern
+with its fixture samples. Discovery adds the registered owner sheet to the
+generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
+into the token preview independently of the runtime component. Custom builders
+that replace this plugin must preserve these explicit stylesheet dependencies.
+Do not render the runtime owner merely to retain its CSS or add unrelated sheets.
+
+Open the exact token scenario in a fresh App and verify resolved values and sample
+effects in both themes. A successful ordinary component preview does not prove
+the independently bundled token preview loads the same definitions. Shared
+foundation styling still follows the project's mount/build integration.
+
 ## Public children can share their parent's scenario
 
 Declare the public parts actually demonstrated in `covers`, even when their

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

@@ -1,8 +1,38 @@
-# Scenario render evidence and public class helpers
+# Scenario rendering, token previews and public class helpers
 
 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.
+A colocated `kind: "tokens"` scenario may render only the public review pattern
+with its fixture samples. Discovery adds the registered owner sheet to the
+generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
+into the token preview independently of the runtime component. Custom builders
+that replace this plugin must preserve these explicit stylesheet dependencies.
+Do not render the runtime owner merely to retain its CSS or add unrelated sheets.
+
+Open the exact token scenario in a fresh App and verify resolved values and sample
+effects in both themes. A successful ordinary component preview does not prove
+the independently bundled token preview loads the same definitions. Shared
+foundation styling still follows the project's mount/build integration.
+
 ## Public children can share their parent's scenario
 
 Declare the public parts actually demonstrated in `covers`, even when their

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

@@ -1,8 +1,38 @@
-# Scenario render evidence and public class helpers
+# Scenario rendering, token previews and public class helpers
 
 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.
+A colocated `kind: "tokens"` scenario may render only the public review pattern
+with its fixture samples. Discovery adds the registered owner sheet to the
+generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
+into the token preview independently of the runtime component. Custom builders
+that replace this plugin must preserve these explicit stylesheet dependencies.
+Do not render the runtime owner merely to retain its CSS or add unrelated sheets.
+
+Open the exact token scenario in a fresh App and verify resolved values and sample
+effects in both themes. A successful ordinary component preview does not prove
+the independently bundled token preview loads the same definitions. Shared
+foundation styling still follows the project's mount/build integration.
+
 ## Public children can share their parent's scenario
 
 Declare the public parts actually demonstrated in `covers`, even when their

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

@@ -1,8 +1,38 @@
-# Scenario render evidence and public class helpers
+# Scenario rendering, token previews and public class helpers
 
 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.
+A colocated `kind: "tokens"` scenario may render only the public review pattern
+with its fixture samples. Discovery adds the registered owner sheet to the
+generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
+into the token preview independently of the runtime component. Custom builders
+that replace this plugin must preserve these explicit stylesheet dependencies.
+Do not render the runtime owner merely to retain its CSS or add unrelated sheets.
+
+Open the exact token scenario in a fresh App and verify resolved values and sample
+effects in both themes. A successful ordinary component preview does not prove
+the independently bundled token preview loads the same definitions. Shared
+foundation styling still follows the project's mount/build integration.
+
 ## Public children can share their parent's scenario
 
 Declare the public parts actually demonstrated in `covers`, even when their

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

@@ -1,8 +1,38 @@
-# Scenario render evidence and public class helpers
+# Scenario rendering, token previews and public class helpers
 
 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.
+A colocated `kind: "tokens"` scenario may render only the public review pattern
+with its fixture samples. Discovery adds the registered owner sheet to the
+generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
+into the token preview independently of the runtime component. Custom builders
+that replace this plugin must preserve these explicit stylesheet dependencies.
+Do not render the runtime owner merely to retain its CSS or add unrelated sheets.
+
+Open the exact token scenario in a fresh App and verify resolved values and sample
+effects in both themes. A successful ordinary component preview does not prove
+the independently bundled token preview loads the same definitions. Shared
+foundation styling still follows the project's mount/build integration.
+
 ## Public children can share their parent's scenario
 
 Declare the public parts actually demonstrated in `covers`, even when their

package/dist/verification.mjs

@@ -170,7 +170,11 @@ export function createVerificationController(root) {
           if (profile.mode === "browser" && group.some(check => check.scenario)) {
             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); url.searchParams.set("scenario", check.scenario); scenarios[check.scenario] = url.href; }
+            for (const check of group.filter(check => check.scenario)) {
+              const url = new URL(host.url);
+              url.searchParams.set("scenario", check.scenario);
+              scenarios[check.scenario] = url.href;
+            }
           }
           const requestContext = { schemaVersion: 1, runId, projectRoot: root, framework: options.config.framework, profile: profileName, mode: profile.mode ?? "unit", checks: group.map(({ contract: _contract, ...check }) => check), scenarios };
           writeFileSync(request, JSON.stringify(requestContext));

package/docs/ADS.md

@@ -209,6 +209,11 @@ Measured runtime variables retain their existing exact `styleWrites` boundary.
 
 A colocated scenario sets `kind:"tokens"` and declares real fixture `samples`
 consumed by a public review pattern. Its ID still derives from its source path.
+Discovery attaches its owner's registered definition sheet as `stylesheets` on
+the generated scenario record; `previewEntriesPlugin` imports it directly into
+that preview's module graph. CSS-only package side effects can then tree-shake
+the runtime component without dropping the token definitions. Keep the runtime
+CSS import for product use; the token scenario need not import or render its owner.
 Every local token needs this real sample coverage, just like shared tokens.
 Definitions, metadata, fixture and token scenario belong to the same edit unit.
 Manifests/fixtures are development inputs; production includes the runtime's

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.
@@ -434,6 +441,8 @@ verification, and the browser check does not judge design quality.
 An optional owner-local token namespace keeps component/pattern constants beside
 their consumer. Its definition-only stylesheet contains root/theme custom
 properties and is imported by the runtime owner; UI styling remains in Linaria.
+Independent owner-token preview entries also import the registered definition
+sheet directly, so tree-shaking an unused runtime owner cannot remove their values.
 Namespaces, aliases, ownership and actual colocated sample coverage are checked.
 The shared foundation remains the cross-owner vocabulary. See the
 [owner-token contract](ADS.md#owner-local-tokens).

package/docs/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 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
+  previews, preserving definitions under CSS-only package side effects without
+  retaining runtime owners or loading peer sheets. Verify resource closure in
+  React/Preact and rendered samples in a sandboxed App in both themes.
+- Route managed browser checks for owner-local token scenarios through the
+  discovered token category, independent of their component/pattern file paths.
+
 ## 0.3.9
 
 - Credit explicitly declared public child renders reached through parents,

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`
@@ -560,6 +568,10 @@ framework compilation and Linaria extraction. The starter's
 - Its `buildGraph(entries, options, track)` adapter runs one multi-entry Vite build
   with `previewEntriesPlugin()` and `createPreviewResources()` from
   `@reqvire-org/ads/scenarios/vite`.
+  Generated owner-token entries include `stylesheets` derived from the registered
+  owner manifest. Pass the entries intact: the plugin imports those definition
+  sheets even when the runtime owner is tree-shaken. A replacement entry plugin
+  must preserve these dependencies without importing unrelated owners.
 - Keep `preserveEntrySignatures: "strict"`, `cssCodeSplit: true`,
   `assetsInlineLimit: 0`, `modulePreload: false`, and `write: false`. Include the
   supplied dependency-tracking plugin and the project's Linaria/framework plugins.
@@ -697,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.9",
+  "version": "0.3.11",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {