@fuzdev/mdz 0.1.0

package/package.json

@@ -0,0 +1,131 @@
+{
+  "name": "@fuzdev/mdz",
+  "version": "0.1.0",
+  "description": "a strict markdown dialect built for streaming, Svelte authoring, docs websites, and untrusted content",
+  "tagline": "markdown for fuz",
+  "glyph": "📝",
+  "logo": "logo.svg",
+  "logo_alt": "a friendly pixelated spider facing you",
+  "license": "MIT",
+  "homepage": "https://mdz.fuz.dev/",
+  "author": {
+    "name": "Ryan Atkinson",
+    "email": "mail@ryanatkn.com",
+    "url": "https://www.ryanatkn.com/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fuzdev/mdz.git"
+  },
+  "bugs": "https://github.com/fuzdev/mdz/issues",
+  "funding": "https://www.ryanatkn.com/funding",
+  "scripts": {
+    "start": "gro dev",
+    "dev": "gro dev",
+    "build": "gro build",
+    "check": "gro check",
+    "test": "gro test",
+    "fixtures:update": "gro src/test/fixtures/update",
+    "preview": "vite preview",
+    "deploy": "gro deploy",
+    "benchmark": "gro run src/benchmarks/mdz.benchmark.ts",
+    "benchmark:save": "gro run src/benchmarks/mdz.benchmark.ts --save",
+    "benchmark:clean": "rm -f src/benchmarks/baseline.json"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.14"
+  },
+  "peerDependencies": {
+    "@fuzdev/fuz_util": ">=0.65.1",
+    "@sveltejs/kit": "^2.47.3",
+    "@types/estree": "^1",
+    "esm-env": "^1",
+    "svelte": "^5"
+  },
+  "peerDependenciesMeta": {
+    "@types/estree": {
+      "optional": true
+    },
+    "esm-env": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "magic-string": "^0.30.21",
+    "zimmerframe": "^1.1.4"
+  },
+  "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_util": "^0.65.1",
+    "@fuzdev/gro": "^0.204.0",
+    "@ryanatkn/eslint-config": "^0.12.1",
+    "@sveltejs/acorn-typescript": "^1.0.10",
+    "@sveltejs/adapter-static": "^3.0.10",
+    "@sveltejs/kit": "^2.65.0",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@types/estree": "^1.0.8",
+    "@types/node": "^24.12.4",
+    "@webref/css": "^8.2.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-svelte": "^3.13.1",
+    "esm-env": "^1.2.2",
+    "prettier": "^3.7.4",
+    "prettier-plugin-svelte": "^3.5.1",
+    "svelte": "^5.56.3",
+    "svelte-check": "^4.6.0",
+    "svelte-docinfo": "^0.5.3",
+    "svelte2tsx": "^0.7.56",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.1",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.15"
+  },
+  "prettier": {
+    "plugins": [
+      "prettier-plugin-svelte"
+    ],
+    "useTabs": true,
+    "printWidth": 100,
+    "singleQuote": true,
+    "bracketSpacing": false,
+    "overrides": [
+      {
+        "files": "package.json",
+        "options": {
+          "useTabs": false
+        }
+      }
+    ]
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "src/lib/**/*.ts",
+    "!src/lib/**/*.test.*",
+    "!dist/**/*.test.*"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.ts": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.svelte": {
+      "types": "./dist/*.svelte.d.ts",
+      "svelte": "./dist/*.svelte",
+      "default": "./dist/*.svelte"
+    }
+  }
+}

package/src/lib/context_helpers.ts

@@ -0,0 +1,52 @@
+import {getContext, setContext} from 'svelte';
+
+// This uses a function instead of a class because of the overloaded type signatures.
+// It could be implemented internally with a class like `SvelteContext`
+// but this is less code and seems a bit simpler.
+// The memory gains of a class appear minimal given the expected usage patterns.
+
+// TODO maybe remove `error_message`?
+
+/**
+ * Wraps Svelte's `setContext` and `getContext` for better ergonomics.
+ * When no value is set in the context,
+ * `get` throws an error and `get_maybe` returns `undefined`.
+ * 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
+ * in the dependency graph, so mdz keeps its own copy for `mdz_contexts.ts`.
+ * Consumers should import fuz_ui's.
+ *
+ * @nodocs
+ */
+export function create_context<T>(fallback: () => T): {
+	get: () => T;
+	set: (value?: T) => T;
+};
+export function create_context<T>(): {
+	get: (error_message?: string) => T;
+	get_maybe: () => T | undefined;
+	set: (value: T) => T;
+};
+export function create_context<T>(fallback?: () => T): {
+	get: (error_message?: string) => T;
+	get_maybe: () => T | undefined;
+	set: (value?: T) => T;
+} {
+	const key = Symbol();
+	const get_maybe = () => {
+		const value: T | undefined = getContext(key); // treat `null` as a valid value - the `typescript-eslint` rule below is bugged because `??` would clobber nulls, see issue https://github.com/typescript-eslint/typescript-eslint/issues/7842
+		return value === undefined ? fallback?.() : value;
+	};
+	return {
+		get: (error_message?: string) => {
+			const value = get_maybe();
+			if (value === undefined) throw Error(error_message ?? 'context value is not set');
+			return value;
+		},
+		get_maybe,
+		// this is typesafe, so no runtime check:
+		set: (value: T | undefined = fallback?.()) => setContext(key, value)!,
+	};
+}

package/src/lib/mdz.ts

@@ -0,0 +1,190 @@
+/**
+ * mdz — strict markdown dialect built for streaming, Svelte authoring, docs
+ * sites, and untrusted content.
+ *
+ * Created for two motivating use cases: rendering TSDoc/JSDoc comments on
+ * docs websites (with domain-specific behavior like linkifying backticked
+ * identifiers) and authoring content with Svelte components. It also has a
+ * streaming parser that extends the same grammar to LLM output.
+ *
+ * This module is the synchronous entry: `mdz_parse` parses a complete string
+ * to an `MdzNode` tree. It is the canonical reference parser — the streaming
+ * pipeline (`mdz_stream_parser.ts`) emits opcodes that converge on the same
+ * tree, asserted by parity tests.
+ *
+ * The dialect supports:
+ * - inline formatting: `code`, **bold**, _italic_, ~~strikethrough~~
+ * - auto-detected links: external URLs (`https://...`) and internal paths (`/path`)
+ * - markdown links: `[text](url)` with custom display text
+ * - 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
+ * - HTML elements and Svelte components (opt-in via context)
+ *
+ * Whitespace: the parser preserves whitespace in text node content (single
+ * newlines stay literal `\n`, no `<br>` nodes), while structural whitespace is
+ * interpreted — blank lines separate paragraphs, extra blank lines collapse,
+ * and a line of only whitespace (spaces, tabs, `\r`) counts as blank, so an
+ * invisible trailing space never changes document structure.
+ * Presentation is the renderer's choice: by default whitespace collapses like
+ * standard markdown (single newlines are soft breaks), and the `whitespace`
+ * prop on `Mdz`/`MdzStream` opts into `pre-line` or `pre-wrap` rendering.
+ *
+ * ## Design philosophy
+ *
+ * - **False negatives over false positives**: When in doubt, treat as plain text.
+ *   Block elements can interrupt paragraphs without blank lines; inline formatting is strict.
+ * - **One way to do things**: Single unambiguous syntax per feature. No alternatives.
+ * - **Explicit over implicit**: Clear delimiters and column-0 requirements avoid ambiguity.
+ * - **Simple over complete**: Prefer simple parsing rules over complex edge case handling.
+ * - **No implicit retroactivity**: the grammar admits no construct where later input changes
+ *   the rendering of unboundedly-earlier output, so the streaming pipeline corrects only via
+ *   bounded, explicit opcodes and never re-parses.
+ *
+ * ## Status
+ *
+ * Pre-stable — breaking changes are expected as the dialect matures.
+ * Next: attributes, editing.
+ *
+ * @module
+ */
+
+import {MdzLexer} from './mdz_lexer.js';
+import {MdzTokenParser} from './mdz_token_parser.js';
+
+// TODO design incremental parsing or some system that preserves Svelte components across re-renders when possible
+
+/**
+ * Parses text to an array of `MdzNode`.
+ *
+ * Two phases: `MdzLexer` tokenizes the input into a flat `MdzToken[]` stream,
+ * then `MdzTokenParser` builds the `MdzNode[]` tree from the tokens.
+ */
+export const mdz_parse = (text: string): Array<MdzNode> =>
+	new MdzTokenParser(new MdzLexer(text).tokenize()).parse();
+
+export type MdzNode =
+	| MdzNodeText
+	| MdzNodeCode
+	| MdzNodeCodeblock
+	| MdzNodeBold
+	| MdzNodeItalic
+	| MdzNodeStrikethrough
+	| MdzNodeLink
+	| MdzNodeParagraph
+	| MdzNodeHr
+	| MdzNodeHeading
+	| MdzNodeList
+	| MdzNodeListItem
+	| MdzNodeBlockquote
+	| MdzNodeElement
+	| MdzNodeComponent;
+
+export interface MdzNodeBase {
+	type: string;
+	start: number;
+	end: number;
+}
+
+export interface MdzNodeText extends MdzNodeBase {
+	type: 'Text';
+	content: string;
+}
+
+export interface MdzNodeCode extends MdzNodeBase {
+	type: 'Code';
+	/** The code content (identifier/module name). */
+	content: string;
+}
+
+export interface MdzNodeCodeblock extends MdzNodeBase {
+	type: 'Codeblock';
+	/** Language hint, if provided. */
+	lang: string | null;
+	/** Raw code content. */
+	content: string;
+}
+
+export interface MdzNodeBold extends MdzNodeBase {
+	type: 'Bold';
+	children: Array<MdzNode>;
+}
+
+export interface MdzNodeItalic extends MdzNodeBase {
+	type: 'Italic';
+	children: Array<MdzNode>;
+}
+
+export interface MdzNodeStrikethrough extends MdzNodeBase {
+	type: 'Strikethrough';
+	children: Array<MdzNode>;
+}
+
+export interface MdzNodeLink extends MdzNodeBase {
+	type: 'Link';
+	/** URL or path. */
+	reference: string;
+	/** Display content (can include inline formatting). */
+	children: Array<MdzNode>;
+	/** `external` is `https`/`http`; `internal` is `/path`, `./path`, or `../path`. */
+	link_type: 'external' | 'internal';
+}
+
+export interface MdzNodeParagraph extends MdzNodeBase {
+	type: 'Paragraph';
+	children: Array<MdzNode>;
+}
+
+export interface MdzNodeHr extends MdzNodeBase {
+	type: 'Hr';
+}
+
+export interface MdzNodeHeading extends MdzNodeBase {
+	type: 'Heading';
+	level: 1 | 2 | 3 | 4 | 5 | 6;
+	/** Slugified heading text for fragment links. */
+	id: string;
+	/** Inline formatting allowed. */
+	children: Array<MdzNode>;
+}
+
+export interface MdzNodeList extends MdzNodeBase {
+	type: 'List';
+	ordered: boolean;
+	/** First item's authored number (ordered only) — the `<ol start>` attribute. */
+	start_number?: number;
+	children: Array<MdzNodeListItem>;
+}
+
+export interface MdzNodeListItem extends MdzNodeBase {
+	type: 'ListItem';
+	/** Authored number (ordered only); the renderer ignores it, tooling and the future formatter use it. */
+	number?: number;
+	/** Inline run first, then block children (`Paragraph` | `List` | `Codeblock` | `Blockquote`). */
+	children: Array<MdzNode>;
+}
+
+export interface MdzNodeBlockquote extends MdzNodeBase {
+	type: 'Blockquote';
+	/**
+	 * Block children — a quote's content is a mini-document, so anything that
+	 * can appear at the top level can appear here (`Paragraph` | `Heading` |
+	 * `Hr` | `List` | `Codeblock` | `Blockquote`).
+	 */
+	children: Array<MdzNode>;
+}
+
+export interface MdzNodeElement extends MdzNodeBase {
+	type: 'Element';
+	/** HTML element name (e.g. `div`, `span`, `aside`). */
+	name: string;
+	children: Array<MdzNode>;
+}
+
+export interface MdzNodeComponent extends MdzNodeBase {
+	type: 'Component';
+	/** Svelte component name (e.g. `Alert`, `Card`). */
+	name: string;
+	children: Array<MdzNode>;
+}

package/src/lib/mdz_contexts.ts

@@ -0,0 +1,99 @@
+import type {Component} from 'svelte';
+
+import {create_context} from './context_helpers.js';
+
+/**
+ * Component registry for custom Svelte components that can be used in mdz content.
+ *
+ * For example, registering 'Alert' allows using `<Alert>...</Alert>` in mdz content.
+ *
+ * The Map values are Svelte components.
+ */
+export type MdzComponents = Map<string, Component<any, any>>; // TODO support params
+
+/**
+ * Element registry for HTML elements that can be used in mdz content.
+ *
+ * For example, registering 'div' allows using `<div>...</div>` in mdz content.
+ *
+ * The Map values are boolean placeholders for future configuration options.
+ */
+export type MdzElements = Map<string, boolean>;
+
+/**
+ * CSS `white-space` values for the `whitespace` prop on `Mdz`, `MdzStream`,
+ * and `MdzPrecompiled`. By default no style is applied, so whitespace
+ * collapses like standard markdown — single newlines are soft breaks.
+ * `pre-line` renders every newline as a line break (chat-style input);
+ * `pre-wrap` additionally preserves spaces and tabs.
+ */
+export type MdzWhitespace = 'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line' | 'break-spaces';
+
+/**
+ * Context for providing custom mdz components via a getter function.
+ * Set to a getter (e.g., `() => components`) so changes are reflected reactively.
+ */
+export const mdz_components_context = create_context<() => MdzComponents | undefined>();
+
+/**
+ * Context for providing allowed HTML elements via a getter function.
+ * Set to a getter (e.g., `() => elements`) so changes are reflected reactively.
+ * By default, no HTML elements are allowed.
+ */
+export const mdz_elements_context = create_context<() => MdzElements | undefined>();
+
+/**
+ * Context for providing a base path getter for resolving relative links in mdz content.
+ * Set to a getter (e.g., `() => base`) so changes to the base prop are reflected
+ * without needing an effect. When the getter returns a path like `'/docs/usage/'`,
+ * relative paths like `./grammar` resolve to `/docs/usage/grammar` before rendering.
+ * When not set, relative paths use raw hrefs (browser resolves them).
+ */
+export const mdz_base_context = create_context<() => string | undefined>();
+
+/**
+ * Component that renders an inline `` `code` `` span. Receives the raw span
+ * content as `reference` — the prop name matches `fuz_ui`'s `DocsLink`, so it
+ * can be injected directly to auto-link backticked API identifiers.
+ */
+export type MdzCodeComponent = Component<{reference: string}>;
+
+/**
+ * Context for overriding how inline `` `code` `` spans render, via a getter
+ * function. When not set, inline code renders as a plain `<code>` element.
+ */
+export const mdz_code_context = create_context<() => MdzCodeComponent | undefined>();
+
+/**
+ * Component that renders a fenced code block. Receives `lang` and `content`,
+ * matching `@fuzdev/fuz_code`'s `Code`, so it can be injected directly for
+ * syntax highlighting.
+ */
+export type MdzCodeblockComponent = Component<{lang: string | null; content: string}>;
+
+/**
+ * Context for overriding how fenced code blocks render, via a getter function.
+ * When not set, code blocks render as a plain `<pre><code>` element.
+ */
+export const mdz_codeblock_context = create_context<() => MdzCodeblockComponent | undefined>();
+
+interface MdzGetterContext<T> {
+	get_maybe(): (() => T | undefined) | undefined;
+	set(value: () => T | undefined): unknown;
+}
+
+/**
+ * Set an mdz context to a getter that prefers the local `value_fn` and falls
+ * back to the ancestor's value when `value_fn()` returns `undefined`.
+ *
+ * Pass `value_fn` as a getter (not a snapshot) so prop changes remain reactive.
+ * The ancestor lookup happens once at component init — that's intentional, it
+ * captures the surrounding scope's context at mount time.
+ */
+export const mdz_set_context_with_fallback = <T>(
+	context: MdzGetterContext<T>,
+	value_fn: () => T | undefined,
+): void => {
+	const ancestor = context.get_maybe();
+	context.set(() => value_fn() ?? ancestor?.());
+};