@fuzdev/mdz 0.9.0 → 0.10.0

package/src/lib/mdz_helpers.ts

@@ -528,6 +528,18 @@ export const is_word_char = (char_code: number): boolean =>
 	(char_code >= A_LOWER && char_code <= Z_LOWER) ||
 	(char_code >= ZERO && char_code <= NINE);
 
+/**
+ * Whether a char next to an italic `_` blocks it from opening (the char
+ * before) or closing (the char after): a word char, or `_` itself — italic is
+ * self-opaque, so runs like `__init__` never pair. The one italic boundary
+ * predicate, shared by the lexer, the streaming parser, and the streaming
+ * auto-link span resolution.
+ *
+ * @nodocs
+ */
+export const is_italic_boundary_blocker = (char_code: number): boolean =>
+	is_word_char(char_code) || char_code === UNDERSCORE;
+
 /**
  * Lookup table for valid URI path characters per RFC 3986.
  * Replaces a 16-comparison chain with a single array access.
@@ -587,7 +599,7 @@ export const TEXT_CLASS_STOP = 1;
 export const TEXT_CLASS_NEWLINE = 2;
 /** `h`/`H` — potential URL scheme start, needs the prefix probe. @nodocs */
 export const TEXT_CLASS_URL = 4;
-/** `/` and `.` — potential path start, needs the boundary probe. @nodocs */
+/** `/` and `.` — potential path start, needs the `is_path_boundary` probe. @nodocs */
 export const TEXT_CLASS_PATH = 8;
 /** `\` — a literal-pipe escape candidate inside table cells only. @nodocs */
 export const TEXT_CLASS_BACKSLASH = 16;
@@ -611,10 +623,23 @@ export const TEXT_SCAN_CLASS: Uint8Array = (() => {
 	return t;
 })();
 
+// trailing chars that never end a URL/path reference
+const is_trailing_punctuation = (char_code: number): boolean =>
+	char_code === PERIOD ||
+	char_code === COMMA ||
+	char_code === SEMICOLON ||
+	char_code === COLON ||
+	char_code === EXCLAMATION ||
+	char_code === QUESTION ||
+	char_code === RIGHT_BRACKET;
+
 /**
- * Trim trailing punctuation from URL/path per RFC 3986 and GFM rules.
- * - Trims simple trailing: .,;:!?]
- * - Balanced logic for () only (valid in path components)
+ * Trim the trailing characters a URL/path scan consumed that read as
+ * surrounding prose rather than the reference, per GFM's autolink
+ * conventions, repeated until nothing more trims:
+ * - trailing punctuation `.,;:!?]`
+ * - an unbalanced trailing `)` (parens are valid in path components, so a
+ *   balanced `(…)` stays)
  *
  * Note on `]`: the mdz parsers (`mdz.ts`, `mdz_stream_parser_url.ts`,
  * `mdz_lexer.ts`) scan URL/path chars through `is_valid_path_char`, which
@@ -622,68 +647,111 @@ export const TEXT_SCAN_CLASS: Uint8Array = (() => {
  * The `]` branch here is for external callers using this helper directly on
  * arbitrary URL-ish input as part of the published `@fuzdev/mdz` surface.
  *
- * Optimized to avoid O(n²) string slicing - tracks end index and slices once at the end.
+ * Tracks the end index and slices once, avoiding O(n²) string slicing.
  */
 export const mdz_trim_url_punctuation = (url: string): string => {
 	let end = url.length;
+	// paren counts over the untrimmed prefix — counted once, on the first
+	// trailing `)`; the chars trimmed after that hold no parens except the
+	// trimmed `)` themselves, which decrement `close_count`
+	let open_count = -1;
+	let close_count = 0;
 
-	while (end > 0) {
-		const last_char = url.charCodeAt(end - 1);
-		if (
-			last_char === PERIOD ||
-			last_char === COMMA ||
-			last_char === SEMICOLON ||
-			last_char === COLON ||
-			last_char === EXCLAMATION ||
-			last_char === QUESTION ||
-			last_char === RIGHT_BRACKET
-		) {
-			end--;
-		} else {
-			break;
+	for (;;) {
+		while (end > 0 && is_trailing_punctuation(url.charCodeAt(end - 1))) end--;
+		if (end === 0 || url.charCodeAt(end - 1) !== RIGHT_PAREN) break;
+		if (open_count === -1) {
+			open_count = 0;
+			for (let i = 0; i < end; i++) {
+				const char = url.charCodeAt(i);
+				if (char === LEFT_PAREN) open_count++;
+				else if (char === RIGHT_PAREN) close_count++;
+			}
 		}
+		if (close_count <= open_count) break; // balanced — the `)` belongs to the reference
+		end--;
+		close_count--;
 	}
 
-	// Handle balanced parentheses ONLY (parens are valid in URI path components)
-	// Only count parens when the trimmed URL ends with ')' — otherwise the
-	// trailing-paren loop below can't trim anything.
-	if (end > 0 && url.charCodeAt(end - 1) === RIGHT_PAREN) {
-		let open_count = 0;
-		let close_count = 0;
-		for (let i = 0; i < end; i++) {
-			const char = url.charCodeAt(i);
-			if (char === LEFT_PAREN) open_count++;
-			if (char === RIGHT_PAREN) close_count++;
-		}
+	return end === url.length ? url : url.slice(0, end);
+};
 
-		// Trim unmatched trailing closing parens
-		while (end > 0 && close_count > open_count) {
-			const last_char = url.charCodeAt(end - 1);
-			if (last_char === RIGHT_PAREN) {
-				end--;
-				close_count--;
-			} else {
-				break;
+/**
+ * End of the URI-char run starting at `start` — where an auto-link scan
+ * stops, before any trailing trim. A path opened by `(` (`paren_opened`,
+ * see `is_path_boundary`) also ends before the `)` that matches that opener:
+ * a `(` inside the path raises the depth, so `(./Foo_(bar))` scans
+ * `./Foo_(bar)`.
+ *
+ * @nodocs
+ */
+export const scan_uri_chars_end = (text: string, start: number, paren_opened: boolean): number => {
+	let i = start;
+	let depth = 0;
+	while (i < text.length) {
+		const c = text.charCodeAt(i);
+		if (!is_valid_path_char(c)) break;
+		if (paren_opened) {
+			if (c === LEFT_PAREN) depth++;
+			else if (c === RIGHT_PAREN) {
+				if (depth === 0) break;
+				depth--;
 			}
 		}
+		i++;
 	}
-
-	// Return original string if no trimming, otherwise slice once
-	return end === url.length ? url : url.slice(0, end);
+	return i;
 };
 
+/**
+ * Whether an internal path reference is only its prefix (`/`, `./`, `../`)
+ * with nothing after it — such a reference never links, since a path is its
+ * prefix plus at least one URI char.
+ *
+ * @nodocs
+ */
+export const is_bare_path_prefix = (reference: string): boolean =>
+	reference === '/' || reference === './' || reference === '../';
+
+// the char code `distance` chars before `index`, or `-1` past the start of input
+const char_code_before = (text: string, index: number, distance: number): number =>
+	index >= distance ? text.charCodeAt(index - distance) : -1;
+
+/**
+ * Whether an auto-detected path (`/…`, `./…`, `../…`) may start after the
+ * given characters: at the start of input, after a space, tab, or newline, or
+ * after an opening `(` that is itself neither glued to a word char nor the
+ * `](` of markdown link syntax. The paren case covers parenthesized
+ * references like `(./foo.md)` and `(see /docs)` — a path opened by `(` ends
+ * at its matching `)` (`scan_uri_chars_end`), and an unbalanced `)` after a
+ * whitespace-opened path is trimmed by `mdz_trim_url_punctuation` — while
+ * call-shaped `foo(./bar)` and a failed link's `[text](./foo bar)` stay
+ * literal. Every other preceding character (word chars, `[`, `{`, quotes,
+ * `*`, `_`, `~`, `/`, `.`) keeps a following path literal.
+ *
+ * @param prev - the char code directly before the path, or `-1` at the start of input
+ * @param before_prev - the char code before `prev`, or `-1` at the start of input
+ * @nodocs
+ */
+export const is_path_boundary = (prev: number, before_prev: number): boolean =>
+	prev === -1 ||
+	prev === SPACE ||
+	prev === NEWLINE ||
+	prev === TAB ||
+	(prev === LEFT_PAREN && before_prev !== RIGHT_BRACKET && !is_word_char(before_prev));
+
 /**
  * Check if position in text is the start of an absolute path (starts with `/`).
- * Must be preceded by whitespace or be at the start of the string.
+ * Must sit at a path boundary (see `is_path_boundary`): start of input,
+ * whitespace, or a `(` not glued to a word or a `]`.
  * Rejects `//` (comments/protocol-relative) and slash followed by whitespace.
  *
  * @nodocs
  */
 export const is_at_absolute_path = (text: string, index: number): boolean => {
 	if (text.charCodeAt(index) !== SLASH) return false;
-	if (index > 0) {
-		const prev_char = text.charCodeAt(index - 1);
-		if (prev_char !== SPACE && prev_char !== NEWLINE && prev_char !== TAB) return false;
+	if (!is_path_boundary(char_code_before(text, index, 1), char_code_before(text, index, 2))) {
+		return false;
 	}
 	if (index + 1 >= text.length) return false;
 	const next_char = text.charCodeAt(index + 1);
@@ -692,16 +760,16 @@ export const is_at_absolute_path = (text: string, index: number): boolean => {
 
 /**
  * Check if position in text is the start of a relative path (`./` or `../`).
- * Must be preceded by whitespace or be at the start of the string.
+ * Must sit at a path boundary (see `is_path_boundary`): start of input,
+ * whitespace, or a `(` not glued to a word or a `]`.
  * Rejects prefix followed by whitespace, slash, or end of string.
  *
  * @nodocs
  */
 export const is_at_relative_path = (text: string, index: number): boolean => {
 	if (text.charCodeAt(index) !== PERIOD) return false;
-	if (index > 0) {
-		const prev_char = text.charCodeAt(index - 1);
-		if (prev_char !== SPACE && prev_char !== NEWLINE && prev_char !== TAB) return false;
+	if (!is_path_boundary(char_code_before(text, index, 1), char_code_before(text, index, 2))) {
+		return false;
 	}
 	const remaining = text.length - index;
 	// Check for ../ (at least 4 chars: ../x)

package/src/lib/mdz_lexer.ts

@@ -14,6 +14,9 @@ import {
 	is_tag_name_char,
 	is_word_char,
 	is_valid_path_char,
+	is_bare_path_prefix,
+	is_italic_boundary_blocker,
+	scan_uri_chars_end,
 	mdz_trim_url_punctuation,
 	BACKTICK,
 	ASTERISK,
@@ -2133,6 +2136,13 @@ export class MdzLexer {
 		reference = mdz_trim_url_punctuation(reference);
 		this.#index = start + reference.length;
 
+		// a bare scheme (`https://`) left after trimming isn't a URL — literal text,
+		// matching the streaming parser's completion check
+		if (reference.length <= match_url_prefix_case_insensitive(reference, 0)) {
+			this.#emit_text(reference, start);
+			return;
+		}
+
 		this.#tokens.push({
 			type: 'autolink',
 			reference,
@@ -2145,19 +2155,24 @@ export class MdzLexer {
 	#tokenize_auto_link_internal(): void {
 		const start = this.#index;
 
-		// Collect path characters
-		while (this.#index < this.#text.length) {
-			const char_code = this.#text.charCodeAt(this.#index);
-			if (char_code === SPACE || char_code === NEWLINE || !is_valid_path_char(char_code)) {
-				break;
-			}
-			this.#index++;
-		}
+		// collect path characters — a path opened by `(` ends at its matching `)`
+		// (the probes only admit a `(` before a path at a valid boundary)
+		this.#index = scan_uri_chars_end(
+			this.#text,
+			start,
+			start > 0 && this.#text.charCodeAt(start - 1) === LEFT_PAREN
+		);
 
 		let reference = this.#text.slice(start, this.#index);
 		reference = mdz_trim_url_punctuation(reference);
 		this.#index = start + reference.length;
 
+		// a bare prefix (`./`, `/`) left after trimming isn't a path — literal text
+		if (is_bare_path_prefix(reference)) {
+			this.#emit_text(reference, start);
+			return;
+		}
+
 		this.#tokens.push({
 			type: 'autolink',
 			reference,
@@ -2240,13 +2255,15 @@ export class MdzLexer {
 	 * transparent (so `_~~x~~_` nests).
 	 */
 	#is_at_word_boundary(index: number, check_before: boolean, check_after: boolean): boolean {
-		if (check_before && index > 0) {
-			const prev = this.#text.charCodeAt(index - 1);
-			if (is_word_char(prev) || prev === UNDERSCORE) return false;
+		if (check_before && index > 0 && is_italic_boundary_blocker(this.#text.charCodeAt(index - 1))) {
+			return false;
 		}
-		if (check_after && index < this.#text.length) {
-			const next = this.#text.charCodeAt(index);
-			if (is_word_char(next) || next === UNDERSCORE) return false;
+		if (
+			check_after &&
+			index < this.#text.length &&
+			is_italic_boundary_blocker(this.#text.charCodeAt(index))
+		) {
+			return false;
 		}
 		return true;
 	}

package/src/lib/mdz_stream_parser.ts

@@ -7,7 +7,7 @@
  * corrections are bounded, explicit opcodes (`revert`, `wrap`, `trim_text`).
  *
  * The design is derived from
- * {@link https://bsky.app/profile/pngwn.at/post/3mi527zntb22n @pngwn.at}'s
+ * [@pngwn.at](https://bsky.app/profile/pngwn.at/post/3mi527zntb22n)'s
  * ideas: restrict the syntax so streaming is tractable, render
  * optimistically and correct when wrong, emit serializable opcodes to avoid
  * re-parsing, and keep the opcodes target-agnostic so any renderer can
@@ -138,9 +138,22 @@ import { consume_delimiter_as_text, consume_text_run } from './mdz_stream_parser
  *   Italic is the only wedge (the only delimiter whose one-shot form rejects
  *   on a failed first closer); see `try_code`'s hold and `code_search_limit`.
  * - **Optimistic inline code unclosed at EOF** — a `` ` `` that opened
- *   optimistically consumes its tail as raw code text, so formatting inside it
- *   never forms (`` h `x **b** z `` stays flat where one-shot parses the bold);
+ *   optimistically consumes its tail as raw code text, so formatting and
+ *   auto-links inside it never form (`x **b** z` and `(./a.md)` after an
+ *   unclosed backtick stay flat where one-shot parses the bold and the link);
  *   the parser never re-parses, so the EOF revert can only flatten it to text.
+ * - **A span crossing a markdown link's `]`** — the one-shot parse pairs a
+ *   `**`/`_`/`~~` opener with the first occurrence of its delimiter even across
+ *   a `[text](url)`'s bracket, because markdown links aren't bounded by an
+ *   enclosing span. With the opener before the link and that occurrence in its
+ *   display text, the link forms and the opener stays literal
+ *   (`**x [a b** c](/u) y**`; also when the occurrence sits in an auto-link in
+ *   the display text, `_x [a https://b_.c **d** e](/u) y_`); with the opener in
+ *   the display text and the closer past `]`, a link that then fails re-lexes
+ *   from `[` and the span forms (`[_]_`). Streaming decides the span before it
+ *   knows whether the link completes, so it closes at the bracketed
+ *   occurrence, or reverts the span with the failed link; mirroring the
+ *   one-shot parse would need a hold to the link's `)` or a re-parse.
  * - **Link/tag opens at EOF** — `finish()` doesn't open links or tags, so a held
  *   tail containing complete `[text](url)` / `<Tag>…</Tag>` syntax parses flat.
  * - **Block elements interrupt optimistic inlines** — at column 0 a

package/src/lib/mdz_stream_parser_block.ts

@@ -1,8 +1,8 @@
 /**
  * Block-element handlers for the streaming mdz parser.
  *
- * Each `try_*` returns {@link TryResult} so the orchestrator in
- * {@link ./mdz_stream_parser.ts} can fall through or wait for more input.
+ * Each `try_*` returns `TryResult` so the orchestrator in
+ * `mdz_stream_parser.ts` can fall through or wait for more input.
  *
  * @module
  */

package/src/lib/mdz_stream_parser_inline.ts

@@ -10,8 +10,8 @@ import {
 	NEWLINE,
 	RIGHT_ANGLE,
 	UNDERSCORE,
+	is_italic_boundary_blocker,
 	is_line_whitespace,
-	is_word_char,
 	mdz_blockquote_line_has_content,
 	mdz_match_blockquote_prefix
 } from './mdz_helpers.ts';
@@ -190,7 +190,7 @@ export const try_double_delimiter = (
 export const try_italic = (state: MdzStreamParserState, forced = false): boolean => {
 	// opening boundary: reject after a word char, or after the delimiter
 	// itself — `_` is self-opaque, so runs like `__init__` stay literal
-	if (state.prev_char !== -1 && (is_word_char(state.prev_char) || state.prev_char === UNDERSCORE)) {
+	if (state.prev_char !== -1 && is_italic_boundary_blocker(state.prev_char)) {
 		consume_delimiter_as_text(state, '_');
 		return true;
 	}
@@ -248,7 +248,7 @@ export const check_close_word_boundary = (state: MdzStreamParserState): boolean
 	const next_pos = state.pos + 1;
 	if (next_pos < state.buffer.length) {
 		const next = state.buffer.charCodeAt(next_pos);
-		return !(is_word_char(next) || next === UNDERSCORE);
+		return !is_italic_boundary_blocker(next);
 	}
 	return true;
 };
@@ -327,7 +327,7 @@ export const scan_closer_boundary = (
 	const after_pos = delim_pos + 1;
 	if (after_pos < state.buffer.length) {
 		const after = state.buffer.charCodeAt(after_pos);
-		return is_word_char(after) || after === UNDERSCORE ? 'rejected' : 'confirmed';
+		return is_italic_boundary_blocker(after) ? 'rejected' : 'confirmed';
 	}
 	// closer at end of buffer — treat as confirmed, consistent with
 	// check_close_word_boundary which also assumes boundary at buffer end

package/src/lib/mdz_stream_parser_state.ts

@@ -167,6 +167,12 @@ export interface PendingUrl {
 	/** Prefix match tracking — only used when `!confirmed`. */
 	viable_https: boolean;
 	viable_http: boolean;
+	/**
+	 * Paren depth inside a path opened by `(` — the path ends at a `)` at
+	 * depth zero — or `-1` for every other URL/path, which scan to their
+	 * terminator.
+	 */
+	paren_depth: number;
 }
 
 /**
@@ -185,6 +191,14 @@ export interface MdzStreamParserState {
 	stack: Array<StackEntry>;
 	column: number;
 	prev_char: number;
+	/**
+	 * The char before `prev_char` — the second char of lookbehind the path
+	 * boundary needs (`is_path_boundary`: a `(` opens a path only when not
+	 * glued to a word or a `]`). Only `consume_text_run` maintains it, and it's read only
+	 * when `prev_char` is `(`, which only a text run leaves behind ahead of a
+	 * path-start char; elsewhere it may be stale.
+	 */
+	before_prev_char: number;
 	active_text_id: MdzNodeId | null;
 	accumulated_text: string;
 	accumulated_text_start: number;
@@ -331,6 +345,7 @@ export const create_state = (): MdzStreamParserState => ({
 	stack: [],
 	column: 0,
 	prev_char: -1,
+	before_prev_char: -1,
 	active_text_id: null,
 	accumulated_text: '',
 	accumulated_text_start: 0,
@@ -776,18 +791,24 @@ export const revert_above = (state: MdzStreamParserState, target_idx: number): v
 };
 
 /**
- * Revert an open `Italic` whose first closer candidate failed its boundary
- * check (italic is the only inline with closer-boundary rules). One-shot
- * parsing greedy-rejects the opener at the first invalid closer, so once a
- * failed candidate is seen, the optimistic open is known wrong — reverting
- * immediately (instead of leaving the container open for a later closer)
- * keeps chunked output identical to the one-shot parse.
+ * Revert one open frame, possibly **mid-stack**, without reverting the frames
+ * above it. Two callers:
+ *
+ * - an open `Italic` whose first closer candidate failed its boundary check
+ *   (italic is the only inline with closer-boundary rules) — one-shot parsing
+ *   greedy-rejects the opener at the first invalid closer, so once a failed
+ *   candidate is seen the optimistic open is known wrong, and reverting
+ *   immediately keeps chunked output identical to the one-shot parse
+ * - the auto-link span resolution (`revert_spans_closed_inside` in
+ *   `mdz_stream_parser_url.ts`), which reverts `Bold`, `Italic`,
+ *   `Strikethrough`, `Element`, and `Component` frames whose span the one-shot
+ *   parse leaves literal, one frame at a time and possibly beneath a `Link`
+ *   frame that stays open
  *
- * Unlike `revert_above`, this reverts a possibly
- * **mid-stack** entry: containers opened above it (e.g. a Bold inside the
- * failed Italic) stay open — the one-shot parse opens them at top level, and
- * the consumers' revert handlers re-parent them identically (the reverted
- * node is still its parent's last child; see `mdz_opcodes_to_nodes` and
+ * Containers opened above the reverted frame stay open, and the consumers'
+ * revert handlers re-parent them identically for every frame type — the
+ * reverted node is still its parent's last child, and both handlers work on
+ * node ids and children only (see `mdz_opcodes_to_nodes` and
  * `MdzStreamState`).
  *
  * Bypasses `emit` for the opcode push: `emit`'s heading-segment handling
@@ -813,8 +834,8 @@ export const revert_failed_close = (state: MdzStreamParserState, stack_idx: numb
 		if (remaining === 0) counts.delete(entry.tag_name);
 		else counts.set(entry.tag_name, remaining);
 	}
-	// only ever reverts an Italic today, but keep the depth counter honest if a
-	// Link/Element/Component is ever failed-closed mid-stack
+	// Element/Component frames count toward the link/tag nesting depth (Link
+	// frames are never reverted here today, but keep the counter honest)
 	if (entry.node_type === 'Link' || entry.tag_name !== undefined) state.open_link_tag_depth--;
 	state.opcodes.push({
 		type: 'revert',

package/src/lib/mdz_stream_parser_text.ts

@@ -6,14 +6,12 @@
 
 import {
 	HTTPS_PREFIX_LENGTH,
-	NEWLINE,
-	SPACE,
-	TAB,
 	TEXT_CLASS_NEWLINE,
 	TEXT_CLASS_PATH,
 	TEXT_CLASS_STOP,
 	TEXT_CLASS_URL,
 	TEXT_SCAN_CLASS,
+	is_path_boundary,
 	is_word_char,
 	match_url_prefix_case_insensitive
 } from './mdz_helpers.ts';
@@ -82,15 +80,24 @@ export const consume_text_run = (state: MdzStreamParserState): void => {
 				break;
 			}
 		} else if ((char_class & TEXT_CLASS_PATH) !== 0) {
-			// path (`/` or `.`): only break at a plausible path start
-			const prev = state.buffer.charCodeAt(state.pos - 1);
-			if (prev === SPACE || prev === NEWLINE || prev === TAB) break;
+			// path (`/` or `.`): only break at a plausible path start — the run
+			// start's lookbehind is the incoming `prev_char`
+			if (
+				is_path_boundary(
+					state.buffer.charCodeAt(state.pos - 1),
+					state.pos - 2 >= start ? state.buffer.charCodeAt(state.pos - 2) : state.prev_char
+				)
+			) {
+				break;
+			}
 		}
 		// backslash (or a non-starting path char) — ordinary text
 		state.pos++;
 	}
 	if (mdz_debug_work.enabled) mdz_debug_work.total += state.pos - start;
 	accumulate_text(state, state.buffer.slice(start, state.pos), offset(state, start));
+	state.before_prev_char =
+		state.pos - 2 >= start ? state.buffer.charCodeAt(state.pos - 2) : state.prev_char;
 	state.prev_char = state.buffer.charCodeAt(state.pos - 1);
 	state.column += state.pos - start;
 };