@tenphi/tasty 3.6.0 → 3.8.0

package/docs/ai-agents.md

@@ -50,6 +50,8 @@ Prefer the Tasty shorthand over its CSS equivalents:
 | `hide: true`                             | `display: 'none'`                                                                     |
 | `flexGrow` / `flexShrink` / `flexBasis`  | `flex`                                                                                |
 
+Use logical category styles when layout must follow writing mode or direction: `blockSize`/`inlineSize`, `blockPadding`/`inlinePadding`, `blockMargin`/`inlineMargin`, `blockInset`/`inlineInset`, `blockScrollMargin`/`inlineScrollMargin`, `blockScrollPadding`/`inlineScrollPadding`, and `blockBorder`/`inlineBorder`. Use `start`/`end` value modifiers; do not replace them with physical sides. Native logical CSS properties remain valid as ordinary keys when an individual declaration is needed.
+
 The last row goes the other way — longhands over the shorthand — because `flex` is lossy: it resets the components you omit to non-initial values (`flex: '0'` silently sets `flex-basis: 0%`) and cannot express `flexShrink: 0` at all. The longhands also carry separate state maps.
 
 ## 3. Values
@@ -86,7 +88,7 @@ Prefer units over raw pixels: `8px` → `1x` … `64px` → `8x`; `radius: '6px'
 
 ### `true`
 
-`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `fade`, `preset`, `font`, `scrollbar`, `hide`. Anywhere else it is an error.
+`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `fade`, `preset`, `font`, `scrollbar`, `scrollMargin`, `scrollPadding`, and the enhanced logical category styles listed above, plus `hide`. Anywhere else it is an error.
 
 ### `!important`
 
@@ -100,9 +102,11 @@ A value is `[values…] [modifiers…]`, and several groups can be comma-separat
 | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
 | `padding`, `margin`, `inset`, `fade` | `top` `right` `bottom` `left`                                                                              |
 | `border`                             | the four directions + `solid` `dashed` `dotted` `double` `groove` `ridge` `inset` `outset` `none` `hidden` |
+| logical axis spacing/inset styles    | `start` `end`                                                                                              |
+| `blockBorder`, `inlineBorder`         | `start` `end` + the border style keywords above                                                            |
 | `outline`                            | the style keywords above                                                                                   |
 | `radius`                             | `top` `right` `bottom` `left` + shapes `round` `ellipse` `leaf` `backleaf`                                 |
-| `width`, `height`                    | `min` `max` `fixed`                                                                                        |
+| `width`, `height`, `blockSize`, `inlineSize` | `min` `max` `fixed`                                                                                |
 | `flow`                               | `row` `column` `row-reverse` `column-reverse` `wrap` `nowrap` `dense`                                      |
 | `overflow`                           | `visible` `hidden` `scroll` `clip` `auto` `overlay`                                                        |
 | `position`                           | `static` `relative` `absolute` `fixed` `sticky`                                                            |
@@ -118,7 +122,7 @@ Directional modifiers beat placeholder zeros:
 - ❌ `padding: '2x 4x top right'` — a directional group takes one value, so `4x` is dropped → ✅ `padding: '2x top, 4x right'`
 - ❌ `fade: '3x 1x top bottom'` → ✅ `fade: '3x top, 1x bottom'`
 
-Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, `tabSize`, `paddingInline`, `paddingBlock`. `fill` and `color` take a color (plus `none` / `transparent`); `caretColor` and `accentColor` take a color only.
+Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, and `tabSize`. Logical axis category styles accept one or two values in start/end order and the `start`, `end`, and `longhand` modifiers. `fill` and `color` take a color (plus `none` / `transparent`); `caretColor` and `accentColor` take a color only.
 
 ### `transition`
 
@@ -214,6 +218,7 @@ The selector must be a string literal and valid CSS. Values must be static — s
 
 - Token, preset, recipe, unit and `@alias` names exist in the project config.
 - Tasty shorthand chosen over CSS longhands; `flexGrow`/`flexShrink`/`flexBasis` over `flex`; `hide: true` over `display: 'none'`.
+- Logical category styles keep native `block`/`inline` declarations and accept `start`/`end`, never physical direction modifiers.
 - Colors are `#tokens`, not hex/rgb/oklch/named; `$prop` not `var(--prop)`.
 - Spacing uses `x`/`r`/`bw`/`ow` units; math uses `(…)`, not `calc(…)`.
 - `true` only on the properties that accept it; no `!important`.

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/methodology.md

@@ -122,10 +122,10 @@ Tasty exports predefined style prop lists that group properties by role. Use the
 | Preset             | Properties                                                                                                                                                                     | Typical use                                   |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
 | `FLOW_STYLES`      | flow, gap, columnGap, rowGap, align, justify, placeItems, placeContent, alignItems, alignContent, justifyItems, justifyContent, gridColumns, gridRows, gridTemplate, gridAreas | Layout containers (`Space`, `Grid`)           |
-| `POSITION_STYLES`  | gridArea, gridColumn, gridRow, order, placeSelf, alignSelf, justifySelf, zIndex, margin, inset, position                                                                       | Positioned elements (`Button`, `Badge`)       |
-| `DIMENSION_STYLES` | width, height, flexBasis, flexGrow, flexShrink, flex                                                                                                                           | Sized elements                                |
+| `POSITION_STYLES`  | gridArea, gridColumn, gridRow, order, placeSelf, alignSelf, justifySelf, zIndex, physical/logical margin, inset, scroll margin/padding, position                                 | Positioned elements (`Button`, `Badge`)       |
+| `DIMENSION_STYLES` | width, height, blockSize, inlineSize, flexBasis, flexGrow, flexShrink, flex                                                                                                    | Sized elements                                |
 | `COLOR_STYLES`     | color, fill, fade, image                                                                                                                                                       | Color-customizable elements                   |
-| `BLOCK_STYLES`     | padding, paddingInline, paddingBlock, overflow, scrollbar, textAlign, border, radius, shadow, outline                                                                          | Block-level containers                        |
+| `BLOCK_STYLES`     | padding, blockPadding, inlinePadding, overflow, scrollbar, textAlign, border, blockBorder, inlineBorder, radius, shadow, outline                                               | Block-level containers                        |
 | `CONTAINER_STYLES` | All of the above combined (+ BASE_STYLES)                                                                                                                                      | Fully flexible containers                     |
 | `OUTER_STYLES`     | POSITION_STYLES + DIMENSION_STYLES + block outer (border, radius, shadow, outline)                                                                                             | Components whose outer shell is customizable  |
 | `INNER_STYLES`     | BASE_STYLES + COLOR_STYLES + block inner (padding, overflow, scrollbar) + FLOW_STYLES                                                                                          | Components whose inner layout is customizable |

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)
 
@@ -413,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`
@@ -439,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()`.                                                                                                                                            |
@@ -448,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/docs/styles.md

@@ -20,9 +20,10 @@ Use these instead of their raw CSS counterparts:
 |-----|------------|
 | `fill` | `backgroundColor`, `background` |
 | `image` | `backgroundImage` |
-| `padding` (with direction modifiers) | `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` |
-| `margin` (with direction modifiers) | `marginTop`, `marginRight`, `marginBottom`, `marginLeft` |
-| `width` (with `min`/`max` modifiers) | `minWidth`, `maxWidth` |
+| `padding` (with physical direction modifiers) | `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` |
+| `margin` (with physical direction modifiers) | `marginTop`, `marginRight`, `marginBottom`, `marginLeft` |
+| Logical block/inline category styles (with `start`/`end` modifiers) | Native logical axis/edge declarations |
+| `width` / `blockSize` / `inlineSize` (with `min`/`max` modifiers) | Their separate min/max declarations when one state map is sufficient |
 | `height` (with `min`/`max` modifiers) | `minHeight`, `maxHeight` |
 | `border` | `borderColor`, `borderWidth`, `borderStyle` |
 | `radius` | `borderRadius` |
@@ -125,9 +126,7 @@ A group that names *no* direction keeps plain CSS shorthand order, which is unam
 
 Later comma-separated groups override earlier groups for conflicting directions.
 
-Individual props `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, `paddingBlock`, `paddingInline` are supported but `padding` with modifiers is recommended.
-
-**Priority:** `padding` < `paddingBlock`/`paddingInline` < `paddingTop`/`paddingRight`/`paddingBottom`/`paddingLeft`
+Individual physical props `paddingTop`, `paddingRight`, `paddingBottom`, and `paddingLeft` are supported, but `padding` with modifiers is recommended. Use `blockPadding` or `inlinePadding` for an enhanced logical-axis shorthand; native declarations such as `paddingInlineStart` remain ordinary CSS properties. See [Logical properties](#logical-properties).
 
 ### `margin`
 
@@ -153,9 +152,7 @@ The [one-value-per-directional-group rule](#padding) from `padding` applies here
 
 Later comma-separated groups override earlier groups for conflicting directions.
 
-Individual props `marginTop`, `marginRight`, `marginBottom`, `marginLeft`, `marginBlock`, `marginInline` are supported but `margin` with modifiers is recommended.
-
-**Priority:** `margin` < `marginBlock`/`marginInline` < `marginTop`/`marginRight`/`marginBottom`/`marginLeft`
+Individual physical props `marginTop`, `marginRight`, `marginBottom`, and `marginLeft` are supported, but `margin` with modifiers is recommended. Use `blockMargin` or `inlineMargin` for an enhanced logical-axis shorthand; native declarations such as `marginInlineStart` remain ordinary CSS properties. See [Logical properties](#logical-properties).
 
 ### `width`
 
@@ -234,9 +231,44 @@ second to every side they span.
 
 Later comma-separated groups override earlier groups for conflicting directions.
 
-Individual props `top`, `right`, `bottom`, `left`, `insetBlock`, `insetInline` are supported. When only individual direction props are used (without `inset`), individual CSS properties are output for correct cascade behavior with state overrides.
+Individual physical props `top`, `right`, `bottom`, and `left` are supported. When only those props are used (without `inset`), individual CSS properties are output for correct cascade behavior with state overrides. Use `blockInset` or `inlineInset` for logical axes; native declarations such as `insetInlineStart` remain ordinary CSS properties.
+
+### Logical properties
+
+Tasty provides one enhanced handler for each logical axis/category pair. Each handler emits native logical CSS instead of converting values to `top`, `right`, `bottom`, `left`, `width`, or `height`. The browser therefore resolves `block`, `inline`, `start`, and `end` from the element's `writingMode` and `direction`.
+
+```jsx
+styles: {
+  direction: 'rtl',
+  inlinePadding: '1x start, 2x end',
+  inlineBorder: '1bw solid #accent start',
+  blockInset: '0 end',
+}
+```
+
+An axis handler accepts one value for both edges or two values in logical **start/end** order. Use `start` and `end` modifiers, with comma-separated groups for different edge values. Unspecified padding, margin, and scroll edges reset to `0`; unspecified inset edges reset to `auto`. The `longhand` modifier emits the two native start/end declarations.
+
+| Category | Block axis | Inline axis |
+|----------|------------|-------------|
+| Size | `blockSize` | `inlineSize` |
+| Padding | `blockPadding` | `inlinePadding` |
+| Margin | `blockMargin` | `inlineMargin` |
+| Inset | `blockInset` | `inlineInset` |
+| Scroll margin | `blockScrollMargin` | `inlineScrollMargin` |
+| Scroll padding | `blockScrollPadding` | `inlineScrollPadding` |
+| Border | `blockBorder` | `inlineBorder` |
+
+`blockSize` and `inlineSize` use the same enhanced one/two/three-value and `min`/`max`/`fixed` syntax as `width`. Separate `minBlockSize`, `maxBlockSize`, `minInlineSize`, and `maxInlineSize` declarations override constraints produced by that shorthand.
+
+`blockBorder` and `inlineBorder` use the same width/style/color parsing and defaults as `border`, including `1bw`, color tokens, and `true`. Logical padding, margin, scroll margin, and scroll padding default to `1x` for `true`; logical inset defaults to `0`.
+
+Native logical CSS names—such as `paddingInlineStart`, `borderBlockColor`, and `borderStartStartRadius`—remain available as ordinary CSS properties. They support Tasty tokens and units through the normal value parser, but do not get category defaults or directional shorthand behavior.
+
+The physical `scrollMargin` and `scrollPadding` shorthands support the same values and physical direction modifiers as `padding`. Their logical counterparts stay in separate axis handlers.
+
+`writingMode`, `direction`, and `textOrientation` are standard CSS control properties. They use Tasty's normal value parser and need no special handler.
 
-**Priority:** `inset` < `insetBlock`/`insetInline` < `top`/`right`/`bottom`/`left`
+Avoid setting physical and logical declarations that resolve to the same edge in one style block. Tasty keeps them separate and lets the native CSS cascade resolve the overlap, whose result also depends on writing mode and direction.
 
 ---