@barocss/browser 0.5.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;
 
@@ -18,6 +19,10 @@ export declare class BrowserRuntime {
     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;
@@ -49,6 +54,13 @@ 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>;
     /**
@@ -70,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;
@@ -106,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;
@@ -142,6 +166,21 @@ export declare interface BrowserRuntimeOptions {
      * 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;
 }
 
 /**
@@ -174,6 +213,9 @@ export declare class ChangeDetector {
      * @param BrowserRuntime - Optional BrowserRuntime instance for CSS injection
      */
     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
@@ -221,6 +263,61 @@ export declare class ChangeDetector {
     disconnect(): void;
 }
 
+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[];
 
@@ -242,25 +339,6 @@ 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;
 
-/**
- * Tailwind-compatible cascade order for runtime-inserted rules (#254).
- *
- * The runtime discovers classes in DOM order, so without sorting `lg:px-8`
- * seen before `sm:px-6` would land earlier and lose at >= 1024px. Each rule
- * gets a sort key derived from its leading `@media` / `@container` preludes:
- *
- *   0  base, state media (hover), motion/contrast, unknown
- *   1  max-* breakpoints        (larger width first)
- *   2  min-* breakpoints        (smaller width first)
- *   3  @max-* container queries (larger width first)
- *   4  @min-* container queries (smaller width first)
- *   5  orientation, dark (prefers-color-scheme), print, forced-colors
- *
- * Nested at-rules (e.g. `sm:dark:`) contribute one key pair per level, so
- * `sm:` < `sm:dark:` < `md:`. Equal keys keep discovery order.
- */
-declare type RuleKey = number[];
-
 export declare const shadcnTheme: {
     colors: Record<string, string>;
     borderRadius: Record<string, string>;
@@ -316,6 +394,15 @@ 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;
     /**
      * 특정 규칙이 어느 파티션에 있는지 찾기
      */