@owomark/processor 0.1.5

package/README.md

@@ -0,0 +1,41 @@
+# `@owomark/processor`
+
+Node-safe Markdown and MDX processing for OwoMark. This package owns the static rendering pipeline, remark/rehype plugins, built-in MDX components, and MDX component CSS.
+
+## Install
+
+```bash
+npm install @owomark/processor
+```
+
+If you enable MDX evaluation, also install peer dependencies:
+
+```bash
+npm install @mdx-js/mdx react react-dom
+```
+
+## Usage
+
+```ts
+import { createOwoMarkProcessor } from '@owomark/processor';
+
+const processor = createOwoMarkProcessor({
+  mode: 'production',
+  enableMdx: true,
+});
+
+const html = await processor.process('# Hello');
+```
+
+Import component styles separately:
+
+```ts
+import '@owomark/processor/mdx-components.css';
+```
+
+To apply official light or dark token values, layer in theme CSS from `@owomark/view`:
+
+```ts
+import '@owomark/processor/mdx-components.css';
+import '@owomark/view/light.css';
+```

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { BlockContent, Root } from 'mdast';
+import { Root as Root$1 } from 'hast';
+
+/**
+ * Rehype plugin: unwrap display math from `<pre><code>` wrappers.
+ *
+ * remark-math + remark-rehype produce `<pre><code class="language-math math-display">`.
+ * rehype-katex renders the KaTeX HTML inside that `<code>`, but the outer
+ * `<pre>` triggers code-block styling and suppresses block-level math display.
+ * This plugin hoists the rendered KaTeX content out of `<pre><code>`.
+ */
+declare function rehypeMathDisplayFix(): (tree: any) => void;
+
+/**
+ * Remark plugin: convert paragraph-level soft line breaks into hard break nodes.
+ *
+ * Only rewrites inline phrasing content inside paragraphs, so fenced code,
+ * tables, math blocks, and other block structures keep their original
+ * Markdown semantics.
+ */
+declare function remarkConvertSoftBreaksToHardBreaks(): (tree: any) => void;
+
+/**
+ * remark-side-annotation — OwoMark Side Annotation syntax plugin.
+ *
+ * Parses four tiers of side annotation syntax and produces SideAnnotation
+ * container nodes in the mdast tree:
+ *
+ * - Tier 1:  `text (>} annotation)`         — single-block inline
+ * - Tier 1+: `text (>} anno)` + `(>+)`      — 2-3 block continuation
+ * - Tier 2:  `:::side (>} anno) ... :::`     — 4+ block container
+ * - Tier 3:  `:::side [>id] ... :::` + def   — long-content reference
+ *
+ * @see docs/pitch/owomark-side-annotation.md
+ * @see docs/adr/ADR-010-owomark-side-annotation-syntax-design.md
+ */
+
+/**
+ * Custom mdast node for side annotations.
+ * Discriminant: `type: 'sideAnnotation'` — use this for type guards
+ * (e.g. `node.type === 'sideAnnotation'`).
+ * Bridged to rehype via `data.hName`/`data.hProperties`.
+ */
+interface SideAnnotationNode {
+    /** Discriminant — always `'sideAnnotation'`. */
+    type: 'sideAnnotation';
+    data: {
+        hName: 'div';
+        hProperties: {
+            className: string[];
+            'data-side-type': string;
+            'data-side-text'?: string;
+            'data-side-orphan'?: string;
+        };
+    };
+    sideType: string;
+    sideTypeSymbol: string;
+    noteRef: string | null;
+    inlineText: string | null;
+    orphan?: boolean;
+    children: BlockContent[];
+}
+declare function remarkSideAnnotation(): (tree: Root) => void;
+
+/**
+ * rehype-side-annotation — Transforms remark-side-annotation output into
+ * full HTML structure with CSS Grid layout and SVG decorations.
+ *
+ * After remark-rehype, SideAnnotation nodes become `<div>` elements with
+ * `data-side-type` attributes. This plugin detects them and injects the
+ * two-column grid structure (main content + annotation aside).
+ *
+ * SVG decorations use segmented rendering (ADR-014): fixed-height SVG
+ * caps/beaks + flex-stretch line divs. This prevents curve distortion
+ * at any container height.
+ *
+ * @see docs/adr/ADR-014-side-annotation-segmented-svg-rendering.md
+ * @see docs/pitch/owomark-side-annotation.md §R4
+ */
+
+declare function rehypeSideAnnotation(): (tree: Root$1) => void;
+
+/**
+ * micromark-side-annotation — micromark syntax extension for Side Annotation.
+ *
+ * Tokenizes `(>TYPE CONTENT)` as a single opaque token at the micromark level
+ * (Phase 0), preventing MDX's expression parser from intercepting `{` / `}`
+ * inside the annotation marker. The fromMarkdown extension converts the token
+ * back to a plain text node so that `remark-side-annotation` (Phase 2 tree
+ * transform) can process it unchanged.
+ *
+ * Also tokenizes `(>+)` continuation markers for the same reason.
+ */
+
+/**
+ * Remark plugin that registers the micromark + fromMarkdown extensions.
+ * Add this BEFORE `remarkMdx` in the plugin chain so the micromark tokenizer
+ * is available when the parser runs.
+ */
+declare function remarkMicromarkSideAnnotation(this: any): void;
+
+type ProcessorMode = 'preview' | 'production';
+/** A single plugin or a [plugin, ...options] tuple accepted by unified. */
+type PluginEntry = unknown | [unknown, ...unknown[]];
+/** Minimal processor contract shared by unified and MDX engines. */
+interface OwoMarkProcessor {
+    process(source: string): Promise<{
+        toString(): string;
+        value: string;
+    }>;
+}
+/** React component map for MDX rendering. */
+type MdxComponentMap = Record<string, React.ComponentType<any>>;
+type OwoMarkProcessorOptions = {
+    /** Rendering mode. Defaults to 'preview'. */
+    mode?: ProcessorMode;
+    /**
+     * When false (default), plain newlines in paragraphs become `<br>`.
+     * When true, CommonMark soft-break semantics are preserved.
+     */
+    preserveSoftLineBreaks?: boolean;
+    /** Shiki theme for code highlighting. Defaults to 'vitesse-light'. */
+    codeTheme?: string;
+    /**
+     * Additional rehype plugins injected after the core chain but before
+     * rehype-stringify. Use this for host-specific plugins like
+     * rehypeSourceLines (scroll-sync anchors).
+     */
+    extraRehypePlugins?: PluginEntry[];
+    /**
+     * Additional remark plugins injected after the core remark chain but
+     * before remark-rehype. Use for host-specific remark transformations.
+     */
+    extraRemarkPlugins?: PluginEntry[];
+    /** Enable side annotation syntax. Defaults to true. */
+    enableSideAnnotation?: boolean;
+    /** Enable math (KaTeX) rendering. Defaults to true. */
+    enableMath?: boolean;
+    /** Enable fenced markdown sandbox rendering. Defaults to true. */
+    enableMarkdownSandbox?: boolean;
+    /** Markdown sandbox configuration. */
+    markdownSandbox?: {
+        outerFenceTicks?: number;
+    };
+    /**
+     * Enable MDX rendering via @mdx-js/mdx evaluate().
+     * When true, the processor delegates to evaluate() + renderToStaticMarkup()
+     * instead of the unified pipeline. Defaults to false.
+     */
+    enableMdx?: boolean;
+    /**
+     * Additional or override React components for MDX rendering.
+     * Merged on top of the built-in defaults (Callout, CodeDemo).
+     * Only used when enableMdx is true.
+     */
+    mdxComponents?: MdxComponentMap;
+};
+/**
+ * Create a fully configured processor (Gold Processor).
+ *
+ * When `enableMdx` is false (default), returns a unified Processor.
+ * When `enableMdx` is true, returns an MDX-aware processor that delegates to
+ * `@mdx-js/mdx` evaluate() + renderToStaticMarkup(). Both share the same
+ * `process(source) → HTML string` contract.
+ */
+declare function createOwoMarkProcessor(options?: OwoMarkProcessorOptions): OwoMarkProcessor;
+declare function getOwoMarkPlugins(options?: OwoMarkProcessorOptions): {
+    remarkPlugins: PluginEntry[];
+    rehypePlugins: PluginEntry[];
+};
+
+declare function Callout({ type, children }: {
+    type?: string;
+    children?: ReactNode;
+}): react.DetailedReactHTMLElement<{
+    className: string;
+    'data-callout-type': string;
+}, HTMLElement>;
+
+declare function CodeDemo({ title, language, code }: {
+    title?: string;
+    language?: string;
+    code: string;
+}): react.DetailedReactHTMLElement<{
+    className: string;
+    'data-code-demo': string;
+}, HTMLElement>;
+
+declare function Steps({ children }: {
+    children?: ReactNode;
+}): react.DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement>;
+declare function Step({ title, children }: {
+    title?: string;
+    children?: ReactNode;
+}): react.DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement>;
+
+declare function Tabs({ children }: {
+    children?: ReactNode;
+}): react.DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement>;
+declare function Tab({ label: _label, children }: {
+    label?: string;
+    children?: ReactNode;
+}): react.DetailedReactHTMLElement<react.HTMLAttributes<HTMLElement>, HTMLElement>;
+
+declare function FileTree({ children }: {
+    children?: ReactNode;
+}): react.DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement>;
+
+declare function Kbd({ children }: {
+    children?: ReactNode;
+}): react.DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement>;
+
+/**
+ * Built-in MDX components shipped with owomark-view.
+ *
+ * These are the default components available when `enableMdx: true`.
+ * Users can override any of these or add new ones via the `mdxComponents` option.
+ */
+
+declare const DEFAULT_MDX_COMPONENTS: MdxComponentMap;
+
+export { Callout, CodeDemo, DEFAULT_MDX_COMPONENTS, FileTree, Kbd, type MdxComponentMap, type OwoMarkProcessor, type OwoMarkProcessorOptions, type PluginEntry, type ProcessorMode, type SideAnnotationNode, Step, Steps, Tab, Tabs, createOwoMarkProcessor, getOwoMarkPlugins, rehypeMathDisplayFix, rehypeSideAnnotation, remarkConvertSoftBreaksToHardBreaks, remarkMicromarkSideAnnotation, remarkSideAnnotation };