@tenphi/tasty 0.0.0-snapshot.fdb16ea → 0.0.0-snapshot.fde6cf3

package/docs/precompile.md

@@ -0,0 +1,202 @@
+# Precompiled Component Catalogs
+
+Precompiled catalogs let a design system render a curated component matrix at
+build time, publish the resulting CSS as a static asset, and teach Tasty which
+classes and ancillary rules that asset already contains. Covered chunks then
+return their existing class names without running the style pipeline or
+inserting CSS. Uncovered runtime styles continue through the normal path.
+
+This mode complements SSR and `tastyStatic()`:
+
+- SSR collects the styles used by one request.
+- `tastyStatic()` extracts explicitly static style calls through a build
+  transform.
+- A precompiled catalog covers the stable runtime `tasty()` styles shared by
+  many applications, while retaining runtime props and overrides.
+
+## Compile a Catalog
+
+`@tenphi/tasty/precompile` is Node-only. Each case returns a React tree; Tasty
+renders it inside the active style collector. The entry requires the optional
+`react` and `react-dom` peers used by the component library.
+
+```tsx
+import { writeFile } from 'node:fs/promises';
+import { precompileTastyStyles } from '@tenphi/tasty/precompile';
+
+import { Button, Dialog } from './index.js';
+
+const artifact = await precompileTastyStyles({
+  id: '@acme/ui',
+  cases: [
+    {
+      id: 'button/default',
+      render: () => <Button>Continue</Button>,
+    },
+    {
+      id: 'button/danger',
+      render: () => <Button variant="danger">Delete</Button>,
+    },
+    {
+      id: 'dialog/default',
+      render: () => (
+        <Dialog open title="Account">
+          Content
+        </Dialog>
+      ),
+    },
+  ],
+});
+
+await Promise.all([
+  writeFile('dist/precompiled.css', artifact.css),
+  writeFile(
+    'dist/precompiled.manifest.json',
+    JSON.stringify(artifact.manifest),
+  ),
+  writeFile('dist/precompiled.report.json', JSON.stringify(artifact.report)),
+]);
+```
+
+Run the catalog with the same Tasty configuration and exact Tasty version that
+the design system publishes. Generation rejects page-relative CSS resources
+such as `url(font.woff2)` because their meaning changes when the stylesheet is
+moved. Absolute, root-relative, and data URLs are accepted.
+
+The output is deterministic for a deterministic catalog and configuration.
+The report lists the classes and ordered collector artifacts first introduced
+by each case; use it to remove cases that add no coverage.
+
+The Node-only precompile entry renders each returned tree with React DOM's
+`renderToStaticMarkup()` inside the collector context. Catalog cases only need
+to construct their representative component tree, including any providers the
+design system normally requires.
+
+## Publish and Register
+
+The production default is a static stylesheet plus manifest registration:
+
+```ts
+// @acme/ui/precompiled
+import { registerTastyPrecompiled } from '@tenphi/tasty/precompile/register';
+import manifest from './precompiled.manifest.json';
+import './precompiled.css';
+
+registerTastyPrecompiled(manifest);
+export * from './index.js';
+```
+
+Mark this module and the CSS asset as side-effectful in the UI package. Keep the
+normal entry unchanged so adoption is explicit. Applications that link the CSS
+from HTML or a framework layout must still execute the registration module
+before rendering Tasty components.
+
+A static asset is preferred because the browser can load and cache it in
+parallel with JavaScript, it is available for first paint, and it requires no
+CSP nonce. Environments that must bundle CSS text can use the fallback:
+
+```ts
+import {
+  installTastyPrecompiled,
+  type TastyPrecompiledManifest,
+} from '@tenphi/tasty/precompile/register';
+import css from './precompiled.css?raw';
+import manifestJSON from './precompiled.manifest.json';
+
+installTastyPrecompiled({
+  css,
+  manifest: manifestJSON as TastyPrecompiledManifest,
+});
+```
+
+Call `installTastyPrecompiled()` before the first Tasty render. It appends one
+`<style data-tasty-precompiled>` element, assigns `textContent` once, and does
+not place the CSS in Tasty's normal rule lifecycle. An explicit nonce overrides
+the nonce from `configure()`.
+
+## What the Artifact Contains
+
+The stylesheet contains only collector artifacts attributed to components:
+
+- style chunks;
+- component-local and standalone `@property`, `@keyframes`, `@font-face`,
+  `@counter-style`, and native `@function` rules;
+- properties inferred from component declarations.
+
+It excludes `configure()` internals, `useGlobalStyles()`, and `useRawCSS()`.
+Tokens, palettes, body styles, and application globals therefore remain
+dynamic. The asset is a base stylesheet: dynamic globals and uncovered chunks
+are appended later and can override it. It intentionally does not use
+`data-tasty-ssr`, which would incorrectly tell hydration that configured
+globals were already emitted.
+
+Dependency metadata seeds browser, SSR, and RSC caches as immutable external
+definitions. Tasty neither inserts duplicate ancillary rules nor adds external
+classes to its garbage-collected rule set. A precompiled hit is restricted to
+the document the catalog CSS lives in — a static stylesheet in the page, or the
+`<style>` `installTastyPrecompiled()` appends to the global `document`. Any
+other root uses the normal runtime path: a `ShadowRoot`, which cannot see
+document CSS, and another `Document` such as an iframe's, which the asset was
+never installed into.
+
+Registration is global across server module graphs and idempotent for the same
+manifest ID and CSS hash. Tasty rejects incompatible versions, name prefixes,
+or conflicting lookup mappings in development and safely falls back to runtime
+generation.
+
+## Catalog Policy for UI Kits
+
+Use the smallest matrix that exposes every unique styled structure:
+
+1. Render one default case for every public styled component.
+2. Render every declared visual variant.
+3. Add controlled states or props only when they change Tasty input or mount a
+   distinct styled subtree.
+4. Use multiple items in collections and compound components only to expose
+   different internal styled primitives.
+5. Do not add a clear or close case when it only reuses a shared action such as
+   `ItemAction` and adds no class or dependency.
+6. Remove non-default cases whose report delta is empty unless a documented
+   structural reason requires them.
+7. Catalog every public styled component or mark it runtime-only with a reason.
+
+Consumer changes to parser functions, units, states, handlers, recipes, chunk
+assignments, `replaceTokens`, or other compilation-affecting configuration
+invalidate a shared catalog. Such applications should use runtime generation or
+build a project-specific artifact.
+
+Theming does not invalidate a catalog. `configure({ tokens })` emits `:root`
+custom properties, which the asset excludes, and a chunk written against
+`#brand` compiles to `var(--brand-color)` whatever the current value is — so a
+palette swap leaves every compiled chunk correct. `replaceTokens` is listed
+above because it is the opposite: it substitutes at parse time and bakes its
+value into the declaration.
+
+Chunk lookup is exact. A shared UI-kit catalog is most useful when applications
+render those components close to their cataloged styles; frequent project
+overrides can leave a large static asset mostly inactive while the expensive
+custom chunks still run through the pipeline. Use `tastyDebug.summary()` to
+compare active runtime and precompiled classes and to inspect distinct
+precompiled classes used since metrics were reset. For heavily styled
+applications, prefer a project-specific catalog that renders representative
+application routes and states under the application's real Tasty
+configuration. Do not load both the broad shared asset and a project-specific
+asset containing the same coverage.
+
+## Performance Verification
+
+Catalog generation, registration, and stylesheet loading are startup work and
+should stay outside render samples. `pnpm bench:injection` includes a
+1,000-rule precompiled lookup case alongside cold generation and an
+already-present CSS control. It asserts up front that the case is actually
+being served from the catalog, and fails the run otherwise: a class name is
+`hashString(cacheKey)` whether it came from the catalog or from runtime
+generation, so nothing in the name or the rendering distinguishes a hit from a
+miss, and a case that quietly stopped hitting would report the runtime path
+under the precompiled label. Use `pnpm bench`, `pnpm bench:overhead`, and
+`pnpm bench:injection` in alternating runs on the same idle machine when
+changing this path.
+
+With no registered manifest, the registry does not allocate lookup maps and
+`computeStyles()` performs only the disabled-path boolean check before
+continuing through its existing cache and injection behavior.

package/docs/runtime-benchmarks.md

@@ -1,19 +1,21 @@
 # Runtime Benchmarks
 
 Tasty keeps its performance claims in reproducible benchmarks rather than
-combining unlike measurements into one score. The repository measures four
+combining unlike measurements into one score. The repository measures three
 different costs:
 
 1. Style parsing and generation in Node.
 2. The React overhead of an empty `tasty({})` wrapper.
 3. Cold browser generation and injection compared with equivalent CSS that is
-   already on the page.
-4. A representative React update that combines wrapper, cache, generation,
-   injection, and style-resolution work.
+   already on the page or registered as a precompiled catalog.
+4. Page-load cold start: transfer, compile, execution, first render, and
+   retained heap, against the same page built without Tasty.
 
-These are focused microbenchmarks, not page-load or interaction scores. Run
-them several times on an otherwise idle machine and use a production profile
-to decide whether any cost matters in an application.
+The first three are focused microbenchmarks, not page-load or interaction
+scores. The fourth is the page-load measurement, and it is the one to read
+before concluding anything about a real application. Run them several times on
+an otherwise idle machine and use a production profile to decide whether any
+cost matters.
 
 ## Reproducing the Results
 
@@ -21,10 +23,10 @@ to decide whether any cost matters in an application.
 pnpm bench
 pnpm bench:overhead
 pnpm bench:injection
-pnpm bench:tree
+pnpm bench:cold-start
 ```
 
-`pnpm bench` runs the core pipeline benchmarks in Node. The other three commands
+`pnpm bench` runs the core pipeline benchmarks in Node. The other two commands
 use production code paths in headless Chromium. The first checkout may require
 `pnpm test:setup` to download Chromium.
 
@@ -106,21 +108,17 @@ snapshot experiment with controlled garbage collection.
 work when Tasty must generate and inject CSS that an otherwise equivalent page
 already has. It does not compare different stylesheet insertion techniques.
 
-The benchmark covers four group sizes with one style-resolution boundary per
-group:
+The benchmark covers two useful workloads:
 
-- **One new rule:** add one rule, append its element, and immediately read its
-  computed style. Each sample performs 50 independent groups for timer
-  stability.
-- **10 new rules together:** generate and insert 10 rules, append their 10
-  elements, then read every computed color without another write. Each sample
-  performs 10 independent groups.
-- **100 or 1,000 new rules together:** perform the same sequence once per
-  sample with 100 or 1,000 rules before the resolution boundary.
-
-Repeating the smaller groups inside one sample only raises the measurement
-above Chromium's timer resolution. Results are divided by that repetition
-count, so every row below describes one group with one resolution boundary.
+- **One new rule:** add one rule to an existing stylesheet, append its one
+  element, and immediately read its computed style. Each timed sample performs
+  50 independent one-rule transactions and reports their total; dividing the
+  raw/Tasty difference by 50 produces a stable per-rule result despite
+  Chromium's 0.1 ms timer resolution.
+- **1,000 new rules together:** generate and insert all 1,000 rules into one
+  stylesheet, append all 1,000 elements, then read every computed color without
+  another write in between. This gives the browser one style-resolution
+  boundary for the group.
 
 For every transaction, the existing-CSS control has the equivalent stylesheet
 parsed, adopted, and attached before timing. The runtime root has a Tasty
@@ -129,6 +127,13 @@ rules. Both paths perform the same class assignment, DOM commit, and
 computed-style reads. Only the runtime path calls `computeStyles()` and inserts
 the new rules.
 
+The 1,000-rule workload also includes a precompiled Tasty case. Its catalog is
+generated and registered, and its CSS is parsed in an isolated document,
+before the timer starts. The timed work is the chunk-key lookup, class
+assignment, DOM commit, and the same computed-style reads. This keeps CSS
+delivery and registration out of render latency while preserving the real
+runtime lookup path.
+
 Preparation and cleanup happen outside the sample timer. Every runtime style
 value is unique within a cycle, the relevant caches are cleared between cycles,
 and a guard verifies that both paths resolve to the same color. React and the
@@ -137,20 +142,20 @@ the result. Pre-creating both stylesheets also excludes one-time sheet creation
 and adoption from the subtraction.
 
 On an Apple M3 Pro with Chromium 151, three consecutive runs produced these
-normalized ranges:
+ranges:
 
-| New rules before one resolution | Groups per sample | Incremental cost per group | Incremental cost per rule |
-| ------------------------------: | ----------------: | -------------------------: | ------------------------: |
-|                               1 |                50 |             0.111–0.114 ms |                111–114 us |
-|                              10 |                10 |             0.142–0.159 ms |              14.2–15.9 us |
-|                             100 |                 1 |               0.90–0.94 ms |                9.0–9.4 us |
-|                           1,000 |                 1 |               7.58–8.10 ms |                7.6–8.1 us |
+| Workload                                             | CSS already present |  Tasty runtime | Incremental Tasty cost |
+| ---------------------------------------------------- | ------------------: | -------------: | ---------------------: |
+| One new rule + immediate resolution, per transaction |          2.8–3.3 us | 110.3–113.8 us |         107.3–111.0 us |
+| 1,000 new rules + one resolution                     |        1.86–2.06 ms |   9.01–9.98 ms |           7.13–7.92 ms |
+| 1,000-rule workload, incremental cost per rule       |                   — |              — |             7.1–7.9 us |
 
-The curve makes the fixed work visible. Delivering 1,000 rules before one
-resolution boundary cost roughly 67–73 times as much in total as delivering
-one rule and resolving it, not 1,000 times as much. The average incremental
-cost per rule was roughly 14–15 times lower because the group amortized fixed
-transaction work and let the browser resolve all stylesheet writes together.
+Directly compared, injecting 1,000 rules before one resolution boundary cost
+about 66–71 times as much in total as injecting one rule and resolving it—not
+1,000 times as much. Its average incremental cost per rule was about 14–16
+times lower. This is the same Tasty generation and injection path in both cases;
+the group amortizes fixed transaction work and lets the browser resolve all the
+stylesheet writes together.
 
 The subtraction is the meaningful result. It includes Tasty's cold style
 generation, cache and injector bookkeeping, rule insertion, and any additional
@@ -159,41 +164,12 @@ pretend to isolate `insertRule()` from the system that calls it.
 
 This is a deliberately cold workload. Reused styles resolve from cache and do
 not inject another rule. Different rule complexity, DOM shape, stylesheet size,
-browser, and hardware will change the number. Because the same group and
-resolution pattern is present in each workload's control, the difference
-answers the narrower delivery question: how much extra work did Tasty perform
-when the same CSS was not already there?
-
-## Representative React Tree
-
-[`tasty-tree.bench.tsx`](../src/tasty-tree.bench.tsx) bridges the isolated
-measurements with one production React update. Every path updates 1,000 host
-elements sharing 20 combinations of `color` and `padding`, then reads computed
-styles after the commit:
-
-- **CSS already present:** raw elements switch between classes whose rules were
-  attached before timing.
-- **Tasty, warm:** the elements switch between two sets of Tasty styles that
-  were generated before timing.
-- **Tasty, cold:** every update introduces 20 new combinations shared across
-  the 1,000 elements.
-
-The Tasty paths use the normal component API and `TastyBatchProvider`. On an
-Apple M3 Pro with production React 19.2.4 and Chromium 151, three consecutive
-runs produced these mean ranges:
-
-| Update path                         | Total time for 1,000 elements |
-| ----------------------------------- | ----------------------------: |
-| CSS already present                 |                  1.64–1.70 ms |
-| Tasty, shared styles already cached |                  4.17–4.43 ms |
-| Tasty, 20 new shared styles         |                  4.62–4.80 ms |
-
-In this workload, the warmed Tasty path added 2.52–2.73 ms over raw elements
-with existing CSS. Introducing 20 new shared combinations added another
-0.38–0.55 ms over the warm Tasty update. This is a synthetic update, not an
-application score: it excludes effects, layout reads, paint, and concurrent
-scheduling, while deliberately making all 1,000 elements participate in every
-commit.
+browser, and hardware will change the number. The single-rule and 1,000-rule
+results are not interchangeable: the first crosses the injection-to-resolution
+boundary once per rule, while the second lets the browser resolve 1,000 writes
+together. Because the same resolution pattern is present in each workload's
+control, the difference answers the narrower delivery question: how much extra
+work did Tasty perform when the same CSS was not already there?
 
 ## Reading the Results Together
 
@@ -206,11 +182,106 @@ They describe different paths:
   rule.
 - A genuinely new style pays generation and injection once, then becomes
   reusable.
-- A tree that shares a small style vocabulary pays the wrapper path per element
-  but cold generation only per new combination.
+- A registered precompiled chunk skips declaration rendering and rule
+  insertion, while uncovered chunks in the same component remain dynamic.
 - Browser style resolution, layout, and paint depend on the actual document and
   need application-level profiling.
 
 The practical optimization target is therefore repeated work: keep style input
 stable when possible, reuse generated chunks, and generate CSS at build or
 server time when runtime flexibility is unnecessary.
+
+## Page-Load Cold Start
+
+```bash
+pnpm bench:cold-start
+pnpm bench:cold-start -- --network slow-4g --cpu 4 --runs 7
+pnpm bench:cold-start -- --mode baseline,precompiled --components 200
+```
+
+[`scripts/cold-start/`](../scripts/cold-start/) loads a real page in headless
+Chromium under emulated network and CPU conditions and splits the wait into the
+parts a change can move: HTML, JS and CSS transfer, module-graph compilation,
+each bundle's top-level execution, the first styled component, the rest of the
+page, first contentful paint, and retained heap after a forced collection.
+
+Assets are bundled and minified the way an application ships them. Measuring
+`dist/` directly would report an unminified twelve-file build nobody serves.
+Nothing is cached between runs, so every run is a first visit.
+
+Four columns run on the identical page:
+
+| mode          | what it is                                                                                             |
+| ------------- | ------------------------------------------------------------------------------------------------------ |
+| `baseline`    | No Tasty at all. The same markup and the same stylesheet, with hand-written class names — the control. |
+| `runtime`     | Tasty generating and injecting every chunk.                                                            |
+| `precompiled` | A catalog covering the page, its CSS linked as a static stylesheet.                                    |
+| `prewarm`     | Runtime, with one throwaway `computeStyles()` before the first render.                                 |
+
+**Read every number against `baseline`.** On its own, most of what the page
+spends is React, the network and the DOM; the difference between a column and
+the control is what Tasty costs.
+
+Each run is verified before its numbers are reported: an untimed pass with
+`devMode` on asserts that `precompiled` served every chunk from the catalog and
+generated none, and that the other modes generated theirs. This is not
+optional bookkeeping — a precompiled class name and a runtime one are the same
+string, `hashString(cacheKey)`, so neither the markup nor the rendering
+distinguishes a catalog hit from a miss, and a column that quietly stopped
+hitting would report the runtime path under a precompiled label.
+
+### Results
+
+Apple M1 Max, headless Chromium, 50 distinct styled components, median of 5.
+
+Uncontended CPU, no network throttling — the CPU picture on its own:
+
+| phase            |  baseline |   runtime | precompiled |   prewarm |
+| ---------------- | --------: | --------: | ----------: | --------: |
+| compile (graph)  |    6.8 ms |    6.8 ms |      4.7 ms |    6.6 ms |
+| react execute    |     10 ms |     11 ms |       11 ms |     12 ms |
+| tasty execute    |         — |    1.0 ms |      0.9 ms |    1.1 ms |
+| catalog register |         — |         — |      0.3 ms |         — |
+| prewarm          |         — |         — |           — |    5.2 ms |
+| first component  |    1.8 ms |    6.7 ms |      5.0 ms |    2.7 ms |
+| 49 more          |    1.2 ms |    6.7 ms |      2.1 ms |    6.7 ms |
+| **painted**      | **41 ms** | **54 ms** |   **49 ms** | **60 ms** |
+| retained heap    |  1,616 KB |  2,665 KB |    2,374 KB |  2,675 KB |
+
+Slow 4G with a 4x CPU slowdown — closer to a mid-range phone:
+
+| phase                 |     baseline |      runtime |  precompiled |
+| --------------------- | -----------: | -----------: | -----------: |
+| html                  |       570 ms |       570 ms |       569 ms |
+| **js + css transfer** | **1,551 ms** | **2,667 ms** | **2,712 ms** |
+| compile (graph)       |       5.0 ms |       5.5 ms |       5.9 ms |
+| tasty execute         |            — |       3.8 ms |       4.1 ms |
+| first component       |        10 ms |        33 ms |        24 ms |
+| 49 more               |       5.6 ms |        29 ms |       8.3 ms |
+| **painted**           | **2,812 ms** | **3,979 ms** | **4,010 ms** |
+
+### What the numbers say
+
+**Tasty's page-load cost is its bundle, not its execution.** On Slow 4G the
+runtime column reaches paint 1,167 ms after the control, and 1,116 ms of that
+is downloading 60 KB of extra JavaScript. Every CPU phase together — compile,
+execute, and rendering all 50 components — is under 70 ms even with a 4x
+slowdown. Optimising the style pipeline cannot move the number that dominates
+this page; shipping less code can.
+
+**The first styled component costs several times what the next one does**
+(6.7 ms against roughly 0.14 ms each for the following 49, uncontended). That
+is Tasty's deferred payload compiling on first use, not per-component work.
+`prewarm` moves it off the first render — 6.7 ms down to 2.7 ms — but pays the
+same cost earlier and finishes later overall, so it is worth doing only where
+those milliseconds land somewhere nobody is waiting.
+
+**A catalog roughly thirds the rendering work** (29 ms to 8.3 ms at 4x) and
+takes about 300 KB off the retained heap, at the cost of a stylesheet to
+download. On a fast connection it wins; on Slow 4G the extra CSS costs about
+as much as the CPU it saves. It also does not remove the first-render spike —
+5.0 ms against 6.7 — because the code that computes a lookup key compiles
+whether or not the lookup then hits.
+
+**Retained heap is about 1 MB over the control for 50 components**, or 760 KB
+with a catalog. It does not vary with network or CPU.