@reqvire-org/ads 0.3.1 → 0.3.3

package/docs/ARCHITECTURE.md

@@ -191,6 +191,29 @@ and the UI rendered inside Apps belong to the project. This keeps the tool usefu
 with an empty ADS while making every implementation addressable once its scenario
 exists.
 
+### The foundation has a narrow styling role
+
+Shared token sheets define values on the document root and its themes. The
+import-only entry loads them in canonical order. `fonts.css` declares font faces;
+`base.css` establishes shared native defaults and normalization. Components and
+patterns own their layout, skin, states and animations in Linaria.
+
+`base.css` has a closed contract with three roles: root/body typography, canvas
+colors and theme behavior; limited native normalization; and global accessibility
+through focus indicators and reduced-motion rules. Selector, property and value
+checks reject component skins and layout even when they use native selectors and
+valid tokens. A `button` background or `body` grid belongs to a Linaria owner.
+Document defaults also cover shared text selection and document scrollbars;
+local control/scroll-container styling stays with its owner.
+
+Foundation CSS passes the ordinary token-reference and visual-value checks too.
+Parsed selectors reject component hooks, local shared-token overrides and
+contextual selectors, including hooks concealed in `:where()` or `:is()`. The
+policy describes CSS roles and normalization keywords, with no project classes,
+token catalogue or sample templates. Lower specificity cannot bypass ownership.
+Static gates establish this source contract; browser review still checks its
+actual effects and accessibility.
+
 ### A preview scenario is the unit of review
 
 A component export alone may need inputs, parent context, local state or callbacks
@@ -199,10 +222,13 @@ real public implementation. It mounts independently, without opening a showcase
 page or initializing the application's router, store or services first.
 
 Scenarios and their fixtures live beside the tokens, component or pattern they exercise.
+Demo framing belongs to public review/layout patterns; component props describe
+intentional product behavior and visual variants.
 Token scenarios choose real token names and sample inputs; a project-owned
 review pattern applies the foundation variables. The tool contains no project
-token list, sample templates or assumed visual identity. A minimal foundation
-scenario can inspect values before a project has any components.
+token list, sample templates or assumed visual identity. Even an initial token
+scenario uses a public project-owned review pattern to apply its declared samples;
+a definitions-only inspector does not establish preview coverage.
 Larger scenarios live under `composition/`. They use the same public screen
 patterns as production: application adapters supply live data and effects;
 scenario adapters supply fixture data, local state and simulated services.
@@ -222,7 +248,12 @@ 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
 loader mounts the new module graph. Failed builds retain the previous view with
-visible stale diagnostics. Compilation remains necessary for TSX and Linaria;
+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.
+If the compiler process exits, the next preview request starts one fresh child;
+MCP inspection remains available. Each child generation has its own status report,
+so independent MCP clients do not overwrite each other's build state.
+Compilation remains necessary for TSX and Linaria;
 there is one preview pipeline with automatic updates.
 
 Scenario entries, adapters and fixtures are development source even when
@@ -274,9 +305,10 @@ remain in place for source changes made through other editors; preview review re
 necessary after either editing path.
 
 Required shared-entry bookkeeping can accompany its owner: component/pattern
-re-exports and canonical foundation imports for token files created or deleted in
-the same patch. ADS restricts these companion edits and validates the complete
-candidate before writing, so coupled changes do not need a guard bypass.
+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
+patch. ADS restricts these companion edits and validates the complete candidate
+before writing, so coupled changes do not need a guard bypass.
 
 The architecture makes that inspection practical. A public export has an owning
 source and addressable preview coverage. Token definitions expose its visual

package/docs/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.3.3
+
+- Reject unused inline-style permissions and imperative property permissions.
+  Allow only the edited owner's boundary entries to accompany its source patch
+  atomically; preserve other settings and peer permissions.
+- Keep directory unit ownership stable when removing an optional standalone
+  scenario; require actual coverage from remaining entries.
+- Expose nonblocking pointer-capture cleanup advisories in CLI, MCP checks and
+  accepted mutations. Keep delegated cleanup and runtime correctness under review.
+- Clarify demo framing, intentional product APIs and local asset fixtures in
+  diagnostics and skills; preserve component capabilities without demo-only props.
+
+## 0.3.2
+
+- Enforce foundation CSS roles, parsed selector boundaries, root-only shared token
+  assignments, token references and visual values. Keep native defaults in
+  `base.css`, definitions in value sheets and font-face metadata in `fonts.css`;
+  reject hidden owner styling, extra imports and animation/scoping escapes.
+  Close `base.css` to document defaults, limited normalization and global
+  accessibility; native selectors and valid tokens cannot hide component skins
+  or layout. Move the demo link hover styling into its TextLink owner.
+- Keep scenario discovery and build failures recoverable in the watcher, including
+  invalid metadata at startup. Reattach replaced source-directory watches.
+- Retry exited builders on the next preview request without reconnecting MCP;
+  reload changed compiler code through a fresh child and preserve inspection.
+  Isolate status reports per child session across concurrent MCP clients.
+- Align the starter, example foundation and skills with the enforced boundaries.
+
 ## 0.3.1
 
 - Stop generating redundant empty public exports. Allow an owning unit's public

package/docs/GUIDE.md

@@ -302,7 +302,7 @@ For iterative development, use the linking workflow above. From the repository r
 npm install
 npm run build
 npm run pack:tool
-ads_tool_package="$PWD/output/npm/reqvire-org-ads-0.3.1.tgz"
+ads_tool_package="$PWD/output/npm/reqvire-org-ads-0.3.2.tgz"
 ```
 
 Then change into an existing test project containing `package.json`:
@@ -497,6 +497,14 @@ import-only: fonts (when present), colors, typography, spacing, elevation, base.
 Fixed artwork colors and geometry are permitted inside SVG assets; they do not
 permit raw visual values in component or pattern styles.
 
+Foundation sheets are checked source. Keep root token definitions in value sheets,
+font faces in `fonts.css`, and closed-role defaults in `base.css` (document
+typography/canvas/theme, limited native resets, global focus/reduced motion).
+Owner hooks, contextual UI selectors, keyframes, extra CSS imports, raw visual
+values and missing token references fail checks there too. Move component-specific
+repairs into their Linaria owner; see the [foundation contract](ADS.md#shared-token-contract).
+
+
 Select one SVG master with an ADS-relative path:
 
 ```json
@@ -681,6 +689,15 @@ Registered project configuration and build helpers may import one another;
 this boundary is derived when lint configuration is generated. It does not
 allow application code to import private ADS modules or build helpers to import
 private UI implementation.
+
+Unused `inlineStyleFiles` entries and `styleWrites` properties fail the core
+`stale-style-boundary` check. Inline permissions recognize JSX, imported UI
+factories and UI `CSSProperties` use; property permissions require an exact write
+or removal, not a read. For MCP migrations, include the owner's source and only
+its own exception entries through its `ds.config.json` companion. Preserve peer
+permissions and other settings. A future filename can be valid configuration,
+but the complete checked candidate must contain the matching use.
+
 `inlineStyleFiles` should name only documented geometry/renderer boundaries,
 not broad styling exceptions. Ignore `.ds/`; generated paths refer to the project
 and its locally installed tool.

package/docs/MCP.md

@@ -209,6 +209,22 @@ imports for canonical files created/deleted in that patch. Preserve other import
 and comments, retain the foundation entry, and follow the required import order.
 Both files pass the same candidate checks before either is written.
 
+Runtime owner manifests also list `ds.config.json` in `companionFiles`. An owner's
+patch may update only its own `inlineStyleFiles` and `boundaries.styleWrites`
+entries together with its source. All other settings and peer permissions must
+remain unchanged. This supports atomic JSX-to-imperative geometry migrations,
+new boundaries and removal of obsolete permissions without bypassing the gate.
+Unused inline exceptions and properties never written fail `stale-style-boundary`;
+configuration-first registration of an unused boundary therefore fails validation.
+General policy, component customization hooks and compiler changes still use the
+`configuration` unit.
+
+A directory owner's runtime entry (`index` or a source file matching its directory
+name) or colocated fixture keeps ownership stable without `Scenario.tsx`.
+A redundant standalone scenario can be removed when other registered scenarios
+still declare and actually render its public exports. Coverage requirements remain
+in force; there is no metadata waiver for uncovered UI.
+
 The same discovery covers the rest of the project ADS:
 
 | Unit | Scope |
@@ -262,6 +278,13 @@ not an edit to live ADS source. Binary `ads_read_file` results return the digest
 byte count without encoded content. Git verifies the original binary blob and
 reconstructs the result inside the validation copy.
 
+Resolve ownership diagnostics by preserving the required capability in its proper
+layer. Demo-only sizing, borders and framing belong in a public review/layout
+pattern; a component API addition needs a runtime use case. Measured imperative
+geometry uses exact `styleWrites` properties. After migrating JSX inline geometry,
+replace its own boundary entries in the same owner patch and check the final state.
+After the gates pass, verify the behavior in a browser.
+
 A small change needs only its hunk. A complete new component may include its
 implementation, public re-export, scenario and fixture in the same unit patch,
 so coverage is checked against a complete candidate. New units use a new
@@ -378,6 +401,13 @@ and unchanged styles/fonts are reused. External hosts may create a fresh App for
 each tool call. Each fresh App loads independently through the same contract.
 There is no special local direct-artifact rendering path.
 
+`ads_check` returns blocking `diagnostics` separately from bounded nonblocking
+`advisories`, with `advisoryCount`. The checks resource contains the full result.
+For example, `pointer-capture-review` reports capture without a locally visible
+capture-loss handler. Cleanup can be delegated; inspect it and test cancellation,
+capture loss and teardown. A local handler suppresses that advisory but does not
+prove correct behavior. Accepted mutations also return bounded advisories.
+
 ### Host boundary and compatibility
 
 The showcase's packaged shell retains its own minimal CSS and navigation. It
@@ -498,11 +528,17 @@ success cache is republished in the new watcher session without recompilation;
 merely finding an older HTML file is insufficient. A timeout leaves the watcher running: inspect the
 logs and invoke the preview again. `ads_status` distinguishes watcher process
 state from reported build state. Token inspection and other ordinary tools
-remain available after a build failure. An exited watcher needs reconnection;
-an active watcher can recover on the next successful rebuild. Changes to
-`previewWatch`, the compiler adapter or ADS tooling require reconnection to load
-new process code. The shared scheduler rejects publication if its loaded adapter
-files change; normal component, fixture and style edits remain automatic.
+remain available after a build failure. Invalid scenario metadata at startup and
+later source/validation failures remain reported while the compiler watches for
+repairs. A successful edit recovers without reconnecting MCP. If the child process
+exits, fix the builder and invoke the preview again: concurrent requests share one
+fresh child and session. ADS does not run an unattended crash/restart loop.
+
+Changes to loaded compiler code or dependencies produce `ADS_PREVIEW_RESTART`;
+the next preview invocation restarts only the builder and validates current inputs.
+Managed configuration changes replace the compiler through the same supervisor.
+Updating ADS server code itself still requires reconnecting the MCP client to load
+the new package. Normal component, fixture and style edits remain automatic.
 
 ADS stops the managed watcher and its compiler subprocesses when stdin closes or
 it receives SIGINT/SIGTERM. The project must keep its watcher in the foreground,
@@ -529,7 +565,10 @@ No ADS package release or skill reinstall is needed for project component change
 ### When code or styles break
 
 A preview publisher reports `building`, `ready` or `error` to
-`.ds/build-status.json`. `ads_status.build` and the `ads://project/build` resource
+`.ds/build-status.json` for standalone builds. A managed compiler receives its own
+`.ds/build-status-<session>.json` through `ADS_MCP_BUILD_STATUS`; publishers must
+honor that path and `ADS_MCP_BUILD_SESSION`. Independent MCP clients therefore do
+not clobber each other's reports. `ads_status.build` and the `ads://project/build` resource
 expose those states, each preview's build revision, last successful revision,
 availability, freshness and diagnostics. Diagnostic positions are one-based.
 Tool summaries include the first three diagnostics per preview, capped at 1,000
@@ -553,7 +592,9 @@ failed build even when older output remains on disk. The reusable bootstrap and
 retained immutable assets stay readable so an existing App can report freshness;
 readability alone does not establish a current preview. After a successful rebuild the same
 tool works again without restarting MCP. If the watcher itself exits, its
-failure is reported and the client must reconnect after fixing the command.
+failure is reported; after fixing the command, invoke the preview again to start
+a fresh builder. Partial or empty scenario discovery also exposes project-level
+diagnostics through `ads://project/build`.
 
 Already-mounted Apps show rebuilding, failure or a newer available revision
 when the host permits server resource reads. They check build status every two

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {
@@ -51,6 +51,7 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.3.1",
     "postcss": "^8.5.30",
+    "postcss-selector-parser": "^7.1.6",
     "postcss-value-parser": "^4.2.0",
     "sharp": "^0.35.5",
     "typescript": "^5.9.3",