@tenphi/tasty 3.5.0 → 3.7.0

package/dist/ssr-collector-ref-COs_ioWl.js

@@ -0,0 +1,29 @@
+//#region src/ssr/ssr-collector-ref.ts
+const GETTER_KEY = "__tasty_ssr_collector_getter__";
+let _getSSRCollector = null;
+/**
+* Register the collector getter in the current module graph only.
+* Used by Next.js TastyRegistry.
+*/
+function registerSSRCollectorGetter(fn) {
+	_getSSRCollector = fn;
+}
+/**
+* Register the collector getter on globalThis so it is visible across
+* separate module graphs (e.g. Astro middleware ↔ page components).
+*/
+function registerSSRCollectorGetterGlobal(fn) {
+	globalThis[GETTER_KEY] = fn;
+}
+/**
+* Retrieve the SSR collector: module-level first, globalThis fallback.
+*/
+function getRegisteredSSRCollector() {
+	if (_getSSRCollector) return _getSSRCollector();
+	const getter = globalThis[GETTER_KEY];
+	return getter ? getter() : null;
+}
+//#endregion
+export { registerSSRCollectorGetter as n, registerSSRCollectorGetterGlobal as r, getRegisteredSSRCollector as t };
+
+//# sourceMappingURL=ssr-collector-ref-COs_ioWl.js.map

package/dist/ssr-collector-ref-COs_ioWl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-collector-ref-COs_ioWl.js","names":[],"sources":["../src/ssr/ssr-collector-ref.ts"],"sourcesContent":["/**\n * Global reference to the SSR collector getter function.\n *\n * This indirection avoids importing 'node:async_hooks' in the browser bundle.\n * The SSR entry point sets this ref when loaded on the server. The useStyles\n * hook calls it if set; on the client it stays null and is never called.\n *\n * Uses a module-level variable as the primary mechanism. In Next.js App\n * Router the RSC and SSR module graphs load separate copies of this module,\n * so the getter registered by TastyRegistry (SSR layer) is invisible to\n * server components (RSC layer) — which correctly fall through to inline\n * RSC styles.\n *\n * A globalThis fallback (`registerSSRCollectorGetterGlobal`) is provided\n * for frameworks like Astro where middleware and page components live in\n * different module graphs and must share the getter across them.\n */\n\nimport type { ServerStyleCollector } from './collector';\n\ntype SSRCollectorGetter = () => ServerStyleCollector | null;\n\nconst GETTER_KEY = '__tasty_ssr_collector_getter__';\n\nlet _getSSRCollector: SSRCollectorGetter | null = null;\n\n/**\n * Register the collector getter in the current module graph only.\n * Used by Next.js TastyRegistry.\n */\nexport function registerSSRCollectorGetter(fn: SSRCollectorGetter): void {\n  _getSSRCollector = fn;\n}\n\n/**\n * Register the collector getter on globalThis so it is visible across\n * separate module graphs (e.g. Astro middleware ↔ page components).\n */\nexport function registerSSRCollectorGetterGlobal(fn: SSRCollectorGetter): void {\n  (globalThis as Record<string, unknown>)[GETTER_KEY] = fn;\n}\n\n/**\n * Retrieve the SSR collector: module-level first, globalThis fallback.\n */\nexport function getRegisteredSSRCollector(): ServerStyleCollector | null {\n  if (_getSSRCollector) return _getSSRCollector();\n  const getter = (globalThis as Record<string, unknown>)[GETTER_KEY] as\n    SSRCollectorGetter | undefined;\n  return getter ? getter() : null;\n}\n"],"mappings":";AAsBA,MAAM,aAAa;AAEnB,IAAI,mBAA8C;;;;;AAMlD,SAAgB,2BAA2B,IAA8B;CACvE,mBAAmB;AACrB;;;;;AAMA,SAAgB,iCAAiC,IAA8B;CAC7E,WAAwC,cAAc;AACxD;;;;AAKA,SAAgB,4BAAyD;CACvE,IAAI,kBAAkB,OAAO,iBAAiB;CAC9C,MAAM,SAAU,WAAuC;CAEvD,OAAO,SAAS,OAAO,IAAI;AAC7B"}

package/docs/debug.md

@@ -54,6 +54,19 @@ interface DebugOptions {
 
 When `raw` is `false` (the default), results are logged to the console **and** returned. When `raw` is `true`, results are returned silently.
 
+### Environments Without a DOM
+
+`tastyDebug` reads the document, so on a server — SSR, a Node REPL, a test
+runner in the `node` environment — there is nothing for it to read. Every
+method returns its empty result (`''`, an empty `InspectResult`, a summary of
+zeroes, `metrics: null`) instead of throwing, and explains itself once with a
+console warning. `{ raw: true }` suppresses that warning along with the rest of
+the logging.
+
+To see the styles a server render produced, read the `ServerStyleCollector`
+instead — `collector.getCSS()` and `collector.getRenderedClassNames()`. See
+[SSR](./ssr.md).
+
 ---
 
 ## API Reference

package/docs/runtime-benchmarks.md

@@ -1,17 +1,22 @@
 # Runtime Benchmarks
 
 Tasty keeps its performance claims in reproducible benchmarks rather than
-combining unlike measurements into one score. The repository measures three
+combining unlike measurements into one score. The repository measures five
 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. The steady-state interaction path — mod flips and styled subtrees opening
+   and closing after the page has loaded.
+5. Page-load cold start: network, module compilation, execution and first
+   paint, end to end in a throttled browser.
 
-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 four are focused microbenchmarks, not page-level scores. The fifth is
+a page-level measurement and is the only one that answers "what does a visitor
+wait for". Run them several times on an otherwise idle machine and use a
+production profile to decide whether any cost matters in an application.
 
 ## Reproducing the Results
 
@@ -19,17 +24,21 @@ to decide whether any cost matters in an application.
 pnpm bench
 pnpm bench:overhead
 pnpm bench:injection
+pnpm bench:interaction
+pnpm bench:cold-start
 ```
 
-`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.
+`pnpm bench` runs the core pipeline benchmarks in Node. The rest use production
+code paths in headless Chromium. The first checkout may require
+`pnpm test:setup` to download Chromium, and `pnpm bench:cold-start` needs a
+current `dist/` — run `pnpm build` first.
 
 Run the Node and browser suites separately so they do not compete for CPU. The
-browser timer has 0.1 ms resolution, so both browser benchmarks perform many
+browser timer has 0.1 ms resolution, so the browser benchmarks perform many
 matched operations per sample and divide the absolute difference by the number
-of elements or rules. Machine load, browser versions, and CPU power will move
-the results.
+of elements, rules or interactions. Machine load, browser versions, and CPU
+power will move the results — on a loaded machine the absolute columns drift
+several percent while the raw/Tasty delta holds, so read the delta.
 
 ## Core Style Pipeline
 
@@ -159,10 +168,165 @@ 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?
 
+## Steady-State Interaction
+
+The benchmarks above measure mounting and whole-tree updates. A running
+application spends most of its time on neither. It flips mods — hovered,
+pressed, selected, expanded — on elements whose styles never change, one
+element at a time, and it mounts and unmounts small styled subtrees as menus
+and dialogs open. Both paths go through the state-map and ref-counting
+machinery rather than the parser, so a regression in them is invisible to every
+other benchmark here.
+
+[`tasty-interaction.bench.tsx`](../src/tasty-interaction.bench.tsx) pairs each
+case with a raw-DOM equivalent driven by a hand-written stylesheet that
+produces the same computed color and background in both states. The benchmark
+fails if either arm resolves to anything else, so an arm that quietly rendered
+unstyled elements cannot report a flattering number.
+
+Each leaf owns its own `useState`, which is what keeps a single-element
+interaction single: re-rendering the root to flip one row would time the whole
+tree. One toggle is far below Chromium's 0.1 ms timer resolution, so a sample
+flips a 100-element tree three times over — 300 commits — and the churn case
+performs 20 open/close cycles. Divide the raw/Tasty difference by those counts.
+
+Two things had to be sized deliberately, and both are the difference between a
+readable number and noise:
+
+- **The tree is small (100 elements), not large.** React locates a leaf's
+  pending update by walking the sibling list, so in a 1,000-element tree a
+  single-element update costs ~68 us of traversal — identical in both arms and
+  an order of magnitude above anything the styling layer contributes.
+- **The sample resolves style once, not once per flip.** Forcing a recalc
+  between flips costs ~70 us in both arms, which buries the delta the same way.
+  The browser's side of an interaction is real, but it is the browser's;
+  resolution boundaries are what the injection benchmark above measures.
+
+The contract check also reads the injected CSS **before** any toggle and fails
+if the hovered rule is not already there. That a style map's states all ship in
+one chunk on first render is the premise of this case; if the hovered rule
+arrived lazily, the first sample would be timing injection.
+
+On an Apple M1 Max with React 19.2.8 and Chromium 151, across several runs:
+
+| Workload                                             | Raw elements |   Tasty mods |           Extra per unit |
+| ---------------------------------------------------- | -----------: | -----------: | -----------------------: |
+| 300 single-element mod toggles in a 100-element tree |   2.1–2.5 ms |   2.7–3.1 ms | 1.6–2.1 us / interaction |
+| 20 mount + unmount cycles of a 200-element subtree    |   7.6–8.0 ms | 12.6–12.7 ms |   1.22–1.27 us / element |
+
+The absolute columns move several percent with machine load; the delta between
+the arms is the stable quantity, so read that rather than either column.
+
+Two things are worth reading out of this.
+
+A mod flip on an already-mounted element costs about 2 us. The CSS for both
+states already exists — Tasty emits every state of a style map in one chunk on
+first render — so both arms perform the same commit, and what is left is
+Tasty's props and mod handling. That is the same order as the ~1 us empty
+wrapper measured above, which is most of where it comes from.
+
+Subtree churn is not about styling at all. Its ~1.25 us per element sits right
+on the empty-wrapper mount cost, because the styles are already cached:
+reopening a menu re-pays the React wrapper, not the style pipeline.
+
+## Page-Load Cold Start
+
+Every benchmark above deliberately excludes the network, module compilation and
+the first render. [`scripts/cold-start`](../scripts/cold-start) measures exactly
+those: what a visitor waits for between requesting a page and seeing styled
+content, in a real Chromium under CDP network and CPU throttling.
+
+Three pages render the same 50 styled components and are verified, before any
+timing, to produce the same 50 elements at the same computed color:
+
+- **baseline** — the components server-rendered: identical markup, identical
+  class names, a linked stylesheet, and no Tasty on the page. Every other
+  column is a delta against this one.
+- **runtime** — Tasty generates the CSS in the browser, as a client-rendered
+  application does. The run asserts it really did (69 rules generated).
+- **prewarm** — the same, after one throwaway `computeStyles()` against a
+  detached root before the first component renders.
+
+Each cell is the median of 5 uncached loads in a fresh browser context. The run
+ends at the first contentful paint, observed through a `PerformanceObserver`
+rather than counted in animation frames — `requestAnimationFrame` fires before
+paint, so a page that commits fast can reach its second frame with nothing
+painted yet.
+
+Two things about the payload decide whether this measures a deployment or a
+straw man, so both are enforced rather than assumed:
+
+- **Assets are served brotli-compressed**, the way a static host serves them.
+  The bundle is 52.0 KB on the wire and 186 KB decoded; putting the decoded
+  bytes on a 1.6 Mbps link would add ~700 ms and charge it to Tasty. The run
+  reads `encodedBodySize` back out of resource timing and fails if what
+  crossed the wire is not the compressed size the table reports.
+- **The bundle is built from what the page imports** (`tasty`, `configure`,
+  `computeStyles`, `tastyDebug`), so it is tree-shaken as an application's
+  would be. Re-exporting the whole library adds ~4 KB brotli of code no page
+  here calls.
+
+On an Apple M1 Max with React 19.2.8 and Chromium 151, first contentful paint:
+
+| Link / CPU            | baseline | runtime | prewarm | Tasty's cost |
+| --------------------- | -------: | ------: | ------: | -----------: |
+| No throttling, 1x     |    40 ms |   52 ms |   52 ms |       +12 ms |
+| Fast 4G, 1x           |   624 ms |  680 ms |  676 ms |       +56 ms |
+| Slow 4G, 1x           |  2028 ms | 2304 ms | 2304 ms |      +276 ms |
+| No throttling, 4x CPU |   148 ms |  196 ms |  196 ms |       +48 ms |
+| Fast 4G, 4x CPU       |   684 ms |  784 ms |  788 ms |      +100 ms |
+| Slow 4G, 4x CPU       |  2096 ms | 2416 ms | 2408 ms |      +320 ms |
+
+That is one full run of the matrix; a second moved every cell by a few percent.
+
+**The cost is the bundle, not the work.** On Slow 4G the extra transfer alone
+accounts for 262 ms of the 276 ms FCP delta — nearly all of it. Everything
+Tasty then *does* is small by comparison:
+
+| Phase (Slow 4G, 1x)     | baseline | runtime | prewarm |
+| ----------------------- | -------: | ------: | ------: |
+| js+css transfer         |  1420 ms | 1682 ms | 1681 ms |
+| module compile (shared) |   1.2 ms |  1.5 ms |  2.0 ms |
+| tasty top-level execute |        — |  1.2 ms |  0.9 ms |
+| `configure()`           |        — |  0.6 ms |  0.5 ms |
+| prewarm                 |        — |       — |  5.3 ms |
+| render 1st component    |   2.0 ms |  8.2 ms |  2.7 ms |
+| render 49 more          |   1.0 ms |  7.1 ms |  6.0 ms |
+
+Importing Tasty costs about 1 ms of top-level execution; `configure()` costs
+half of one. The rest of the CPU delta — about 13 ms for 50 components — is
+generation and injection, which is the cost the injection benchmark isolates.
+
+One asymmetry is worth naming: the control links a render-blocking stylesheet
+and the runtime modes have none, so the control's first paint waits for CSS the
+runtime modes never request. That is the real difference between the two
+delivery models, not a thumb on the scale, but it means the FCP delta is not
+purely "what Tasty costs to execute".
+
+**Prewarming moves the wake-up, it does not remove it.** The first styled render
+is ~5 ms more expensive than the ones after it, because that is when the
+engine's deferred payload is actually compiled. A throwaway `computeStyles()`
+against a detached root pays it early: `render 1st` drops from 8.2 ms to
+2.7 ms. The prewarm itself costs 5.3 ms, so FCP does not move. It is worth
+doing only when something else can overlap it, or when the first render is on a
+latency-critical path and the page has idle time before it.
+
+**Retained heap.** After a forced collection, the runtime page holds about
+1,013 KB more than the control (2,632 KB vs 1,619 KB) for 50 components — the
+parser caches, the chunk cache, the injector's registry and the generated CSS.
+The control is not zero either; most of its 1.6 MB is React and the DOM.
+
+CPU throttling changes which line moves. At 4x, module compilation of the
+larger graph becomes visible (5.9 ms → 25 ms) where at 1x it is free: V8
+pre-parses at import and compiles lazily, so a slower CPU pays for code the
+faster one never fully compiled. Transfer numbers from the unthrottled cells
+are not worth reading — with no emulated link, resource timings are scheduling
+jitter.
+
 ## Reading the Results Together
 
-Do not add all three benchmark numbers to estimate an application blindly.
-They describe different paths:
+Do not add the microbenchmark numbers together to estimate an application
+blindly. They describe different paths:
 
 - A stable `tasty()` factory can skip the style pipeline on later renders, but
   its React wrapper still participates in reconciliation.
@@ -170,9 +334,18 @@ They describe different paths:
   rule.
 - A genuinely new style pays generation and injection once, then becomes
   reusable.
+- A mod flip on an already-styled element pays neither; it is a class-name
+  change.
 - Browser style resolution, layout, and paint depend on the actual document and
   need application-level profiling.
 
+The cold-start measurement is the one that puts the rest in proportion. On a
+slow connection, nearly all of Tasty's page-load cost is transferring the
+library — 262 ms of a 276 ms delta — while the generation and injection the
+microbenchmarks obsess over is ~13 ms for 50 components. Bundle size is
+therefore the lever with the largest effect on first paint, and the runtime
+levers matter for what happens after it.
+
 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.

package/docs/ssr.md

@@ -86,6 +86,92 @@ export default function RootLayout({
 
 That's it. All `tasty()` components inside the tree automatically get SSR support. No per-component changes needed.
 
+### Optional shared globals stylesheet
+
+By default, configured global CSS is included in the streamed Tasty style tag
+for every route. `withTastyNext()` can move that stable CSS into one
+content-hashed stylesheet shared by all routes while leaving component and hook
+styles in the normal streaming path.
+
+Keep the Tasty config in a side-effect-free module:
+
+```ts
+// app/tasty.config.ts
+import type { TastyConfig } from '@tenphi/tasty';
+
+const config: TastyConfig = {
+  tokens: { $gap: '8px', '#brand': 'rebeccapurple' },
+  globalStyles: { body: { margin: '0', color: '#brand' } },
+  fontFaces: {
+    Brand: { src: 'url("/fonts/brand.woff2") format("woff2")' },
+  },
+};
+
+export default config;
+```
+
+Use it from the Next config:
+
+```ts
+// next.config.ts
+import { withTastyNext } from '@tenphi/tasty/ssr/next-config';
+import config from './app/tasty.config';
+
+export default withTastyNext({
+  config,
+})({
+  // your Next.js config
+});
+```
+
+The runtime must receive the same config. Import and configure it before the
+registry renders:
+
+```tsx
+// app/tasty-registry.tsx
+'use client';
+
+import { configure } from '@tenphi/tasty';
+import { TastyRegistry } from '@tenphi/tasty/ssr/next';
+import config from './tasty.config';
+
+configure(config);
+
+export default function TastyStyleRegistry({ children }) {
+  return <TastyRegistry>{children}</TastyRegistry>;
+}
+```
+
+The generated file contains eager configuration artifacts: built-in and custom
+`@property` rules, tokens and presets, `@font-face`, `@counter-style`, native
+CSS `@function` definitions, and `globalStyles`. Route-dependent component
+rules and calls to `useGlobalStyles`, `useRawCSS`, `useKeyframes`,
+`useProperty`, `useFontFace`, `useCounterStyle`, and `useFunction` remain
+route-specific. Configured keyframes also remain lazy and are streamed only
+when a route references them.
+
+The default output directory is `public/_tasty`. The wrapper adds the generated
+URL to `TastyRegistry`, respects `basePath`, preserves existing `env` and
+`headers` config, and serves the content-hashed file with an immutable one-year
+cache header on Next server deployments. Static exports keep the content-hashed
+URL and leave cache headers to the hosting provider. Older hashes are not
+deleted automatically, so rolling deployments cannot break pages from the
+previous build; clean the generated directory as part of a clean deployment if
+needed. Page-relative CSS resources such as
+`url(../fonts/brand.woff2)` are rejected because moving them would change their
+meaning; use root-relative, absolute, or data URLs.
+
+`withTastyNext()` options:
+
+| Option       | Type          | Default                   | Description                                                            |
+| ------------ | ------------- | ------------------------- | ---------------------------------------------------------------------- |
+| `config`     | `TastyConfig` | —                         | Config object; takes precedence over `configFile`                      |
+| `configFile` | `string`      | —                         | Project-relative config module path; requires the optional `jiti` peer |
+| `rootDir`    | `string`      | current directory         | Next app root when the build runs from a monorepo root                 |
+| `outputDir`  | `string`      | `public/_tasty`           | Filesystem output directory                                            |
+| `publicPath` | `string`      | inferred from `outputDir` | Root-relative URL; required when output is outside `public`            |
+| `enabled`    | `boolean`     | `true`                    | Disable generation without changing wrapper composition                |
+
 ### How it works
 
 - `TastyRegistry` is a `'use client'` component, but Next.js still server-renders it on initial page load. The `'use client'` boundary is required solely to access `useServerInsertedHTML` — **not** because `tasty()` components need the client.
@@ -130,13 +216,13 @@ The nonce is automatically applied to all `<style>` and `<script>` tags injected
 
 Tasty offers several levels of Astro integration. Choose the one that matches your needs:
 
-| Setup                                                     | Config needed | Deduplication                 | Hooks work             | Client JS      |
-| --------------------------------------------------------- | ------------- | ----------------------------- | ---------------------- | -------------- |
-| Zero setup                                                | None          | Per render tree               | Yes (within each tree) | None           |
-| `tastyIntegration({ islands: false })`                    | One line      | Cross-tree                    | Yes                    | None           |
-| `tastyIntegration()`                                      | One line      | Cross-tree                    | Yes                    | Auto-hydration |
-| `tastyIntegration({ css: { mode: 'extract' } })`          | One line      | Cross-tree and cross-page     | Yes                    | Auto-hydration |
-| `tastyIntegration({ islands: false, css: { mode: 'extract' } })` | One line | Cross-tree and cross-page | Yes                    | None           |
+| Setup                                                            | Config needed | Deduplication             | Hooks work             | Client JS      |
+| ---------------------------------------------------------------- | ------------- | ------------------------- | ---------------------- | -------------- |
+| Zero setup                                                       | None          | Per render tree           | Yes (within each tree) | None           |
+| `tastyIntegration({ islands: false })`                           | One line      | Cross-tree                | Yes                    | None           |
+| `tastyIntegration()`                                             | One line      | Cross-tree                | Yes                    | Auto-hydration |
+| `tastyIntegration({ css: { mode: 'extract' } })`                 | One line      | Cross-tree and cross-page | Yes                    | Auto-hydration |
+| `tastyIntegration({ islands: false, css: { mode: 'extract' } })` | One line      | Cross-tree and cross-page | Yes                    | None           |
 
 ### Zero setup (static pages)
 
@@ -235,8 +321,8 @@ This gives the same middleware deduplication and hook support, but ships zero cl
 
 #### Build-wide CSS extraction
 
-Static Astro builds can move repeated Tasty CSS into a content-hashed,
-browser-cacheable asset:
+Static Astro builds can move Tasty CSS into content-hashed, browser-cacheable
+shared and page assets:
 
 ```ts
 export default defineConfig({
@@ -257,14 +343,38 @@ output. Extraction requires Astro 5 or newer and only applies to prerendered
 production pages. Development, preview-time SSR, and on-demand routes continue
 to receive the normal inline `<style data-tasty-ssr>` output.
 
-Extraction moves the largest common block whose position can be preserved on
-every generated page into one stylesheet. Page-only component, global, and raw
-CSS stays inline, so unvisited routes do not receive unrelated styles.
-
-The asset is written under Astro's configured `build.assets` directory (for
-example, `/_astro/tasty.a1b2c3.css`). Links include the configured Astro
-`base`, so nested routes do not need relative-path handling. The content hash
-and output are deterministic for identical builds.
+Extraction writes every artifact emitted by all styled pages to a shared
+stylesheet. Each page's strict set difference is written to a separate page
+stylesheet. The shared link comes first and the page link follows, so shared
+styles form the base cascade and page-only styles can override them. A fully
+shared page omits the empty page stylesheet. If generated pages have no common
+artifacts, each page receives only its page stylesheet.
+
+The shared-base/page-override order is the extraction-mode cascade contract.
+It does not preserve an inline artifact order where a page-only rule originally
+appeared before a shared rule. Use shared styles for defaults and page-only
+styles for overrides.
+
+Extracted CSS preserves resource URLs verbatim. Relative URLs in an inline
+style resolve from the page, but in an extracted stylesheet they resolve from
+the asset directory. Use absolute URLs or data URLs when extraction is enabled.
+Root-relative URLs such as `url(/fonts/brand.woff2)` are also safe while the
+stylesheet stays on the page's origin. The build fails with a clear error if an
+artifact contains a page-relative or fragment-only URL, including URL strings
+in `image-set()`, `image()`, `src()`, and `@import`.
+
+Assets are written under Astro's configured `build.assets` directory (for
+example, `/_astro/tasty.shared.a1b2c3.css` and
+`/_astro/tasty.page.d4e5f6.css`). Links include the configured Astro `base`, so
+nested routes do not need relative-path handling. Content hashes and output are
+deterministic for identical builds. If `build.assetsPrefix` is configured,
+Tasty uses its CSS-specific prefix (or `fallback`) just like Astro-generated
+stylesheets. When that prefix points to a different origin, root-relative
+resources would resolve against the asset origin rather than the page's origin,
+so the build rejects them as well. Tasty compares the prefix with Astro's `site`
+when it is configured; without `site`, an absolute or protocol-relative prefix
+is treated conservatively as cross-origin. Use a fully absolute resource URL in
+that configuration.
 
 ### Manual middleware (advanced)
 
@@ -300,12 +410,13 @@ Astro's `@astrojs/react` renderer calls `renderToString()` for each React compon
 - The middleware reads the full response body, then injects the collected CSS into `</head>` before sending the final HTML.
 - In extraction mode, prerendered responses also carry temporary structured
   artifact metadata. `astro:build:done` uses those collector-provided
-  boundaries to write the shared asset and rewrite generated HTML, then removes
-  the metadata. CSS is never split on newlines or parsed heuristically.
+  boundaries to write shared and page assets and rewrite generated HTML, then
+  removes the metadata. Artifact boundaries are never inferred by splitting or
+  reparsing the generated CSS.
 
 ### CSP nonce
 
-Call `configure({ nonce: '...' })` before any rendering happens. The middleware reads the nonce and applies it to injected `<style>` and `<script>` tags. In extraction mode, page-local inline style tags and the external stylesheet link retain the nonce.
+Call `configure({ nonce: '...' })` before any rendering happens. The middleware reads the nonce and applies it to injected `<style>` and `<script>` tags. In extraction mode, the external stylesheet links retain the nonce.
 
 ---
 
@@ -388,12 +499,13 @@ const stream = await runWithCollector(collector, () =>
 
 ### Entry points
 
-| Import path                                                                         | Description                                                                                                                                                                                                     |
-| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@tenphi/tasty/ssr`                                                                 | Core SSR API: `ServerStyleCollector`, `createServerStyleCollector`, `runWithCollector`, `hydrateTastyClasses`                                                                                                   |
-| `@tenphi/tasty/ssr/next`                                                            | Next.js App Router: `TastyRegistry` component                                                                                                                                                                   |
-| `@tenphi/tasty/ssr/astro`                                                           | Astro: `tastyIntegration`, `tastyMiddleware`                                                                                                                                                                    |
-| `@tenphi/tasty/ssr/astro-client`                                                    | Astro: client-side cache hydration (auto-injected by integration, or import manually)                                                                                                                           |
+| Import path                                                                                                                                                                                | Description                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tenphi/tasty/ssr`                                                                                                                                                                        | Core SSR API: `ServerStyleCollector`, `createServerStyleCollector`, `runWithCollector`, `hydrateTastyClasses`                                                                                                   |
+| `@tenphi/tasty/ssr/next`                                                                                                                                                                   | Next.js App Router: `TastyRegistry` component                                                                                                                                                                   |
+| `@tenphi/tasty/ssr/next-config`                                                                                                                                                            | Next.js config wrapper: shared, content-hashed global stylesheet                                                                                                                                                |
+| `@tenphi/tasty/ssr/astro`                                                                                                                                                                  | Astro: `tastyIntegration`, `tastyMiddleware`                                                                                                                                                                    |
+| `@tenphi/tasty/ssr/astro-client`                                                                                                                                                           | Astro: client-side cache hydration (auto-injected by integration, or import manually)                                                                                                                           |
 | `@tenphi/tasty/ssr/astro-middleware`<br>`@tenphi/tasty/ssr/astro-middleware-static`<br>`@tenphi/tasty/ssr/astro-middleware-extract`<br>`@tenphi/tasty/ssr/astro-middleware-extract-static` | Astro: the middleware entrypoints `tastyIntegration()` registers via `addMiddleware()`. Exported so Astro can resolve them by specifier; you should not import them. For manual setups use `tastyMiddleware()`. |
 
 ### `ServerStyleCollector`
@@ -414,7 +526,7 @@ Constructor: `new ServerStyleCollector(namePrefix?)`, or use the `createServerSt
 | `allocateCounterStyleName(providedName?)`  | Allocate a counter-style name. Returns `providedName` if given, otherwise generates one using `${namePrefix}c${counter}` (e.g. `tc0`, `tc1`, ...).                                                                                                                         |
 | `collectGlobalStyles(key, css)`            | Record global styles (from `useGlobalStyles`). Deduplicated by key.                                                                                                                                                                                                        |
 | `collectRawCSS(key, css)`                  | Record raw CSS text (from `useRawCSS`). Deduplicated by key.                                                                                                                                                                                                               |
-| `collectInternals()`                       | Collect internal `@property` rules, `:root` token defaults, `@font-face`, and `@counter-style` rules from the global config. Called automatically on first chunk collection; idempotent.                                                                                   |
+| `collectInternals()`                       | Collect eager configured globals: `@property`, `:root` tokens and presets, `@font-face`, `@counter-style`, `@function`, and `globalStyles`. Called automatically on first chunk collection; idempotent.                                                                    |
 | `getCSS()`                                 | Get all collected CSS as a single string. For non-streaming SSR.                                                                                                                                                                                                           |
 | `flushCSS()`                               | Get only CSS collected since the last flush. For streaming SSR.                                                                                                                                                                                                            |
 | `getRenderedClassNames()`                  | Get the list of class names rendered so far. Serialized to `window.__TASTY__` for client hydration via `hydrateTastyClasses()`.                                                                                                                                            |
@@ -423,10 +535,18 @@ Constructor: `new ServerStyleCollector(namePrefix?)`, or use the `createServerSt
 
 Next.js App Router component. Props:
 
-| Prop            | Type        | Default  | Description                                      |
-| --------------- | ----------- | -------- | ------------------------------------------------ |
-| `children`      | `ReactNode` | required | Application tree                                 |
-| `transferCache` | `boolean`   | `true`   | Embed cache state script for zero-cost hydration |
+| Prop               | Type              | Default   | Description                                                               |
+| ------------------ | ----------------- | --------- | ------------------------------------------------------------------------- |
+| `children`         | `ReactNode`       | required  | Application tree                                                          |
+| `transferCache`    | `boolean`         | `true`    | Embed cache state script for zero-cost hydration                          |
+| `sharedStylesheet` | `string \| false` | generated | Override the shared URL, or disable generated shared CSS for the registry |
+
+### `withTastyNext(options)`
+
+Next.js configuration wrapper exported from
+`@tenphi/tasty/ssr/next-config`. It generates a shared stylesheet from eager
+Tasty configuration artifacts and wires its URL and immutable cache header
+into the Next config. Route-specific CSS continues through `TastyRegistry`.
 
 ### `tastyIntegration(options?)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",
@@ -52,6 +52,11 @@
       "import": "./dist/ssr/next.js",
       "default": "./dist/ssr/next.js"
     },
+    "./ssr/next-config": {
+      "types": "./dist/ssr/next-config.d.ts",
+      "import": "./dist/ssr/next-config.js",
+      "default": "./dist/ssr/next-config.js"
+    },
     "./ssr/astro": {
       "types": "./dist/ssr/astro.d.ts",
       "import": "./dist/ssr/astro.js",
@@ -174,6 +179,7 @@
     "@types/react-dom": "^19.0.0",
     "@vitest/browser-playwright": "^4.1.10",
     "astro": "^5.18.2",
+    "esbuild": "^0.27.7",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
     "jiti": "^2.6.1",
@@ -249,6 +255,8 @@
     "bench:browser": "vitest bench --project browser",
     "bench:overhead": "vitest bench --config vitest.production-browser-bench.config.ts src/tasty-overhead.bench.tsx",
     "bench:injection": "vitest bench --config vitest.production-browser-bench.config.ts src/tasty-injection.bench.ts",
+    "bench:interaction": "vitest bench --config vitest.production-browser-bench.config.ts src/tasty-interaction.bench.tsx",
+    "bench:cold-start": "node scripts/cold-start/index.mjs",
     "changeset": "changeset",
     "version": "changeset version",
     "release": "changeset publish",