@markii/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sadigaxund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @markii/core
+
+The framework-agnostic reference parser for [Mark](https://github.com/sadigaxund/markii) (`.mk.md`): CommonMark + GitHub-Flavored Markdown plus a generic directive syntax, parsed to an mdast tree and converted to a sanitized hast tree. Zero React dependency — component-agnostic by design, so any renderer (e.g. `@markii/react`) can consume its output.
+
+See the [repository](https://github.com/sadigaxund/markii) for the format spec and the reference library as a whole.

package/dist/corpus.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Resolves the repo-root `conformance/` directory relative to this module's
+ * own file location (not `process.cwd()`), so it works the same whether
+ * tests run from the repo root or from within a single workspace (each
+ * workspace's `vitest run` / `node` invocation has a different cwd).
+ */
+export declare function conformanceDir(): string;
+export interface CorpusCase {
+    /** Fixture name, e.g. `"01-plain-markdown"` (no extension). */
+    name: string;
+    /** Absolute path to the `.mk.md` input file. */
+    smdPath: string;
+    /** Absolute path to the sibling expected-AST `.json` file. */
+    jsonPath: string;
+    /** Raw `.mk.md` source text. */
+    input: string;
+    /** Parsed expected-AST JSON (already position-free). */
+    expected: unknown;
+}
+/**
+ * Base fixture names (no extension) for every `*.mk.md` file in `dir`,
+ * sorted. `.mk.md` is a COMPOUND extension (two dots) — the sibling name is
+ * derived by stripping the full `DOC_EXTENSION` suffix, not by slicing off
+ * whatever `path.extname()` would report (which would only strip `.md` and
+ * leave a stray `.mk` in the fixture name).
+ */
+export declare function listCorpusNames(dir?: string): string[];
+/**
+ * Loads every `<name>.mk.md` / `<name>.json` pair from `dir` (default: the
+ * repo-root `conformance/` directory). A `.mk.md` file with no matching
+ * `.json` sibling throws (surfacing the missing fixture loudly rather than
+ * silently skipping a corpus case).
+ */
+export declare function loadCorpusCases(dir?: string): CorpusCase[];
+/**
+ * Recursively strips every `position` field from a parsed tree (unist nodes
+ * carry `position` with line/column/offset info that's irrelevant to
+ * structural conformance and would make corpus fixtures brittle to
+ * reformat). Generic over any plain-data tree shape, not just mdast, so it
+ * doubles as a hast-position-stripper if a future corpus level needs one.
+ */
+export declare function stripPositions<T>(value: T): T;
+/**
+ * Serializes `value` as pretty-printed JSON with a deterministic, sorted key
+ * order (so regenerated expected-AST fixtures diff cleanly and don't depend
+ * on incidental object-construction order) and a trailing newline.
+ */
+export declare function stableStringify(value: unknown): string;

package/dist/corpus.js

@@ -0,0 +1,97 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The language-agnostic conformance corpus: `*.mk.md` inputs plus
+ * expected-AST `*.json` siblings, living at the repo root (see DESIGN.md
+ * §13). This module is deliberately parser-agnostic — it only
+ * loads/compares corpus data — so it's usable from any package's tests (or
+ * a future non-JS implementation's tooling), not just `@markii/core`'s own
+ * parser tests.
+ */
+/** The Mark document extension. Compound (two dots) — never use `path.extname()` to strip it. */
+const DOC_EXTENSION = '.mk.md';
+/**
+ * Resolves the repo-root `conformance/` directory relative to this module's
+ * own file location (not `process.cwd()`), so it works the same whether
+ * tests run from the repo root or from within a single workspace (each
+ * workspace's `vitest run` / `node` invocation has a different cwd).
+ */
+export function conformanceDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // packages/markii-core/src -> packages/markii-core -> packages -> repo root
+    return join(here, '..', '..', '..', 'conformance');
+}
+/**
+ * Base fixture names (no extension) for every `*.mk.md` file in `dir`,
+ * sorted. `.mk.md` is a COMPOUND extension (two dots) — the sibling name is
+ * derived by stripping the full `DOC_EXTENSION` suffix, not by slicing off
+ * whatever `path.extname()` would report (which would only strip `.md` and
+ * leave a stray `.mk` in the fixture name).
+ */
+export function listCorpusNames(dir = conformanceDir()) {
+    return readdirSync(dir)
+        .filter((entry) => entry.endsWith(DOC_EXTENSION))
+        .map((entry) => entry.slice(0, -DOC_EXTENSION.length))
+        .sort();
+}
+/**
+ * Loads every `<name>.mk.md` / `<name>.json` pair from `dir` (default: the
+ * repo-root `conformance/` directory). A `.mk.md` file with no matching
+ * `.json` sibling throws (surfacing the missing fixture loudly rather than
+ * silently skipping a corpus case).
+ */
+export function loadCorpusCases(dir = conformanceDir()) {
+    return listCorpusNames(dir).map((name) => {
+        const smdPath = join(dir, `${name}${DOC_EXTENSION}`);
+        const jsonPath = join(dir, `${name}.json`);
+        const input = readFileSync(smdPath, 'utf8');
+        const expected = JSON.parse(readFileSync(jsonPath, 'utf8'));
+        return { name, smdPath, jsonPath, input, expected };
+    });
+}
+/**
+ * Recursively strips every `position` field from a parsed tree (unist nodes
+ * carry `position` with line/column/offset info that's irrelevant to
+ * structural conformance and would make corpus fixtures brittle to
+ * reformat). Generic over any plain-data tree shape, not just mdast, so it
+ * doubles as a hast-position-stripper if a future corpus level needs one.
+ */
+export function stripPositions(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => stripPositions(item));
+    }
+    if (value !== null && typeof value === 'object') {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            if (key === 'position')
+                continue;
+            result[key] = stripPositions(val);
+        }
+        return result;
+    }
+    return value;
+}
+/** Deep-clones `value` with every object's keys sorted alphabetically. */
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortKeysDeep(item));
+    }
+    if (value !== null && typeof value === 'object') {
+        const source = value;
+        const sorted = {};
+        for (const key of Object.keys(source).sort()) {
+            sorted[key] = sortKeysDeep(source[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/**
+ * Serializes `value` as pretty-printed JSON with a deterministic, sorted key
+ * order (so regenerated expected-AST fixtures diff cleanly and don't depend
+ * on incidental object-construction order) and a trailing newline.
+ */
+export function stableStringify(value) {
+    return `${JSON.stringify(sortKeysDeep(value), null, 2)}\n`;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { parse } from './parse.js';
+export { toHast, isSafeUrl } from './to-hast.js';
+export { extractScripts, parseMetaAttributes, type ScriptBlock, } from './scripts.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+// This is @markii/core's browser-safe entry point: parsing and hast conversion
+// only. The conformance-corpus runner (`./corpus`) touches `node:fs` and is
+// Node-only tooling for tests/scripts — it lives at the `@markii/core/corpus`
+// subpath instead of here so a browser bundler consuming `@markii/core` (e.g.
+// via `@markii/react`) never has to reason about Node built-ins reachable from
+// its entry point.
+export { parse } from './parse.js';
+export { toHast, isSafeUrl } from './to-hast.js';
+export { extractScripts, parseMetaAttributes, } from './scripts.js';

package/dist/parse.d.ts

@@ -0,0 +1,17 @@
+import type { Root } from 'mdast';
+/**
+ * Parses Mark text into an mdast AST. CommonMark plus GitHub-Flavored
+ * Markdown (`remark-gfm`: tables, task lists, strikethrough, autolinks) plus
+ * the generic directive grammar (`remark-directive`) — nothing more. GFM and
+ * directives are independent micromark syntax extensions (GFM extends the
+ * table / list-item / inline grammar; directives add their own `:`/`::`/`:::`
+ * grammar) and compose without interference regardless of `.use()` order —
+ * confirmed empirically by the conformance corpus (a document combining a
+ * GFM table and a `:::` directive parses both correctly). This module is
+ * component-agnostic: it has no knowledge of the registry or any component,
+ * and must stay that way (directive nodes carry only a name, attributes,
+ * and children; interpreting a name is the renderer's job; GFM nodes are
+ * standard mdast — `table`, `listItem.checked`, `delete` — needing no
+ * component/registry coupling at all).
+ */
+export declare function parse(text: string): Root;

package/dist/parse.js

@@ -0,0 +1,26 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkDirective from 'remark-directive';
+import remarkGfm from 'remark-gfm';
+/**
+ * Parses Mark text into an mdast AST. CommonMark plus GitHub-Flavored
+ * Markdown (`remark-gfm`: tables, task lists, strikethrough, autolinks) plus
+ * the generic directive grammar (`remark-directive`) — nothing more. GFM and
+ * directives are independent micromark syntax extensions (GFM extends the
+ * table / list-item / inline grammar; directives add their own `:`/`::`/`:::`
+ * grammar) and compose without interference regardless of `.use()` order —
+ * confirmed empirically by the conformance corpus (a document combining a
+ * GFM table and a `:::` directive parses both correctly). This module is
+ * component-agnostic: it has no knowledge of the registry or any component,
+ * and must stay that way (directive nodes carry only a name, attributes,
+ * and children; interpreting a name is the renderer's job; GFM nodes are
+ * standard mdast — `table`, `listItem.checked`, `delete` — needing no
+ * component/registry coupling at all).
+ */
+export function parse(text) {
+    const processor = unified()
+        .use(remarkParse)
+        .use(remarkDirective)
+        .use(remarkGfm);
+    return processor.parse(text);
+}

package/dist/scripts.d.ts

@@ -0,0 +1,50 @@
+import type { Code, Root } from 'mdast';
+/**
+ * Slice 1 of the scripting-usability layer (DESIGN.md §8): this module only
+ * *reads* script blocks out of an already-parsed AST — it never executes
+ * anything, imports no Lua/wasmoon, and knows nothing about a value store.
+ * A script block is, at the parse layer, an ordinary fenced code block (see
+ * `to-hast.ts`/§8: "plain markdown viewers just show the code") — the only
+ * thing that distinguishes it from any other code fence is a `{...}`
+ * attribute group in its `meta` string carrying a `name`.
+ */
+/**
+ * One script block found in a document, in document order. `lang` is the
+ * fence's language tag (`"lua"` for ` ```lua {name=...}` `, `""` if the
+ * fence had no language). `src`, when present, points at a bundle-relative
+ * long-script file (§8: "the block becomes a one-line reference,
+ * ` ```lua {src=scripts/etl.lua name=stars}` ` with an empty body"); `code`
+ * is still the fence's own body (empty for a `src=` reference).
+ */
+export interface ScriptBlock {
+    name: string;
+    lang: string;
+    src?: string;
+    code: string;
+    position?: Code['position'];
+}
+/**
+ * Parses a fence `meta` string's `{...}` attribute group into a flat
+ * key/value map (bare `key` with no `=value` yields `''`). Returns an empty,
+ * null-prototype object when `meta` has no attribute group at all — the
+ * caller treats a missing `name` key the same way either way (not a
+ * script), but the null prototype keeps a lookup like `attrs.constructor`
+ * from ever resolving to an inherited `Object.prototype` member, matching
+ * the defensive pattern already used for the registry (`registry.ts`) and
+ * the URL-attribute lookup (`to-hast.ts`).
+ *
+ * Exported so a renderer (e.g. `@markii/react`) that wants to tell a script
+ * block from ordinary code can reuse this exact grammar instead of
+ * duplicating the brace/quote/token-scanning logic — `to-hast.ts` preserves
+ * the raw fence `meta` string onto the hast `<code>` element for exactly
+ * this purpose (see its `preserveCodeMeta` plugin).
+ */
+export declare function parseMetaAttributes(meta: string | null | undefined): Record<string, string>;
+/**
+ * Walks a parsed mdast `Root` and returns every script block, in document
+ * order. A `code` node is a script iff its `meta` carries a `{...}`
+ * attribute group with a non-empty `name`; a code block with no meta, or
+ * meta with no `name`, is ordinary code and is skipped. Pure AST
+ * inspection — no execution, no I/O, no knowledge of any value store.
+ */
+export declare function extractScripts(tree: Root): ScriptBlock[];

package/dist/scripts.js

@@ -0,0 +1,94 @@
+import { visit } from 'unist-util-visit';
+/**
+ * Finds the first brace-delimited attribute group (`{...}`) in `source`,
+ * returning its inner text (without the braces), or `undefined` if none is
+ * present. Braces inside a quoted attribute value are ignored while
+ * scanning for the closing `}`, so `{title="a }b" name=x}` still finds the
+ * real close brace rather than the one inside the quotes.
+ */
+function findAttributeGroup(source) {
+    const start = source.indexOf('{');
+    if (start === -1)
+        return undefined;
+    let quote;
+    for (let i = start + 1; i < source.length; i++) {
+        const ch = source[i];
+        if (quote) {
+            if (ch === quote)
+                quote = undefined;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === '}')
+            return source.slice(start + 1, i);
+    }
+    return undefined;
+}
+/**
+ * Token grammar inside a `{...}` attribute group: `key`, `key=bareValue`,
+ * `key="quoted value"`, or `key='quoted value'`. Whitespace-separated.
+ */
+const ATTRIBUTE_TOKEN = /([A-Za-z_][\w-]*)(?:=(?:"([^"]*)"|'([^']*)'|(\S+)))?/g;
+/**
+ * Parses a fence `meta` string's `{...}` attribute group into a flat
+ * key/value map (bare `key` with no `=value` yields `''`). Returns an empty,
+ * null-prototype object when `meta` has no attribute group at all — the
+ * caller treats a missing `name` key the same way either way (not a
+ * script), but the null prototype keeps a lookup like `attrs.constructor`
+ * from ever resolving to an inherited `Object.prototype` member, matching
+ * the defensive pattern already used for the registry (`registry.ts`) and
+ * the URL-attribute lookup (`to-hast.ts`).
+ *
+ * Exported so a renderer (e.g. `@markii/react`) that wants to tell a script
+ * block from ordinary code can reuse this exact grammar instead of
+ * duplicating the brace/quote/token-scanning logic — `to-hast.ts` preserves
+ * the raw fence `meta` string onto the hast `<code>` element for exactly
+ * this purpose (see its `preserveCodeMeta` plugin).
+ */
+export function parseMetaAttributes(meta) {
+    const attrs = Object.create(null);
+    if (!meta)
+        return attrs;
+    const group = findAttributeGroup(meta);
+    if (group === undefined)
+        return attrs;
+    ATTRIBUTE_TOKEN.lastIndex = 0;
+    let match;
+    while ((match = ATTRIBUTE_TOKEN.exec(group)) !== null) {
+        const key = match[1];
+        if (!key)
+            continue;
+        attrs[key] = match[2] ?? match[3] ?? match[4] ?? '';
+    }
+    return attrs;
+}
+/**
+ * Walks a parsed mdast `Root` and returns every script block, in document
+ * order. A `code` node is a script iff its `meta` carries a `{...}`
+ * attribute group with a non-empty `name`; a code block with no meta, or
+ * meta with no `name`, is ordinary code and is skipped. Pure AST
+ * inspection — no execution, no I/O, no knowledge of any value store.
+ */
+export function extractScripts(tree) {
+    const blocks = [];
+    visit(tree, 'code', (node) => {
+        const attrs = parseMetaAttributes(node.meta);
+        const name = attrs.name;
+        if (!name)
+            return;
+        const block = {
+            name,
+            lang: node.lang ?? '',
+            code: node.value,
+        };
+        if (attrs.src)
+            block.src = attrs.src;
+        if (node.position)
+            block.position = node.position;
+        blocks.push(block);
+    });
+    return blocks;
+}

package/dist/to-hast.d.ts

@@ -0,0 +1,40 @@
+import type { Root as HastRoot } from 'hast';
+/**
+ * Modelled on react-markdown's `defaultUrlTransform`, though our allowlist
+ * differs from theirs (we add `tel`; we drop `ircs` and `xmpp`) — see
+ * `SAFE_URL_PROTOCOLS` above for the actual list. A URL with no scheme
+ * (relative, fragment-only `#...`, or query-only `?...`) is always allowed;
+ * a URL with a scheme is allowed only if that scheme is in
+ * `SAFE_URL_PROTOCOLS`. Finding the "scheme" the same way a browser does —
+ * text before the first `:`, but only when that `:` comes before any `/`,
+ * `?`, or `#` — is what correctly rejects tricks like a leading space
+ * (`" javascript:..."`, whose slice-before-colon is `" javascript"`, which
+ * never matches a bare protocol name) while still allowing a same-origin
+ * path that happens to contain a colon later on.
+ *
+ * Exported (not just used by `sanitizeUrls` below) because a directive
+ * *attribute* that a renderer maps straight to a DOM URL prop — e.g.
+ * `@markii/react`'s `figure` component putting a `src` attribute into
+ * `<img src>` — never passes through `sanitizeUrls`, which only walks the
+ * hast tree `remark-rehype` itself produces from markdown links/images.
+ * Such a renderer must run the attribute value through this same check
+ * itself, rather than re-implementing URL-scheme parsing, to get the exact
+ * same guarantee.
+ */
+export declare function isSafeUrl(url: string): boolean;
+/**
+ * Converts Mark text straight to a sanitized hast tree: parse (mdast, with
+ * directive + GFM syntax extensions) -> tag directive nodes + preserve
+ * code-fence meta for hast conversion -> remark-rehype (hast) -> strip
+ * unsafe URLs. GFM constructs (tables, task lists, strikethrough, autolinks)
+ * need no tagging step of their own — `remark-rehype`'s default handlers
+ * already turn them into standard `<table>`/`<input type=checkbox>`/`<del>`/
+ * `<a>` hast elements, and `sanitizeUrls` below covers every `<a href>`/
+ * `<img src>` regardless of whether it came from a GFM autolink or an
+ * ordinary link. This is the framework-agnostic half of rendering —
+ * `@markii/react` (or any other renderer) turns this hast tree into its own
+ * component tree, resolving `<mk-directive>` elements through a registry and
+ * `data-mk-meta` on `<code>` elements however it likes (e.g. a collapsed
+ * script marker).
+ */
+export declare function toHast(text: string): HastRoot;

package/dist/to-hast.js

@@ -0,0 +1,176 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkDirective from 'remark-directive';
+import remarkGfm from 'remark-gfm';
+import remarkRehype from 'remark-rehype';
+import { visit } from 'unist-util-visit';
+/** The hast tag name our directive-tagging plugin marks directive nodes with. */
+const DIRECTIVE_TAG = 'mk-directive';
+function isDirectiveNode(node) {
+    return (node.type === 'containerDirective' ||
+        node.type === 'leafDirective' ||
+        node.type === 'textDirective');
+}
+/**
+ * Small remark plugin: tags every directive node with `data.hName` /
+ * `data.hProperties` so that `remark-rehype`'s default mdast->hast
+ * conversion turns it into a `<mk-directive>` hast element carrying the
+ * directive's name, raw attributes, and shape (inline vs block) as data-*
+ * properties. Inner markdown is left untouched, so it converts to hast
+ * exactly like any other node — this is what makes it become
+ * already-rendered `children` on the renderer side.
+ */
+const tagDirectiveNodes = () => (tree) => {
+    visit(tree, (node) => {
+        if (!isDirectiveNode(node))
+            return;
+        node.data = {
+            ...node.data,
+            hName: DIRECTIVE_TAG,
+            hProperties: {
+                'data-mk-name': node.name,
+                'data-mk-attrs': JSON.stringify(normalizeAttributes(node.attributes)),
+                'data-mk-kind': node.type,
+            },
+        };
+    });
+};
+/**
+ * mdast-util-directive represents a bare (valueless) attribute, e.g.
+ * `{collapsed}`, as an empty string. The registry-facing contract instead
+ * uses `null` for "present but valueless" — this normalization is what
+ * lands in the serialized `data-mk-attrs` JSON that the renderer parses
+ * back out.
+ */
+function normalizeAttributes(attributes) {
+    const result = {};
+    for (const [key, value] of Object.entries(attributes ?? {})) {
+        result[key] = value === '' || value == null ? null : value;
+    }
+    return result;
+}
+/**
+ * The hast/DOM attribute a fenced code block's raw `meta` string (e.g.
+ * `"{name=stars}"`) is preserved onto, since `mdast-util-to-hast`'s default
+ * `code` handler drops mdast `meta` entirely when building the hast
+ * `<code>` element.
+ */
+const CODE_META_ATTR = 'data-mk-meta';
+/**
+ * Small remark plugin: copies a code fence's raw `meta` string onto the
+ * mdast `code` node's `data.hProperties`, so it survives the mdast->hast
+ * conversion as a `data-mk-meta` attribute on the resulting `<code>`
+ * element (`mdast-util-to-hast`'s `code` handler applies `hProperties` to
+ * the `<code>` it builds, not the wrapping `<pre>` — see its
+ * `handlers/code.js`). This is deliberately generic meta *preservation*,
+ * not script detection: `@markii/core` stays framework-agnostic and knows
+ * nothing about "script blocks" here. A renderer that cares (e.g.
+ * `@markii/react`) reads this attribute and parses it with this package's
+ * `parseMetaAttributes` (`scripts.ts`) to decide whether a code block is a
+ * script; a renderer that doesn't care ignores the attribute and the block
+ * still renders as plain `<pre><code>` either way.
+ */
+const preserveCodeMeta = () => (tree) => {
+    visit(tree, 'code', (node) => {
+        if (!node.meta)
+            return;
+        node.data = {
+            ...node.data,
+            hProperties: { [CODE_META_ATTR]: node.meta },
+        };
+    });
+};
+/** URL schemes allowed in `href`/`src`, matched case-insensitively. */
+const SAFE_URL_PROTOCOLS = new Set(['http', 'https', 'mailto', 'tel']);
+/**
+ * Modelled on react-markdown's `defaultUrlTransform`, though our allowlist
+ * differs from theirs (we add `tel`; we drop `ircs` and `xmpp`) — see
+ * `SAFE_URL_PROTOCOLS` above for the actual list. A URL with no scheme
+ * (relative, fragment-only `#...`, or query-only `?...`) is always allowed;
+ * a URL with a scheme is allowed only if that scheme is in
+ * `SAFE_URL_PROTOCOLS`. Finding the "scheme" the same way a browser does —
+ * text before the first `:`, but only when that `:` comes before any `/`,
+ * `?`, or `#` — is what correctly rejects tricks like a leading space
+ * (`" javascript:..."`, whose slice-before-colon is `" javascript"`, which
+ * never matches a bare protocol name) while still allowing a same-origin
+ * path that happens to contain a colon later on.
+ *
+ * Exported (not just used by `sanitizeUrls` below) because a directive
+ * *attribute* that a renderer maps straight to a DOM URL prop — e.g.
+ * `@markii/react`'s `figure` component putting a `src` attribute into
+ * `<img src>` — never passes through `sanitizeUrls`, which only walks the
+ * hast tree `remark-rehype` itself produces from markdown links/images.
+ * Such a renderer must run the attribute value through this same check
+ * itself, rather than re-implementing URL-scheme parsing, to get the exact
+ * same guarantee.
+ */
+export function isSafeUrl(url) {
+    const colon = url.indexOf(':');
+    if (colon === -1)
+        return true;
+    const slash = url.indexOf('/');
+    const questionMark = url.indexOf('?');
+    const numberSign = url.indexOf('#');
+    const hasSchemeBeforeDelimiter = (slash === -1 || colon < slash) &&
+        (questionMark === -1 || colon < questionMark) &&
+        (numberSign === -1 || colon < numberSign);
+    if (!hasSchemeBeforeDelimiter)
+        return true;
+    return SAFE_URL_PROTOCOLS.has(url.slice(0, colon).toLowerCase());
+}
+/**
+ * hast tag name -> the one attribute on it that carries a URL. Null-prototype
+ * (rather than a plain object literal) so a hast tag named `constructor`,
+ * `toString`, etc. must miss this lookup rather than resolve to an
+ * inherited `Object.prototype` member.
+ */
+const URL_ATTRIBUTE_BY_TAG = Object.assign(Object.create(null), { a: 'href', img: 'src' });
+/**
+ * Strips `href` on `<a>` and `src` on `<img>` when they hold an unsafe URL
+ * (e.g. `javascript:`, `data:text/html`), mutating the hast tree in place.
+ * Runs after `remark-rehype`, so it covers every link/image the document
+ * produces regardless of source (CommonMark autolinks, `[text](url)`, raw
+ * `<a href>` — remark-rehype normalizes all of them to hast `element` nodes
+ * by this point). The element and its children are kept — only the
+ * dangerous attribute is dropped — so link text still renders, per the
+ * fallback-not-failure spirit of Architecture rule 3.
+ */
+function sanitizeUrls(tree) {
+    visit(tree, 'element', (node) => {
+        const attr = URL_ATTRIBUTE_BY_TAG[node.tagName];
+        if (!attr)
+            return;
+        const value = node.properties[attr];
+        if (typeof value === 'string' && !isSafeUrl(value)) {
+            delete node.properties[attr];
+        }
+    });
+}
+/**
+ * Converts Mark text straight to a sanitized hast tree: parse (mdast, with
+ * directive + GFM syntax extensions) -> tag directive nodes + preserve
+ * code-fence meta for hast conversion -> remark-rehype (hast) -> strip
+ * unsafe URLs. GFM constructs (tables, task lists, strikethrough, autolinks)
+ * need no tagging step of their own — `remark-rehype`'s default handlers
+ * already turn them into standard `<table>`/`<input type=checkbox>`/`<del>`/
+ * `<a>` hast elements, and `sanitizeUrls` below covers every `<a href>`/
+ * `<img src>` regardless of whether it came from a GFM autolink or an
+ * ordinary link. This is the framework-agnostic half of rendering —
+ * `@markii/react` (or any other renderer) turns this hast tree into its own
+ * component tree, resolving `<mk-directive>` elements through a registry and
+ * `data-mk-meta` on `<code>` elements however it likes (e.g. a collapsed
+ * script marker).
+ */
+export function toHast(text) {
+    const processor = unified()
+        .use(remarkParse)
+        .use(remarkDirective)
+        .use(remarkGfm)
+        .use(tagDirectiveNodes)
+        .use(preserveCodeMeta)
+        .use(remarkRehype);
+    const mdastTree = processor.parse(text);
+    const hastTree = processor.runSync(mdastTree);
+    sanitizeUrls(hastTree);
+    return hastTree;
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@markii/core",
+  "version": "0.1.0",
+  "description": "Framework-agnostic reference parser for Mark (.mk.md): CommonMark + directives to mdast, and mdast to a sanitized hast tree. Zero React dependency.",
+  "keywords": [
+    "markdown",
+    "mark",
+    "mk.md",
+    "mdast",
+    "hast",
+    "unified",
+    "directive",
+    "parser"
+  ],
+  "license": "MIT",
+  "author": "sadigaxund",
+  "homepage": "https://github.com/sadigaxund/markii#readme",
+  "bugs": "https://github.com/sadigaxund/markii/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sadigaxund/markii.git",
+    "directory": "packages/markii-core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./corpus": {
+      "types": "./dist/corpus.d.ts",
+      "import": "./dist/corpus.js",
+      "default": "./dist/corpus.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc --noEmit -p tsconfig.json",
+    "build:dist": "rm -rf dist && tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "corpus:regen": "node scripts/regen-corpus.ts"
+  },
+  "dependencies": {
+    "mdast-util-directive": "^3.1.0",
+    "remark-directive": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
+    "prettier": "^3.9.6"
+  }
+}