@sigx/lynx-markdown 0.4.5 → 0.4.7

package/README.md

@@ -1,26 +1,17 @@
 # @sigx/lynx-markdown
 
-Typed SignalX wrapper around Lynx's `<x-markdown>` XElement.
+A **SignalX-native, streaming-aware markdown renderer** for Lynx.
 
-## Status
+It parses markdown in JavaScript (zero dependencies) and renders to native Lynx
+`<view>`/`<text>`/`<image>` primitives — so it renders **identically on every
+platform** (iOS, Android, Harmony) and is fully controllable from JS. Built for
+AI output: as the source string grows token-by-token, finalized blocks keep a
+stable identity and are never re-parsed or remounted, so completed content
+doesn't flicker or reflow while new tokens stream in.
 
-**Pre-release** — the wrapper compiles and types cleanly today, but the
-underlying native element ships per-platform on different schedules:
-
-| Platform | First version  | Notes                                          |
-| -------- | -------------- | ---------------------------------------------- |
-| Harmony  | Lynx 3.7.0     | Stable.                                        |
-| Android  | Lynx 3.8.0-rc.0 | Ships as `org.lynxsdk.lynx:lynx_xelement_markdown`. |
-| iOS      | (post-3.8.0)   | Currently only on the upstream `main` branch.  |
-
-On platforms where `<x-markdown>` is not yet registered, the component
-renders nothing at runtime. This package exists so that app code can
-already adopt the typed API surface — once you bump SignalX's Lynx pins
-to a release that includes the native element on your target platforms,
-it starts rendering without code changes.
-
-When the iOS/Android pods land in stable, this README will be updated
-with the matching native dependency wiring (Podfile + gradle).
+The package also ships [`XMarkdown`](#xmarkdown--native-element-wrapper), the
+thin wrapper around Lynx's native `<x-markdown>` element, for cases where you
+want the platform's built-in renderer.
 
 ## Install
 
@@ -31,41 +22,120 @@ pnpm add @sigx/lynx-markdown
 ## Use
 
 ```tsx
-import { Markdown } from '@sigx/lynx-markdown';
+import { MarkdownView } from '@sigx/lynx-markdown';
 
 export default function ArticleScreen() {
   return (
-    <Markdown
-      value={"# Hello\n\nThis is **markdown**."}
-      effect="typewriter"
-      onLink={(e) => console.log('tapped', e.detail.url)}
-      onParseEnd={() => console.log('parsed')}
+    <MarkdownView
+      value={'# Hello\n\nThis is **markdown** with a [link](https://signalx.dev).'}
+      onLink={(href) => openUrl(href)}
     />
   );
 }
 ```
 
-## Props
+### Streaming AI output
+
+`createMarkdownStream()` bridges a token loop to `<MarkdownView>` in one line. It
+owns a reactive `value` signal and coalesces bursts of tokens into a bounded
+number of re-renders.
+
+```tsx
+import { MarkdownView, createMarkdownStream } from '@sigx/lynx-markdown';
+
+const md = createMarkdownStream({ flushIntervalMs: 16 }); // ~60fps cap
+
+// producer — your AI completion loop
+for await (const token of completion) md.append(token);
+md.done();
+
+// consumer
+<MarkdownView value={md.value.value} />;
+```
+
+`MarkdownStream` API:
+
+| Member             | Description                                              |
+| ------------------ | ------------------------------------------------------- |
+| `value`            | Reactive accumulated source (`PrimitiveSignal<string>`).|
+| `finished`         | Reactive flag, set by `done()`.                         |
+| `append(chunk)`    | Append a token/chunk; buffered + coalesced into `value`.|
+| `done()`           | Flush the buffer and mark complete.                     |
+| `reset()`          | Clear buffer/`value`/`finished` (e.g. for a regenerate).|
+
+## Supported syntax
+
+Core CommonMark + GFM:
+
+- Headings (`#`…`######`)
+- Paragraphs with soft-wrap joining
+- **Bold**, _italic_, ~~strikethrough~~, `inline code`
+- Links, images, angle (`<url>`) and bare (`https://…`, `www.…`) autolinks
+- Ordered and unordered nested lists, GFM task lists (`- [ ]` / `- [x]`)
+- Blockquotes (with nested blocks)
+- Fenced code blocks (with language label); unterminated fences render while
+  streaming and close cleanly when the final fence arrives
+- Thematic breaks (`---`, `***`, `___`)
+- GFM tables with per-column alignment
+
+Not supported (renders as literal text): raw HTML, reference-style links,
+setext headings, syntax highlighting. Link hrefs are sanitized — only
+`http(s):`, `mailto:`, `tel:` and scheme-less links are exposed to `onLink`;
+`javascript:`/`data:` collapse to `#`.
+
+### `<MarkdownView>` props
+
+| Prop          | Type                          | Description                                  |
+| ------------- | ----------------------------- | -------------------------------------------- |
+| `value`       | `string`                      | Markdown source (reactive).                  |
+| `onLink`      | `(href: string) => void`      | Fired when a link/autolink is tapped.        |
+| `onImageTap`  | `(src: string) => void`       | Fired when an image is tapped.               |
+| `components`  | `Partial<MarkdownComponents>` | Per-node-type render-function overrides.     |
+
+### Theming with `components`
+
+`MarkdownView` is **design-system agnostic**: it ships neutral, theme-agnostic
+defaults and walks the AST calling a render function per node type. Override any
+subset to control the element, styling, and layout — the engine pre-renders each
+node's `children` and keeps the stable streaming keys regardless of what you
+return.
 
-| Prop          | Type                                    | Notes                                               |
-| ------------- | --------------------------------------- | --------------------------------------------------- |
-| `value`       | `string`                                | Markdown source passed as a raw-text child.         |
-| `effect`      | `'typewriter' \| 'none' \| string`      | Maps to the `markdown-effect` attribute.            |
-| `attachments` | `ReadonlyArray<unknown>`                | Maps to `text-mark-attachments`. Engine-defined.    |
-| `class`       | `string`                                |                                                      |
-| `style`       | `string \| Record<string, ...>`         |                                                      |
-| `onLink`      | `(e: MarkdownLinkEvent) => void`        | Underlying `bindlink`.                              |
-| `onImageTap`  | `(e: MarkdownImageTapEvent) => void`    | Underlying `bindimageTap`.                          |
-| `onParseEnd`  | `(e: MarkdownParseEndEvent) => void`    | Underlying `bindparseEnd`.                          |
+```tsx
+<MarkdownView
+  value={src}
+  components={{
+    heading: ({ level, children }) => <Heading level={level}>{children}</Heading>,
+    strong: ({ children }) => <text class="font-bold">{children}</text>,
+  }}
+/>
+```
+
+For a ready-made daisyUI mapping, pass `markdownComponents` from
+`@sigx/lynx-daisyui`:
+
+```tsx
+import { MarkdownView } from '@sigx/lynx-markdown';
+import { markdownComponents } from '@sigx/lynx-daisyui';
+
+<MarkdownView value={src} components={markdownComponents} />;
+```
+
+## `XMarkdown` — native element wrapper
+
+`XMarkdown` wraps Lynx's native `<x-markdown>` XElement. It's fast where
+available but platform-gated and opaque (the engine owns parsing and styling):
 
-## Native element methods
+| Platform | First version   | Notes                                               |
+| -------- | --------------- | --------------------------------------------------- |
+| Harmony  | Lynx 3.7.0      | Stable.                                             |
+| Android  | Lynx 3.8.0-rc.0 | Ships as `org.lynxsdk.lynx:lynx_xelement_markdown`. |
+| iOS      | (post-3.8.0)    | Currently only on the upstream `main` branch.       |
 
-The underlying `<x-markdown>` exposes UI methods you can invoke via a
-`main-thread:ref`:
+On platforms where `<x-markdown>` is not registered, it renders nothing. Prefer
+`MarkdownView` for cross-platform, streaming, and customizable rendering.
 
-- `getContent`, `getParseResult`, `getImages`
-- `pauseAnimation`, `resumeAnimation`, `clearStatus`
-- `getTextBoundingRect`, `setTextSelection`, `getSelectedText`
+```tsx
+import { XMarkdown } from '@sigx/lynx-markdown';
 
-These are not yet wrapped by the component; drop down to the intrinsic
-`<x-markdown>` element with a ref to call them directly.
+<XMarkdown value={'# Hello'} effect="typewriter" onLink={(e) => open(e.detail.url)} />;
+```

package/dist/XMarkdown.d.ts

@@ -0,0 +1,36 @@
+import { type Define } from '@sigx/lynx';
+import './jsx-augment.js';
+import type { MarkdownLinkEvent, MarkdownImageTapEvent, MarkdownParseEndEvent } from './jsx-augment.js';
+export type XMarkdownEffect = 'typewriter' | 'none' | (string & {});
+export type XMarkdownProps = Define.Prop<'value', string, false> & Define.Prop<'effect', XMarkdownEffect, 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 native `<x-markdown>` XElement.
+ *
+ * This is the thin wrapper over the platform's native markdown element. It is
+ * fast where available but platform-gated (Harmony 3.7.0+, Android 3.8.0-rc.0+,
+ * iOS not yet in a tagged release) and opaque — the engine owns parsing and
+ * styling. For a cross-platform, fully-controllable, streaming-aware renderer
+ * built on Lynx `<view>`/`<text>` primitives, use {@link Markdown} instead.
+ *
+ * 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
+ * <XMarkdown
+ *   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 XMarkdown: import("@sigx/runtime-core").ComponentFactory<XMarkdownProps, void, {}>;

package/dist/{Markdown.js → XMarkdown.js}

@@ -2,7 +2,13 @@ import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
 import { component } from '@sigx/lynx';
 import './jsx-augment.js';
 /**
- * Render a markdown document using Lynx's `<x-markdown>` XElement.
+ * Render a markdown document using Lynx's native `<x-markdown>` XElement.
+ *
+ * This is the thin wrapper over the platform's native markdown element. It is
+ * fast where available but platform-gated (Harmony 3.7.0+, Android 3.8.0-rc.0+,
+ * iOS not yet in a tagged release) and opaque — the engine owns parsing and
+ * styling. For a cross-platform, fully-controllable, streaming-aware renderer
+ * built on Lynx `<view>`/`<text>` primitives, use {@link Markdown} instead.
  *
  * 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
@@ -12,7 +18,7 @@ import './jsx-augment.js';
  *
  * @example
  * ```tsx
- * <Markdown
+ * <XMarkdown
  *   value={"# Hello\n\nThis is **markdown**."}
  *   effect="typewriter"
  *   onLink={(e) => console.log('tapped', e.detail.url)}
@@ -25,6 +31,6 @@ import './jsx-augment.js';
  * native element is not registered, the engine logs a warning and renders
  * no view; there is no JS-side feature gate.
  */
-export const Markdown = component(({ props }) => {
+export const XMarkdown = component(({ props }) => {
     return () => (_jsx("x-markdown", { "markdown-effect": props.effect, "text-mark-attachments": props.attachments, class: props.class, style: props.style, bindlink: props.onLink, bindimageTap: props.onImageTap, bindparseEnd: props.onParseEnd, children: props.value ?? '' }));
 });

package/dist/ast.d.ts

@@ -0,0 +1,117 @@
+/**
+ * AST node types for the SignalX-native markdown renderer.
+ *
+ * The tree is intentionally small and flat: the parser produces it, the render
+ * layer maps it to Lynx `<view>`/`<text>`/`<image>` intrinsics, and the
+ * incremental engine memoizes finalized {@link BlockNode}s by reference. Every
+ * block carries a `key` (assigned by the incremental layer for stable
+ * reconciliation) and `raw` (the exact source slice, used for memo equality and
+ * introspection).
+ */
+export type InlineNode = InlineText | InlineStrong | InlineEm | InlineDel | InlineCodeSpan | InlineLink | InlineImage | InlineAutolink | InlineBreak;
+/** A run of literal text. */
+export interface InlineText {
+    type: 'text';
+    value: string;
+}
+/** `**bold**` / `__bold__`. */
+export interface InlineStrong {
+    type: 'strong';
+    children: InlineNode[];
+}
+/** `*italic*` / `_italic_`. */
+export interface InlineEm {
+    type: 'em';
+    children: InlineNode[];
+}
+/** GFM `~~strikethrough~~`. */
+export interface InlineDel {
+    type: 'del';
+    children: InlineNode[];
+}
+/** `` `code` `` — content is literal (no nested inline parsing). */
+export interface InlineCodeSpan {
+    type: 'codeSpan';
+    value: string;
+}
+/** `[text](href "title")`. */
+export interface InlineLink {
+    type: 'link';
+    href: string;
+    title?: string;
+    children: InlineNode[];
+}
+/** `![alt](src "title")`. */
+export interface InlineImage {
+    type: 'image';
+    src: string;
+    alt: string;
+    title?: string;
+}
+/** `<https://…>` / `<email>` / GFM bare-URL autolink. */
+export interface InlineAutolink {
+    type: 'autolink';
+    href: string;
+    value: string;
+}
+/** A hard line break (two trailing spaces or a trailing backslash). */
+export interface InlineBreak {
+    type: 'br';
+}
+export interface BlockBase {
+    /** Stable reconciliation key, assigned by the incremental engine. */
+    key: string;
+    /** Exact source slice this block was parsed from. */
+    raw: string;
+}
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export type TableAlign = 'left' | 'center' | 'right';
+export type BlockNode = HeadingBlock | ParagraphBlock | BlockquoteBlock | ListBlock | CodeBlock | ThematicBreakBlock | TableBlock;
+export interface HeadingBlock extends BlockBase {
+    type: 'heading';
+    level: HeadingLevel;
+    children: InlineNode[];
+}
+export interface ParagraphBlock extends BlockBase {
+    type: 'paragraph';
+    children: InlineNode[];
+}
+export interface BlockquoteBlock extends BlockBase {
+    type: 'blockquote';
+    children: BlockNode[];
+}
+export interface ListBlock extends BlockBase {
+    type: 'list';
+    ordered: boolean;
+    /** Starting number for ordered lists (1 for unordered). */
+    start: number;
+    /** Tight lists have no blank lines between items → tighter spacing. */
+    tight: boolean;
+    items: ListItem[];
+}
+export interface ListItem {
+    key: string;
+    /** GFM task list state: `true`/`false`, or `null` when not a task item. */
+    checked: boolean | null;
+    children: BlockNode[];
+}
+export interface CodeBlock extends BlockBase {
+    type: 'codeBlock';
+    lang?: string;
+    value: string;
+    /** `false` while the fence is still open (streaming, or unterminated). */
+    closed: boolean;
+}
+export interface ThematicBreakBlock extends BlockBase {
+    type: 'thematicBreak';
+}
+export interface TableBlock extends BlockBase {
+    type: 'table';
+    /** Per-column alignment; `null` = default (left). */
+    align: (TableAlign | null)[];
+    header: TableCell[];
+    rows: TableCell[][];
+}
+export interface TableCell {
+    children: InlineNode[];
+}

package/dist/ast.js

@@ -0,0 +1,11 @@
+/**
+ * AST node types for the SignalX-native markdown renderer.
+ *
+ * The tree is intentionally small and flat: the parser produces it, the render
+ * layer maps it to Lynx `<view>`/`<text>`/`<image>` intrinsics, and the
+ * incremental engine memoizes finalized {@link BlockNode}s by reference. Every
+ * block carries a `key` (assigned by the incremental layer for stable
+ * reconciliation) and `raw` (the exact source slice, used for memo equality and
+ * introspection).
+ */
+export {};

package/dist/index.d.ts

@@ -1,4 +1,15 @@
 import './jsx-augment.js';
-export { Markdown } from './Markdown.js';
-export type { MarkdownProps, MarkdownEffect } from './Markdown.js';
+export { MarkdownView } from './render/MarkdownView.js';
+export type { MarkdownViewProps } from './render/MarkdownView.js';
+export { defaultComponents } from './render/components.js';
+export type { MarkdownComponents, MarkdownChild, RootProps, HeadingProps, ParagraphProps, BlockquoteProps, ListProps, ListItemProps, CodeProps, ThematicBreakProps, TableProps, TableRowProps, TableCellProps, StrongProps, EmProps, DelProps, CodeSpanProps, LinkProps, AutolinkProps, ImageProps, } from './render/components.js';
+export { createMarkdownStream } from './stream.js';
+export type { MarkdownStream, CreateMarkdownStreamOptions } from './stream.js';
+export { XMarkdown } from './XMarkdown.js';
+export type { XMarkdownProps, XMarkdownEffect } from './XMarkdown.js';
+export { createIncrementalEngine } from './parser/incremental.js';
+export type { IncrementalEngine } from './parser/incremental.js';
+export { parseBlocks } from './parser/blocks.js';
+export { parseInline } from './parser/inline.js';
+export type * from './ast.js';
 export type { XMarkdownAttributes, MarkdownLinkEvent, MarkdownLinkEventDetail, MarkdownImageTapEvent, MarkdownImageTapEventDetail, MarkdownParseEndEvent, MarkdownParseEndEventDetail, } from './jsx-augment.js';

package/dist/index.js

@@ -1,2 +1,14 @@
 import './jsx-augment.js';
-export { Markdown } from './Markdown.js';
+// Primary: the SignalX-native streaming renderer. (An editable `MarkdownEditor`
+// is planned as a sibling export.)
+export { MarkdownView } from './render/MarkdownView.js';
+// Generic render-function override API (design systems plug in here).
+export { defaultComponents } from './render/components.js';
+// Streaming controller for AI token loops.
+export { createMarkdownStream } from './stream.js';
+// Native `<x-markdown>` wrapper, preserved for platforms that ship the element.
+export { XMarkdown } from './XMarkdown.js';
+// Parser primitives (for advanced consumers / testing).
+export { createIncrementalEngine } from './parser/incremental.js';
+export { parseBlocks } from './parser/blocks.js';
+export { parseInline } from './parser/inline.js';

package/dist/parser/blocks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Block-level parser: source → `BlockNode[]`.
+ *
+ * Line-oriented with a small open-container model. The key streaming-safety
+ * rule lives here: a blank line only separates blocks at the top level and
+ * *outside* an open fenced code block — a blank line inside ``` does not close
+ * it. An unterminated fence parses as a `codeBlock` with `closed: false` and is
+ * still rendered, so streaming code dumps don't flicker when the closing fence
+ * finally arrives.
+ *
+ * Keys are assigned by the caller through a `KeyGen` so nested blocks (list
+ * items, blockquote contents) get stable, unique keys for reconciliation.
+ */
+import type { BlockNode } from '../ast.js';
+/** Monotonic key generator so every block (incl. nested) gets a unique key. */
+export interface KeyGen {
+    next(): string;
+}
+export declare function makeKeyGen(prefix: string): KeyGen;
+/** Parse a complete (or partial) source string into block nodes. */
+export declare function parseBlocks(src: string, keys?: KeyGen): BlockNode[];