@markii/core 0.1.0 → 0.3.0

package/dist/corpus.js

@@ -3,7 +3,7 @@ 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
+ * expected-AST `*.json` siblings, living at the repo root (see docs/spec.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

package/dist/frontmatter.d.ts

@@ -0,0 +1,50 @@
+import type { Root } from 'mdast';
+/**
+ * A document's leading YAML frontmatter block, as far as this package cares
+ * about it: the raw text between the `---` fences, plus the one
+ * format-defined key (`uses`) when it is written in one of the two simple
+ * list forms this module understands.
+ *
+ * `raw` is the block's exact source text, unparsed — a host that genuinely
+ * needs arbitrary YAML metadata (its own `title`, `tags`, ...) brings its own
+ * YAML parser and reads this string. `@markii/core` deliberately does not:
+ * see `readUses` below.
+ */
+export interface Frontmatter {
+    /** The raw YAML text between the `---` fences (no fences, no trailing newline). */
+    raw: string;
+    /**
+     * Pack names from a `uses:` list written in one of the two supported
+     * forms, or `undefined` when the key is absent, is written in any other
+     * shape, or contains anything that is not a plain name. An empty list
+     * (`uses: []`) is `[]` — "declared, and it names no packs" — which is
+     * distinguishable from `undefined` ("no usable declaration").
+     */
+    uses?: string[];
+}
+/**
+ * The document's leading YAML frontmatter, or `undefined` when it has none.
+ *
+ * Accepts either the source text or an already-parsed tree, so a caller that
+ * has parsed the document already (the common case for a renderer) pays no
+ * second parse. Recognition is the PARSER's, not this module's: frontmatter
+ * is whatever `parse` produced as a leading `yaml` node, so the accessor and
+ * the renderer can never disagree about whether a `---` block at the top of
+ * a file was metadata or a thematic break.
+ *
+ * Never throws — `uses` simply degrades to `undefined` for anything beyond
+ * the two list forms `readUses` documents. A tree that did not come from
+ * this package's `parse` (a host that transforms the AST, or hand-builds
+ * one) is treated the same way: a leading node that merely CLAIMS to be
+ * `yaml` without carrying string content is no frontmatter at all, rather
+ * than a `raw.split` on a number.
+ */
+export declare function extractFrontmatter(source: string | Root): Frontmatter | undefined;
+/**
+ * Convenience wrapper over `extractFrontmatter`: just the `uses` list, or
+ * `undefined` when the document has no frontmatter, no `uses:` key, or a
+ * `uses:` value outside the two supported list forms. `uses` semantics
+ * (surfacing "pack not installed" in a host's UI) live with the host — this
+ * is only the reader.
+ */
+export declare function extractFrontmatterUses(source: string | Root): string[] | undefined;

package/dist/frontmatter.js

@@ -0,0 +1,178 @@
+import { parse } from './parse.js';
+/**
+ * The one format-defined frontmatter key (docs/format.md, docs/packs.md), as
+ * a top-level `uses:` line: the key at column 0 (so a `uses:` nested under
+ * some other mapping is deliberately invisible to this reader), optional
+ * spacing, then whatever follows the colon on the same line.
+ */
+const USES_LINE = /^uses[ \t]*:(.*)$/;
+/** One block-sequence item line: `- name`, capturing its indent and value. */
+const LIST_ITEM_LINE = /^([ \t]*)-[ \t]+(.*)$/;
+/**
+ * What a pack name may look like once quotes are stripped. Intentionally
+ * narrow: alphanumerics, `-`, `_`, `.` only (docs/packs.md — a namespace is
+ * a plain word, joined to a component name with `-` or `_`). Anything else —
+ * whitespace, `:`, `#`, brackets, braces, commas, a stray quote — means the
+ * value is not the simple scalar this reader claims to understand, so the
+ * whole list degrades to `undefined` rather than being half-read.
+ *
+ * A name like `__proto__` or `constructor` passes, and that is deliberate:
+ * this reader returns STRINGS in an array, never object keys, so a
+ * prototype-flavored name is ordinary data here. The registry lookups that
+ * eventually consume such a name are themselves null-prototype and
+ * `Object.hasOwn`-guarded (`@markii/react`'s `registry.ts`), which is where
+ * that class of defense belongs — not in a name filter that would have to
+ * guess every hostile spelling.
+ */
+const PACK_NAME = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+/**
+ * Reads one flow-sequence or block-sequence item: trims it, strips ONE pair
+ * of matching surrounding quotes (`'a'` / `"a"` — YAML's two quoting styles,
+ * used here only to unwrap a name, never to interpret escapes), and returns
+ * it only if what remains is a plain pack name. Returns `undefined` for
+ * anything else, including an opening quote with no matching close.
+ */
+function readItem(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return undefined;
+    const quote = trimmed[0];
+    let value = trimmed;
+    if (quote === '"' || quote === "'") {
+        if (trimmed.length < 2 || !trimmed.endsWith(quote))
+            return undefined;
+        value = trimmed.slice(1, -1);
+    }
+    return PACK_NAME.test(value) ? value : undefined;
+}
+/** Maps `readItem` over every raw item, failing the WHOLE list if any item fails. */
+function readItems(rawItems) {
+    const values = [];
+    for (const rawItem of rawItems) {
+        const value = readItem(rawItem);
+        if (value === undefined)
+            return undefined;
+        values.push(value);
+    }
+    return values;
+}
+/**
+ * Reads the flow form — `uses: [a, b]` — from the text that follows the
+ * colon. The text must be exactly a bracketed sequence: a trailing comment
+ * (`uses: [a] # note`) or any other suffix is NOT this form and yields
+ * `undefined`, since recognizing it would mean tokenizing YAML rather than
+ * matching one fixed shape. `[]` yields the empty list.
+ */
+function readFlowSequence(text) {
+    if (!text.startsWith('[') || !text.endsWith(']'))
+        return undefined;
+    const inner = text.slice(1, -1).trim();
+    if (inner === '')
+        return [];
+    return readItems(inner.split(','));
+}
+/**
+ * Reads the block form — a bare `uses:` followed by `- name` lines — from
+ * the lines after the key. Items must be contiguous (the first line that is
+ * not an item ends the sequence, blank lines included) and share one indent,
+ * which is what keeps a differently-indented continuation of some richer
+ * YAML structure from being mistaken for a flat list. No items, or a
+ * ragged/uneven sequence, yields `undefined`.
+ */
+function readBlockSequence(lines, start) {
+    const rawItems = [];
+    let indent;
+    for (const line of lines.slice(start)) {
+        const match = LIST_ITEM_LINE.exec(line);
+        const [, lineIndent, item] = match ?? [];
+        if (lineIndent === undefined || item === undefined)
+            break;
+        if (indent === undefined)
+            indent = lineIndent;
+        else if (lineIndent !== indent)
+            return undefined;
+        rawItems.push(item);
+    }
+    return rawItems.length > 0 ? readItems(rawItems) : undefined;
+}
+/**
+ * The hand-rolled `uses:` reader — the whole reason `@markii/core` needs no
+ * YAML library, exactly as `@markii/bundle`'s `manifest.ts` needs no schema
+ * library. It recognizes TWO shapes and nothing else:
+ *
+ * ```yaml
+ * uses: [ana, gh]      # flow sequence
+ * uses:                # block sequence
+ *   - ana
+ *   - gh
+ * ```
+ *
+ * quotes and surrounding whitespace tolerated in both. Every other input —
+ * a `uses:` holding a scalar or a nested mapping, a duplicated `uses:` key,
+ * an indented (non-top-level) `uses:`, a value this reader cannot recognize,
+ * or frontmatter that is not valid YAML at all — returns `undefined`. It
+ * NEVER throws and never returns a partially-read list: `uses` is an
+ * informative hint (docs/packs.md — "this note uses pack `ana`, which is not
+ * installed"), so "I could not read this" and "there is nothing here" are
+ * the same, harmless answer, while a half-read list would produce a wrong
+ * warning about packs the note never named.
+ */
+function readUses(raw) {
+    const lines = raw.split(/\r?\n/);
+    let keyIndex = -1;
+    let rest = '';
+    for (const [index, line] of lines.entries()) {
+        const [, value] = USES_LINE.exec(line) ?? [];
+        if (value === undefined)
+            continue;
+        // A second top-level `uses:` makes the document ambiguous (YAML itself
+        // rejects duplicate keys); refuse to guess which one was meant.
+        if (keyIndex !== -1)
+            return undefined;
+        keyIndex = index;
+        rest = value;
+    }
+    if (keyIndex === -1)
+        return undefined;
+    const inline = rest.trim();
+    return inline === ''
+        ? readBlockSequence(lines, keyIndex + 1)
+        : readFlowSequence(inline);
+}
+/**
+ * The document's leading YAML frontmatter, or `undefined` when it has none.
+ *
+ * Accepts either the source text or an already-parsed tree, so a caller that
+ * has parsed the document already (the common case for a renderer) pays no
+ * second parse. Recognition is the PARSER's, not this module's: frontmatter
+ * is whatever `parse` produced as a leading `yaml` node, so the accessor and
+ * the renderer can never disagree about whether a `---` block at the top of
+ * a file was metadata or a thematic break.
+ *
+ * Never throws — `uses` simply degrades to `undefined` for anything beyond
+ * the two list forms `readUses` documents. A tree that did not come from
+ * this package's `parse` (a host that transforms the AST, or hand-builds
+ * one) is treated the same way: a leading node that merely CLAIMS to be
+ * `yaml` without carrying string content is no frontmatter at all, rather
+ * than a `raw.split` on a number.
+ */
+export function extractFrontmatter(source) {
+    const tree = typeof source === 'string' ? parse(source) : source;
+    const first = tree.children[0];
+    if (first?.type !== 'yaml' || typeof first.value !== 'string') {
+        return undefined;
+    }
+    const raw = first.value;
+    const uses = readUses(raw);
+    return uses === undefined ? { raw } : { raw, uses };
+}
+/**
+ * Convenience wrapper over `extractFrontmatter`: just the `uses` list, or
+ * `undefined` when the document has no frontmatter, no `uses:` key, or a
+ * `uses:` value outside the two supported list forms. `uses` semantics
+ * (surfacing "pack not installed" in a host's UI) live with the host — this
+ * is only the reader.
+ */
+export function extractFrontmatterUses(source) {
+    return extractFrontmatter(source)?.uses;
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { parse } from './parse.js';
-export { toHast, isSafeUrl } from './to-hast.js';
-export { extractScripts, parseMetaAttributes, type ScriptBlock, } from './scripts.js';
+export { extractFrontmatter, extractFrontmatterUses, type Frontmatter, } from './frontmatter.js';
+export { toHast, nodeToHast, isSafeUrl, type MarkNode } from './to-hast.js';
+export { extractScripts, isBareAttribute, isValidScriptName, parseMetaAttributes, type ScriptBlock, } from './scripts.js';

package/dist/index.js

@@ -5,5 +5,6 @@
 // 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';
+export { extractFrontmatter, extractFrontmatterUses, } from './frontmatter.js';
+export { toHast, nodeToHast, isSafeUrl } from './to-hast.js';
+export { extractScripts, isBareAttribute, isValidScriptName, parseMetaAttributes, } from './scripts.js';

package/dist/parse.d.ts

@@ -2,6 +2,7 @@ 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
+ * optional leading YAML frontmatter (`remark-frontmatter`) 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 `:`/`::`/`:::`
@@ -13,5 +14,16 @@ import type { Root } from 'mdast';
  * 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).
+ *
+ * Frontmatter is the YAML preset only (`---` fences; the TOML `+++` form is
+ * deliberately not enabled) and, per micromark's frontmatter extension, is
+ * recognized ONLY as the very first construct of the document. Everywhere
+ * else `---` keeps its ordinary CommonMark meaning — a thematic break, or a
+ * setext heading underline — and an unterminated opening `---` degrades to
+ * exactly that too, never to an error (conformance fixtures 19-23). The
+ * resulting `yaml` node carries the raw block text and nothing more: this
+ * module does not interpret YAML, and `@markii/core` depends on no YAML
+ * library. `frontmatter.ts`'s hand-rolled accessor reads the one
+ * format-defined key (`uses`) off that raw text for the simple list forms.
  */
 export declare function parse(text: string): Root;

package/dist/parse.js

@@ -1,10 +1,12 @@
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkDirective from 'remark-directive';
+import remarkFrontmatter from 'remark-frontmatter';
 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
+ * optional leading YAML frontmatter (`remark-frontmatter`) 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 `:`/`::`/`:::`
@@ -16,10 +18,22 @@ import remarkGfm from 'remark-gfm';
  * 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).
+ *
+ * Frontmatter is the YAML preset only (`---` fences; the TOML `+++` form is
+ * deliberately not enabled) and, per micromark's frontmatter extension, is
+ * recognized ONLY as the very first construct of the document. Everywhere
+ * else `---` keeps its ordinary CommonMark meaning — a thematic break, or a
+ * setext heading underline — and an unterminated opening `---` degrades to
+ * exactly that too, never to an error (conformance fixtures 19-23). The
+ * resulting `yaml` node carries the raw block text and nothing more: this
+ * module does not interpret YAML, and `@markii/core` depends on no YAML
+ * library. `frontmatter.ts`'s hand-rolled accessor reads the one
+ * format-defined key (`uses`) off that raw text for the simple list forms.
  */
 export function parse(text) {
     const processor = unified()
         .use(remarkParse)
+        .use(remarkFrontmatter)
         .use(remarkDirective)
         .use(remarkGfm);
     return processor.parse(text);

package/dist/scripts.d.ts

@@ -1,6 +1,6 @@
 import type { Code, Root } from 'mdast';
 /**
- * Slice 1 of the scripting-usability layer (DESIGN.md §8): this module only
+ * Slice 1 of the scripting-usability layer (docs/scripting.md): 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
@@ -15,14 +15,46 @@ import type { Code, Root } from 'mdast';
  * 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).
+ *
+ * `publish`, when present, is always `true` — docs/scripting.md: "**Publishing is
+ * declarative**: the bare `publish` attribute on the script fence, no API to
+ * call." "Bare" is load-bearing: it is set ONLY when the fence spells the
+ * key with no `=value` at all (` ```lua {name=gh publish}` `, per
+ * `parseMetaAttributes`'s bare-key convention of yielding `''`). Any valued
+ * spelling — `publish=true`, `publish=yes`, `publish=1`, even `publish=false`
+ * or `publish=""` — is a DIFFERENT, undefined attribute, not the one the
+ * format specifies, and is silently ignored (the block simply does not
+ * publish), matching the format's "unrecognized input degrades, never
+ * throws" rule. This is deliberately fail-closed rather than lenient:
+ * publishing "writes beyond the note" (§8), so guessing at an unrecognized
+ * spelling risks writing to the shared vault when the author didn't mean to
+ * — silently NOT publishing is always the safe wrong answer, silently
+ * publishing never is. In particular `publish=false` must never be treated
+ * as an opt-out toggle that flips a default-on behavior; there is no such
+ * toggle, only the presence or absence of the one bare form.
+ *
+ * The field is only ever set when true, so a non-publishing block's shape is
+ * byte-identical to a `ScriptBlock` from before this field existed (no
+ * `publish: false` litter). Use `Object.hasOwn`/`'publish' in block` to test
+ * for absence, not falsiness.
  */
 export interface ScriptBlock {
     name: string;
     lang: string;
     src?: string;
     code: string;
+    publish?: true;
     position?: Code['position'];
 }
+/**
+ * Whether `name` is a legal script `name` (docs/scripting.md). Dots are
+ * deliberately excluded from the charset — `data=`/`:value[]` read a dot in
+ * a name as path traversal (`repo.stars` means "field `stars` of value
+ * `repo`"), which would make a dotted *script* name unreachable from either
+ * attribute. Fully anchored (`^`…`$`), so a trailing newline or any other
+ * stray character fails the match rather than being silently tolerated.
+ */
+export declare function isValidScriptName(name: string): boolean;
 /**
  * Parses a fence `meta` string's `{...}` attribute group into a flat
  * key/value map (bare `key` with no `=value` yields `''`). Returns an empty,
@@ -40,11 +72,43 @@ export interface ScriptBlock {
  * this purpose (see its `preserveCodeMeta` plugin).
  */
 export declare function parseMetaAttributes(meta: string | null | undefined): Record<string, string>;
+/**
+ * Whether `key` appears in `meta`'s `{...}` attribute group written
+ * genuinely bare (`key` with no `=value` at all — none of the three value
+ * alternatives in `ATTRIBUTE_TOKEN` matched). This is the ONE shared
+ * mechanism for a bare-only boolean fence-meta attribute (docs/scripting.md:
+ * "Boolean fence-meta attributes (`publish`, the reference renderer's
+ * `open`) are bare-only: writing any value — `publish=true` no less than
+ * `publish=false` — is not the boolean form and counts as absent. Fail
+ * closed: an unrecognized spelling must never enable behavior."). Used by
+ * `extractScripts` below for `publish`, and by `@markii/react`'s `PreElement`
+ * for `open` (see `ScriptBlock.publish`'s doc comment for why the
+ * bare/valued distinction matters).
+ *
+ * `parseMetaAttributes` collapses a bare key and an explicitly-empty quoted
+ * value (`key=""`) to the same `''` result in its flat map — the right
+ * choice for its general-purpose contract, but it erases exactly the
+ * distinction a bare-only attribute needs (`{publish}` must enable
+ * publishing; `{publish=""}` must not — and likewise `{open}` vs.
+ * `{open=""}`/`{open=true}`/`{open=false}`). So this walks the same token
+ * grammar directly instead of going through that already-flattened map.
+ * Like `parseMetaAttributes`, a key repeated in the group is "last
+ * occurrence wins" (the loop keeps overwriting `bare` for each match of
+ * `key`).
+ *
+ * Exported so a renderer (e.g. `@markii/react`) that defines its own
+ * bare-only boolean fence-meta attribute reuses this exact grammar instead
+ * of duplicating (and risking drift from) the bare/valued distinction here.
+ */
+export declare function isBareAttribute(meta: string | null | undefined, key: string): boolean;
 /**
  * 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.
+ * attribute group with a non-empty `name` that also matches the script-name
+ * charset (docs/scripting.md, `isValidScriptName`); a code block with no meta,
+ * meta with no `name`, or a `name` outside the charset (e.g. a dotted
+ * `repo.stars`) is ordinary code and is skipped — same display-only
+ * degradation either way, never an error and never a console message. 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

@@ -32,6 +32,28 @@ function findAttributeGroup(source) {
  * `key="quoted value"`, or `key='quoted value'`. Whitespace-separated.
  */
 const ATTRIBUTE_TOKEN = /([A-Za-z_][\w-]*)(?:=(?:"([^"]*)"|'([^']*)'|(\S+)))?/g;
+/**
+ * The full charset a script `name` may use (docs/scripting.md). Deliberately NOT
+ * `g`-flagged: a `g`-flagged `RegExp` carries `lastIndex` state across
+ * `.test()` calls (the exec-loop cursor from a previous match survives to
+ * the next call on the same instance), which silently makes alternating
+ * calls report wrong results — a real bug class. `ATTRIBUTE_TOKEN` above
+ * needs `g` because it's driven with `.exec()` in a loop and resets
+ * `lastIndex` itself each time; `isValidScriptName` has no such loop, so it
+ * gets a plain, stateless pattern instead.
+ */
+const SCRIPT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/**
+ * Whether `name` is a legal script `name` (docs/scripting.md). Dots are
+ * deliberately excluded from the charset — `data=`/`:value[]` read a dot in
+ * a name as path traversal (`repo.stars` means "field `stars` of value
+ * `repo`"), which would make a dotted *script* name unreachable from either
+ * attribute. Fully anchored (`^`…`$`), so a trailing newline or any other
+ * stray character fails the match rather than being silently tolerated.
+ */
+export function isValidScriptName(name) {
+    return SCRIPT_NAME_PATTERN.test(name);
+}
 /**
  * Parses a fence `meta` string's `{...}` attribute group into a flat
  * key/value map (bare `key` with no `=value` yields `''`). Returns an empty,
@@ -65,19 +87,69 @@ export function parseMetaAttributes(meta) {
     }
     return attrs;
 }
+/**
+ * Whether `key` appears in `meta`'s `{...}` attribute group written
+ * genuinely bare (`key` with no `=value` at all — none of the three value
+ * alternatives in `ATTRIBUTE_TOKEN` matched). This is the ONE shared
+ * mechanism for a bare-only boolean fence-meta attribute (docs/scripting.md:
+ * "Boolean fence-meta attributes (`publish`, the reference renderer's
+ * `open`) are bare-only: writing any value — `publish=true` no less than
+ * `publish=false` — is not the boolean form and counts as absent. Fail
+ * closed: an unrecognized spelling must never enable behavior."). Used by
+ * `extractScripts` below for `publish`, and by `@markii/react`'s `PreElement`
+ * for `open` (see `ScriptBlock.publish`'s doc comment for why the
+ * bare/valued distinction matters).
+ *
+ * `parseMetaAttributes` collapses a bare key and an explicitly-empty quoted
+ * value (`key=""`) to the same `''` result in its flat map — the right
+ * choice for its general-purpose contract, but it erases exactly the
+ * distinction a bare-only attribute needs (`{publish}` must enable
+ * publishing; `{publish=""}` must not — and likewise `{open}` vs.
+ * `{open=""}`/`{open=true}`/`{open=false}`). So this walks the same token
+ * grammar directly instead of going through that already-flattened map.
+ * Like `parseMetaAttributes`, a key repeated in the group is "last
+ * occurrence wins" (the loop keeps overwriting `bare` for each match of
+ * `key`).
+ *
+ * Exported so a renderer (e.g. `@markii/react`) that defines its own
+ * bare-only boolean fence-meta attribute reuses this exact grammar instead
+ * of duplicating (and risking drift from) the bare/valued distinction here.
+ */
+export function isBareAttribute(meta, key) {
+    if (!meta)
+        return false;
+    const group = findAttributeGroup(meta);
+    if (group === undefined)
+        return false;
+    ATTRIBUTE_TOKEN.lastIndex = 0;
+    let match;
+    let bare = false;
+    while ((match = ATTRIBUTE_TOKEN.exec(group)) !== null) {
+        if (match[1] !== key)
+            continue;
+        bare =
+            match[2] === undefined &&
+                match[3] === undefined &&
+                match[4] === undefined;
+    }
+    return bare;
+}
 /**
  * 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.
+ * attribute group with a non-empty `name` that also matches the script-name
+ * charset (docs/scripting.md, `isValidScriptName`); a code block with no meta,
+ * meta with no `name`, or a `name` outside the charset (e.g. a dotted
+ * `repo.stars`) is ordinary code and is skipped — same display-only
+ * degradation either way, never an error and never a console message. 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)
+        if (!name || !isValidScriptName(name))
             return;
         const block = {
             name,
@@ -86,6 +158,13 @@ export function extractScripts(tree) {
         };
         if (attrs.src)
             block.src = attrs.src;
+        // Bare-only, per `ScriptBlock.publish`'s doc comment and
+        // `isBareAttribute`'s: a plain `attrs.publish === ''` check can't tell
+        // `{publish}` from `{publish=""}` (both flatten to `''`), so this asks
+        // the token grammar directly instead of trusting the flattened map.
+        if (isBareAttribute(node.meta, 'publish')) {
+            block.publish = true;
+        }
         if (node.position)
             block.position = node.position;
         blocks.push(block);

package/dist/to-hast.d.ts

@@ -1,3 +1,4 @@
+import type { RootContent } from 'mdast';
 import type { Root as HastRoot } from 'hast';
 /**
  * Modelled on react-markdown's `defaultUrlTransform`, though our allowlist
@@ -38,3 +39,41 @@ export declare function isSafeUrl(url: string): boolean;
  * script marker).
  */
 export declare function toHast(text: string): HastRoot;
+/**
+ * One mdast node as this package's `parse` produces it (a member of a
+ * `Root`'s `children` array — `mdast`'s own `RootContent` union). Re-exported
+ * under this package's naming so a consumer (e.g. `@markii/react`'s
+ * `renderMarkNode`) can type a "single already-parsed node" parameter without
+ * adding its own `@types/mdast` dependency — `@markii/core` already depends
+ * on it.
+ */
+export type MarkNode = RootContent;
+/**
+ * Converts a single already-parsed mdast node (as produced by this package's
+ * `parse`, e.g. one top-level child of its `Root`) to a sanitized hast tree,
+ * running the exact SAME pipeline as `toHast` — see `createProcessor` above,
+ * the one shared plugin-list source of truth — over a synthetic mdast `root`
+ * wrapping just this node. Directive tagging, code-meta preservation, and URL
+ * sanitizing (`sanitizeUrls`) all run identically to the whole-document path;
+ * the only difference is skipping `processor.parse` (there is no text to
+ * parse — `node` is already an AST) and wrapping in a throwaway root instead
+ * of using the document's own.
+ *
+ * Pure: `node` is deep-cloned (`structuredClone` — mdast nodes are plain
+ * JSON-safe data) before the pipeline runs, so the plugins' in-place
+ * `data.hName`/`data.hProperties` mutations never touch the caller's node.
+ *
+ * Hardened: because this entry point takes an AST rather than text, the
+ * clone is also stripped of every node's `data` — the caller-controllable
+ * hast-override channel — before the pipeline runs, so a hand-built or
+ * transformed node cannot dictate the emitted tag/attributes (e.g. a
+ * `data.hName: 'script'` injection). See `stripHastOverrides`.
+ *
+ * Never throws, matching `toHast`'s and Architecture rule 3's
+ * never-throw-on-odd-input guarantee: an inline/text-level node at the root
+ * of the synthetic tree, a `code` node with malformed `meta`, or a
+ * container-directive subtree left over from an unclosed fence may all
+ * produce degraded hast (in the worst case, an empty root — `emptyHastRoot`),
+ * but the call itself cannot fail.
+ */
+export declare function nodeToHast(node: MarkNode): HastRoot;

package/dist/to-hast.js

@@ -1,6 +1,7 @@
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkDirective from 'remark-directive';
+import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
 import remarkRehype from 'remark-rehype';
 import { visit } from 'unist-util-visit';
@@ -146,6 +147,37 @@ function sanitizeUrls(tree) {
         }
     });
 }
+/**
+ * The ONE source of truth for the mdast->hast pipeline's plugin list, shared
+ * by `toHast` (whole-document) and `nodeToHast` (single-node) below —
+ * exactly one `.use()` chain exists in this module so the two entry points
+ * cannot drift apart on directive tagging, code-meta preservation, or the
+ * remark-rehype conversion itself. Building a fresh processor per call
+ * (rather than a shared module-level instance) matches `unified`'s own
+ * immutable-processor model (`.use()` returns a new processor) and keeps
+ * each call's `.parse`/`.runSync` free of any state left over from a
+ * previous call.
+ *
+ * The plugin list mirrors `parse.ts` exactly (frontmatter, directives, GFM),
+ * so what `parse` accepts and what this pipeline renders can never disagree
+ * about the grammar. Frontmatter needs no tagging step of its own: a leading
+ * `---` block becomes an mdast `yaml` node, and `mdast-util-to-hast`'s
+ * default handler for `yaml` is its `ignore` handler, so the block is
+ * DROPPED from the hast tree rather than leaking into the rendered document
+ * as text (pinned by `to-hast.test.ts`, since that drop is a rendering
+ * guarantee of the format, not an incidental upstream default). Metadata is
+ * read from the AST via `frontmatter.ts`, never rendered.
+ */
+function createProcessor() {
+    return unified()
+        .use(remarkParse)
+        .use(remarkFrontmatter)
+        .use(remarkDirective)
+        .use(remarkGfm)
+        .use(tagDirectiveNodes)
+        .use(preserveCodeMeta)
+        .use(remarkRehype);
+}
 /**
  * Converts Mark text straight to a sanitized hast tree: parse (mdast, with
  * directive + GFM syntax extensions) -> tag directive nodes + preserve
@@ -162,15 +194,96 @@ function sanitizeUrls(tree) {
  * script marker).
  */
 export function toHast(text) {
-    const processor = unified()
-        .use(remarkParse)
-        .use(remarkDirective)
-        .use(remarkGfm)
-        .use(tagDirectiveNodes)
-        .use(preserveCodeMeta)
-        .use(remarkRehype);
+    const processor = createProcessor();
     const mdastTree = processor.parse(text);
     const hastTree = processor.runSync(mdastTree);
     sanitizeUrls(hastTree);
     return hastTree;
 }
+/**
+ * Deletes `data` from every node in `tree`, in place.
+ *
+ * Security-relevant, and specific to the single-node path. mdast `data` is
+ * the documented channel for overriding hast output — `mdast-util-to-hast`
+ * reads `data.hName`, `data.hProperties`, and `data.hChildren` and will emit
+ * *any* tag with *any* attributes a node asks for. `toHast` can never be
+ * handed such a node: it takes TEXT and parses it itself, and
+ * `remark-parse`/`remark-directive`/`remark-gfm` never populate `data` on the
+ * nodes they produce. `nodeToHast` instead accepts an already-built AST from
+ * the caller, so without this step a node carrying
+ * `data.hName = 'script'` + `data.hProperties = { src: 'javascript:...' }`
+ * would convert to a real `<script src="javascript:...">` hast element —
+ * bypassing `sanitizeUrls` entirely, since that only guards `a[href]` and
+ * `img[src]`. Any host that transforms the AST between `parse` and rendering
+ * (or renders a node built from untrusted input) would inherit an injection
+ * path that the document path simply does not have.
+ *
+ * Deleting `data` WHOLESALE, rather than allowlisting away the three known
+ * `h*` keys, is the deliberate choice: it is fail-closed by construction (a
+ * future `mdast-util-to-hast` release that honors a fourth `data.h*` key
+ * cannot silently reopen this hole, whereas a hardcoded three-name denylist
+ * would), and it costs nothing in fidelity — since parser-produced nodes
+ * carry no `data` at all, stripping it reproduces exactly the shape the
+ * document path feeds the pipeline. The pipeline's own tagging
+ * (`tagDirectiveNodes`, `preserveCodeMeta`) runs AFTER this and repopulates
+ * `data` itself, so directives and code fences are unaffected.
+ */
+function stripHastOverrides(tree) {
+    visit(tree, (node) => {
+        if (node.data !== undefined)
+            delete node.data;
+    });
+}
+/**
+ * An empty hast root, returned by `nodeToHast` when the pipeline itself
+ * throws on odd input (Architecture rule 3's never-throw guarantee, extended
+ * to the single-node path) — degraded output, never an exception.
+ */
+function emptyHastRoot() {
+    return { type: 'root', children: [] };
+}
+/**
+ * Converts a single already-parsed mdast node (as produced by this package's
+ * `parse`, e.g. one top-level child of its `Root`) to a sanitized hast tree,
+ * running the exact SAME pipeline as `toHast` — see `createProcessor` above,
+ * the one shared plugin-list source of truth — over a synthetic mdast `root`
+ * wrapping just this node. Directive tagging, code-meta preservation, and URL
+ * sanitizing (`sanitizeUrls`) all run identically to the whole-document path;
+ * the only difference is skipping `processor.parse` (there is no text to
+ * parse — `node` is already an AST) and wrapping in a throwaway root instead
+ * of using the document's own.
+ *
+ * Pure: `node` is deep-cloned (`structuredClone` — mdast nodes are plain
+ * JSON-safe data) before the pipeline runs, so the plugins' in-place
+ * `data.hName`/`data.hProperties` mutations never touch the caller's node.
+ *
+ * Hardened: because this entry point takes an AST rather than text, the
+ * clone is also stripped of every node's `data` — the caller-controllable
+ * hast-override channel — before the pipeline runs, so a hand-built or
+ * transformed node cannot dictate the emitted tag/attributes (e.g. a
+ * `data.hName: 'script'` injection). See `stripHastOverrides`.
+ *
+ * Never throws, matching `toHast`'s and Architecture rule 3's
+ * never-throw-on-odd-input guarantee: an inline/text-level node at the root
+ * of the synthetic tree, a `code` node with malformed `meta`, or a
+ * container-directive subtree left over from an unclosed fence may all
+ * produce degraded hast (in the worst case, an empty root — `emptyHastRoot`),
+ * but the call itself cannot fail.
+ */
+export function nodeToHast(node) {
+    try {
+        const cloned = structuredClone(node);
+        const root = { type: 'root', children: [cloned] };
+        // Before the pipeline runs: drop any caller-supplied hast overrides
+        // (`data.hName`/`hProperties`/`hChildren`) so only this pipeline's own
+        // tagging can influence the hast output. See `stripHastOverrides`.
+        stripHastOverrides(root);
+        const processor = createProcessor();
+        const hastTree = processor.runSync(root);
+        sanitizeUrls(hastTree);
+        return hastTree;
+    }
+    catch {
+        return emptyHastRoot();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/core",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -51,8 +51,11 @@
     "corpus:regen": "node scripts/regen-corpus.ts"
   },
   "dependencies": {
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
     "mdast-util-directive": "^3.1.0",
     "remark-directive": "^4.0.0",
+    "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
@@ -60,8 +63,6 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
-    "@types/hast": "^3.0.5",
-    "@types/mdast": "^4.0.4",
     "prettier": "^3.9.6"
   }
 }