nudge-ui 0.2.0

package/dist/css/token-inventory/inventory.js

@@ -0,0 +1,421 @@
+import { parseStylesheetArtifact } from "./parseStylesheet.js";
+function artifactKey(value) {
+    return `${value.buildTool}\u0000${value.id}`;
+}
+function effectiveObservation(entry) {
+    return entry.transformFailed ? entry.authored : (entry.transformed ?? entry.authored);
+}
+function effectiveOrder(entry) {
+    return effectiveObservation(entry)?.artifact.order ?? entry.authored?.artifact.order;
+}
+function effectiveDiscoveryOrder(entry) {
+    return effectiveObservation(entry)?.artifact.discoveryOrder
+        ?? entry.authored?.artifact.discoveryOrder;
+}
+function compareArtifacts(a, b) {
+    const aOrder = effectiveOrder(a);
+    const bOrder = effectiveOrder(b);
+    const aHasOrder = aOrder !== undefined;
+    const bHasOrder = bOrder !== undefined;
+    if (aHasOrder !== bHasOrder)
+        return aHasOrder ? -1 : 1;
+    if (aOrder !== undefined && bOrder !== undefined && aOrder !== bOrder) {
+        return aOrder - bOrder;
+    }
+    const discovery = (effectiveDiscoveryOrder(a) ?? Infinity)
+        - (effectiveDiscoveryOrder(b) ?? Infinity);
+    return discovery || artifactKey(a).localeCompare(artifactKey(b));
+}
+function compareContributions(a, b) {
+    const order = (a.order ?? Infinity) - (b.order ?? Infinity);
+    return order || a.id.localeCompare(b.id);
+}
+function copyArtifact(artifact) {
+    return {
+        ...artifact,
+        diagnostics: artifact.diagnostics?.map((diagnostic) => ({ ...diagnostic })),
+    };
+}
+function copyToken(entry) {
+    return { ...entry };
+}
+function copyDefinition(definition) {
+    return {
+        ...definition,
+        declarations: definition.declarations.map((declaration) => ({
+            ...declaration,
+            context: {
+                ...declaration.context,
+                wrappers: declaration.context.wrappers?.map((wrapper) => ({ ...wrapper })),
+            },
+        })),
+    };
+}
+function copyContribution(contribution) {
+    return {
+        ...contribution,
+        tokens: contribution.tokens?.map(copyToken),
+        definitions: contribution.definitions?.map(copyDefinition),
+        relabellings: contribution.relabellings?.map((relabelling) => ({ ...relabelling })),
+        diagnostics: contribution.diagnostics?.map((diagnostic) => ({ ...diagnostic })),
+    };
+}
+function sameObservationFacts(observation, artifact) {
+    return JSON.stringify(observation.artifact) === JSON.stringify(artifact);
+}
+/**
+ * Scalar-only equality over stylesheet artifacts, used as a cheap pre-parse
+ * no-op guard: identical re-feeds (the common HMR case) must not pay for a
+ * PostCSS parse. Every field is enumerated so a future artifact field cannot
+ * silently bypass the guard; diagnostics are rare and small, so they alone
+ * compare by serialization — content strings never do.
+ */
+function sameArtifactScalars(a, b) {
+    return a.buildTool === b.buildTool
+        && a.id === b.id
+        && a.stage === b.stage
+        && a.provenance === b.provenance
+        && a.order === b.order
+        && a.discoveryOrder === b.discoveryOrder
+        && a.content === b.content
+        && a.adapter === b.adapter
+        && a.failed === b.failed
+        && ((a.diagnostics === undefined && b.diagnostics === undefined)
+            || (a.diagnostics !== undefined && b.diagnostics !== undefined
+                && JSON.stringify(a.diagnostics) === JSON.stringify(b.diagnostics)));
+}
+function sameContributionFacts(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function parseObservation(artifact) {
+    const storedArtifact = copyArtifact(artifact);
+    const parsed = artifact.content === undefined
+        ? { definitions: [], diagnostics: [] }
+        : parseStylesheetArtifact(storedArtifact);
+    const adapterDiagnostics = (artifact.diagnostics ?? []).map((diagnostic) => ({ ...diagnostic, artifact: artifact.id }));
+    return {
+        artifact: storedArtifact,
+        contribution: {
+            definitions: parsed.definitions,
+            diagnostics: [...adapterDiagnostics, ...parsed.diagnostics],
+        },
+    };
+}
+function orderEvidence(entries) {
+    const discoveryEntries = entries.filter((entry) => effectiveOrder(entry) === undefined);
+    const explicit = discoveryEntries.flatMap((entry) => {
+        const value = effectiveDiscoveryOrder(entry);
+        return value === undefined ? [] : [value];
+    });
+    let next = explicit.length > 0 ? Math.max(...explicit) + 1 : 0;
+    const result = new Map();
+    for (const entry of entries) {
+        const artifact = effectiveObservation(entry)?.artifact;
+        if (!artifact)
+            continue;
+        const order = effectiveOrder(entry);
+        result.set(artifactKey(entry), order !== undefined
+            ? { kind: "stylesheet", index: order }
+            : { kind: "discovery", index: effectiveDiscoveryOrder(entry) ?? next++ });
+    }
+    return result;
+}
+/** Preserve an authored declaration id when the transform retains its position. */
+function reconciledDeclarationId(authored, cssName, declaration) {
+    const authoredDefinition = authored?.contribution.definitions.find((definition) => definition.cssName === cssName);
+    const match = authoredDefinition?.declarations.find((candidate) => candidate.order === declaration.order
+        && candidate.source === declaration.source
+        && JSON.stringify(candidate.context) === JSON.stringify(declaration.context));
+    return match?.id ?? declaration.id;
+}
+function reconcileObservations(entry) {
+    const authored = entry.authored;
+    const facts = effectiveObservation(entry);
+    if (!facts)
+        return [];
+    const authoredNames = new Set(authored?.contribution.definitions.map((definition) => definition.cssName) ?? []);
+    return facts.contribution.definitions.map((definition) => {
+        const transformOnly = authored !== undefined && !authoredNames.has(definition.cssName);
+        // Project compilers own transform-only names, but package ownership is
+        // stronger provenance and survives compilation.
+        const origin = transformOnly && facts.artifact.provenance !== "package"
+            ? "generated"
+            : facts.artifact.provenance;
+        const adapter = facts.artifact.adapter ?? authored?.artifact.adapter;
+        const base = {
+            ...definition,
+            origin,
+            declarations: definition.declarations.map((declaration) => ({
+                ...declaration,
+                id: facts.artifact.stage === "transformed"
+                    ? reconciledDeclarationId(authored, definition.cssName, declaration)
+                    : declaration.id,
+            })),
+        };
+        if (origin === "package" || origin === "generated")
+            base.editable = false;
+        if (adapter && origin !== "package")
+            base.adapter = adapter;
+        return { definition: base, artifact: facts.artifact };
+    });
+}
+function adapterDeclaration(entry, contributionId, contributionOrder, order) {
+    const key = entry.cssName ?? entry.name;
+    return {
+        id: `adapter\x00${contributionId}\x00${key}\x00${entry.source}`,
+        order,
+        value: entry.value,
+        source: entry.source,
+        important: false,
+        context: {},
+        contribution: {
+            kind: "adapter",
+            id: contributionId,
+            provenance: entry.origin,
+            editable: entry.editable,
+            order: contributionOrder,
+        },
+    };
+}
+function setLiteralToken(merged, entry, contributionId, contributionOrder, order) {
+    const key = entry.cssName ?? entry.name;
+    merged.set(key, {
+        base: {
+            cssName: key,
+            name: entry.name,
+            cssValue: entry.cssValue,
+            adapter: entry.adapter,
+            origin: entry.origin,
+            editable: entry.editable,
+        },
+        declarations: [adapterDeclaration(entry, contributionId, contributionOrder, order)],
+    });
+}
+/** FNV-1a 32-bit fingerprint. */
+function fnv1a(input) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0");
+}
+function canonicalSnapshotFacts(definitions, diagnostics) {
+    const parts = [];
+    for (const definition of definitions) {
+        parts.push(`D\x00${definition.cssName}\x00${definition.name}\x00${definition.origin ?? ""}`
+            + `\x00${String(definition.editable ?? "")}\x00${definition.adapter ?? ""}`
+            + `\x00${definition.cssValue ?? ""}`);
+        for (const declaration of definition.declarations) {
+            parts.push(`d\x00${declaration.id ?? ""}\x00${declaration.order}`
+                + `\x00${declaration.value}\x00${declaration.source}\x00${String(declaration.important)}`
+                + `\x00${JSON.stringify(declaration.context)}\x00${JSON.stringify(declaration.contribution)}`);
+        }
+    }
+    for (const diagnostic of diagnostics) {
+        parts.push(`X\x00${diagnostic.code}\x00${diagnostic.artifact ?? ""}\x00${diagnostic.module ?? ""}`
+            + `\x00${diagnostic.exportName ?? ""}\x00${diagnostic.message}`);
+    }
+    return parts.join("\n");
+}
+function deepFreeze(value) {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value))
+        return value;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            deepFreeze(item);
+    }
+    else {
+        for (const item of Object.values(value)) {
+            deepFreeze(item);
+        }
+    }
+    return Object.freeze(value);
+}
+export function createTokenInventory() {
+    const artifacts = new Map();
+    const contributions = new Map();
+    let snapshotCache = null;
+    const invalidate = () => { snapshotCache = null; };
+    function apply(artifact) {
+        const key = artifactKey(artifact);
+        const hasDiagnostics = (artifact.diagnostics?.length ?? 0) > 0;
+        if (artifact.content === undefined && !artifact.failed && !hasDiagnostics) {
+            if (artifacts.delete(key))
+                invalidate();
+            return;
+        }
+        const entry = artifacts.get(key) ?? { buildTool: artifact.buildTool, id: artifact.id };
+        if (artifact.failed) {
+            if (artifact.stage !== "transformed" || entry.transformFailed === true)
+                return;
+            entry.transformFailed = true;
+            artifacts.set(key, entry);
+            invalidate();
+            return;
+        }
+        const current = artifact.stage === "authored" ? entry.authored : entry.transformed;
+        const isRecoveringFailedTransform = artifact.stage === "transformed" && entry.transformFailed === true;
+        // Cheap pre-parse guard. A transformed-stage re-feed while the failure
+        // flag is set always falls through so recovery still lands.
+        if (current && !isRecoveringFailedTransform
+            && sameArtifactScalars(current.artifact, artifact))
+            return;
+        const observation = parseObservation(artifact);
+        if (current && sameObservationFacts(current, observation.artifact)
+            && !isRecoveringFailedTransform)
+            return;
+        if (artifact.stage === "authored")
+            entry.authored = observation;
+        else {
+            entry.transformed = observation;
+            entry.transformFailed = false;
+        }
+        artifacts.set(key, entry);
+        invalidate();
+    }
+    function applyContribution(contribution) {
+        const copied = copyContribution(contribution);
+        const existing = contributions.get(copied.id);
+        if (existing && sameContributionFacts(existing, copied))
+            return;
+        contributions.set(copied.id, copied);
+        invalidate();
+    }
+    function removeContribution(id) {
+        if (contributions.delete(id))
+            invalidate();
+    }
+    function snapshot() {
+        if (snapshotCache)
+            return snapshotCache;
+        const sortedArtifacts = [...artifacts.values()].sort(compareArtifacts);
+        const sortedContributions = [...contributions.values()].sort(compareContributions);
+        const evidence = orderEvidence(sortedArtifacts);
+        const merged = new Map();
+        let provisionalOrder = 0;
+        for (const entry of sortedArtifacts) {
+            const rows = reconcileObservations(entry)
+                .flatMap(({ definition, artifact }) => definition.declarations.map((declaration) => ({ definition, declaration, artifact })))
+                .sort((a, b) => (a.declaration.order ?? 0) - (b.declaration.order ?? 0));
+            for (const { definition, declaration, artifact } of rows) {
+                const enriched = {
+                    ...declaration,
+                    order: provisionalOrder++,
+                    contribution: {
+                        kind: "stylesheet",
+                        buildTool: artifact.buildTool,
+                        id: artifact.id,
+                        stage: artifact.stage,
+                        provenance: definition.origin ?? artifact.provenance,
+                        editable: definition.editable ?? artifact.provenance !== "package",
+                        orderEvidence: evidence.get(artifactKey(artifact)),
+                    },
+                };
+                const existing = merged.get(definition.cssName);
+                if (existing)
+                    existing.declarations.push(enriched);
+                else {
+                    const { declarations: _declarations, ...base } = definition;
+                    merged.set(definition.cssName, { base, declarations: [enriched] });
+                }
+            }
+        }
+        for (const [contributionIndex, contribution] of sortedContributions.entries()) {
+            const contributionOrder = contribution.order ?? contributionIndex;
+            const tokens = [...(contribution.tokens ?? [])]
+                .sort((a, b) => (a.cssName ?? a.name).localeCompare(b.cssName ?? b.name));
+            for (const token of tokens) {
+                setLiteralToken(merged, token, contribution.id, contributionOrder, provisionalOrder++);
+            }
+            for (const relabelling of contribution.relabellings ?? []) {
+                for (const entry of merged.values()) {
+                    if (entry.base.adapter !== relabelling.adapter
+                        || entry.base.origin !== relabelling.fromOrigin)
+                        continue;
+                    entry.base = {
+                        ...entry.base,
+                        origin: relabelling.origin ?? entry.base.origin,
+                        editable: relabelling.editable ?? entry.base.editable,
+                    };
+                }
+            }
+            // Definition-level enrichment by cssName: contributed declarations
+            // append, `name`/`adapter` win, and
+            // `origin`/`editable` are applied only when the stylesheet-derived
+            // definition has none. Unmatched entries are ignored (a contract
+            // variable absent from active CSS adds no row).
+            for (const definition of contribution.definitions ?? []) {
+                const existing = merged.get(definition.cssName);
+                if (!existing)
+                    continue;
+                for (const declaration of definition.declarations) {
+                    existing.declarations.push({
+                        ...declaration,
+                        order: provisionalOrder++,
+                        contribution: {
+                            kind: "adapter",
+                            id: contribution.id,
+                            provenance: definition.origin,
+                            editable: definition.editable,
+                            order: contributionOrder,
+                        },
+                    });
+                }
+                existing.base = {
+                    ...existing.base,
+                    name: definition.name,
+                    adapter: definition.adapter ?? existing.base.adapter,
+                    origin: existing.base.origin ?? definition.origin,
+                    editable: existing.base.editable ?? definition.editable,
+                };
+            }
+        }
+        const allDeclarations = [...merged.values()]
+            .flatMap((entry) => entry.declarations)
+            .sort((a, b) => a.order - b.order);
+        const compactOrder = new Map(allDeclarations.map((declaration, index) => [declaration, index]));
+        const definitions = [...merged.values()].map(({ base, declarations }) => ({
+            ...base,
+            declarations: declarations.map((declaration) => ({
+                ...declaration,
+                order: compactOrder.get(declaration),
+            })),
+        }));
+        const tokens = definitions.map((definition) => ({
+            name: definition.name,
+            cssName: definition.cssName,
+            value: definition.declarations[0]?.value ?? "",
+            source: definition.declarations[0]?.source ?? "",
+            cssValue: definition.cssValue,
+            adapter: definition.adapter,
+            origin: definition.origin,
+            editable: definition.editable,
+        }));
+        const diagnostics = [];
+        for (const entry of sortedArtifacts) {
+            const facts = effectiveObservation(entry);
+            if (facts)
+                diagnostics.push(...facts.contribution.diagnostics);
+            if (entry.transformFailed) {
+                diagnostics.push({
+                    code: "transform-observation-failed",
+                    artifact: entry.id,
+                    message: `The transformed observation for "${entry.id}" is unavailable or failed; `
+                        + "the last valid authored observation is retained.",
+                });
+            }
+        }
+        for (const contribution of sortedContributions) {
+            diagnostics.push(...(contribution.diagnostics ?? []));
+        }
+        snapshotCache = deepFreeze({
+            generation: `g${fnv1a(canonicalSnapshotFacts(definitions, diagnostics))}`,
+            definitions,
+            tokens,
+            diagnostics,
+        });
+        return snapshotCache;
+    }
+    return { apply, snapshot, applyContribution, removeContribution };
+}

package/dist/css/token-inventory/parseStylesheet.d.ts

@@ -0,0 +1,16 @@
+import type { TokenDefinition } from "../model/index.js";
+import type { InventoryDiagnostic, StylesheetArtifact } from "./types.js";
+/** The parsed contribution of one stylesheet artifact. */
+export interface ParsedContribution {
+    readonly definitions: readonly TokenDefinition[];
+    readonly diagnostics: readonly InventoryDiagnostic[];
+}
+/**
+ * Parse one stylesheet artifact into grouped definitions plus diagnostics.
+ *
+ * The returned declarations carry `id` (stable per declaration) and the
+ * definition list preserves source order. `order` is assigned by the
+ * inventory during snapshot assembly because it is a positional fact across
+ * artifacts, not a per-artifact one.
+ */
+export declare function parseStylesheetArtifact(artifact: StylesheetArtifact): ParsedContribution;

package/dist/css/token-inventory/parseStylesheet.js

@@ -0,0 +1,155 @@
+/**
+ * Internal ordinary-CSS parsing for the token inventory.
+ *
+ * This is the canonical home of the parsing previously owned by the plugin's
+ * legacy `parseTokens`/`parseTokenCatalog` projections (removed in S2-D).
+ * Behavior is preserved exactly for root/host themes, contextual selectors,
+ * wrapper capture, duplicate declarations, importance, and source locations;
+ * the two differences are:
+ *
+ * 1. Declarations carry a deterministic `id` and a `source`-anchored local
+ *    order so the inventory can aggregate without Vite.
+ * 2. Malformed CSS no longer silently yields an empty list — it produces a
+ *    structured `stylesheet-parse-failed` diagnostic plus an empty
+ *    contribution for that artifact.
+ *
+ * This module runs at build time only (Node) and is not reachable from the
+ * browser-safe subpaths.
+ */
+import postcss, {} from "postcss";
+import { GLOBAL_TOKEN_AT_RULES, MIN_THEME_TABLE_DECLARATIONS } from "./policy.js";
+/**
+ * Deterministic declaration identity, keyed by (artifact id, cssName, source
+ * line, context, local order). The id does not depend on event-batch timing:
+ * the same facts always produce the same ids.
+ */
+function declarationId(artifact, cssName, source, context, localOrder) {
+    return `${artifact.buildTool}\u0000${artifact.id}\u0000${artifact.stage}`
+        + `\u0000${cssName}\u0000${source}\u0000${JSON.stringify(context)}\u0000${localOrder}`;
+}
+function isRootSelectorPart(sel) {
+    return sel === ":root"
+        || sel === ":host"
+        || /^:root[:.[]/.test(sel)
+        || /^:host[:.[]/.test(sel);
+}
+function isRootOnlySelector(rule) {
+    const parts = rule.selector.split(",").map((s) => s.trim());
+    return parts.length > 0 && parts.every(isRootSelectorPart);
+}
+/**
+ * Scoped theme-table policy — see `policy.ts` for the named constant and
+ * rationale. A sufficiently large rule made entirely of custom properties is a
+ * theme table, not a component-local variable declaration; its selector is
+ * retained in the catalog and resolved against the selected element later.
+ */
+function isScopedThemeTable(rule) {
+    const declarations = rule.nodes?.filter((node) => node.type === "decl") ?? [];
+    return declarations.length >= MIN_THEME_TABLE_DECLARATIONS
+        && declarations.every((declaration) => declaration.prop.startsWith("--"));
+}
+function isRule(node) {
+    return node.type === "rule";
+}
+function isAtRule(node) {
+    return node.type === "atrule";
+}
+function nearestGlobalAncestor(decl) {
+    // Walk up; return true ONLY if we encounter a :root rule or a global at-rule
+    // BEFORE encountering any non-:root rule. A non-:root rule (e.g. .button)
+    // inside @layer still means the declaration is local, not a global token.
+    let cur = decl.parent;
+    while (cur) {
+        if (isRule(cur)) {
+            return isRootOnlySelector(cur) || isScopedThemeTable(cur);
+        }
+        if (isAtRule(cur)) {
+            if (GLOBAL_TOKEN_AT_RULES.has(cur.name))
+                return true;
+        }
+        cur = cur.parent;
+    }
+    return false;
+}
+function belongsToGlobalTokenContext(decl) {
+    return nearestGlobalAncestor(decl);
+}
+function declarationContext(decl) {
+    const context = {};
+    const wrappers = [];
+    let current = decl.parent;
+    while (current) {
+        if (isRule(current) && context.selector === undefined) {
+            context.selector = current.selector;
+        }
+        else if (isAtRule(current)) {
+            if (current.name === "media" || current.name === "supports" || current.name === "scope" || current.name === "layer") {
+                // Parents are visited inner-to-outer; prepend to preserve the source
+                // nesting order and retain repeated/interleaved wrapper kinds.
+                wrappers.unshift({ kind: current.name, params: current.params });
+            }
+        }
+        current = current.parent;
+    }
+    if (wrappers.length > 0)
+        context.wrappers = wrappers;
+    return context;
+}
+/**
+ * Parse one stylesheet artifact into grouped definitions plus diagnostics.
+ *
+ * The returned declarations carry `id` (stable per declaration) and the
+ * definition list preserves source order. `order` is assigned by the
+ * inventory during snapshot assembly because it is a positional fact across
+ * artifacts, not a per-artifact one.
+ */
+export function parseStylesheetArtifact(artifact) {
+    const content = artifact.content ?? "";
+    let root;
+    try {
+        root = postcss.parse(content, { from: artifact.id });
+    }
+    catch (error) {
+        return {
+            definitions: [],
+            diagnostics: [{
+                    code: "stylesheet-parse-failed",
+                    artifact: artifact.id,
+                    message: `Stylesheet artifact "${artifact.id}" could not be parsed as CSS: ${error instanceof Error ? error.message : String(error)}`,
+                }],
+        };
+    }
+    const definitions = new Map();
+    let localOrder = 0;
+    root.walkDecls((decl) => {
+        if (!decl.prop.startsWith("--"))
+            return;
+        if (!belongsToGlobalTokenContext(decl))
+            return;
+        let value = decl.value;
+        if (decl.important) {
+            value = value.replace(/!\s*important\s*$/i, "").trim();
+        }
+        value = value.trim();
+        const line = decl.source?.start?.line;
+        if (typeof line !== "number")
+            return;
+        const source = `${artifact.id}:${line}`;
+        const context = declarationContext(decl);
+        const declaration = {
+            id: declarationId(artifact, decl.prop, source, context, localOrder),
+            order: localOrder,
+            value,
+            source,
+            important: Boolean(decl.important),
+            context,
+        };
+        const existing = definitions.get(decl.prop);
+        if (existing)
+            existing.declarations.push(declaration);
+        else
+            definitions.set(decl.prop, { cssName: decl.prop, name: decl.prop, declarations: [declaration] });
+        localOrder += 1;
+    });
+    return { definitions: [...definitions.values()], diagnostics: [] };
+}

package/dist/css/token-inventory/policy.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Explicit inventory policies behind ordinary CSS parsing.
+ *
+ * Parsing must not bury heuristics as unexplained constants. This module names
+ * each policy, documents its rationale, and pins both directions of the
+ * trade-off with tests in `parseStylesheet.test.ts`.
+ */
+/**
+ * At-rules that make a nested custom-property declaration global regardless of
+ * an enclosing selector: `@theme` (Tailwind v4), `@layer`, and `@scope`.
+ *
+ * Deliberately NOT included: `@media`, `@supports`, and `@container`. A bare
+ * custom property directly inside those wrappers (without `:root`/`:host`) is
+ * not a global token — see the false-positive guards in the parsing tests.
+ */
+export declare const GLOBAL_TOKEN_AT_RULES: Set<string>;
+/**
+ * Minimum declaration count for a scoped rule to be treated as a theme table.
+ *
+ * Rationale: published design systems often scope an entire theme beneath a
+ * class on the application shell (for example to support multiple themes on
+ * one page) instead of `:root`. A rule that is large enough AND made entirely
+ * of custom-property declarations is treated as a theme table, so its selector
+ * is retained in the catalog and resolved against the selected element later.
+ *
+ * The threshold is a deliberately explicit policy with two documented edges,
+ * both pinned by tests:
+ *
+ * - False positive: a component-local rule with many custom properties (at or
+ *   above the threshold) is admitted as a theme table even though it is local
+ *   to the component. Accepted so genuine multi-variable theme tables keep
+ *   working; a cleaner fix needs selector heuristics that are out of scope for
+ *   ordinary-CSS parsing.
+ * - False negative: a real theme table with fewer than the threshold
+ *   declarations is rejected. Accepted so small component-local rules do not
+ *   leak into the global catalog.
+ *
+ * The threshold is a count of direct custom-property declarations on the rule,
+ * not a line count and not an estimate of selector breadth.
+ */
+export declare const MIN_THEME_TABLE_DECLARATIONS = 8;
+export interface ScopedThemeTablePolicy {
+    readonly minDeclarations: number;
+    readonly requiresOnlyCustomProperties: boolean;
+    readonly rationale: string;
+}
+export declare const SCOPED_THEME_TABLE_POLICY: ScopedThemeTablePolicy;

package/dist/css/token-inventory/policy.js

@@ -0,0 +1,50 @@
+/**
+ * Explicit inventory policies behind ordinary CSS parsing.
+ *
+ * Parsing must not bury heuristics as unexplained constants. This module names
+ * each policy, documents its rationale, and pins both directions of the
+ * trade-off with tests in `parseStylesheet.test.ts`.
+ */
+/**
+ * At-rules that make a nested custom-property declaration global regardless of
+ * an enclosing selector: `@theme` (Tailwind v4), `@layer`, and `@scope`.
+ *
+ * Deliberately NOT included: `@media`, `@supports`, and `@container`. A bare
+ * custom property directly inside those wrappers (without `:root`/`:host`) is
+ * not a global token — see the false-positive guards in the parsing tests.
+ */
+export const GLOBAL_TOKEN_AT_RULES = new Set(["theme", "layer", "scope"]);
+/**
+ * Minimum declaration count for a scoped rule to be treated as a theme table.
+ *
+ * Rationale: published design systems often scope an entire theme beneath a
+ * class on the application shell (for example to support multiple themes on
+ * one page) instead of `:root`. A rule that is large enough AND made entirely
+ * of custom-property declarations is treated as a theme table, so its selector
+ * is retained in the catalog and resolved against the selected element later.
+ *
+ * The threshold is a deliberately explicit policy with two documented edges,
+ * both pinned by tests:
+ *
+ * - False positive: a component-local rule with many custom properties (at or
+ *   above the threshold) is admitted as a theme table even though it is local
+ *   to the component. Accepted so genuine multi-variable theme tables keep
+ *   working; a cleaner fix needs selector heuristics that are out of scope for
+ *   ordinary-CSS parsing.
+ * - False negative: a real theme table with fewer than the threshold
+ *   declarations is rejected. Accepted so small component-local rules do not
+ *   leak into the global catalog.
+ *
+ * The threshold is a count of direct custom-property declarations on the rule,
+ * not a line count and not an estimate of selector breadth.
+ */
+export const MIN_THEME_TABLE_DECLARATIONS = 8;
+export const SCOPED_THEME_TABLE_POLICY = {
+    minDeclarations: MIN_THEME_TABLE_DECLARATIONS,
+    requiresOnlyCustomProperties: true,
+    rationale: "A scoped rule is a theme table only when it is large enough and made entirely "
+        + "of custom-property declarations. This admits multi-variable theme tables on "
+        + "an application shell while keeping small component-local variable blocks out "
+        + "of the global catalog. Both directions of the trade-off are pinned by tests "
+        + "in parseStylesheet.test.ts.",
+};