@fuzdev/mdz 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/mdz",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "a strict markdown dialect built for streaming, Svelte authoring, docs websites, and untrusted content",
   "tagline": "markdown for fuz",
   "glyph": "📝",
@@ -57,17 +57,17 @@
   },
   "devDependencies": {
     "@fuzdev/blake3_wasm": "^0.1.1",
-    "@fuzdev/fuz_code": "^0.46.0",
-    "@fuzdev/fuz_css": "^0.62.0",
-    "@fuzdev/fuz_ui": "^0.204.0",
+    "@fuzdev/fuz_code": "^0.46.1",
+    "@fuzdev/fuz_css": "^0.63.2",
+    "@fuzdev/fuz_ui": "^0.205.1",
     "@fuzdev/fuz_util": "^0.65.1",
-    "@fuzdev/gro": "^0.204.0",
+    "@fuzdev/gro": "^0.205.1",
     "@ryanatkn/eslint-config": "^0.12.1",
     "@sveltejs/acorn-typescript": "^1.0.10",
     "@sveltejs/adapter-static": "^3.0.10",
-    "@sveltejs/kit": "^2.65.0",
+    "@sveltejs/kit": "2.64.0",
     "@sveltejs/package": "^2.5.7",
-    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "@types/estree": "^1.0.8",
     "@types/node": "^24.12.4",
     "@webref/css": "^8.2.0",
@@ -83,7 +83,7 @@
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.1",
-    "vite": "^7.3.1",
+    "vite": "^8.0.16",
     "vitest": "^4.0.15"
   },
   "prettier": {

package/src/lib/context_helpers.ts

@@ -14,7 +14,7 @@ import {getContext, setContext} from 'svelte';
  * If a `fallback` is provided, the `value` argument to `set` is optional
  * and `get_maybe` is omitted from the type.
  *
- * Vendored from `@fuzdev/fuz_ui/context_helpers.js` — fuz_ui sits above mdz
+ * Vendored from `@fuzdev/fuz_ui/context_helpers.ts` — fuz_ui sits above mdz
  * in the dependency graph, so mdz keeps its own copy for `mdz_contexts.ts`.
  * Consumers should import fuz_ui's.
  *

package/src/lib/mdz.ts

@@ -19,7 +19,7 @@
  * - inline code in backticks (creates `Code` nodes; auto-linking to identifiers/modules
  *   is handled by the rendering layer via `MdzNodeView.svelte`)
  * - paragraph breaks (blank lines)
- * - block elements: headings, horizontal rules, lists, blockquotes, code blocks
+ * - block elements: headings, horizontal rules, lists, blockquotes, code blocks, tables
  * - HTML elements and Svelte components (opt-in via context)
  *
  * Whitespace: the parser preserves whitespace in text node content (single
@@ -50,8 +50,8 @@
  * @module
  */
 
-import {MdzLexer} from './mdz_lexer.js';
-import {MdzTokenParser} from './mdz_token_parser.js';
+import {MdzLexer} from './mdz_lexer.ts';
+import {MdzTokenParser} from './mdz_token_parser.ts';
 
 // TODO design incremental parsing or some system that preserves Svelte components across re-renders when possible
 
@@ -64,6 +64,37 @@ import {MdzTokenParser} from './mdz_token_parser.js';
 export const mdz_parse = (text: string): Array<MdzNode> =>
 	new MdzTokenParser(new MdzLexer(text).tokenize()).parse();
 
+/**
+ * Parses table cells' inline content for the streaming parser, sharing one
+ * `MdzLexer` + `MdzTokenParser` across a row's cells rather than allocating a
+ * fresh pair (and search-memo `Map`) per cell. Bind to the buffer holding the
+ * row, then call `parse` once per cell `[cell_start, cell_end)` span; each
+ * call yields inline `MdzNode`s honoring code-span protection and the `\|`
+ * escape, matching the sync reference exactly — it *is* the sync lexer/parser,
+ * reset per cell, mirroring how the sync lexer already reuses one instance
+ * across a table's cells.
+ *
+ * The sync pipeline never needs this seam: its `MdzLexer` tokenizes a table's
+ * cells in place. Only the streaming path, which parses each fully-buffered
+ * cell out of band, would otherwise allocate per cell.
+ *
+ * @nodocs
+ */
+export class MdzTableCellParser {
+	#lexer: MdzLexer;
+	#parser: MdzTokenParser = new MdzTokenParser([]);
+
+	/** @param text - the buffer the cell spans index into (stable across a row). */
+	constructor(text: string) {
+		this.#lexer = new MdzLexer(text);
+	}
+
+	parse(cell_start: number, cell_end: number): Array<MdzNode> {
+		this.#parser.reset(this.#lexer.lex_table_cell(cell_start, cell_end));
+		return this.#parser.parse_inline_run();
+	}
+}
+
 export type MdzNode =
 	| MdzNodeText
 	| MdzNodeCode
@@ -78,6 +109,9 @@ export type MdzNode =
 	| MdzNodeList
 	| MdzNodeListItem
 	| MdzNodeBlockquote
+	| MdzNodeTable
+	| MdzNodeTableRow
+	| MdzNodeTableCell
 	| MdzNodeElement
 	| MdzNodeComponent;
 
@@ -175,6 +209,39 @@ export interface MdzNodeBlockquote extends MdzNodeBase {
 	children: Array<MdzNode>;
 }
 
+/** Per-column text alignment from the delimiter row's colons; `null` is the default (no alignment). */
+export type MdzTableAlign = 'left' | 'center' | 'right' | null;
+
+export interface MdzNodeTable extends MdzNodeBase {
+	type: 'Table';
+	/**
+	 * Per-column alignment, length equal to the delimiter row's column count.
+	 * Rendered as `text-align` on each cell; tooling can read it to re-theme
+	 * (e.g. a CSP-strict consumer that avoids inline styles).
+	 */
+	align: Array<MdzTableAlign>;
+	/** The header row first, then any body rows. */
+	children: Array<MdzNodeTableRow>;
+}
+
+export interface MdzNodeTableRow extends MdzNodeBase {
+	type: 'TableRow';
+	/** `true` for the header row (renders `thead`/`th`); `false` for body rows (`tbody`/`td`). */
+	header: boolean;
+	/**
+	 * The row's authored cells, preserved as written. The renderer normalizes to
+	 * the column count: short rows are padded with empty cells, cells past the
+	 * column count are ignored (their content survives here for tooling).
+	 */
+	children: Array<MdzNodeTableCell>;
+}
+
+export interface MdzNodeTableCell extends MdzNodeBase {
+	type: 'TableCell';
+	/** Inline content only (text, bold, italic, strikethrough, code, links). */
+	children: Array<MdzNode>;
+}
+
 export interface MdzNodeElement extends MdzNodeBase {
 	type: 'Element';
 	/** HTML element name (e.g. `div`, `span`, `aside`). */

package/src/lib/mdz_contexts.ts

@@ -1,6 +1,6 @@
 import type {Component} from 'svelte';
 
-import {create_context} from './context_helpers.js';
+import {create_context} from './context_helpers.ts';
 
 /**
  * Component registry for custom Svelte components that can be used in mdz content.

package/src/lib/mdz_helpers.ts

@@ -7,7 +7,7 @@
  * @module
  */
 
-import type {MdzNode, MdzNodeText, MdzNodeComponent, MdzNodeElement} from './mdz.js';
+import type {MdzNode, MdzNodeText, MdzNodeComponent, MdzNodeElement, MdzTableAlign} from './mdz.ts';
 
 // Character codes for performance
 /** @nodocs */
@@ -47,6 +47,10 @@ export const RIGHT_PAREN = 41; // )
 /** @nodocs */
 export const COLON = 58; // :
 /** @nodocs */
+export const PIPE = 124; // |
+/** @nodocs */
+export const BACKSLASH = 92; // \
+/** @nodocs */
 export const PERIOD = 46; // .
 /** @nodocs */
 export const COMMA = 44; // ,
@@ -287,6 +291,126 @@ export const mdz_remap_segments = (
 	return seg.source_start + (p - seg.inner_start);
 };
 
+// -- Table helpers --
+
+/** Trim line-whitespace from both ends of a `[start, end)` span. */
+const trim_table_cell = (
+	text: string,
+	start: number,
+	end: number,
+): {start: number; end: number} => {
+	let s = start;
+	let e = end;
+	while (s < e && is_line_whitespace(text.charCodeAt(s))) s++;
+	while (e > s && is_line_whitespace(text.charCodeAt(e - 1))) e--;
+	return {start: s, end: e};
+};
+
+/**
+ * Split a table row line `[line_start, line_end)` into its cell-content spans.
+ *
+ * A valid row starts with `|` and ends — after optional trailing whitespace —
+ * with `|`, yielding at least one cell. Returns each cell's trimmed
+ * `[start, end)` source span, or `null` when the line is not a valid pipe row
+ * (no leading `|`, no trailing `|`, or zero cells).
+ *
+ * Pipe-finding honors two protections so the cell content can hold a literal
+ * `|`: an inline-code span (a `` ` `` to its matching `` ` `` on the same line —
+ * an unclosed `` ` `` is literal and protects nothing) shields the pipes inside
+ * it, and a `\|` escape is consumed as a literal pipe. The escape is
+ * table-cell-scoped — the caller's inline tokenizer performs the matching
+ * `\|` → `|` substitution; this scanner only declines to split there.
+ *
+ * @nodocs
+ */
+export const mdz_split_table_row = (
+	text: string,
+	line_start: number,
+	line_end: number,
+): Array<{start: number; end: number}> | null => {
+	if (line_start >= line_end || text.charCodeAt(line_start) !== PIPE) return null;
+	const cells: Array<{start: number; end: number}> = [];
+	let i = line_start + 1; // past the leading pipe
+	let cell_start = i;
+	while (i < line_end) {
+		const char_code = text.charCodeAt(i);
+		if (char_code === BACKTICK) {
+			// inline-code span: skip to the matching backtick; unclosed → literal
+			let close = -1;
+			for (let k = i + 1; k < line_end; k++) {
+				if (text.charCodeAt(k) === BACKTICK) {
+					close = k;
+					break;
+				}
+			}
+			if (close === -1) {
+				i++;
+			} else {
+				i = close + 1;
+			}
+			continue;
+		}
+		if (char_code === BACKSLASH) {
+			// `\|` is a literal pipe, never a delimiter
+			i += i + 1 < line_end && text.charCodeAt(i + 1) === PIPE ? 2 : 1;
+			continue;
+		}
+		if (char_code === PIPE) {
+			cells.push(trim_table_cell(text, cell_start, i));
+			i++;
+			cell_start = i;
+			continue;
+		}
+		i++;
+	}
+	// the trailing pipe is required: only whitespace may follow the last one
+	for (let k = cell_start; k < line_end; k++) {
+		if (!is_line_whitespace(text.charCodeAt(k))) return null;
+	}
+	if (cells.length === 0) return null;
+	return cells;
+};
+
+/** Classify a trimmed delimiter cell `[start, end)`; `false` when it is not a valid delimiter cell. */
+const table_delimiter_align = (text: string, start: number, end: number): MdzTableAlign | false => {
+	let i = start;
+	let j = end;
+	if (i >= j) return false;
+	const left = text.charCodeAt(i) === COLON;
+	if (left) i++;
+	const right = j > i && text.charCodeAt(j - 1) === COLON;
+	if (right) j--;
+	if (i >= j) return false; // needs at least one dash
+	for (let k = i; k < j; k++) {
+		if (text.charCodeAt(k) !== HYPHEN) return false;
+	}
+	return left && right ? 'center' : left ? 'left' : right ? 'right' : null;
+};
+
+/**
+ * Parse a table delimiter row (`| --- | :-: | ---: |`) into its per-column
+ * alignment, or `null` when the line is not a valid delimiter row. Each cell
+ * must be an optional leading `:`, one or more `-`, and an optional trailing
+ * `:`. Splits with `mdz_split_table_row` so the column count matches the header.
+ *
+ * @nodocs
+ */
+export const mdz_parse_table_delimiter = (
+	text: string,
+	line_start: number,
+	line_end: number,
+): Array<MdzTableAlign> | null => {
+	const cells = mdz_split_table_row(text, line_start, line_end);
+	if (cells === null) return null;
+	const align: Array<MdzTableAlign> = [];
+	for (const cell of cells) {
+		const a = table_delimiter_align(text, cell.start, cell.end);
+		if (a === false) return null;
+		align.push(a);
+	}
+	return align;
+};
+
 /**
  * Lowercase an ASCII letter code; passes other chars through.
  * Mirrors the `[A-Z] → [a-z]` shift without touching non-ASCII.

package/src/lib/mdz_lexer.ts

@@ -47,7 +47,13 @@ import {
 	mdz_blockquote_line_has_content,
 	mdz_blockquote_strip_width,
 	mdz_remap_segments,
-} from './mdz_helpers.js';
+	mdz_split_table_row,
+	mdz_parse_table_delimiter,
+	PIPE,
+	BACKSLASH,
+} from './mdz_helpers.ts';
+
+import type {MdzTableAlign} from './mdz.ts';
 
 //
 // Token types
@@ -84,7 +90,13 @@ export type MdzToken =
 	| MdzTokenListItemOpen
 	| MdzTokenListItemClose
 	| MdzTokenBlockquoteOpen
-	| MdzTokenBlockquoteClose;
+	| MdzTokenBlockquoteClose
+	| MdzTokenTableOpen
+	| MdzTokenTableClose
+	| MdzTokenTableRowOpen
+	| MdzTokenTableRowClose
+	| MdzTokenTableCellOpen
+	| MdzTokenTableCellClose;
 
 export interface MdzTokenText extends MdzTokenBase {
 	type: 'text';
@@ -207,6 +219,34 @@ export interface MdzTokenBlockquoteClose extends MdzTokenBase {
 	type: 'blockquote_close';
 }
 
+export interface MdzTokenTableOpen extends MdzTokenBase {
+	type: 'table_open';
+	/** Per-column alignment from the delimiter row; length is the column count. */
+	align: Array<MdzTableAlign>;
+}
+
+export interface MdzTokenTableClose extends MdzTokenBase {
+	type: 'table_close';
+}
+
+export interface MdzTokenTableRowOpen extends MdzTokenBase {
+	type: 'table_row_open';
+	/** `true` for the header row, `false` for body rows. */
+	header: boolean;
+}
+
+export interface MdzTokenTableRowClose extends MdzTokenBase {
+	type: 'table_row_close';
+}
+
+export interface MdzTokenTableCellOpen extends MdzTokenBase {
+	type: 'table_cell_open';
+}
+
+export interface MdzTokenTableCellClose extends MdzTokenBase {
+	type: 'table_cell_close';
+}
+
 /**
  * A matched list marker: `- ` (unordered) or `N. ` (ordered, 1-9 digits).
  * `empty` markers have nothing but whitespace after the marker — valid only
@@ -258,6 +298,12 @@ export class MdzLexer {
 	 * scanner pre-validated every line in the run as continuation).
 	 */
 	#list_run_strip: boolean = false;
+	/**
+	 * Whether `#tokenize_text` is inside a table cell: `#max_search_index` is a
+	 * hard stop (the cell's trimmed end, mid-line with no newline to halt on)
+	 * and `\|` unescapes to a literal pipe.
+	 */
+	#in_table_cell: boolean = false;
 
 	constructor(text: string) {
 		this.#text = text;
@@ -300,6 +346,7 @@ export class MdzLexer {
 				if (this.#tokenize_codeblock()) continue;
 				if (this.#tokenize_list()) continue;
 				if (this.#tokenize_blockquote()) continue;
+				if (this.#tokenize_table()) continue;
 			}
 
 			// Check for paragraph break
@@ -317,6 +364,22 @@ export class MdzLexer {
 		return this.#tokens;
 	}
 
+	/**
+	 * Tokenize a table cell's inline content `[cell_start, cell_end)` as a
+	 * bounded inline run, with no wrapping cell tokens (the bare form of
+	 * `#emit_table_cell`, sharing `#tokenize_cell_inline`). The streaming parser
+	 * reuses it across a row's cells via `MdzTableCellParser`: the token buffer
+	 * resets per call while the search memo — valid over the immutable bound
+	 * text — carries across cells (the same reuse the sync lexer does in place).
+	 *
+	 * @nodocs
+	 */
+	lex_table_cell(cell_start: number, cell_end: number): Array<MdzToken> {
+		this.#tokens = [];
+		this.#tokenize_cell_inline(cell_start, cell_end);
+		return this.#tokens;
+	}
+
 	#is_at_column_0(): boolean {
 		return this.#index === 0 || this.#text.charCodeAt(this.#index - 1) === NEWLINE;
 	}
@@ -604,6 +667,163 @@ export class MdzLexer {
 		this.#index = last_line_end;
 	}
 
+	// -- Table tokenizers --
+
+	/**
+	 * Tokenize a table starting at a column-0 pipe row, emitting
+	 * `table_open`/`table_row_open`/`table_cell_open` … structure tokens (the
+	 * header row's cells first, then each body row's). Returns false with no
+	 * side effects when the current line isn't a table: not a `| … |` row, or
+	 * not followed by a delimiter row whose column count matches the header. The
+	 * delimiter row's colons set `align`; body rows continue until a blank line,
+	 * a non-pipe-row line, or EOF.
+	 */
+	#tokenize_table(): boolean {
+		const table_start = this.#index;
+		let header_end = this.#index_of('\n', this.#index);
+		if (header_end === -1) header_end = this.#text.length;
+		const header_cells = mdz_split_table_row(this.#text, this.#index, header_end);
+		if (header_cells === null) return false;
+		if (header_end >= this.#text.length) return false; // a header needs a delimiter row beneath it
+		const delim_start = header_end + 1;
+		let delim_end = this.#index_of('\n', delim_start);
+		if (delim_end === -1) delim_end = this.#text.length;
+		const align = mdz_parse_table_delimiter(this.#text, delim_start, delim_end);
+		if (align === null || align.length !== header_cells.length) return false;
+
+		// committed — emit the table; the delimiter row is structural (not emitted)
+		this.#tokens.push({type: 'table_open', align, start: table_start, end: header_end});
+		this.#emit_table_row(header_cells, true, table_start, header_end);
+
+		this.#index = delim_end;
+		let table_end = delim_end;
+
+		// body rows: consecutive valid pipe rows, until a blank/non-row line or EOF
+		while (this.#index < this.#text.length) {
+			const row_start = this.#index + 1; // past the newline at #index
+			let row_end = this.#index_of('\n', row_start);
+			if (row_end === -1) row_end = this.#text.length;
+			const cells = mdz_split_table_row(this.#text, row_start, row_end);
+			if (cells === null) break;
+			this.#emit_table_row(cells, false, row_start, row_end);
+			this.#index = row_end;
+			table_end = row_end;
+		}
+
+		this.#tokens.push({type: 'table_close', start: table_end, end: table_end});
+		this.#skip_blank_lines();
+		return true;
+	}
+
+	/** Emit one table row's open / cell / close tokens. */
+	#emit_table_row(
+		cells: Array<{start: number; end: number}>,
+		header: boolean,
+		row_start: number,
+		row_end: number,
+	): void {
+		this.#tokens.push({type: 'table_row_open', header, start: row_start, end: row_start});
+		for (const cell of cells) {
+			this.#emit_table_cell(cell.start, cell.end);
+		}
+		this.#tokens.push({type: 'table_row_close', start: row_end, end: row_end});
+	}
+
+	/**
+	 * Emit one cell's `table_cell_open`, inline-content tokens, and
+	 * `table_cell_close`. Inline tokenization is bounded to the cell's trimmed
+	 * span via `#max_search_index`, with `#in_table_cell` set so `#tokenize_text`
+	 * stops at that bound and unescapes `\|`.
+	 */
+	#emit_table_cell(cell_start: number, cell_end: number): void {
+		this.#tokens.push({type: 'table_cell_open', start: cell_start, end: cell_start});
+		this.#tokenize_cell_inline(cell_start, cell_end);
+		this.#tokens.push({type: 'table_cell_close', start: cell_end, end: cell_end});
+	}
+
+	/**
+	 * Tokenize a cell's trimmed inline span `[cell_start, cell_end)` into the
+	 * current token buffer, bounded by `#max_search_index` with `#in_table_cell`
+	 * set so `#tokenize_text` stops at the bound and unescapes `\|`. Shared by
+	 * `#emit_table_cell` (wrapped in cell tokens) and `lex_table_cell` (bare).
+	 */
+	#tokenize_cell_inline(cell_start: number, cell_end: number): void {
+		const saved_max = this.#max_search_index;
+		this.#max_search_index = cell_end;
+		this.#in_table_cell = true;
+		this.#index = cell_start;
+		while (this.#index < cell_end) {
+			this.#tokenize_inline();
+		}
+		this.#in_table_cell = false;
+		this.#max_search_index = saved_max;
+	}
+
+	/**
+	 * Recognize an in-item table whose header row's leading `|` is at `first`
+	 * (the line's indent already skipped): a pipe row whose next line is a
+	 * delimiter row, both indented past `marker_indent` (so both stay inside the
+	 * item). Returns the parsed header/delimiter, or null. Pure — no emission.
+	 */
+	#match_item_table_head(
+		first: number,
+		marker_indent: number,
+	): {
+		header_cells: Array<{start: number; end: number}>;
+		header_end: number;
+		align: Array<MdzTableAlign>;
+		delim_end: number;
+	} | null {
+		const header_end = this.#index_of('\n', first);
+		if (header_end === -1) return null; // a header needs a delimiter line beneath it
+		const header_cells = mdz_split_table_row(this.#text, first, header_end);
+		if (header_cells === null) return null;
+		const delim_line_start = header_end + 1;
+		let dj = delim_line_start;
+		while (dj < this.#text.length && is_line_whitespace(this.#text.charCodeAt(dj))) dj++;
+		if (dj - delim_line_start <= marker_indent) return null; // delimiter dedented out of the item
+		let delim_end = this.#index_of('\n', dj);
+		if (delim_end === -1) delim_end = this.#text.length;
+		const align = mdz_parse_table_delimiter(this.#text, dj, delim_end);
+		if (align === null || align.length !== header_cells.length) return null;
+		return {header_cells, header_end, align, delim_end};
+	}
+
+	/** Whether a table opens at `first` as a block child of an item at `marker_indent`. */
+	#is_item_table_start(first: number, marker_indent: number): boolean {
+		return this.#match_item_table_head(first, marker_indent) !== null;
+	}
+
+	/**
+	 * Tokenize an in-item table at `first` (a recognized table start). Mirrors
+	 * `#tokenize_table` but per row skips the line's indent to the `|` and ends
+	 * when a row dedents to `marker_indent` or shallower, leaving `#index` at the
+	 * table's terminating newline so the list loop classifies what follows (no
+	 * `#skip_blank_lines` — the list owns blank-line containment).
+	 */
+	#tokenize_item_table(first: number, marker_indent: number): void {
+		const head = this.#match_item_table_head(first, marker_indent)!;
+		this.#tokens.push({type: 'table_open', align: head.align, start: first, end: head.header_end});
+		this.#emit_table_row(head.header_cells, true, first, head.header_end);
+		this.#index = head.delim_end;
+		let table_end = head.delim_end;
+		while (this.#index < this.#text.length) {
+			const row_line_start = this.#index + 1; // past the newline at #index
+			let rj = row_line_start;
+			while (rj < this.#text.length && is_line_whitespace(this.#text.charCodeAt(rj))) rj++;
+			if (rj - row_line_start <= marker_indent) break; // dedent ends the table
+			if (this.#text.charCodeAt(rj) !== PIPE) break;
+			let row_end = this.#index_of('\n', rj);
+			if (row_end === -1) row_end = this.#text.length;
+			const cells = mdz_split_table_row(this.#text, rj, row_end);
+			if (cells === null) break;
+			this.#emit_table_row(cells, false, rj, row_end);
+			this.#index = row_end;
+			table_end = row_end;
+		}
+		this.#tokens.push({type: 'table_close', start: table_end, end: table_end});
+	}
+
 	// -- List tokenizers --
 
 	/**
@@ -739,6 +959,23 @@ export class MdzLexer {
 				}
 			}
 
+			// a deeper pipe-row line whose next line is a delimiter becomes a
+			// table child of the item it would otherwise continue (the fence/quote
+			// precedent, but a two-line lookahead)
+			if (indent > 0 && this.#text.charCodeAt(first) === PIPE) {
+				const target_idx = this.#list_continuation_target(levels, indent);
+				if (target_idx !== -1) {
+					const marker_indent = levels[target_idx]!.indent;
+					if (this.#is_item_table_start(first, marker_indent)) {
+						while (levels.length - 1 > target_idx) {
+							this.#list_close(levels);
+						}
+						this.#tokenize_item_table(first, marker_indent);
+						continue;
+					}
+				}
+			}
+
 			// any other line deeper than an open item's marker opens a new
 			// `Paragraph` block child of that item (the item's inline run is never
 			// current here — a blank, block child, or dedent intervened)
@@ -947,6 +1184,9 @@ export class MdzLexer {
 			if (this.#text.charCodeAt(j) === RIGHT_ANGLE && this.#is_blockquote_opener(j)) {
 				return nl; // a quote opener line interrupts the run
 			}
+			if (this.#text.charCodeAt(j) === PIPE && this.#is_item_table_start(j, deepest_indent)) {
+				return nl; // a table opener (pipe row + delimiter) interrupts the run
+			}
 			i = line_start; // continuation — keep scanning
 		}
 	}
@@ -1543,6 +1783,24 @@ export class MdzLexer {
 		while (this.#index < this.#text.length) {
 			const char_code = this.#text.charCodeAt(this.#index);
 
+			// in a table cell: the trimmed cell end is a hard stop (no newline to
+			// halt on mid-line), and `\|` is a literal pipe (the only mdz escape,
+			// scoped here)
+			if (this.#in_table_cell) {
+				if (this.#index >= this.#max_search_index) break;
+				if (
+					char_code === BACKSLASH &&
+					this.#index + 1 < this.#max_search_index &&
+					this.#text.charCodeAt(this.#index + 1) === PIPE
+				) {
+					(parts ??= []).push(this.#text.slice(part_start, this.#index));
+					parts.push('|');
+					this.#index += 2;
+					part_start = this.#index;
+					continue;
+				}
+			}
+
 			// Stop at special characters
 			if (
 				char_code === BACKTICK ||
@@ -1588,7 +1846,8 @@ export class MdzLexer {
 						next_char === HYPHEN ||
 						next_char === BACKTICK ||
 						next_char === ONE ||
-						next_char === RIGHT_ANGLE
+						next_char === RIGHT_ANGLE ||
+						next_char === PIPE
 					) {
 						this.#index++; // consume the newline
 						break;

package/src/lib/mdz_opcodes.ts

@@ -12,6 +12,8 @@
  * @module
  */
 
+import type {MdzTableAlign} from './mdz.ts';
+
 /**
  * Unique monotonic identifier for each node created by the parser.
  * IDs are never reused within a parser instance.
@@ -39,7 +41,10 @@ export type MdzNodeTypeContainer =
 	| 'Element'
 	| 'Component'
 	| 'Codeblock'
-	| 'Code';
+	| 'Code'
+	| 'Table'
+	| 'TableRow'
+	| 'TableCell';
 
 /** Node types for self-contained leaf elements. */
 export type MdzNodeTypeVoid = 'Hr';
@@ -69,6 +74,10 @@ export interface MdzOpcodeOpen {
 	start_number?: number;
 	/** Authored item number. Present when `node_type` is `'ListItem'` in an ordered list. */
 	number?: number;
+	/** Per-column alignment from the delimiter row. Present when `node_type` is `'Table'`. */
+	align?: Array<MdzTableAlign>;
+	/** Whether this is the header row (`thead`/`th`). Present when `node_type` is `'TableRow'`. */
+	header?: boolean;
 }
 
 /**