@reqvire-org/ads 0.3.3 → 0.3.6

package/docs/ARCHITECTURE.md

@@ -149,6 +149,33 @@ preserving compatible consumer APIs. Markup, accessibility, events, layout, and
 motion still need verification when an implementation changes. Imported or
 adapted source carries its credits and applicable notices in its local guide.
 
+## Controllers own reusable behavior
+
+A private controller stays beside its component or pattern. Shared behavior uses
+`controllers/<Name>/` as an independent edit owner. Controllers may be plain
+functions/classes, framework hooks or context providers; sharing code does not
+implicitly share instances. Use the configured framework and declared project
+dependencies, with no runtime supplied by the MCP host. Shared controllers do not
+import styled consumers or introduce another skin layer. Existing measurement and
+style-write boundaries still apply.
+
+Optional owner-local `behavior.json` contracts identify public APIs or private
+source/symbols, named guarantees and registered execution checks. Scenario
+`exercises` links public behavior APIs to reachable demonstrations; `covers`
+continues to describe rendered public UI. Controllers need no artificial standalone
+visual scenario. Static registration is separate from current passing evidence.
+
+Manifests, checks, scenarios and fixtures are development inputs; production
+imports only actual components/controllers and their styles. Browser checks can
+exercise the real MCP App. React development StrictMode uses a project development
+harness, since production previews do not replay those effects. The
+[behavior contract](BEHAVIORS.md) defines profiles, execution and evidence freshness.
+
+The normal compiled import graph delivers controller dependencies through MCP
+resources. There is no eager global controller registry. ESM splitting and selected
+asset loading remain in place; tree shaking depends on actual imports, exports and
+side effects, rather than the controller directory name.
+
 ## The showcase is the shared design workspace
 
 Humans and coding agents inspect the same project through MCP. The showcase is
@@ -178,6 +205,13 @@ scenarios unmounts the previous view while keeping unchanged dependencies cached
 Persistence is a host lifecycle choice; a new external widget loads the same
 resources independently. Resource sharing is scoped to an App instance.
 
+Managed graph builders publish into a private session directory beside the
+configured manifest. Logical scenario IDs and resource URIs stay unchanged;
+standalone builds retain the configured output and cannot overwrite a live
+session's success record. Verified compiled snapshots form a bounded shared
+warm-start cache. Source, compiler, dependency and output hashes still gate reuse.
+Ordinary shutdown removes owned session output while retaining that cache.
+
 ```mermaid
 flowchart LR
   Host[Minimal host: navigation and MCP client] --> Proxy[Separate-origin sandbox proxy]
@@ -289,11 +323,22 @@ Bounded tools establish what exists; explicit resource reads provide detail.
 Prompts and packaged skills explain how to reason through Data, UX and Skin and
 how to inspect the real implementation before changing it.
 
+The MCP runtime owns its browser hosts and preview builder lifetime. Closing the
+client connection releases them together; a separate ownership guard can stop
+detached builders after abrupt owner death. A preview process must not outlive
+its owner and continue publishing stale output.
+Build reports expose queued, validation, compilation and publication progress.
+A timed-out preview request marks the builder stalled; the next explicit request
+restarts it within the same MCP session. A running process alone is not freshness.
+
 Opt-in MCP editing makes validation part of the write operation. The agent sends
 a Git unified diff for one logical ADS unit: its implementation and owned preview
 context, or the shared token foundation. ADS resolves file ownership, reconstructs
 candidate files locally and validates a temporary project copy with architecture
-checks, registered lint rules and project validation scripts. This keeps edits
+checks, registered lint rules and project validation scripts. Affected registered
+behavior checks, including consumers of a changed shared controller, also run in
+the isolated candidate project. Passing checks describe
+their registered assertions, not every natural-language claim. This keeps edits
 focused without requiring entire file bodies in model context. Peer units and
 unrelated owners remain outside the selected unit's edit boundary. Shared foundation,
 branding and guides have their own units. Project configuration, registered guards
@@ -304,6 +349,13 @@ replace the managed process while retaining the MCP connection. Normal build gat
 remain in place for source changes made through other editors; preview review remains
 necessary after either editing path.
 
+For genuinely coupled changes, a bounded transaction accepts one Git patch per
+distinct owner and validates a single complete candidate before publication.
+Each patch retains its ownership and companion rules. Local owner drafts remove
+the need for a separate project mirror; token-sample reconciliation preserves
+project bindings and reports unresolved mappings. Neither preparation changes live
+source or substitutes for guarded application and rendered review.
+
 Required shared-entry bookkeeping can accompany its owner: component/pattern
 re-exports, canonical foundation imports for token files created or deleted, and
 only that owner’s style-boundary entries in project configuration in the same
@@ -353,3 +405,10 @@ review pattern. The App then verifies rendered samples in the actual browser by
 probing those bindings and restoring them. The tool supplies no token/property
 classification or visual sample palette. A source build alone is not a rendered
 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.
+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/BEHAVIORS.md

@@ -0,0 +1,241 @@
+# Controllers and behavioral verification
+
+Controllers own reusable UI behavior: state, subscriptions, DOM measurements and
+lifecycle coordination. A controller may be a class, function, hook, state
+machine or context provider. Linaria and tokens own its consumers' visual design.
+
+Private controllers stay inside their component/pattern mutation unit. Shared
+controllers use `design-system/controllers/<Name>/` with an `index` entry or a
+runtime file matching the directory name. The unit ID is `controllers/<Name>`.
+Its implementation, tests and guides can change together, including only its own
+required public re-exports. A shared controller needs no artificial visual preview.
+Consumers normally create separate instances; sharing implementation does not
+implicitly share state.
+
+Use the project's `framework` from `ds.config.json` for framework-specific APIs.
+Plain TypeScript, browser APIs and local behavior helpers remain supported.
+Declare external dependencies in the project package. ADS does not install them
+or assume a renderer/library supplied by an MCP host. The framework field selects
+compilation/mounting; controller checks also validate runtime imports. Type-only
+UI references are allowed, but shared controllers cannot import component/pattern
+runtime implementations. Keep business data in application adapters. Measured
+style writes retain exact `boundaries.styleWrites` properties; they do not allow
+shared-token overrides or an extra styling layer.
+These gates inspect supported direct imports, markup and style boundaries.
+External package internals and delegated DOM behavior still require source,
+build and browser review; declaring a dependency does not prove it is headless.
+
+## Development boundary
+
+Production includes real components, controllers, tokens and compiled styles.
+Scenarios and fixtures are included only in previews. Behavior manifests and test
+files are development/tooling inputs. Runtime imports and public re-exports of
+those inputs are rejected, including dynamic imports and aliases.
+
+## Register guarantees
+
+An optional `behavior.json` belongs to one directory unit. Flat units use
+`<Owner>.behavior.json`. Existing projects without manifests remain valid and have
+no implied behavioral verification. A manifest is declarative and contains no
+executable command:
+
+```json
+{
+  "schemaVersion": 1,
+  "subjects": {
+    "controller": { "source": "./scroller-controller.ts", "symbol": "ScrollerController" },
+    "scroll-api": { "api": "useMessageScroller" }
+  },
+  "guarantees": [
+    {
+      "id": "prepend-anchor",
+      "description": "Prepending history preserves the visible anchor after layout settles.",
+      "subjects": ["controller", "scroll-api"],
+      "checks": ["prepend-anchor"]
+    }
+  ],
+  "checks": {
+    "prepend-anchor": {
+      "file": "./behavior.spec.ts",
+      "case": "prepend-anchor",
+      "scenario": "components/MessageScroller",
+      "profile": "widget"
+    }
+  }
+}
+```
+
+Names above are illustrative project choices. A subject identifies a public export
+through `api`, or an owner-local implementation `source` with an optional top-level
+`symbol`. Private subjects do not become public API. A guarantee references known
+subjects and checks. Each check names an owner-local test/spec file, stable case
+ID, registered profile and optional discovered scenario. Several guarantees may
+reference one check. Repeated execution identities use the same check ID.
+
+Static validation establishes registration and ownership, not that the guarantee
+is true. README prose is not automatically certified. Link specific guarantees
+when describing the evidence available for a behavior.
+
+## Link a public API to a demonstration
+
+Scenario `covers` retains its existing render-reference contract. Optional
+`exercises` identifies public behavioral APIs:
+
+```tsx
+export const scenario = {
+  title: "Message scrolling",
+  covers: ["MessageScroller", "MessageScrollerViewport"],
+  exercises: ["useMessageScroller", "useMessageScrollerScrollable"],
+};
+```
+
+Call hooks in a rendered local scenario adapter. Calls/construction are matched by
+resolved symbol, not a `use*` naming convention. An unused import, dead adapter or
+metadata string does not count. Dynamically passed behavior references produce a
+review advisory when a direct call cannot be established; verify those through
+registered execution checks rather than changing the API for the analyzer.
+
+Public APIs appear in `ads_catalog` with `apiKind: "ui"` or `"behavior"` and their
+scenario links. `ads_behaviors` joins contracts to demonstrations and evidence.
+A demonstrated API is not automatically a verified guarantee.
+
+## Register execution profiles
+
+Profiles are explicit trusted development commands in `ds.config.json`. They use
+literal executable/argument arrays, no shell interpolation or model-supplied
+command. For a project with an installed Playwright test runner:
+
+```json
+{
+  "mcp": {
+    "behaviorProfiles": {
+      "widget": {
+        "runner": "playwright",
+        "command": "npm",
+        "args": ["run", "test:behavior", "--"],
+        "mode": "browser",
+        "timeoutMs": 60000
+      }
+    }
+  }
+}
+```
+
+Here `test:behavior` invokes the project's local `playwright test`. Its Playwright
+configuration must discover colocated spec files. Configure browser installation
+and any required test setup in that project. The ADS tooling host gains no
+framework or browser dependency from a profile.
+
+The Playwright adapter appends selected file paths, its reporter and a generated
+artifact directory. Use native test tags for stable case identity:
+
+```ts
+import { test, expect } from "@playwright/test";
+import { openBehaviorScenario } from "@reqvire-org/ads/verification";
+
+test("history preserves the visible anchor", { tag: "@ads:prepend-anchor" }, async ({ page }) => {
+  const frame = await openBehaviorScenario(page, "prepend-anchor");
+  // Perform real interactions and assert the project's guarantee here.
+  await expect(frame.getByRole("region", { name: "Messages" })).toBeVisible();
+});
+```
+
+The shown assertion is only a harness example; it does not establish anchoring.
+Write meaningful assertions for the registered guarantee. The helper waits for
+the current selected scenario inside the real sandboxed MCP App. It uses `load`
+and explicit readiness, not `networkidle`: MCP keeps event connections open.
+
+Compare reference and candidate under equivalent framing. In a reported Chrome
+comparison, `content-visibility` initially used placeholder geometry inside a
+cross-origin App iframe for both ADS and the upstream reference; the same content
+measured differently as a top-level page. This is an observed browser/layout
+condition, not evidence of an ADS defect. App readiness does not imply that every
+off-screen item has rendered. For geometry assertions, bring the relevant content
+into view and wait for its measured layout to settle. Record the framing and
+visibility state; test initial placeholder behavior separately when it matters to
+the guarantee. Wait for focus and positioning readiness before normal keyboard
+comparisons, and test rapid input separately rather than hiding it behind delays.
+
+`mode: "browser"` starts an isolated managed showcase on an automatic port. Test
+requests contain its scenario URLs, and cleanup closes its host/compiler tree.
+Mutation candidates use their own source, generated graph and server; a passing
+test against an older fixed-port live showcase cannot validate a candidate.
+
+Use `mode: "strict"` only for React with a project development harness that mounts
+the relevant API in StrictMode. The production MCP App does not replay development
+effects. This profile does not receive a production showcase URL from the helper.
+For Preact, register its actual lifecycle tests without claiming React StrictMode.
+The profile names record the chosen environment; ADS does not infer that a test's
+assertions cover every lifecycle condition.
+
+Other runners use `runner: "protocol"` (the default). ADS provides
+`ADS_VERIFY_REQUEST` and `ADS_VERIFY_REPORT` absolute paths. Read the request's
+`schemaVersion`, unique `runId`, `projectRoot`, `framework`, `profile`, `mode`,
+selected `checks` and optional `scenarios` URLs. Write a bounded JSON report:
+
+```json
+{
+  "schemaVersion": 1,
+  "runId": "<the request's runId>",
+  "cases": [
+    {
+      "id": "prepend-anchor",
+      "file": "design-system/components/MessageScroller/behavior.spec.ts",
+      "status": "passed"
+    }
+  ]
+}
+```
+
+Case statuses are `passed`, `failed` or `skipped`, with optional `message`.
+`file` is project-relative. Nonzero process exit, missing cases, skipped cases,
+wrong run IDs and unavailable reports do not pass. Test commands are trusted
+project code; an adapter cannot prove the quality or honesty of their assertions.
+
+## Execute and inspect evidence
+
+Use `ads_behaviors` for bounded discovery; request an exact unit for its contract.
+General listings return counts and short API/guarantee/scenario summaries. Exact
+owner requests return the registered details; source reads remain available for
+bounded inspection of large contracts. No full guide or test body is injected
+into discovery results.
+Call `ads_verify({unit, checks?})` for selected registered checks. Read
+`ads://project/behaviors` for current evidence or `ads://guides/behaviors` for this
+guide. CLI/CI equivalents are:
+
+```sh
+ads behaviors . --json
+ads verify . --unit controllers/ScrollFollow
+ads verify . --unit components/MessageScroller --check prepend-anchor --json
+```
+
+Execution has bounded output, a configured timeout, cancellation and process-tree
+ownership. Evidence records case/profile identity, source/dependency revision,
+completion time, report path and the available preview revision. Later input
+changes mark results stale; changes during execution prevent a current pass.
+Guarantees report passing only when all their checks have current passing evidence.
+Passing applies to those cases and profiles, not every application state.
+
+Revisions include owned files, literal import dependencies, local CSS imports and
+asset URLs, token foundation, project/runner configuration, lockfiles and tooling.
+Computed module selection conservatively includes all ADS owners. Environment,
+network and other unregistered external inputs remain the runner's responsibility;
+an evidence record is not a proof about arbitrary external state.
+
+Guarded mutations execute affected registered behavior contracts after core,
+Oxlint and configured project checks, before writing source. Imported shared
+controller changes also select dependent contracts conservatively. Rejected and
+dry-run patches publish no source changes. Verification output stays under `.ds/`.
+
+## Packaging and performance
+
+Controllers follow normal component/scenario imports into the project's compiled
+resource graph. Their framework dependencies are bundled by the project compiler
+and served through MCP resources inside the App iframe; external hosts install
+nothing. The selected scenario loads its dependency closure. Shared modules are
+cached within that App instance, and each separately opened App has its own runtime.
+
+Keep ESM modules and explicit imports. Avoid an eagerly imported controller
+registry. Tree shaking and shared chunks follow the project bundler: class methods,
+side effects, global CSS and dynamic maps can retain extra code. Inspect emitted
+resources instead of assuming a controller produces a minimal bundle.

package/docs/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.6
+
+- Isolate managed resource-graph output by session; reuse verified compiled
+  snapshots across warm starts without letting standalone builds overwrite live
+  preview success records.
+- Add component/pattern-owned token namespaces, closed definition-only sheets,
+  discovery, alias/ownership checks and real colocated token-preview coverage.
+- Add owner draft/diff preparation and project-directed token sample reconciliation.
+  Keep all source writes behind guarded Git patches.
+- Add bounded coupled-owner transactions, validating all guards, registered checks
+  and affected behavior checks against the final candidate before publication.
+- Permit empty .gitkeep deletion alongside real new owner source. Retain hidden
+  file restrictions, render coverage and public scenario-control ownership.
+- Document framed content-visibility geometry as a browser comparison condition,
+  with observable layout/focus readiness and separate rapid-input checks.
+
+- Use MCP display titles throughout the diagnostic explorer, with annotation-title
+  and tool-name fallbacks. Publish configured App titles in tool metadata and keep
+  machine-readable names for protocol calls.
+
+## 0.3.5
+
+- Bound preview-watch test teardown, publish selection requests atomically and
+  wait for the changed preview output before checking revision/queue order.
+  Cap the release test stage so failed cleanup cannot hold publication indefinitely.
+
+- Stabilize the development StrictMode browser harness across dependency-optimizer
+  reloads. Verify the broken controller fails its cleanup assertion and the
+  repaired controller passes. Version 0.3.4 was not published after CI caught the
+  harness navigation race.
+
+- Add shared controller units, framework/dependency and headless ownership checks,
+  while retaining private controllers in their consumers' units.
+- Add optional owner-local behavior contracts, scenario `exercises`, public hook
+  discovery, `ads_behaviors`/`ads_verify`, revision-bound results and subscribed
+  evidence resources. Guarded edits run affected registered checks in candidates.
+- Add registered protocol/Playwright execution profiles with cancellation,
+  process-tree cleanup, real sandboxed-App checks and development StrictMode
+  harness guidance. Keep behavior metadata/tests outside production imports.
+- Rename the external-library adaptation workflow and MCP prompt to `ads-migrate`;
+  retain `ads-import` for ADS-compatible source and token transfers.
+- Expose compiler progress phases and restart a timed-out builder on the next
+  explicit preview request without requiring an MCP reconnect.
+
+- Close the raw `ch` sizing gap across absolute/font-relative CSS length units,
+  nested calculations and numeric notation. Share unit categories with dimension
+  token validation; keep structural angles and responsive geometry available.
+  Preserve the demo's text measures in owned tokens with preview coverage.
+
+- Close the whole MCP runtime on stdio wire closure, including broken output,
+  and stop browser sockets, subscriptions and preview processes together.
+- Add an independent preview ownership guard so abrupt MCP process or process-group
+  death also terminates detached builders and their descendants.
+
 ## 0.3.3
 
 - Reject unused inline-style permissions and imperative property permissions.

package/docs/GUIDE.md

@@ -29,6 +29,20 @@ template strings and Shadow DOM style constructs lack equivalent coverage.
 Retain framework-specific checks; a clean ADS check does not validate those
 unchecked surfaces.
 
+### Controllers and behavior checks
+
+Keep private controllers with their consumer; share reusable behavior through
+`design-system/controllers/<Name>/`. Use the configured framework and declared
+project dependencies. Controllers own lifecycle/measurements while components and
+patterns own presentation. A shared context provider is a behavioral API too.
+
+Optional owner-local `behavior.json` registers guarantees and maintained checks.
+Scenario `exercises` records demonstrations separately from rendered `covers`.
+Use `ads behaviors --json` for discovery and `ads verify --unit <discovered-id>`
+to run registered cases; MCP exposes `ads_behaviors` and `ads_verify`. Tests and
+contracts stay outside production exports. See the [complete schema and runner
+integration](BEHAVIORS.md), including browser and React development StrictMode profiles.
+
 ### Linaria integration
 
 Before authoring components or patterns, integrate Linaria extraction with the
@@ -350,7 +364,11 @@ for edits made by other tools.
 categories, undefined aliases, alias cycles, and individual theme/media
 overrides. Project-specific values and additional definitions within ADS's fixed
 naming contract are allowed. The contract's `naming` section lists the fixed
-shared families and names; projects cannot configure alternative prefixes.
+shared families and names; projects cannot rename those shared semantics.
+Component/pattern constants can use an explicit unique owner-local namespace and
+definition-only stylesheet, with the same real-token preview completeness rules.
+See [owner-local tokens](ADS.md#owner-local-tokens). Unregistered foreign names
+remain rejected.
 `--ds-*`, `--ux-*`, and `--showcase-*` variables remain owned by their layers,
 including when a file is inside `tokens/`. Shared token assignments outside
 `tokens/` fail. Source styles also check shared references for undeclared names.
@@ -484,8 +502,9 @@ in owned component/pattern styles, with tokens supplying visual values.
 
 ADS has fixed token names and ownership namespaces. Change values in the existing
 token files; `--accent`, `--font-sans`, `--radius-md`, and the other shared roles
-keep their meanings across projects. Foreign prefixes such as `--nuv-*` or
-`--brand-*` fail. Components own `--ds-*`, patterns own `--ux-*`, and the showcase
+keep their meanings across projects. Foreign shared prefixes such as `--nuv-*` or
+`--brand-*` fail; a registered owner-local constant namespace is separate from
+the shared branding vocabulary. Components own `--ds-*`, patterns own `--ux-*`, and the showcase
 reserves `--showcase-*` for showcase boundaries. Fixture files still define no
 custom styling; the frame pattern uses `--ux-*`. Branding never assigns
 component state variables.
@@ -558,6 +577,7 @@ Application manifest metadata and other platform exports remain project-owned.
 | Asset ownership | ADS/public mount collisions, configured generated assets in source, and tracked generated output |
 | Product patterns | CSS/JSX namespace ownership; ADS implementations and showcase cannot import app source |
 | Primitive state | State-variable overrides outside components; undocumented non-state component variables |
+| Literal visual values | Absolute/font-relative lengths (including `ch` and root font units), durations and color/effect formulas require tokens; geometry angles and responsive viewport/container relationships remain available |
 | Fixed token ownership | Foreign token names, shared token overrides, misplaced component/pattern/showcase variables, and noncanonical foundation imports |
 | Showcase ownership | Fixture CSS/Linaria definitions, custom JSX classes, native controls/widget roles, state styling, private CSS/aliased imports, legacy catalogue dependencies and source ownership, and runtime imports of fixtures/test helpers |
 | Scenario coverage | All public renderable UI has path-discovered entries, colocated fixtures, literal metadata and reachable public render references; runtime imports of scenarios/fixtures are rejected |
@@ -717,7 +737,7 @@ Retain unrelated lint, type checking, and framework build commands.
 ## External content
 
 Use the repository's `ads-import` skill for selected external ADS source or theme
-values, and `ads-assimilate` for a native implementation inspired by an upstream
+values, and `ads-migrate` for a native implementation inspired by an upstream
 library. These agent workflows handle dependency closure, token mapping, motion
 comparisons, source credits, applicable notices, and local documentation.
 They are agent workflows, rather than CLI import/design subcommands. Install