@tenphi/tasty 0.0.0-snapshot.bbd10c7 → 0.0.0-snapshot.bbfcd75

package/docs/debug.md

@@ -6,18 +6,17 @@ Runtime CSS inspection and diagnostics for the Tasty styling system. Inspect inj
 
 ## Overview
 
-`tastyDebug` is a diagnostic object that exposes Tasty's runtime CSS state. It is designed for development use but can be manually installed in production for debugging.
-
-In development mode (`isDevEnv()` returns `true`), `tastyDebug` is automatically installed on `window.tastyDebug`. In production, install it manually when needed.
+`tastyDebug` is a diagnostic object that exposes Tasty's runtime CSS state. It is designed for development use and can be installed on `window` explicitly when needed.
 
 All methods **log to the console by default**. Pass `{ raw: true }` to suppress logging and only return data.
 
+> **Note (2.0.0+):** Class names use a content-addressed base36 hash format (e.g. `t3a5f`) instead of the previous sequential `t{number}` format. Cross-environment hydration reads the rendered class list from `window.__TASTY__` (the legacy `window.__TASTY_SSR_CACHE__` global was removed in 2.0.0).
+
 ---
 
 ## Quick Start
 
 ```typescript
-// Auto-installed in dev mode. Otherwise:
 import { tastyDebug } from '@tenphi/tasty';
 tastyDebug.install();
 
@@ -52,6 +51,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
@@ -66,18 +78,18 @@ Retrieves CSS text for a given target. Logs the result with rule count and size.
 |---|---|
 | `'all'` | All tasty CSS (component + global + raw) |
 | `'active'` | CSS for classes currently in the DOM |
-| `'unused'` | CSS with refCount = 0 (cached but not used) |
+| `'unused'` | CSS for injected classes no element carries (cached but not rendered) |
 | `'global'` | Only global CSS (from `injectGlobal`) |
 | `'page'` | All CSS on the page (including non-tasty) |
-| `'t42'` | CSS for a specific tasty class |
-| `['t0', 't5']` | CSS for multiple tasty classes |
+| `'t3a5f'` | CSS for a specific tasty class (class names are `t` + base36 hash) |
+| `['t3a5f', 't9k2']` | CSS for multiple tasty classes |
 | `'.my-button'` | CSS affecting a DOM element (by selector) |
 | `element` | CSS affecting a DOM element (by reference) |
 
 **Extra options:**
 
 ```typescript
-interface CssOptions extends DebugOptions {
+interface CSSOptions extends DebugOptions {
   prettify?: boolean; // Format output (default: true)
   source?: boolean;   // Read original CSS instead of live CSSOM (default: false, dev-mode only)
 }
@@ -88,11 +100,11 @@ interface CssOptions extends DebugOptions {
 tastyDebug.css('active');
 
 // Specific class, silent
-const css = tastyDebug.css('t42', { raw: true });
+const css = tastyDebug.css('t3a5f', { raw: true });
 
 // Compare original vs browser-parsed CSS (dev mode only)
-tastyDebug.css('t42');                    // live CSSOM
-tastyDebug.css('t42', { source: true }); // original output
+tastyDebug.css('t3a5f');                    // live CSSOM
+tastyDebug.css('t3a5f', { source: true }); // original output
 
 // Shadow DOM
 tastyDebug.css('all', { root: shadowRoot });
@@ -109,14 +121,14 @@ Inspects a DOM element and returns detailed information about its tasty styles,
 ```typescript
 interface InspectResult {
   element?: Element | null;
-  classes: string[];    // Tasty classes on the element
-  chunks: ChunkInfo[];  // Chunk assignment per class
-  css: string;          // Prettified CSS
-  size: number;         // CSS size in characters
-  rules: number;        // Number of CSS rule blocks
+  classes: string[];          // Tasty classes on the element
+  chunks: DebugChunkInfo[];   // Chunk assignment per class
+  css: string;                // Prettified CSS
+  size: number;               // CSS size in characters
+  rules: number;              // Number of CSS rule blocks
 }
 
-interface ChunkInfo {
+interface DebugChunkInfo {
   className: string;
   chunkName: string | null; // e.g., 'appearance', 'font', 'dimension'
 }
@@ -125,11 +137,11 @@ interface ChunkInfo {
 ```typescript
 tastyDebug.inspect('.my-card');
 // Logs: inspect div — 3 classes, 5 rules, 1.2KB
-//       Chunks: t3→appearance, t7→font, t12→dimension
+//       Chunks: t3a5f→appearance, t9k2→font, tb71→dimension
 
 // Silent
 const result = tastyDebug.inspect('.my-card', { raw: true });
-console.log(result.classes);  // ['t3', 't7', 't12']
+console.log(result.classes);  // ['t3a5f', 't9k2', 'tb71']
 console.log(result.rules);    // 5
 ```
 
@@ -239,7 +251,9 @@ tastyDebug.cache();
 
 ### `cleanup(opts?): void`
 
-Forces immediate cleanup of all unused styles (those with `refCount = 0`).
+Removes every injected style that is neither carried by an element nor pinned by
+an outstanding `inject()` handle — the same set `summary()` reports as unused.
+Equivalent to `gc({ force: true })`.
 
 ```typescript
 tastyDebug.cleanup();
@@ -260,7 +274,7 @@ tastyDebug.help();
 
 ### `install(): void`
 
-Attaches `tastyDebug` to `window.tastyDebug`. Called automatically in development mode.
+Attaches `tastyDebug` to `window.tastyDebug`.
 
 ```typescript
 import { tastyDebug } from '@tenphi/tasty';
@@ -291,10 +305,10 @@ tastyDebug.summary({ root: shadowRoot });
 tastyDebug.inspect('.my-button');
 
 // 2. See CSS for a specific class
-tastyDebug.css('t3');
+tastyDebug.css('t3a5f');
 
 // 3. Compare original vs browser-parsed (dev mode)
-tastyDebug.css('t3', { source: true });
+tastyDebug.css('t3a5f', { source: true });
 ```
 
 ### Checking cache efficiency

package/docs/design-system.md

@@ -1,8 +1,8 @@
 # Building a Design System
 
-This guide walks through building a design-system styling layer on top of Tasty — defining tokens, state aliases, recipes, primitive components, and compound components with sub-elements.
+This guide shows how to build shared React components whose styles stay predictable as states, variants, themes, and responsive rules accumulate. You will define tokens, state aliases, recipes, primitive APIs, and compound components with sub-elements.
 
-It assumes you have already decided to adopt Tasty. The goal is not just to centralize tokens, but to define a styling language whose component states resolve deterministically across variants, responsive rules, and sub-elements. For evaluation criteria, audience fit, and incremental adoption phases, see the [Adoption Guide](adoption.md). For the recommended component patterns and mental model, see [Methodology](methodology.md).
+It assumes you have already decided to adopt Tasty. The goal is not only to centralize values, but to give your design system one state model and a governed component-facing styling API. For evaluation criteria and incremental rollout, see the [Adoption Guide](adoption.md). For the recommended component architecture, see [Methodology](methodology.md).
 
 ---
 
@@ -43,8 +43,8 @@ configure({
     '#border': '#e0e0e0',
 
     // Unit values
-    '$gap': '8px',
-    '$radius': '4px',
+    $gap: '8px',
+    $radius: '4px',
     '$border-width': '1px',
     '$outline-width': '2px',
   },
@@ -84,35 +84,65 @@ configure({
 
 ### Typography presets
 
-Use `generateTypographyTokens()` to create typography tokens from your own presets, then pass them to `configure({ tokens })`:
+Pass typography presets directly to `configure()` — they are converted to tokens automatically:
 
 ```tsx
-import { configure, generateTypographyTokens } from '@tenphi/tasty';
+import { configure } from '@tenphi/tasty';
 
-const typographyTokens = generateTypographyTokens({
-  h1: { fontSize: '2rem', lineHeight: '1.2', letterSpacing: '-0.02em', fontWeight: 700 },
-  t2: { fontSize: '0.875rem', lineHeight: '1.5', letterSpacing: 'normal', fontWeight: 400 },
+configure({
+  presets: {
+    h1: {
+      fontSize: '2rem',
+      lineHeight: '1.2',
+      letterSpacing: '-0.02em',
+      fontWeight: 700,
+    },
+    t2: {
+      fontSize: '0.875rem',
+      lineHeight: '1.5',
+      letterSpacing: 'normal',
+      fontWeight: 400,
+    },
+  },
 });
+```
 
+Preset values support state maps for responsive or theme-aware typography:
+
+```tsx
 configure({
-  tokens: {
-    ...typographyTokens,
+  presets: {
+    t2: {
+      fontSize: '0.875rem',
+      lineHeight: '1.5',
+      fontWeight: { '': 400, '@dark': 300 },
+    },
   },
 });
 ```
 
 Then use `preset: 'h1'` or `preset: 't2'` in any component's styles.
 
+> You can also call `generateTypographyTokens()` manually and spread the result into `tokens` for more control — `presets` is just a shorthand.
+
 ### Registering brand fonts
 
-Register your design system's custom fonts via `configure({ fontFace })` so every component can reference them:
+Register your design system's custom fonts via `configure({ fontFaces })` so every component can reference them:
 
 ```ts
 configure({
-  fontFace: {
+  fontFaces: {
     'Brand Sans': [
-      { src: 'url("/fonts/brand-regular.woff2") format("woff2")', fontWeight: 400, fontDisplay: 'swap' },
-      { src: 'url("/fonts/brand-bold.woff2") format("woff2")', fontWeight: 700, fontDisplay: 'swap' },
+      {
+        src: 'url("/fonts/brand-regular.woff2") format("woff2")',
+        fontWeight: 400,
+        fontDisplay: 'swap',
+      },
+      {
+        src: 'url("/fonts/brand-bold.woff2") format("woff2")',
+        fontWeight: 700,
+        fontDisplay: 'swap',
+      },
     ],
   },
 });
@@ -132,7 +162,8 @@ configure({
     '@mobile': '@media(w < 768px)',
     '@tablet': '@media(768px <= w < 1024px)',
     '@desktop': '@media(w >= 1024px)',
-    '@dark': '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
+    '@dark':
+      '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
     '@reduced-motion': '@media(prefers-reduced-motion: reduce)',
   },
 });
@@ -173,7 +204,7 @@ configure({
     'input-reset': {
       border: 'none',
       outline: 'none',
-      fill: 'transparent',
+      fill: '#clear',
       font: true,
       preset: 't3',
     },
@@ -199,7 +230,7 @@ const ProfileCard = tasty({
 });
 ```
 
-Use the `/` separator when a recipe should be applied *after* local styles (post-merge), so recipe states take priority:
+Use the `/` separator when a recipe should be applied _after_ local styles (post-merge), so recipe states take priority:
 
 ```tsx
 const Input = tasty({
@@ -271,12 +302,12 @@ Product engineers use these to compose layouts without writing CSS:
 
 Match the prop set to the component's role:
 
-| Component category | Recommended styleProps |
-|--------------------|----------------------|
-| Layout containers (`Space`, `Box`, `Grid`) | `FLOW_STYLES` — flow, gap, align, justify, padding, fill |
-| Positioned elements (`Button`, `Badge`) | `POSITION_STYLES` — placeSelf, gridArea, order |
-| Text elements | `['preset', 'color']` or a custom subset |
-| Compound components | Typically none — styling happens via sub-elements and wrapping |
+| Component category                         | Recommended styleProps                                         |
+| ------------------------------------------ | -------------------------------------------------------------- |
+| Layout containers (`Space`, `Box`, `Grid`) | `FLOW_STYLES` — flow, gap, align, justify, padding, fill       |
+| Positioned elements (`Button`, `Badge`)    | `POSITION_STYLES` — placeSelf, gridArea, order                 |
+| Text elements                              | `['preset', 'color']` or a custom subset                       |
+| Compound components                        | Typically none — styling happens via sub-elements and wrapping |
 
 Exposing too many props weakens the design system's constraints. See [Methodology — styleProps as the public API](methodology.md#styleprops-as-the-public-api) for the rationale.
 
@@ -323,9 +354,7 @@ Usage:
 ```tsx
 <Card>
   <Card.Title>Monthly Revenue</Card.Title>
-  <Card.Content>
-    $1.2M — up 12% from last month.
-  </Card.Content>
+  <Card.Content>$1.2M — up 12% from last month.</Card.Content>
   <Card.Footer>
     <Button>Details</Button>
   </Card.Footer>
@@ -334,7 +363,7 @@ Usage:
 
 Sub-elements share the root component's state context by default. A `disabled` modifier on `<Card>` affects `Title`, `Content`, and `Footer` styles automatically — no prop drilling. For the full mental model, see [Methodology — Component architecture](methodology.md#component-architecture-root--sub-elements).
 
-For sub-element syntax details (selector affix `$`, `@own()`, `elements` config), see [Runtime API — Sub-element Styling](runtime.md#sub-element-styling).
+For sub-element syntax details (selector affix `$`, `@own()`, `elements` config), see [React API — Sub-element Styling](react-api.md#sub-element-styling).
 
 ---
 
@@ -353,13 +382,15 @@ A design system works best when the rules for customization are explicit. Tasty
 2. **Use modProps** — control component states through typed props instead of `mods`:
 
 ```tsx
-<Button isLoading size="large">Submit</Button>
+<Button isLoading size="large">
+  Submit
+</Button>
 ```
 
 3. **Pass tokens** — inject runtime values through the `tokens` prop for per-instance customization:
 
 ```tsx
-<ProgressBar tokens={{ '$progress': `${percent}%` }} />
+<ProgressBar tokens={{ $progress: `${percent}%` }} />
 ```
 
 4. **Create styled wrappers** — extend a component's styles with `tasty(Base, { styles })`:
@@ -404,7 +435,7 @@ ds/
     index.ts              # Recipe definitions (imported by config.ts)
   tokens/
     colors.ts             # Color token definitions
-    typography.ts         # Typography presets via generateTypographyTokens()
+    typography.ts         # Typography presets for configure({ presets })
     spacing.ts            # Spacing token definitions
   index.ts                # Public API: re-exports components + configure
 ```
@@ -418,7 +449,7 @@ The key principle: `config.ts` imports tokens and recipes, calls `configure()`,
 - **[Methodology](methodology.md)** — The recommended patterns for structuring Tasty components
 - **[Getting Started](getting-started.md)** — Installation, first component, tooling setup
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
-- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[React API](react-api.md)** — `tasty()` factory, component props, variants, sub-elements, style functions
 - **[Configuration](configuration.md)** — Full `configure()` API: tokens, recipes, custom units, style handlers
 - **[Adoption Guide](adoption.md)** — Who should adopt Tasty, incremental phases, what changes for product engineers
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties