superdoc 2.2.0 → 2.3.0

package/dist/layout-engine/painters/dom/src/paragraph/borders/border-layer.d.ts

@@ -0,0 +1,59 @@
+import { ParagraphAttrs, ParagraphBorders } from '../../../../../contracts/src/index.js';
+import { BetweenBorderInfo } from './group-analysis.js';
+/**
+ * Computes the indent-aware bounding box for paragraph border/shading layers.
+ * Borders hug the paragraph content, inset by left/right/firstLine/hanging indents.
+ */
+export declare const getParagraphBorderBox: (fragmentWidth: number, indent?: ParagraphAttrs["indent"]) => {
+    leftInset: number;
+    width: number;
+};
+/**
+ * Computes the outward expansion for the border/shading layers based on
+ * the `space` attribute (OOXML: distance between border and text, in points).
+ *
+ * Within between-border groups, suppressed sides don't expand (the gap
+ * extension handles visual continuity instead).
+ *
+ * @spec ECMA-376 §17.3.1.24 — space attribute on pBdr child elements
+ */
+export declare const computeBorderSpaceExpansion: (borders?: ParagraphBorders, betweenInfo?: BetweenBorderInfo) => {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+/**
+ * Builds overlay elements for paragraph shading and borders.
+ * Returns layers in the order they should be appended (shading below borders).
+ *
+ * When `betweenInfo` indicates this fragment is in a border group:
+ * - The border layer extends downward by `gapBelow` px into the paragraph-spacing
+ *   gap, making left/right borders visually continuous across the group.
+ * - `suppressTopBorder` hides the top border for non-first group members.
+ * - `showBetweenBorder` replaces the bottom border with the between definition.
+ *
+ * The `space` attribute on each border side expands the layer outward,
+ * creating padding between the border line and the paragraph text.
+ */
+export declare const createParagraphDecorationLayers: (doc: Document, fragmentWidth: number, attrs?: ParagraphAttrs, betweenInfo?: BetweenBorderInfo) => {
+    shadingLayer?: HTMLElement;
+    borderLayer?: HTMLElement;
+};
+/**
+ * Applies paragraph border styles to an HTML element.
+ *
+ * Handles between-border groups:
+ * - `suppressTopBorder`: skips top border for non-first group members
+ * - `showBetweenBorder`: replaces bottom with the between border definition
+ */
+export declare const applyParagraphBorderStyles: (element: HTMLElement, borders?: ParagraphAttrs["borders"], betweenInfo?: BetweenBorderInfo) => void;
+/**
+ * Stamps between-border info onto an element's dataset for debugging
+ * and incremental update cache invalidation.
+ */
+export declare const stampBetweenBorderDataset: (element: HTMLElement, betweenInfo?: BetweenBorderInfo) => void;
+/**
+ * Applies paragraph shading (background color) to an HTML element.
+ */
+export declare const applyParagraphShadingStyles: (element: HTMLElement, shading?: ParagraphAttrs["shading"]) => void;

package/dist/layout-engine/painters/dom/src/paragraph/borders/group-analysis.d.ts

@@ -0,0 +1,38 @@
+import { ResolvedPaintItem } from '../../../../../contracts/src/index.js';
+/**
+ * Per-fragment rendering info for between-border groups.
+ *
+ * - showBetweenBorder: replace bottom border with the between definition
+ * - suppressTopBorder: hide this fragment's top border (covered by previous fragment's extension)
+ * - gapBelow: px to extend the border layer downward into the paragraph-spacing gap
+ */
+export type BetweenBorderInfo = {
+    showBetweenBorder: boolean;
+    suppressTopBorder: boolean;
+    suppressBottomBorder: boolean;
+    gapBelow: number;
+};
+/**
+ * Pre-computes per-fragment between-border rendering info for a page.
+ *
+ * Two fragments (i, i+1) form a border group pair when:
+ * 1. Both are para fragments (not table/image/drawing)
+ * 2. Neither is a page-split continuation
+ * 3. They represent different logical paragraphs
+ * 4. Both have border definitions
+ * 5. Their full border definitions match (same border group)
+ *
+ * Per ECMA-376 §17.3.1.5: grouping occurs when all border properties are
+ * identical. A `between` border is NOT required — when absent, the group
+ * is rendered as a single box without a separator line.
+ *
+ * For each pair, the first fragment gets:
+ * - showBetweenBorder: true — bottom border replaced with between definition
+ * - gapBelow: px distance to extend border layer into spacing gap
+ *
+ * The second fragment gets:
+ * - suppressTopBorder: true — the previous fragment's extension covers the boundary
+ *
+ * Middle fragments in a chain of 3+ get both flags.
+ */
+export declare const computeBetweenBorderFlags: (resolvedItems: readonly ResolvedPaintItem[]) => Map<number, BetweenBorderInfo>;

package/dist/layout-engine/painters/dom/src/paragraph/borders/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Paragraph Borders — rendering feature module
+ *
+ * Handles all aspects of paragraph border rendering:
+ * - Border group detection (between-border analysis)
+ * - Border/shading DOM layer creation
+ * - CSS border style application
+ *
+ * @ooxml w:pPr/w:pBdr — paragraph border properties
+ * @ooxml w:pPr/w:pBdr/w:top, w:bottom, w:left, w:right — side borders
+ * @ooxml w:pPr/w:pBdr/w:between — between border for grouped paragraphs
+ * @ooxml w:pPr/w:pBdr/w:bar — bar border (vertical line)
+ * @ooxml w:pPr/w:shd — paragraph shading
+ * @spec  ECMA-376 §17.3.1.24 (pBdr), §17.3.1.31 (shd)
+ */
+export { computeBetweenBorderFlags } from './group-analysis.js';
+export type { BetweenBorderInfo } from './group-analysis.js';
+export { createParagraphDecorationLayers, applyParagraphBorderStyles, applyParagraphShadingStyles, getParagraphBorderBox, stampBetweenBorderDataset, computeBorderSpaceExpansion, } from './border-layer.js';

package/dist/layout-engine/painters/dom/src/paragraph/frame.d.ts

@@ -0,0 +1,3 @@
+import { ParaFragment, ResolvedFragmentItem } from '../../../../contracts/src/index.js';
+export type FragmentFrameSection = 'body' | 'header' | 'footer';
+export declare const applyParagraphFragmentPmAttributes: (el: HTMLElement, fragment: ParaFragment, section?: FragmentFrameSection, resolvedItem?: ResolvedFragmentItem) => void;

package/dist/layout-engine/painters/dom/src/paragraph/indentation.d.ts

@@ -0,0 +1,25 @@
+import { Line, ParagraphIndent } from '../../../../contracts/src/index.js';
+export type ParagraphLineIndentationParams = {
+    lineEl: HTMLElement;
+    line: Line;
+    indent?: ParagraphIndent;
+    indentLeftPx: number;
+    hasListMarkerLayout: boolean;
+    lineIndex: number;
+    localStartLine: number;
+    continuesFromPrev?: boolean;
+    suppressFirstLineIndent: boolean;
+    resetContinuationTextIndent?: boolean;
+};
+export declare const hasExplicitSegmentPositioning: (line: Line) => boolean;
+export declare const applyParagraphLineIndentation: (params: ParagraphLineIndentationParams) => void;
+export declare const resolveAvailableWidthForLine: (params: {
+    containerWidth: number;
+    line: Line;
+    indentLeftPx: number;
+    indentRightPx: number;
+    firstLineOffset: number;
+    isFirstLine: boolean;
+    isListFirstLine: boolean;
+    resolvedListTextStartPx?: number;
+}) => number;

package/dist/layout-engine/painters/dom/src/paragraph/list-marker.d.ts

@@ -0,0 +1,51 @@
+import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
+import { ParagraphMeasure, ResolvedListMarkerItem, SourceAnchor } from '../../../../contracts/src/index.js';
+import { MinimalMarker, MinimalWordLayout, ResolvedListMarkerGeometry } from '../../../../../../shared/common/list-marker-utils';
+import { MarkerTrackedChangeView } from './marker-tracked-change.js';
+import { TrackedChangesRenderConfig } from '../runs/types.js';
+type PainterListTextStartParams = {
+    wordLayout: MinimalWordLayout | undefined;
+    indentLeftPx: number;
+    hangingIndentPx: number;
+    firstLineIndentPx: number;
+    markerTextWidthPx?: number;
+};
+export declare const resolvePainterListMarkerGeometry: ({ wordLayout, indentLeftPx, hangingIndentPx, firstLineIndentPx, markerTextWidthPx, }: PainterListTextStartParams) => ResolvedListMarkerGeometry | undefined;
+export declare const resolvePainterListTextStartPx: ({ wordLayout, indentLeftPx, hangingIndentPx, firstLineIndentPx, markerTextWidthPx, }: PainterListTextStartParams) => number | undefined;
+type MarkerRunStyle = {
+    fontFamily?: string | null;
+    fontSize?: number | null;
+    bold?: boolean | null;
+    italic?: boolean | null;
+    color?: string | null;
+    letterSpacing?: number | null;
+    vanish?: boolean | null;
+    allCaps?: boolean | null;
+    smallCaps?: boolean | null;
+};
+export declare const createListMarkerElement: (doc: Document, markerText: string, run: MarkerRunStyle, sourceAnchor?: SourceAnchor, resolvePhysical?: ResolvePhysicalFamily, trackedChange?: MarkerTrackedChangeView, trackedChangesConfig?: TrackedChangesRenderConfig) => HTMLElement;
+export declare const renderLegacyListMarker: (params: {
+    doc: Document;
+    lineEl: HTMLElement;
+    wordLayout?: MinimalWordLayout;
+    markerLayout: MinimalMarker;
+    markerMeasure: ParagraphMeasure["marker"];
+    markerTextWidthPx?: number;
+    indentLeftPx: number;
+    hangingIndentPx: number;
+    firstLineIndentPx: number;
+    isRtl?: boolean;
+    sourceAnchor?: SourceAnchor;
+    resolvePhysical?: ResolvePhysicalFamily;
+    trackedChangesConfig?: TrackedChangesRenderConfig;
+}) => void;
+export declare const renderResolvedListMarker: (params: {
+    doc: Document;
+    lineEl: HTMLElement;
+    marker: ResolvedListMarkerItem;
+    isRtl?: boolean;
+    sourceAnchor?: SourceAnchor;
+    resolvePhysical?: ResolvePhysicalFamily;
+    trackedChangesConfig?: TrackedChangesRenderConfig;
+}) => void;
+export {};

package/dist/layout-engine/painters/dom/src/paragraph/marker-tracked-change.d.ts

@@ -0,0 +1,34 @@
+import { TrackedChangesRenderConfig } from '../runs/types.js';
+/**
+ * Permissive view over both marker tracked-change shapes — the contracts
+ * `MarkerTrackedChange` (resolved path) and the `@superdoc/common`
+ * `MinimalMarkerTrackedChange` (legacy `wordLayout.marker` path). Both are
+ * structurally assignable to this view, so neither paint path needs a cast.
+ */
+export interface MarkerTrackedChangeView {
+    id: string;
+    kind: 'insert' | 'delete' | 'format';
+    groupedIds?: readonly string[];
+    type?: string;
+    subtype?: string;
+    targetKind?: string;
+    semanticColorKey?: string;
+    semanticColor?: string;
+    color?: string;
+    author?: string;
+    authorEmail?: string;
+    date?: string;
+    storyKey?: string;
+}
+/** Marker-specific marker class so CSS can target marker review chrome only. */
+export declare const TRACK_CHANGE_MARKER_CLASS = "track-list-marker-dec";
+/**
+ * Stamp a marker glyph span with tracked-change review metadata + Word-like
+ * styling. Shares the run vocabulary (`track-insert-dec` / `track-delete-dec` /
+ * `track-format-dec`, the `--sd-tracked-changes-*` variable family, and the
+ * semantic datasets) so marker and run review decorations stay consistent.
+ *
+ * @param markerEl - The `.superdoc-paragraph-marker` glyph span.
+ * @param tc - The marker tracked-change metadata (resolved or legacy shape).
+ */
+export declare const applyMarkerTrackedChange: (markerEl: HTMLElement, tc: MarkerTrackedChangeView | undefined, config?: TrackedChangesRenderConfig) => void;

package/dist/layout-engine/painters/dom/src/paragraph/renderParagraphContent.d.ts

@@ -0,0 +1,87 @@
+import { DropCapDescriptor, Line, ParagraphBlock, ParagraphMeasure, ResolvedParagraphContent, Run, SdtMetadata, SourceAnchor } from '../../../../contracts/src/index.js';
+import { MinimalWordLayout } from '../../../../../../shared/common/list-marker-utils';
+import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
+import { SdtAncestorOptions, SdtBoundaryOptions } from '../sdt/container.js';
+import { BetweenBorderInfo } from './borders/index.js';
+export type RenderedParagraphLineInfo = {
+    el: HTMLElement;
+    top: number;
+    height: number;
+};
+export type ParagraphRenderLineInput = {
+    block: ParagraphBlock;
+    line: Line;
+    lineIndex: number;
+    isLastLine: boolean;
+    availableWidth?: number;
+    skipJustify?: boolean;
+    preExpandedRuns?: Run[];
+    resolvedListTextStartPx?: number;
+    indentOffsetOverride?: number;
+    paragraphMarkLeftOffsetOverride?: number;
+};
+export type ParagraphRenderLine = (input: ParagraphRenderLineInput) => HTMLElement;
+export type ParagraphRenderDropCap = (descriptor: DropCapDescriptor, measure?: {
+    width: number;
+    height: number;
+    lines: number;
+    mode: 'drop' | 'margin';
+}) => HTMLElement;
+export type ParagraphContainerKind = 'body-fragment' | 'table-cell';
+type ParagraphSpacingPolicy = {
+    isFirstBlock: boolean;
+    isLastBlock: boolean;
+    paddingTop: number;
+};
+export type RenderParagraphContentParams = {
+    doc: Document;
+    frameEl: HTMLElement;
+    block: ParagraphBlock;
+    measure: ParagraphMeasure;
+    containerKind: ParagraphContainerKind;
+    width: number;
+    localStartLine: number;
+    localEndLine: number;
+    linesOverride?: Line[];
+    lineIndexOffset?: number;
+    continuesFromPrev?: boolean;
+    continuesOnNext?: boolean;
+    markerWidth?: number;
+    markerTextWidth?: number;
+    wordLayout?: MinimalWordLayout;
+    resolvedContent?: ResolvedParagraphContent;
+    betweenInfo?: BetweenBorderInfo;
+    sdtBoundary?: SdtBoundaryOptions;
+    spacingPolicy?: ParagraphSpacingPolicy;
+    ancestorContainerKey?: string | null;
+    ancestorContainerSdt?: SdtMetadata | null;
+    ancestorContainerKeys?: SdtAncestorOptions['ancestorContainerKeys'];
+    ancestorContainerSdts?: SdtAncestorOptions['ancestorContainerSdts'];
+    onSdtContainerChrome?: () => void;
+    applySdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    applyContainerSdtDataset?: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    renderLine: ParagraphRenderLine;
+    renderDropCap?: ParagraphRenderDropCap;
+    /**
+     * Per-document logical->physical font resolver for list markers. Threaded from the renderer's
+     * per-document resolver so a marker paints the same physical family it was measured in. Undefined
+     * (or omitted) falls back to the global resolver, matching text runs and field annotations.
+     */
+    resolvePhysical?: ResolvePhysicalFamily;
+    captureLineSnapshot?: (lineEl: HTMLElement, options?: {
+        inTableParagraph?: boolean;
+        wrapperEl?: HTMLElement;
+        sourceAnchor?: SourceAnchor;
+    }) => void;
+    convertFinalParagraphMark?: boolean;
+    lineTopOffset?: number;
+    sourceAnchor?: SourceAnchor;
+    contentControlsChrome?: 'default' | 'none';
+};
+export type RenderParagraphContentResult = {
+    renderedHeight: number;
+    totalHeight: number;
+    renderedLines: RenderedParagraphLineInfo[];
+};
+export declare const renderParagraphContent: (params: RenderParagraphContentParams) => RenderParagraphContentResult;
+export {};

package/dist/layout-engine/painters/dom/src/paragraph/renderParagraphFragment.d.ts

@@ -0,0 +1,33 @@
+import { ParaFragment, ResolvedFragmentItem, SdtMetadata } from '../../../../contracts/src/index.js';
+import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
+import { SdtBoundaryOptions } from '../sdt/container.js';
+import { BetweenBorderInfo } from './borders/index.js';
+import { ParagraphRenderLineInput } from './renderParagraphContent.js';
+type ApplyStyles = (el: HTMLElement, styles: Partial<CSSStyleDeclaration>) => void;
+type RenderParagraphFragmentParams = {
+    doc: Document | null;
+    fragment: ParaFragment;
+    sdtBoundary?: SdtBoundaryOptions;
+    betweenInfo?: BetweenBorderInfo;
+    resolvedItem?: ResolvedFragmentItem;
+    applyStyles: ApplyStyles;
+    applyResolvedFragmentFrame: (el: HTMLElement, item: ResolvedFragmentItem, fragment: ParaFragment) => void;
+    applyFragmentFrame: (el: HTMLElement, fragment: ParaFragment) => void;
+    applySdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    applyContainerSdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
+    renderLine: (input: ParagraphRenderLineInput) => HTMLElement;
+    captureLineSnapshot: (lineEl: HTMLElement, options?: {
+        sourceAnchor?: ResolvedFragmentItem['sourceAnchor'];
+        wrapperEl?: HTMLElement;
+    }) => void;
+    createErrorPlaceholder: (blockId: string, error: unknown) => HTMLElement;
+    contentControlsChrome?: 'default' | 'none';
+    /**
+     * Per-document logical->physical font resolver for the drop cap and list markers. Threaded from
+     * the renderer's per-document resolver so they paint the same physical family they were measured
+     * in. Undefined falls back to the global resolver, matching text runs and field annotations.
+     */
+    resolvePhysical?: ResolvePhysicalFamily;
+};
+export declare const renderParagraphFragment: (params: RenderParagraphFragmentParams) => HTMLElement;
+export {};

package/dist/layout-engine/painters/dom/src/paragraph/styles.d.ts

@@ -0,0 +1,3 @@
+import { ParagraphAttrs } from '../../../../contracts/src/index.js';
+export declare const applyParagraphBlockStyles: (element: HTMLElement, attrs?: ParagraphAttrs) => void;
+export declare const clearParagraphFrameIndentStyles: (element: HTMLElement) => void;

package/dist/layout-engine/painters/dom/src/paragraph-hash-utils.d.ts

@@ -0,0 +1,13 @@
+import { ParagraphBorders, ParagraphBorder, TableBorders, TableBorderValue, CellBorders, BorderSpec } from '../../../contracts/src/index.js';
+/**
+ * Hash helpers are duplicated from layout-bridge to avoid a circular dependency
+ * (layout-bridge imports DOM_CLASS_NAMES from painter-dom). Keep these helpers
+ * in sync with layout-bridge when formatting changes need cache invalidation.
+ */
+export declare const hashParagraphBorder: (border: ParagraphBorder) => string;
+export declare const hashParagraphBorders: (borders: ParagraphBorders) => string;
+export declare const hashBorderSpec: (border: BorderSpec) => string;
+export declare const hashTableBorderValue: (borderValue: TableBorderValue | undefined) => string;
+export declare const hashTableBorders: (borders: TableBorders | undefined) => string;
+export declare const hashCellBorders: (borders: CellBorders | undefined) => string;
+export { getRunBooleanProp, getRunNumberProp, getRunStringProp, getRunUnderlineColor, getRunUnderlineStyle, hasBooleanProp, hasNumberProp, hasStringProp, } from './runs/hash.js';

package/dist/layout-engine/painters/dom/src/pm-position-validation.d.ts

@@ -0,0 +1,149 @@
+import { LayoutStoryKind, LayoutStoryLocator } from '../../../contracts/src/index.js';
+/**
+ * Which editor coordinate model the host is painting under. The host owns this
+ * choice; the painter never infers editor semantics from the presence of a
+ * number.
+ *
+ * - `legacy-pm`: v1 input — every text-bearing run requires a document-global
+ *   `pmStart`/`pmEnd` span.
+ * - `editor-neutral-story`: v2 — body runs still carry compatibility PM spans
+ *   during migration, but named stories (headers/footers/notes/textboxes) are
+ *   addressed by story identity, not a body PM offset.
+ */
+export type PaintCoordinateModel = 'legacy-pm' | 'editor-neutral-story';
+/** The coordinate obligation a single run must satisfy, once classified. */
+export type RunCoordinateRequirement = 'legacy-pm-required' | 'story-identity-required' | 'visual-only' | 'not-addressable';
+/** Console verbosity. `off` is production and the performance `--quiet` mode. */
+export type PositionValidationConsolePolicy = 'off' | 'summary' | 'verbose';
+/** Which painter produced the observation (kept isolated per painter instance). */
+export type PaintKind = 'surface-window' | 'dense-reference';
+/** Execution realm, for cross-realm report comparison. */
+export type PaintRealm = 'node-headless' | 'browser-inline' | 'browser-worker' | 'product';
+export type PositionValidationSection = 'body' | 'header' | 'footer';
+export type PositionRunKind = 'text' | 'image' | 'field' | 'math';
+/** Structural issue codes. None carry content. */
+export type PositionValidationCode = 'missing-start' | 'missing-end' | 'missing-both' | 'invalid-range' | 'identity-missing' | 'story-section-mismatch' | 'unexpected-story';
+/**
+ * The content-free structural tuple that keys aggregation and is echoed in
+ * `unexpectedKeys`. Every field is a small enum or boolean — never an id or
+ * text.
+ */
+export interface PositionValidationStructuralKey {
+    coordinateModel: PaintCoordinateModel;
+    requirement: RunCoordinateRequirement;
+    storyKind: LayoutStoryKind;
+    storyNamed: boolean;
+    section: PositionValidationSection;
+    runKind: PositionRunKind;
+    code?: PositionValidationCode;
+}
+export interface PositionValidationGroupRow extends PositionValidationStructuralKey {
+    checked: number;
+    valid: number;
+    issues: number;
+}
+export interface PositionValidationRequirementTally {
+    checked: number;
+    valid: number;
+    issues: number;
+}
+/**
+ * Bounded, content-free snapshot of one painter's validation coverage since the
+ * last consume. Safe to serialize into a performance report.
+ */
+export interface PositionValidationSummary {
+    enabled: boolean;
+    coordinateModel: PaintCoordinateModel;
+    paintKind: PaintKind;
+    realm: PaintRealm;
+    /** Total runs observed. */
+    checked: number;
+    /** Runs that met their requirement. */
+    valid: number;
+    /** Runs that failed their requirement (checked - valid). */
+    issues: number;
+    issuesByCode: Record<PositionValidationCode, number>;
+    byRequirement: Record<RunCoordinateRequirement, PositionValidationRequirementTally>;
+    /** Distinct verbose lines withheld after the verbose cap was reached. */
+    suppressedConsole: number;
+    /** Distinct structural groups seen (<= MAX_GROUPS retained). */
+    groupCount: number;
+    /** Run observations not retained after MAX_GROUPS distinct keys (still counted in totals). */
+    groupsOverflowed: number;
+    /** Aggregate rows, capped at MAX_GROUPS, most-issues first. */
+    groups: PositionValidationGroupRow[];
+    /** First unexpected (issue-bearing) structural keys, capped and content-free. */
+    unexpectedKeys: PositionValidationStructuralKey[];
+}
+/** A single run's content-free observation, handed to the collector. */
+export interface RunPositionObservation {
+    runKind: PositionRunKind;
+    section: PositionValidationSection;
+    story?: LayoutStoryLocator;
+    pmStart?: number | null;
+    pmEnd?: number | null;
+    /**
+     * True for render-only dynamic display text (PAGE / NUMPAGES / section-page
+     * fields) that mints no editable coordinate. Such runs are `visual-only`.
+     */
+    renderOnly?: boolean;
+}
+export interface PositionValidationOptions {
+    /** Dark by default; the perf harness enables it for its proof. */
+    enabled?: boolean;
+    /** Host-selected coordinate model. Defaults to the strict `legacy-pm`. */
+    coordinateModel?: PaintCoordinateModel;
+    /** Console policy. Defaults to `off` (counters only). */
+    policy?: PositionValidationConsolePolicy;
+    /** Which painter this is; keeps oracle and product coverage separable. */
+    paintKind?: PaintKind;
+    /** Execution realm for report comparison. */
+    realm?: PaintRealm;
+}
+/**
+ * Derive the story kind used for classification and reporting. The story
+ * locator, when present, is authoritative; otherwise we fall back to the paint
+ * section. Never defaults an absent-yet-non-body story to `body`.
+ */
+export declare const resolveStoryKind: (section: PositionValidationSection, story: LayoutStoryLocator | undefined) => LayoutStoryKind;
+/**
+ * Pure classification: which coordinate obligation does this run carry?
+ * Exported for unit testing.
+ */
+export declare const classifyRequirement: (coordinateModel: PaintCoordinateModel, storyKind: LayoutStoryKind, renderOnly: boolean) => RunCoordinateRequirement;
+/**
+ * Painter-scoped collector. One instance per `DomPainter`. Bounded memory:
+ * counters are O(1), the group map is capped at MAX_GROUPS, and no per-run
+ * event array is ever retained.
+ */
+export declare class PositionValidationCollector {
+    private readonly enabled;
+    private readonly coordinateModel;
+    private readonly policy;
+    private readonly paintKind;
+    private readonly realm;
+    private groups;
+    private groupsOverflowed;
+    private checked;
+    private valid;
+    private issues;
+    private issuesByCode;
+    private byRequirement;
+    private unexpectedKeys;
+    private unexpectedKeysSeen;
+    private verboseKeysSeen;
+    private verboseLines;
+    private suppressedConsole;
+    constructor(options?: PositionValidationOptions);
+    get isEnabled(): boolean;
+    record(obs: RunPositionObservation): void;
+    /** Verbose-mode: one content-free warning per NEW structural key, capped. */
+    private emitVerbose;
+    /** Drain and reset. The documented pass boundary. */
+    consume(): PositionValidationSummary;
+    /** Read without draining (for assertions / mid-run inspection). */
+    peek(): PositionValidationSummary;
+    private buildSummary;
+    private reset;
+}
+export declare const createPositionValidationCollector: (options?: PositionValidationOptions) => PositionValidationCollector;