@tenphi/tasty 0.0.0-snapshot.1c5dff6 → 0.0.0-snapshot.1f1c00a

package/docs/debug.md

@@ -6,68 +6,63 @@ Runtime CSS inspection and diagnostics for the Tasty styling system. Inspect inj
 
 ## Overview
 
-`tastyDebug` is a diagnostic object that exposes every aspect of Tasty's runtime CSS state. It is designed for development use: inspecting which CSS is active, what's cached, how chunks are distributed, and whether cleanup is working as expected.
+`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.
 
-In development mode (`isDevEnv()` returns `true`), `tastyDebug` is automatically installed on `window.tastyDebug`. In production, you can install it manually when needed.
+All methods **log to the console by default**. Pass `{ raw: true }` to suppress logging and only return data.
 
-> **Note:** This is a development/debugging tool. It does not affect style generation or application behavior.
+> **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();
 
 // Print a quick-start guide
 tastyDebug.help();
 
-// Get a comprehensive overview logged to the console
-tastyDebug.summary({ log: true });
+// Get a comprehensive overview (logged automatically)
+tastyDebug.summary();
 
-// See all active CSS (for components currently in the DOM)
-tastyDebug.log('active');
+// See all active CSS
+tastyDebug.css('active');
 
 // Inspect a specific element
 tastyDebug.inspect('.my-button');
 
-// Check cache hit rates
-tastyDebug.metrics();
+// Silent mode — return data only, no console output
+const data = tastyDebug.summary({ raw: true });
 ```
 
 ---
 
-## Core Types
-
-### `CSSTarget`
+## Options
 
-The `target` parameter accepted by `css()`, `log()`, and related methods:
+All methods accept a shared options object:
 
 ```typescript
-type CSSTarget =
-  | 'all'       // All tasty CSS (component + global + raw)
-  | 'global'    // Only global CSS (from injectGlobal)
-  | 'active'    // CSS for classes currently present in the DOM
-  | 'unused'    // CSS with refCount = 0 (cached but not actively used)
-  | 'page'      // ALL CSS on the page, including non-tasty stylesheets
-  | string      // A tasty class ('t123') or a CSS selector ('.my-class')
-  | string[]    // Array of tasty classes (['t0', 't5', 't12'])
-  | Element;    // A DOM element
+interface DebugOptions {
+  root?: Document | ShadowRoot; // Target root (default: document)
+  raw?: boolean;                // Suppress console logging (default: false)
+}
 ```
 
-### `CssOptions`
+When `raw` is `false` (the default), results are logged to the console **and** returned. When `raw` is `true`, results are returned silently.
 
-Common options for CSS retrieval methods:
+### Environments Without a DOM
 
-```typescript
-interface CssOptions {
-  root?: Document | ShadowRoot;  // Target root (default: document)
-  prettify?: boolean;            // Format CSS output (default: true)
-  log?: boolean;                 // Auto-log to console (default: false)
-}
-```
+`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).
 
 ---
 
@@ -75,45 +70,48 @@ interface CssOptions {
 
 ### `css(target, opts?): string`
 
-Retrieves CSS text for a given target. This is the primary method for extracting CSS from the runtime.
+Retrieves CSS text for a given target. Logs the result with rule count and size.
 
-```typescript
-// All tasty CSS
-tastyDebug.css('all');
-
-// Only CSS for classes currently in the DOM
-tastyDebug.css('active');
+**Targets:**
 
-// CSS for unused classes (refCount = 0, still in cache)
-tastyDebug.css('unused');
+| Target | Description |
+|---|---|
+| `'all'` | All tasty CSS (component + global + raw) |
+| `'active'` | CSS for classes currently in the DOM |
+| `'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) |
+| `'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) |
 
-// Only global CSS (injected via injectGlobal)
-tastyDebug.css('global');
+**Extra options:**
 
-// ALL CSS on the page (including non-tasty stylesheets)
-tastyDebug.css('page');
-
-// CSS for a specific tasty class
-tastyDebug.css('t42');
-
-// CSS for multiple tasty classes
-tastyDebug.css(['t0', 't5', 't12']);
+```typescript
+interface CSSOptions extends DebugOptions {
+  prettify?: boolean; // Format output (default: true)
+  source?: boolean;   // Read original CSS instead of live CSSOM (default: false, dev-mode only)
+}
+```
 
-// CSS affecting a DOM element (by selector)
-tastyDebug.css('.my-button');
+```typescript
+// Active CSS with stats
+tastyDebug.css('active');
 
-// CSS affecting a DOM element (by reference)
-const el = document.querySelector('.my-button');
-tastyDebug.css(el);
+// Specific class, silent
+const css = tastyDebug.css('t3a5f', { raw: true });
 
-// With options
-tastyDebug.css('active', { prettify: false, log: true });
+// Compare original vs browser-parsed CSS (dev mode only)
+tastyDebug.css('t3a5f');                    // live CSSOM
+tastyDebug.css('t3a5f', { source: true }); // original output
 
 // Shadow DOM
-const shadowRoot = host.shadowRoot;
 tastyDebug.css('all', { root: shadowRoot });
 ```
 
+The `source` option reads from `RuleInfo.cssText`, which is only populated when `devMode` is active (development environment or `localStorage.TASTY_DEBUG = 'true'`). In production without debug mode, it falls back to the live CSSOM with a warning.
+
 ---
 
 ### `inspect(target, opts?): InspectResult`
@@ -123,309 +121,177 @@ Inspects a DOM element and returns detailed information about its tasty styles,
 ```typescript
 interface InspectResult {
   element?: Element | null;
-  classes: string[];    // Tasty classes found on the element (e.g., ['t0', 't5'])
-  chunks: ChunkInfo[];  // Chunk assignment per class
-  css: string;          // Prettified CSS affecting the element
-  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 {
-  className: string;       // e.g., 't0'
+interface DebugChunkInfo {
+  className: string;
   chunkName: string | null; // e.g., 'appearance', 'font', 'dimension'
 }
 ```
 
 ```typescript
-// By CSS selector
-const result = tastyDebug.inspect('.my-card');
-console.log(result.classes);  // ['t3', 't7', 't12']
-console.log(result.chunks);   // [{className: 't3', chunkName: 'appearance'}, ...]
-console.log(result.rules);    // 5
-console.log(result.css);      // prettified CSS
-
-// By element reference
-const el = document.querySelector('[data-element="Title"]');
-tastyDebug.inspect(el);
-
-// Shadow DOM
-tastyDebug.inspect('.shadow-component', { root: shadowRoot });
-```
-
----
-
-### `cache(opts?): CacheStatus`
-
-Returns the current state of the style cache: which classes are active, which are unused, and performance metrics.
-
-```typescript
-interface CacheStatus {
-  classes: {
-    active: string[];  // Classes with refCount > 0 and present in DOM
-    unused: string[];  // Classes with refCount = 0 but still in cache
-    all: string[];     // Union of active and unused
-  };
-  metrics: CacheMetrics | null;
-}
-```
-
-```typescript
-const status = tastyDebug.cache();
+tastyDebug.inspect('.my-card');
+// Logs: inspect div — 3 classes, 5 rules, 1.2KB
+//       Chunks: t3a5f→appearance, t9k2→font, tb71→dimension
 
-console.log(status.classes.active.length);  // 42
-console.log(status.classes.unused.length);  // 8
-console.log(status.metrics?.hits);          // 156
+// Silent
+const result = tastyDebug.inspect('.my-card', { raw: true });
+console.log(result.classes);  // ['t3a5f', 't9k2', 'tb71']
+console.log(result.rules);    // 5
 ```
 
 ---
 
-### `cleanup(opts?): void`
+### `summary(opts?): Summary`
 
-Forces immediate cleanup of all unused styles (those with `refCount = 0`).
+One-shot overview of the entire Tasty CSS state. Logs a compact report.
 
 ```typescript
-tastyDebug.cleanup();
+interface Summary {
+  activeClasses: string[];
+  unusedClasses: string[];
+  totalStyledClasses: string[];
+
+  activeCSSSize: number;
+  unusedCSSSize: number;
+  globalCSSSize: number;
+  rawCSSSize: number;
+  keyframesCSSSize: number;
+  propertyCSSSize: number;
+  totalCSSSize: number;
+
+  activeRuleCount: number;
+  unusedRuleCount: number;
+  globalRuleCount: number;
+  rawRuleCount: number;
+  keyframesRuleCount: number;
+  propertyRuleCount: number;
+  totalRuleCount: number;
 
-// Shadow DOM
-tastyDebug.cleanup({ root: shadowRoot });
-```
-
----
-
-### `metrics(opts?): CacheMetrics | null`
-
-Returns performance metrics for the style cache. Only available when `devMode` is enabled.
-
-```typescript
-interface CacheMetrics {
-  hits: number;             // Successful cache hits
-  misses: number;           // New styles injected (cache misses)
-  bulkCleanups: number;     // Number of bulk cleanup operations
-  totalInsertions: number;  // Lifetime style insertions
-  totalUnused: number;      // Total styles marked as unused
-  stylesCleanedUp: number;  // Total styles removed by cleanup
-  startTime: number;        // Metrics collection start timestamp
-  unusedHits?: number;      // Reactivations of cached unused styles
-  cleanupHistory: {
-    timestamp: number;
-    classesDeleted: number;
-    cssSize: number;
-    rulesDeleted: number;
-  }[];
-}
-```
-
-```typescript
-const m = tastyDebug.metrics();
-
-if (m) {
-  const hitRate = ((m.hits + (m.unusedHits || 0)) / (m.hits + m.misses)) * 100;
-  console.log(`Cache hit rate: ${hitRate.toFixed(1)}%`);
-  console.log(`Total insertions: ${m.totalInsertions}`);
-  console.log(`Bulk cleanups: ${m.bulkCleanups}`);
+  metrics: CacheMetrics | null;
+  definedProperties: string[];
+  definedKeyframes: { name: string; refCount: number }[];
+  chunkBreakdown: ChunkBreakdown;
 }
 ```
 
-### `resetMetrics(opts?): void`
-
-Resets all performance metrics counters.
-
 ```typescript
-tastyDebug.resetMetrics();
+// Logged automatically
+tastyDebug.summary();
+// Output:
+//   Active:   42 classes, 186 rules, 12.4KB
+//   Unused:   3 classes, 8 rules, 0.5KB
+//   Global:   12 rules, 1.1KB
+//   Total:    45 classes, 206 rules, 14.0KB
+//   Cache:    94.2% hit rate (312 lookups)
+
+// Silent
+const s = tastyDebug.summary({ raw: true });
+console.log(s.totalRuleCount); // 206
 ```
 
 ---
 
 ### `chunks(opts?): ChunkBreakdown`
 
-Returns a breakdown of styles by chunk type. With style chunking enabled, styles are split into logical chunks (appearance, font, dimension, etc.) for better caching and CSS reuse.
+Breakdown of styles by chunk type.
 
 ```typescript
-const breakdown = tastyDebug.chunks();
-
-console.log(breakdown.totalChunkTypes);  // 6
-console.log(breakdown.totalClasses);     // 87
-
-for (const [chunkName, data] of Object.entries(breakdown.byChunk)) {
-  console.log(`${chunkName}: ${data.classes.length} classes, ${data.cssSize}B`);
+interface ChunkBreakdown {
+  byChunk: Record<string, {
+    classes: string[];
+    cssSize: number;
+    ruleCount: number;
+  }>;
+  totalChunkTypes: number;
+  totalClasses: number;
 }
-
-// Log a formatted breakdown to the console
-tastyDebug.chunks({ log: true });
-```
-
-Chunk types: `combined` (non-chunked), `appearance`, `font`, `dimension`, `display`, `layout`, `position`, `misc`, `subcomponents`.
-
----
-
-### `getGlobalTypeCSS(type, opts?): { css: string; ruleCount: number; size: number }`
-
-Retrieves CSS for a specific global injection type.
-
-```typescript
-// CSS injected via injectGlobal()
-const global = tastyDebug.getGlobalTypeCSS('global');
-
-// CSS injected via injectRawCSS() / useRawCSS()
-const raw = tastyDebug.getGlobalTypeCSS('raw');
-
-// @keyframes CSS
-const keyframes = tastyDebug.getGlobalTypeCSS('keyframes');
-
-// @property CSS
-const properties = tastyDebug.getGlobalTypeCSS('property');
-
-console.log(`Global: ${global.ruleCount} rules, ${global.size}B`);
-console.log(`Raw: ${raw.ruleCount} rules, ${raw.size}B`);
-console.log(`Keyframes: ${keyframes.ruleCount} rules, ${keyframes.size}B`);
-console.log(`Properties: ${properties.ruleCount} rules, ${properties.size}B`);
 ```
 
----
-
-### `defs(opts?): Definitions`
-
-Returns all defined `@property` and `@keyframes` entries.
-
 ```typescript
-interface Definitions {
-  properties: string[];  // Defined via @property (e.g., ['--primary-color', '--gap'])
-  keyframes: { name: string; refCount: number }[];
-}
+tastyDebug.chunks();
+// Output:
+//   appearance: 24 cls, 48 rules, 3.2KB
+//   font: 18 cls, 18 rules, 1.1KB
+//   dimension: 31 cls, 45 rules, 2.4KB
 ```
 
-```typescript
-const defs = tastyDebug.defs();
-
-console.log('Properties:', defs.properties);
-// ['--primary-color', '--surface-color', ...]
-
-console.log('Keyframes:', defs.keyframes);
-// [{ name: 'fadeIn', refCount: 2 }, { name: 'pulse', refCount: 1 }]
-```
+Chunk types: `combined`, `appearance`, `font`, `dimension`, `display`, `layout`, `position`, `misc`, `subcomponents`.
 
 ---
 
-### `summary(opts?): Summary`
+### `cache(opts?): CacheStatus`
 
-One-shot comprehensive overview of the entire Tasty CSS state. Returns detailed statistics and optionally logs a formatted report.
+Cache state and performance metrics.
 
 ```typescript
-interface SummaryOptions {
-  root?: Document | ShadowRoot;
-  log?: boolean;
-  includePageCSS?:
-    | false    // Do not include page-level CSS stats (default)
-    | true     // Include sizes/counts only
-    | 'all';   // Include stats and return full page CSS string
+interface CacheStatus {
+  classes: {
+    active: string[];
+    unused: string[];
+    all: string[];
+  };
+  metrics: CacheMetrics | null;
 }
 ```
 
-The returned `Summary` object contains:
-
-- **Classes**: `activeClasses`, `unusedClasses`, `totalStyledClasses`
-- **CSS sizes**: `activeCSSSize`, `unusedCSSSize`, `globalCSSSize`, `rawCSSSize`, `keyframesCSSSize`, `propertyCSSSize`, `totalCSSSize`
-- **CSS payloads**: `activeCSS`, `unusedCSS`, `globalCSS`, `rawCSS`, `keyframesCSS`, `propertyCSS`, `allCSS`
-- **Rule counts**: `globalRuleCount`, `rawRuleCount`, `keyframesRuleCount`, `propertyRuleCount`
-- **Page CSS** (when `includePageCSS` is set): `page.cssSize`, `page.ruleCount`, `page.stylesheetCount`, `page.skippedStylesheets`
-- **Metrics & definitions**: `metrics`, `definedProperties`, `definedKeyframes`, `propertyCount`, `keyframeCount`
-- **Cleanup summary**: `cleanupSummary.totalCleanups`, `cleanupSummary.totalClassesDeleted`, `cleanupSummary.lastCleanup`, etc.
-- **Chunk breakdown**: `chunkBreakdown.byChunk`, `chunkBreakdown.totalChunkTypes`
-
 ```typescript
-// Log a formatted report
-tastyDebug.summary({ log: true });
-
-// Get the data programmatically
-const s = tastyDebug.summary();
-console.log(`Active: ${s.activeClasses.length} classes, ${s.activeCSSSize}B`);
-console.log(`Unused: ${s.unusedClasses.length} classes, ${s.unusedCSSSize}B`);
-console.log(`Total CSS: ${s.totalCSSSize}B`);
-
-// Include page-level CSS stats
-const withPage = tastyDebug.summary({ includePageCSS: true });
-console.log(`Page CSS: ${withPage.page?.cssSize}B across ${withPage.page?.stylesheetCount} stylesheets`);
+tastyDebug.cache();
+// Output:
+//   Active: 42, Unused: 3
+//   Hits: 294, Misses: 18, Rate: 94.2%
 ```
 
 ---
 
-### `pageCSS(opts?): string`
-
-Returns all CSS on the page across all stylesheets (not only tasty-generated CSS).
-
-```typescript
-// Get all page CSS
-const css = tastyDebug.pageCSS();
-
-// Log it
-tastyDebug.pageCSS({ log: true });
-
-// Raw (unformatted)
-tastyDebug.pageCSS({ prettify: false });
-
-// Exclude cross-origin stylesheet placeholders
-tastyDebug.pageCSS({ includeCrossOrigin: false });
-```
-
-### `pageStats(opts?): PageStats`
+### `cleanup(opts?): void`
 
-Returns size and rule count statistics for all page CSS without extracting the full text.
+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
-const stats = tastyDebug.pageStats();
-console.log(`${stats.cssSize}B across ${stats.stylesheetCount} stylesheets`);
-console.log(`${stats.ruleCount} rules, ${stats.skippedStylesheets} skipped (CORS)`);
+tastyDebug.cleanup();
+tastyDebug.cleanup({ root: shadowRoot });
 ```
 
 ---
 
-### `log(target, opts?): void`
+### `help(): void`
 
-Logs CSS for a target to the console with formatted output, collapsible groups, and sub-element detection.
+Prints a quick-start guide to the console.
 
 ```typescript
-// Log active CSS with stats header
-tastyDebug.log('active');
-
-// Log CSS for a specific class
-tastyDebug.log('t42');
-
-// Log with custom title
-tastyDebug.log('active', { title: 'Button styles' });
-
-// Log CSS for an element
-tastyDebug.log('.my-card');
+tastyDebug.help();
 ```
 
-The output includes:
-- Rule count, line count, and byte size
-- Sub-element breakdown (detects `[data-element="..."]` selectors)
-- Full CSS in a collapsible group
-
 ---
 
-### `help(): void`
+### `install(): void`
 
-Prints a quick-start guide to the console with available commands and common targets.
+Attaches `tastyDebug` to `window.tastyDebug`.
 
 ```typescript
-tastyDebug.help();
+import { tastyDebug } from '@tenphi/tasty';
+tastyDebug.install();
 ```
 
 ---
 
-### `install(): void`
+## Shadow DOM Support
 
-Attaches `tastyDebug` to `window.tastyDebug` for console access. Called automatically in development mode.
+All methods accept a `root` option to target a Shadow DOM:
 
 ```typescript
-import { tastyDebug } from '@tenphi/tasty';
-
-// Manual install (e.g., in staging/production for debugging)
-tastyDebug.install();
-
-// Then use from the browser console:
-// > tastyDebug.summary({ log: true })
+const shadowRoot = host.shadowRoot;
+tastyDebug.css('all', { root: shadowRoot });
+tastyDebug.inspect('.shadow-component', { root: shadowRoot });
+tastyDebug.summary({ root: shadowRoot });
 ```
 
 ---
@@ -435,71 +301,32 @@ tastyDebug.install();
 ### Debugging a component's styles
 
 ```typescript
-// 1. Find the element
+// 1. Inspect the element
 tastyDebug.inspect('.my-button');
-// → { classes: ['t3', 't7'], chunks: [...], css: '...', rules: 4 }
 
 // 2. See CSS for a specific class
-tastyDebug.log('t3');
+tastyDebug.css('t3a5f');
 
-// 3. Check which chunk it belongs to
-tastyDebug.inspect('.my-button').chunks;
-// → [{ className: 't3', chunkName: 'appearance' }, { className: 't7', chunkName: 'font' }]
+// 3. Compare original vs browser-parsed (dev mode)
+tastyDebug.css('t3a5f', { source: true });
 ```
 
 ### Checking cache efficiency
 
 ```typescript
-const m = tastyDebug.metrics();
-const hitRate = m ? ((m.hits + (m.unusedHits || 0)) / (m.hits + m.misses)) * 100 : 0;
-console.log(`Hit rate: ${hitRate.toFixed(1)}%`);
-console.log(`Unused style reactivations: ${m?.unusedHits}`);
+const { metrics } = tastyDebug.cache({ raw: true });
+if (metrics) {
+  const total = metrics.hits + metrics.misses;
+  const rate = total > 0 ? ((metrics.hits / total) * 100).toFixed(1) : 0;
+  console.log(`Cache hit rate: ${rate}%`);
+}
 ```
 
 ### Monitoring CSS growth
 
 ```typescript
-const s = tastyDebug.summary();
-console.log(`Total tasty CSS: ${(s.totalCSSSize / 1024).toFixed(1)}KB`);
-console.log(`Active: ${(s.activeCSSSize / 1024).toFixed(1)}KB`);
-console.log(`Unused (pending cleanup): ${(s.unusedCSSSize / 1024).toFixed(1)}KB`);
-
-// Compare with total page CSS
-const page = tastyDebug.pageStats();
-const ratio = ((s.totalCSSSize / page.cssSize) * 100).toFixed(1);
-console.log(`Tasty is ${ratio}% of total page CSS`);
+const s = tastyDebug.summary({ raw: true });
+console.log(`Total: ${s.totalRuleCount} rules, ${(s.totalCSSSize / 1024).toFixed(1)}KB`);
+console.log(`Active: ${s.activeRuleCount} rules`);
+console.log(`Unused: ${s.unusedRuleCount} rules`);
 ```
-
-### Analyzing chunk distribution
-
-```typescript
-tastyDebug.chunks({ log: true });
-// → Formatted breakdown:
-//   • appearance: 24 classes, 3.2KB, 48 rules
-//   • font: 18 classes, 1.1KB, 18 rules
-//   • dimension: 31 classes, 2.4KB, 45 rules
-//   • ...
-```
-
----
-
-## Shadow DOM Support
-
-All methods accept a `root` option to target a Shadow DOM instead of the main document:
-
-```typescript
-const shadowRoot = host.shadowRoot;
-
-tastyDebug.css('all', { root: shadowRoot });
-tastyDebug.inspect('.shadow-component', { root: shadowRoot });
-tastyDebug.summary({ root: shadowRoot, log: true });
-tastyDebug.chunks({ root: shadowRoot, log: true });
-```
-
----
-
-## Integration with Tasty
-
-`tastyDebug` reads directly from the [Style Injector](./injector.md)'s internal registries. It does not inject, modify, or intercept any styles. The `cleanup()` method is the only method with side effects — it triggers the injector's garbage collection for unused styles.
-
-For most development, you'll use the [Tasty style system](./usage.md) to create components and the debug utilities to inspect the resulting CSS at runtime.