@owomark/view 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,228 @@
+import { OwoMarkCore, OwoMarkEditorInstance, OwoMarkSharedState, PreviewBlockKind, PreviewBlock } from '@owomark/core';
+export { DocumentChangeCallback } from '@owomark/core';
+export { Callout, CodeDemo, DEFAULT_MDX_COMPONENTS, FileTree, Kbd, MdxComponentMap, OwoMarkProcessor, OwoMarkProcessorOptions, OwoMarkThemeName, PluginEntry, ProcessorMode, SideAnnotationNode, Step, Steps, THEME_DARK_CLASS, THEME_LIGHT_CLASS, Tab, Tabs, createOwoMarkProcessor, getOwoMarkPlugins, getThemeClassName, rehypeMathDisplayFix, rehypeSideAnnotation, remarkConvertSoftBreaksToHardBreaks, remarkSideAnnotation } from './static.js';
+import 'react';
+import 'mdast';
+import 'hast';
+
+/**
+ * Three-layer view engine for OwoMark.
+ *
+ * Layer 1: Active block input proxy + state-to-DOM engine
+ * Layer 2: Shadow Buffer (IME composition with active block isolation)
+ * Layer 3: Cross-block virtual selection
+ *
+ * Only the active block (cursor position) has contenteditable="true" and
+ * receives focus. All other blocks are contenteditable="false".
+ */
+
+type OwoMarkViewEngine = {
+    mount(element: HTMLElement): void;
+    destroy(): void;
+    getActiveBlockId(): string | null;
+};
+type ViewEngineOptions = {
+    core: OwoMarkCore;
+};
+declare function createViewEngine(options: ViewEngineOptions): OwoMarkViewEngine;
+
+/**
+ * View engine for OwoMark.
+ *
+ * Provides two APIs:
+ * - createOwoMarkView(core, element): Three-layer sovereign view engine
+ * - createOwoMarkVanillaEditor(): Legacy standalone editor (backward compat)
+ */
+
+type OwoMarkView = OwoMarkViewEngine;
+/**
+ * Create a sovereign view engine bound to an existing Core instance and DOM element.
+ *
+ * This is the primary public API for non-React usage:
+ *   const core = createOwoMarkCore({ initialMarkdown: '# Hello' });
+ *   const view = createOwoMarkView(core, element);
+ */
+declare function createOwoMarkView(core: OwoMarkCore, element: HTMLElement): OwoMarkView;
+/**
+ * Create a standalone editor (creates its own Core internally).
+ * Preserved for backward compatibility with vanilla adapter consumers.
+ */
+declare function createOwoMarkVanillaEditor(): OwoMarkEditorInstance;
+
+type PreviewRenderPhase = 'idle' | 'rendering' | 'highlighting' | 'ready' | 'error';
+type PreviewCacheEntry = {
+    blockId: string;
+    renderKey: string;
+    html: string;
+    highlighted: boolean;
+    themeKey: string;
+    updatedAt: number;
+};
+type PreviewRenderContext = {
+    version: number;
+    themeKey: string;
+    abortSignal?: AbortSignal;
+    /**
+     * Line offset to add to source-line attributes in the rendered HTML.
+     * When a block starts at line N in the document, the renderer processes
+     * its raw content starting from line 1; this offset (N - 1) must be
+     * added to `data-source-line-start/end` so scroll sync anchors map
+     * to the correct document lines.
+     */
+    sourceLineOffset: number;
+};
+type PreviewRenderResult = {
+    kind: 'html';
+    html: string;
+} | {
+    kind: 'dom';
+    mount: (container: HTMLElement) => void;
+    unmount?: () => void;
+};
+type PreviewRendererMode = 'html-worker-safe' | 'dom-main-thread';
+type PreviewTaskPriority = 'realtime' | 'deferred';
+type PreviewRendererDefinition = {
+    mode: PreviewRendererMode;
+    priority: PreviewTaskPriority;
+    render: PreviewBlockRenderer;
+    version: string;
+};
+type PreviewBlockRenderer = (block: PreviewBlock, context: PreviewRenderContext) => Promise<PreviewRenderResult> | PreviewRenderResult;
+type PreviewRendererRegistry = {
+    get(kind: PreviewBlockKind): PreviewRendererDefinition | null;
+    register(kind: PreviewBlockKind, renderer: PreviewRendererDefinition): void;
+    unregister(kind: PreviewBlockKind): void;
+};
+type PreviewStrategy = 'incremental' | 'virtual';
+type OwoMarkPreviewEngineOptions = {
+    strategy?: PreviewStrategy;
+    themeKey?: string;
+    registry?: PreviewRendererRegistry;
+    viewportFirst?: boolean;
+    /**
+     * External block renderer function. When provided, the engine uses this
+     * instead of the built-in default renderer. This allows the host to supply
+     * its own Markdown pipeline (unified, remark, rehype, Shiki, etc.) without
+     * the preview package bundling those heavy dependencies.
+     */
+    renderBlock?: (block: PreviewBlock, context: PreviewRenderContext) => Promise<string>;
+    /**
+     * Called after every DOM mutation — including idle-backfilled and deferred
+     * block renders — not just after the synchronous update() return.
+     * Use for scroll sync or other post-DOM-update side effects.
+     */
+    onContentUpdate?: () => void;
+};
+type OwoMarkPreviewEngine = {
+    mount(root: HTMLElement): void;
+    destroy(): void;
+    update(state: OwoMarkSharedState): void;
+    getRenderedVersion(): number;
+};
+
+/**
+ * OwoMark Preview Engine factory.
+ *
+ * Dispatches to the configured strategy implementation:
+ * - 'incremental': Block-level incremental rendering (Strategy A)
+ * - 'virtual': Offscreen measurement + virtual layout (Strategy B, default)
+ */
+
+declare function createOwoMarkPreviewEngine(options?: OwoMarkPreviewEngineOptions): OwoMarkPreviewEngine;
+
+declare function createRendererRegistry(): PreviewRendererRegistry;
+
+/**
+ * Default block renderer using simple HTML conversion.
+ *
+ * This is a lightweight built-in renderer that converts Markdown block raw
+ * content to basic HTML. For full-featured rendering (GFM tables, math,
+ * syntax highlighting), the host should provide a custom `renderBlock`
+ * function via engine options, typically backed by unified/remark/rehype/Shiki.
+ *
+ * The default renderer handles common block types correctly and is suitable
+ * for basic previews without heavy dependencies.
+ */
+
+/**
+ * Render a single PreviewBlock to HTML using the built-in lightweight renderer.
+ */
+declare function renderBlockDefault(block: PreviewBlock): string;
+
+/**
+ * DOM patcher: blockId-driven incremental DOM updates.
+ *
+ * Maintains a mapping of blockId -> DOM wrapper element.
+ * Only dirty blocks get their content replaced; unchanged blocks are preserved.
+ */
+
+declare class PreviewDomPatcher {
+    private root;
+    private blockElements;
+    /** Tracked unmount callbacks for DOM-mounted renderers. */
+    private domUnmounts;
+    mount(root: HTMLElement): void;
+    destroy(): void;
+    /**
+     * Full render: replace all content with the given blocks.
+     */
+    fullRender(blocks: PreviewBlock[], htmlMap: Map<string, string>): void;
+    /**
+     * Incremental patch: update only dirty blocks.
+     * Handles additions, removals, and content changes.
+     */
+    patch(blocks: PreviewBlock[], htmlMap: Map<string, string>, dirtyBlockIds: Set<string>): void;
+    /**
+     * Rebuild DOM while reusing non-dirty block wrappers.
+     */
+    private rebuildWithReuse;
+    /**
+     * Update a single block's HTML content in place.
+     * Used by idle-scheduled backfill and deferred renders.
+     */
+    patchBlockHtml(blockId: string, html: string): void;
+    /**
+     * Mount a DOM renderer into a block's wrapper element.
+     * The renderer controls the wrapper's DOM directly.
+     */
+    mountDomContent(blockId: string, mountFn: (container: HTMLElement) => void, unmountFn?: () => void): void;
+    /**
+     * Cleanup a previous DOM mount for a block, if any.
+     */
+    private cleanupDomMount;
+    private createBlockWrapper;
+    private updateBlockAttributes;
+    /**
+     * Get the DOM element for a given blockId.
+     */
+    getBlockElement(blockId: string): HTMLElement | null;
+}
+
+/**
+ * SideAnnotationPositioner — Phase 3 JS dynamic positioning for side annotations.
+ *
+ * After the preview HTML is rendered with `.side-annotation` containers using CSS Grid,
+ * this module applies absolute positioning to annotation aside columns to handle
+ * collision avoidance when multiple annotations are near each other.
+ *
+ * Usage:
+ *   const positioner = new SideAnnotationPositioner(previewContainer);
+ *   positioner.reposition(); // call after each content update
+ *   positioner.destroy();    // cleanup
+ */
+declare class SideAnnotationPositioner {
+    private container;
+    private resizeObserver;
+    private repositionScheduled;
+    constructor(container: HTMLElement);
+    private setupResizeObserver;
+    private scheduleReposition;
+    /**
+     * Scan all side annotations in the container, detect overlaps,
+     * and apply offset positioning to avoid collisions.
+     */
+    reposition(): void;
+    destroy(): void;
+}
+
+export { type OwoMarkPreviewEngine, type OwoMarkPreviewEngineOptions, type OwoMarkView, type OwoMarkViewEngine, type PreviewBlockRenderer, type PreviewCacheEntry, PreviewDomPatcher, type PreviewRenderContext, type PreviewRenderPhase, type PreviewRenderResult, type PreviewRendererDefinition, type PreviewRendererMode, type PreviewRendererRegistry, type PreviewStrategy, type PreviewTaskPriority, SideAnnotationPositioner, type ViewEngineOptions, createOwoMarkPreviewEngine, createOwoMarkVanillaEditor, createOwoMarkView, createRendererRegistry, createViewEngine, renderBlockDefault };