superdoc 2.2.1 → 2.3.0

package/dist/layout-engine/contracts/src/segment-geometry.d.ts

@@ -0,0 +1,192 @@
+import { SourceAnchor } from './index.js';
+import { LayoutBlockRef, LayoutFragmentId, LayoutSourceIdentity, LayoutStoryLocator } from './layout-identity.js';
+/**
+ * Schema version for the neutral segment-geometry substrate.
+ *
+ * Bump when a load-bearing field changes semantics. Pure additive growth
+ * (new optional fields) does not require a bump.
+ */
+export declare const LAYOUT_SEGMENT_GEOMETRY_SCHEMA = "layout-segment-geometry/1";
+/** Resolved inline direction for a measured line. */
+export type NeutralTextDirection = 'ltr' | 'rtl';
+/**
+ * Geometry for a single measured run-segment within a line.
+ *
+ * `x` is **load-bearing**: it is the resolved container-space left edge of the
+ * segment, with paragraph indent, list text-start, alignment offset, and
+ * explicit tab positioning already applied. The producer's `LineSegment.x` is
+ * intentionally optional (it only carries an explicit override for tab-aligned
+ * runs); the readback resolves it to a concrete value here so the host never
+ * needs fallback positioning logic.
+ *
+ * `fromChar` / `toChar` are visible-text offsets **within the segment's run**
+ * (`runIndex`), matching the producer's `LineSegment` semantics. Joined with
+ * `runIndex` they address the exact visible text the segment paints.
+ */
+export type NeutralSegmentGeometry = {
+    /** Index of this segment within the line's segment list. */
+    segmentIndex: number;
+    /** Run index (into the source block's runs) this segment belongs to. */
+    runIndex: number;
+    /** Visible-text start offset within the run (inclusive). */
+    fromChar: number;
+    /** Visible-text end offset within the run (exclusive). */
+    toChar: number;
+    /** Resolved container-space x of the segment's start edge (px). Always present. */
+    x: number;
+    /** Measured width of the segment (px). */
+    width: number;
+};
+/**
+ * Per-line advisory flags. Present only when the corresponding condition holds,
+ * so consumers can treat an absent flag as "false" without ambiguity.
+ */
+export type NeutralLineGeometryFlags = {
+    /**
+     * Line participates in justified alignment. Segment `x`/`width` are the
+     * natural (pre-justify) measured values; the painter distributes slack across
+     * spaces at paint time, so downstream caret math past the first segment is
+     * approximate. Paired with a `approximate-justify` diagnostic on the fragment.
+     */
+    justified?: boolean;
+    /** Line uses explicit tab/segment positioning (at least one segment has an explicit x). */
+    tabAligned?: boolean;
+};
+/**
+ * Geometry for a single measured line within a fragment.
+ *
+ * Vertical metrics follow the painter's line-box model (see DomPainter
+ * `tab-run.ts`): the baseline sits at `top + halfLeading + ascent`, where
+ * `halfLeading = max(0, (lineHeight - ascent - descent) / 2)`. `baseline` is
+ * precomputed with that formula so the host does not reimplement it.
+ */
+export type NeutralLineGeometry = {
+    /** 0-based line index within the source block's measure. */
+    lineIndex: number;
+    /** Container-space top edge of the line box (px). */
+    top: number;
+    /** Container-space baseline y (px) — `top + halfLeading + ascent`. */
+    baseline: number;
+    /** Ascent above the baseline (px). */
+    ascent: number;
+    /** Descent below the baseline (px). */
+    descent: number;
+    /** Total line-box height (px). */
+    lineHeight: number;
+    /** Container-space x where line content starts after indent + alignment (px). */
+    contentLeft: number;
+    /** Measured natural content width of the line (px). */
+    contentWidth: number;
+    /** Resolved inline direction for the line. */
+    direction: NeutralTextDirection;
+    /** Advisory flags; omitted when none apply. */
+    flags?: NeutralLineGeometryFlags;
+    /** Per-segment geometry in visual (left-to-right paint) order. */
+    segments: NeutralSegmentGeometry[];
+};
+/**
+ * Diagnostics describing a case the substrate cannot fully represent.
+ *
+ * Emitted at the fragment level so a consumer can fail closed (skip caret/rect
+ * placement) instead of trusting partial geometry.
+ */
+export type NeutralGeometryDiagnostic = 
+/** Fragment kind has no per-line text geometry in this version (table, image, drawing). */
+{
+    code: 'unsupported-fragment-kind';
+    fragmentKind: string;
+}
+/**
+ * Inline direction is RTL but the line is not a proven simple-RTL case (e.g.
+ * tab-aligned, justified, or a rendered list marker whose RTL geometry is not
+ * mirrored yet). Per-segment x is not resolved for this fragment.
+ *
+ * Simple horizontal RTL paragraph fragments DO resolve and carry no diagnostic
+ * (V2 RTL Plan 004). Mixed-script bidi uses {@link 'unsupported-complex-bidi'}
+ * and vertical writing modes use {@link 'unsupported-vertical-direction'}.
+ */
+ | {
+    code: 'unsupported-direction';
+    direction: NeutralTextDirection;
+}
+/**
+ * The paragraph uses a vertical writing mode (`w:textDirection` tbRl/btLr,
+ * resolved to a vertical `WritingMode`). Horizontal text geometry cannot place
+ * carets here, so the fragment fails closed. (V2 RTL Plan 004 scope boundary.)
+ */
+ | {
+    code: 'unsupported-vertical-direction';
+    writingMode: string;
+}
+/**
+ * An RTL paragraph line mixes strong-LTR letters or Unicode numbers into the
+ * RTL flow, so the visual order is not a single-level reverse of the logical order.
+ * Resolving it needs per-segment visual-order data the substrate does not have
+ * yet, so the fragment fails closed rather than emit a mirrored-twice rect.
+ * (V2 RTL Plan 004 scope boundary; Plan 005+ may extend.)
+ */
+ | {
+    code: 'unsupported-complex-bidi';
+}
+/** Fragment has justified lines; segment x past the first is pre-justify (approximate). */
+ | {
+    code: 'approximate-justify';
+}
+/** The block measure was missing or mismatched; no geometry was produced. */
+ | {
+    code: 'missing-measure';
+}
+/** Fragment carried remeasured lines (narrow-column re-wrap); geometry used those lines. */
+ | {
+    code: 'remeasured-lines';
+};
+/**
+ * Geometry for one rendered fragment, joined back to neutral identity.
+ *
+ * Every record is addressable without ProseMirror: `identity` carries the
+ * story, source block ref, stable fragment id, and (when available) the DOCX
+ * source anchor. `bounds` is the fragment's container-space box; `lines` is the
+ * resolved per-line/per-segment geometry (empty for unsupported fragments,
+ * which carry a diagnostic instead).
+ */
+export type NeutralFragmentGeometry = {
+    schema: typeof LAYOUT_SEGMENT_GEOMETRY_SCHEMA;
+    /** Composite editor-neutral identity for the fragment. */
+    identity: LayoutSourceIdentity;
+    /** Story locator for the fragment. */
+    story: LayoutStoryLocator;
+    /** Source block reference. */
+    blockRef: LayoutBlockRef;
+    /** Stable opaque fragment id. */
+    fragmentId: LayoutFragmentId;
+    /** Optional cross-reference to the DOCX source anchor. */
+    sourceAnchor?: SourceAnchor;
+    /** 0-based page index containing the fragment. */
+    pageIndex: number;
+    /** Producer fragment kind (`para`, `list-item`, `table`, `image`, `drawing`). */
+    fragmentKind: string;
+    /** Container-space bounding box of the fragment (px). */
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Resolved per-line geometry, in paint order. */
+    lines: NeutralLineGeometry[];
+    /** Per-fragment diagnostics; omitted when fully represented. */
+    diagnostics?: NeutralGeometryDiagnostic[];
+};
+/**
+ * Result of a neutral segment-geometry readback over a layout.
+ *
+ * `layoutRevision` mirrors `layout.layoutEpoch` so a consumer can detect stale
+ * geometry. `fragments` is in page-then-fragment order.
+ */
+export type NeutralSegmentGeometryReadback = {
+    schema: typeof LAYOUT_SEGMENT_GEOMETRY_SCHEMA;
+    layoutRevision: number;
+    fragments: NeutralFragmentGeometry[];
+    /** Top-level diagnostics not attributable to a single fragment; omitted when none. */
+    diagnostics?: NeutralGeometryDiagnostic[];
+};

package/dist/layout-engine/contracts/src/semantic-colors.d.ts

@@ -0,0 +1,150 @@
+import { FlowBlock, TrackChangeAuthor, TrackedChangeMeta } from './index.js';
+/**
+ * Tracked-change visual categories. This is the full paint/metadata
+ * vocabulary: it names the DOM class, `data-track-change-semantic-color-key`
+ * dataset value, and review-metadata category of every rendered
+ * tracked-change side.
+ *
+ * COLOR ownership is split in two:
+ * - {@link TrackedChangeConfigurableSemanticColorKey} (a subset) resolves its
+ *   paint color through the JS `semanticColors` config (overrides/resolver)
+ *   with the defaults below.
+ * - The table-structure categories (`table-insertion`, `table-deletion`,
+ *   `table-row-insertion`, `table-row-deletion`, `table-split`) are CSS-only:
+ *   they carry NO JS-resolved color; DomPainter styles them via the
+ *   `--sd-tracked-changes-table-*` theme variables, which hosts override in
+ *   CSS.
+ *
+ * `move` is a group override key for both move sides; rendered move layers
+ * continue to carry the specific `move-from` / `move-to` keys.
+ * `table-split` covers whole-table split structure; `cell-split` covers split
+ * cells.
+ */
+export type TrackedChangeSemanticColorKey = 'insertion' | 'deletion' | 'move' | 'move-from' | 'move-to' | 'table-insertion' | 'table-deletion' | 'table-row-insertion' | 'table-row-deletion' | 'table-cell-insertion' | 'table-cell-deletion' | 'table-split' | 'cell-merge' | 'cell-split' | 'image-insertion' | 'image-deletion' | 'image-property-change';
+/**
+ * The categories whose paint color is resolvable through the JS
+ * `semanticColors` config. Table-structure categories are deliberately
+ * excluded: their colors are themed via CSS variables only.
+ */
+export type TrackedChangeConfigurableSemanticColorKey = 'insertion' | 'deletion' | 'move' | 'move-from' | 'move-to' | 'table-cell-insertion' | 'table-cell-deletion' | 'cell-merge' | 'cell-split' | 'image-insertion' | 'image-deletion' | 'image-property-change';
+/** All semantic color keys, in declaration order (useful for iteration/tests). */
+export declare const TRACKED_CHANGE_SEMANTIC_COLOR_KEYS: readonly TrackedChangeSemanticColorKey[];
+/** The JS-configurable subset, in declaration order. */
+export declare const TRACKED_CHANGE_CONFIGURABLE_SEMANTIC_COLOR_KEYS: readonly TrackedChangeConfigurableSemanticColorKey[];
+/** Whether a category resolves its color through the JS `semanticColors` config. */
+export declare const isConfigurableSemanticColorKey: (key: TrackedChangeSemanticColorKey | null | undefined) => key is TrackedChangeConfigurableSemanticColorKey;
+/**
+ * Default semantic colors per JS-configurable key. These are Word-like
+ * defaults for SD-3479: insertion blue, deletion red, and moved text green.
+ * All entries are hex constants so downstream focused-background derivation
+ * (`colorWithAlpha`) works without extra parsing. Table-structure categories
+ * have no entry here — their defaults live in the painter's CSS variables.
+ */
+export declare const DEFAULT_TRACKED_CHANGE_SEMANTIC_COLORS: Readonly<Record<TrackedChangeConfigurableSemanticColorKey, string>>;
+/** Input the host semantic resolver receives for a single tracked-change layer. */
+export interface TrackedChangeSemanticColorResolverInput {
+    /** Semantic category being colored (JS-configurable categories only). */
+    key: TrackedChangeConfigurableSemanticColorKey;
+    /** Author identity, when known (semantic colors are not author-derived). */
+    author?: TrackChangeAuthor;
+    /** Raw structural change type, when known. */
+    type?: string;
+    /** Logical structural subtype, when known. */
+    subtype?: string;
+    /** Structural target kind (e.g. cell/row/table), when known. */
+    targetKind?: string;
+    /** Scope of the semantic paint anchor, when known. */
+    semanticAnchorScope?: string;
+}
+/**
+ * A composed resolver mapping a semantic tracked-change input to a color.
+ * Returns `undefined` only when the resolver itself declines for a key. The
+ * composer returns `undefined` only when semantic colors are explicitly
+ * disabled.
+ */
+export type TrackChangeSemanticColorResolver = (input: TrackedChangeSemanticColorResolverInput) => string | undefined;
+/**
+ * Host-facing semantic tracked-change color configuration. Mirrors the
+ * (later) `modules.trackChanges.semanticColors` shape on the public `superdoc`
+ * package.
+ */
+export interface SemanticColorsConfig {
+    /** When `false`, semantic colors are not applied. Defaults to enabled. */
+    enabled?: boolean;
+    /**
+     * Color overrides keyed by semantic category. `move` applies to both move
+     * sides unless a side-specific override exists. Table-structure categories
+     * are not configurable here — theme them via the
+     * `--sd-tracked-changes-table-*` CSS variables instead.
+     */
+    overrides?: Partial<Record<TrackedChangeConfigurableSemanticColorKey, string>>;
+    /**
+     * Resolver consulted after `overrides`. Return a CSS color string, or
+     * `undefined`/nullish to fall through to the default semantic color.
+     */
+    resolve?: (input: TrackedChangeSemanticColorResolverInput) => string | undefined | null;
+}
+/**
+ * Deterministic signature for tracked-change metadata that can affect paint.
+ *
+ * Used by layout/painter cache keys. Keep this aligned with fields DomPainter
+ * reads when stamping classes, datasets, CSS variables, and mode-dependent
+ * tracked-change decorations.
+ */
+export declare const trackedChangeMetaSignature: (trackedChange: TrackedChangeMeta | null | undefined) => string;
+export declare const trackedChangeLayersSignature: (trackedChanges: readonly TrackedChangeMeta[] | null | undefined) => string;
+/** Default semantic color for a JS-configurable key, or `undefined` for an unknown/CSS-only key. */
+export declare const defaultSemanticColor: (key: TrackedChangeSemanticColorKey) => string | undefined;
+/** Structural target kind painted by a semantic color key. */
+export type TrackedChangeSemanticTargetKind = 'text' | 'table' | 'row' | 'cell' | 'image';
+/**
+ * Target kind painted by each semantic color key. Single source of truth for
+ * the projection (v2 host), the layout adapter, and sidebar metadata, so a key
+ * added in one layer cannot silently disagree about its target in another.
+ */
+export declare const TRACKED_CHANGE_SEMANTIC_TARGET_KINDS: Readonly<Record<TrackedChangeSemanticColorKey, TrackedChangeSemanticTargetKind>>;
+/** Target kind for a semantic key, or `undefined` for an unknown/absent key. */
+export declare const semanticColorTargetKind: (key: TrackedChangeSemanticColorKey | null | undefined) => TrackedChangeSemanticTargetKind | undefined;
+/**
+ * Keys whose paint anchors to an affected range rather than a single direct
+ * marker (cell merge/split and table split are range paints).
+ */
+export declare const TRACKED_CHANGE_AFFECTED_RANGE_KEYS: ReadonlySet<TrackedChangeSemanticColorKey>;
+/** Anchor scope for a semantic key: `'affected-range'` for range paints, else `null`. */
+export declare const semanticColorAnchorScope: (key: TrackedChangeSemanticColorKey | null | undefined) => "affected-range" | null;
+/**
+ * Semantic key implied by a structural insert/delete marker on a table, row,
+ * cell, or image target. Inverse of {@link TRACKED_CHANGE_SEMANTIC_TARGET_KINDS} for
+ * the structural insert/delete families; `undefined` for other kinds
+ * (formatting, moves) which never imply a structural semantic key.
+ */
+export declare const structuralSemanticColorKey: (kind: string | null | undefined, targetKind: "table" | "row" | "cell" | "image") => TrackedChangeSemanticColorKey | undefined;
+/**
+ * Composes the host `semanticColors` config into a single resolver.
+ *
+ * Resolution order per key:
+ * 1. `overrides[key]` (exact key match).
+ * 2. `overrides.move` for `move-from` / `move-to`.
+ * 3. `resolve(input)`.
+ * 4. The default semantic color for the key.
+ *
+ * Missing config still enables the built-in defaults, so supported semantic
+ * keys receive the requested colors without host configuration. Returns
+ * `undefined` only when semantic colors are disabled (`enabled === false`). A
+ * throwing host resolver must not break rendering: it falls through to the
+ * default color.
+ */
+export declare const composeSemanticColorResolver: (config?: SemanticColorsConfig | null) => TrackChangeSemanticColorResolver | undefined;
+/**
+ * Walks every tracked-change layer in the converted FlowBlocks and stamps
+ * `meta.semanticColor` from the resolver, based on each layer's
+ * `semanticColorKey`. Covers run layers, row-level tracked changes, and the
+ * cell-level `TableCellAttrs.trackedChange` carrier.
+ *
+ * Passing `undefined` (semantic colors disabled or no resolver available)
+ * clears any existing `semanticColor`, which prevents stale semantic colors
+ * from surviving on reused cached blocks. Missing host config should normally
+ * be passed through {@link composeSemanticColorResolver} so defaults apply.
+ * Author `color` fields are never read, mutated, or cleared by this pass.
+ */
+export declare const stampTrackedChangeSemanticColors: (blocks: FlowBlock[], resolve: TrackChangeSemanticColorResolver | undefined) => void;

package/dist/layout-engine/contracts/src/table-cell-spacing.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Effective paragraph spacing in table cells.
+ *
+ * Word absorbs the first paragraph's spacing.before into the cell's top padding,
+ * and the last paragraph's spacing.after into the cell's bottom padding.
+ * This helper returns the amount to add to height/position: at a boundary,
+ * only the excess of spacing over padding; otherwise the full spacing.
+ *
+ * Use for both spacing.before (isBoundary = first block, padding = paddingTop)
+ * and spacing.after (isBoundary = last block, padding = paddingBottom).
+ */
+export declare function effectiveTableCellSpacing(spacing: number | undefined, isBoundary: boolean, padding: number): number;

package/dist/layout-engine/contracts/src/table-column-rescale.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Proportionally rescales table column widths when the measured total width
+ * exceeds the available fragment width.
+ *
+ * Returns `undefined` when no rescaling is needed (total fits within fragment).
+ * Each column is guaranteed at least 1px; the last column absorbs rounding drift.
+ *
+ * @param measureColumnWidths - Measured widths per column (or undefined)
+ * @param measureTotalWidth - Sum of measured widths plus borders/spacing
+ * @param fragmentWidth - Available render width for the table
+ * @returns Rescaled widths array, or undefined if no scaling needed
+ */
+export declare function rescaleColumnWidths(measureColumnWidths: number[] | undefined, measureTotalWidth: number, fragmentWidth: number): number[] | undefined;

package/dist/layout-engine/contracts/src/vertical-text.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared vertical-text helpers for superscript, subscript, and explicit baseline shifts.
+ *
+ * OOXML allows both semantic vertical alignment (`vertAlign`) and an explicit
+ * position offset (`position`). During rendering, a zero offset is an identity
+ * value and should behave the same as an absent offset.
+ */
+export type VerticalTextAlign = 'superscript' | 'subscript' | 'baseline';
+type VerticalTextFormatting = {
+    vertAlign?: VerticalTextAlign | null;
+    baselineShift?: number | null;
+};
+/**
+ * Font size scaling factor for default superscript/subscript rendering.
+ * Matches Microsoft Word's default visual behavior closely enough for layout.
+ */
+export declare const SUBSCRIPT_SUPERSCRIPT_SCALE = 0.65;
+/**
+ * Normalizes explicit baseline shifts for rendering.
+ *
+ * A numeric shift of zero is a no-op and should not override semantic
+ * superscript/subscript styling. This preserves the raw OOXML value for
+ * round-tripping while giving the renderer a clean intent model.
+ */
+export declare function normalizeBaselineShift(baselineShift: number | null | undefined): number | undefined;
+export declare function hasExplicitBaselineShift(baselineShift: number | null | undefined): boolean;
+export declare function isSuperscriptOrSubscript(vertAlign: VerticalTextAlign | null | undefined): boolean;
+/**
+ * Returns true when the run should use the default superscript/subscript
+ * presentation path: scaled font size plus the renderer's default raise/lower.
+ */
+export declare function usesDefaultScriptLayout(formatting: VerticalTextFormatting): boolean;
+/**
+ * Applies default superscript/subscript font scaling when the run uses the
+ * default semantic layout path.
+ */
+export declare function scaleFontSizeForVerticalText(fontSize: number, formatting: VerticalTextFormatting): number;
+/**
+ * Returns the original base font size for runs that already carry scaled
+ * superscript/subscript text metrics.
+ */
+export declare function resolveBaseFontSizeForVerticalText(fontSize: number, formatting: VerticalTextFormatting): number;
+export {};

package/dist/layout-engine/dom-contract/src/class-names.d.ts

@@ -0,0 +1,62 @@
+/**
+ * DOM Contract: Class Names
+ *
+ * CSS class names stamped on rendered document elements by the DOM painter.
+ * These names form a public contract read by the painter (emitter) and by
+ * editor-side DOM observation code (reader).
+ *
+ * Changing a value here is a breaking change for both systems.
+ */
+export declare const DOM_CLASS_NAMES: {
+    /** Top-level page container element. */
+    readonly PAGE: "superdoc-page";
+    /** Fragment container (paragraph, table, image block, etc.). */
+    readonly FRAGMENT: "superdoc-fragment";
+    /** Line container within a fragment. */
+    readonly LINE: "superdoc-line";
+    /**
+     * Inline structured-content (SDT) wrapper.
+     *
+     * Carries `data-pm-start` / `data-pm-end` for selection highlighting.
+     * Should be EXCLUDED from click-to-position mapping — child spans are
+     * the character-level targets.
+     */
+    readonly INLINE_SDT_WRAPPER: "superdoc-structured-content-inline";
+    /** Inline structured-content label chrome. */
+    readonly INLINE_SDT_LABEL: "superdoc-structured-content-inline__label";
+    /** Block-level structured-content container. */
+    readonly BLOCK_SDT: "superdoc-structured-content-block";
+    /** Block-level structured-content label chrome. */
+    readonly BLOCK_SDT_LABEL: "superdoc-structured-content__label";
+    /** Table fragment container (resize overlay and click-mapping target). */
+    readonly TABLE_FRAGMENT: "superdoc-table-fragment";
+    /** Document section container. */
+    readonly DOCUMENT_SECTION: "superdoc-document-section";
+    /**
+     * Grouped hover highlight applied to all fragments of the same block SDT.
+     * Set by document-runtime hover coordination via event delegation.
+     */
+    readonly SDT_GROUP_HOVER: "sdt-group-hover";
+    /** Paragraph fragment rendered as a Table of Contents entry. */
+    readonly TOC_ENTRY: "superdoc-toc-entry";
+    /** TOC analogue of `SDT_GROUP_HOVER`, applied to every fragment sharing a `data-toc-id`. */
+    readonly TOC_GROUP_HOVER: "toc-group-hover";
+    /** Block-level image fragment (ImageBlock). */
+    readonly IMAGE_FRAGMENT: "superdoc-image-fragment";
+    /** Inline image element (ImageRun inside a paragraph). */
+    readonly INLINE_IMAGE: "superdoc-inline-image";
+    /** Wrapper around a paragraph's list marker (bullet glyph or ordered number). */
+    readonly LIST_MARKER: "superdoc-list-marker";
+    /** Clip wrapper around a cropped inline image. */
+    readonly INLINE_IMAGE_CLIP_WRAPPER: "superdoc-inline-image-clip-wrapper";
+    /** Field annotation outer wrapper. */
+    readonly ANNOTATION: "annotation";
+    /** Field annotation inner content wrapper. */
+    readonly ANNOTATION_CONTENT: "annotation-content";
+    /** Hidden caret anchor span appended after field annotation content. */
+    readonly ANNOTATION_CARET_ANCHOR: "annotation-caret-anchor";
+};
+/** Union of all DOM contract class name values. */
+export type DomClassName = (typeof DOM_CLASS_NAMES)[keyof typeof DOM_CLASS_NAMES];
+/** Structured-content chrome labels that should not drive text-position mapping. */
+export declare const STRUCTURED_CONTENT_CHROME_LABEL_CLASS_NAMES: readonly ["superdoc-structured-content-inline__label", "superdoc-structured-content__label"];

package/dist/layout-engine/dom-contract/src/data-attrs.d.ts

@@ -0,0 +1,103 @@
+/**
+ * DOM Contract: Data Attributes
+ *
+ * Named constants for `data-*` attributes stamped on rendered DOM elements.
+ * These attributes are read by editor-side DOM observers, click-to-position
+ * mapping, and bridge compatibility code.
+ *
+ * Each constant stores the full attribute name (e.g. `"data-pm-start"`) as it
+ * appears in `getAttribute()` / `setAttribute()` calls and CSS selectors.
+ *
+ * The `DATASET_KEYS` mirror provides the camelCase equivalents used with
+ * `element.dataset.*` access.
+ *
+ * Editor-neutral (prep-001) attributes live alongside the legacy `data-pm-*`
+ * attributes; both surfaces are emitted so that v1 consumers continue to work
+ * unmodified while future editor-neutral consumers (hit-test / range mapping)
+ * can address rendered output without consulting ProseMirror positions.
+ */
+/**
+ * Full attribute names for use with `getAttribute` / `setAttribute` / CSS selectors.
+ */
+export declare const DATA_ATTRS: {
+    /** ProseMirror start position of the element's content range. */
+    readonly PM_START: "data-pm-start";
+    /** ProseMirror end position of the element's content range. */
+    readonly PM_END: "data-pm-end";
+    /** Layout epoch stamp — incremented on each layout pass. */
+    readonly LAYOUT_EPOCH: "data-layout-epoch";
+    /** JSON-encoded table boundary metadata for resize overlays. */
+    readonly TABLE_BOUNDARIES: "data-table-boundaries";
+    /** SDT unique identifier. */
+    readonly SDT_ID: "data-sdt-id";
+    /** SDT type (fieldAnnotation, structuredContent, documentSection, etc.). */
+    readonly SDT_TYPE: "data-sdt-type";
+    /** Field annotation field identifier. */
+    readonly FIELD_ID: "data-field-id";
+    /** Field annotation field type (signer, text, checkbox, etc.). */
+    readonly FIELD_TYPE: "data-field-type";
+    /** Marks an element as draggable by the editor. */
+    readonly DRAGGABLE: "data-draggable";
+    /** Display label text for drag toast / accessibility. */
+    readonly DISPLAY_LABEL: "data-display-label";
+    /** Field annotation variant (text, image, signature, checkbox, html, link). */
+    readonly VARIANT: "data-variant";
+    /** Element type discriminator (annotation variant, etc.). */
+    readonly TYPE: "data-type";
+    /** Schema version for the editor-neutral layout boundary attributes. */
+    readonly LAYOUT_BOUNDARY_SCHEMA: "data-layout-boundary-schema";
+    /** Stable opaque id of the rendered fragment (see `LayoutFragmentId`). */
+    readonly LAYOUT_FRAGMENT_ID: "data-layout-fragment-id";
+    /** Encoded story locator (e.g. `body`, `header:rId4`, `footer:rId7`). */
+    readonly LAYOUT_STORY: "data-layout-story";
+    /** Source block reference (today: producer's `blockId`). */
+    readonly LAYOUT_BLOCK_REF: "data-layout-block-ref";
+};
+/**
+ * CamelCase keys for use with `element.dataset.*` property access.
+ *
+ * `element.dataset.pmStart` is equivalent to `element.getAttribute('data-pm-start')`.
+ */
+export declare const DATASET_KEYS: {
+    readonly PM_START: "pmStart";
+    readonly PM_END: "pmEnd";
+    readonly LAYOUT_EPOCH: "layoutEpoch";
+    readonly TABLE_BOUNDARIES: "tableBoundaries";
+    readonly SDT_ID: "sdtId";
+    readonly SDT_TYPE: "sdtType";
+    readonly FIELD_ID: "fieldId";
+    readonly FIELD_TYPE: "fieldType";
+    readonly DRAGGABLE: "draggable";
+    readonly DISPLAY_LABEL: "displayLabel";
+    readonly VARIANT: "variant";
+    readonly TYPE: "type";
+    readonly LAYOUT_BOUNDARY_SCHEMA: "layoutBoundarySchema";
+    readonly LAYOUT_FRAGMENT_ID: "layoutFragmentId";
+    readonly LAYOUT_STORY: "layoutStory";
+    readonly LAYOUT_BLOCK_REF: "layoutBlockRef";
+};
+/**
+ * Encode a `LayoutStoryLocator`-shaped object into its dataset string form.
+ *
+ * Format is `"body"` for body content and `"<kind>:<id>"` otherwise. The id
+ * is passed through verbatim (no escaping is applied) because the producers
+ * pass opaque part-relationship ids that do not contain the colon delimiter.
+ *
+ * Kept here so emitters and readers agree on the wire shape without taking a
+ * dependency on the contracts package from dom-contract.
+ */
+export declare const encodeLayoutStoryDataset: (story: {
+    kind: "body" | "header" | "footer" | "footnote" | "endnote" | "textbox" | "unknown";
+    id?: string;
+}) => string;
+/**
+ * Decode the dataset string back into a `LayoutStoryLocator`-shaped object.
+ *
+ * Used by editor-side DOM observers. Unknown kinds fall back to
+ * `{ kind: 'unknown' }` so downstream code can treat the value as a
+ * diagnostic, not as a default body.
+ */
+export declare const decodeLayoutStoryDataset: (raw: string | undefined | null) => {
+    kind: "body" | "header" | "footer" | "footnote" | "endnote" | "textbox" | "unknown";
+    id?: string;
+};

package/dist/layout-engine/dom-contract/src/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @superdoc/dom-contract
+ *
+ * Source of truth for the DOM surface contract shared between the painter
+ * (emitter) and editor-side DOM readers.
+ *
+ * This package owns:
+ * - CSS class name constants
+ * - Data-attribute name constants
+ * - Selector helpers built from the above
+ *
+ * It must NOT contain DOM querying logic, editor behavior, or painter
+ * implementation details.
+ */
+export { DOM_CLASS_NAMES, STRUCTURED_CONTENT_CHROME_LABEL_CLASS_NAMES } from './class-names.js';
+export type { DomClassName } from './class-names.js';
+export { DATA_ATTRS, DATASET_KEYS, encodeLayoutStoryDataset, decodeLayoutStoryDataset } from './data-attrs.js';
+export { buildImagePmSelector, buildInlineImagePmSelector, buildSdtBlockSelector, buildSdtInlineSelector, buildAnnotationSelector, buildAnnotationTypeSelector, buildAnnotationPmSelector, SDT_BLOCK_WITH_ID_SELECTOR, DRAGGABLE_SELECTOR, } from './selectors.js';

package/dist/layout-engine/dom-contract/src/selectors.d.ts

@@ -0,0 +1,47 @@
+/** Selector for any block SDT element that carries an sdtId attribute. */
+export declare const SDT_BLOCK_WITH_ID_SELECTOR: string;
+/** Selector for draggable elements. */
+export declare const DRAGGABLE_SELECTOR: string;
+/**
+ * Builds a compound CSS selector matching any image element (block fragment,
+ * inline clip-wrapper, or bare inline image) by its `data-pm-start` value.
+ *
+ * Useful when re-acquiring an image element after a layout re-render.
+ *
+ * Callers with untrusted or user-facing values should `CSS.escape()` before
+ * passing them here; numeric PM positions and pre-escaped IDs are safe as-is.
+ */
+export declare function buildImagePmSelector(pmStart: string | number): string;
+/**
+ * Builds a compound CSS selector matching inline image elements (clip-wrapper
+ * first, then bare inline image) by their `data-pm-start` value.
+ *
+ * Prefers the clip-wrapper because selection outlines and resize handles should
+ * target the visible cropped portion, not the scaled inner image.
+ */
+export declare function buildInlineImagePmSelector(pmStart: string | number): string;
+/**
+ * Builds a selector for block-level SDT elements with a given sdtId.
+ *
+ * Callers MUST `CSS.escape()` the sdtId before passing it here;
+ * numeric IDs and pre-escaped strings are safe as-is.
+ */
+export declare function buildSdtBlockSelector(escapedSdtId: string): string;
+/**
+ * Builds a selector for inline SDT wrapper elements with a given sdtId.
+ *
+ * Callers MUST `CSS.escape()` the sdtId before passing it here.
+ */
+export declare function buildSdtInlineSelector(escapedSdtId: string): string;
+/**
+ * Selector for annotation elements that carry a ProseMirror start position.
+ */
+export declare function buildAnnotationSelector(): string;
+/**
+ * Selector for annotation elements with a specific `data-type` value.
+ */
+export declare function buildAnnotationTypeSelector(type: string): string;
+/**
+ * Selector for an annotation element at a specific ProseMirror start position.
+ */
+export declare function buildAnnotationPmSelector(pmStart: string | number): string;