domflax 0.1.0 → 0.1.1

package/dist/pattern-F5xBtIE-.d.cts

@@ -0,0 +1,547 @@
+import { d as RewriteOp, e as IRDocument, f as SafetyLevel, c as StyleNormalizer, g as SelectorIndex, h as StyleResolver, I as IRNodeId, P as PatternName, D as DiagnosticCode, i as Diagnostic, F as FileKind, j as SyntheticSink, k as SourceSpan, l as PassPhase, m as PassCategory, n as NodeMeta, o as DeepReadonly, p as IRElement, S as StyleMap, N as NodeLike, E as ElementLike, q as IRNode, r as RewriteFactory, R as RewriteOpDraft, s as Reporter, t as StyleCondition, u as ConditionKey, v as IRNamespace, w as ClassList, x as InlineStyle, A as AttrMap, B as BackrefTable, y as Backref, z as IRComment, G as FrontendKind, H as ExprRef, J as IRExpr, K as ExprRegistry, L as IRFragment, M as IdAllocator, O as IRText, V as Visitor, a as StyleConflictPolicy } from './resolve-ops-DIwEelH-.cjs';
+
+/**
+ * @domflax/core — type contract, part 3/3: the pattern contract + match/rewrite contexts, the pass
+ * manager + applier, frontends/backends, and the pure single-file pipeline.
+ *
+ * Pure type/interface declarations only: ZERO runtime. Depends on the IR/style primitives in `./ir`
+ * and the resolver/op types in `./resolve-ops`.
+ */
+
+type Captures = Record<string, unknown>;
+/** Read-only style predicate over a normalized StyleMap (queries MEANING, not strings). */
+type StylePredicate = (sm: StyleMap) => boolean;
+/**
+ * Relational precondition (review-2 blocker): describes ancestor/sibling/child subtree shape AND
+ * ancestor LAYOUT context (review-4 blocker) so fuzzProve generates trees that exercise the
+ * relational + parent-constraint branches, not just node-local ones.
+ */
+interface TreeShapeSketch {
+    readonly tag?: string | readonly string[];
+    readonly requiredComputed?: Readonly<Record<string, string>>;
+    readonly meta?: Partial<Record<keyof NodeMeta, boolean>>;
+    readonly children?: readonly TreeShapeSketch[];
+}
+type ParentLayoutContext = 'block-flow' | 'flex-item' | 'flex-item-stretch' | 'grid-item' | 'fixed-size-ancestor' | 'percentage-sized-child' | 'inline-context';
+interface PreconditionSketch {
+    readonly requiredComputed?: Readonly<Record<string, string>>;
+    readonly childCount?: {
+        readonly min?: number;
+        readonly max?: number;
+    };
+    readonly forbid?: readonly string[];
+    readonly ancestor?: TreeShapeSketch;
+    readonly siblings?: readonly TreeShapeSketch[];
+    readonly childShapes?: readonly TreeShapeSketch[];
+    readonly parentContexts?: readonly ParentLayoutContext[];
+}
+interface PatternDoc {
+    readonly title: string;
+    readonly summary: string;
+    readonly before?: string;
+    readonly after?: string;
+    readonly safetyRationale?: string;
+}
+/** Result of a successful match: op drafts (origin stamped later) + optional captures/diagnostics. */
+interface MatchResult<C extends Captures = Captures> {
+    readonly ops: readonly RewriteOpDraft[];
+    readonly captures?: C;
+    readonly diagnostics?: readonly Diagnostic[];
+}
+interface MatchContext {
+    readonly node: DeepReadonly<IRElement>;
+    readonly doc: DeepReadonly<IRDocument>;
+    readonly resolver: StyleResolver;
+    readonly selectors: SelectorIndex;
+    readonly safety: SafetyLevel;
+    readonly phase: PassPhase;
+    readonly iteration: number;
+    parent(): DeepReadonly<IRElement> | null;
+    elementChildren(): readonly DeepReadonly<IRElement>[];
+    onlyElementChild(): DeepReadonly<IRElement> | null;
+    computed(): StyleMap;
+    computedOf(n: NodeLike): StyleMap;
+    isOpaque(n?: ElementLike): boolean;
+    ancestors(): readonly DeepReadonly<IRElement>[];
+    closest(pred: (el: DeepReadonly<IRElement>) => boolean): DeepReadonly<IRElement> | null;
+    prevSibling(): DeepReadonly<IRNode> | null;
+    nextSibling(): DeepReadonly<IRNode> | null;
+    nthChildIndex(): number;
+}
+/** Context handed to the `rewrite` phase: a MatchContext plus the typed captures. */
+interface RewriteContext<C extends Captures = Captures> extends MatchContext {
+    readonly captures: C;
+}
+interface Pattern {
+    readonly name: PatternName;
+    readonly category: PassCategory;
+    readonly safety: SafetyLevel;
+    readonly priority?: number;
+    readonly precondition?: PreconditionSketch;
+    readonly doc?: PatternDoc;
+    /** Pure. Returns a MatchResult (op drafts) or null on no-match. MUST NOT mutate. */
+    evaluate(ctx: MatchContext, rw: RewriteFactory): MatchResult | null;
+}
+interface Pass {
+    readonly phase: PassPhase;
+    readonly category: PassCategory;
+    readonly patterns: readonly Pattern[];
+}
+interface FixpointConfig {
+    readonly maxIterations: number;
+    readonly phases: Partial<Record<PassPhase, number>>;
+    readonly onBudgetExhausted: 'warn' | 'error';
+    readonly detectOscillation: boolean;
+}
+type HaltReason = 'converged' | 'budget' | 'oscillation' | 'error';
+interface PhaseRunResult {
+    readonly phase: PassPhase;
+    readonly iterations: number;
+    readonly converged: boolean;
+    readonly haltReason: HaltReason;
+    readonly touched: ReadonlySet<IRNodeId>;
+    readonly diagnostics: readonly Diagnostic[];
+}
+interface RewriteGroup {
+    readonly pattern: PatternName;
+    readonly anchor: IRNodeId;
+    readonly ops: readonly RewriteOp[];
+}
+/**
+ * VERIFIER-GATED flatten policy (the "identical UI" safety guarantee).
+ *
+ *   • `'all'`             — commit every flatten the patterns produce (subject only to the existing
+ *                            emittability revert). The historical behaviour; the pattern auto-test
+ *                            harness runs in this mode so authored examples are validated in isolation.
+ *   • `'provably-safe'`   — commit ONLY flattens that provably change nothing renderable (the wrapper
+ *                            contributes no own box/formatting context and drops no style, and the
+ *                            rewrite makes no parent-context assumption). Every other flatten is
+ *                            reverted via the inverse journal. This is the default for the `domflax`
+ *                            orchestrator + CLI: domflax never changes rendering by default, and it is
+ *                            the ONLY user-facing behaviour — the transform is fully static and never
+ *                            launches a browser.
+ */
+type FlattenGate = 'all' | 'provably-safe';
+interface ApplyContext {
+    readonly doc: IRDocument;
+    readonly safetyCeiling: SafetyLevel;
+    readonly normalizer: StyleNormalizer;
+    readonly selectors: SelectorIndex;
+    readonly resolver: StyleResolver;
+    /** Flatten safety policy. Defaults to `'all'` when omitted (historical behaviour). */
+    readonly gate?: FlattenGate;
+}
+interface StructuralInverse {
+    readonly kind: 'structural';
+    readonly describe: string;
+    readonly snapshot: unknown;
+}
+interface AppliedOp {
+    readonly op: RewriteOp;
+    readonly inverse: RewriteOp | StructuralInverse;
+}
+interface OpValidationIssue {
+    readonly op: RewriteOp;
+    readonly code: DiagnosticCode;
+    readonly message: string;
+}
+interface SkippedOpGroup {
+    readonly group: RewriteGroup;
+    readonly issues: readonly OpValidationIssue[];
+}
+interface ApplyResult {
+    readonly touched: ReadonlySet<IRNodeId>;
+    readonly removed: ReadonlySet<IRNodeId>;
+    readonly created: ReadonlySet<IRNodeId>;
+    readonly appliedGroups: number;
+    readonly skipped: readonly SkippedOpGroup[];
+    readonly journal: readonly AppliedOp[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+interface PassManager {
+    run(doc: IRDocument, ctx: ApplyContext, config?: FixpointConfig): readonly PhaseRunResult[];
+}
+interface FrontendConfig {
+    readonly jsxImportSource?: string;
+    readonly preserveComments?: boolean;
+    readonly [key: string]: unknown;
+}
+interface FrontendParseContext {
+    readonly id: string;
+    readonly kind: FileKind;
+    readonly resolver: StyleResolver;
+    readonly normalizer: StyleNormalizer;
+    readonly config: FrontendConfig;
+    onDiagnostic(d: Diagnostic): void;
+    babelAst?: unknown;
+}
+interface ParseResult {
+    readonly doc: IRDocument;
+    readonly diagnostics: readonly Diagnostic[];
+}
+interface Frontend {
+    readonly name: string;
+    readonly langs: readonly FileKind[];
+    canParse(id: string, code: string): boolean;
+    parse(code: string, ctx: FrontendParseContext): ParseResult;
+}
+interface ReindentSpec {
+    readonly baseIndent: string;
+    readonly delta: number;
+}
+interface TextEdit {
+    readonly span: SourceSpan;
+    readonly replacement: string;
+    readonly reindent?: ReindentSpec;
+    readonly origin: string;
+}
+interface EditPlan {
+    readonly moduleId: string;
+    readonly ops: readonly RewriteOp[];
+    readonly provenance: ReadonlyMap<number, PatternName>;
+}
+interface EncodedSourceMap {
+    readonly version: 3;
+    readonly sources: readonly string[];
+    readonly sourcesContent?: readonly (string | null)[];
+    readonly names: readonly string[];
+    readonly mappings: string;
+    readonly file?: string;
+}
+interface BackendContext {
+    readonly normalizer: StyleNormalizer;
+    readonly resolver: StyleResolver;
+    readonly sink: SyntheticSink;
+    readonly eol: '\n' | '\r\n';
+    onDiagnostic(d: Diagnostic): void;
+}
+interface CodegenResult {
+    readonly code: string;
+    readonly map: EncodedSourceMap | null;
+    readonly edits: readonly TextEdit[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+interface Backend {
+    readonly name: string;
+    readonly langs: readonly FileKind[];
+    print(doc: IRDocument, plan: EditPlan, ctx: BackendContext): CodegenResult;
+}
+interface PipelineConfig {
+    readonly safety: SafetyLevel;
+    readonly fixpoint?: Partial<FixpointConfig>;
+    readonly preserveComments?: boolean;
+    readonly emitSourceMap?: boolean;
+}
+interface PipelineInput {
+    readonly code: string;
+    readonly id: string;
+    readonly kind: FileKind;
+    readonly frontend: Frontend;
+    readonly backend: Backend;
+    readonly resolver: StyleResolver;
+    readonly normalizer: StyleNormalizer;
+    readonly passes: readonly Pass[];
+    readonly config?: PipelineConfig;
+    readonly reporter?: Reporter;
+    readonly babelAst?: unknown;
+}
+interface PipelineStats {
+    readonly nodesIn: number;
+    readonly nodesOut: number;
+    readonly opsApplied: number;
+    readonly iterations: Readonly<Record<PassPhase, number>>;
+    readonly durationMs: number;
+}
+interface PipelineOutput {
+    readonly code: string;
+    readonly map: EncodedSourceMap | null;
+    readonly changed: boolean;
+    readonly touched: readonly SourceSpan[];
+    readonly diagnostics: readonly Diagnostic[];
+    readonly stats: PipelineStats;
+    readonly doc: IRDocument;
+    readonly editPlan: EditPlan;
+}
+/** The pure single-file pipeline. Adapters/orchestrator call this; the verifier reuses it. */
+interface Pipeline {
+    run(input: PipelineInput): PipelineOutput;
+}
+
+/**
+ * @domflax/core — runtime builders + traversal.
+ *
+ * Pure, dependency-free helpers to construct IR nodes, assemble an {@link IRDocument},
+ * and walk the tree honouring {@link VisitSignal}. No heavy third-party deps: only the
+ * type contract in `./types`.
+ */
+
+/** Monotonic IRNodeId allocator. `peek` reports the id `next()` would return. */
+declare function createIdAllocator(start?: number): IdAllocator;
+/** Minimal in-memory ExprRegistry. */
+declare function createExprRegistry(start?: number): ExprRegistry;
+/** Mutable BackrefTable: frontends register backrefs as they parse. */
+interface MutableBackrefTable extends BackrefTable {
+    set(id: IRNodeId, backref: Backref): void;
+}
+declare function createBackrefTable(): MutableBackrefTable;
+/** A NodeMeta with every barrier/flag cleared. */
+declare function defaultMeta(safetyFloor?: SafetyLevel): NodeMeta;
+/** Canonical base style condition (`media:'' states:[] pseudoElement:''`). */
+declare const BASE_CONDITION: StyleCondition;
+/** Stable serialization of a StyleCondition into a ConditionKey. */
+declare function conditionKey(c: StyleCondition): ConditionKey;
+declare const BASE_CONDITION_KEY: ConditionKey;
+/** An empty StyleMap (no blocks). */
+declare function emptyStyleMap(): StyleMap;
+/** An empty (absent) ClassList. */
+declare function emptyClassList(): ClassList;
+/** An empty AttrMap. */
+declare function emptyAttrMap(): AttrMap;
+/** An empty InlineStyle. */
+declare function emptyInlineStyle(): InlineStyle;
+interface ElementInit {
+    readonly tag: string;
+    readonly namespace?: IRNamespace;
+    readonly isComponent?: boolean;
+    readonly selfClosing?: boolean;
+    readonly classes?: ClassList;
+    readonly inlineStyle?: InlineStyle;
+    readonly computed?: StyleMap;
+    readonly attrs?: AttrMap;
+    readonly children?: IRNodeId[];
+    readonly parent?: IRNodeId | null;
+    readonly span?: SourceSpan | null;
+    readonly meta?: NodeMeta;
+}
+declare function createElement(id: IRNodeId, init: ElementInit): IRElement;
+declare function createText(id: IRNodeId, value: string, opts?: {
+    collapsible?: boolean;
+    parent?: IRNodeId | null;
+    span?: SourceSpan | null;
+}): IRText;
+declare function createExpr(id: IRNodeId, expr: ExprRef, opts?: {
+    parent?: IRNodeId | null;
+    span?: SourceSpan | null;
+}): IRExpr;
+declare function createFragment(id: IRNodeId, opts?: {
+    children?: IRNodeId[];
+    parent?: IRNodeId | null;
+    span?: SourceSpan | null;
+}): IRFragment;
+declare function createComment(id: IRNodeId, value: string, opts?: {
+    parent?: IRNodeId | null;
+    span?: SourceSpan | null;
+}): IRComment;
+/** Build an empty document whose root is a fresh fragment. */
+declare function createDocument(frontend: FrontendKind): IRDocument;
+/** Returns the child id list for container nodes, or an empty array. */
+declare function childIds(node: IRNode): readonly IRNodeId[];
+/** Returns the node, or undefined. */
+declare function getNode(doc: IRDocument, id: IRNodeId): IRNode | undefined;
+/** Returns the node iff it is an element. */
+declare function getElement(doc: IRDocument, id: IRNodeId): IRElement | undefined;
+/** Pre-order list of every element id reachable from the root. */
+declare function elementIds(doc: IRDocument): IRNodeId[];
+/**
+ * Depth-first pre/post-order walk. `enter` may return `'skip'` (don't descend) or `'stop'`
+ * (abort the whole walk); `exit` may return `'stop'`. The visitor receives a live {@link IRNode}
+ * plus a {@link VisitContext} exposing depth and the parent node.
+ */
+declare function walk(doc: IRDocument, visitor: Visitor): void;
+
+/**
+ * @domflax/pattern-kit — composable matcher vocabulary.
+ *
+ * A {@link Matcher} is a PURE predicate over a node + its {@link MatchContext}. Matchers never
+ * mutate; they only read the (DeepReadonly) IR and the precomputed targeting/selector facts the
+ * context exposes. Authors compose them with {@link and}/{@link or}/{@link not} and feed the
+ * result into a pattern's `evaluate`.
+ *
+ * Style-aware matchers (`computed`, `hasOwnVisualStyle`) reason over the NORMALIZED StyleMap via
+ * the shared normalizer in `./normalize`, so they query meaning, not raw CSS strings.
+ */
+
+/** A pure predicate: does `node` satisfy this condition in the given match context? */
+type Matcher = (node: NodeLike, ctx: MatchContext) => boolean;
+/** Logical AND. Empty list ⇒ always matches. Short-circuits on the first failure. */
+declare function and(...matchers: readonly Matcher[]): Matcher;
+/** Logical OR. Empty list ⇒ never matches. Short-circuits on the first success. */
+declare function or(...matchers: readonly Matcher[]): Matcher;
+/** Logical NOT. */
+declare function not(matcher: Matcher): Matcher;
+/** Matches any element; with `tag`, only elements whose (case-insensitive) tag equals it. */
+declare function isElement(tag?: string): Matcher;
+/** Matches an element with exactly one ELEMENT child (text/expr/comment children ignored). */
+declare const hasSingleElementChild: Matcher;
+/**
+ * Matches when the node's computed StyleMap is a SUPERSET of `partial` — i.e. every declaration
+ * in `partial` is present in `node.computed` with an equal normalized value. Comparison is
+ * meaning-based (both sides normalized first). Empty `partial` always matches.
+ */
+declare function computed(partial: StyleMap): Matcher;
+/**
+ * Matches when the element paints something of its own: a meaningful background, border, shadow,
+ * outline, filter, etc. across ANY style condition. Honours the frontend-set `meta.hasOwnVisualStyle`
+ * fast-path, then falls back to scanning the normalized computed StyleMap.
+ */
+declare const hasOwnVisualStyle: Matcher;
+/** Element carries a `ref` (hard opacity barrier). */
+declare const hasRef: Matcher;
+/** Element has event handlers (onClick, …). */
+declare const hasEventHandlers: Matcher;
+/** Element has dynamic children (mapped/conditional islands). */
+declare const hasDynamicChildren: Matcher;
+/** Element's class list contains a dynamic segment (template/expr) → not freely rewritable. */
+declare const hasDynamicClasses: Matcher;
+/**
+ * Element's class list is wholly dynamic / spread-derived (`classes.opaque`, or spread attrs) — its
+ * concrete tokens can't be seen or statically rewritten, so a class-rewriting (compress) pattern
+ * must decline. Delegates to the context's authoritative {@link MatchContext.isOpaque}.
+ */
+declare const opaque: Matcher;
+/**
+ * Element is the subject of a combinator selector (`>`/`+`/`~`). Honours the frontend-set meta
+ * flag and the precomputed {@link SelectorIndex} in the context.
+ */
+declare const targetedByCombinator: Matcher;
+
+/**
+ * @domflax/pattern-kit — `definePattern()`: THE declarative pattern-authoring surface.
+ *
+ * `definePattern(config)` is the single public way to author a rewrite pattern: definition AND its
+ * tests are co-located in one call. It compiles down to the private lower-level
+ * {@link import('./define').validatePattern}/{@link Pattern} contract (it never replaces the
+ * engine). Authors describe the match as a plain DATA object and the rewrite as a named RECIPE; this
+ * module maps each key to the existing matcher combinators and op-draft factories, auto-applies the
+ * phase-appropriate safety guards (the full opacity-barrier + selector set for `flatten/*`; the
+ * narrower class-rewrite-safety set for `compress/*`) so authors never hand-write them, and threads
+ * `doc`/`test` through. Two escape hatches — a `match` predicate and a `rewrite` function — keep
+ * exotic patterns (e.g. ones anchored on a parent fragment) expressible.
+ *
+ * The co-located {@link PatternTest} (`provider`/`cssFiles`/`cases`/`noMatch`/`custom`) is carried on
+ * the compiled {@link AuthoredPattern} as `.test`, where the generic harness (`./testing`) reads it:
+ * each `case` asserts `before → after`, each `noMatch` asserts the input is left unchanged, and the
+ * optional `custom` hook runs arbitrary assertions against the built transform.
+ *
+ * `style` blocks in the declarative match (and in `childGains`/`mergeStyle` recipes) are PLAIN
+ * objects (camelCase or kebab keys) auto-normalized into a superset StyleMap via the shared
+ * normalizer — authors never import the normalizer or hand-build a StyleMap.
+ *
+ * `pattern` remains exported as a DEPRECATED alias of `definePattern` for backward compatibility.
+ */
+
+/** A plain CSS style object: camelCase or kebab-case keys, string or number values. */
+type PlainStyle = Readonly<Record<string, string | number>>;
+/**
+ * Declarative match as DATA. Every key maps to one of the existing matcher combinators; an empty
+ * object matches any element. Use the `match` FUNCTION escape hatch for anything not expressible
+ * here (relational/ancestor/sibling shapes, parent-anchored patterns, …).
+ */
+interface DeclarativeMatch {
+    /** Restrict to a tag (case-insensitive). Omit to match any element. */
+    readonly tag?: string;
+    /** Computed style the node must be a SUPERSET of (plain object, auto-normalized). */
+    readonly style?: PlainStyle;
+    /** Require exactly one ELEMENT child. */
+    readonly onlyChild?: 'element';
+    /** Require the element to paint nothing of its own (no own visual style). */
+    readonly paintsNothing?: boolean;
+    /** Extra, hand-written predicate AND-ed into the declarative match. */
+    readonly where?: Matcher | readonly Matcher[];
+}
+/** Escape hatch: a raw match predicate (no auto-guards are added). */
+type MatchFn = (node: NodeLike, ctx: MatchContext) => boolean;
+/**
+ * Flatten recipe: fold inherited styles onto the sole element child (default on), optionally merge
+ * `childGains` onto it, then unwrap the node (id-preserving). Mirrors the flatten exemplars.
+ */
+interface FlattenIntoRecipe {
+    readonly flattenInto: 'child';
+    /** Plain style merged onto the surviving child (source-wins) before unwrap. */
+    readonly childGains?: PlainStyle;
+    /** Fold inheritable declarations onto the child first. Default `true`. */
+    readonly foldInherited?: boolean;
+}
+/** Compress recipe: rebuild the element's class StyleMap; return `null` to decline. */
+interface RewriteClassesRecipe {
+    readonly rewriteClasses: (computed: StyleMap, ctx: MatchContext) => StyleMap | null;
+    /** Keep opaque/selector-bound tokens verbatim. Default `true`. */
+    readonly preserveOpaque?: boolean;
+}
+/** Compress recipe: drop fully-overridden class tokens (provenance is pruned automatically). */
+interface DropClassesRecipe {
+    readonly dropClasses: (computed: StyleMap, ctx: MatchContext) => Iterable<string>;
+    /** Keep opaque/selector-bound tokens verbatim. Default `true`. */
+    readonly preserveOpaque?: boolean;
+}
+/** Merge a literal plain style onto the matched element. */
+interface MergeStyleRecipe {
+    readonly mergeStyle: PlainStyle;
+    readonly onConflict?: StyleConflictPolicy;
+}
+type RewriteRecipe = FlattenIntoRecipe | RewriteClassesRecipe | DropClassesRecipe | MergeStyleRecipe;
+/** Escape hatch: a raw rewrite that returns op drafts (or `null`/`[]` for no-op). */
+type RewriteFn = (ctx: MatchContext, rw: RewriteFactory) => readonly RewriteOpDraft[] | null;
+/** A single positive before→after assertion run through the pattern's built transform. */
+interface PatternTestCase {
+    readonly name?: string;
+    readonly before: string;
+    readonly after: string;
+}
+/** Helpers handed to a {@link PatternTest.custom} hook (the built transform + expectation sugar). */
+interface TestHelpers {
+    /** Run the pattern's transform on `code` (default filename `'X.tsx'`). */
+    readonly transform: (code: string, filename?: string) => string;
+    /** Assert `before` transforms to `after` (whitespace-normalized). */
+    readonly expectTransforms: (before: string, after: string) => void;
+    /** Assert `code` is left unchanged (whitespace-normalized). */
+    readonly expectUnchanged: (code: string) => void;
+}
+/**
+ * Co-located test spec for a pattern. The generic harness (`./testing`) builds a transform for the
+ * declared `provider` (default `'tailwind'`; `'custom'` resolves the listed `cssFiles`), then runs
+ * every `case` (`before → after`), every `noMatch` (left unchanged), and the optional `custom` hook.
+ */
+interface PatternTest {
+    /** Which style provider the harness builds the transform from. Default `'tailwind'`. */
+    readonly provider?: 'tailwind' | 'custom';
+    /** For `provider: 'custom'` — the project stylesheet paths backing the CSS resolver. */
+    readonly cssFiles?: readonly string[];
+    /** Positive before→after assertions. */
+    readonly cases?: readonly PatternTestCase[];
+    /** Inputs the pattern must leave UNCHANGED (barriers, non-matching shapes, safety reverts). */
+    readonly noMatch?: readonly string[];
+    /** Arbitrary extra assertions against the built transform. */
+    readonly custom?: (h: TestHelpers) => void;
+}
+interface PatternConfig {
+    readonly name: string;
+    readonly category: PassCategory;
+    readonly safety: SafetyLevel;
+    readonly priority?: number;
+    readonly precondition?: PreconditionSketch;
+    readonly doc?: PatternDoc;
+    /** Co-located tests consumed by the generic harness (`./testing`). */
+    readonly test?: PatternTest;
+    /** Declarative match DATA, or a raw predicate escape hatch. Defaults to "any element". */
+    readonly match?: DeclarativeMatch | MatchFn;
+    /** A named rewrite recipe, or a raw op-draft factory escape hatch. */
+    readonly rewrite: RewriteRecipe | RewriteFn;
+}
+/** A {@link Pattern} that also carries its co-located {@link PatternTest} for the test harness. */
+interface AuthoredPattern<C extends Captures = Captures> extends Pattern {
+    readonly test?: PatternTest;
+    evaluate(ctx: MatchContext, rw: RewriteFactory): MatchResult<C> | null;
+}
+/**
+ * THE declarative pattern-authoring function. Compile a {@link PatternConfig} (definition + co-located
+ * {@link PatternTest}) into a validated {@link AuthoredPattern}: a normal {@link Pattern} (registerable
+ * into any {@link import('@domflax/core').Pass}) that also exposes its `test` for the generic harness.
+ */
+declare function definePattern(config: PatternConfig): AuthoredPattern;
+/**
+ * @deprecated Use {@link definePattern}. Retained as a thin alias for backward compatibility.
+ */
+declare const pattern: typeof definePattern;
+
+export { type Frontend as $, type AuthoredPattern as A, type ApplyContext as B, type MatchContext as C, type DeclarativeMatch as D, type FixpointConfig as E, type FlattenIntoRecipe as F, type Pass as G, type HaltReason as H, type PassManager as I, type Pattern as J, type PhaseRunResult as K, type Pipeline as L, type MatchFn as M, type Captures as N, type EncodedSourceMap as O, type PatternConfig as P, type AppliedOp as Q, type RewriteClassesRecipe as R, BASE_CONDITION as S, type TestHelpers as T, BASE_CONDITION_KEY as U, type Backend as V, type BackendContext as W, type CodegenResult as X, type EditPlan as Y, type ElementInit as Z, type FlattenGate as _, type DropClassesRecipe as a, type FrontendConfig as a0, type FrontendParseContext as a1, type MatchResult as a2, type MutableBackrefTable as a3, type OpValidationIssue as a4, type ParentLayoutContext as a5, type ParseResult as a6, type PatternDoc as a7, type PipelineConfig as a8, type PipelineInput as a9, getElement as aA, getNode as aB, walk as aC, type PipelineOutput as aa, type PipelineStats as ab, type PreconditionSketch as ac, type ReindentSpec as ad, type RewriteContext as ae, type SkippedOpGroup as af, type StructuralInverse as ag, type StylePredicate as ah, type TextEdit as ai, type TreeShapeSketch as aj, childIds as ak, conditionKey as al, createBackrefTable as am, createComment as an, createDocument as ao, createElement as ap, createExpr as aq, createExprRegistry as ar, createFragment as as, createIdAllocator as at, createText as au, defaultMeta as av, elementIds as aw, emptyAttrMap as ax, emptyClassList as ay, emptyInlineStyle as az, type Matcher as b, type MergeStyleRecipe as c, type PatternTest as d, type PatternTestCase as e, type PlainStyle as f, type RewriteFn as g, type RewriteRecipe as h, and as i, computed as j, definePattern as k, emptyStyleMap as l, hasDynamicChildren as m, hasDynamicClasses as n, hasEventHandlers as o, hasOwnVisualStyle as p, hasRef as q, hasSingleElementChild as r, isElement as s, not as t, opaque as u, or as v, pattern as w, targetedByCombinator as x, type ApplyResult as y, type RewriteGroup as z };