@tenphi/tasty 0.0.0-snapshot.27b6708 → 0.0.0-snapshot.28eb83c

package/docs/ssr.md

@@ -1,16 +1,22 @@
 # Server-Side Rendering (SSR)
 
-Tasty supports server-side rendering with zero-cost client hydration. This does **not** introduce a separate styling engine: SSR uses the same runtime `tasty()` pipeline you already use on the client, then adds server-side CSS collection and client-side cache hydration. Your existing `tasty()` components work unchanged, and SSR remains opt-in with no per-component modifications. For the broader docs map, see the [Docs Hub](README.md).
+Tasty supports server-side rendering with zero-cost client hydration. This does **not** introduce a separate styling engine: `tasty()` uses the same rendering pipeline on the server and in the browser, while the SSR integrations add server-side CSS collection and client-side cache hydration. Your existing `tasty()` components work unchanged, and SSR remains opt-in with no per-component modifications. For the broader docs map, see the [Docs Hub](README.md).
+
+## Zero-runtime terminology
+
+Zero-runtime delivery is an outcome, not an alias for `tastyStatic()`. When `tasty()` components render only on the server, their CSS is delivered with the HTML and no Tasty styling runtime is shipped to the browser. Astro's `tastyIntegration({ islands: false })` is the explicit integration for this setup. Server-only Next.js React Server Components follow the same architecture, although you should verify the generated output for your deployment.
+
+`tastyStatic()` reaches the same client-side outcome by extracting CSS during the build instead of during React rendering. Use it when extraction must happen before rendering or when the consumer is not React; see [Build-Time Extraction](tasty-static.md).
 
 ---
 
 ## Requirements
 
-| Dependency | Version | Required for |
-|---|---|---|
-| `react` | >= 18 | All SSR entry points (matches the current peer dependency of `@tenphi/tasty`) |
-| `next` | >= 13 | Next.js integration (`@tenphi/tasty/ssr/next`) — App Router with `useServerInsertedHTML` |
-| Node.js | >= 20 | Generic / streaming SSR (`@tenphi/tasty/ssr`) — uses `node:async_hooks` for `AsyncLocalStorage` |
+| Dependency | Version | Required for                                                                                    |
+| ---------- | ------- | ----------------------------------------------------------------------------------------------- |
+| `react`    | >= 18   | All SSR entry points (matches the current peer dependency of `@tenphi/tasty`)                   |
+| `next`     | >= 13   | Next.js integration (`@tenphi/tasty/ssr/next`) — App Router with `useServerInsertedHTML`        |
+| Node.js    | >= 20   | Generic / streaming SSR (`@tenphi/tasty/ssr`) — uses `node:async_hooks` for `AsyncLocalStorage` |
 
 The Astro integration (`@tenphi/tasty/ssr/astro`) has no additional dependencies beyond `react`.
 
@@ -80,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.
@@ -122,13 +214,15 @@ The nonce is automatically applied to all `<style>` and `<script>` tags injected
 
 ## Astro
 
-Tasty offers three levels of Astro integration. Choose the one that matches your needs:
+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 |
+| 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)
 
@@ -225,6 +319,63 @@ export default defineConfig({
 
 This gives the same middleware deduplication and hook support, but ships zero client-side JavaScript. No class-list `<script>` is emitted.
 
+#### Build-wide CSS extraction
+
+Static Astro builds can move Tasty CSS into content-hashed, browser-cacheable
+shared and page assets:
+
+```ts
+export default defineConfig({
+  integrations: [
+    react(),
+    tastyIntegration({
+      islands: false,
+      css: {
+        mode: 'extract',
+      },
+    }),
+  ],
+});
+```
+
+`css.mode` defaults to `'inline'`, so existing projects keep their current
+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 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)
 
 If you need to compose Tasty's middleware with other middleware (e.g., via `sequence()`), use `tastyMiddleware()` directly:
@@ -234,10 +385,7 @@ If you need to compose Tasty's middleware with other middleware (e.g., via `sequ
 import { sequence } from 'astro:middleware';
 import { tastyMiddleware } from '@tenphi/tasty/ssr/astro';
 
-export const onRequest = sequence(
-  tastyMiddleware(),
-  myOtherMiddleware,
-);
+export const onRequest = sequence(tastyMiddleware(), myOtherMiddleware);
 ```
 
 For island hydration with manual middleware, import the client module in a shared entry point or in each island:
@@ -260,10 +408,15 @@ Astro's `@astrojs/react` renderer calls `renderToString()` for each React compon
 - **Static components** (no `client:*`): Styles are collected during `renderToString` and injected into `</head>` as a single `<style>` tag. No JavaScript is shipped.
 - **Islands** (`client:load`, `client:visible`, etc.): Styles are collected during SSR the same way. On the client, the hydration script (auto-injected by `tastyIntegration()` or manually via `@tenphi/tasty/ssr/astro-client`) reads the class list from `window.__TASTY__` and pre-populates the injector's rules map. The island's `computeStyles()` calls see the class names as already registered and skip the pipeline during hydration.
 - 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 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.
+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.
 
 ---
 
@@ -285,9 +438,7 @@ import { hydrateRoot } from 'react-dom/client';
 
 const collector = createServerStyleCollector();
 
-const html = await runWithCollector(collector, () =>
-  renderToString(<App />)
-);
+const html = await runWithCollector(collector, () => renderToString(<App />));
 
 const css = collector.getCSS();
 const classNames = collector.getRenderedClassNames();
@@ -338,7 +489,7 @@ const stream = await runWithCollector(collector, () =>
         `<script>(window.__TASTY__=window.__TASTY__||[]).push(${JSON.stringify(classNames)})</script>`,
       );
     },
-  })
+  }),
 );
 ```
 
@@ -348,13 +499,14 @@ 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) |
-| `@tenphi/tasty/ssr/astro-middleware`<br>`@tenphi/tasty/ssr/astro-middleware-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()`. |
+| 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`
 
@@ -362,47 +514,55 @@ Server-safe style collector. One instance per request.
 
 Constructor: `new ServerStyleCollector(namePrefix?)`, or use the `createServerStyleCollector(namePrefix?)` factory. The optional `namePrefix` overrides the value from `configure({ namePrefix })`; in normal usage you pass nothing and let the global config drive it. See [Configuration: Name prefix](configuration.md#name-prefix).
 
-| Method | Description |
-|---|---|
-| `allocateClassName(cacheKey)` | Allocate a deterministic, content-hashed class name for a cache key (e.g. `t1a2b3` with the default prefix). The same `cacheKey` always produces the same class name on server and client when both share the same `namePrefix`. Returns `{ className, isNewAllocation }`. |
-| `collectChunk(cacheKey, className, rules)` | Record CSS rules for a chunk. Deduplicated by `cacheKey`. |
-| `collectKeyframes(name, css)` | Record a `@keyframes` rule. Deduplicated by name. |
-| `allocateKeyframeName(providedName?)` | Allocate a keyframe name. Returns `providedName` if given, otherwise generates one using `${namePrefix}k${counter}` (e.g. `tk0`, `tk1`, ...). |
-| `collectProperty(name, css)` | Record a `@property` rule. Deduplicated by name. |
-| `collectFontFace(key, css)` | Record a `@font-face` rule. Deduplicated by content hash. |
-| `collectCounterStyle(name, css)` | Record a `@counter-style` rule. Deduplicated by name. |
-| `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. |
-| `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()`. |
+| Method                                     | Description                                                                                                                                                                                                                                                                |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allocateClassName(cacheKey)`              | Allocate a deterministic, content-hashed class name for a cache key (e.g. `t1a2b3` with the default prefix). The same `cacheKey` always produces the same class name on server and client when both share the same `namePrefix`. Returns `{ className, isNewAllocation }`. |
+| `collectChunk(cacheKey, className, rules)` | Record CSS rules for a chunk. Deduplicated by `cacheKey`.                                                                                                                                                                                                                  |
+| `collectKeyframes(name, css)`              | Record a `@keyframes` rule. Deduplicated by name.                                                                                                                                                                                                                          |
+| `allocateKeyframeName(providedName?)`      | Allocate a keyframe name. Returns `providedName` if given, otherwise generates one using `${namePrefix}k${counter}` (e.g. `tk0`, `tk1`, ...).                                                                                                                              |
+| `collectProperty(name, css)`               | Record a `@property` rule. Deduplicated by name.                                                                                                                                                                                                                           |
+| `collectFontFace(key, css)`                | Record a `@font-face` rule. Deduplicated by content hash.                                                                                                                                                                                                                  |
+| `collectCounterStyle(name, css)`           | Record a `@counter-style` rule. Deduplicated by name.                                                                                                                                                                                                                      |
+| `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 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()`.                                                                                                                                            |
 
 ### `TastyRegistry`
 
 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?)`
 
 Astro integration factory. Registers middleware and optionally injects client hydration.
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `islands` | `boolean` | `true` | When `true`, injects client hydration script and enables `transferCache`. When `false`, no client JS is shipped. |
+| Option    | Type      | Default | Description                                                                                                      |
+| --------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
+| `islands` | `boolean` | `true`  | When `true`, injects client hydration script and enables `transferCache`. When `false`, no client JS is shipped. |
 
 ### `tastyMiddleware(options?)`
 
 Astro middleware factory. Use for manual middleware composition.
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `transferCache` | `boolean` | `true` | Embed cache state script for island hydration |
+| Option          | Type      | Default | Description                                   |
+| --------------- | --------- | ------- | --------------------------------------------- |
+| `transferCache` | `boolean` | `true`  | Embed cache state script for island hydration |
 
 ### `hydrateTastyClasses(classes?)`
 
@@ -424,11 +584,11 @@ The `TastyRegistry` or `tastyIntegration` is missing. Ensure your layout wraps t
 
 Class names are deterministic for the same render order. If you see mismatches, ensure `hydrateTastyClasses()` runs before React hydration. For Next.js, this is automatic. For Astro with `tastyIntegration()`, this is also automatic. For manual Astro middleware setups, import `@tenphi/tasty/ssr/astro-client` in your island components. For custom setups, call `hydrateTastyClasses()` before `hydrateRoot()`.
 
-Class names are also derived from the *resolved* styles, so the server and the client must configure Tasty identically. Anything that changes what a component's styles resolve to will produce a mismatch if it is registered on only one side — `namePrefix`, `recipes`, `handlers`, and the `propHandlers` / `baseStyleProps` extension points described in [Plugins](plugins.md). Call the same `configure()` on both; global CSS is deduplicated automatically, so no `typeof window` guard is needed.
+Class names are also derived from the _resolved_ styles, so the server and the client must configure Tasty identically. Anything that changes what a component's styles resolve to will produce a mismatch if it is registered on only one side — `namePrefix`, `recipes`, `handlers`, and the `propHandlers` / `baseStyleProps` extension points described in [Plugins](plugins.md). Call the same `configure()` on both; global CSS is deduplicated automatically, so no `typeof window` guard is needed.
 
 ### Styles duplicated after hydration
 
-**Global CSS** (`:root` tokens, `@property`, `globalStyles`, `@font-face`, `@counter-style`) configured via `configure()` is automatically deduplicated. When Tasty detects `<style data-tasty-ssr>` in the document, it skips client-side injection of globals that were already rendered by the SSR collector. This means `configure()` can be called with the full config on both server and client — no `typeof window === 'undefined'` guard is needed.
+**Global CSS** (`:root` tokens, `@property`, `globalStyles`, `@font-face`, `@counter-style`, `@function`) configured via `configure()` is automatically deduplicated. When Tasty detects an inline or extracted `[data-tasty-ssr]` stylesheet in the document, it skips client-side injection of globals that were already rendered by the SSR collector. This means `configure()` can be called with the full config on both server and client — no `typeof window === 'undefined'` guard is needed.
 
 **Component CSS**: SSR `<style data-tasty-ssr>` tags remain in the DOM. The client injector creates separate `<style>` elements for any new styles. SSR styles are never modified or removed by the client. If this is a concern for very large apps, you can remove the SSR style tags and hydration scripts manually after hydration:
 
@@ -440,11 +600,9 @@ hydrateRoot(root, <App />);
 
 // Optional: remove SSR style tags and class-list scripts after hydration
 document.querySelectorAll('style[data-tasty-ssr]').forEach((el) => el.remove());
-document
-  .querySelectorAll('script')
-  .forEach((el) => {
-    if (el.textContent?.includes('__TASTY__')) el.remove();
-  });
+document.querySelectorAll('script').forEach((el) => {
+  if (el.textContent?.includes('__TASTY__')) el.remove();
+});
 ```
 
 ### `AsyncLocalStorage` not available

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.
 
 ---