@stll/folio-core 0.0.1-placeholder.0 → 0.1.1

package/dist/layout-engine/types.js

@@ -0,0 +1,100 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { isFloatingWrapType, isWrapNone } from "../docx/wrapTypes.js";
+//#region src/layout-engine/types.ts
+var types_exports = /* @__PURE__ */ __exportAll({
+	DEFAULT_TEXTBOX_MARGINS: () => DEFAULT_TEXTBOX_MARGINS,
+	DEFAULT_TEXTBOX_WIDTH: () => 200,
+	FOOTNOTE_ENTRY_MARGIN_BOTTOM: () => 0,
+	FOOTNOTE_FALLBACK_LINE_HEIGHT: () => 13,
+	FOOTNOTE_SEPARATOR_HEIGHT: () => 12,
+	floatingTextBoxReservesBand: () => floatingTextBoxReservesBand,
+	floatingTextBoxWrapsText: () => floatingTextBoxWrapsText,
+	isFloatingImageRun: () => isFloatingImageRun,
+	isFloatingTextBoxBlock: () => isFloatingTextBoxBlock,
+	isTextWrappingFloatingImageRun: () => isTextWrappingFloatingImageRun
+});
+/** Default internal margins for text boxes (OOXML defaults in pixels) */
+const DEFAULT_TEXTBOX_MARGINS = {
+	top: 4,
+	bottom: 4,
+	left: 7,
+	right: 7
+};
+/** Default text box width in pixels when no width is specified */
+const DEFAULT_TEXTBOX_WIDTH = 200;
+/**
+* Height of the horizontal separator line drawn above the footnote stack.
+* Used by the paginator when reserving space and by the painter when laying
+* out the stack at the bottom of the page.
+*/
+const FOOTNOTE_SEPARATOR_HEIGHT = 12;
+/**
+* Extra bottom margin applied to every rendered footnote entry, in CSS pixels.
+*
+* Word footnotes are separate paragraphs in the footnote story, so their
+* own paragraph spacing already describes the vertical gap between notes.
+* Keep the wrapper margin at zero to avoid adding whitespace that is not
+* present in the source DOCX.
+*/
+const FOOTNOTE_ENTRY_MARGIN_BOTTOM = 0;
+/**
+* Line height used when a footnote entry has no measured line height yet.
+* Conservative fallback so a missing measure does not collapse the entry.
+*/
+const FOOTNOTE_FALLBACK_LINE_HEIGHT = 13;
+/**
+* `true` when the image run is anchored at page-level coordinates instead of
+* participating in inline flow. Covers the OOXML floating wrap types
+* (`square`, `tight`, `through`, `behind`, `inFront`) and the legacy
+* `displayMode === "float"` escape hatch used by ProseMirror nodes that
+* pre-date the wrap-type round-trip.
+*
+* Pure predicate over `ImageRun` — no DOM, no measurement state. Lives here
+* so the bridge can call it without importing from the painter.
+*/
+const isFloatingImageRun = (run) => {
+	const wrapType = run.wrapType;
+	if (wrapType === "square" || wrapType === "tight" || wrapType === "through" || wrapType === "behind" || wrapType === "inFront") return true;
+	return run.displayMode === "float";
+};
+/**
+* `true` when a floating image should also shrink surrounding line widths.
+* `behind` / `inFront` (wrapNone) and `topAndBottom` do not — text either
+* paints over/under them or flows above/below as a block — only
+* `square` / `tight` / `through` carve a horizontal exclusion. The legacy
+* `displayMode === "float"` path is treated as wrapping when a CSS float
+* direction is set.
+*/
+const isTextWrappingFloatingImageRun = (run) => {
+	const wrapType = run.wrapType;
+	if (wrapType === "behind" || wrapType === "inFront" || wrapType === "topAndBottom") return false;
+	if (wrapType === "square" || wrapType === "tight" || wrapType === "through") return true;
+	return run.displayMode === "float" && run.cssFloat !== "none";
+};
+/**
+* `true` when the text box is anchored outside normal block flow — either
+* via the `float` display mode or via an OOXML floating wrap type (which
+* includes `topAndBottom`; see {@link floatingTextBoxReservesBand}).
+*/
+function isFloatingTextBoxBlock(block) {
+	return block.displayMode === "float" || isFloatingWrapType(block.wrapType);
+}
+/**
+* `true` when a floating text box should also reduce surrounding text
+* line widths. Excludes wrapNone (`behind`/`inFront`) and `topAndBottom`
+* which are positioned floats but do not carve a horizontal exclusion.
+*/
+function floatingTextBoxWrapsText(block) {
+	return isFloatingTextBoxBlock(block) && !isWrapNone(block.wrapType) && block.wrapType !== "topAndBottom";
+}
+/**
+* `true` when a floating text box reserves a full-width vertical band rather
+* than a side exclusion. `topAndBottom` boxes break the text above and below
+* the box (no text beside it), so surrounding lines flow past the band.
+* Ported from eigenpal #694.
+*/
+function floatingTextBoxReservesBand(block) {
+	return isFloatingTextBoxBlock(block) && block.wrapType === "topAndBottom";
+}
+//#endregion
+export { DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, floatingTextBoxReservesBand, floatingTextBoxWrapsText, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, types_exports };

package/dist/layout-painter/documentColors.d.ts

@@ -0,0 +1,4 @@
+//#region src/layout-painter/documentColors.d.ts
+declare function getAutomaticTextColorForBackground(backgroundColor: string | undefined): string | undefined;
+//#endregion
+export { getAutomaticTextColorForBackground };

package/dist/layout-painter/documentColors.js

@@ -0,0 +1,40 @@
+//#region src/layout-painter/documentColors.ts
+const HEX_COLOR_RE = /^#?[0-9a-f]{6}$/iu;
+const BLACK_TEXT_COLOR = "#000000";
+const WHITE_TEXT_COLOR = "#FFFFFF";
+const BLACK_LUMINANCE = 0;
+const WHITE_LUMINANCE = 1;
+const CONTRAST_OFFSET = .05;
+function normalizeHexColor(color) {
+	const trimmed = color.trim();
+	if (!HEX_COLOR_RE.test(trimmed)) return null;
+	return `#${trimmed.replace(/^#/u, "").toUpperCase()}`;
+}
+function relativeLuminance(hexColor) {
+	const normalized = normalizeHexColor(hexColor);
+	if (!normalized) return null;
+	const hex = normalized.slice(1);
+	const [red, green, blue] = [
+		0,
+		2,
+		4
+	].map((offset) => {
+		const value = Number.parseInt(hex.slice(offset, offset + 2), 16) / 255;
+		return value <= .03928 ? value / 12.92 : ((value + .055) / 1.055) ** 2.4;
+	});
+	if (red === void 0 || green === void 0 || blue === void 0) return null;
+	return .2126 * red + .7152 * green + .0722 * blue;
+}
+function contrastRatio(luminanceA, luminanceB) {
+	const lighter = Math.max(luminanceA, luminanceB);
+	const darker = Math.min(luminanceA, luminanceB);
+	return (lighter + CONTRAST_OFFSET) / (darker + CONTRAST_OFFSET);
+}
+function getAutomaticTextColorForBackground(backgroundColor) {
+	if (!backgroundColor) return;
+	const luminance = relativeLuminance(backgroundColor);
+	if (luminance === null) return;
+	return contrastRatio(luminance, BLACK_LUMINANCE) >= contrastRatio(luminance, WHITE_LUMINANCE) ? BLACK_TEXT_COLOR : WHITE_TEXT_COLOR;
+}
+//#endregion
+export { getAutomaticTextColorForBackground };

package/dist/layout-painter/index.d.ts

@@ -0,0 +1,110 @@
+import { FlowBlock, Layout, Measure } from "../layout-engine/types.js";
+import { RenderContext } from "./renderUtils.js";
+import { BlockFor, FeatureDispatchInput, FeatureFallback, FeatureModule, FeatureRenderInput, FragmentFor, MeasureFor } from "./registry/types.js";
+import { FeatureRegistry, createFeatureRegistry } from "./registry/registry.js";
+import { FRAGMENT_CLASS_NAMES, renderFragment } from "./renderFragment.js";
+import { IMAGE_CLASS_NAMES, renderImageFragment } from "./renderImage.js";
+import { renderPage, renderPages } from "./renderPage.js";
+import { renderLine, renderParagraphFragment, sliceRunsForLine } from "./renderParagraph.js";
+import { TABLE_CLASS_NAMES, renderTableFragment } from "./renderTable.js";
+import { TEXTBOX_CLASS_NAMES, renderTextBoxFragment } from "./renderTextBox.js";
+import { createDefaultRegistry } from "./registry/modules.js";
+
+//#region src/layout-painter/index.d.ts
+/**
+ * Block lookup entry for painter
+ */
+type BlockLookupEntry = {
+  block: FlowBlock;
+  measure: Measure;
+  version?: string;
+};
+/**
+ * Block lookup map type
+ */
+type BlockLookup = Map<string, BlockLookupEntry>;
+/**
+ * Painter options
+ */
+type PainterOptions = {
+  /** Document to create elements in */document?: Document; /** Gap between pages in pixels */
+  pageGap?: number; /** Show page shadows */
+  showShadow?: boolean; /** Background color for pages */
+  pageBackground?: string; /** Container background color */
+  containerBackground?: string;
+  /**
+   * Optional custom feature registry. Defaults to `createDefaultRegistry()`.
+   * Pass a custom registry to swap or extend renderers without subclassing
+   * `LayoutPainter`.
+   */
+  registry?: FeatureRegistry;
+};
+/**
+ * Layout Painter class
+ *
+ * Renders Layout data to DOM with efficient reconciliation.
+ * Only updates changed pages and fragments for better performance.
+ */
+declare class LayoutPainter {
+  private container;
+  private blockLookup;
+  private pageStates;
+  private totalPages;
+  private readonly options;
+  private readonly doc;
+  private readonly registry;
+  constructor(options?: PainterOptions);
+  /**
+   * Set the block lookup map for rendering fragments
+   */
+  setBlockLookup(lookup: BlockLookup): void;
+  /**
+   * Mount the painter to a container element
+   */
+  mount(container: HTMLElement): void;
+  /**
+   * Unmount the painter
+   */
+  unmount(): void;
+  /**
+   * Apply styles to the container
+   */
+  private applyContainerStyles;
+  /**
+   * Paint a layout to the container
+   */
+  paint(layout: Layout): void;
+  /**
+   * Render a page using block lookup for full fragment rendering
+   */
+  private renderPageWithLookup;
+  /**
+   * Render a fragment via the feature-module registry. Dispatch is O(1)
+   * keyed on `fragment.kind`; modules supply the actual render. Fragments
+   * without a resolved block/measure or with an unregistered kind fall
+   * back to the placeholder renderer (`renderFragment`).
+   */
+  private renderFragmentWithLookup;
+  /**
+   * Apply positioning styles to a fragment element
+   */
+  private applyFragmentPosition;
+  /**
+   * Get the current page count
+   */
+  getPageCount(): number;
+  /**
+   * Get a page element by index
+   */
+  getPageElement(index: number): HTMLElement | null;
+  /**
+   * Scroll to a specific page
+   */
+  scrollToPage(pageNumber: number): void;
+}
+/**
+ * Create a new LayoutPainter instance
+ */
+declare function createPainter(options?: PainterOptions): LayoutPainter;
+//#endregion
+export { type BlockFor, BlockLookup, BlockLookupEntry, FRAGMENT_CLASS_NAMES, type FeatureDispatchInput, type FeatureFallback, type FeatureModule, type FeatureRegistry, type FeatureRenderInput, type FragmentFor, IMAGE_CLASS_NAMES, LayoutPainter, type MeasureFor, PainterOptions, type RenderContext, TABLE_CLASS_NAMES, TEXTBOX_CLASS_NAMES, createDefaultRegistry, createFeatureRegistry, createPainter, renderFragment, renderImageFragment, renderLine, renderPage, renderPages, renderParagraphFragment, renderTableFragment, renderTextBoxFragment, sliceRunsForLine };

package/dist/layout-painter/index.js

@@ -0,0 +1,182 @@
+import { FRAGMENT_CLASS_NAMES, renderFragment } from "./renderFragment.js";
+import { IMAGE_CLASS_NAMES, renderImageFragment } from "./renderImage.js";
+import { renderLine, renderParagraphFragment, sliceRunsForLine } from "./renderParagraph.js";
+import { TABLE_CLASS_NAMES, renderTableFragment } from "./renderTable.js";
+import { TEXTBOX_CLASS_NAMES, renderTextBoxFragment } from "./renderTextBox.js";
+import { renderPage, renderPages } from "./renderPage.js";
+import { prefersReducedMotionBehavior } from "../paged-layout/scrollNavigation.js";
+import { createFeatureRegistry } from "./registry/registry.js";
+import { createDefaultRegistry } from "./registry/modules.js";
+import { panic } from "better-result";
+//#region src/layout-painter/index.ts
+/**
+* Layout Painter
+*
+* Main entry point for rendering Layout data to DOM.
+* Provides reconciliation for efficient incremental updates.
+*/
+/**
+* Layout Painter class
+*
+* Renders Layout data to DOM with efficient reconciliation.
+* Only updates changed pages and fragments for better performance.
+*/
+var LayoutPainter = class {
+	container = null;
+	blockLookup = /* @__PURE__ */ new Map();
+	pageStates = [];
+	totalPages = 0;
+	options;
+	doc;
+	registry;
+	constructor(options = {}) {
+		this.options = options;
+		this.doc = options.document ?? document;
+		this.registry = options.registry ?? createDefaultRegistry();
+	}
+	/**
+	* Set the block lookup map for rendering fragments
+	*/
+	setBlockLookup(lookup) {
+		this.blockLookup = lookup;
+	}
+	/**
+	* Mount the painter to a container element
+	*/
+	mount(container) {
+		this.container = container;
+		this.applyContainerStyles();
+	}
+	/**
+	* Unmount the painter
+	*/
+	unmount() {
+		if (this.container) this.container.innerHTML = "";
+		this.container = null;
+		this.pageStates = [];
+	}
+	/**
+	* Apply styles to the container
+	*/
+	applyContainerStyles() {
+		if (!this.container) return;
+		const pageGap = this.options.pageGap ?? 24;
+		this.container.style.display = "flex";
+		this.container.style.flexDirection = "column";
+		this.container.style.alignItems = "center";
+		this.container.style.gap = `${pageGap}px`;
+		this.container.style.padding = `${pageGap}px`;
+		this.container.style.backgroundColor = this.options.containerBackground ?? "var(--doc-bg, #f8f9fa)";
+		this.container.style.minHeight = "100%";
+	}
+	/**
+	* Paint a layout to the container
+	*/
+	paint(layout) {
+		if (!this.container) panic("LayoutPainter: not mounted");
+		const { pages } = layout;
+		this.totalPages = pages.length;
+		this.container.innerHTML = "";
+		this.pageStates = [];
+		for (const i_item of pages) {
+			const page = i_item;
+			const context = {
+				pageNumber: page.number,
+				totalPages: this.totalPages,
+				section: "body"
+			};
+			const pageEl = this.renderPageWithLookup(page, context);
+			this.container.append(pageEl);
+			this.pageStates.push({
+				element: pageEl,
+				pageNumber: page.number,
+				fragmentCount: page.fragments.length
+			});
+		}
+	}
+	/**
+	* Render a page using block lookup for full fragment rendering
+	*/
+	renderPageWithLookup(page, context) {
+		const pageEl = this.doc.createElement("div");
+		pageEl.className = "layout-page";
+		pageEl.dataset["pageNumber"] = String(page.number);
+		pageEl.style.position = "relative";
+		pageEl.style.width = `${page.size.w}px`;
+		pageEl.style.height = `${page.size.h}px`;
+		pageEl.style.backgroundColor = this.options.pageBackground ?? "var(--doc-canvas, #ffffff)";
+		pageEl.style.color = "var(--doc-canvas-text, #1f2937)";
+		pageEl.style.overflow = "hidden";
+		const contentEl = this.doc.createElement("div");
+		contentEl.className = "layout-page-content";
+		contentEl.style.position = "absolute";
+		contentEl.style.top = `${page.margins.top}px`;
+		contentEl.style.left = `${page.margins.left}px`;
+		contentEl.style.right = `${page.margins.right}px`;
+		contentEl.style.bottom = `${page.margins.bottom}px`;
+		contentEl.style.overflow = "visible";
+		for (const fragment of page.fragments) {
+			const fragmentEl = this.renderFragmentWithLookup(fragment, context);
+			this.applyFragmentPosition(fragmentEl, fragment);
+			contentEl.append(fragmentEl);
+		}
+		pageEl.append(contentEl);
+		return pageEl;
+	}
+	/**
+	* Render a fragment via the feature-module registry. Dispatch is O(1)
+	* keyed on `fragment.kind`; modules supply the actual render. Fragments
+	* without a resolved block/measure or with an unregistered kind fall
+	* back to the placeholder renderer (`renderFragment`).
+	*/
+	renderFragmentWithLookup(fragment, context) {
+		const lookup = this.blockLookup.get(String(fragment.blockId));
+		return this.registry.render({
+			fragment,
+			block: lookup?.block,
+			measure: lookup?.measure,
+			context,
+			doc: this.doc
+		});
+	}
+	/**
+	* Apply positioning styles to a fragment element
+	*/
+	applyFragmentPosition(element, fragment) {
+		element.style.position = "absolute";
+		element.style.left = `${fragment.x}px`;
+		element.style.top = `${fragment.y}px`;
+		element.style.width = `${fragment.width}px`;
+		element.style.height = `${fragment.height}px`;
+	}
+	/**
+	* Get the current page count
+	*/
+	getPageCount() {
+		return this.totalPages;
+	}
+	/**
+	* Get a page element by index
+	*/
+	getPageElement(index) {
+		return this.pageStates[index]?.element ?? null;
+	}
+	/**
+	* Scroll to a specific page
+	*/
+	scrollToPage(pageNumber) {
+		const state = this.pageStates.find((s) => s.pageNumber === pageNumber);
+		if (state?.element) state.element.scrollIntoView({
+			behavior: prefersReducedMotionBehavior(),
+			block: "start"
+		});
+	}
+};
+/**
+* Create a new LayoutPainter instance
+*/
+function createPainter(options) {
+	return new LayoutPainter(options);
+}
+//#endregion
+export { FRAGMENT_CLASS_NAMES, IMAGE_CLASS_NAMES, LayoutPainter, TABLE_CLASS_NAMES, TEXTBOX_CLASS_NAMES, createDefaultRegistry, createFeatureRegistry, createPainter, renderFragment, renderImageFragment, renderLine, renderPage, renderPages, renderParagraphFragment, renderTableFragment, renderTextBoxFragment, sliceRunsForLine };

package/dist/layout-painter/registry/modules/image.d.ts

@@ -0,0 +1,6 @@
+import { FeatureModule } from "../types.js";
+
+//#region src/layout-painter/registry/modules/image.d.ts
+declare const imageModule: FeatureModule<"image">;
+//#endregion
+export { imageModule };

package/dist/layout-painter/registry/modules/image.js

@@ -0,0 +1,17 @@
+import { renderImageFragment } from "../../renderImage.js";
+//#region src/layout-painter/registry/modules/image.ts
+/**
+* Image feature module — renders `ImageFragment`.
+*
+* Thin wrapper over `renderImageFragment`. Kept as a module so the
+* registry can dispatch image fragments uniformly and so future
+* variants (e.g. SVG, EMF preview) can plug in alongside.
+*/
+const imageModule = {
+	kind: "image",
+	render({ fragment, block, measure, context, doc }) {
+		return renderImageFragment(fragment, block, measure, context, { document: doc });
+	}
+};
+//#endregion
+export { imageModule };

package/dist/layout-painter/registry/modules/paragraph.d.ts

@@ -0,0 +1,6 @@
+import { FeatureModule } from "../types.js";
+
+//#region src/layout-painter/registry/modules/paragraph.d.ts
+declare const paragraphModule: FeatureModule<"paragraph">;
+//#endregion
+export { paragraphModule };

package/dist/layout-painter/registry/modules/paragraph.js

@@ -0,0 +1,18 @@
+import { renderParagraphFragment } from "../../renderParagraph.js";
+//#region src/layout-painter/registry/modules/paragraph.ts
+/**
+* Paragraph feature module — wraps `renderParagraphFragment`.
+*
+* The paragraph orchestrator is intentionally still monolithic: it dispatches
+* paragraph-internal kinds (runs, fields, inline images, hyperlinks). Future
+* work can split that into a sub-registry without changing this module's
+* external contract.
+*/
+const paragraphModule = {
+	kind: "paragraph",
+	render({ fragment, block, measure, context, doc }) {
+		return renderParagraphFragment(fragment, block, measure, context, { document: doc });
+	}
+};
+//#endregion
+export { paragraphModule };

package/dist/layout-painter/registry/modules/table.d.ts

@@ -0,0 +1,6 @@
+import { FeatureModule } from "../types.js";
+
+//#region src/layout-painter/registry/modules/table.d.ts
+declare const tableModule: FeatureModule<"table">;
+//#endregion
+export { tableModule };

package/dist/layout-painter/registry/modules/table.js

@@ -0,0 +1,16 @@
+import { renderTableFragment } from "../../renderTable.js";
+//#region src/layout-painter/registry/modules/table.ts
+/**
+* Table feature module — wraps `renderTableFragment`.
+*
+* Like paragraph, the table orchestrator still owns row/cell rendering.
+* Splitting cell-level renderers into a sub-registry is future work.
+*/
+const tableModule = {
+	kind: "table",
+	render({ fragment, block, measure, context, doc }) {
+		return renderTableFragment(fragment, block, measure, context, { document: doc });
+	}
+};
+//#endregion
+export { tableModule };

package/dist/layout-painter/registry/modules/textBox.d.ts

@@ -0,0 +1,6 @@
+import { FeatureModule } from "../types.js";
+
+//#region src/layout-painter/registry/modules/textBox.d.ts
+declare const textBoxModule: FeatureModule<"textBox">;
+//#endregion
+export { textBoxModule };

package/dist/layout-painter/registry/modules/textBox.js

@@ -0,0 +1,13 @@
+import { renderTextBoxFragment } from "../../renderTextBox.js";
+//#region src/layout-painter/registry/modules/textBox.ts
+/**
+* Text-box feature module — renders `TextBoxFragment`.
+*/
+const textBoxModule = {
+	kind: "textBox",
+	render({ fragment, block, measure, context, doc }) {
+		return renderTextBoxFragment(fragment, block, measure, context, { document: doc });
+	}
+};
+//#endregion
+export { textBoxModule };

package/dist/layout-painter/registry/modules.d.ts

@@ -0,0 +1,6 @@
+import { FeatureRegistry } from "./registry.js";
+
+//#region src/layout-painter/registry/modules.d.ts
+declare function createDefaultRegistry(): FeatureRegistry;
+//#endregion
+export { createDefaultRegistry };

package/dist/layout-painter/registry/modules.js

@@ -0,0 +1,26 @@
+import { imageModule } from "./modules/image.js";
+import { paragraphModule } from "./modules/paragraph.js";
+import { tableModule } from "./modules/table.js";
+import { textBoxModule } from "./modules/textBox.js";
+import { createFeatureRegistry } from "./registry.js";
+//#region src/layout-painter/registry/modules.ts
+/**
+* Default feature-module registry.
+*
+* To add a new OOXML renderer:
+*   1. Create `modules/<kind>.ts` exporting a `FeatureModule<"...">`.
+*   2. Add one import + `register(...)` line below.
+*
+* Discovery is explicit (not glob-based) so register lines are greppable
+* and tree-shaking stays deterministic.
+*/
+function createDefaultRegistry() {
+	const registry = createFeatureRegistry();
+	registry.register(paragraphModule);
+	registry.register(tableModule);
+	registry.register(imageModule);
+	registry.register(textBoxModule);
+	return registry;
+}
+//#endregion
+export { createDefaultRegistry };

package/dist/layout-painter/registry/registry.d.ts

@@ -0,0 +1,24 @@
+import { Fragment } from "../../layout-engine/types.js";
+import { FeatureDispatchInput, FeatureFallback, FeatureModule } from "./types.js";
+
+//#region src/layout-painter/registry/registry.d.ts
+type FeatureRegistry = {
+  register: <TKind extends Fragment["kind"]>(mod: FeatureModule<TKind>) => void;
+  get: <TKind extends Fragment["kind"]>(kind: TKind) => FeatureModule<TKind> | undefined;
+  has: (kind: Fragment["kind"]) => boolean;
+  render: (input: FeatureDispatchInput) => HTMLElement;
+};
+type CreateFeatureRegistryOptions = {
+  /**
+   * Hook for unknown kinds and fragments with no resolved block/measure.
+   * Defaults to the placeholder renderer in `renderFragment.ts`.
+   */
+  fallback?: FeatureFallback;
+};
+/**
+ * Build a new feature registry. Callers register modules, then dispatch via
+ * `render()`. The registry never mutates module objects.
+ */
+declare function createFeatureRegistry(options?: CreateFeatureRegistryOptions): FeatureRegistry;
+//#endregion
+export { CreateFeatureRegistryOptions, FeatureRegistry, createFeatureRegistry };

package/dist/layout-painter/registry/registry.js

@@ -0,0 +1,53 @@
+import { renderFragment } from "../renderFragment.js";
+import { panic } from "better-result";
+//#region src/layout-painter/registry/registry.ts
+/**
+* Feature-module registry for the layout painter.
+*
+* O(1) dispatch keyed on `Fragment["kind"]`. Modules self-describe their
+* kind; the registry routes each fragment to its module's `render()`. A
+* fallback closes the loop for unknown kinds and for fragments arriving
+* without a resolved block/measure.
+*/
+const defaultFallback = ({ fragment, context, doc }) => renderFragment(fragment, context, { document: doc });
+/**
+* Build a new feature registry. Callers register modules, then dispatch via
+* `render()`. The registry never mutates module objects.
+*/
+function createFeatureRegistry(options = {}) {
+	const modules = /* @__PURE__ */ new Map();
+	const fallback = options.fallback ?? defaultFallback;
+	const register = (mod) => {
+		if (modules.has(mod.kind)) panic(`FeatureRegistry: module for kind "${mod.kind}" is already registered`);
+		modules.set(mod.kind, mod);
+	};
+	const get = (kind) => {
+		const found = modules.get(kind);
+		if (!found) return;
+		return found;
+	};
+	const has = (kind) => modules.has(kind);
+	const render = ({ fragment, block, measure, context, doc }) => {
+		const mod = modules.get(fragment.kind);
+		if (!mod || !block || !measure) return fallback({
+			fragment,
+			context,
+			doc
+		});
+		return mod.render({
+			fragment,
+			block,
+			measure,
+			context,
+			doc
+		});
+	};
+	return {
+		register,
+		get,
+		has,
+		render
+	};
+}
+//#endregion
+export { createFeatureRegistry };