diff --git a/.gitignore b/.gitignore index 0bcd5bc7..fc5b83c6 100644 --- a/.gitignore +++ b/.gitignore @@ -23,3 +23,4 @@ dist/ # full-api demo validator scratch demos/.validate/ +demos/.audit/ diff --git a/reports/full-api-audit/REPORT.md b/reports/full-api-audit/REPORT.md new file mode 100644 index 00000000..1a0a9782 --- /dev/null +++ b/reports/full-api-audit/REPORT.md @@ -0,0 +1,185 @@ +# SLASHED Full-API Testing Operation — Report + +**Framework:** SLASHED v0.6.25 · **Date:** 2026-06-30 +**Surface tested:** 691 tokens + 239 classes (930 API elements) +**Method:** local build (`npm run build`) + configurator dev server, driven with +Playwright/Chromium; computed values diffed against the source-of-truth oracle +`docs/api-index.json`. Harness scripts live alongside this report in +`reports/full-api-audit/` and are re-runnable. + +--- + +## 1. Executive summary + +| Ground | Scope | Result | +|--------|-------|--------| +| **1 — Correctness** (demos + framework) | 691 tokens, 239 classes, 225 knobs, dark mode, visuals | **PASS** — no framework functional defects. 4 demo/framework polish findings (F1–F4), all low/medium. | +| **2 — Configurator fidelity** | control coverage + live override + preview reflection | **PASS** — every editable knob reachable and overridable; previews reflect changes; 59/59 configurator unit+component tests green. | + +**Headline numbers** + +- Tokens: **691/691** rendered, **0** console errors, **683/691** resolve at `:root` (the 8 "empty" are fully explained below — none is a framework bug). Demo's displayed value matched the independently-read computed value for **691/691** tokens (0 misreports). Aliases: **0** mismatches. Dark mode re-resolves **272** tokens. +- Classes: **239/239** rendered, **238/239** ship in the loaded bundle, **69/69** behavioural contracts pass, **0** console errors. +- Override wiring (overrides demo): **202/202** perturbed knobs move; the **23** non-perturbed knobs exactly equal the **23** documented skips (0 undocumented); **460/466** consumption tokens recompute downstream. +- Configurator: **224/224** editable PUBLIC knobs reachable as controls; **8/8** power knobs (`knobs-report.json`) and **5/5** sampled generic rows (`configurator-report.json`) inject overrides *and* update the live preview; preset + reset work (`preset-reset-report.json`); **59/59** configurator unit+component tests pass (`results/configurator-unit-tests.txt`). + +**Verdict:** The two demo pages are accurate, faithful reflections of the +framework, and the framework itself behaves correctly. The configurator +correctly implements the full token surface and every control overrides the +live preview as intended. Findings are limited to demo-packaging polish (F1, F2, +F4) and one framework design question (F3). + +--- + +## 2. Ground 1 — correctness + +### 2.1 Tokens (`check-tokens.mjs`) + +All 691 tokens render with a live value tile; the demo's `getComputedStyle` +readout matches an independent read for every token (no misreporting). 272 +tokens change under `data-theme="dark"`, confirming the dark-mode engine. + +**The 8 tokens that read empty at `:root`:** + +| Tokens | Why | Classification | +|--------|-----|----------------| +| `--sf-btn-radius`, `--sf-btn-padding-block`, `--sf-btn-padding-inline`, `--sf-field-radius`, `--sf-field-padding-block`, `--sf-field-padding-inline` | Defined in `optional/tokens.components.css`, which the **`optimal`** bundle (loaded by both demos) excludes. They resolve correctly under `full`/`optimal-components` (`var(--sf-radius-m)`, `var(--sf-space-xs)`). | **F1 — demo** (bundle choice). Framework correct. | +| `--sf-color-mark-text`, `--sf-color-selection-text` | Declared `inherit` (fallback-only hooks consumed as `var(--token, MarkText)`); `inherit` resolves empty at `:root` per CSS rules but works contextually. They *do* take a value in the overrides demo, proving wiring. | **F2 — demo** cosmetic. Framework correct. | + +The 2 reported "literal default mismatches" (`--sf-radius-none`, `--sf-space-none`: +declared `0`, computed `0px`) are `@property ` normalization — **not defects**. + +### 2.2 Classes (`check-classes.mjs`) + +239/239 class tiles render. 238/239 selectors are present in the loaded bundle; +the one exception, `theme-transition`, is an example-only class +(`bundles: []`, from `optional/theme-example.css`) — see **F4**. 69 classes +have a strong behavioural contract (state classes, layout displays, a11y); all +**69/69 pass** (e.g. `.is-hidden`→`display:none`, `.sf-grid`→`display:grid`, +`.is-disabled`→`pointer-events:none`+opacity, `.is-truncated`→ellipsis, +`.sr-only`→clipped 1px). Bento *item* span modifiers (`sf-bento-wide` etc.) +correctly compute `display:block` (their effect is grid-span inside a parent). + +### 2.3 Override-wiring proof (`diff-overrides.mjs`) + +Diffing the baseline vs the always-on overrides demo: + +| Check | Result | +|-------|--------| +| Perturbed knobs that moved | **202 / 202** | +| Knobs not perturbed vs documented skips | **23 = 23** (0 undocumented, 0 mismatched) | +| Consumption tokens that recomputed | **460 / 466** | +| Tokens unchanged | 29 = 23 skips + 6 component tokens (F1) | +| Console errors (both demos) | 0 | + +Every configurable token is wired end-to-end; the 23 skips (z-index ladder, +runtime state flags, `env()` insets, sentinel `none`s) are deliberate and +documented in `ultimate-override.css`. + +### 2.4 Visual + +Baseline and overrides demos render as intended (screenshots: +`baseline-desktop.png`, `overrides-desktop.png`; the harness also captures +tablet/mobile widths, omitted here for size). Color ramps, +semantic colors, spacing and type scales are correct; the overrides demo shows +the dramatic, coherent re-skin (serif type, red palette, enlarged scales, +dashed borders) that proves the cascade. + +--- + +## 3. Ground 2 — configurator fidelity + +### 3.1 Coverage (`probe-panels.mjs` + configurator test suite) + +- `catalogue-projection`, `smoke`, `curation` tests pass → the configurator's + `api-index.generated.json` matches the framework (no drift), all 691 tokens + present, every PUBLIC knob has a domain pattern (no orphans). +- **224/224 editable PUBLIC knobs** are reachable as controls. The only knob + not exposed is the **INTERNAL** `--sf-is-dark` (correctly hidden — "do not + override"). 49 derived/alias consumption tokens are intentionally not + individually editable (they recompute from knobs). +- 641 tokens are additionally browsable/editable as generic rows. + +### 3.2 Override application (`check-knobs.mjs`, `check-configurator.mjs`, `check-preset-reset.mjs`) + +Mechanism: a control's `onChange` → `overrides` state → an `$effect` writes the +override CSS into `