@barocss/browser 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { Config } from '@barocss/kit';
 import { GenerateCssRulesResult } from '@barocss/kit';
 import { IncrementalParser } from '@barocss/kit';
+import { RuleKey } from '@barocss/kit';
 
 export declare function baroBoot({ loadingClassName, ...options }?: BaroBootOptions): void;
 
@@ -16,9 +17,16 @@ export declare class BrowserRuntime {
     private context;
     private options;
     private isDestroyed;
+    private existing;
+    private existingSheetCount;
+    /** #269: classes requested explicitly through addClass(); never reclaimed. */
+    private pinned;
+    private gc;
+    private reclaimedCount;
     private incrementalParser;
     private changeDetector;
     private stylePartitionManager;
+    private getCategory;
     constructor(options?: BrowserRuntimeOptions);
     /**
      * Add debug logs (by level)
@@ -46,6 +54,15 @@ export declare class BrowserRuntime {
     applyParseResults(results: Array<GenerateCssRulesResult>, _opts?: {
         isBrowser?: boolean;
     }): void;
+    /** #269: a class that must never be reclaimed. */
+    private isPermanent;
+    /**
+     * #269: delete the generated rules of classes no live element uses. Root/@property rules stay
+     * (they are shared and harmless); a rule text another cached class still emits is kept.
+     */
+    private reclaim;
+    /** Class names defined by the page's own stylesheets (BaroCSS's sheets and cross-origin sheets excluded). */
+    getExistingClasses(): Set<string>;
     /**
      * MutationObserver instance method to automatically call addClass when class attributes change in DOM
      */
@@ -65,6 +82,12 @@ export declare class BrowserRuntime {
         runtime: {
             cachedClasses: number;
             rootCacheSize: number;
+            ruleCount: number;
+            reclaimedClasses: number;
+            gc: {
+                trackedClasses: number;
+                candidates: number;
+            } | null;
         };
         ast: {
             size: number;
@@ -101,6 +124,12 @@ export declare class BrowserRuntime {
             runtime: {
                 cachedClasses: number;
                 rootCacheSize: number;
+                ruleCount: number;
+                reclaimedClasses: number;
+                gc: {
+                    trackedClasses: number;
+                    candidates: number;
+                } | null;
             };
             ast: {
                 size: number;
@@ -128,6 +157,30 @@ export declare interface BrowserRuntimeOptions {
     styleId?: string;
     insertionPoint?: 'head' | 'body' | HTMLElement;
     maxRulesPerPartition?: number;
+    /**
+     * #210: skip classes the page's existing (non-BaroCSS, same-origin) stylesheets already define,
+     * so a built app plus the runtime injects only what the build is missing. Opt-in. A class counts
+     * as covered only when a rule's selector starts with it (e.g. `.p-4`, `.md\:p-4` inside @media,
+     * `.hover\:x:hover`), so a class seen only as a descendant (`.group:hover .x`) is not skipped.
+     * The index is rebuilt when `document.styleSheets.length` changes. A page class that leads a selector
+     * with the same name is treated as covered, and rules added later to an already-indexed sheet aren't seen.
+     */
+    skipExisting?: boolean;
+    /**
+     * #269: reclaim the rules of classes that no element inside the observed root carries any more.
+     * On by default; it only acts on classes seen through `observe()`. A class is deleted only after
+     * its refcount has stayed 0 for `gcGraceMs` and a live-DOM re-check finds no element with it.
+     * Never reclaimed: classes passed to `addClass()`, classes any pre-existing (non-BaroCSS) sheet
+     * defines (build output, server sheet), root/@property/preflight rules. `false` disables it.
+     */
+    gc?: boolean;
+    /** #269: how long a class must stay unused before its rules are deleted (default 3000 ms). */
+    gcGraceMs?: number;
+    /**
+     * #269: soft cap on cached classes. When exceeded, unused (refcount 0) classes are evicted
+     * oldest-first without waiting for the grace period; classes in use are never evicted. Default: no cap.
+     */
+    maxRules?: number;
 }
 
 /**
@@ -152,13 +205,17 @@ export declare class ChangeDetector {
     private incrementalParser;
     /** Reference to BrowserRuntime for CSS injection (optional) */
     private BrowserRuntime?;
+    private getCategory;
     /**
      * Create a new ChangeDetector instance
      *
      * @param incrementalParser - IncrementalParser instance for class processing
      * @param BrowserRuntime - Optional BrowserRuntime instance for CSS injection
      */
-    constructor(incrementalParser: IncrementalParser, BrowserRuntime?: BrowserRuntime);
+    constructor(incrementalParser: IncrementalParser, BrowserRuntime?: BrowserRuntime, getCategory?: (cls: string) => string | undefined);
+    /** #269: refcount/GC tracker, when the runtime has GC enabled. */
+    private gc;
+    setGc(gc: ClassGc | null): void;
     setParser(parser: IncrementalParser): void;
     /**
      * Starts observing DOM changes for new CSS classes
@@ -206,19 +263,101 @@ export declare class ChangeDetector {
     disconnect(): void;
 }
 
-export declare function getRuntime(options: BrowserRuntimeOptions): BrowserRuntime;
+declare class ClassGc {
+    private host;
+    private graceMs;
+    private maxRules;
+    private now;
+    private counts;
+    private counted;
+    /** class -> time its count reached 0 (insertion order = oldest first). */
+    private candidates;
+    private timer;
+    private root;
+    constructor(host: ClassGcHost, graceMs: number, maxRules: number, now?: () => number);
+    /** Start counting for a new root: count every element currently inside it. */
+    setRoot(root: Element): void;
+    count(cls: string): number;
+    /** Re-count `el` and (optionally) all its descendants from their current state. */
+    reconcileTree(node: Node): void;
+    reconcile(el: Element): void;
+    /** Call after a mutation batch has been counted and its classes inserted. */
+    afterBatch(): void;
+    private schedule;
+    /** Reclaim candidates whose grace period elapsed (plus LRU overflow). Public for tests. */
+    sweep(): void;
+    private inDom;
+    cancel(): void;
+    stats(): {
+        trackedClasses: number;
+        candidates: number;
+    };
+}
+
+/**
+ * #269: per-class refcount over the observed root, plus a delayed sweep that
+ * reclaims classes no live element carries any more.
+ *
+ * Counting is reconciliation, not delta arithmetic: for every element a
+ * mutation batch touches (attribute target, added subtree, removed subtree) we
+ * compare the classes we last counted for it with what it carries *now*
+ * (nothing if it is no longer inside the root). That makes the count
+ * independent of record order, so remove-then-re-add in one batch, moves
+ * between parents and edits made while detached all settle to the true state.
+ * An element we miss can only leak a count (rule kept), never drop one.
+ *
+ * Before a class is reclaimed the sweep re-checks the live DOM
+ * (`getElementsByClassName`), so even a miscount cannot unstyle a live element.
+ */
+declare interface ClassGcHost {
+    /** Delete the rules of these classes. */
+    reclaim(classes: string[]): void;
+    /** Whether a class must never be reclaimed (pinned, found in a pre-existing sheet, ...). */
+    isPermanent(cls: string): boolean;
+    /** Number of generated rules/classes currently cached (for the LRU cap). */
+    cachedCount(): number;
+}
+
+/** Collect literal className tokens from a json-render Spec's flat elements map. */
+export declare function collectJsonRenderClassNames(spec: unknown): string[];
+
+/**
+ * Returns the shared runtime, creating it on first use. If a live runtime
+ * already exists and `options.config` is a different config object, it is
+ * applied via `updateConfig` (which replaces the whole config), so an early
+ * `getRuntime()` never makes a later `baroStart({ config })` lose its config.
+ */
+export declare function getRuntime(options?: BrowserRuntimeOptions): BrowserRuntime;
+
+/** Tailwind 4 layer order, declared by BaroCSS's first <style> in <head>. */
+export declare const LAYER_ORDER = "@layer theme, base, components, utilities;";
 
 export declare function normalizeClassName(className: any): string;
 
 export declare function normalizeClassNameList(className: any): string[];
 
+/** Submit literal classes synchronously before UI mount; the caller validates class support. */
+export declare function preloadJsonRenderClasses(spec: unknown, runtime: Pick<BrowserRuntime, 'addClass'>): void;
+
+export declare const shadcnTheme: {
+    colors: Record<string, string>;
+    borderRadius: Record<string, string>;
+};
+
 export declare interface StylePartition {
     id: string;
     styles: string[];
     styleElement: HTMLStyleElement;
+    /** Sort keys parallel to `styles` / the sheet's cssRules (#254). */
+    keys?: RuleKey[];
 }
 
 export declare class StylePartitionManager {
+    /**
+     * Insert `rule` at its Tailwind variant position within `partition` (#254):
+     * one insertRule at a binary-searched index, no sheet rewrite.
+     */
+    private insertSorted;
     private partitions;
     private categoryPartitions;
     private partitionCounter;
@@ -227,7 +366,8 @@ export declare class StylePartitionManager {
     private classToPartitionMap;
     private classToCategoryPartitionMap;
     private styleIdPrefix;
-    constructor(insertionPoint: HTMLElement, maxRulesPerPartition?: number, styleIdPrefix?: string);
+    private getCategory;
+    constructor(insertionPoint: HTMLElement, maxRulesPerPartition?: number, styleIdPrefix?: string, getCategory?: (cls: string) => string | undefined);
     private initializeDefaultPartition;
     private createNewCategoryPartition;
     private createNewPartition;
@@ -254,11 +394,20 @@ export declare class StylePartitionManager {
         success: number;
         failed: number;
     };
+    /**
+     * Remove one generated rule (#269 GC). Keeps `styles`, the #254 `keys` and the
+     * sheet's cssRules parallel: one deleteRule at the rule's index, or a text
+     * rebuild when the sheet isn't solely ours / has no CSSOM. Returns whether
+     * the rule was found.
+     */
+    removeRule(rule: string, category?: string): boolean;
+    /** Number of generated (non-root, non-preflight) rules currently held. */
+    get ruleCount(): number;
     /**
      * 특정 규칙이 어느 파티션에 있는지 찾기
      */
     findRulePartition(rule: string): StylePartition | null;
-    updateRuleContent(category: string, ruleContent: string): void;
+    updateRuleContent(category: string, ruleContent: string, atDocumentStart?: boolean): void;
     /**
      * 모든 파티션 정리
      */