@sigx/lynx-markdown 0.4.4 → 0.4.6

package/dist/render/engine.js

@@ -0,0 +1,145 @@
+/**
+ * Render engine: walks a `BlockNode[]` AST and dispatches each node to a
+ * {@link MarkdownComponents} renderer.
+ *
+ * Responsibilities the engine keeps (so components stay simple and design
+ * systems can't accidentally break streaming):
+ *  - AST recursion — children are fully rendered before a component is called.
+ *  - Stable reconciliation keys — `VNode.key` is stamped from the AST node's
+ *    streaming key after the component returns, so finalized blocks never
+ *    remount regardless of which element a component produced.
+ */
+/** Stamp a stable reconciliation key onto a rendered element (no-op for strings). */
+function stampKey(el, key) {
+    if (el && typeof el === 'object')
+        el.key = key;
+}
+/** Render top-level blocks and wrap them in the `root` container. */
+export function renderDocument(blocks, ctx) {
+    const children = blocks.map((b) => renderBlock(b, ctx));
+    return ctx.components.root({ children });
+}
+function renderBlock(block, ctx) {
+    const C = ctx.components;
+    let el;
+    switch (block.type) {
+        case 'heading':
+            el = C.heading({ level: block.level, children: renderInline(block.children, ctx), node: block });
+            break;
+        case 'paragraph':
+            el = C.paragraph({ children: renderInline(block.children, ctx), node: block });
+            break;
+        case 'blockquote':
+            el = C.blockquote({ children: block.children.map((b) => renderBlock(b, ctx)), node: block });
+            break;
+        case 'list':
+            el = C.list({
+                ordered: block.ordered,
+                start: block.start,
+                tight: block.tight,
+                children: block.items.map((item, i) => {
+                    const li = C.listItem({
+                        ordered: block.ordered,
+                        index: i,
+                        number: block.start + i,
+                        checked: item.checked,
+                        children: item.children.map((b) => renderBlock(b, ctx)),
+                        item,
+                    });
+                    stampKey(li, item.key);
+                    return li;
+                }),
+                node: block,
+            });
+            break;
+        case 'codeBlock':
+            el = C.code({
+                ...(block.lang ? { lang: block.lang } : {}),
+                value: block.value,
+                closed: block.closed,
+                node: block,
+            });
+            break;
+        case 'thematicBreak':
+            el = C.thematicBreak({ node: block });
+            break;
+        case 'table':
+            el = renderTable(block, ctx);
+            break;
+    }
+    stampKey(el, block.key);
+    return el;
+}
+function renderTable(block, ctx) {
+    const C = ctx.components;
+    const headerCells = block.header.map((cell, i) => {
+        const c = C.tableCell({
+            header: true,
+            align: block.align[i] ?? null,
+            children: renderInline(cell.children, ctx),
+            node: block,
+        });
+        stampKey(c, `c${i}`);
+        return c;
+    });
+    const headerRow = C.tableRow({ header: true, children: headerCells, node: block });
+    stampKey(headerRow, 'head');
+    const bodyRows = block.rows.map((row, ri) => {
+        const cells = row.map((cell, ci) => {
+            const c = C.tableCell({
+                header: false,
+                align: block.align[ci] ?? null,
+                children: renderInline(cell.children, ctx),
+                node: block,
+            });
+            stampKey(c, `c${ci}`);
+            return c;
+        });
+        const r = C.tableRow({ header: false, children: cells, node: block });
+        stampKey(r, `r${ri}`);
+        return r;
+    });
+    return C.table({ align: block.align, children: [headerRow, ...bodyRows], node: block });
+}
+function renderInline(nodes, ctx) {
+    return nodes.map((node, i) => {
+        const el = renderInlineNode(node, ctx);
+        stampKey(el, String(i));
+        return el;
+    });
+}
+function renderInlineNode(node, ctx) {
+    const C = ctx.components;
+    switch (node.type) {
+        case 'text':
+            return node.value;
+        case 'br':
+            return C.br();
+        case 'strong':
+            return C.strong({ children: renderInline(node.children, ctx), node });
+        case 'em':
+            return C.em({ children: renderInline(node.children, ctx), node });
+        case 'del':
+            return C.del({ children: renderInline(node.children, ctx), node });
+        case 'codeSpan':
+            return C.codeSpan({ value: node.value, node });
+        case 'link':
+            return C.link({
+                href: node.href,
+                ...(node.title ? { title: node.title } : {}),
+                children: renderInline(node.children, ctx),
+                onLink: ctx.onLink,
+                node,
+            });
+        case 'autolink':
+            return C.autolink({ href: node.href, value: node.value, onLink: ctx.onLink, node });
+        case 'image':
+            return C.image({
+                src: node.src,
+                alt: node.alt,
+                ...(node.title ? { title: node.title } : {}),
+                onImageTap: ctx.onImageTap,
+                node,
+            });
+    }
+}

package/dist/stream.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `createMarkdownStream()` — a one-line bridge between an AI token loop and
+ * `<Markdown>`.
+ *
+ * It owns a reactive `value` signal and coalesces bursts of `append()` calls
+ * into a single signal write per `flushIntervalMs` window, so a fast token
+ * stream re-renders at a bounded rate instead of once per token.
+ *
+ * @example
+ * ```tsx
+ * const md = createMarkdownStream({ flushIntervalMs: 16 });
+ *
+ * // producer
+ * for await (const token of completion) md.append(token);
+ * md.done();
+ *
+ * // consumer
+ * <Markdown value={md.value.value} />
+ * ```
+ */
+import { type PrimitiveSignal } from '@sigx/lynx';
+export interface CreateMarkdownStreamOptions {
+    /**
+     * Coalesce `append()` calls within this many milliseconds into a single
+     * `value` update. `0` (default) flushes synchronously on every append.
+     * A small value such as `16` caps re-renders to ~60fps under fast streams.
+     */
+    flushIntervalMs?: number;
+}
+export interface MarkdownStream {
+    /** Reactive accumulated source. Pass to `<Markdown value={stream.value.value} />`. */
+    readonly value: PrimitiveSignal<string>;
+    /** Reactive completion flag, set by {@link MarkdownStream.done}. */
+    readonly finished: PrimitiveSignal<boolean>;
+    /** Append a token/chunk; buffered and coalesced into `value`. */
+    append(chunk: string): void;
+    /** Flush any pending buffer and mark the stream complete. */
+    done(): void;
+    /** Clear the buffer, `value`, and `finished` (e.g. for a regenerate). */
+    reset(): void;
+}
+export declare function createMarkdownStream(opts?: CreateMarkdownStreamOptions): MarkdownStream;

package/dist/stream.js

@@ -0,0 +1,69 @@
+/**
+ * `createMarkdownStream()` — a one-line bridge between an AI token loop and
+ * `<Markdown>`.
+ *
+ * It owns a reactive `value` signal and coalesces bursts of `append()` calls
+ * into a single signal write per `flushIntervalMs` window, so a fast token
+ * stream re-renders at a bounded rate instead of once per token.
+ *
+ * @example
+ * ```tsx
+ * const md = createMarkdownStream({ flushIntervalMs: 16 });
+ *
+ * // producer
+ * for await (const token of completion) md.append(token);
+ * md.done();
+ *
+ * // consumer
+ * <Markdown value={md.value.value} />
+ * ```
+ */
+import { signal } from '@sigx/lynx';
+export function createMarkdownStream(opts) {
+    const flushIntervalMs = opts?.flushIntervalMs ?? 0;
+    const value = signal('');
+    const finished = signal(false);
+    let buffer = '';
+    let timer = null;
+    const flush = () => {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (value.value !== buffer)
+            value.value = buffer;
+    };
+    const schedule = () => {
+        if (flushIntervalMs <= 0) {
+            flush();
+            return;
+        }
+        if (timer === null)
+            timer = setTimeout(flush, flushIntervalMs);
+    };
+    return {
+        value,
+        finished,
+        append(chunk) {
+            if (!chunk)
+                return;
+            buffer += chunk;
+            if (finished.value)
+                finished.value = false;
+            schedule();
+        },
+        done() {
+            flush();
+            finished.value = true;
+        },
+        reset() {
+            if (timer !== null) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            buffer = '';
+            value.value = '';
+            finished.value = false;
+        },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sigx/lynx-markdown",
-  "version": "0.4.4",
-  "description": "Typed signalx wrapper around Lynx's <x-markdown> element. Renders markdown source via XElement/Markdown.",
+  "version": "0.4.6",
+  "description": "SignalX-native streaming markdown renderer for Lynx. Parses markdown in JS (zero deps) and renders to native <view>/<text> primitives, with incremental streaming for AI output. Also ships XMarkdown, the native <x-markdown> wrapper.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,12 +19,13 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@sigx/lynx": "^0.4.4"
+    "@sigx/lynx": "^0.4.6"
   },
   "devDependencies": {
     "@typescript/native-preview": "7.0.0-dev.20260521.1",
     "typescript": "^6.0.3",
-    "@sigx/lynx": "^0.4.4"
+    "@sigx/lynx": "^0.4.6",
+    "@sigx/lynx-testing": "^0.4.6"
   },
   "author": "Andreas Ekdahl",
   "license": "MIT",
@@ -45,11 +46,15 @@
     "sigx",
     "lynx",
     "markdown",
+    "native",
+    "streaming",
+    "ai",
     "x-markdown"
   ],
   "scripts": {
     "build": "node ../../scripts/clean.mjs dist && tsgo",
     "dev": "tsgo --watch",
+    "test": "vitest run",
     "clean": "node ../../scripts/clean.mjs dist .turbo"
   }
 }

package/dist/Markdown.d.ts

@@ -1,30 +0,0 @@
-import { type Define } from '@sigx/lynx';
-import './jsx-augment.js';
-import type { MarkdownLinkEvent, MarkdownImageTapEvent, MarkdownParseEndEvent } from './jsx-augment.js';
-export type MarkdownEffect = 'typewriter' | 'none' | (string & {});
-export type MarkdownProps = Define.Prop<'value', string, false> & Define.Prop<'effect', MarkdownEffect, false> & Define.Prop<'attachments', ReadonlyArray<unknown>, false> & Define.Prop<'class', string, false> & Define.Prop<'style', string | Record<string, string | number>, false> & Define.Prop<'onLink', (e: MarkdownLinkEvent) => void, false> & Define.Prop<'onImageTap', (e: MarkdownImageTapEvent) => void, false> & Define.Prop<'onParseEnd', (e: MarkdownParseEndEvent) => void, false>;
-/**
- * Render a markdown document using Lynx's `<x-markdown>` XElement.
- *
- * The markdown source is passed via the `value` prop; it is delivered to the
- * native element as a raw-text child (per the 3.7.0 "raw-text node
- * optimization" path). Event props use signalx's automatic
- * `onLink`→`bindlink` mapping in `nodeOps.parseEventProp`, so handlers wire
- * up without any per-event glue.
- *
- * @example
- * ```tsx
- * <Markdown
- *   value={"# Hello\n\nThis is **markdown**."}
- *   effect="typewriter"
- *   onLink={(e) => console.log('tapped', e.detail.url)}
- * />
- * ```
- *
- * @remarks
- * Availability of the `<x-markdown>` element is platform-dependent — see
- * `jsx-augment.ts` for the per-platform schedule. On platforms where the
- * native element is not registered, the engine logs a warning and renders
- * no view; there is no JS-side feature gate.
- */
-export declare const Markdown: import("@sigx/runtime-core").ComponentFactory<MarkdownProps, void, {}>;