@stll/template-conditions 0.3.0 → 0.5.0

package/README.md

@@ -7,7 +7,7 @@ functions usable on both backend (Bun) and frontend (browser).
 
 Boolean conditions are evaluated through the canonical
 [`@stll/conditions`](https://github.com/stella/stella/tree/main/packages/conditions)
-AST and its single evaluator, so template `{{#if ...}}` conditionals share one
+AST and its single evaluator, so template `{% if ... %}` conditionals share one
 set of operators and semantics with the rest of the system. This package owns
 the template surface: the marker grammar, the string parser, the named-condition
 resolver, the numeric expression evaluator, and the no-code builder serializer.

package/dist/index.d.ts

@@ -6,6 +6,22 @@ declare const resolvePath: (path: string, data: Record<string, unknown>) => unkn
 //#region src/parse.d.ts
 declare const parseCondition: (expression: string) => ConditionNode$1 | null;
 //#endregion
+//#region src/referenced-paths.d.ts
+/**
+ * What a `{% if %}` expression reads. Structural, not evaluative: the paths a
+ * condition depends on, for callers that decide something about the condition
+ * itself rather than about a document being filled.
+ */
+/**
+ * Every field path an expression reads, in source order.
+ *
+ * `null` says the expression does not answer the question: it did not parse,
+ * or it reads an operand whose own references cannot be enumerated. A caller
+ * deciding what a condition depends on must not read that as "depends on
+ * nothing".
+ */
+declare const referencedConditionPaths: (expression: string) => string[] | null;
+//#endregion
 //#region src/compute.d.ts
 /**
  * Arithmetic evaluator for computed template fields.
@@ -31,8 +47,8 @@ declare const evaluateNumericExpression: (expression: string, data: Record<strin
 //#region src/field-values.d.ts
 /**
  * Single source of truth for the DETERMINISTIC field-value transforms a
- * template fill applies — composite (parts joined by a `{{key}}` format),
- * formula (arithmetic over the other values), and locale-aware date rendering.
+ * template fill applies: formula (arithmetic over the other values) and
+ * locale-aware date rendering.
  *
  * Both the API fill engine (apps/api/src/handlers/docx) and the web live
  * preview (template-studio.tsx) MUST route their rendering through
@@ -67,18 +83,6 @@ type FieldDateFormat = {
  * returns null.
  */
 declare const formatDate: (value: string, dateFormat: FieldDateFormat) => string | null;
-/** Minimal structural shape of one composite field part: only the `key`
- *  referenced by the join format is needed to render. Callers' richer part
- *  types (api FieldPart, web EditablePart) structurally satisfy this. */
-type PartConfig = {
-  key: string;
-};
-/**
- * Render a `{{key}}` format over part values. Markers whose key has no part
- * value are left as-is (a visible authoring artifact, not a render error), so
- * a partially filled composite previews exactly as the fill engine renders it.
- */
-declare const renderComposite: (parts: readonly PartConfig[], format: string, partValues: Readonly<Record<string, string>>) => string;
 /**
  * Minimal STRUCTURAL config of a field, carrying only what the deterministic
  * transforms read. Callers (api FieldMeta, web StudioField) structurally
@@ -88,8 +92,6 @@ declare const renderComposite: (parts: readonly PartConfig[], format: string, pa
 type DeterministicFieldConfig = {
   path: string;
   inputType?: string | undefined;
-  parts?: readonly PartConfig[] | undefined;
-  format?: string | undefined;
   formula?: string | undefined;
   dateFormat?: FieldDateFormat | undefined;
 };
@@ -99,16 +101,13 @@ type DeterministicFieldConfig = {
  * no deterministic transform (a scalar, lookup, or AI field the CALLER renders
  * itself).
  *
- * Dispatch order mirrors the API fill pipeline (composite → formula → date):
- *   - composite (parts + format present) → {@link renderComposite}
- *   - else formula present → {@link evaluateNumericExpression}, stringified
+ * Dispatch order mirrors the API fill pipeline (formula → date):
+ *   - formula present → {@link evaluateNumericExpression}, stringified
  *   - else date (inputType "date" + dateFormat) → {@link formatDate}
  *   - else null
  *
- * Composite returns null when its value is not an object of part values (a
- * plain string passes through unchanged on the api side, so the caller's
- * scalar path handles it). Formula and date return null when the expression /
- * value does not yield a value, so the caller leaves the field as-is.
+ * Formula and date return null when the expression or value does not yield a
+ * value, so the caller leaves the field as-is.
  */
 declare const renderDeterministicFieldValue: (field: DeterministicFieldConfig, values: Record<string, unknown>) => string | null;
 //#endregion
@@ -122,22 +121,47 @@ declare const serializeCondition: (node: ConditionNode$1) => string;
 //#endregion
 //#region src/markers.d.ts
 /**
- * Canonical grammar for `{{...}}` template markers — the single source of truth
- * shared by the fill pipeline (api), the editor highlighter (folio), and the
- * read-only preview (web).
+ * Canonical grammar for the docxtpl dialect of Jinja — the single source of
+ * truth shared by the fill pipeline (api), the editor highlighter (folio), and
+ * the read-only preview (web).
+ *
+ * Two spans carry meaning: an output marker `{{ ... }}` prints a value, and a
+ * tag `{% ... %}` opens or closes a block. A tag may carry a docxtpl placement
+ * prefix — `{%p ... %}` owns its paragraph, `{%tr ... %}` owns its table row —
+ * and a bare tag is placed by the leniency rules the consumer applies.
  *
  * Add a new directive to `MarkerMeta` and teach {@link classifyMarker} to
  * recognize it. Compile-time totality checks then require its ordered runtime
  * value and its block/inline disposition, while exhaustive consumer switches
  * fail until they handle it.
  *
- * No consumer should define its own `{{...}}` regex. The low-level pattern
+ * No consumer should define its own marker regex. The low-level pattern
  * factories below exist so handlers that mutate raw XML/text reuse the exact
  * same literals; recognizers should prefer the high-level scanner.
  */
+/** A literal an author can write inside a filter or function call. */
+type MarkerLiteral = string | number | boolean;
+/** One argument of a filter call: positional, or `name=value`. */
+type FilterArgument = {
+  kind: "positional";
+  value: MarkerLiteral;
+} | {
+  kind: "keyword";
+  name: string;
+  value: MarkerLiteral;
+};
+/** One `| name` / `| name(args)` step of an output marker's filter chain. */
+type FilterCall = {
+  name: FilterName;
+  args: readonly FilterArgument[];
+};
+/** The loop properties addressable inside a `{% for %}` body. */
+declare const LOOP_PROPERTIES: readonly ["index", "index0", "first", "last", "length"];
+type LoopProperty = (typeof LOOP_PROPERTIES)[number];
 type MarkerMeta = {
   kind: "placeholder";
   expr: string;
+  filters: readonly FilterCall[];
 } | {
   kind: "clause";
   name: string;
@@ -149,134 +173,377 @@ type MarkerMeta = {
   kind: "ref";
   key: string;
 } | {
-  kind: "index";
-} | {
-  kind: "count";
+  kind: "loop";
+  property: LoopProperty;
 } | {
   kind: "if";
   expr: string;
 } | {
-  kind: "elseif";
+  kind: "elif";
   expr: string;
 } | {
   kind: "else";
 } | {
   kind: "endif";
 } | {
-  kind: "each";
-  expr: string;
+  kind: "for";
+  alias: string;
+  path: string;
+  /** Filters on the loop path configure the ARRAY: how many rows it takes
+   *  and what to call it. */
+  filters: readonly FilterCall[];
 } | {
-  kind: "endeach";
+  kind: "endfor";
 };
 type DirectiveKind = MarkerMeta["kind"];
-declare const DIRECTIVE_KINDS: readonly ["placeholder", "clause", "num", "ref", "index", "count", "if", "elseif", "else", "endif", "each", "endeach"];
+declare const DIRECTIVE_KINDS: readonly ["placeholder", "clause", "num", "ref", "loop", "if", "elif", "else", "endif", "for", "endfor"];
 declare const DIRECTIVE_PLACEMENT: {
   readonly placeholder: "inline";
   readonly clause: "inline";
   readonly num: "inline";
   readonly ref: "inline";
-  readonly index: "inline";
-  readonly count: "inline";
+  readonly loop: "inline";
   readonly if: "block";
-  readonly elseif: "block";
+  readonly elif: "block";
   readonly else: "block";
   readonly endif: "block";
-  readonly each: "block";
-  readonly endeach: "block";
+  readonly for: "block";
+  readonly endfor: "block";
 };
 type BlockDirectiveKind = { [TKind in DirectiveKind]: (typeof DIRECTIVE_PLACEMENT)[TKind] extends "block" ? TKind : never; }[DirectiveKind];
 /** Directives that occupy their own paragraph, in canonical grammar order. */
-declare const BLOCK_DIRECTIVE_KINDS: readonly ["if", "elseif", "else", "endif", "each", "endeach"];
+declare const BLOCK_DIRECTIVE_KINDS: readonly ["if", "elif", "else", "endif", "for", "endfor"];
 declare const isBlockDirectiveKind: (kind: unknown) => kind is BlockDirectiveKind;
-/** Any `{{...}}` marker; group 1 is the inner text (untrimmed — callers trim). */
+/**
+ * Every filter the dialect accepts on a fillable value. The names are the
+ * grammar's; which manifest property each one writes is decided by the field
+ * catalogue in the api, which is total over BOTH this list and the manifest
+ * keys, so neither side can gain an entry the other has not decided.
+ */
+declare const FILTER_NAMES: readonly ["text", "number", "date", "checkbox", "select", "options_from", "label", "hint", "required", "pattern", "min", "max", "min_length", "max_length", "min_items", "max_items", "ai", "lookup", "matter", "contact", "party", "attorney", "firm", "formula", "condition"];
+type FilterName = (typeof FILTER_NAMES)[number];
+/** Normalise one marker's inner text: typographic quotes become straight
+ *  quotes, fixed-width spaces become ordinary ones. */
+declare const normalizeMarkerInner: (inner: string) => string;
+/**
+ * What an output marker holds between its braces: anything but a brace or a
+ * double quote, plus whole double-quoted arguments, whose braces are content
+ * rather than the marker's own delimiters — `pattern("^[0-9]{5}$")` is a regex,
+ * not a nested marker. An apostrophe stays an ordinary character, so
+ * `label("Owner's")` reads as it always did.
+ *
+ * A quoted run honours `\`-escapes, the way the argument scanner reads them,
+ * so `label("she said \"yes\"")` is one span rather than three: the span and
+ * the scanner have to agree on where a literal ends or a marker the scanner
+ * would parse is one the recognizer never sees.
+ *
+ * The alternatives cannot overlap (the plain one excludes every character the
+ * quoted one may start with, and inside a quoted run the escape branch is the
+ * only one that starts with a backslash), so the scan stays linear on
+ * adversarial input: a `{{` with no closing `}}` costs one failed pass, not a
+ * polynomial retry.
+ */
+declare const MARKER_OUTPUT_BODY: string;
+/** What a tag holds between `{%` and `%}`: anything but a brace, and a `%`
+ *  only where it does not close the tag. */
+declare const MARKER_STATEMENT_BODY: string;
+/**
+ * Any marker span: an output `{{...}}` (group `output`) or a tag `{%...%}`
+ * (group `statement`, with the docxtpl placement in group `prefix`).
+ */
 declare const markerPattern: () => RegExp;
-/** Inline field / clause / numbering marker (inner allows the directive sigils). */
+/** Inline value marker, including its filter chain; group `name` is the path
+ *  the value comes from and group `filters` the untouched chain. */
 declare const placeholderPattern: () => RegExp;
-/** `{{@clause:Name}}` / `{{@clause:Name:v3}}` — `name` and `modifier` groups. */
+/** `{{ clause("Name") }}` / `{{ clause("Name", "v3") }}`. */
 declare const clauseSlotPattern: () => RegExp;
-/** `{{@num:Key}}` — the `key` group. */
+/** `{{ num("key") }}` — the `key` group. */
 declare const numPattern: () => RegExp;
-/** `{{@ref:Key}}` — the `key` group. */
+/** `{{ ref("key") }}` — the `key` group. */
 declare const refPattern: () => RegExp;
-/** `{{@index}}` — the 1-based position within the innermost enclosing loop. */
-declare const indexPattern: () => RegExp;
-/** `{{@count}}` — the item count of the innermost enclosing loop. */
-declare const countPattern: () => RegExp;
+/** `{{ loop.index }}` and its siblings — the `property` group. */
+declare const loopPattern: () => RegExp;
 /** Cheap presence test for any numbering marker (no capture). */
 declare const hasNumberingPattern: () => RegExp;
-/** Cheap presence test for any block directive (no capture). */
+/** Cheap presence test for any tag (no capture). */
 declare const hasBlockDirectivePattern: () => RegExp;
-/** A whole line that is a single block directive — `tag` and `expr` groups. */
+/** A whole line that is a single block tag — `prefix`, `tag` and `expr`. */
 declare const blockDirectiveLinePattern: () => RegExp;
 /** Whether `value` is a valid field path per the marker grammar (dotted
  *  segments of letters/digits/underscore/dash — no brackets or spaces). */
 declare const isFieldPath: (value: string) => boolean;
 /** Whether `value` is safe to use as a dotted object path. */
 declare const isSafeFieldPath: (value: string) => boolean;
-/** Whether `value` is a valid name for authoring a `{{@clause:NAME}}` slot:
- *  the intersection of the clause-slot parse grammar and the fill pipeline's
- *  placeholder charset, so every accepted name round-trips through fill. */
+/** Whether `value` is a valid name for authoring a `clause("NAME")` slot. */
 declare const isClauseSlotName: (value: string) => boolean;
+/** Which brace pair carried the marker text. */
+type MarkerForm = "output" | "statement";
+/** Where a tag's docxtpl prefix says the tag belongs. `"none"` is a bare tag,
+ *  placed by the consumer's leniency rules, and every output marker. */
+type MarkerPrefix = "none" | "paragraph" | "row";
 /**
- * Classify the inner text of a `{{...}}` marker. Returns `null` when the text is
- * not a recognized directive (so a recognizer can leave stray braces alone).
+ * Classify the inner text of one marker. Returns `null` when the text is not a
+ * recognized directive (so a recognizer can leave stray braces alone).
  */
-declare const classifyMarker: (innerRaw: string) => MarkerMeta | null;
+declare const classifyMarker: (innerRaw: string, form?: MarkerForm) => MarkerMeta | null;
 type ScannedMarker = {
-  /** Offset of `{{` in the source text. */
+  /** Offset of the opening brace pair in the source text. */
   start: number;
-  /** Offset just past `}}`. */
+  /** Offset just past the closing brace pair. */
   end: number;
-  /** The full matched marker, e.g. `{{@num:scope}}`. */
+  /** The full matched marker, e.g. `{% endfor %}`. */
   raw: string;
-  /** The (untrimmed) inner text. */
+  /** The normalized, trimmed inner text. */
   inner: string;
+  form: MarkerForm;
+  /** The docxtpl placement prefix the author wrote. */
+  prefix: MarkerPrefix;
   meta: MarkerMeta;
 };
 /**
- * Find every recognized `{{...}}` marker in `text`, in document order, with
- * offsets and classified metadata. Unrecognized `{{...}}` spans are skipped.
+ * Find every recognized marker in `text`, in document order, with offsets and
+ * classified metadata. Unrecognized spans are skipped.
  */
 declare const scanMarkers: (text: string) => ScannedMarker[];
-/** A `{{...}}` span that looks like a marker but classifies to nothing. */
+/**
+ * Rewrite every `{{ ... }}` output marker in `text` through `replace`, which
+ * receives the whole marker and its raw inner text and returns the replacement.
+ * Tags are left untouched. The single scan is the same one the classifier uses,
+ * so a caller that rewrites marker text never needs its own regex.
+ */
+declare const replaceOutputMarkers: (text: string, replace: (raw: string, inner: string) => string) => string;
+/**
+ * The values-map key one marker substitutes from, or `null` when the marker is
+ * not a substitution target (a tag, or a `loop.*` token the loop expander
+ * resolves first). One function so the key discovery writes is the key the
+ * patcher reads.
+ */
+declare const substitutionKey: (meta: MarkerMeta) => string | null;
+/** The values-map key for one clause slot. */
+declare const clauseSlotKey: (name: string, version?: string) => string;
+/** A marker-shaped span that classifies to nothing. */
 type InvalidMarker = {
-  /** Offset of `{{` in the source text. */
+  /** Offset of the opening brace pair in the source text. */
   start: number;
-  /** Offset just past `}}`. */
+  /** Offset just past the closing brace pair. */
   end: number;
   /** The full matched span, e.g. `{{my field}}`. */
   raw: string;
-  /** The (trimmed) inner text. */
+  /** The normalized, trimmed inner text. */
   inner: string;
+  form: MarkerForm;
 };
 /**
- * Find every `{{...}}` span whose inner text is NOT a recognized directive —
- * near-misses an author clearly meant as markers but that every recognizer
- * skips, so they print literally at fill time (e.g. `{{my field}}` with a
- * space, `{{@clause:}}` with no name). Offsets and raw text are shaped like
- * {@link scanMarkers} results, minus the classified `meta`. This is the exact
+ * Find every marker-shaped span whose inner text is NOT a recognized
+ * directive — near-misses an author clearly meant as markers but that every
+ * recognizer skips, so they print literally at fill time. This is the exact
  * complement of {@link scanMarkers}: a span is in one list or the other.
  */
 declare const scanInvalidMarkers: (text: string) => InvalidMarker[];
+/** The loop alias the codemod (and the legacy-marker message) generates for a
+ *  `{{#each path}}`: the singular of the last plain-word segment, else `item`. */
+declare const legacyLoopAlias: (path: string) => string;
+/** Translate an old-dialect condition expression to the Jinja surface:
+ *  `!a` becomes `not a`, `a contains "x"` becomes `"x" in a`. */
+declare const translateLegacyExpression: (expr: string) => string;
 /**
- * Why a `{{...}}` span misses the grammar in a way that names the authoring
- * mistake rather than merely failing to classify. Consumers derive their own
- * warning codes from {@link MARKER_DEFECT_KINDS} so the two never drift.
+ * The Jinja marker that replaces one old-dialect marker's inner text, or
+ * `null` when the text is not old-dialect. Shared by the rejection message and
+ * the codemod, so the fix an author is told to make is the fix the script
+ * would have made.
  */
-type MarkerDefectKind = "unknown_directive" | "bracket_index";
-declare const MARKER_DEFECT_KINDS: readonly ["unknown_directive", "bracket_index"];
+declare const legacyMarkerReplacement: (innerRaw: string) => string | null;
 /**
- * Name the authoring mistake behind one marker's inner text, or `null` when the
- * text is a recognized directive ({@link classifyMarker} accepts it) or an
- * unrecognizable span with no specific diagnosis (`{{my field}}`). The
- * recognized-directive check is what makes `DIRECTIVE_KINDS` the single
- * authority on which `{{#...}}` tokens exist: adding a directive to the grammar
- * stops it being reported here, with no list to update.
+ * Why a marker-shaped span misses the grammar in a way that names the
+ * authoring mistake rather than merely failing to classify. Consumers derive
+ * their own warning codes from {@link MARKER_DEFECT_KINDS} so the two never
+ * drift.
  */
-declare const classifyMarkerDefect: (innerRaw: string) => MarkerDefectKind | null;
+type MarkerDefectKind = "legacy_marker" | "unsupported_tag" | "unknown_filter" | "python_expression" | "bracket_index";
+declare const MARKER_DEFECT_KINDS: readonly ["legacy_marker", "unsupported_tag", "unknown_filter", "python_expression", "bracket_index"];
+/** One diagnosis of a rejected span: the kind plus the construct to quote. */
+type MarkerDefect = {
+  kind: MarkerDefectKind;
+  /** The construct the author wrote that the grammar refuses. */
+  construct: string;
+  /** The Jinja that replaces it, when the mistake has one exact fix. */
+  replacement?: string;
+};
+/**
+ * Name the authoring mistake behind one marker's inner text, or `null` when
+ * the text is a recognized directive ({@link classifyMarker} accepts it) or an
+ * unrecognizable span with no specific diagnosis (`{{my field}}`).
+ */
+declare const classifyMarkerDefect: (innerRaw: string, form?: MarkerForm) => MarkerDefect | null;
 /** Exhaustiveness guard — pass the discriminant in a `switch` default branch. */
 declare const assertNever: (value: never) => never;
 //#endregion
+//#region src/loop-scope.d.ts
+/**
+ * The path a marker names, once the loops around it are taken into account.
+ *
+ * `{% for attorney in attorneys %}{{ attorney.name }}{% endfor %}` writes one
+ * field, and the manifest calls it `attorneys.name`: the loop's alias is the
+ * body's name for the item, the array path is the manifest's. Discovery reads
+ * that mapping, and every writer that puts a configuration back into a marker
+ * has to reverse it, so the rule lives beside the grammar rather than in each
+ * of them; two readings of one loop are two different documents.
+ */
+/** One enclosing `{% for %}`, as the body sees it and as the manifest does. */
+type RowScope = {
+  /** The loop variable the body addresses items through. */
+  alias: string;
+  /** The array path the opener was written with, before its own enclosing
+   *  loops were applied. */
+  declaredPath: string;
+  /** The array path the manifest speaks, enclosing loops included. */
+  scopedPath: string;
+};
+declare const rowScopePaths: (rowScopes: readonly RowScope[]) => string[];
+/** A path already under the innermost repeat is left alone; anything else is
+ *  read as a name relative to it. */
+declare const qualifyRowScopedPath: (path: string, rowPaths?: readonly string[]) => string;
+/** The manifest path for a marker written inside these loops. */
+declare const qualifyRowScopedPlaceholder: (path: string, rowScopes: readonly RowScope[]) => string;
+/** The manifest path for an array a `{% for %}` opens inside these loops. */
+declare const qualifyLoopPath: (declaredPath: string, rowScopes: readonly RowScope[]) => string;
+//#endregion
+//#region src/field-config.d.ts
+/** Where a field's value comes from, when a record supplies it. Only the shape
+ *  the filters read: each caller's own union satisfies it. */
+type MarkerFieldSource = {
+  kind: "matter";
+  field: string;
+} | {
+  kind: "contact";
+  field: string;
+} | {
+  kind: "firm";
+  field: string;
+} | {
+  kind: "party";
+  role: string;
+  field: string;
+} | {
+  kind: "attorney";
+  ref: string;
+  field: string;
+};
+/** The constraints a chain can express. */
+type MarkerFieldValidation = {
+  required?: boolean | undefined;
+  pattern?: string | undefined;
+  min?: number | undefined;
+  max?: number | undefined;
+  minLength?: number | undefined;
+  maxLength?: number | undefined;
+  minItems?: number | undefined;
+  maxItems?: number | undefined;
+};
+/** A registry lookup and the renderings of its one resolved hit. */
+type MarkerFieldLookup = {
+  registry: string;
+  formats: readonly {
+    key: string;
+    template: string;
+  }[];
+};
+/** The input controls a marker can name. */
+type MarkerFieldInputType = "text" | "number" | "boolean" | "date" | "select";
+/**
+ * Everything about a field that a marker's filter chain can carry. A caller's
+ * own field type may hold more (a derived condition AST, a discovery count);
+ * those keys are simply not read here.
+ */
+type MarkerFieldConfig = {
+  path: string;
+  label?: string | undefined;
+  hint?: string | undefined;
+  inputType?: MarkerFieldInputType | undefined;
+  options?: readonly string[] | undefined;
+  optionsFrom?: string | undefined;
+  validation?: MarkerFieldValidation | undefined;
+  required?: boolean | undefined;
+  aiPrompt?: string | undefined;
+  aiAdapt?: boolean | undefined;
+  aiSeesDocument?: boolean | undefined;
+  lookup?: MarkerFieldLookup | undefined;
+  source?: MarkerFieldSource | undefined;
+  formula?: string | undefined;
+  condition?: string | undefined;
+  dateFormat?: FieldDateFormat | undefined;
+};
+/**
+ * The filters that describe a REPEAT rather than a value: how many rows it
+ * takes and what to call it. These are the ones a `{% for %}` tag may carry,
+ * since the loop path names the array, not one of its values.
+ */
+declare const ARRAY_FILTER_NAMES: readonly ["label", "hint", "required", "min_items", "max_items"];
+declare const isArrayFilterName: (name: FilterName) => boolean;
+/**
+ * The filter chain that declares this field in a document, in the catalogue's
+ * own order so a chain the writer produces and one an author wrote read the
+ * same.
+ */
+declare const filtersFromFieldConfig: (field: MarkerFieldConfig) => FilterCall[];
+/**
+ * The chain a `{% for %}` opener carries for this array: the repeat's own
+ * filters and nothing else, derived from {@link ARRAY_FILTER_NAMES}, so a
+ * value filter can never be written where the reader refuses it.
+ */
+declare const arrayFiltersFromFieldConfig: (field: MarkerFieldConfig) => FilterCall[];
+//#endregion
+//#region src/render.d.ts
+/** Why a value has no spelling the scanner reads back as itself. */
+type UnwritableReason = "tag-delimiter" | "number-spelling";
+/** The reason this literal cannot be written in a marker of this form, or
+ *  `null` when it can. A boolean always can; a string can in a `{{ }}` marker,
+ *  because the writer quotes and escapes it. */
+declare const unwritableMarkerLiteral: (value: MarkerLiteral, form?: MarkerForm) => UnwritableReason | null;
+/** Every value in a chain the grammar has no spelling for, with the filter it
+ *  was written on and why, so a caller can refuse a configuration before it
+ *  rewrites a document into something the scanner would read differently. A
+ *  repeat's chain goes in a tag, so pass `"statement"` for one. */
+declare const unwritableFilterValues: (filters: readonly FilterCall[], form?: MarkerForm) => {
+  filter: string;
+  value: MarkerLiteral;
+  reason: UnwritableReason;
+}[];
+/**
+ * One filter chain as marker text, without the leading pipe: `label("A") |
+ * required`. An empty chain renders the empty string, which is what a marker
+ * that configures nothing carries.
+ */
+declare const renderFilterChain: (filters: readonly FilterCall[]) => string;
+/** One value marker: `{{ path }}` or `{{ path | filters }}`. */
+declare const renderValueMarker: (path: string, filters: readonly FilterCall[]) => string;
+type ConditionTagOptions = {
+  /** Which branch opener this is; `elif` keeps its place in the chain. */
+  kind: "if" | "elif";
+  /** The `{% if %}` expression, already serialized. */
+  expression: string;
+  /** The placement the tag already carried. */
+  prefix: MarkerPrefix;
+};
+/**
+ * One `{% if %}` / `{% elif %}` opener carrying its expression.
+ *
+ * A rule that decides whether a block shows belongs in the tag that shows it:
+ * the tag is the only place a document has for it, so a builder's rule is
+ * serialized here rather than stored beside the document under a name.
+ */
+declare const renderConditionTag: ({ expression, kind, prefix }: ConditionTagOptions) => string;
+type ForOpenerOptions = {
+  alias: string;
+  path: string;
+  filters: readonly FilterCall[];
+  /** The placement the opener already carried, so rewriting its filters does
+   *  not move a row-form loop off its table row. */
+  prefix: MarkerPrefix;
+};
+/** One `{% for %}` opener, keeping its placement prefix. */
+declare const renderForOpener: ({ alias, filters, path, prefix }: ForOpenerOptions) => string;
+//#endregion
 //#region src/row-blocks.d.ts
 /** One end of a row block, addressed within the row that was scanned. */
 type RowBlockMarker = {
@@ -300,7 +567,7 @@ type RowBlockPair = {
  * paragraph, they are a matching opener/closer pair, the closer sits in a LATER
  * cell than the opener, the opener prefixes its cell and the closer suffixes
  * its cell. Everything else — one half of a pair, two nested pairs, a stray
- * `{{#else}}`, a pair wrapping the paragraphs of a single cell — is left to the
+ * `{% else %}`, a pair wrapping the paragraphs of a single cell — is left to the
  * engine's existing structure errors rather than guessed at.
  */
 declare const detectRowBlockPair: (cells: readonly (readonly string[])[]) => RowBlockPair | null;
@@ -308,11 +575,11 @@ declare const detectRowBlockPair: (cells: readonly (readonly string[])[]) => Row
 //#region src/index.d.ts
 type NamedCondition = {
   name: string;
-  /** The `{{#if}}` expression string. Authoritative unless `node` is set. */
+  /** The `{% if %}` expression string. Authoritative unless `node` is set. */
   expression: string;
   /**
    * The canonical AST, set when the condition cannot round-trip through the
-   * expression string — i.e. it uses a `formula` operand the `{{#if}}` grammar
+   * expression string — i.e. it uses a `formula` operand the `{% if %}` grammar
    * has no syntax for. When present it is evaluated directly and `expression`
    * is ignored.
    */
@@ -326,16 +593,17 @@ type NamedCondition = {
  */
 declare const MAX_CONDITION_DEPTH = 50;
 /**
- * Evaluate a template `{{#if ...}}` condition. The expression is parsed into
+ * Evaluate a template `{% if ... %}` condition. The expression is parsed into
  * the canonical `@stll/conditions` AST and evaluated by the shared evaluator.
  *
- * Supports comparisons (`==`, `!=`, `>`, `<`, `>=`, `<=`), `contains`,
- * truthiness, negation (`!`), logical operators (`and`, `or`), parentheses,
- * dotted paths, numeric underscores, and named-condition references.
+ * Supports comparisons (`==`, `!=`, `>`, `<`, `>=`, `<=`), membership
+ * (`"x" in path`), presence (`is defined` / `is not defined`), truthiness,
+ * negation (`not`), logical operators (`and`, `or`), parentheses, dotted
+ * paths, numeric underscores, and named-condition references.
  *
  * An empty or unparseable expression is `false` ("no condition" never gates a
  * branch true).
  */
 declare const evaluateCondition: (expression: string, data: Record<string, unknown>, namedConditions?: readonly NamedCondition[], _resolved?: ReadonlySet<string>, _depth?: number) => boolean;
 //#endregion
-export { BLOCK_DIRECTIVE_KINDS, type BlockDirectiveKind, type CompareNode, type CompareOp, type Condition, type ConditionNode, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, type DateFormatStyle, type DeterministicFieldConfig, type DirectiveKind, type FieldDateFormat, type GroupNode, type InvalidMarker, MARKER_DEFECT_KINDS, MAX_CONDITION_DEPTH, type MarkerDefectKind, type MarkerMeta, NUMERIC_FUNCTION_NAMES, NamedCondition, type NumericFunctionName, type Operand, type PartConfig, type PredicateNode, type PredicateOp, type RowBlockMarker, type RowBlockPair, type ScannedMarker, assertNever, blockDirectiveLinePattern, classifyMarker, classifyMarkerDefect, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, countPattern, detectRowBlockPair, emptyCondition, evaluateCondition, evaluateNumericExpression, formatDate, hasBlockDirectivePattern, hasNumberingPattern, indexPattern, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, markerPattern, numPattern, parseCondition, placeholderPattern, refPattern, renderComposite, renderDeterministicFieldValue, resolvePath, scanInvalidMarkers, scanMarkers, serializeCondition };
+export { ARRAY_FILTER_NAMES, BLOCK_DIRECTIVE_KINDS, type BlockDirectiveKind, type CompareNode, type CompareOp, type Condition, type ConditionNode, type ConditionTagOptions, DATE_FORMAT_EXAMPLE_ISO, DATE_FORMAT_STYLES, DIRECTIVE_KINDS, type DateFormatStyle, type DeterministicFieldConfig, type DirectiveKind, FILTER_NAMES, type FieldDateFormat, type FilterArgument, type FilterCall, type FilterName, type ForOpenerOptions, type GroupNode, type InvalidMarker, LOOP_PROPERTIES, type LoopProperty, MARKER_DEFECT_KINDS, MARKER_OUTPUT_BODY, MARKER_STATEMENT_BODY, MAX_CONDITION_DEPTH, type MarkerDefect, type MarkerDefectKind, type MarkerFieldConfig, type MarkerFieldInputType, type MarkerFieldLookup, type MarkerFieldSource, type MarkerFieldValidation, type MarkerForm, type MarkerLiteral, type MarkerMeta, type MarkerPrefix, NUMERIC_FUNCTION_NAMES, NamedCondition, type NumericFunctionName, type Operand, type PredicateNode, type PredicateOp, type RowBlockMarker, type RowBlockPair, type RowScope, type ScannedMarker, type UnwritableReason, arrayFiltersFromFieldConfig, assertNever, blockDirectiveLinePattern, classifyMarker, classifyMarkerDefect, clauseSlotKey, clauseSlotPattern, conditionHasFormula, conditionNodeSchema, conditionSchema, detectRowBlockPair, emptyCondition, evaluateCondition, evaluateNumericExpression, filtersFromFieldConfig, formatDate, hasBlockDirectivePattern, hasNumberingPattern, isArrayFilterName, isBlockDirectiveKind, isClauseSlotName, isFieldPath, isSafeFieldPath, legacyLoopAlias, legacyMarkerReplacement, loopPattern, markerPattern, normalizeMarkerInner, numPattern, parseCondition, placeholderPattern, qualifyLoopPath, qualifyRowScopedPath, qualifyRowScopedPlaceholder, refPattern, referencedConditionPaths, renderConditionTag, renderDeterministicFieldValue, renderFilterChain, renderForOpener, renderValueMarker, replaceOutputMarkers, resolvePath, rowScopePaths, scanInvalidMarkers, scanMarkers, serializeCondition, substitutionKey, translateLegacyExpression, unwritableFilterValues, unwritableMarkerLiteral };