domflax 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { e as IRDocument, d as RewriteOp, I as IRNodeId, h as StyleResolver, g as SelectorIndex, f as SafetyLevel, l as PassPhase, r as RewriteFactory, i as Diagnostic, c as StyleNormalizer, R as RewriteOpDraft, j as SyntheticSink } from './resolve-ops-DIwEelH-.js';
-export { A as AttrMap, Q as AttrValue, y as Backref, B as BackrefTable, T as Brand, w as ClassList, U as ClassListForm, W as ClassSegment, X as ClassToken, Y as CommentSpec, u as ConditionKey, C as CssProperty, Z as CssValue, _ as DeclSignature, o as DeepReadonly, D as DiagnosticCode, $ as DistributiveOmit, E as ElementLike, a0 as ElementSpec, a1 as EmitContext, a2 as EmitResult, a3 as ExprKind, a4 as ExprRecord, H as ExprRef, K as ExprRegistry, a5 as ExprSpec, F as FileKind, a6 as FragmentSpec, G as FrontendKind, z as IRComment, p as IRElement, J as IRExpr, L as IRFragment, v as IRNamespace, q as IRNode, a7 as IRNodeBase, a8 as IRNodeKind, O as IRText, M as IdAllocator, a9 as InheritedPropertyTable, x as InlineStyle, N as NodeLike, n as NodeMeta, aa as NodeRefSpec, b as NodeSpec, ab as OpOrigin, ac as OpaqueReason, ad as OpaqueToken, m as PassCategory, ae as PassTraceEntry, P as PatternName, af as Position, s as Reporter, ag as ResolveInput, ah as ResolveResult, ai as ResolverDiagnostic, aj as SelectorUsage, ak as Severity, al as SourceFile, am as SourceFileId, k as SourceSpan, an as StyleBlock, t as StyleCondition, a as StyleConflictPolicy, ao as StyleDecl, S as StyleMap, ap as StyleOrigin, aq as SyntheticClass, ar as TextSpec, as as VisitContext, at as VisitSignal, V as Visitor } from './resolve-ops-DIwEelH-.js';
-import { y as ApplyResult, z as RewriteGroup, B as ApplyContext, C as MatchContext, E as FixpointConfig, H as HaltReason, G as Pass, I as PassManager, J as Pattern, K as PhaseRunResult, L as Pipeline, A as AuthoredPattern, N as Captures, O as EncodedSourceMap } from './pattern-CV607P87.js';
-export { Q as AppliedOp, S as BASE_CONDITION, U as BASE_CONDITION_KEY, V as Backend, W as BackendContext, X as CodegenResult, Y as EditPlan, Z as ElementInit, _ as FlattenGate, $ as Frontend, a0 as FrontendConfig, a1 as FrontendParseContext, a2 as MatchResult, a3 as MutableBackrefTable, a4 as OpValidationIssue, a5 as ParentLayoutContext, a6 as ParseResult, a7 as PatternDoc, a8 as PipelineConfig, a9 as PipelineInput, aa as PipelineOutput, ab as PipelineStats, ac as PreconditionSketch, ad as ReindentSpec, ae as RewriteContext, af as SkippedOpGroup, ag as StructuralInverse, ah as StylePredicate, ai as TextEdit, aj as TreeShapeSketch, ak as childIds, al as conditionKey, am as createBackrefTable, an as createComment, ao as createDocument, ap as createElement, aq as createExpr, ar as createExprRegistry, as as createFragment, at as createIdAllocator, au as createText, av as defaultMeta, aw as elementIds, ax as emptyAttrMap, ay as emptyClassList, az as emptyInlineStyle, l as emptyStyleMap, aA as getElement, aB as getNode, aC as walk } from './pattern-CV607P87.js';
+import { e as IRDocument, d as RewriteOp, I as IRNodeId, h as StyleResolver, g as SelectorIndex, f as SafetyLevel, l as PassPhase, r as RewriteFactory, i as Diagnostic, c as StyleNormalizer, R as RewriteOpDraft, j as SyntheticSink, S as StyleMap } from './resolve-ops-D8aQina5.js';
+export { A as AttrMap, Q as AttrValue, y as Backref, B as BackrefTable, T as Brand, w as ClassList, U as ClassListForm, W as ClassSegment, X as ClassToken, Y as CommentSpec, u as ConditionKey, C as CssProperty, Z as CssValue, _ as DeclSignature, o as DeepReadonly, D as DiagnosticCode, $ as DistributiveOmit, E as ElementLike, a0 as ElementSpec, a1 as EmitContext, a2 as EmitResult, a3 as ExprKind, a4 as ExprRecord, H as ExprRef, K as ExprRegistry, a5 as ExprSpec, F as FileKind, a6 as FragmentSpec, G as FrontendKind, z as IRComment, p as IRElement, J as IRExpr, L as IRFragment, v as IRNamespace, q as IRNode, a7 as IRNodeBase, a8 as IRNodeKind, O as IRText, M as IdAllocator, a9 as InheritedPropertyTable, x as InlineStyle, N as NodeLike, n as NodeMeta, aa as NodeRefSpec, b as NodeSpec, ab as OpOrigin, ac as OpaqueReason, ad as OpaqueToken, m as PassCategory, ae as PassTraceEntry, P as PatternName, af as Position, s as Reporter, ag as ResolveInput, ah as ResolveResult, ai as ResolverDiagnostic, aj as SelectorUsage, ak as Severity, al as SourceFile, am as SourceFileId, k as SourceSpan, an as StyleBlock, t as StyleCondition, a as StyleConflictPolicy, ao as StyleDecl, ap as StyleOrigin, aq as SyntheticClass, ar as TextSpec, as as VisitContext, at as VisitSignal, V as Visitor } from './resolve-ops-D8aQina5.js';
+import { y as ApplyResult, z as RewriteGroup, B as ApplyContext, C as MatchContext, E as FixpointConfig, H as HaltReason, G as Pass, I as PassManager, J as Pattern, K as PhaseRunResult, L as Pipeline, A as AuthoredPattern, N as Captures, O as EncodedSourceMap } from './pattern-urm5uuwj.js';
+export { Q as AppliedOp, S as BASE_CONDITION, U as BASE_CONDITION_KEY, V as Backend, W as BackendContext, X as CodegenResult, Y as EditPlan, Z as ElementInit, _ as FlattenGate, $ as Frontend, a0 as FrontendConfig, a1 as FrontendParseContext, a2 as MatchResult, a3 as MutableBackrefTable, a4 as OpValidationIssue, a5 as ParentLayoutContext, a6 as ParseResult, a7 as PatternDoc, a8 as PipelineConfig, a9 as PipelineInput, aa as PipelineOutput, ab as PipelineStats, ac as PreconditionSketch, ad as ReindentSpec, ae as RewriteContext, af as SkippedOpGroup, ag as StructuralInverse, ah as StylePredicate, ai as TextEdit, aj as TreeShapeSketch, ak as childIds, al as conditionKey, am as createBackrefTable, an as createComment, ao as createDocument, ap as createElement, aq as createExpr, ar as createExprRegistry, as as createFragment, at as createIdAllocator, au as createText, av as defaultMeta, aw as elementIds, ax as emptyAttrMap, ay as emptyClassList, az as emptyInlineStyle, l as emptyStyleMap, aA as getElement, aB as getNode, aC as walk } from './pattern-urm5uuwj.js';
 
 /**
  * @domflax/core — applier runtime helpers (shared by the per-op handlers in `./apply`).
@@ -201,13 +201,29 @@ declare function createPipeline(): Pipeline;
  * orchestrator (the `domflax` meta package, `@domflax/cli`, and the pattern auto-test harness) so
  * their pipelines cannot diverge.
  *
- * ## REPLACE, not append
+ * ## Only STYLE-DIRTY elements are re-emitted (never inflate a bystander)
  *
- * For every TOUCHED, rewritable (non-opaque, non-dynamic) element we ask the resolver for the
- * MINIMAL class set reproducing the element's FULL computed style (`resolver.emit(el.computed)`),
- * then REPLACE the element's static tokens with it — rather than appending. Replacing is what lets
- * a compress pass actually shorten output: `px-4 py-4` collapses to `p-4`, equal `w/h` to `size-*`,
- * the four insets to `inset-0`, and fully-overridden duplicates simply disappear.
+ * Reverse-emit runs ONLY on elements a pass actually rewrote the computed style of — `meta.styleDirty`
+ * (a `setClassList`, a `mergeStyle` onto it, or an inherited fold into it). An element that was merely
+ * `touched` as a STRUCTURAL BYSTANDER — a child was flattened/unwrapped, a sibling merged/moved, a
+ * node inserted next to it — never has its own computed changed, so its `class` attribute is left
+ * BYTE-FOR-BYTE IDENTICAL. This is what stops a real custom-CSS site from INFLATING: an unchanged
+ * `<div class="product-art">` can no longer gain a redundant `.bg-cream-deep` just because an inert
+ * child next to it was flattened.
+ *
+ * ## REPLACE, not append — with retained-class coverage SUBTRACTED
+ *
+ * For every style-dirty, rewritable (non-opaque, non-dynamic) element we ask the resolver for the
+ * MINIMAL class set reproducing the element's computed style, then REPLACE the element's droppable
+ * tokens with it — rather than appending. Replacing is what lets a compress pass actually shorten
+ * output: `px-4 py-4` collapses to `p-4`, equal `w/h` to `size-*`, the four insets to `inset-0`, and
+ * fully-overridden duplicates simply disappear.
+ *
+ * Crucially, before choosing what to emit we SUBTRACT the style already supplied by the element's
+ * RETAINED (kept, non-droppable) classes: we emit only for the RESIDUAL declarations those classes do
+ * not already reproduce. So reverse-emit can never materialize a utility for a property a semantic
+ * class the element keeps already sets (the `.product-art` background is never re-added as
+ * `.bg-cream-deep`). Output therefore never grows with a class whose contribution is already covered.
  *
  * ## Droppability gate (never lose a load-bearing class)
  *
@@ -215,70 +231,127 @@ declare function createPipeline(): Pipeline;
  * plain, resolver-owned utility whose entire contribution is reproducible from `computed`. Tokens
  * that are unknown to the resolver, opaque (combinator/at-rule utilities whose effect never folds
  * onto the element's own box), variant-bound, or referenced by a custom-CSS selector are NOT
- * droppable and are preserved verbatim. As a safety net, if `emit` produces nothing at all we leave
- * the element's tokens untouched (a resolver that failed to load must never erase classes).
+ * droppable and are preserved verbatim. As a safety net, if the residual `emit` produces nothing at
+ * all we leave the element's tokens untouched (a resolver that failed to load must never erase
+ * classes).
  */
 
 /**
- * Fold every TOUCHED, rewritable element's optimized computed style back into the MINIMAL static
- * class-token set (see module docs). Mutates `doc` in place.
+ * Fold each rewritable element's computed style back into the MINIMAL static class-token set — the
+ * general compress engine (see module docs + {@link import('./compress-engine')}). Mutates `doc`.
+ *
+ * TWO kinds of element are processed, and their guarantees differ:
+ *
+ *   • STYLE-DIRTY — a pass rewrote this element's own computed style (a flatten fold / merge). Its
+ *     computed CHANGED, so its classes MUST be re-derived to represent the new style (which may
+ *     legitimately need MORE tokens than before). Handled exactly as it always was.
+ *
+ *   • COMPRESS-ONLY — no pass touched it; we run the exact-cover engine purely to SHORTEN its class
+ *     string (`px-4 py-4 → p-4`, drop a redundant class, pick a custom class that covers the same
+ *     style, …). This is a pure class-string rewrite that must NEVER change the render or GROW the
+ *     output, so it carries two extra hard backstops below: the rewritten set must re-resolve to the
+ *     element's exact computed style, and it must not be longer than the original. A structural
+ *     bystander with no compression opportunity therefore keeps its `class` attribute byte-for-byte.
  */
 declare function syncClassesFromComputed(doc: IRDocument, resolver: StyleResolver, norm: StyleNormalizer): void;
 
 /**
- * @domflax/patterns — flatten pattern: `display-contents-wrapper`.
+ * @domflax/core — the general COMPRESS ENGINE: a minimal-string exact-cover solver.
  *
- * Collapses a wrapper that has explicitly opted OUT of generating a box:
+ * ## What it replaces
  *
- *   <div style="display:contents"><Child/></div>   →   <Child/>
+ * The hand-written compress patterns (padding/margin/inset/size/gap/place/border/overflow/…-shorthand
+ * and dedupe-classes) each recognised ONE shorthand shape and folded it. This module subsumes them
+ * ALL with a SINGLE, provider-uniform algorithm: given an element's target computed style, find the
+ * class set that reproduces it EXACTLY with the SHORTEST total `class="…"` string, searching the whole
+ * vocabulary (every Tailwind utility AND the project's custom-CSS classes at once).
  *
- * `display:contents` makes an element generate NO box of its own — its children render exactly as if
- * they were direct children of the element's parent. A `display:contents` wrapper with a single
- * element child is therefore already a layout passthrough: it contributes nothing to flow, paint
- * (a contents box paints nothing), formatting, stacking, or containing-block resolution. Removing it
- * and hoisting the child produces a tree that is layout-identical — the wrapper's only remaining
- * effect was inheritance, which is preserved by folding inheritable declarations onto the child first.
+ * ## The algorithm (per element, per style-condition — all folded into one solve)
  *
- * This is the safest possible wrapper-elimination: the box being removed provably did not exist.
- * The opacity-barrier + selector-safety guards (ref/handlers/dynamic-children/raw-html/combinator/
- * reparent-impact) are auto-applied for every `flatten/*` pattern; the `where` predicates add the
- * passthrough-specific requirements (no own attrs / dynamic-or-spread classes, no `var()` coupling,
- * not a component, not a structural-pseudo subject).
+ * Given a normalized target StyleMap `U`:
+ *   1. UNIVERSE = the set of `(conditionKey, property, value, important)` tuples in `U`
+ *      (a `tupleKey` per {@link tupleKey}).
+ *   2. CANDIDATES = the vocabulary classes whose FULL normalized-longhand declaration set is a SUBSET
+ *      of `U` (never introduces a declaration `U` does not already contain). The caller feeds the
+ *      vocabulary; the element's own droppable tokens are part of it, guaranteeing feasibility and the
+ *      "never worse than the original" property.
+ *   3. COST(class) = token length + 1 (the token plus its joining space) — so minimizing total cost
+ *      minimizes the rendered `class="…"` byte length exactly.
+ *   4. MIN-COST EXACT COVER via bitmask DP over `U`'s tuples: `dp[coveredMask]` = least cost reaching
+ *      that coverage; each transition adds one candidate's mask. Because every candidate AGREES with
+ *      `U` on every tuple it sets, ANY full cover reproduces `U` at the tuple level.
+ *   5. `|U|` is BOUNDED ({@link DEFAULT_MAX_UNIVERSE}); a larger condition-block returns `null` so the
+ *      caller falls back to its greedy emit for that element.
  *
- * (Chosen as the safe variant of the size-hoisting "full-size passthrough" idea: hoisting an explicit
- * `width/height:100%` onto a child is only sound when the child is block-level and unsized, which is
- * not knowable from the wrapper alone — whereas a `display:contents` box is a passthrough by definition.)
+ * The **correctness backstop** (re-resolve the chosen set and assert it equals `U` exactly) lives in
+ * each resolver's `emit` — it owns the forward `resolve`, and running the check there keeps this core
+ * helper pure and provider-agnostic. A chosen set that fails the backstop is discarded and the greedy
+ * emit is used instead, so a set that does not reproduce `U` is NEVER emitted.
  */
+
 /**
- * Flatten a `display:contents` wrapper (a box that generates no box) into its sole element child,
- * folding any inheritable styles down first so inherited values survive the removal.
+ * The canonical key for one normalized declaration under one style condition: the atomic unit both the
+ * target universe and every vocabulary class are expressed in. Equal keys ⇔ the SAME declaration.
  */
-declare const displayContentsWrapper: AuthoredPattern<Captures>;
-
+declare function tupleKey(condition: string, property: string, value: string, important: boolean): string;
 /**
- * @domflax/patterns — flatten pattern: `empty-style-div`.
- *
- * Collapses the most common piece of structural noise of all: a `<div>` whose ONLY role is to wrap
- * a single child while contributing nothing to layout or paint —
- *
- *   <div><Child/></div>            (no styles at all)
- *   <div style="display:block"><Child/></div>   (the default; still a no-op box)
+ * Flatten a StyleMap into its set of {@link tupleKey}s (normalizing first). This is how BOTH the target
+ * universe and each vocabulary class's declarations are lowered, so a class's tuples can be tested for
+ * subset-membership in the universe by plain string equality.
+ */
+declare function styleMapTuples(map: StyleMap, norm: StyleNormalizer): string[];
+/** One vocabulary entry: a class token and the {@link tupleKey}s its full declaration set produces. */
+interface CoverClass {
+    readonly token: string;
+    readonly tuples: readonly string[];
+}
+interface MinCoverOptions {
+    /** Upper bound on `|U|`; above it the DP is skipped (`null`) so the caller uses its greedy emit. */
+    readonly maxUniverse?: number;
+}
+/**
+ * The largest universe the bitmask DP will solve. 20 tuples ⇒ a `2^20` (~1M) DP table, comfortably
+ * fast and bounded in memory; a heavier element (rare) falls back to the resolver's greedy emit.
+ */
+declare const DEFAULT_MAX_UNIVERSE = 20;
+/**
+ * Solve the minimal-string exact cover of `universe` using `vocabulary`.
  *
- * Such a div is layout-neutral: it is a plain block box with no own visual style, establishes no
- * box / formatting / stacking context, is not a containing block, and declares no custom properties
- * a descendant might read. Its box is therefore indistinguishable from "not being there", so it can
- * be unwrapped into its sole child.
+ * Returns the chosen class tokens (sorted, de-duplicated) whose union reproduces `universe` EXACTLY at
+ * least total string cost, or `null` when there is no exact cover OR the universe exceeds the bound (in
+ * both cases the caller falls back to its greedy emit). An empty universe yields `[]`.
  *
- * Authored with the declarative {@link definePattern} API. The opacity-barrier + selector-safety
- * guards (ref/handlers/dynamic-children/raw-html/combinator/reparent-impact) are applied
- * automatically for every `flatten/*` pattern; the `where` predicates below add the LAYOUT-neutrality
- * requirements specific to this pattern (no non-block display, no box/formatting/stacking context, no
- * containing block, no custom-property coupling, no structural-pseudo targeting).
+ * Pure and provider-agnostic: the caller performs the re-resolve correctness backstop.
  */
+declare function minStringCover(universe: readonly string[], vocabulary: Iterable<CoverClass>, options?: MinCoverOptions): readonly string[] | null;
+
 /**
- * Flatten a layout-neutral, style-free `<div>` wrapper into its sole element child.
+ * domflax — build-end optimization SUMMARY.
+ *
+ * A tiny, dependency-free formatter shared by the Vite and webpack/Next adapters. Each adapter
+ * accumulates {@link FileStatDelta} numbers across the build into a {@link Totals}, then prints ONE
+ * boxed {@link renderSummary} block at build end — so the user sees the aggregate payoff without any
+ * per-file spam in between.
+ *
+ * ```
+ *   ▲ domflax
+ *   ────────────────────────────────
+ *    files optimized     42
+ *    DOM nodes removed   318
+ *    classes compressed  1,204
+ *    size saved          18.7 KB
+ *   ────────────────────────────────
+ * ```
  */
-declare const emptyStyleDiv: AuthoredPattern<Captures>;
+/** Per-file optimization delta (from a single {@link Domflax.transform}). */
+interface FileStatDelta {
+    /** DOM/IR nodes removed by provably-safe flattens. */
+    readonly nodesRemoved: number;
+    /** Class tokens eliminated by semantic compression. */
+    readonly classesSaved: number;
+    /** Bytes saved = original byte length − output byte length (may be negative in edge cases). */
+    readonly bytesSaved: number;
+}
 
 /**
  * @domflax/patterns — flatten pattern: `flex-center-wrapper`.
@@ -303,108 +376,6 @@ declare const emptyStyleDiv: AuthoredPattern<Captures>;
  */
 declare const flexCenterWrapper: AuthoredPattern<Captures>;
 
-/**
- * @domflax/patterns — flatten pattern: `inline-flex-center-wrapper`.
- *
- * Collapses the inline-flex flavour of the "centering wrapper" idiom
- *
- *   <div style="display:inline-flex; align-items:center; justify-content:center"><Child/></div>
- *
- * into its sole child, pushing the centering intent down onto the child as `place-self: center`.
- * Like its block-level `flex-center-wrapper` sibling the wrapper only exists to center one element;
- * once `place-self:center` lives on the child the wrapper is pure structural noise and can go.
- *
- * Authored with the declarative {@link definePattern} API: the match is the inline-flex-centering
- * computed-style signature on a single-element-child `<div>` that paints nothing of its own; the
- * recipe folds inheritable styles onto the child, grants it `place-self:center`, then unwraps the
- * wrapper (id-preserving). The opacity-barrier + selector-safety guards are applied automatically by
- * the `definePattern` factory for every `flatten/*` pattern.
- */
-/**
- * Flatten an inline-flex-centering `<div>` wrapper into its sole element child, granting the child
- * `place-self:center`.
- */
-declare const inlineFlexCenterWrapper: AuthoredPattern<Captures>;
-
-/**
- * @domflax/patterns — flatten pattern: `nested-flex-merge`.
- *
- * Collapses a redundant nesting of two flex containers
- *
- *   <div style="display:flex; align-items:center; gap:8px">
- *     <div style="display:flex; flex-direction:column"> … </div>
- *   </div>
- *
- * where the OUTER flex container's sole element child is ITSELF a flex container, into a single
- * flex container that carries the union of both elements' flex declarations. The outer wrapper's
- * box is then structural noise (it paints nothing and only establishes a flex context that the
- * merged child now also establishes), so it is removed.
- *
- * Authored with the declarative {@link pattern} API: the match is a flex `<div>` with a single
- * element child painting nothing of its own (auto-guarded against opacity barriers / combinator
- * targeting like every `flatten/*` pattern). The value-relational reasoning — the child must also
- * be a (non-combinator) flex container, the wrapper must carry only transferable flex/inheritable
- * declarations, and the two must not conflict on any shared flex property — lives in the `rewrite`
- * op-draft factory escape hatch, which folds inherited styles, transfers the wrapper's flex
- * declarations onto the child (target-wins), then unwraps the wrapper.
- */
-/**
- * Flatten a flex container whose sole child is a compatible flex container into a single container.
- */
-declare const nestedFlexMerge: AuthoredPattern<Captures>;
-
-/**
- * @domflax/patterns — flatten pattern: `nested-grid-merge`.
- *
- * Collapses a redundant nesting of two grid containers
- *
- *   <div style="display:grid; gap:8px">
- *     <div style="display:grid; grid-template-columns:1fr 1fr"> … </div>
- *   </div>
- *
- * where the OUTER grid container's sole element child is ITSELF a grid container, into a single grid
- * container carrying the union of both elements' grid declarations. The outer wrapper's box is then
- * structural noise (it paints nothing and only establishes a grid context the merged child now also
- * establishes), so it is removed.
- *
- * This is the grid analogue of `nested-flex-merge`. The declarative match is a grid `<div>` with a
- * single element child painting nothing of its own (auto-guarded against opacity barriers / combinator
- * targeting like every `flatten/*` pattern). The value-relational reasoning — the child must also be a
- * (non-combinator) grid container, the wrapper must carry only transferable grid/inheritable
- * declarations, and the two must not conflict on any shared grid property — lives in the `rewrite`
- * op-draft factory escape hatch, which folds inherited styles, transfers the wrapper's grid
- * declarations onto the child (target-wins), then unwraps the wrapper.
- */
-/**
- * Flatten a grid container whose sole child is a compatible grid container into a single container.
- */
-declare const nestedGridMerge: AuthoredPattern<Captures>;
-
-/**
- * @domflax/patterns — flatten pattern: `passthrough-wrapper`.
- *
- * Collapses a purely-structural wrapper that exists for no reason at all:
- *
- *   <div><Child/></div>
- *
- * The wrapper paints nothing, establishes no box / formatting / stacking context, carries no
- * attributes beyond an (optional) inert class, holds exactly one element child, and is free of every
- * opacity barrier (ref / event-handlers / dynamic children / dangerous html / spread / component).
- * Such a `<div>` is pure DOM noise: removing it and hoisting the child is invisible to both paint
- * and layout.
- *
- * Authored with the declarative {@link definePattern} API. The opacity-barrier + selector-safety
- * guards (ref/handlers/dynamic-children/raw-html/combinator/reparent-impact) are applied
- * automatically for every `flatten/*` pattern; the `where` predicates add the passthrough-specific
- * requirements (no box/formatting/stacking context, no own attrs, no dynamic/spread classes, not a
- * component, not a structural-pseudo subject).
- */
-/**
- * Flatten a do-nothing `<div>` wrapper into its sole element child, folding any inheritable styles
- * down first so inherited values survive the box removal.
- */
-declare const passthroughWrapper: AuthoredPattern<Captures>;
-
 /**
  * @domflax/patterns — flatten pattern: `redundant-fragment`.
  *
@@ -430,378 +401,167 @@ declare const passthroughWrapper: AuthoredPattern<Captures>;
 declare const redundantFragment: AuthoredPattern<Captures>;
 
 /**
- * @domflax/patterns — flatten pattern: `redundant-inline-wrapper`.
- *
- * Collapses a purely-structural INLINE wrapper:
- *
- *   <span><Child/></span>            (display:inline, no own style)
- *
- * An inline `<span>` that paints nothing, establishes no box / formatting / stacking context, carries
- * no attributes beyond an (optional) inert class, declares no custom properties, and holds exactly one
- * element child is pure inline noise. An empty inline box merely wraps its child's box; removing it and
- * hoisting the child leaves both paint and layout untouched (the surviving child folds the inheritable
- * declarations the span carried).
- *
- * This is the inline sibling of `passthrough-wrapper` (which targets `<div>`): the same opacity-barrier
- * + selector-safety guards are auto-applied by the `pattern()` factory for every `flatten/*` pattern;
- * the `where` predicates add the inline-passthrough requirements (display must be the inline default,
- * no box/formatting/stacking context or var coupling, no own attrs / dynamic-or-spread classes, not a
- * component, not a structural-pseudo subject).
- */
-/**
- * Flatten a do-nothing inline `<span>` wrapper into its sole element child, folding any inheritable
- * styles down first so inherited values survive the box removal.
- */
-declare const redundantInlineWrapper: AuthoredPattern<Captures>;
-
-/**
- * @domflax/patterns — compress pattern: `border-radius-shorthand`.
- *
- * Collapses an element whose four corner radii are expressed as separate longhand declarations and
- * are ALL EQUAL into the single CSS `border-radius` shorthand:
- *
- *   border-top-left-radius:0.5rem; border-top-right-radius:0.5rem;
- *   border-bottom-right-radius:0.5rem; border-bottom-left-radius:0.5rem
- *     ⇒  border-radius:0.5rem                  (Tailwind `rounded-lg`)
- *
- * The IR's computed StyleMap keeps each corner as its own longhand (Tailwind's `rounded-tl-*` /
- * `rounded-tr-*` / … each resolve to one corner property). This pass runs the collapse in reverse on
- * the computed map ONLY when all four corners share one value — the single case that maps cleanly to
- * a single Tailwind utility (the CSS 2-value `border-radius` form is DIAGONAL, which has no clean
- * `rounded-*` edge utility, so per-corner differences are intentionally left alone). Rebuilding the
- * map with one `border-radius` decl lets the minimizing reverse-emit pick the single `rounded-*`
- * token covering all four corners instead of two edge tokens.
- *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the
- * `rewriteClasses` recipe rebuilds the class StyleMap, declining (`null`) unless the four corners are
- * present, concrete, equal, and share an `!important` flag.
- */
-/** Fold four equal corner radii into the single `border-radius` shorthand. */
-declare const borderRadiusShorthand: AuthoredPattern<Captures>;
-
-/**
- * @domflax/patterns — compress pattern: `border-shorthand`.
- *
- * Collapses an element whose four border-side WIDTHS are expressed as separate longhand declarations
- * back into the shortest equivalent `border-width` shorthand:
- *
- *   border-top-width:2px; border-right-width:2px; border-bottom-width:2px; border-left-width:2px
- *     ⇒  border-width:2px                      (Tailwind `border-2`)
- *
- *   border-top-width:2px; border-bottom-width:2px; border-left-width:4px; border-right-width:4px
- *     ⇒  border-width:2px 4px                  (Tailwind `border-y-2 border-x-4`)
- *
- * Tailwind's per-side / per-axis width utilities (`border-t-*`, `border-x-*`, …) each resolve to the
- * matching `border-*-width` longhand(s); the shared normalizer keeps them longhand. This pass runs
- * the expansion in reverse on the computed map ONLY when the four widths fold cleanly into a 1- or
- * 2-value form — i.e. `top===bottom` AND `left===right`. Rebuilding the map with one `border-width`
- * shorthand lets the minimizing reverse-emit pick the single/paired utility (`border-2`, or
- * `border-x-* border-y-*`) instead of four per-side tokens. Only WIDTH is folded — border style and
- * color are independent longhands the resolver carries separately, so this never disturbs them.
- *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the `rewriteClasses`
- * recipe rebuilds the class StyleMap, declining (`null`) unless the four widths fold cleanly.
- */
-/** Compress an element's four equal/paired border-width longhands into the shortest shorthand. */
-declare const borderShorthand: AuthoredPattern<Captures>;
-
-/**
- * @domflax/patterns — compress pattern: `dedupe-classes`.
+ * @domflax/patterns — flatten pattern: `grid-center-wrapper`.
  *
- * Removes duplicate / fully-overridden class tokens that resolve to the same property where a
- * LATER token wins, leaving the minimal set of tokens with an IDENTICAL computed style. The
- * canonical case:
+ * Collapses the grid flavour of the "centering wrapper" idiom
  *
- *   <p class="text-sm text-lg">…</p>   →   <p class="text-lg">…</p>
+ *   <div style="display:grid; align-items:center; justify-content:center"><Child/></div>
  *
- * Both `text-sm` and `text-lg` set `font-size`; resolution already made `text-lg` win, so the
- * computed `font-size` is `text-lg`'s value and `text-sm` contributes NOTHING to the final
- * computed style. The earlier token is pure noise and can be dropped without changing a pixel.
+ * into its sole child, pushing the centering intent down onto the child as `place-self:center`. This is
+ * the grid analogue of `flex-center-wrapper`: the wrapper only exists to center one element, and once
+ * `place-self:center` lives on the child the wrapper is pure structural noise.
  *
- * How redundancy is detected (purely from the already-resolved, normalized computed StyleMap):
- *   • every declaration carries provenance — `origin` (the winning token) and `shadowed`
- *     (the tokens it overrode);
- *   • a class token is FULLY OVERRIDDEN iff it appears in some declaration's `shadowed` list but
- *     is NOT the winning `origin` of any declaration across ANY style condition. Such a token can
- *     be deleted with zero effect on the computed style.
+ * Authored with the declarative {@link definePattern} API: the match is the grid-centering computed-style
+ * signature on a single-element-child `<div>` that paints nothing of its own; the recipe folds
+ * inheritable styles onto the child, grants it `place-self:center`, then unwraps the wrapper. The
+ * opacity-barrier + selector-safety guards are auto-applied for every `flatten/*` pattern.
  *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the `dropClasses` recipe returns the set of
- * fully-overridden, resolver-droppable tokens to delete (their `shadowed` provenance is pruned
- * automatically before the minimal class StyleMap is re-installed).
+ * Genuinely additive under the conservative gate: unlike a plain passthrough (which the gate REVERTS on
+ * a grid wrapper because grid establishes a formatting context), the compensating `place-self:center`
+ * makes the flatten `provably-safe` — but ONLY when the child's NEW parent is a statically-known grid
+ * that lets the wrapper fill its area (the ONE context where the child's `justify-self` is honored).
  */
 /**
- * Collapse a class list to the minimal token set that yields an identical computed style, by
- * dropping tokens whose declarations are fully overridden by later tokens.
- */
-declare const dedupeClasses: AuthoredPattern<Captures>;
-
-/**
- * @domflax/patterns — compress pattern: `gap-shorthand`.
- *
- * Collapses an element whose grid/flex gutters are expressed as two equal axis longhands back into
- * the single `gap` shorthand:
- *
- *   row-gap:16px; column-gap:16px   ⇒   gap:16px            (Tailwind `gap-x-4 gap-y-4` → `gap-4`)
- *
- * The IR's computed StyleMap is canonically LONGHAND (the shared normalizer expands the `gap`
- * shorthand into `row-gap` + `column-gap` at parse time). This pass runs the expansion in reverse on
- * the computed map ONLY when both axes carry the SAME value and `!important` flag — i.e. when the two
- * gutters genuinely fold into a single-value `gap`. When the axes differ it declines, leaving the two
- * longhands verbatim (an asymmetric gutter has no equivalent single-value shorthand).
- *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the
- * `rewriteClasses` recipe rebuilds the class StyleMap, declining (`null`) unless the two axis gaps
- * are present, equal, and share an `!important` flag.
- */
-/** Fold an equal `row-gap`/`column-gap` pair into the single `gap` shorthand. */
-declare const gapShorthand: AuthoredPattern<Captures>;
-
-/**
- * @domflax/patterns — compress pattern: `inset-shorthand`.
- *
- * Recompacts the four physical inset longhands (`top`/`right`/`bottom`/`left`) on an element's
- * computed style back into the tightest CSS shorthand the values allow:
- *
- *   • all four equal                       → `inset: <v>`
- *   • top == bottom  (a matching pair)     → `inset-block: <v>`   (Tailwind `inset-y-*`)
- *   • left == right  (a matching pair)     → `inset-inline: <v>`  (Tailwind `inset-x-*`)
- *
- * The two axis collapses are independent: an element whose `top == bottom` but `left != right`
- * collapses only the block axis and keeps the `left`/`right` longhands verbatim. When nothing
- * collapses (all four distinct, or fewer than a full pair present) the pattern declines.
- *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the `rewriteClasses` recipe rebuilds the class
- * StyleMap, declining (`null`) unless at least one inset axis collapses.
- */
-/**
- * Collapse equal/paired physical inset longhands into the `inset` / `inset-block` / `inset-inline`
- * shorthands on an element's computed style.
+ * Flatten a grid-centering `<div>` wrapper into its sole element child, granting the child
+ * `place-self:center`.
  */
-declare const insetShorthand: AuthoredPattern<Captures>;
+declare const gridCenterWrapper: AuthoredPattern<Captures>;
 
 /**
- * @domflax/patterns — compress pattern: `margin-shorthand`.
- *
- * Collapses the four explicit margin longhands
+ * @domflax/patterns — flatten pattern: `display-contents-wrapper`.
  *
- *   margin-top / margin-right / margin-bottom / margin-left
+ * Collapses a wrapper that has explicitly opted OUT of generating a box:
  *
- * back into a single CSS `margin` shorthand declaration on the SAME element (the margin analogue of
- * `padding-shorthand`, covering the `m` / `mx` / `my` collapse), choosing the shortest legal
- * 1–4-value form:
+ *   <div style="display:contents"><Child/></div>   →   <Child/>
  *
- *   • all four equal               → `margin: <v>`           (the `m` case)
- *   • top==bottom and left==right  → `margin: <y> <x>`       (the `my`/`mx` case)
- *   • left==right (top!=bottom)    → `margin: <t> <x> <b>`
- *   • otherwise                    → `margin: <t> <r> <b> <l>`
+ * `display:contents` makes an element generate NO box of its own — its children render exactly as if
+ * they were direct children of the element's parent. A `display:contents` wrapper with a single
+ * element child is therefore already a layout passthrough: it contributes nothing to flow, paint
+ * (a contents box paints nothing), formatting, stacking, or containing-block resolution. Removing it
+ * and hoisting the child produces a tree that is layout-identical — the wrapper's only remaining
+ * effect was inheritance, which is preserved by folding inheritable declarations onto the child first.
  *
- * It is a pure representation change: the resolved box model is identical, only the declaration
- * count shrinks from four to one, which the backend can then re-emit as a single shorthand utility.
+ * This is the safest possible wrapper-elimination: the box being removed provably did not exist.
+ * The opacity-barrier + selector-safety guards (ref/handlers/dynamic-children/raw-html/combinator/
+ * reparent-impact) are auto-applied for every `flatten/*` pattern; the `where` predicates add the
+ * passthrough-specific requirements (no own attrs / dynamic-or-spread classes, no `var()` coupling,
+ * not a component, not a structural-pseudo subject).
  *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the `rewriteClasses` recipe rebuilds the class
- * StyleMap, declining (`null`) unless all four margin longhands are present with a uniform
- * (non-)`!important` flag.
+ * (Chosen as the safe variant of the size-hoisting "full-size passthrough" idea: hoisting an explicit
+ * `width/height:100%` onto a child is only sound when the child is block-level and unsized, which is
+ * not knowable from the wrapper alone — whereas a `display:contents` box is a passthrough by definition.)
  */
 /**
- * Fold four margin longhands into one `margin` shorthand on the element's base style block.
+ * Flatten a `display:contents` wrapper (a box that generates no box) into its sole element child,
+ * folding any inheritable styles down first so inherited values survive the removal.
  */
-declare const marginShorthand: AuthoredPattern<Captures>;
+declare const displayContentsWrapper: AuthoredPattern<Captures>;
 
 /**
- * @domflax/patterns — compress pattern: `overflow-shorthand`.
+ * @domflax/patterns — flatten pattern: `empty-style-div`.
  *
- * Collapses an element whose two overflow axes are expressed as equal longhands back into the single
- * `overflow` shorthand:
+ * Collapses the most common piece of structural noise of all: a `<div>` whose ONLY role is to wrap
+ * a single child while contributing nothing to layout or paint —
  *
- *   overflow-x:auto; overflow-y:auto   ⇒   overflow:auto   (Tailwind `overflow-x-auto overflow-y-auto`
- *                                                            → `overflow-auto`)
+ *   <div><Child/></div>            (no styles at all)
+ *   <div style="display:block"><Child/></div>   (the default; still a no-op box)
  *
- * Unlike the box shorthands, the shared normalizer leaves `overflow-x` / `overflow-y` as independent
- * longhands (it does not synthesize an `overflow` shorthand), so an element styled with two equal
- * axis utilities keeps two separate declarations until this pass folds them. The fold runs ONLY when
- * both axes carry the SAME value and `!important` flag; an asymmetric pair (`overflow-x !==
- * overflow-y`) has no single-keyword `overflow` equivalent and is declined.
+ * Such a div is layout-neutral: it is a plain block box with no own visual style, establishes no
+ * box / formatting / stacking context, is not a containing block, and declares no custom properties
+ * a descendant might read. Its box is therefore indistinguishable from "not being there", so it can
+ * be unwrapped into its sole child.
  *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the
- * `rewriteClasses` recipe rebuilds the class StyleMap, declining (`null`) unless both overflow axes
- * are present, equal, and share an `!important` flag.
+ * Authored with the declarative {@link definePattern} API. The opacity-barrier + selector-safety
+ * guards (ref/handlers/dynamic-children/raw-html/combinator/reparent-impact) are applied
+ * automatically for every `flatten/*` pattern; the `where` predicates below add the LAYOUT-neutrality
+ * requirements specific to this pattern (no non-block display, no box/formatting/stacking context, no
+ * containing block, no custom-property coupling, no structural-pseudo targeting).
  */
-/** Fold an equal `overflow-x`/`overflow-y` pair into the single `overflow` shorthand. */
-declare const overflowShorthand: AuthoredPattern<Captures>;
-
 /**
- * @domflax/patterns — compress pattern: `overscroll-behavior-shorthand`.
- *
- * Collapses an element whose two overscroll-behavior axes are expressed as separate longhand
- * declarations and are EQUAL into the single CSS `overscroll-behavior` shorthand:
- *
- *   overscroll-behavior-x:contain; overscroll-behavior-y:contain
- *     ⇒  overscroll-behavior:contain           (Tailwind `overscroll-x-contain overscroll-y-contain` → `overscroll-contain`)
- *
- * Tailwind's `overscroll-x-*` / `overscroll-y-*` utilities each resolve to the matching
- * `overscroll-behavior-{x,y}` axis longhand, and the shared normalizer keeps `overscroll-behavior`
- * un-expanded (it is NOT one of the box/gap shorthands the normalizer splits). So only the equal-axis
- * form maps cleanly to a single `overscroll-*` utility. This pass runs the collapse in reverse on the
- * computed map ONLY when both axes carry the SAME value and `!important` flag, replacing them with one
- * `overscroll-behavior` decl so the minimizing reverse-emit can pick a single `overscroll-*` token
- * instead of two axis tokens. When the axes differ it declines, leaving the two longhands verbatim.
- *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the
- * `rewriteClasses` recipe rebuilds the class StyleMap, declining (`null`) unless both axes are
- * present, concrete, equal, and share an `!important` flag.
+ * Flatten a layout-neutral, style-free `<div>` wrapper into its sole element child.
  */
-/** Fold an equal overscroll-behavior x/y pair into the single `overscroll-behavior` shorthand. */
-declare const overscrollBehaviorShorthand: AuthoredPattern<Captures>;
+declare const emptyStyleDiv: AuthoredPattern<Captures>;
 
 /**
- * @domflax/patterns — compress pattern: `padding-shorthand`.
- *
- * Collapses an element whose four padding sides are expressed as separate longhand declarations
- * back into the shortest equivalent shorthand:
+ * @domflax/patterns — flatten pattern: `inherited-only-wrapper`.
  *
- *   padding-top:16px; padding-right:16px; padding-bottom:16px; padding-left:16px
- *     ⇒  padding:16px                         (Tailwind `p-4`)
+ * Collapses a paint-free wrapper whose ONLY own declarations are INHERITED properties
+ * (`text-align`, `color`, `font-*`, `line-height`, `letter-spacing`, `white-space`, …):
  *
- *   padding-top:8px; padding-bottom:8px; padding-left:16px; padding-right:16px
- *     ⇒  padding:8px 16px                     (Tailwind `px-4 py-2`)
+ *   <div style="text-align:center"><Child/></div>   →   <Child style="text-align:center"/>
  *
- * The IR's computed StyleMap is canonically LONGHAND (the shared normalizer expands every box
- * shorthand at parse time). This pass runs the expansion in reverse on the computed map ONLY when
- * the four sides fold cleanly into a 1- or 2-value form — i.e. `top===bottom` AND `left===right`.
+ * An inherited property on a wrapper reaches its descendants purely through inheritance, so folding it
+ * onto the sole child and removing the box is render-identical — the child (and everything below it)
+ * still sees the same inherited value. The wrapper carries nothing NON-inherited (no padding, margin,
+ * sizing, border, background, layout), so its box contributes nothing to flow or paint.
  *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the `rewriteClasses`
- * recipe rebuilds the class StyleMap, declining (`null`) unless the four sides fold cleanly.
+ * Distinct from `passthrough-wrapper` in INTENT: it recognizes the common "styling wrapper" idiom —
+ * a box that exists only to set an inherited text/font property on a subtree — and pushes that intent
+ * down onto the child. `foldInheritedStyles` (auto-applied by the flatten recipe) performs the fold;
+ * the `where` predicate restricts the match to wrappers whose entire own style is inheritable.
  */
 /**
- * Compress an element's four equal/paired padding longhands into the shortest `padding` shorthand.
+ * Flatten a wrapper whose only own style is inherited into its sole element child (folding the
+ * inherited declarations down first so the subtree keeps the same inherited values).
  */
-declare const paddingShorthand: AuthoredPattern<Captures>;
+declare const inheritedOnlyWrapper: AuthoredPattern<Captures>;
 
 /**
- * @domflax/patterns — compress pattern: `place-shorthand`.
+ * @domflax/patterns — flatten pattern: `passthrough-wrapper`.
  *
- * Recompacts the grid/flex alignment longhands on an element's computed style into the CSS `place-*`
- * shorthands whenever the two axes of a pair agree:
+ * Collapses a purely-structural wrapper that exists for no reason at all:
  *
- *   • align-items   == justify-items     → `place-items: <v>`     (Tailwind `items-* justify-items-*`)
- *   • align-content == justify-content   → `place-content: <v>`   (Tailwind `content-* justify-*`)
+ *   <div><Child/></div>
  *
- * The two collapses are INDEPENDENT: an element whose items pair agrees but whose content pair does
- * not collapses only `place-items` and keeps the content longhands verbatim. The shared normalizer
- * leaves all four alignment properties as independent longhands (it synthesizes no `place-*`
- * shorthand), so an element styled with two matching axis utilities keeps the longhands until this
- * pass folds them. When neither pair agrees the pattern declines.
+ * The wrapper paints nothing, establishes no box / formatting / stacking context, carries no
+ * attributes beyond an (optional) inert class, holds exactly one element child, and is free of every
+ * opacity barrier (ref / event-handlers / dynamic children / dangerous html / spread / component).
+ * Such a `<div>` is pure DOM noise: removing it and hoisting the child is invisible to both paint
+ * and layout.
  *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the
- * `rewriteClasses` recipe rebuilds the class StyleMap, declining (`null`) unless at least one
- * alignment pair collapses.
+ * Authored with the declarative {@link definePattern} API. The opacity-barrier + selector-safety
+ * guards (ref/handlers/dynamic-children/raw-html/combinator/reparent-impact) are applied
+ * automatically for every `flatten/*` pattern; the `where` predicates add the passthrough-specific
+ * requirements (no box/formatting/stacking context, no own attrs, no dynamic/spread classes, not a
+ * component, not a structural-pseudo subject).
  */
-/** Fold matching align/justify pairs into the `place-items` / `place-content` shorthands. */
-declare const placeShorthand: AuthoredPattern<Captures>;
-
 /**
- * @domflax/patterns — compress pattern: `scroll-margin-shorthand`.
- *
- * Collapses an element whose four scroll-margin sides are expressed as separate longhand
- * declarations and are ALL EQUAL into the single CSS `scroll-margin` shorthand:
- *
- *   scroll-margin-top:1rem; scroll-margin-right:1rem;
- *   scroll-margin-bottom:1rem; scroll-margin-left:1rem
- *     ⇒  scroll-margin:1rem                    (Tailwind `scroll-m-4`)
- *
- * Tailwind's `scroll-mt-*` / `scroll-mx-*` / … utilities each resolve to the matching
- * `scroll-margin-*` longhand(s), and the shared normalizer keeps `scroll-margin` un-expanded (it is
- * NOT one of the box shorthands the normalizer splits). So only the all-equal (1-value) form maps
- * cleanly to a single `scroll-m-*` utility — the 2-value (`scroll-mx`/`scroll-my`) shape is left to
- * the resolver's own reverse-emit. This pass runs the collapse in reverse on the computed map ONLY
- * when all four sides share one value, replacing them with one `scroll-margin` decl so the minimizing
- * reverse-emit can pick a single `scroll-m-*` token instead of two axis tokens.
- *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the
- * `rewriteClasses` recipe rebuilds the class StyleMap, declining (`null`) unless the four sides are
- * present, concrete, equal, and share an `!important` flag.
+ * Flatten a do-nothing `<div>` wrapper into its sole element child, folding any inheritable styles
+ * down first so inherited values survive the box removal.
  */
-/** Fold four equal scroll-margin sides into the single `scroll-margin` shorthand. */
-declare const scrollMarginShorthand: AuthoredPattern<Captures>;
+declare const passthroughWrapper: AuthoredPattern<Captures>;
 
 /**
- * @domflax/patterns — compress pattern: `scroll-padding-shorthand`.
+ * @domflax/patterns — flatten pattern: `redundant-inline-wrapper`.
  *
- * Collapses an element whose four scroll-padding sides are expressed as separate longhand
- * declarations and are ALL EQUAL into the single CSS `scroll-padding` shorthand:
+ * Collapses a purely-structural INLINE wrapper:
  *
- *   scroll-padding-top:1rem; scroll-padding-right:1rem;
- *   scroll-padding-bottom:1rem; scroll-padding-left:1rem
- *     ⇒  scroll-padding:1rem                   (Tailwind `scroll-p-4`)
+ *   <span><Child/></span>            (display:inline, no own style)
  *
- * Tailwind's `scroll-pt-*` / `scroll-px-*` / … utilities each resolve to the matching
- * `scroll-padding-*` longhand(s), and the shared normalizer keeps `scroll-padding` un-expanded (it is
- * NOT one of the box shorthands the normalizer splits). So only the all-equal (1-value) form maps
- * cleanly to a single `scroll-p-*` utility — the 2-value (`scroll-px`/`scroll-py`) shape is left to
- * the resolver's own reverse-emit. This pass runs the collapse in reverse on the computed map ONLY
- * when all four sides share one value, replacing them with one `scroll-padding` decl so the minimizing
- * reverse-emit can pick a single `scroll-p-*` token instead of two axis tokens.
+ * An inline `<span>` that paints nothing, establishes no box / formatting / stacking context, carries
+ * no attributes beyond an (optional) inert class, declares no custom properties, and holds exactly one
+ * element child is pure inline noise. An empty inline box merely wraps its child's box; removing it and
+ * hoisting the child leaves both paint and layout untouched (the surviving child folds the inheritable
+ * declarations the span carried).
  *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the
- * `rewriteClasses` recipe rebuilds the class StyleMap, declining (`null`) unless the four sides are
- * present, concrete, equal, and share an `!important` flag.
+ * This is the inline sibling of `passthrough-wrapper` (which targets `<div>`): the same opacity-barrier
+ * + selector-safety guards are auto-applied by the `pattern()` factory for every `flatten/*` pattern;
+ * the `where` predicates add the inline-passthrough requirements (display must be the inline default,
+ * no box/formatting/stacking context or var coupling, no own attrs / dynamic-or-spread classes, not a
+ * component, not a structural-pseudo subject).
  */
-/** Fold four equal scroll-padding sides into the single `scroll-padding` shorthand. */
-declare const scrollPaddingShorthand: AuthoredPattern<Captures>;
-
 /**
- * @domflax/patterns — compress pattern: `size-shorthand`.
- *
- * Collapses an element whose computed `width` and `height` are EQUAL into the single Tailwind
- * `size-*` utility:
- *
- *   <div style="width:1rem; height:1rem"/>   →   <div class="size-4"/>
- *
- * At the IR level we work over the normalized computed StyleMap (CSS longhands), so the pattern
- * recognizes the `width === height` shape in the BASE condition and rebuilds the element's class
- * StyleMap with a single `size` declaration (the resolver reverse-emits the concrete `size-*` token
- * at codegen). Both longhands are removed and replaced by the merged `size` decl, so the rewrite is
- * idempotent — once collapsed there is no `width`+`height` pair left to re-match.
- *
- * Authored with the declarative {@link pattern} API: `definePattern` auto-applies the compress safety guards — a dynamic or opaque class list
- * and combinator-subject selectors are excluded (a ref / event handler / dynamic child / dangerous
- * HTML never blocks a class-only rewrite); the
- * `rewriteClasses` recipe rebuilds the class StyleMap, returning `null` (decline) unless the BASE
- * width/height are equal, concrete, and share an `!important` flag.
+ * Flatten a do-nothing inline `<span>` wrapper into its sole element child, folding any inheritable
+ * styles down first so inherited values survive the box removal.
  */
-/** Fold equal `width`/`height` into the `size-*` utility. */
-declare const sizeShorthand: AuthoredPattern<Captures>;
+declare const redundantInlineWrapper: AuthoredPattern<Captures>;
 
 /**
  * AUTO-GENERATED by `scripts/gen-registry.mjs` — DO NOT EDIT BY HAND.
  *
  * Regenerate with `npm run generate` (also runs automatically before build/typecheck/test).
- * Patterns are discovered by the `*.pattern.ts` file convention under `src/library/flatten`
- * and `src/library/compress`; the array below is sorted flatten-before-compress.
+ * Patterns are discovered by the recursive `*.pattern.ts` file convention (organized into DOMAIN
+ * folders under `src/library/`); the array below is sorted flatten-before-compress.
  */
 
 /** Every built-in pattern, in registration order (flatten patterns before compress). */
@@ -814,13 +574,12 @@ declare const builtinPatterns: readonly Pattern[];
  * `@domflax/patterns` library, then layers thin, framework-agnostic build adapters on top
  * (`vite()` / `webpack()`) plus a programmatic `createDomflax()` factory.
  *
- * Each adapter runs the SAME single-file engine as {@link createDomflax} (JSX/TSX frontend + lazy
- * Tailwind/CSS resolver → core pass manager → reverse-emit → JSX backend). The adapters are
+ * Each adapter runs the SAME single-file engine as {@link createDomflax} (JSX/TSX + HTML frontends +
+ * lazy Tailwind/CSS resolver → core pass manager → reverse-emit → surgical backend). The adapters are
  * structurally typed against their bundlers — they never hard-depend on `vite` or `webpack`.
  *
- * Future deps (intentionally NOT imported yet — they land in a later stage):
- *   - `@domflax/frontend-html` — HTML / Astro-static frontend feeding the pipeline.
- *   - `@domflax/backend-*`     — additional surgical codegen backends.
+ * `.jsx`/`.tsx` route to `@domflax/frontend-jsx` (Babel); `.html`/`.htm` route to
+ * `@domflax/frontend-html` (parse5). Both emit via SURGICAL span edits over the original source.
  */
 
 /** How class names resolve to computed styles. */
@@ -850,6 +609,12 @@ interface ResolvedDomflaxOptions {
 interface DomflaxTransformResult {
     readonly code: string;
     readonly map: EncodedSourceMap | null;
+    /**
+     * Per-file optimization delta (nodes removed / classes saved / bytes saved). Zeroed for
+     * unsupported or unchanged files. Consumed by the build adapters to accumulate the build-end
+     * {@link renderSummary summary}.
+     */
+    readonly stats: FileStatDelta;
 }
 /**
  * A configured domflax engine. Holds the wired core {@link Pipeline}, the passthrough
@@ -881,6 +646,12 @@ interface DomflaxVitePlugin {
     readonly enforce: 'pre';
     /** Vite's per-file source hook. Fully synchronous and browser-free. */
     transform(code: string, id: string): DomflaxTransformResult | null;
+    /** Vite build-start hook — resets the per-build summary accumulator (watch/serve safe). */
+    buildStart(): void;
+    /** Vite build-end hook — prints the aggregate {@link renderSummary} once (if anything changed). */
+    buildEnd(): void;
+    /** Vite close-bundle hook — prints the summary as a backstop if `buildEnd` did not fire. */
+    closeBundle(): void;
 }
 /**
  * Vite adapter. Returns a real Vite `Plugin` (`enforce: 'pre'`) whose `transform` runs the domflax
@@ -901,6 +672,12 @@ interface DomflaxWebpackModuleHost {
     module?: {
         rules?: unknown[];
     };
+    /** webpack's plugin list (present on both a real `Compiler.options` and Next's bare config). */
+    plugins?: unknown[];
+}
+/** A tappable webpack hook (only the `tap` arm domflax uses). */
+interface DomflaxWebpackHook {
+    tap(name: string, fn: (arg: unknown) => void): void;
 }
 /**
  * Minimal webpack-compiler shape. Declared locally so this adapter does NOT depend on `webpack`'s
@@ -912,6 +689,10 @@ interface DomflaxWebpackModuleHost {
  */
 interface DomflaxWebpackCompiler extends DomflaxWebpackModuleHost {
     options?: DomflaxWebpackModuleHost;
+    /** Present only on a REAL webpack `Compiler` (not on Next's bare config). Used for the summary. */
+    hooks?: {
+        done?: DomflaxWebpackHook;
+    };
 }
 /**
  * Minimal webpack-plugin shape. `apply(compiler)` is the webpack plugin entry point.
@@ -920,30 +701,6 @@ interface DomflaxWebpackPlugin {
     readonly name: string;
     apply(compiler: DomflaxWebpackCompiler): void;
 }
-/**
- * webpack adapter (also the Next.js path). Returns a plugin whose `apply(compiler)` injects a
- * pre-enforced `module.rule` that invokes the domflax {@link ./webpack-loader loader} on every
- * `.jsx`/`.tsx` module. The loader runs the SAME lazy engine as {@link createDomflax} (no eager
- * Tailwind/postcss load).
- *
- * Next.js wiring (`next.config.js`) — Next exposes the underlying webpack config via `webpack(config)`:
- * ```js
- * // next.config.js
- * const domflax = require('domflax');
- * module.exports = {
- *   webpack(config) {
- *     domflax.webpack({ provider: 'tailwind' }).apply(config);
- *     return config;
- *   },
- * };
- * ```
- * `apply(compiler)` is intentionally duck-typed on `compiler.options.module.rules`, so it accepts
- * both a real webpack `Compiler` and the bare `config` object Next.js hands you.
- *
- * Caveat: this targets the webpack builder only. **Turbopack is not yet supported** — it does not
- * accept arbitrary webpack loaders, so the `next.config.js` wiring above is a no-op under
- * `next dev --turbopack`. Run domflax through the webpack builder until Turbopack exposes a loader API.
- */
 declare function webpack(options?: DomflaxOptions): DomflaxWebpackPlugin;
 /**
  * The default-export namespace. Exposes the build adapters and the programmatic factory as an OBJECT
@@ -959,4 +716,4 @@ interface DomflaxDefault {
 /** Default export: an object exposing `vite`, `webpack`, and the programmatic `createDomflax`. */
 declare const domflax: DomflaxDefault;
 
-export { ApplyContext, type ApplyOutcome, ApplyResult, Captures, DEFAULT_FIXPOINT, Diagnostic, type Domflax, type DomflaxDefault, type DomflaxOptions, type DomflaxProvider, type DomflaxTransformResult, type DomflaxVitePlugin, type DomflaxWebpackCompiler, type DomflaxWebpackPlugin, EncodedSourceMap, FixpointConfig, type FlattenClass, type FlattenClassification, type FlattenVerdict, HaltReason, IRDocument, IRNodeId, MatchContext, PHASE_ORDER, Pass, PassManager, PassPhase, Pattern, type PhaseLoopState, PhaseRunResult, Pipeline, type ResolvedDomflaxOptions, RewriteFactory, RewriteGroup, RewriteOp, RewriteOpDraft, type RunState, SafetyLevel, SelectorIndex, StyleNormalizer, StyleResolver, SyntheticSink, applyGroups, applyOps, borderRadiusShorthand, borderShorthand, buildMatchContext, buildSelectorIndex, builtinPatterns, classifyFlattenOps, cloneDocument, createDomflax, createNullResolver, createNullSelectorIndex, createPassManager, createPipeline, createRewriteFactory, createSyntheticSink, dedupeClasses, domflax as default, displayContentsWrapper, docFingerprint, emptyStyleDiv, evaluateElement, finalizePhase, flattenVerdict, flattenWouldDropStyle, flexCenterWrapper, gapShorthand, inlineFlexCenterWrapper, insetShorthand, marginShorthand, nestedFlexMerge, nestedGridMerge, overflowShorthand, overscrollBehaviorShorthand, paddingShorthand, passthroughWrapper, patternsForPhase, placeShorthand, redundantFragment, redundantInlineWrapper, revertDiagnostic, runPasses, scrollMarginShorthand, scrollPaddingShorthand, sizeShorthand, stampOrigin, syncClassesFromComputed, vite, webpack };
+export { ApplyContext, type ApplyOutcome, ApplyResult, Captures, type CoverClass, DEFAULT_FIXPOINT, DEFAULT_MAX_UNIVERSE, Diagnostic, type Domflax, type DomflaxDefault, type DomflaxOptions, type DomflaxProvider, type DomflaxTransformResult, type DomflaxVitePlugin, type DomflaxWebpackCompiler, type DomflaxWebpackPlugin, EncodedSourceMap, FixpointConfig, type FlattenClass, type FlattenClassification, type FlattenVerdict, HaltReason, IRDocument, IRNodeId, MatchContext, type MinCoverOptions, PHASE_ORDER, Pass, PassManager, PassPhase, Pattern, type PhaseLoopState, PhaseRunResult, Pipeline, type ResolvedDomflaxOptions, RewriteFactory, RewriteGroup, RewriteOp, RewriteOpDraft, type RunState, SafetyLevel, SelectorIndex, StyleMap, StyleNormalizer, StyleResolver, SyntheticSink, applyGroups, applyOps, buildMatchContext, buildSelectorIndex, builtinPatterns, classifyFlattenOps, cloneDocument, createDomflax, createNullResolver, createNullSelectorIndex, createPassManager, createPipeline, createRewriteFactory, createSyntheticSink, domflax as default, displayContentsWrapper, docFingerprint, emptyStyleDiv, evaluateElement, finalizePhase, flattenVerdict, flattenWouldDropStyle, flexCenterWrapper, gridCenterWrapper, inheritedOnlyWrapper, minStringCover, passthroughWrapper, patternsForPhase, redundantFragment, redundantInlineWrapper, revertDiagnostic, runPasses, stampOrigin, styleMapTuples, syncClassesFromComputed, tupleKey, vite, webpack };