@reqvire-org/ads 0.0.0-stage → 0.2.9

package/dist/skills/ads-assimilate/references/cli.md

@@ -0,0 +1,111 @@
+# Run ADS tooling through npx
+
+Use npx for setup or ad hoc checks alongside this skill's research,
+implementation, documentation, and verification workflow. ADS must be a project
+development dependency, and its checks must run before the project's build.
+Routine builds use the local CLI.
+
+Select an actual published package/version or a real local tarball supplied by
+the user or built from the tool checkout. Respect the project's installed
+version. Confirm the selected published version supports the required features; use a
+local tarball for unreleased changes. Never resolve an unrelated package with
+bare `npx ds`. Read the actual version/help and use only supported commands.
+
+## Published setup
+
+Run **inside the receiving project**, where
+`package.json` lives:
+
+```sh
+npx @reqvire-org/ads init --framework react
+npm install
+npm run build
+```
+
+Use `--framework preact` for native Preact. A saved `framework` in
+`ds.config.json` lets later init runs omit the flag; otherwise the choice is
+required, including for an older config. Init preserves existing framework
+tooling and rejects conflicting saved/JSX settings instead of converting it.
+
+Use the confirmed package name/version if different. For an existing Bun
+project, the same init command detects `packageManager` or `bun.lock`/`bun.lockb`;
+then use `bun install` and `bun run build`. Node 22.12 or newer remains required.
+Only use `--package-manager bun` when the project has no Bun marker yet or needs
+an explicit override. Preserve its existing package-manager policy and lockfile.
+
+`init` accepts no directory argument and requires an existing `package.json`.
+For starting from zero, copy the bundled `ads-designer` application scaffold
+first, then run init inside it. For an existing app, init preserves app files,
+framework configuration, lockfiles, and build scripts. It adds only missing ADS
+foundation files, config, development dependencies, and build checks. Existing
+ADS values are reused; incomplete contracts need an explicit migration.
+
+Init adds `lint:ds` and `assets:ds`, and runs checks then brand generation before
+the existing `prebuild` hook without replacing the actual build command or
+unrelated checks. It rejects conflicting custom scripts before writing.
+It does not configure framework aliases, style
+extraction, or application entry points; integrate these using the target's
+framework and ADS contracts. Install dependencies, review the changes, and
+commit the updated lockfile.
+
+## Local checkout testing
+
+If no published distribution exists, build and pack the tooling checkout with
+`npm run build` and `npm run pack:tool`. Resolve its tarball to an absolute path.
+From inside an existing test project:
+
+```sh
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+npx --yes --package "$ads_tool_package" ads --help
+npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
+npm install
+npm run build
+```
+
+Use Bun's install/build commands for Bun projects. Keep npx options before
+`ds`. `--tool-package` is optional local-testing/version-override support;
+registry users do not need an archive. A `file:` dependency must remain
+available wherever dependencies are installed. A published pinned version is
+portable between machines.
+
+## Checks and rules
+
+For an initialized project, from its root:
+
+```sh
+npx @reqvire-org/ads check
+npx @reqvire-org/ads tokens --json
+npx @reqvire-org/ads assets
+```
+
+Use the selected real distribution; for a local tarball, invoke
+`npx --yes --package "$ads_tool_package" ads check` instead. Other inspection
+commands accept a directory; init deliberately does not.
+
+Every normal build refreshes `.ds/oxlintrc.json`, runs `ads check`, executes
+core/project Oxlint rules, then generates configured standard brand icons in
+`.ds/assets/`. Set `assets.iconSource` to an SVG inside the ADS's `assets/brand/`,
+relative to the ADS folder; no source means generation is a no-op. Integrate that
+directory through the app's existing asset mount. Fixed token names and prefixes
+are required; project values and artwork remain project-owned. Its paths reference the project and local tool;
+builds do not depend on the initializing npx cache. Ignore `.ds/`. Register
+component rules through the project's plugin adapter and `ds.config.json`, then
+run its actual build. Use `lint-config` directly for custom pipeline integration
+or debugging, not as a separate routine setup step.
+
+Use ADS 0.3 or later for the shared-resource preview compiler. `mcp` starts stdio
+plus its local website; `showcase` starts the browser-only MCP runtime. Open the existing runtime URL from `ads_status` when
+connected; otherwise use `npm run dev:showcase` or the installed `ads showcase`.
+The tool client discovers entries and renders MCP Apps. Init adds the launch
+script but does not install the project preview compiler. Integrate its graph
+compiler/mount adapter and configure `mcp.previewManifest` plus `mcp.previewWatch`;
+then use the same foundation and Linaria extraction as the application. Source discovery,
+selected component/pattern/style/brand imports, explicit theme-value imports, and
+assimilation are agent workflows. There is no CLI `import` command. Core checks
+do not copy source, import values, or establish behavior/motion parity; continue
+project type checking, meaningful tests, and browser comparisons.
+
+If no CLI distribution is available, continue with the target's existing
+checks. `ads-designer` includes an empty scaffold for offline bootstrapping.
+Install skills separately with `npx skills`; the tool does not install skills
+or fetch an external UI catalogue.

package/dist/skills/ads-assimilate/references/lint-and-docs.md

@@ -0,0 +1,87 @@
+# Component-local documentation and lint rules
+
+## Documentation ownership
+
+Make a README in the component's existing feature directory the detailed guide.
+An existing native Toast project may use
+`design-system/components/core/toast/README.md`, beside its state/geometry
+helpers and usage rules; `Toast.tsx` and `Toaster.tsx` remain in the parent directory.
+Follow the target's existing structure rather than moving runtime files solely
+for colocation. This path is a project layout example, not a bundled component;
+discover the actual implementation and guide in the destination.
+
+The local guide should explain the public entry, a working quick start, props/API,
+supported states, lifecycle, interactions, focus, motion, responsive behavior,
+token hooks, and any agreed differences from the identified reference. Include
+how to run relevant tests and browser comparisons, migration guidance when needed,
+and the limits of any lint enforcement. Keep examples on the public API.
+
+Include a References and credits section in that local README. Link the original
+library, relevant implementation/CSS, official usage guidance, and influential
+articles actually used. State the reference version or commit, name the original
+authors, and identify the influenced behavior, layout, or motion. Explain agreed
+differences so the result's closeness to the reference can be assessed. Preserve
+applicable license notices when implementation or assets are copied/adapted.
+
+The receiving project's main README owns discovery/quick start and a short
+upstream inspiration credit. Its project ADS guide (often `ADS.md`) owns shared
+architecture, token and CSS ownership, central enforcement, and links to component
+guides. Keep those implementation details out of core tooling docs. Avoid copying
+the complete component contract into both. Update a project usage skill to route
+to the local guide if one exists.
+Validate relative file links and anchors after moving documentation.
+
+## Decide whether a rule is useful
+
+Add a rule only when there is a concrete misuse, a stable policy, and an AST or
+other deterministic check that can establish the violation. Prefer existing
+TypeScript, import restrictions, token/CSS guards, or documented review guidance
+when they already cover it. A component does not automatically require custom lint.
+
+Examples from Toast are direct calls during React rendering or in server modules,
+effects that create notifications without inspectable stable IDs, and repeated
+or conditional host mounts within an approved root file. These are examples;
+do not apply host/ID policies to components that do not need them.
+
+Do not encode subjective copy, useful duration, placement preference, inferred
+data flow, or application-wide singleton claims in a syntactic rule. Where spreads,
+dynamic values, wrappers, or cross-module behavior defeat proof, document the
+limit rather than reporting an invented conclusion.
+
+## Colocate ownership, register centrally
+
+For an Oxlint-based target, use a tooling-only file such as
+`<component>/<component>.oxlint.mjs`. Export its rule map and let the central
+plugin import it. Register the adapter's namespace/path and rule settings under
+`oxlint.plugins` and `oxlint.rules` in `ds.config.json`. `lint:ds` generates ignored
+`.ds/oxlintrc.json` before running core and registered usage rules. Do not maintain
+another adherence generator or edit generated configuration. Use scoped
+`oxlint.overrides` for justified file-specific settings; they do not disable
+independent architecture checks. Renderer properties and documented non-state
+hooks use explicit `boundaries`, with accepted/rejected cases and local guidance.
+
+Keep tooling modules out of the runtime public barrel and application bundles.
+Core tooling must work without a particular external component. Register its
+local rules through project configuration or an adapter; do not add a hardcoded
+catalogue import to the ADS tool itself.
+Namespace rules consistently and give diagnostics that explain the correction.
+Expose real app-specific configuration, such as root file paths or public import
+sources, without weakening the checks for the intended target.
+
+Recognize imported aliases and namespace imports with scope resolution. Respect
+shadowed local names and unrelated libraries; matching identifier text alone is
+not sufficient. Inspect available AST information before deciding what a rule
+can prove. Handle valid dynamic patterns conservatively.
+
+## Test and document enforcement
+
+Test accepted and rejected consumer snippets through the lint framework, covering
+the real violation and false-positive boundaries: import aliases/namespaces,
+shadowing, unrelated imports, event handlers/effects, relevant nesting, dynamic
+options, and configuration. Choose cases that exercise the rule's actual policy.
+
+Run the normal generated configuration on the source tree as well as isolated
+rule tests; registration errors can pass unit tests. Update package scripts only
+when needed to run the new checks. Document rule names, remediation, configuration,
+and statically unprovable cases in the component README. Keep shared import/token
+ownership rules in shared docs and tooling.

package/dist/skills/ads-assimilate/references/native-implementation.md

@@ -0,0 +1,98 @@
+# Research and native implementation
+
+## Inspect the reference before designing the replacement
+
+Follow the supplied link to the component implementation and its official docs.
+Find the state store/hooks, markup, CSS, motion constants, geometry measurement,
+input handlers, accessibility semantics, examples, and tests. Read an upstream
+usage skill when available as component guidance; installation of that skill is
+not required to read it. Identify the exact package version or source revision
+used for the running reference.
+
+Trace behavior through both code and the browser. CSS duration does not prove
+how long an element stays mounted. A visibility limit may hide records without
+pausing their timers. Focus and hover may drive different states. Separate these
+observations from the behavior you would prefer to implement.
+
+Use a small contract table during work:
+
+| Concern | Original observation | Native requirement | Verification |
+|---------|----------------------|--------------------|--------------|
+| States | Defaults, active/loading/error, disabled | Supported states and transitions | Trigger each public path |
+| Layout | Dimensions, gap, natural height, overflow | Measured/token mapping | Computed styles and rectangles |
+| Lifecycle | Updates, expiry, removal, route teardown | Observable timing and callbacks | Timed state assertions |
+| Input | Pointer/touch, keys, focus targets | Same behavior or user-agreed change | Real input plus active-element checks |
+| Motion | Entry/exit, interruption, transform origin | Duration, easing, trajectory | Transition events and sampled frames |
+
+This is a working aid, not a required standalone report. Keep settled public
+contracts in the component guide and executable evidence in appropriate tests.
+
+## Map into the target system
+
+Use existing primitives for icons, buttons, spinners, surfaces, and typography.
+Map dimensions, colors, radii, shadows, durations, easing, and layering to tokens.
+Add a narrowly named token only when the existing vocabulary cannot express the
+required behavior; preserve unrelated token contracts.
+
+Keep the result close to the reference's function, layout, interaction, and
+motion. Native integration should not become a redesign. Account for each
+material difference with a user requirement or an agreed target-system tradeoff;
+compare again after token/primitive substitutions to detect accidental drift.
+
+Keep the reference's state machine and motion choreography distinct from the
+native skin. Typography and controls can change wrapping and natural height,
+which changes expanded geometry. Placement of a close control and its focus or
+click behavior are UX decisions, even when the control uses a native button.
+
+Use required Linaria extraction for component/pattern styles and preserve the
+target framework. With the default root ADS layout:
+
+- Component markup and Linaria styles live under `design-system/components/`.
+- Public exports belong in `design-system/index.ts`; consumers use the barrel.
+- Shared layout patterns belong under `patterns/`, not in app containers.
+- Appearance uses semantic tokens; consumers do not target `.ads-*` internals.
+- A needed measured-geometry boundary may write only allowlisted computed
+  dimensions, positions, or transforms. Document and constrain the exception in
+  the shared architecture guard; never broaden it to arbitrary visual styles.
+
+Use current repository conventions in another target rather than assuming the
+same framework, directory structure, or lint tooling.
+
+## Implement lifecycle and motion together
+
+Keep model/store state independent of the rendered list where practical. For
+stateful components, consider stable subscriptions, SSR snapshots, scope teardown,
+same-ID updates, stale async results, and callbacks that fire once. Only implement
+the mechanisms the component actually requires.
+
+Measure natural dimensions before applying constrained or collapsed layouts.
+Observe relevant content/font/size changes. Give CSS transitions a rendered
+initial state; otherwise the browser may skip entry. Let interrupted transitions
+retarget from the current visual state. During direct dragging, suppress easing
+and use the correct pointer-capture and cancellation lifecycle.
+
+Match threshold, velocity, axis locking, wrong-direction resistance, dismissal,
+and cleanup behavior independently. Do not assume a matching final transform
+proves a matching gesture. Verify hover gaps, expanded hit areas, focus changes,
+and interactions with buttons or selectable text when applicable.
+
+For async status changes, compare both incoming and outgoing visual layers.
+In the Toast example, the status icon enters over 300 ms while the loader fades
+and shrinks over 200 ms. Replacing the loader immediately loses half the motion.
+These values are reference-specific examples, not defaults for every component.
+
+## Integration and provenance
+
+Use the real native component in showcase/playground pages. Export changes before
+migrating consumers. Replace only the surfaces covered by the request: transient
+notifications and persistent inline feedback can have different purposes.
+
+Keep a reference package in a temporary comparison project when needed. Preserve
+its license files and identify its version. Record whether production code was
+independently authored or copied/adapted. Preserve notices required by the actual
+license for copied/adapted code or assets; tokenizing or changing frameworks does
+not by itself establish independent authorship. Credit inspiration in the main
+README and in a References and credits section in the component-local README.
+Link the library and the actual source/docs/articles studied, identify the
+version or commit, name the authors, and explain the concrete influences.
+Document material adaptations and agreed deviations beside the public contract.

package/dist/skills/ads-assimilate/references/testing.md

@@ -0,0 +1,107 @@
+# Testing and reference comparison
+
+## Use the real reference
+
+Run the published upstream component or an identified upstream source revision
+in its own page. Label it with library/version. Keep its component CSS intact for
+the baseline. The page frame may use native controls, but those controls must
+trigger the original component and store. Two pages importing the native component
+cannot establish upstream parity.
+
+Use identical messages, options, counts, async delays/outcomes, action payloads,
+and viewport/input settings. Align configuration explicitly rather than relying
+on two different defaults. Compare brand/token differences separately from UX
+requirements. For geometric motion, normalize trajectory by actual card size
+where native typography intentionally changes height.
+
+A playground built from `dist` is a snapshot. Rebuild the local ADS and playground
+after changes, verify its asset/version inputs, and reload before comparing.
+Check the main showcase too so a working isolated fixture does not conceal a
+mounting, routing, CSS-entry, or scope integration problem.
+
+## Select tests by observable risk
+
+Use the cases relevant to the component, not a universal checklist:
+
+| Area | Useful observations |
+|------|---------------------|
+| Model/lifecycle | Stable snapshots, updates, expiry, callback counts, stale async results, unmount cleanup |
+| Layout | Natural and constrained dimensions, variable content, overflow, resize, font loading, position changes |
+| Input | Mouse and touch separately, outward/inward drag, cancellation, threshold/flick boundary, controls inside the surface |
+| Keyboard | Actual focused element before/after hotkeys, Escape, Tab order, focus loss or route changes |
+| Motion | Entry/exit paths, easing, duration, scale/opacity, rapid interruption, status crossfade, DOM removal time |
+| Environment | Supported mobile widths, light/dark, reduced motion, document visibility, supported SSR behavior |
+| Consumer integration | Public imports, one-time CSS setup, mounted provider/host, route persistence, scoped instances |
+
+Toast-specific high-value cases include hidden overflow cards' lifetime, compact
+versus hover-expanded geometry, promise settlement using the same ID, close/action
+clicks, `preventDefault()` actions, and loader-to-status motion. Timer expiry,
+exit animation, and DOM removal are distinct observations.
+
+For deterministic stores and async races, unit tests can validate behavior without
+a browser. Use browser tests for geometry, transitions, pointer capture, focus,
+and real control activation. Test a reproduced failure or lifecycle invariant;
+avoid tests that merely mirror JSX, CSS strings, or documentation wording.
+
+## Browser isolation and measurements
+
+Use an independent browser context for comparisons. Do not resize, emulate,
+navigate, or close the user's existing tabs. With a public Playwright browser
+object, a typical ownership pattern is:
+
+```js
+const comparison = await browser.newContext({
+  viewport: { width: 1440, height: 1000 },
+  colorScheme: "light",
+  reducedMotion: "no-preference",
+});
+try {
+  const nativePage = await comparison.newPage();
+  const referencePage = await comparison.newPage();
+  // Navigate, exercise real controls, and collect matching observations.
+} finally {
+  await comparison.close();
+}
+```
+
+Use the browser automation tools available in the environment and follow their
+interaction/snapshot requirements. Use the same isolation principle with other
+browser tooling. Bring the page under test to the foreground for visibility-
+sensitive timers; an inactive page may deliberately pause. Wait for fonts before
+measuring text or dimensions. Use mobile/touch contexts for touch gestures;
+mouse drags alone do not validate touch behavior.
+
+Collect `getBoundingClientRect()` and computed styles for size, padding, gap,
+radius, shadow, font metrics, placement, transform, opacity, transition duration,
+and easing. Observe `transitionrun`/`transitionend` or animation events and sample
+`requestAnimationFrame` around the trigger. Align traces to the actual animation
+start, not tool-call start. Use a mutation observer or lifecycle callback to
+measure exit-state and removal timestamps. Timing assertions should allow normal
+browser scheduling tolerance.
+
+Inspect screenshots of settled states and intermediate/problem states. Pixel
+equality is not expected when the native skin intentionally differs. A computed
+duration of 400 ms does not prove a 400 ms visible exit if the DOM disappears at
+200 ms. Reduced motion can set animation names to `none` while a reset still
+reports a tiny nonzero duration; assert effective motion behavior.
+
+## Required checks and evidence
+
+Run the target's existing lint/typecheck/build pipeline plus meaningful component
+and rule tests. A native Toast project might provide:
+
+```sh
+npm run test:toast  # Toast store/promise and usage-rule checks
+npm run build       # Lint, type checking, public-entry and showcase builds
+```
+
+Discover the target's actual scripts; the commands above are not guaranteed by
+the empty scaffold or ADS tool. For another component, use its actual test entry;
+do not run Toast tests as a substitute. Once checks pass, rerun only when changes
+or unresolved observations justify it. Save browser artifacts in the repository's existing ignored location
+(for example `output/playwright/`) or an isolated temporary directory.
+
+Report matches and differences with their evidence and reference version. Distinguish
+observed behavior, source inference, and untested cases. Give full native/reference
+playground URLs when they exist. Do not report a static server as running without
+checking it, or call screenshots proof of full animation/behavior parity.

package/dist/skills/ads-break-ui/LICENSE.upstream

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emil Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/skills/ads-break-ui/README.md

@@ -0,0 +1,16 @@
+# Credits
+
+Adapted from Emil Kowalski's
+[break-ui skill](https://github.com/emilkowalski/skills/tree/2d228630ba1446365f614a108cb8252f1feda202/skills/break-ui),
+revision `2d228630ba1446365f614a108cb8252f1feda202`.
+
+The fixture catalogue in [references/catalog.md](references/catalog.md) copies
+upstream `CATALOG.md`, with its opening instruction adapted to local field discovery.
+The workflow retains its worst-case
+data, reproducible fixtures, severity reporting, and optional fix approach,
+adapted for local ADS public APIs, token ownership, and project checks.
+
+[LICENSE.upstream](LICENSE.upstream) preserves the full upstream MIT license
+and Copyright (c) 2026 Emil Kowalski. Retain it when redistributing this skill
+or its copied/adapted material. These terms identify upstream material; they
+do not declare a license for unrelated project source.