@stll/folio-core 0.41.0 → 0.43.0

package/dist/prosemirror/conversion/toProseDoc.js

@@ -1,4 +1,5 @@
 import { resolveColorValueToHex } from "../../docx/drawingUtils.js";
+import { isNumberingReference } from "../../docx/numberingReference.js";
 import { PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, createProseParagraphWithPropertySource, getDocumentParagraphPropertySourceContract, recreateProseNodeWithParagraphPropertySource, transportTableCellsWithParagraphPropertySources } from "../../docx/paragraphPropertySource.js";
 import { buildPageBreakRunSourceDescendantIndex } from "../../internal/pageBreakRunSourceDescendantIndex.js";
 import { createStyleEngine } from "../../style-engine/styleEngine.js";
@@ -453,7 +454,7 @@ function paragraphFormattingToAttrs(paragraph, styleResolver, tableParagraphOver
 		if (formatting?.spaceBefore === void 0 && tableParagraphOverlay?.spaceBefore === void 0 && paragraphStyle?.pPr?.spaceBefore === void 0 && docDefaultSpacing?.spaceBefore !== void 0) spacingFromDocDefaults.before = true;
 		if (formatting?.spaceAfter === void 0 && tableParagraphOverlay?.spaceAfter === void 0 && paragraphStyle?.pPr?.spaceAfter === void 0 && docDefaultSpacing?.spaceAfter !== void 0) spacingFromDocDefaults.after = true;
 		if (spacingFromDocDefaults.before || spacingFromDocDefaults.after) attrs.spacingFromDocDefaults = spacingFromDocDefaults;
-		const effectiveIndent = mergeParagraphFormatting(formatting?.numPr?.numId === 0 && stylePpr?.numPr !== void 0 && stylePpr.numPr.numId !== 0 ? void 0 : stylePpr, formatting);
+		const effectiveIndent = mergeParagraphFormatting(formatting?.numPr?.numId === 0 && isNumberingReference(stylePpr?.numPr?.numId) ? void 0 : stylePpr, formatting);
 		set("indentLeft", effectiveIndent?.indentLeft);
 		set("indentRight", formatting?.indentRight ?? stylePpr?.indentRight);
 		set("indentFirstLine", effectiveIndent?.indentFirstLine);
@@ -473,7 +474,7 @@ function paragraphFormattingToAttrs(paragraph, styleResolver, tableParagraphOver
 		set("outlineLevel", formatting?.outlineLevel ?? stylePpr?.outlineLevel);
 		set("direction", directionFromBidi(formatting?.bidi ?? stylePpr?.bidi));
 		set("defaultTextFormatting", resolveParagraphDefaultTextFormatting(styleId, formatting, styleResolver, { includeParagraphMarkRunProperties: tableOfContentsLevel === void 0 && (styleId === void 0 || paragraph.content.length === 0) }));
-		if (stylePpr?.numPr && formatting?.numPr?.numId === void 0 && stylePpr.numPr.numId !== 0) {
+		if (stylePpr?.numPr && formatting?.numPr?.numId === void 0 && isNumberingReference(stylePpr.numPr.numId)) {
 			attrs.numPr = {
 				...stylePpr.numPr,
 				...formatting?.numPr
@@ -1216,19 +1217,27 @@ const PAGE_BREAK_PARAGRAPH_OWNERS = {
 };
 function assertSourceContainerHasNoPageBreakRun(content, owner, sourceDescendants) {
 	if (!sourceDescendants.containsPageBreakRun(content)) return;
-	if (owner === "table-cell" && hasSingleLeadingTableCellPageBreak(content)) return;
+	if (owner === "table-cell" && hasSingleLeadingTableCellPageBreak(content, sourceDescendants)) return;
 	throw new UnsupportedDocxToProseMirrorConversionError({
 		message: `${PAGE_BREAK_CONTAINER_DESCRIPTIONS[owner]} cannot be represented in the editor model`,
 		owner,
 		contentType: "break"
 	});
 }
-/** A leading page-break run in a cell advances the whole row during pagination. This
-* narrow shape has a lossless PM representation and a row-wide layout
-* projection; interior breaks still require table-fragment ownership. */
-function hasSingleLeadingTableCellPageBreak(content) {
-	const paragraph = content.length === 1 && content[0]?.type === "paragraph" ? content[0] : void 0;
-	return paragraph !== void 0 && hasSingleLeadingParagraphPageBreak(paragraph);
+/**
+* A page break opening a cell advances the whole row during pagination.
+*
+* Word writes this shape routinely and the row's own `breakBefore` projects it
+* losslessly, so what follows the break inside the cell rides along: the row
+* moves as a unit. The break has to be the cell's only one and has to open its
+* first paragraph; an interior break still requires table-fragment ownership,
+* which cell-local flow cannot model. `convertTableCell` in the layout bridge
+* decides the same question over the projected runs.
+*/
+function hasSingleLeadingTableCellPageBreak(content, sourceDescendants) {
+	const first = content.at(0);
+	if (first?.type !== "paragraph" || !hasSingleLeadingParagraphPageBreak(first)) return false;
+	return !content.slice(1).some((block) => sourceDescendants.blockContainsPageBreakRun(block));
 }
 const scanLeadingPageBreakRun = (run, scan) => {
 	for (const content of run.content) {
@@ -1237,6 +1246,7 @@ const scanLeadingPageBreakRun = (run, scan) => {
 			scan.pageBreaks += 1;
 			continue;
 		}
+		if (content.type === "shape" && content.shape.textBody && scan.pageBreaks > 0) scan.textBoxShapeAfterBreak = true;
 		if (scan.pageBreaks === 0) scan.contentBeforeBreak = true;
 	}
 };
@@ -1276,12 +1286,17 @@ const scanLeadingPageBreakContent = (content, scan) => {
 		default: return content;
 	}
 };
-const hasSingleLeadingParagraphPageBreak = (paragraph) => {
+const scanParagraphPageBreaks = (paragraph) => {
 	const scan = {
 		contentBeforeBreak: false,
-		pageBreaks: 0
+		pageBreaks: 0,
+		textBoxShapeAfterBreak: false
 	};
 	for (const content of paragraph.content) scanLeadingPageBreakContent(content, scan);
+	return scan;
+};
+const hasSingleLeadingParagraphPageBreak = (paragraph) => {
+	const scan = scanParagraphPageBreaks(paragraph);
 	return !scan.contentBeforeBreak && scan.pageBreaks === 1;
 };
 function assertParagraphPageBreakCanBeProjected({ paragraph, attrs, effectiveFrame, sourceDescendants }) {
@@ -1290,7 +1305,7 @@ function assertParagraphPageBreakCanBeProjected({ paragraph, attrs, effectiveFra
 	const disposition = pageBreakRunParagraphProjectionDispositionForFeatures({
 		attrs,
 		effectiveFrame,
-		hasTextBoxAnchor: sourceFeatures.hasTextBoxShape && !sourceFeatures.pageBreakSharesTextBoxShape
+		textBoxAnchorAfterPageBreak: sourceFeatures.hasTextBoxShape && !sourceFeatures.pageBreakSharesTextBoxShape && scanParagraphPageBreaks(paragraph).textBoxShapeAfterBreak
 	});
 	if (disposition.status === "supported") return;
 	if (disposition.reason !== "textBoxAnchor" && hasSingleLeadingParagraphPageBreak(paragraph)) return;

package/dist/prosemirror/extensions/features/ListExtension.js

@@ -1,3 +1,4 @@
+import { isNumberingReference } from "../../../docx/numberingReference.js";
 import { expectParagraphAttrs } from "../../attrs/index.js";
 import { PPR_CHANGE_SCOPED_ATTR_KEYS, hasSerializableParagraphPropertyChange } from "../../commands/propertyChangeScope.js";
 import { CLEARED_LIST_RENDERING_ATTRS } from "../../listMarker.js";
@@ -9,6 +10,7 @@ import { createExtension } from "../create.js";
 import { goToNextCell, goToPrevCell } from "../nodes/TableExtension.js";
 import { Priority } from "../types.js";
 import { panic } from "better-result";
+import { InputRule, inputRules, undoInputRule } from "prosemirror-inputrules";
 //#region src/prosemirror/extensions/features/ListExtension.ts
 /**
 * List Extension — list commands + keymaps
@@ -48,9 +50,9 @@ function getPreviousListFormatting(attrs) {
 }
 function clearListAttrs(attrs) {
 	const styleNumPr = attrs.numPrFromStyle;
-	const numPr = styleNumPr?.numId !== void 0 && styleNumPr.numId !== 0 ? {
+	const numPr = isNumberingReference(styleNumPr?.numId) ? {
 		numId: 0,
-		ilvl: attrs.numPr?.ilvl ?? styleNumPr.ilvl ?? 0
+		ilvl: attrs.numPr?.ilvl ?? styleNumPr?.ilvl ?? 0
 	} : null;
 	return {
 		...attrs,
@@ -59,7 +61,7 @@ function clearListAttrs(attrs) {
 	};
 }
 function hasActiveListNumbering(attrs) {
-	return attrs.numPr?.numId !== void 0 && attrs.numPr.numId !== 0;
+	return isNumberingReference(attrs.numPr?.numId);
 }
 function toggleList(numId) {
 	return (state, dispatch) => {
@@ -293,11 +295,47 @@ function insertTab() {
 		return true;
 	};
 }
+/**
+* Word's as-you-type markers. Each ends in the space that triggers the rule.
+* `1.` starts a numbered list at one, like the toolbar button; another typed
+* number stays text rather than being silently renumbered.
+*/
+const BULLET_AUTOFORMAT = /^[-*] $/u;
+const NUMBERED_AUTOFORMAT = /^1\. $/u;
+const captureTransaction = (command, state) => {
+	const captured = { transaction: null };
+	command(state, (transaction) => {
+		captured.transaction = transaction;
+	});
+	return captured.transaction;
+};
+/**
+* Replace a typed marker with the list the toolbar button produces. Running the
+* command itself (rather than writing `numPr` here) keeps an autoformatted list
+* identical to a clicked one, down to what the document saves.
+*/
+const listAutoformat = (marker, toggleCommand) => new InputRule(marker, (state, _match, start, end) => {
+	const { $from } = state.selection;
+	if ($from.parent.type.name !== "paragraph") return null;
+	if (start !== $from.start()) return null;
+	if (expectParagraphAttrs($from.parent).numPr?.numId) return null;
+	if (makeRevisionInfo(state)) return null;
+	const toggled = captureTransaction(toggleCommand, state);
+	if (!toggled) return null;
+	const tr = state.tr.delete(start, end);
+	for (const step of toggled.steps) {
+		const mapped = step.map(tr.mapping);
+		if (mapped) tr.step(mapped);
+	}
+	return tr;
+});
+const listAutoformatRules = () => inputRules({ rules: [listAutoformat(BULLET_AUTOFORMAT, toggleBulletList), listAutoformat(NUMBERED_AUTOFORMAT, toggleNumberedList)] });
 const ListExtension = createExtension({
 	name: "list",
 	priority: Priority.High,
 	onSchemaReady() {
 		return {
+			plugins: [listAutoformatRules()],
 			commands: {
 				toggleBulletList: () => toggleBulletList,
 				toggleNumberedList: () => toggleNumberedList,
@@ -310,7 +348,7 @@ const ListExtension = createExtension({
 				"Shift-Tab": chainCommands(goToPrevCell(), decreaseListIndent()),
 				"Shift-Enter": () => false,
 				Enter: chainCommands(exitListOnEmptyEnter(), splitListItem()),
-				Backspace: backspaceExitList()
+				Backspace: chainCommands(undoInputRule, backspaceExitList())
 			}
 		};
 	}

package/dist/prosemirror/listMarker.js

@@ -1,4 +1,5 @@
 import { convertBulletToUnicode } from "../docx/bulletMarkers.js";
+import { isNumberingReference } from "../docx/numberingReference.js";
 import { formatOoxmlCounter } from "../docx/ooxmlCounterFormatter.js";
 import { LIST_RENDERING_ATTR_KEYS } from "./listRenderingAttrs.js";
 //#region src/prosemirror/listMarker.ts
@@ -179,7 +180,7 @@ function advanceListMarker(attrs, state) {
 	const level = attrs.numPr?.ilvl ?? 0;
 	if (!Number.isInteger(level) || level < 0 || level > 8) return null;
 	const numId = attrs.numPr?.numId;
-	if (numId === void 0 || numId === 0) {
+	if (!isNumberingReference(numId)) {
 		let marker = null;
 		if (markerTemplate?.includes("%") && !attrs.listIsBullet) {
 			const counters = getLastListCounters(state);

package/dist/prosemirror/numberedRefFields.js

@@ -1,3 +1,4 @@
+import { isNumberingReference } from "../docx/numberingReference.js";
 import { expectFieldAttrs, expectParagraphAttrs } from "./attrs/index.js";
 import { expectBookmarkBoundaryAttrs } from "./bookmarkBoundaryAttrs.js";
 import { advanceVisibleListMarker, createListCounterState, resolveListTemplateWithComponents } from "./listMarker.js";
@@ -79,7 +80,7 @@ function numberTargetForParagraph(node, contextStreams, streams) {
 }
 function numberTargetForAdvancedMarker(attrs, resolvedMarker, state, contexts) {
 	const numId = attrs.numPr?.numId;
-	if (numId === void 0 || numId === 0 || attrs.listIsBullet || attrs.listMarkerHidden || attrs.listNumFmt === "none" || !resolvedMarker) return null;
+	if (!isNumberingReference(numId) || attrs.listIsBullet || attrs.listMarkerHidden || attrs.listNumFmt === "none" || !resolvedMarker) return null;
 	const marker = attrs.listMarkerAllCaps ? resolvedMarker.toLocaleUpperCase() : resolvedMarker;
 	const level = attrs.numPr?.ilvl ?? 0;
 	if (!Number.isInteger(level) || level < 0 || level > 8) return null;

package/dist/prosemirror/pageBreakRunProjection.d.ts

@@ -6,7 +6,7 @@ declare const PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES: {
   readonly borders: "A bordered paragraph containing an explicit page-break run cannot be projected";
   readonly frame: "A framed paragraph containing an explicit page-break run cannot be projected";
   readonly outline: "An outline paragraph containing an explicit page-break run cannot be projected";
-  readonly textBoxAnchor: "A paragraph containing both an explicit page-break run and a text-box anchor cannot be projected";
+  readonly textBoxAnchor: "A paragraph whose text-box anchor follows an explicit page-break run cannot be projected";
 };
 type PageBreakRunParagraphProjectionReason = keyof typeof PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES;
 type PageBreakRunParagraphProjectionDisposition = {
@@ -19,10 +19,18 @@ type PageBreakRunParagraphProjectionDisposition = {
 type PageBreakRunParagraphFeatures = {
   attrs: ParagraphAttrs;
   effectiveFrame: document_d_exports.ParagraphFormatting["frame"];
-  hasTextBoxAnchor: boolean;
+  /**
+   * A text-box anchor that the paragraph's first page break precedes.
+   *
+   * Layout splits such a paragraph into fragments at its breaks, and only the
+   * first fragment keeps the paragraph's block id, which is what an anchor
+   * resolves its host through. An anchor before the first break is therefore
+   * projected faithfully; one after it would lose its host.
+   */
+  textBoxAnchorAfterPageBreak: boolean;
 };
 /** Keep source-import and ProseMirror-layout ownership decisions on one predicate. */
-declare const pageBreakRunParagraphProjectionDispositionForFeatures: ({ attrs, effectiveFrame, hasTextBoxAnchor }: PageBreakRunParagraphFeatures) => PageBreakRunParagraphProjectionDisposition;
+declare const pageBreakRunParagraphProjectionDispositionForFeatures: ({ attrs, effectiveFrame, textBoxAnchorAfterPageBreak }: PageBreakRunParagraphFeatures) => PageBreakRunParagraphProjectionDisposition;
 declare const pageBreakRunParagraphProjectionDisposition: (paragraph: Node) => PageBreakRunParagraphProjectionDisposition;
 //#endregion
 export { PageBreakRunParagraphProjectionDisposition, PageBreakRunParagraphProjectionReason, pageBreakRunParagraphProjectionDisposition, pageBreakRunParagraphProjectionDispositionForFeatures };

package/dist/prosemirror/pageBreakRunProjection.js

@@ -4,10 +4,10 @@ const PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES = {
 	borders: "A bordered paragraph containing an explicit page-break run cannot be projected",
 	frame: "A framed paragraph containing an explicit page-break run cannot be projected",
 	outline: "An outline paragraph containing an explicit page-break run cannot be projected",
-	textBoxAnchor: "A paragraph containing both an explicit page-break run and a text-box anchor cannot be projected"
+	textBoxAnchor: "A paragraph whose text-box anchor follows an explicit page-break run cannot be projected"
 };
 /** Keep source-import and ProseMirror-layout ownership decisions on one predicate. */
-const pageBreakRunParagraphProjectionDispositionForFeatures = ({ attrs, effectiveFrame, hasTextBoxAnchor }) => {
+const pageBreakRunParagraphProjectionDispositionForFeatures = ({ attrs, effectiveFrame, textBoxAnchorAfterPageBreak }) => {
 	if (effectiveFrame !== void 0 && effectiveFrame.dropCap !== "drop" && effectiveFrame.dropCap !== "margin") return {
 		status: "unsupported",
 		reason: "frame",
@@ -23,7 +23,7 @@ const pageBreakRunParagraphProjectionDispositionForFeatures = ({ attrs, effectiv
 		reason: "borders",
 		message: PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES.borders
 	};
-	if (hasTextBoxAnchor) return {
+	if (textBoxAnchorAfterPageBreak) return {
 		status: "unsupported",
 		reason: "textBoxAnchor",
 		message: PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES.textBoxAnchor
@@ -32,15 +32,23 @@ const pageBreakRunParagraphProjectionDispositionForFeatures = ({ attrs, effectiv
 };
 const pageBreakRunParagraphProjectionDisposition = (paragraph) => {
 	const attrs = expectParagraphAttrs(paragraph);
-	let hasTextBoxAnchor = false;
-	paragraph.descendants((descendant) => {
-		hasTextBoxAnchor ||= descendant.type.name === "textBoxAnchor";
-		return !hasTextBoxAnchor;
+	let firstPageBreakPos;
+	let textBoxAnchorAfterPageBreak = false;
+	paragraph.descendants((descendant, pos) => {
+		if (descendant.type.name === "pageBreakRun") {
+			firstPageBreakPos ??= pos;
+			return false;
+		}
+		if (descendant.type.name === "textBoxAnchor" && firstPageBreakPos !== void 0) {
+			textBoxAnchorAfterPageBreak = true;
+			return false;
+		}
+		return !textBoxAnchorAfterPageBreak;
 	});
 	return pageBreakRunParagraphProjectionDispositionForFeatures({
 		attrs,
 		effectiveFrame: attrs._originalFormatting?.frame,
-		hasTextBoxAnchor
+		textBoxAnchorAfterPageBreak
 	});
 };
 //#endregion

package/dist/prosemirror/plugins/templatePreviewValues.d.ts

@@ -25,6 +25,19 @@ type TemplatePreviewValues = {
   values: Record<string, TemplatePreviewValue>;
   /** `highlighted` marks substitutions with the preview accent. */
   mode: "highlighted" | "plain";
+  /**
+   * `if` expression → whether its block applies. The key is the expression
+   * exactly as written between `{% if` and `%}`, trimmed; a tag that carries a
+   * filter chain (`{% if consented | checkbox | label("…") %}`) also answers to
+   * the bare path in front of the chain, so a host that keys by field path need
+   * not repeat the chain. An expression the map does not mention is left as
+   * authored. The host decides truthiness: folio evaluates nothing.
+   *
+   * `false` hides the block, opener through closer. `true` keeps the body and,
+   * in `plain` mode, drops the block's tag paragraphs so the reader sees what
+   * will be generated; `highlighted` mode keeps them.
+   */
+  conditions?: Record<string, boolean>;
 };
 /**
  * One `{{path}}` marker matched by an active preview value. Exposed on
@@ -41,9 +54,37 @@ type TemplatePreviewEntry = {
   /** The typed value displayed in place of the marker. */
   value: TemplatePreviewValue;
 };
+/**
+ * One span the preview hides: a `false` block from its opener through its
+ * closer, or a single directive tag of a `true` block in `plain` mode. Exposed
+ * on the plugin state beside {@link TemplatePreviewEntry} so a surface that
+ * never sees PM decorations can drop the same spans.
+ */
+type TemplatePreviewHiddenRange = {
+  /** Inclusive PM doc position of the span start. */
+  from: number;
+  /** Exclusive PM doc position of the span end. */
+  to: number;
+  /** The `if` expression of the block this span belongs to, as authored. */
+  expr: string;
+};
+/**
+ * Whether a hidden span swallows a block whole, i.e. covers every position of
+ * its content, leaving it nothing to render. `pmStart`/`pmEnd` are the block
+ * node's own positions, so its content is `[pmStart + 1, pmEnd - 1)`.
+ *
+ * The decoration path and the paged flow both drop a block on this predicate,
+ * so the two surfaces hide exactly the same blocks; a block only partly covered
+ * fails it and keeps its text, and the covered span alone is hidden.
+ */
+declare const templatePreviewHidesWholeBlock: (range: TemplatePreviewHiddenRange, block: {
+  pmStart: number;
+  pmEnd: number;
+}) => boolean;
 type TemplatePreviewState = {
   preview: TemplatePreviewValues | null;
   entries: TemplatePreviewEntry[];
+  hidden: TemplatePreviewHiddenRange[];
   decorationSet: DecorationSet;
 };
 declare const templatePreviewValuesKey: PluginKey<TemplatePreviewState>;
@@ -51,4 +92,4 @@ declare function createTemplatePreviewValuesPlugin(): Plugin<TemplatePreviewStat
 /** Push (or clear, with `null`) the live fill preview into the editor. */
 declare const setTemplatePreviewValues: (view: EditorView, preview: TemplatePreviewValues | null) => void;
 //#endregion
-export { TemplatePreviewEntry, TemplatePreviewSpan, TemplatePreviewValue, TemplatePreviewValues, createTemplatePreviewValuesPlugin, setTemplatePreviewValues, templatePreviewValueFingerprint, templatePreviewValueText, templatePreviewValuesKey };
+export { TemplatePreviewEntry, TemplatePreviewHiddenRange, TemplatePreviewSpan, TemplatePreviewValue, TemplatePreviewValues, createTemplatePreviewValuesPlugin, setTemplatePreviewValues, templatePreviewHidesWholeBlock, templatePreviewValueFingerprint, templatePreviewValueText, templatePreviewValuesKey };

package/dist/prosemirror/plugins/templatePreviewValues.js

@@ -1,6 +1,7 @@
 import { scanDirectives } from "./templateDirectives.js";
 import { Plugin, PluginKey } from "prosemirror-state";
 import { Decoration, DecorationSet } from "prosemirror-view";
+import { classifyMarker, isFieldPath } from "@stll/template-conditions";
 //#region src/prosemirror/plugins/templatePreviewValues.ts
 /** Concatenated plain text of a preview value. */
 const templatePreviewValueText = (value) => typeof value === "string" ? value : value.runs.map((run) => run.text).join("");
@@ -11,6 +12,20 @@ const templatePreviewValueFingerprint = (value) => {
 	if (typeof value === "string") return value;
 	return value.runs.map((run) => `${run.bold === true ? "b" : ""}${run.italic === true ? "i" : ""}:${run.text}`).join("\0");
 };
+/**
+* Whether a hidden span swallows a block whole, i.e. covers every position of
+* its content, leaving it nothing to render. `pmStart`/`pmEnd` are the block
+* node's own positions, so its content is `[pmStart + 1, pmEnd - 1)`.
+*
+* The decoration path and the paged flow both drop a block on this predicate,
+* so the two surfaces hide exactly the same blocks; a block only partly covered
+* fails it and keeps its text, and the covered span alone is hidden.
+*/
+const templatePreviewHidesWholeBlock = (range, block) => range.from <= block.pmStart + 1 && range.to >= block.pmEnd - 1;
+/** Hides the marker text a preview value stands in for. */
+const ORIGINAL_CLASS = "folio-template-preview-original";
+/** Hides a conditional block the host reported as not applying. */
+const HIDDEN_CLASS = "folio-template-preview-hidden";
 const KEY_HOLDER_SYMBOL = Symbol.for("stll.folio.templatePreviewValuesKey");
 const keyHolder = globalThis;
 const templatePreviewValuesKey = keyHolder[KEY_HOLDER_SYMBOL] ?? (keyHolder[KEY_HOLDER_SYMBOL] = new PluginKey("templatePreviewValues"));
@@ -29,6 +44,13 @@ function buildSpanNode(span) {
 	}
 	return node;
 }
+/**
+* The widget standing in for a marker. A value carrying newlines breaks its
+* lines inside the paragraph, not into new ones: here through the widget class's
+* `white-space: pre-wrap`, and on the paged canvas through the line break runs
+* `applyTemplatePreviewToBlocks` emits. The two must keep agreeing — an inline
+* `{{ path }}` placeholder cannot introduce paragraphs on either surface.
+*/
 function buildValueWidget(value, mode) {
 	return () => {
 		const span = document.createElement("span");
@@ -42,13 +64,142 @@ function buildValueWidget(value, mode) {
 		return span;
 	};
 }
-function collectPreviewEntries(doc, preview) {
-	if (!preview || Object.keys(preview.values).length === 0) return [];
+/** Loop alias the bare-path probe binds. Any identifier does; it is discarded. */
+const CHAIN_PROBE_ALIAS = "__folioCondition";
+/** A field path opens with a letter or underscore, so `9x` and `-x` are not one. */
+const FIELD_PATH_HEAD_RE = /^[\p{L}_]/u;
+/**
+* The bare field path a condition's filter chain hangs off, or undefined when
+* the expression is not a path plus a chain.
+*
+* A host may write the tag the way `{% for x in xs | chain %}` already carries
+* one — `{% if buyer_is_a_consumer | checkbox | ai("Is the buyer …") %}` — while
+* keying `conditions` by the bare path. Splitting on `|` would cut a quoted
+* argument such as `label("a | b")` in half, so the expression is classified as
+* that very `for` chain instead and the grammar's own argument-aware scan
+* reports the path. An expression that is not a path plus a chain of known
+* filters (`a and b`, `items|length > 0`, `ai("a|b")`) classifies as nothing,
+* which is what keeps a real expression on exact matching.
+*/
+const filterChainPath = (expr) => {
+	const meta = classifyMarker(`for ${CHAIN_PROBE_ALIAS} in ${expr}`, "statement");
+	if (meta?.kind !== "for" || !isFieldPath(meta.path) || !FIELD_PATH_HEAD_RE.test(meta.path)) return;
+	return meta.path;
+};
+/**
+* The verdict stored under one key. Only a key the host set itself, holding a
+* real boolean, counts: an inherited property (`constructor`, or a boolean the
+* host's prototype carries) and a value from an untyped host are read as
+* silence rather than as a verdict.
+*/
+const ownVerdict = (conditions, key) => {
+	if (!Object.hasOwn(conditions, key)) return;
+	const value = conditions[key];
+	return typeof value === "boolean" ? value : void 0;
+};
+/**
+* The host's verdict on one condition: keyed by the expression as written, else
+* by the bare path its filter chain hangs off. `undefined` means the host said
+* nothing about this block, which leaves it exactly as authored.
+*/
+const conditionVerdict = (conditions, expr) => {
+	const exact = ownVerdict(conditions, expr);
+	if (exact !== void 0) return exact;
+	const path = filterChainPath(expr);
+	return path === void 0 ? void 0 : ownVerdict(conditions, path);
+};
+/**
+* The spans the host's verdicts hide, in document order and without their
+* nested hidden blocks: hiding a block already hides everything inside it.
+*
+* A `false` block is hidden whole, opener through closer. A `true` block keeps
+* its body, and in `plain` mode loses its tag paragraphs — opener, any
+* `{% elif %}` / `{% else %}`, closer — so the reader sees the document as it
+* will be generated rather than its scaffolding. `highlighted` mode exists to
+* show that scaffolding, so it keeps the tags. A block no verdict mentions is
+* left exactly as authored.
+*
+* Openers and closers pair off a kind-aware stack — `{% endif %}` closes the
+* nearest open `{% if %}`, `{% endfor %}` the nearest `{% for %}` — so a
+* mid-edit template with an unpaired opener or a stray closer hides nothing
+* rather than guessing a span. Inline markers pair like block ones: the fill
+* engine resolves an inline conditional within its paragraph, so the preview
+* follows. An `{% elif %}` or `{% else %}` branch of a `false` block sits
+* inside its span and is hidden with it.
+*/
+function collectHiddenRanges(ranges, conditions, mode) {
+	if (conditions === void 0) return [];
+	const open = [];
+	const paired = [];
+	for (const range of [...ranges].sort((a, b) => a.from - b.from)) {
+		if (range.kind === "if" || range.kind === "for") {
+			open.push({
+				opener: range,
+				branches: []
+			});
+			continue;
+		}
+		if (range.kind === "elif" || range.kind === "else") {
+			const innermost = open.at(-1);
+			if (innermost?.opener.kind === "if") innermost.branches.push(range);
+			continue;
+		}
+		if (range.kind !== "endif" && range.kind !== "endfor") continue;
+		const wanted = range.kind === "endif" ? "if" : "for";
+		let block;
+		for (let index = open.length - 1; index >= 0; index -= 1) {
+			const candidate = open[index];
+			if (candidate?.opener.kind === wanted) {
+				block = candidate;
+				open.length = index;
+				break;
+			}
+		}
+		if (block === void 0 || block.opener.kind !== "if") continue;
+		const { opener, branches } = block;
+		const verdict = conditionVerdict(conditions, opener.expr);
+		if (verdict === void 0) continue;
+		if (!verdict) {
+			paired.push({
+				from: opener.from,
+				to: range.to,
+				expr: opener.expr
+			});
+			continue;
+		}
+		if (mode !== "plain") continue;
+		paired.push({
+			from: opener.from,
+			to: opener.to,
+			expr: opener.expr
+		});
+		for (const branch of branches) paired.push({
+			from: branch.from,
+			to: branch.to,
+			expr: opener.expr
+		});
+		paired.push({
+			from: range.from,
+			to: range.to,
+			expr: opener.expr
+		});
+	}
+	paired.sort((a, b) => a.from - b.from || b.to - a.to);
+	const outermost = [];
+	for (const range of paired) {
+		const previous = outermost.at(-1);
+		if (previous && range.to <= previous.to) continue;
+		outermost.push(range);
+	}
+	return outermost;
+}
+function collectPreviewEntries(ranges, values, hidden) {
 	const entries = [];
-	for (const range of scanDirectives(doc)) {
+	for (const range of ranges) {
 		if (range.kind !== "placeholder" && range.kind !== "clause") continue;
-		const value = preview.values[range.expr];
+		const value = values[range.expr];
 		if (value === void 0 || templatePreviewValueText(value) === "") continue;
+		if (hidden.some((block) => range.from >= block.from && range.from < block.to)) continue;
 		entries.push({
 			from: range.from,
 			to: range.to,
@@ -58,10 +209,59 @@ function collectPreviewEntries(doc, preview) {
 	}
 	return entries;
 }
-function buildDecorationSet(doc, entries, mode) {
-	if (entries.length === 0) return DecorationSet.empty;
+function projectPreview(doc, preview) {
+	if (!preview) return {
+		entries: [],
+		hidden: []
+	};
+	const hasValues = Object.keys(preview.values).length > 0;
+	const hasConditions = preview.conditions !== void 0 && Object.keys(preview.conditions).length > 0;
+	if (!hasValues && !hasConditions) return {
+		entries: [],
+		hidden: []
+	};
+	const ranges = scanDirectives(doc);
+	const hidden = collectHiddenRanges(ranges, preview.conditions, preview.mode);
+	return {
+		entries: hasValues ? collectPreviewEntries(ranges, preview.values, hidden) : [],
+		hidden
+	};
+}
+/**
+* Hide one span: a block the span covers whole is hidden as a node, leaving no
+* empty line behind; a block it covers in part is hidden over the covered text
+* only, so an inline `{% if %}` in a paragraph of running text takes its own
+* span and nothing else.
+*/
+function pushHiddenDecorations(doc, range, out) {
+	const { from, to } = range;
+	doc.nodesBetween(from, to, (node, pos) => {
+		if (!node.isBlock) return false;
+		const nodeEnd = pos + node.nodeSize;
+		if (templatePreviewHidesWholeBlock(range, {
+			pmStart: pos,
+			pmEnd: nodeEnd
+		})) {
+			out.push(Decoration.node(pos, nodeEnd, { class: HIDDEN_CLASS }));
+			return false;
+		}
+		const contentFrom = pos + 1;
+		const contentTo = nodeEnd - 1;
+		if (!node.isTextblock) return true;
+		const spanFrom = Math.max(from, contentFrom);
+		const spanTo = Math.min(to, contentTo);
+		if (spanTo > spanFrom) out.push(Decoration.inline(spanFrom, spanTo, { class: HIDDEN_CLASS }, {
+			inclusiveStart: false,
+			inclusiveEnd: false
+		}));
+		return false;
+	});
+}
+function buildDecorationSet(doc, { entries, hidden }, mode) {
+	if (entries.length === 0 && hidden.length === 0) return DecorationSet.empty;
 	const decorations = [];
-	for (const entry of entries) decorations.push(Decoration.inline(entry.from, entry.to, { class: "folio-template-preview-original" }, {
+	for (const range of hidden) pushHiddenDecorations(doc, range, decorations);
+	for (const entry of entries) decorations.push(Decoration.inline(entry.from, entry.to, { class: ORIGINAL_CLASS }, {
 		inclusiveStart: false,
 		inclusiveEnd: false
 	}), Decoration.widget(entry.from, buildValueWidget(entry.value, mode), {
@@ -80,25 +280,28 @@ function createTemplatePreviewValuesPlugin() {
 				return {
 					preview: null,
 					entries: [],
+					hidden: [],
 					decorationSet: DecorationSet.empty
 				};
 			},
 			apply(tr, prev, _oldState, newState) {
 				const meta = tr.getMeta(templatePreviewValuesKey);
 				if (meta !== void 0) {
-					const entries = collectPreviewEntries(newState.doc, meta.preview);
+					const projection = projectPreview(newState.doc, meta.preview);
 					return {
 						preview: meta.preview,
-						entries,
-						decorationSet: buildDecorationSet(newState.doc, entries, meta.preview?.mode ?? "plain")
+						entries: projection.entries,
+						hidden: projection.hidden,
+						decorationSet: buildDecorationSet(newState.doc, projection, meta.preview?.mode ?? "plain")
 					};
 				}
 				if (tr.docChanged && prev.preview) {
-					const entries = collectPreviewEntries(newState.doc, prev.preview);
+					const projection = projectPreview(newState.doc, prev.preview);
 					return {
 						preview: prev.preview,
-						entries,
-						decorationSet: buildDecorationSet(newState.doc, entries, prev.preview.mode)
+						entries: projection.entries,
+						hidden: projection.hidden,
+						decorationSet: buildDecorationSet(newState.doc, projection, prev.preview.mode)
 					};
 				}
 				return prev;
@@ -114,4 +317,4 @@ const setTemplatePreviewValues = (view, preview) => {
 	view.dispatch(view.state.tr.setMeta(templatePreviewValuesKey, { preview }));
 };
 //#endregion
-export { createTemplatePreviewValuesPlugin, setTemplatePreviewValues, templatePreviewValueFingerprint, templatePreviewValueText, templatePreviewValuesKey };
+export { createTemplatePreviewValuesPlugin, setTemplatePreviewValues, templatePreviewHidesWholeBlock, templatePreviewValueFingerprint, templatePreviewValueText, templatePreviewValuesKey };