@reqvire-org/ads 0.3.5 → 0.3.6

package/docs/BEHAVIORS.md

@@ -145,6 +145,17 @@ 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

package/docs/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## 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

package/docs/GUIDE.md

@@ -364,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.
@@ -498,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.

package/docs/MCP.md

@@ -171,6 +171,9 @@ The server supplies agent guidance through its instructions, tool descriptions,
 | `ads_verify` | Execute an owner's registered checks and record revision-bound evidence |
 | `ads_show_<id>` | Optional explicitly configured grouped App |
 | `ads_units` | Discover edit owners and the files belonging to one unit |
+| `ads_prepare_patch` | Prepare a local draft of one owner, then generate its Git patch |
+| `ads_prepare_token_samples` | Reconcile real-token fixture samples using explicit project bindings |
+| `ads_apply_transaction` | Validate and apply coupled owner patches as one final candidate |
 | `ads_read_file` | Read bounded source ranges, with owning unit and full-file digest |
 | `ads_apply_patch` | Opt-in Git unified diff for one ADS unit, with dry-run validation |
 
@@ -220,8 +223,9 @@ npx -y @reqvire-org/ads mcp --mutations
 ```
 
 `ads_status.mutations` reports the mode, checks, limits and latest result. Editing
-is disabled by default. The editing tool accepts **one Git unified diff for one
-ADS unit**, not replacement file bodies or a caller-selected batch of owners.
+is disabled by default. The default editing tool accepts **one Git unified diff
+for one ADS unit**. Replacement file bodies are not mutation inputs. Genuinely
+coupled changes use the bounded owner transaction described below.
 
 Find the owner with `ads_units({ "query": "Button" })`, then request its file
 manifest with `ads_units({ "unit": "components/core/Button" })`. IDs derive from
@@ -231,6 +235,8 @@ composition owns its scenario and mock inputs. Imported components and patterns
 remain separate owners. `tokens` is one foundation unit covering token definitions,
 themes and token scenarios/fixtures, whose coverage spans shared source files.
 Preview IDs remain separate: several token previews belong to `tokens`.
+Unit-local token definitions and their previews stay in their component/pattern
+owner; see [owner tokens](ADS.md#owner-local-tokens).
 
 The `tokens` manifest also returns `companionFiles` with the configured foundation
 entry path. When creating or deleting a canonical token foundation file, include
@@ -256,6 +262,8 @@ 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.
+An empty `.gitkeep` may be deleted alongside new source in the selected owner
+beneath that marker. Other hidden files and nonempty markers remain blocked.
 
 The same discovery covers the rest of the project ADS:
 
@@ -310,6 +318,47 @@ 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.
 
+For local editing without a second Git mirror, call
+`ads_prepare_patch({unit, action:"create"})`. It returns a draft ID and a local
+directory containing only the owner and declared companions. Edit that directory
+using the client's local file tools, then call
+`ads_prepare_patch({unit, action:"diff", draft})`. It checks source/baseline
+freshness and owner paths and returns a `patchFile`; it changes no live source.
+Apply the result through `ads_apply_patch`, which runs the normal candidate gates.
+Use `action:"discard"` to remove the draft. Remote clients can continue sending
+inline Git diffs. Drafts are local conveniences, not an alternative mutation API.
+
+`ads_prepare_token_samples({id, bindings?})` reconciles the selected token
+scenario's consumed literal sample array. Existing bindings and other fixture
+fields are preserved; undeclared samples are removed. New bindings explicitly
+name a real `token`, CSS `property` and `probe`. Missing mappings are reported as
+`unresolved`; ADS never guesses a property or renderer from the token name.
+The result is an owner patch file for guarded application. This preparation does
+not establish rendered effects or waive token coverage.
+
+For a coupled rename or upgrade, call `ads_apply_transaction`:
+
+```json
+{
+  "patches": [
+    { "unit": "tokens", "patchFile": ".ds/patches/tokens.patch" },
+    { "unit": "components/Button", "patchFile": ".ds/patches/button.patch" }
+  ],
+  "dryRun": true
+}
+```
+
+It accepts 2–8 distinct owners, at most 32 distinct files and 16 MiB of combined
+Git diff text. Each patch obeys its own ownership/companion rules. Patches apply
+in order inside one candidate; shared-entry hunks in a later patch must match
+the earlier candidate's content. Core checks, registered Oxlint, project commands
+and all affected behavior checks run against the final candidate. No intermediate
+candidate is published. Dry runs, failures, conflicts and cancellation write no
+source; a publication failure rolls back prior writes. This coordinates owned
+source migrations, not dependency installation or arbitrary application files.
+Install changed dependencies before verification; candidates use the project's
+installed `node_modules`.
+
 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
@@ -326,8 +375,8 @@ a new directory owner, or change unrelated public-entry statements. Shared
 public-entry changes are limited to re-exports from the selected unit. Alongside
 its real re-export, a patch can remove an obsolete `export {};` placeholder;
 it cannot add one or change unrelated statements. Init generates no empty-export
-placeholder. Report unsupported coupled changes rather than bypassing a rejected
-mutation with direct source writes.
+placeholder. For coupled owners use the bounded transaction; a rejection still
+requires correcting its owner/policy, never a direct-write bypass.
 
 Set `dryRun` to `false` to apply. ADS reconstructs complete candidate files locally
 and validates a temporary project copy with core guards and registered Oxlint
@@ -557,7 +606,13 @@ wrappers require their own launcher and are not shell-executed by ADS.
 Both build output streams go to stderr, keeping stdout exclusively for MCP.
 Opening an App waits up to 30 seconds for validated current output. A matching
 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
+merely finding an older HTML file is insufficient. Managed resource graphs and
+HTML descriptors use private session output; standalone build commands retain
+the configured output. One cannot overwrite the other's success record. The
+compiler caches at most six verified graph snapshots under `.ds/preview-graphs/`
+and cleans its session output on ordinary shutdown. These are generated files;
+do not track or use them as source. Legacy self-contained HTML builders retain
+their existing publication contract. 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. Invalid scenario metadata at startup and

package/package.json

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