@reqvire-org/ads 0.3.1 → 0.3.2

package/docs/ADS.md

@@ -169,6 +169,35 @@ custom styling in fixture files. The ADS frame pattern uses `--ux-*`. Foreign br
 CSS imports the approved token files in order; shared assignments belong in
 those token files, never in consumer styles or component state overrides.
 
+Foundation roles are enforced by `foundation-role`, `foundation-selector` and
+`foundation-import`, alongside the regular token checks. Shared definitions
+belong on the document root or explicit root themes; ordinary declarations belong
+in `base.css`, and font-face descriptors in optional `fonts.css`. The entry imports
+canonical sheets; those sheets cannot import another styling layer. Component
+classes, IDs, data/ARIA hooks, contextual selectors, keyframes and scoped UI rules
+are rejected in the foundation, including nested functional selectors. Raw visual
+values and undefined token references are checked in native defaults too; literal
+font-face metadata keeps its separate asset role.
+
+`base.css` has three closed roles:
+
+- Document defaults: root/body typography, canvas colors and theme behavior,
+  global text selection and document scrollbars.
+- Native resets: permitted normalization properties and values, such as zero
+  spacing, inherited control typography, list resets and responsive replaced media.
+- Global accessibility: universal `:focus-visible` outline rules, and reduced-motion
+  overrides inside `@media (prefers-reduced-motion: reduce)`.
+
+The `foundation-role` check validates every selector branch, property and value.
+Native selectors are not a bypass: token-backed button backgrounds, flex/grid
+layout, component-specific focus rules and hover/disabled skins are rejected.
+Shared token definitions belong in value sheets, not `base.css`. No project token
+names are embedded in this policy. A zero-specificity `:where()` wrapper does not
+change ownership. Put component design and animation in Linaria owners, and
+scenario layout variations in typed public review-pattern props. Browser review
+still checks the effects and accessibility of permitted defaults.
+
+
 Store original branding and its usage, credits, and licenses in
 `assets/brand/`, and fonts in `assets/fonts/`. Configure generated icons and
 asset mounts as described in the [branding guide](GUIDE.md#branding).

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
@@ -201,8 +224,9 @@ page or initializing the application's router, store or services first.
 Scenarios and their fixtures live beside the tokens, component or pattern they exercise.
 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 +246,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

package/docs/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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

package/docs/MCP.md

@@ -498,11 +498,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 +535,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 +562,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.2",
   "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",