@markii/html 0.6.0

package/dist/render.js

@@ -0,0 +1,417 @@
+import { toHast, nodeToHast, parseMetaAttributes, isValidScriptName, isBareAttribute, } from '@markii/core';
+import { toHtml } from 'hast-util-to-html';
+import { readRegistryComponent, resolveDirectiveAlias } from './registry.js';
+import { resolveLayoutAttributes } from './layout.js';
+import { escapeHtml } from './escape.js';
+import { resolveScopedPath } from './resolve.js';
+import { failureKindClass, failureTitle } from './failure-presentation.js';
+import { stringifyStoredValue } from './value-format.js';
+/** The hast tag name `@markii/core`'s `toHast` marks every directive with (`to-hast.ts`'s `DIRECTIVE_TAG`). */
+const DIRECTIVE_TAG = 'mk-directive';
+/** `data-mk-kind` value for a TEXT (inline) directive; the other two kinds (`leafDirective`/`containerDirective`) are block. */
+const TEXT_DIRECTIVE_KIND = 'textDirective';
+/** The reserved built-in for render-time value interpolation (§8: `:value[name]`). */
+const VALUE_DIRECTIVE_NAME = 'value';
+/** The one attribute key that binds a directive to the value store rather than passing through (§8: `data=name`). */
+const DATA_ATTRIBUTE_KEY = 'data';
+/** The attribute `@markii/core` preserves a code fence's raw `meta` string onto (`to-hast.ts`'s `preserveCodeMeta`). */
+const CODE_META_ATTR = 'data-mk-meta';
+/** The bare-only meta attribute that opens a script marker expanded (§8; bare-only, fail-closed). */
+const OPEN_ATTRIBUTE_KEY = 'open';
+/**
+ * Wraps a finished HTML string as a hast `raw` node. A `raw` node is not in
+ * the standard `hast` content unions, but `hast-util-to-html` emits its value
+ * verbatim under `allowDangerousHtml` — so every directive, script marker, and
+ * fallback the engine produces re-enters the tree this way, and a single
+ * `toHtml` pass serializes the plain hast around them while their already-built
+ * HTML passes through untouched.
+ */
+function raw(value) {
+    return { type: 'raw', value };
+}
+/** Serializes a run of (already-transformed) hast content to an HTML string, passing `raw` nodes through verbatim. */
+function serialize(children) {
+    const root = { type: 'root', children };
+    return toHtml(root, { allowDangerousHtml: true });
+}
+/**
+ * Builds the missing/stale/resolved `<span>` for a resolved value name,
+ * matching `@markii/react`'s `ValueDirective` markup and class names
+ * byte-for-byte: `mk-value mk-value--missing` (+ a failure-kind modifier
+ * class, only for a genuine `'error'` resolution) with `{name}` as the
+ * label when nothing resolved; `mk-value` (+ `mk-value--stale`) with the
+ * stringified value otherwise. Never throws.
+ */
+function buildValueMarker(name, resolved) {
+    if (resolved.status === 'missing' || resolved.status === 'error') {
+        const failureKind = resolved.status === 'error' ? resolved.failureKind : undefined;
+        const kindClass = failureKindClass('mk-value', failureKind);
+        const className = kindClass
+            ? `mk-value mk-value--missing ${kindClass}`
+            : 'mk-value mk-value--missing';
+        const title = failureTitle(resolved.error, failureKind);
+        const titleAttr = title ? ` title="${escapeHtml(title)}"` : '';
+        const label = name ? `{${escapeHtml(name)}}` : '{value}';
+        return `<span class="${className}"${titleAttr}>${label}</span>`;
+    }
+    const className = resolved.status === 'stale' ? 'mk-value mk-value--stale' : 'mk-value';
+    return `<span class="${className}">${escapeHtml(stringifyStoredValue(resolved.value))}</span>`;
+}
+/**
+ * Builds the base `HtmlRenderContext` for one top-level render call, bound
+ * to `scope` (the store/vault this render was invoked with). `resolve` and
+ * `valueMarker` never throw, matching `resolveScopedPath`'s own contract.
+ * The `data*` fields are attached per-directive later (see
+ * `withDataBinding`) — this base object never carries them.
+ */
+function createBaseContext(scope) {
+    return {
+        esc: escapeHtml,
+        resolve(name) {
+            const trimmed = name.trim();
+            if (!trimmed)
+                return { value: undefined, status: 'missing' };
+            return resolveScopedPath(scope, trimmed);
+        },
+        valueMarker(name) {
+            const trimmed = name.trim();
+            const resolved = trimmed
+                ? resolveScopedPath(scope, trimmed)
+                : { value: undefined, status: 'missing' };
+            return buildValueMarker(trimmed, resolved);
+        },
+    };
+}
+/** `ctx` with one directive's resolved `data=` binding attached, for the single component invocation that binding belongs to. */
+function withDataBinding(ctx, binding) {
+    if (!('data' in binding))
+        return ctx;
+    return {
+        ...ctx,
+        data: binding.data,
+        dataStatus: binding.dataStatus,
+        dataError: binding.dataError,
+        dataFailureKind: binding.dataFailureKind,
+    };
+}
+/**
+ * Splits a `data=<name>` attribute (if present) off `attributes`, resolves
+ * `<name>` against `scope` — dotted paths and `@`-prefixed vault names both
+ * work, via `resolveScopedPath` — and returns the resolved binding plus the
+ * remaining attributes. Never throws: no store/vault, an empty `data`
+ * attribute, or an unresolved path all degrade to `dataStatus: 'missing'`
+ * with `data: undefined`. Mirrors `@markii/react`'s `resolveDataAttribute`.
+ */
+function resolveDataAttribute(attributes, scope) {
+    if (!Object.hasOwn(attributes, DATA_ATTRIBUTE_KEY)) {
+        return { attributes };
+    }
+    const { [DATA_ATTRIBUTE_KEY]: rawName, ...rest } = attributes;
+    if (!rawName) {
+        return { attributes: rest, data: undefined, dataStatus: 'missing' };
+    }
+    const resolved = resolveScopedPath(scope, rawName);
+    return {
+        attributes: rest,
+        data: resolved.value,
+        dataStatus: resolved.status,
+        dataError: resolved.error,
+        dataFailureKind: resolved.status === 'error' ? resolved.failureKind : undefined,
+    };
+}
+/** Parses the `data-mk-attrs` JSON back into an attribute map, keeping only string/null values. Never throws. */
+function parseAttributes(json) {
+    if (!json)
+        return {};
+    try {
+        const parsed = JSON.parse(json);
+        if (parsed === null ||
+            typeof parsed !== 'object' ||
+            Array.isArray(parsed)) {
+            return {};
+        }
+        const result = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === 'string' || value === null || value === undefined) {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+/** A directive property read back as a string, or `undefined` if absent or non-string. */
+function stringProperty(element, name) {
+    const value = element.properties?.[name];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Whether `entry` is a BLOCK component written inline (docs/spec.md's
+ * one-directional form/kind mismatch). Only an explicit `inline: false`
+ * counts; a throwing `inline` getter fails permissive, identical to an absent
+ * flag, so hostile registry configuration can never throw out of the render.
+ */
+function isFormMismatch(entry, kind) {
+    if (kind !== TEXT_DIRECTIVE_KIND)
+        return false;
+    try {
+        return entry.inline === false;
+    }
+    catch {
+        return false;
+    }
+}
+/** The fallback label line, worded for the reason and the form the directive was written in. Returns HTML. */
+function fallbackLabel(name, inline, reason) {
+    const code = `<code>${escapeHtml(name)}</code>`;
+    if (reason === 'form-mismatch') {
+        return inline
+            ? `block component ${code} written inline`
+            : `inline component ${code} written as a block`;
+    }
+    return `unknown component ${code}`;
+}
+/**
+ * The unknown-directive fallback, matching `@markii/react`'s `UnknownDirective`
+ * markup and class names byte-for-byte so one stylesheet covers both renderers.
+ * An inline directive is built from `<span>`s (it lives inside a paragraph); a
+ * block directive gets the dashed `<div>` box with its inner content preserved.
+ */
+function unknownDirective(name, inline, childrenHtml, reason) {
+    const reasonClass = reason === 'form-mismatch' ? ' mk-unknown--mismatch' : '';
+    const label = fallbackLabel(name, inline, reason);
+    if (inline) {
+        return (`<span class="mk-unknown mk-unknown--inline${reasonClass}">` +
+            `<span class="mk-unknown__label">${label}</span>` +
+            `${childrenHtml}</span>`);
+    }
+    const content = childrenHtml
+        ? `<div class="mk-unknown__content">${childrenHtml}</div>`
+        : '';
+    return (`<div class="mk-unknown mk-unknown--block${reasonClass}">` +
+        `<p class="mk-unknown__label">${label}</p>${content}</div>`);
+}
+/**
+ * A registered component that threw while rendering. `@markii/react` lets a
+ * third-party component's throw reach the host's error boundary; a string
+ * engine has none, so a throw is contained here to a neutral box rather than
+ * failing the whole document. Never advertised as "unknown" (it is registered)
+ * and never dumps the error text into the page (cleanliness principle).
+ */
+function componentError(name, inline, childrenHtml) {
+    const code = `<code>${escapeHtml(name)}</code>`;
+    if (inline) {
+        return (`<span class="mk-unknown mk-unknown--inline mk-unknown--error">` +
+            `<span class="mk-unknown__label">component ${code} failed to render</span>` +
+            `${childrenHtml}</span>`);
+    }
+    const content = childrenHtml
+        ? `<div class="mk-unknown__content">${childrenHtml}</div>`
+        : '';
+    return (`<div class="mk-unknown mk-unknown--block mk-unknown--error">` +
+        `<p class="mk-unknown__label">component ${code} failed to render</p>` +
+        `${content}</div>`);
+}
+/**
+ * Flattens a directive's inner hast children back to plain text, for
+ * `:value[name]`'s label (§8: a bare value name). Only top-level TEXT nodes
+ * contribute; a nested element (markup the format never asks authors to
+ * write inside the label) contributes nothing rather than being partially
+ * serialized — mirrors `@markii/react`'s `ValueDirective`'s
+ * `extractPlainText`, adapted from a React-children walk to a hast-children
+ * walk since this engine never builds a React tree.
+ */
+function extractPlainText(children) {
+    let text = '';
+    for (const child of children) {
+        if (child.type === 'text')
+            text += child.value;
+    }
+    return text;
+}
+/** The first element child of `node` named `tagName`, or `undefined`. */
+function findChildElement(node, tagName) {
+    for (const child of node.children) {
+        if (child.type === 'element' && child.tagName === tagName)
+            return child;
+    }
+    return undefined;
+}
+/** The fence's `language-<lang>` tag from a `<code>` element's class list, or `''`. */
+function getLanguage(codeNode) {
+    const className = codeNode?.properties?.className;
+    const list = Array.isArray(className) ? className : [];
+    for (const name of list) {
+        if (typeof name === 'string' && name.startsWith('language-')) {
+            return name.slice('language-'.length);
+        }
+    }
+    return '';
+}
+/** The exact fence body text from a `<code>` element's text children, minus the single trailing newline mdast-util-to-hast appends. */
+function getCodeText(codeNode) {
+    if (!codeNode)
+        return '';
+    let text = '';
+    for (const child of codeNode.children) {
+        if (child.type === 'text')
+            text += child.value;
+    }
+    return text.endsWith('\n') ? text.slice(0, -1) : text;
+}
+/**
+ * Folds a script code block (a fence whose meta carries `{name=...}` with a
+ * valid script name) into a collapsed `<details>` marker, matching
+ * `@markii/react`'s `ScriptMarker` markup. Returns `undefined` for any other
+ * `<pre>` so the caller serializes it as an ordinary code block. Never throws.
+ */
+function renderScriptMarker(node) {
+    try {
+        const codeNode = findChildElement(node, 'code');
+        const meta = codeNode
+            ? (codeNode.properties?.[CODE_META_ATTR] ?? undefined)
+            : undefined;
+        if (typeof meta !== 'string')
+            return undefined;
+        const attrs = parseMetaAttributes(meta);
+        const name = attrs.name;
+        if (!name || !isValidScriptName(name))
+            return undefined;
+        const src = attrs.src || undefined;
+        const detail = src ?? getLanguage(codeNode);
+        const summary = detail ? `⚙ ${name} · ${detail}` : `⚙ ${name}`;
+        const open = isBareAttribute(meta, OPEN_ATTRIBUTE_KEY);
+        const code = getCodeText(codeNode);
+        const body = code
+            ? `<pre class="mk-script__code"><code>${escapeHtml(code)}</code></pre>`
+            : `<p class="mk-script__empty">${src ? `source: ${escapeHtml(src)}` : 'no inline body'}</p>`;
+        return (`<details class="mk-script"${open ? ' open' : ''}>` +
+            `<summary class="mk-script__summary">${escapeHtml(summary)}</summary>` +
+            `${body}</details>`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolves one directive (registry component, `:value[...]`, or the fallback) given its layout-stripped attributes. Never throws. */
+function renderDirectiveContent(name, kind, attributes, childrenHtml, plainLabel, registry, ctx, scope) {
+    if (name === VALUE_DIRECTIVE_NAME)
+        return ctx.valueMarker(plainLabel);
+    const inline = kind === TEXT_DIRECTIVE_KIND;
+    const entry = Object.hasOwn(registry, name) ? registry[name] : undefined;
+    const component = readRegistryComponent(entry);
+    if (!entry || component == null) {
+        return unknownDirective(name || '(unnamed)', inline, childrenHtml, 'unregistered');
+    }
+    if (isFormMismatch(entry, kind)) {
+        return unknownDirective(name || '(unnamed)', inline, childrenHtml, 'form-mismatch');
+    }
+    const binding = resolveDataAttribute(attributes, scope);
+    try {
+        return component(binding.attributes, childrenHtml, withDataBinding(ctx, binding));
+    }
+    catch {
+        return componentError(name || '(unnamed)', inline, childrenHtml);
+    }
+}
+/** Turns one `<mk-directive>` element (children already transformed) into its HTML string, including the layout wrapper for block directives. */
+function renderDirective(element, registry, ctx, scope) {
+    const written = stringProperty(element, 'data-mk-name') ?? '';
+    const kind = stringProperty(element, 'data-mk-kind');
+    const rawAttributes = parseAttributes(stringProperty(element, 'data-mk-attrs'));
+    const childrenHtml = serialize(element.children);
+    const plainLabel = written === VALUE_DIRECTIVE_NAME ? extractPlainText(element.children) : '';
+    const { name, attributes: aliased } = written === VALUE_DIRECTIVE_NAME
+        ? { name: written, attributes: rawAttributes }
+        : resolveDirectiveAlias(registry, written, rawAttributes);
+    const isBlock = kind !== TEXT_DIRECTIVE_KIND;
+    const { attributes, className } = resolveLayoutAttributes(aliased);
+    const content = renderDirectiveContent(name, kind, attributes, childrenHtml, plainLabel, registry, ctx, scope);
+    return isBlock && className
+        ? `<div class="${escapeHtml(className)}">${content}</div>`
+        : content;
+}
+/**
+ * Post-order tree transform: every `<mk-directive>` and every script `<pre>`
+ * is replaced by a `raw` node carrying its finished HTML, and every other
+ * element is left in place with its children transformed. A single `serialize`
+ * pass afterward emits the whole tree. Directives are processed after their
+ * children so a nested directive is already resolved by the time its parent
+ * serializes it.
+ */
+function makeTransform(registry, ctx, scope) {
+    function transform(node) {
+        if (node.type !== 'element')
+            return node;
+        node.children = node.children.map((child) => transform(child));
+        if (node.tagName === DIRECTIVE_TAG)
+            return raw(renderDirective(node, registry, ctx, scope));
+        if (node.tagName === 'pre') {
+            const marker = renderScriptMarker(node);
+            if (marker !== undefined)
+                return raw(marker);
+        }
+        return node;
+    }
+    return transform;
+}
+/** The shared "failed to render" fallback box, matching `@markii/react`'s. Never itself throws. */
+function renderFailureFallback(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (`<div class="mk-unknown mk-unknown--block" role="alert">` +
+        `<p class="mk-unknown__label">failed to render document</p>` +
+        `<pre class="mk-unknown__content">${escapeHtml(message)}</pre></div>`);
+}
+function renderRoot(root, registry, scope) {
+    const ctx = createBaseContext(scope);
+    const transform = makeTransform(registry, ctx, scope);
+    root.children = root.children.map(transform);
+    return serialize(root.children);
+}
+/**
+ * Renders Markii text to a static HTML string using `registry` to resolve
+ * directive names. Pipeline: `@markii/core`'s `toHast` (parse -> tag directive
+ * nodes -> remark-rehype -> sanitize URLs) -> a hast->HTML walk that swaps
+ * directive elements for registry components (or the unknown-directive
+ * fallback) and folds script fences into markers. Pure and never-throwing:
+ * parsing is tolerant, unknown names always render a fallback, and any
+ * unexpected internal error degrades to the "failed to render document" box.
+ *
+ * `store` is the note's value store (`@markii/runtime`, §8's pure read path)
+ * — optional, matching how a missing/absent value degrades gracefully: with
+ * no store, `:value[name]` renders its missing-value marker and every
+ * `data=name` attribute resolves to `dataStatus: 'missing'`, but the
+ * document still renders completely.
+ *
+ * `vault` is the optional app-scoped read seam (`@markii/runtime`'s
+ * `VaultStore`) that an `@`-prefixed name (`data=@gh.stars`,
+ * `:value[@gh.stars]`) resolves against instead of `store` — "bare name =
+ * mine, `@name` = the vault's". With no `vault` supplied, every `@name`
+ * degrades to `'missing'` the same way an absent `store` degrades a bare
+ * name.
+ */
+export function renderMarkToHtml(text, registry, store, vault) {
+    try {
+        return renderRoot(toHast(text), registry, { store, vault });
+    }
+    catch (error) {
+        return renderFailureFallback(error);
+    }
+}
+/**
+ * The block-level twin of `renderMarkToHtml`: renders one already-parsed mdast
+ * node (`@markii/core`'s `MarkNode`) to HTML instead of a whole document's
+ * text, via `nodeToHast`. Same registry resolution, same fallbacks, same
+ * purity and never-throw guarantees, and the same optional `store`/`vault`
+ * value-binding arguments.
+ */
+export function renderMarkNodeToHtml(node, registry, store, vault) {
+    try {
+        return renderRoot(nodeToHast(node), registry, { store, vault });
+    }
+    catch (error) {
+        return renderFailureFallback(error);
+    }
+}

package/dist/resolve.d.ts

@@ -0,0 +1,59 @@
+import type { FailureKind, ValueStatus, ValueStore, VaultStore } from '@markii/runtime';
+/**
+ * The string engine's port of `@markii/react`'s `store-path.ts`: resolves a
+ * `data=`/`:value[]` name (optionally dotted, optionally `@`-prefixed for the
+ * vault) against a `ValueStore`/`VaultStore`. Ported rather than imported
+ * because `store-path.ts` is not part of `@markii/react`'s public export
+ * surface, and the two platform renderers are deliberately independent
+ * implementations of the same contract (docs/scripting.md), not a shared
+ * runtime dependency on each other. The resolution semantics — dotted-path
+ * walk, `@`-scoping, never-throw-on-a-hostile-store — are kept identical to
+ * the React port; only the presentation layer built on top differs by engine.
+ */
+/** What resolving a (possibly dotted) name against a `ValueStore`/`VaultStore` produces. */
+export interface StorePathResolution {
+    value: unknown;
+    status: ValueStatus;
+    /** The root entry's error message, if it has one — carried through regardless of how the rest of the path resolved. Always a `string` when present. */
+    error?: string;
+    /** The root entry's `failureKind`, carried through exactly like `error`. Absent when the root entry didn't carry one, or on a host-store fault (never invented). */
+    failureKind?: FailureKind;
+}
+/**
+ * Best-effort description of something host code threw, for the tooltip
+ * channel. Every step is itself guarded: `instanceof`, `.message`, and
+ * `String(...)` can all throw when the thrown value is a revoked `Proxy` or
+ * an object with hostile traps/getters.
+ */
+export declare function describeHostFault(err: unknown): string;
+/** The one-character prefix that routes a `data=`/`:value[]` name at the vault store instead of the note store (docs/scripting.md). */
+export declare const VAULT_NAME_PREFIX = "@";
+/** Where a `resolveScopedPath` lookup may read from. Either half may be absent. */
+export interface ValueScope {
+    store?: ValueStore;
+    vault?: VaultStore;
+}
+/**
+ * Resolves a `data=`/`:value[]` name against `store`, walking a dotted path.
+ * Never throws, including against a hostile or buggy host store.
+ */
+export declare function resolveStorePath(store: ValueStore | undefined, dottedName: string): StorePathResolution;
+/**
+ * Resolves a `data=`/`:value[]` name against a `ValueScope`, routing an
+ * `@`-prefixed name at `scope.vault` instead of `scope.store` ("bare name =
+ * mine, `@name` = the vault's"). Never throws.
+ */
+export declare function resolveScopedPath(scope: ValueScope, dottedName: string): StorePathResolution;
+/** What `safeRead` produces: the extracted fields, plus the thrown message when the extraction had to be abandoned. */
+export interface SafeRead<T> {
+    fields: T;
+    fault?: string;
+}
+/**
+ * Runs `read` — an extraction that touches an untrusted bound `data` value —
+ * and falls back to `fallback()` if any part of it throws. Ported from
+ * `@markii/react`'s `safe-data.ts`: wraps the WHOLE extraction, not each
+ * individual property read, so a value whose reads throw degrades to the
+ * same "nothing resolved" state a genuinely missing binding already renders.
+ */
+export declare function safeRead<T>(read: () => T, fallback: () => T): SafeRead<T>;

package/dist/resolve.js

@@ -0,0 +1,154 @@
+const MISSING = { value: undefined, status: 'missing' };
+/** `ValueStatus`'s members, for validating a status read back off an untrusted entry. */
+const VALUE_STATUSES = [
+    'fresh',
+    'stale',
+    'error',
+    'missing',
+];
+function isValueStatus(value) {
+    return (typeof value === 'string' &&
+        VALUE_STATUSES.includes(value));
+}
+/**
+ * The message a host-data fault falls back to when even describing the
+ * thrown value throws. Deliberately generic: it only ever reaches a tooltip.
+ */
+const HOST_FAULT_MESSAGE = 'value store threw while reading this name';
+/**
+ * Best-effort description of something host code threw, for the tooltip
+ * channel. Every step is itself guarded: `instanceof`, `.message`, and
+ * `String(...)` can all throw when the thrown value is a revoked `Proxy` or
+ * an object with hostile traps/getters.
+ */
+export function describeHostFault(err) {
+    try {
+        if (err instanceof Error) {
+            const { message } = err;
+            if (typeof message === 'string' && message !== '')
+                return message;
+        }
+        const text = String(err);
+        return text === '' ? HOST_FAULT_MESSAGE : text;
+    }
+    catch {
+        return HOST_FAULT_MESSAGE;
+    }
+}
+/** The degraded resolution for a HOST-STORE FAULT: resolves to `'missing'`, carrying the thrown message as `error`, never inventing a `failureKind`. */
+function hostFault(err) {
+    return { value: undefined, status: 'missing', error: describeHostFault(err) };
+}
+/** The one-character prefix that routes a `data=`/`:value[]` name at the vault store instead of the note store (docs/scripting.md). */
+export const VAULT_NAME_PREFIX = '@';
+/** Reads the four `StoredValue` fields off an entry a host store handed back. MAY THROW; every caller wraps it. */
+function readEntry(entry) {
+    const value = entry.value;
+    const status = entry.status;
+    const error = entry.error;
+    const failureKind = entry.failureKind;
+    return {
+        value,
+        status: isValueStatus(status) ? status : 'missing',
+        error: typeof error === 'string' ? error : undefined,
+        failureKind: typeof failureKind === 'string'
+            ? failureKind
+            : undefined,
+    };
+}
+/** The partial-path degradation: `missing`, but still carrying the root entry's own error/kind. */
+function partialMiss(entry) {
+    return {
+        value: undefined,
+        status: 'missing',
+        error: entry.error,
+        failureKind: entry.failureKind,
+    };
+}
+/**
+ * Walks `segments[1:]` into `entry.value`. Never throws: a hostile stored
+ * value (a revoked `Proxy`, throwing traps) degrades to `hostFault` rather
+ * than escaping. `Object.hasOwn` is the load-bearing guard against a segment
+ * like `__proto__`/`constructor` resolving through the prototype chain.
+ */
+function walkSegments(entry, segments) {
+    let current = entry.value;
+    for (let index = 1; index < segments.length; index += 1) {
+        const segment = segments[index];
+        if (!segment || current === null || typeof current !== 'object') {
+            return partialMiss(entry);
+        }
+        let next;
+        try {
+            if (!Object.hasOwn(current, segment))
+                return partialMiss(entry);
+            next = current[segment];
+        }
+        catch (err) {
+            return hostFault(err);
+        }
+        current = next;
+    }
+    return {
+        value: current,
+        status: entry.status,
+        error: entry.error,
+        failureKind: entry.failureKind,
+    };
+}
+/** The shared never-throw shell around a store lookup. */
+function resolveEntryPath(lookup, segments) {
+    let entry;
+    try {
+        const raw = lookup();
+        if (!raw)
+            return MISSING;
+        entry = readEntry(raw);
+    }
+    catch (err) {
+        return hostFault(err);
+    }
+    return walkSegments(entry, segments);
+}
+/**
+ * Resolves a `data=`/`:value[]` name against `store`, walking a dotted path.
+ * Never throws, including against a hostile or buggy host store.
+ */
+export function resolveStorePath(store, dottedName) {
+    const segments = dottedName.split('.');
+    const root = segments[0];
+    if (!root)
+        return MISSING;
+    return resolveEntryPath(() => store?.get(root), segments);
+}
+/**
+ * Resolves a `data=`/`:value[]` name against a `ValueScope`, routing an
+ * `@`-prefixed name at `scope.vault` instead of `scope.store` ("bare name =
+ * mine, `@name` = the vault's"). Never throws.
+ */
+export function resolveScopedPath(scope, dottedName) {
+    if (dottedName.startsWith(VAULT_NAME_PREFIX)) {
+        const remainder = dottedName.slice(VAULT_NAME_PREFIX.length);
+        const segments = remainder.split('.');
+        const root = segments[0];
+        if (!root)
+            return MISSING;
+        return resolveEntryPath(() => scope.vault?.get(root), segments);
+    }
+    return resolveStorePath(scope.store, dottedName);
+}
+/**
+ * Runs `read` — an extraction that touches an untrusted bound `data` value —
+ * and falls back to `fallback()` if any part of it throws. Ported from
+ * `@markii/react`'s `safe-data.ts`: wraps the WHOLE extraction, not each
+ * individual property read, so a value whose reads throw degrades to the
+ * same "nothing resolved" state a genuinely missing binding already renders.
+ */
+export function safeRead(read, fallback) {
+    try {
+        return { fields: read() };
+    }
+    catch (err) {
+        return { fields: fallback(), fault: describeHostFault(err) };
+    }
+}

package/dist/test/html-context.d.ts

@@ -0,0 +1,9 @@
+import type { HtmlRenderContext } from '../registry.js';
+/**
+ * A minimal, unbound `HtmlRenderContext` for component unit tests that don't
+ * exercise value binding: `resolve` always misses, `valueMarker` renders the
+ * ordinary missing-value span. Colocated component tests (`callout.test.ts`
+ * and siblings) use this instead of hand-building a context object, so
+ * `HtmlRenderContext`'s shape can grow without touching every test file.
+ */
+export declare function createTestContext(overrides?: Partial<HtmlRenderContext>): HtmlRenderContext;

package/dist/test/html-context.js

@@ -0,0 +1,21 @@
+import { escapeHtml } from '../escape.js';
+/**
+ * A minimal, unbound `HtmlRenderContext` for component unit tests that don't
+ * exercise value binding: `resolve` always misses, `valueMarker` renders the
+ * ordinary missing-value span. Colocated component tests (`callout.test.ts`
+ * and siblings) use this instead of hand-building a context object, so
+ * `HtmlRenderContext`'s shape can grow without touching every test file.
+ */
+export function createTestContext(overrides = {}) {
+    return {
+        esc: escapeHtml,
+        resolve() {
+            return { value: undefined, status: 'missing' };
+        },
+        valueMarker(name) {
+            const label = name.trim() ? name.trim() : 'value';
+            return `<span class="mk-value mk-value--missing">{${escapeHtml(label)}}</span>`;
+        },
+        ...overrides,
+    };
+}

package/dist/value-format.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Ported from `@markii/react`'s `components/value-directive.tsx`: coerces a
+ * resolved store value to display text for `:value[...]`. Kept as its own
+ * tiny module because it has no dependency on hast/registry types and is
+ * useful in isolation (colocated test).
+ */
+/**
+ * Coerces a stored value to display text. Objects/arrays render as JSON;
+ * `null`/`undefined` render as an empty string. Never throws for any stored
+ * value.
+ */
+export declare function stringifyStoredValue(value: unknown): string;