# Changelog

## 0.6.0

Your team's rules in CI, and design tokens out. Existing captures, comparisons and exports keep their bytes. The record
kinds OODS Foundry pins (run_manifest 1.8.0, a11y_report 3.0.0, drift_report 2.0.0, style_fingerprint 1.4.0) are
unchanged; new and changed kinds are listed at the end.

- Add `stage1 diff <run-dir> --write-baseline <file>` and `--baseline <file>`.
  - Record a run's findings as a baseline, then list a later run's new, resolved and changed findings, with no totals.
  - A run is compared only when its pins match: Stage1, drift-report and Lighthouse versions, routes, measured pages,
    sampling and design inputs. Otherwise every differing pin is named and the command exits 2.
- Add `.stage1/rules.yaml` and `stage1 check`.
  - The rules file names the families your product counts. Rules select findings by identity, with `when: present` or
    `new` and `block`. It can also set a policy for new unexplained drift and give dated waivers.
  - Exits 0 when no blocking rule failed, 1 when one did, 2 when the check could not be made.
  - Thresholds, counts, ratios, scores and severity are refused by name: rules block on findings, never on a number.
- Document a GitHub Actions recipe that captures declared pages on each pull request, compares them with your tokens and
  runs your rules. It is proven end to end on a public USWDS route set.
  - `stage1 browser setup --with-deps` installs Chromium's system libraries on Linux.
- Every command writes only its result to stdout and its progress to stderr, so CI can read the JSON. The guided
  session's dialogue stays on stdout. The shipped binary keeps `diff`'s and `check`'s exit codes.
- MCP changes:
  - Add `stage1_list_analyses`.
  - `stage1_get_artifact` reads analyses too. An RFC 6901 `pointer` selects a subtree, and a `maxChars` cap refuses an
    oversize response with `OVER_CAP` instead of cutting it.
  - Add `stage1_check`, which runs the same engine and writes the same report bytes as the CLI.
  - Failures carry named codes: `UNKNOWN_ID`, `OUTSIDE_ROOT`, `OVER_CAP`, `BAD_POINTER`, `ATTESTATION_MISMATCH` and
    `INVALID_INPUT`.
- Add `stage1 dtcg-export`, which writes DTCG 2025.10 token sets and a Resolver.
  - Sources: a `.fig` extraction (`--fig-tokens`), a CSS/SCSS reading (`--design-tokens`), or a capture's
    effective-root custom properties and declared `.dark` blocks (`--run`).
  - Each export is read back with Stage1's own reader and kept only when every value and alias matches.
  - What DTCG cannot hold is listed with its reason in the `dtcg_export` receipt.
- `.fig` extraction resolves aliases mode by mode: an alias into another collection uses that collection's default mode,
  with its basis recorded. It also records declared variable scopes, collections, and soft-deleted variables and styles
  (`fig_local_tokens` 1.6.0).
- DTCG Resolver tokens are filed under the set or modifier that defines them (`design_source_tokens` 1.2.0).
  Resolution is bounded per context (100,000 steps, at most 100 contexts), so a full USWDS export reads back.
- `declared_components` 1.3.0 records the main document's `data-oods-*` attributes, and every `data-slot` value inside
  and outside the regions a page names as demos. #/components shows both.
  - A page without retained DOM makes this census not measured, never zero.
- New kinds: check_baseline 1.0.0, check_report 1.0.0 and dtcg_export 1.0.0.
- Changed kinds: fig_local_tokens 1.6.0, design_source_tokens 1.2.0, declared_components 1.3.0 and the web view model
  3.1.0.

## 0.5.1

A patch release. No output schema version changes: 0.5.1 writes the same record versions as 0.5.0.

- Label DTCG 2025.10 token files as `dtcg` when their dimensions are `{value, unit}` objects. 0.5.0 labelled
  such files `tokens-studio` (all nine public samples with that form) and then read every token in them with
  Tokens Studio's lenient grammar. Labels change for affected files; the values of valid tokens do not. A unitless
  DTCG dimension such as `"$value": 4` is no longer accepted as 4px: it stays unresolved with its reason. Tokens Studio
  files keep their own grammar.
- Token guesses on a computed-style record without its tag now fail with a named reason instead of a TypeError.
- Add the npm homepage https://aquex.ai/products/stage1 and the MCP Registry name `ai.aquex/stage1`. The registry entry
  launches `npx -y --package @aquex/stage1@0.5.1 stage1-mcp --out <absolute-directory>`.

## 0.5.0

Conformance ratios change again: modern colour values enter the comparison, conversion matches
are explained separately, inset strokes use border-role rules, declared font-relative lengths such as `ex` are explained,
and new captures count all four border sides. Exact conformance stays exact. The 0.4.0 and 0.5.0 reports are different measurements;
existing captures, comparisons and exports keep their original bytes.

- Read CSS Color 4 values in text, backgrounds, borders, shadows and design sources, and show
  modern colour swatches. Explain colours that convert to the same fixed 8-bit value as
  `normalized_color`; never turn conversion or gamut clipping into exact conformance. Record
  culori 4.0.2 as the converter and keep exact and normalized mode coverage separate.
  Numeric CSS equality applies even with the legacy `case_sensitive` option: hex letter case
  cannot create colour drift. Alpha exclusions remain visible on both sides.
- Read custom properties inside layers, conditions, imports, nested rules and open shadow roots.
  Keep declaration conditions and sheet provenance, record root values in effect, count unreadable
  sheets/imports, and retain matched variable names. Older summary-only runs need recapture.
- Judge spread-only inset shadows as strokes within the shadow family, keeping geometry visible;
  drop and count transparent zero-geometry placeholder layers. Explain declared ex/ch/cap/lh/ic
  lengths without fitting, and omit ratios for unjudged comparisons.
- Capture all four border sides and their winning origins. Older retained records remain top-only.
  Stop ordinary runs showing the guided-only network limitation note.
- Exclude identifiable component demos from IA and implied-object analysis. Attribute third-party
  component and state-rule counts separately. Token guesses keep observed values and site-declared
  names, without invented primary/secondary/surface roles.
- Remove Stage1-made scores and confidence fields from newly produced public artifacts and manifest
  echoes, including the weighted accessibility score, token confidence and density/prominence scores.
  Preserve axe's tool-native facts and Lighthouse's raw reports. Drift severity fields stay in JSON
  for OODS Foundry's object contract, but leave Stage1's views and exported view model.
- Upgrade Lighthouse to 13.5.0, puppeteer-core to 25.12.0 and the MCP SDK to 1.31.0, without overrides. List failing
  Lighthouse insights beside classic opportunities; remove copied performance scores and budget
  ratings. Raise the supported Node floor to `^22.19.0 || ^24.0.0`. Fresh-install audit and browser
  qualification use the candidate's exact archive bytes; dependency inventories belong to each install.
- On explicit resume of a verified incomplete suite, remove abandoned atomic root-manifest writes
  left by a killed process. Retain completed targets and refuse symbolic links or attested files.
- Read DTCG 2025.10, Resolver, Tokens Studio and Figma per-mode token exports as design comparands,
  preserving modes, collections, declared types, aliases and JSON-pointer provenance. Label
  non-strict grammar and constant arithmetic; unresolved expressions carry reasons.
- Add the declared public subject shadcn-ui, compared against its own light theme with MIT attribution.
  Read @theme declarations and derived constant radius calculations; disclose generative spacing
  and iframe coverage limits. USWDS and shadcn/ui are the declared public examples; shadcn's supplied theme does not enumerate spacing or typography scales.
- New output versions include run_manifest 1.8.0, a11y_report 3.0.0, drift_report 2.0.0,
  style_fingerprint 1.4.0, perf kinds 2.0.0, design_source_tokens 1.1.0 and web view model 3.0.0.
  Until OODS Foundry admits the new versions, use Stage1's own views for 0.5.0 output.

## 0.4.0

Conformance numbers change because this release compares raw values, samples computed styles at full depth by default, and separates explained values from drift. Conformant still means an exact token match. Existing captures, comparisons and exports keep their original bytes and meaning.

- Make computed-style depth its own option: `--sampling compact|full` on app, surface and suite capture, and MCP `sampling`. The default is `full`; a suite cannot resume at a different depth. `--keep-evidence` now only decides retention. Screenshots remain viewport JPEGs, axe evidence remains summarized, and the HAR records response sizes regardless of that flag.
- Record the capturing Stage1 version, release/dev build stage and sampling depth in run_manifest 1.7.0. Analyses record their analysing version separately. Every pass that loads or replays a page records its browser build and colour scheme. Older runs show facts they did not record as unavailable.
- Compare each raw value, with type sizes separated by typeface. Rounded clusters remain available for display but no longer determine the comparison. Re-comparison checks retained computed-style evidence against the capture's hashes before recomputing; missing evidence falls back to explicitly labelled historical cluster medians.
- Carry up to five examples on every value-drift finding produced from retained computed styles: page, selector, property and evidence record. Finding details and static exports retain those examples; ambiguous selectors are labelled.
- Replay saved pages with their scripts inert, so an inline loading script cannot undo the captured state while external scripts are blocked. Record replay policy and sampling coverage, and sample painted elements first within each group's caps.
- Separate values on elements not painted at the capture width and state. Keep their reasons and examples visible; closed dialogs, hidden navigation and clipped controls are neither conformant nor drift in that state.
- Separate browser-supplied values using the capture browser's winning style origin, including inherited values and CSS initial values. Record control state and browser build. This also removes browser defaults that previously inflated exact-match counts.
- Attribute subtrees inserted by third-party scripts and frames to their hosts. Show their values apart from the site's authored values. A form-action host alone never establishes attribution, and the site's own widget launcher remains first-party. Category precedence is not painted, then third party, then browser default.
- Explain palette colours that lack a border-role token, negated spacing tokens, and font-relative spacing. Each explanation retains examples and never raises conformance. Border and spacing token eligibility is stated in the report; widths and breakpoints no longer qualify as spacing tokens. `calc()` is explained only from declared text, never from fitted arithmetic.
- Populate Figma variable collections and alias-target collections in fig_local_tokens 1.5.0. Colour coverage separates palettes from themed collections, reports every mode, and names the mode or tied modes explaining the most compared occurrences among distinguishing tokens. Unexplained colours remain visible; a best-covered mode is not a clean-build claim.
- Compare type against the kit's declared per-typeface size modes, falling back to its text styles. Exact matches remain conformant; differences within the fixed 0.16px rounding step are explained as normalized type. Repeatable `redrift --type-factor 'Family=1.06'` and MCP `typeFactors` accept explicit factors for faces without a declared mode. No factor is fitted; a face without a comparand remains unjudged.
- These measurements use style_fingerprint 1.3.0 and drift_report 1.4.0. New comparison categories, counts, explanations, mode coverage and typeface records appear in the local viewer and static export. Capture-time facts absent from an older run say “not recorded on this run.”
- Public MCP app, surface and suite tools return `CAPTURE_REFUSED` with a safe validation reason before creating a job for invalid targets or repositories. Refusals do not echo the target or credentials.
- Start local browser ownership tracking before launch, closing the host-kill window before browser registration. Browser exit also releases log pipes inherited by updater or crash-reporting helpers, preventing an indefinite shutdown wait. Other hosts and released sessions remain untouched; Windows remains unverified.

## 0.3.2

- Refuse single-site target URLs with embedded credentials before capture logging or evidence writes, matching guided and suite capture; refuse exports containing credential-bearing URLs from older runs.
- Use the Chromium revision installed by `stage1 browser setup` for Lighthouse when local Chrome is absent.
- Add `stage1-mcp --version` and show usage for invalid MCP startup arguments.
- Distinguish missing and partially recorded page descriptions from unique descriptions in the overview.
- Refresh the published guide with section navigation, local-server/device examples and troubleshooting; remove pre-publication and private-workspace test instructions.
- Update the public Axios, MCP SDK, UUID and YAML pins within their existing major versions to address dependency advisories. Lighthouse's older transitive dependency advisories still require separate qualification.
- Build the API/core/web dependency chain before the maintainer test gate's core lane so a fresh checkout does not depend on leftover build output.
- Refuse exports carrying a credential-bearing URL whose slashes are backslash-escaped, as captured CSS or inline JSON can hold them.
- State title coverage beside description coverage in the overview ("Titles were recorded on N of M pages").
- A capture browser no longer outlives a CLI or MCP server that is hard-killed or crashes: it is stopped with its host, and its temporary profile is removed.
- Name stage1@aquex.ai as the support address in the guide and in the package's `bugs` field.

## 0.3.1

- Clean up the local Chrome process owned by a failed Lighthouse launch, preserving unrelated browser sessions.
- Exclude navigation toggles from links and prefer a page’s own navigation label when naming routes.
- Read Lighthouse 13 insight diagnostics in Quality while preserving older-report rendering and naming missing measurements. The bundled Lighthouse remains 12.8.2.
- Advance capture manifests to schema 1.6.0 for optional internal evidence-bucket declarations; public captures omit the private declaration.
- Wait for matching registry metadata after publication and retain bounded installation diagnostics when a command times out.

Existing captures remain unchanged. Supported-platform claims are unchanged; Windows and macOS 14 Intel remain unverified.

## 0.3.0

Add public multi-site capture and URL-list discovery through both the CLI and persisted MCP jobs.

- Strict per-target configs reuse public capture defaults and credential references. Discovery records robots, redirects, duplicates and exclusions. Robots overrides require a reason on the individual target.
- Suites retain ordinary target runs and a durable queue, including failed and unscanned targets. Shared output-root ownership prevents concurrent CLI/MCP writers. Explicit resume verifies configuration, identities and every recorded file before retaining successful targets.
- The suite screen compares measured style values, literal structure/API presence, facet spelling groups, JSON-LD and separate accessibility violations/review states. Coverage and missing inputs remain visible; no quality or similarity scores are added.
- Approved static exports include suite and target screens. Every target needs its own public-subject declaration; authenticated targets need additional approval. Source runs remain unchanged.
- Refresh the public CLI reference and installed-package proofs, including cancellation, interruption, root confinement, lease contention and restart/resume.

## 0.2.0

Extend single-site inspection with guided browser sessions, bounded API and source-repository evidence, and a broader design comparison. Every new capture path is available through both the CLI and MCP; the local UI and approved offline exports show its recorded evidence and limits.

- Guided sessions retain labelled states at the same URL, live accessibility results, session bounds and interruption provenance. Saved login state is explicit and excluded from exports. Authenticated sharing requires its own run-bound declaration.
- API inspection reads OpenAPI/Swagger declarations or GraphQL introspection before optional bounded probes. Credentials come from environment/file references, are restricted to the declared origin and are redacted before persistence. The API view shows declarations, entities, authentication and unresolved references.
- Local repository inspection reports bounded source markers, routes, component declarations, dependencies and token counts without executing the tree or storing its absolute root.
- Design comparison adds spacing, border colour, shadow and font weight; declared component-family presence; Figma REST library/variants/metadata/annotations with an environment-only token; and local CSS/SCSS declarations with alias, unit and unresolved-expression provenance. Comparands stay separate and every value signal names its source.
- Scope/rate-limit failures and partial Figma measurements remain visible. Native annotations stay separate from naming hints. Missing measurements never become measured zero; views show no confidence or design-quality score.

Existing captures remain unchanged. Multi-site suite production and internal maintenance producers remain excluded. Node 22.15+/24 and the established Ubuntu 22.04/24.04 x64, macOS 14 ARM64 and macOS 15 Intel qualification scope are retained; Windows and macOS 14 Intel remain unverified.

## 0.1.1

Clarify inspect help and seeded capture errors, add MCP usage help and a view icon, remove private repository metadata, print extraction paths, and refuse non-empty extraction destinations. Document the currently available value comparison. Complete the internal document census and remove retired private registrations while retaining historical readers.

## 0.1.0

First standalone Stage1 Inspector distribution: CLI, stdio MCP server and local browser UI under Apache-2.0.

- Bounded local single-site app/surface capture, with explicit own-account remote browsing.
- Durable MCP capture jobs, responsive status/cancel, explicit output root and interrupted-job recovery.
- Attested run views and separate local .fig comparisons; original capture bytes stay unchanged.
- Run-bound sharing approval and fresh offline exports with withheld evidence and redaction disclosures.
- Pinned Apache-licensed Forge UI components and bundled third-party notices.
- Independent five-page Lighthouse sample, preserving existing root-then-route selection.

API inspection and guided journeys are priority follow-ups. Multi-site capture and internal producer/maintenance commands are not public in this release. Historical reader support does not enable those producers. Node 22.15+/24 required. Verified platforms: Ubuntu 22.04/24.04 x64, macOS 14 ARM64 and macOS 15 Intel. Windows and macOS 14 Intel remain unverified for 0.1.0.