@markii/html 0.6.0

package/dist/components/progress.js

@@ -0,0 +1,79 @@
+import { safeRead } from '../resolve.js';
+import { dataStateClassName, failureTitle } from '../failure-presentation.js';
+const DEFAULT_MAX = 1;
+/** Parses a numeric string defensively: non-numeric, `NaN`, and `±Infinity` all fall back to `fallback`. */
+function parseFiniteNumber(raw, fallback) {
+    if (raw === null || raw === undefined)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+function coerceNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * Reads `value`/`max` off a bound `data` value: a bare finite number
+ * supplies `value` alone; a plain object may supply either/both fields. MAY
+ * THROW for a hostile bound value — guarded at the call site via `safeRead`.
+ */
+function readProgressFields(data) {
+    if (typeof data === 'number') {
+        return { value: Number.isFinite(data) ? data : undefined };
+    }
+    if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+        const record = data;
+        return {
+            value: coerceNumber(record.value),
+            max: coerceNumber(record.max),
+        };
+    }
+    return {};
+}
+/**
+ * `::progress{value=3 max=5 label="tasks"}` — a meter bar. Data binding
+ * (§8): a bound numeric `data` supplies `value`; a bound object may supply
+ * `value`/`max` — explicit directive attributes always win. Parses
+ * defensively: non-numeric/`NaN`/`Infinity` input (from either source) falls
+ * back to `0` (value) or the default `max` of `1`; `value` is then clamped
+ * to `[0, max]` and `max` is guarded to be positive. Missing/error binding
+ * renders a `0%` bar rather than crashing.
+ *
+ * Markup and class names match `@markii/react`'s `Progress` byte-for-byte.
+ */
+export const Progress = (attributes, _childrenHtml, ctx) => {
+    const { data, dataStatus, dataError, dataFailureKind } = ctx;
+    const bound = safeRead(() => dataStatus === 'missing' || dataStatus === 'error'
+        ? {}
+        : readProgressFields(data), () => ({}));
+    const fromData = bound.fields;
+    const rawMax = parseFiniteNumber(attributes.max, fromData.max ?? DEFAULT_MAX);
+    const max = rawMax > 0 ? rawMax : DEFAULT_MAX;
+    const rawValue = parseFiniteNumber(attributes.value, fromData.value ?? 0);
+    const value = clamp(rawValue, 0, max);
+    const percent = clamp((value / max) * 100, 0, 100);
+    const label = attributes.label ?? null;
+    const className = dataStateClassName('mk-progress', dataStatus, dataFailureKind);
+    const title = failureTitle(dataError ?? bound.fault, dataFailureKind);
+    const titleAttr = title ? ` title="${ctx.esc(title)}"` : '';
+    const labelHtml = label
+        ? `<span class="mk-progress__label">${ctx.esc(label)}</span>`
+        : '';
+    return (`<div class="${className}"${titleAttr} role="progressbar" ` +
+        `aria-valuenow="${String(value)}" aria-valuemin="0" aria-valuemax="${String(max)}">` +
+        `${labelHtml}` +
+        `<div class="mk-progress__track">` +
+        `<div class="mk-progress__bar" style="width: ${String(percent)}%"></div>` +
+        `</div>` +
+        `<span class="mk-progress__percent">${String(Math.round(percent))}%</span>` +
+        `</div>`);
+};

package/dist/components/rating.d.ts

@@ -0,0 +1,9 @@
+import type { HtmlComponent } from '../registry.js';
+/**
+ * `::rating{value=3 max=5}` — a leaf directive rendering a row of stars.
+ * Both attributes are optional and clamped to sane bounds; malformed input
+ * degrades gracefully instead of throwing or rendering something
+ * nonsensical. Matches `@markii/react`'s `Rating` markup byte-for-byte so
+ * one stylesheet covers both renderers.
+ */
+export declare const Rating: HtmlComponent;

package/dist/components/rating.js

@@ -0,0 +1,33 @@
+const DEFAULT_MAX = 5;
+const MIN_MAX = 1;
+const MAX_MAX = 20;
+function parseCount(raw, fallback) {
+    if (raw === null || raw === undefined)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * `::rating{value=3 max=5}` — a leaf directive rendering a row of stars.
+ * Both attributes are optional and clamped to sane bounds; malformed input
+ * degrades gracefully instead of throwing or rendering something
+ * nonsensical. Matches `@markii/react`'s `Rating` markup byte-for-byte so
+ * one stylesheet covers both renderers.
+ */
+export const Rating = (attributes) => {
+    const max = clamp(parseCount(attributes.max, DEFAULT_MAX), MIN_MAX, MAX_MAX);
+    const value = clamp(parseCount(attributes.value, 0), 0, max);
+    let stars = '';
+    for (let index = 0; index < max; index += 1) {
+        const filled = index < value;
+        const className = filled
+            ? 'mk-rating__star mk-rating__star--filled'
+            : 'mk-rating__star';
+        stars += `<span class="${className}" aria-hidden="true">${filled ? '★' : '☆'}</span>`;
+    }
+    return (`<div class="mk-rating" role="img" aria-label="rating: ${String(value)} out of ${String(max)}">` +
+        `${stars}</div>`);
+};

package/dist/components/row.d.ts

@@ -0,0 +1,9 @@
+import type { HtmlComponent } from '../registry.js';
+/**
+ * `:::row{cols=3} ... :::` — docs/format.md's one layout *container*. An
+ * absent or invalid `cols` value degrades to plain `mk-row` (auto-fit)
+ * rather than an error. Matches `@markii/react`'s `Row` markup byte-for-byte
+ * so one stylesheet covers both renderers. No outer margin: the document
+ * stylesheet owns spacing between this and its siblings.
+ */
+export declare const Row: HtmlComponent;

package/dist/components/row.js

@@ -0,0 +1,19 @@
+/** The exact `cols` values that select a fixed-column-count class; anything else degrades to auto-fit. */
+const COLS_VALUES = ['2', '3', '4'];
+function isColsValue(value) {
+    return COLS_VALUES.includes(value);
+}
+/**
+ * `:::row{cols=3} ... :::` — docs/format.md's one layout *container*. An
+ * absent or invalid `cols` value degrades to plain `mk-row` (auto-fit)
+ * rather than an error. Matches `@markii/react`'s `Row` markup byte-for-byte
+ * so one stylesheet covers both renderers. No outer margin: the document
+ * stylesheet owns spacing between this and its siblings.
+ */
+export const Row = (attributes, childrenHtml) => {
+    const rawCols = attributes.cols ?? '';
+    const className = isColsValue(rawCols)
+        ? `mk-row mk-row--cols-${rawCols}`
+        : 'mk-row';
+    return `<div class="${className}">${childrenHtml}</div>`;
+};

package/dist/components/stat.d.ts

@@ -0,0 +1,18 @@
+import type { HtmlComponent } from '../registry.js';
+/**
+ * `::stat{value=42 label="stars" trend=up}` — a big value + label, with an
+ * optional delta/trend annotation. Data binding (§8): if the bound `data`
+ * value is a number/string it supplies `value`; if it is an object, its
+ * `value`/`label`/`delta`/`trend` fields are read — an explicit directive
+ * attribute always wins over the bound object's field. Missing value (from
+ * either source) renders `—` rather than a blank box; a missing or errored
+ * binding degrades the same way. Never throws.
+ *
+ * Failure presentation mirrors `@markii/react`'s `Stat` exactly
+ * (docs/scripting.md, AGENTS.md's cleanliness principle): the BODY stays
+ * quiet — `—`, or whatever static attributes supplied — and a failed/stale
+ * binding surfaces only as a `title` tooltip plus a modifier class on the
+ * root element (`mk-stat--stale`, `mk-stat--tier-blocked`, ...). Markup and
+ * class names match `@markii/react`'s `Stat` byte-for-byte.
+ */
+export declare const Stat: HtmlComponent;

package/dist/components/stat.js

@@ -0,0 +1,81 @@
+import { safeRead } from '../resolve.js';
+import { dataStateClassName, failureTitle } from '../failure-presentation.js';
+const EMPTY_VALUE = '—';
+const TRENDS = ['up', 'down', 'flat'];
+function isTrend(value) {
+    return TRENDS.includes(value);
+}
+/** Coerces an unknown field of a bound `data` object to a display string, or `undefined` if it isn't string/number/boolean. */
+function coerceField(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return undefined;
+}
+/**
+ * Reads `value`/`label`/`delta`/`trend` off a bound `data` value. Only a
+ * plain object contributes named fields; a bare number/string contributes
+ * `value` alone. MAY THROW for a hostile bound value — guarded at the call
+ * site via `safeRead`.
+ */
+function readStatFields(data) {
+    if (typeof data === 'number' || typeof data === 'string') {
+        return { value: String(data) };
+    }
+    if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+        const record = data;
+        return {
+            value: coerceField(record.value),
+            label: coerceField(record.label),
+            delta: coerceField(record.delta),
+            trend: coerceField(record.trend),
+        };
+    }
+    return {};
+}
+/** Explicit directive attributes win over the bound `data` object's own fields. */
+function pick(attribute, fromData) {
+    return attribute ?? fromData ?? undefined;
+}
+/**
+ * `::stat{value=42 label="stars" trend=up}` — a big value + label, with an
+ * optional delta/trend annotation. Data binding (§8): if the bound `data`
+ * value is a number/string it supplies `value`; if it is an object, its
+ * `value`/`label`/`delta`/`trend` fields are read — an explicit directive
+ * attribute always wins over the bound object's field. Missing value (from
+ * either source) renders `—` rather than a blank box; a missing or errored
+ * binding degrades the same way. Never throws.
+ *
+ * Failure presentation mirrors `@markii/react`'s `Stat` exactly
+ * (docs/scripting.md, AGENTS.md's cleanliness principle): the BODY stays
+ * quiet — `—`, or whatever static attributes supplied — and a failed/stale
+ * binding surfaces only as a `title` tooltip plus a modifier class on the
+ * root element (`mk-stat--stale`, `mk-stat--tier-blocked`, ...). Markup and
+ * class names match `@markii/react`'s `Stat` byte-for-byte.
+ */
+export const Stat = (attributes, _childrenHtml, ctx) => {
+    const { data, dataStatus, dataError, dataFailureKind } = ctx;
+    const bound = safeRead(() => dataStatus === 'missing' || dataStatus === 'error'
+        ? {}
+        : readStatFields(data), () => ({}));
+    const fromData = bound.fields;
+    const value = pick(attributes.value, fromData.value);
+    const label = pick(attributes.label, fromData.label);
+    const delta = pick(attributes.delta, fromData.delta);
+    const rawTrend = pick(attributes.trend, fromData.trend);
+    const trend = rawTrend && isTrend(rawTrend) ? rawTrend : undefined;
+    const deltaHtml = delta
+        ? `<span class="${trend ? `mk-stat__delta mk-stat__delta--${trend}` : 'mk-stat__delta'}">${ctx.esc(delta)}</span>`
+        : '';
+    const className = dataStateClassName('mk-stat', dataStatus, dataFailureKind);
+    const title = failureTitle(dataError ?? bound.fault, dataFailureKind);
+    const titleAttr = title ? ` title="${ctx.esc(title)}"` : '';
+    const labelHtml = label
+        ? `<div class="mk-stat__label">${ctx.esc(label)}</div>`
+        : '';
+    return (`<div class="${className}"${titleAttr}>` +
+        `<div class="mk-stat__value">${ctx.esc(value || EMPTY_VALUE)}</div>` +
+        `${labelHtml}${deltaHtml}</div>`);
+};

package/dist/components/tab.d.ts

@@ -0,0 +1,18 @@
+import type { HtmlComponent } from '../registry.js';
+/** Default label used when a `tab` directive has no `label` attribute (kept for parity with `@markii/react`; the HTML engine has no way to surface it, see `tabs.ts`). */
+export declare const DEFAULT_TAB_LABEL = "Tab";
+/**
+ * The panel markup a tab shows. Matches `@markii/react`'s `TabPanel`
+ * markup byte-for-byte.
+ */
+export declare function tabPanel(childrenHtml: string): string;
+/**
+ * `:::tab{label="..."} ... :::` — one panel of a `tabs` component
+ * (`tabs.ts`). Rendered standalone (outside a `tabs` parent), it shows its
+ * own panel. `label` has no effect here: it is only meaningful to an
+ * enclosing `tabs`, and (unlike `@markii/react`, which can inspect its
+ * parent's structured React children) this string-based engine has no way
+ * for `tabs` to read a child directive's attributes — see `tabs.ts`'s doc
+ * comment for the resulting limitation.
+ */
+export declare const Tab: HtmlComponent;

package/dist/components/tab.js

@@ -0,0 +1,19 @@
+/** Default label used when a `tab` directive has no `label` attribute (kept for parity with `@markii/react`; the HTML engine has no way to surface it, see `tabs.ts`). */
+export const DEFAULT_TAB_LABEL = 'Tab';
+/**
+ * The panel markup a tab shows. Matches `@markii/react`'s `TabPanel`
+ * markup byte-for-byte.
+ */
+export function tabPanel(childrenHtml) {
+    return `<div class="mk-tab" role="tabpanel">${childrenHtml}</div>`;
+}
+/**
+ * `:::tab{label="..."} ... :::` — one panel of a `tabs` component
+ * (`tabs.ts`). Rendered standalone (outside a `tabs` parent), it shows its
+ * own panel. `label` has no effect here: it is only meaningful to an
+ * enclosing `tabs`, and (unlike `@markii/react`, which can inspect its
+ * parent's structured React children) this string-based engine has no way
+ * for `tabs` to read a child directive's attributes — see `tabs.ts`'s doc
+ * comment for the resulting limitation.
+ */
+export const Tab = (_attributes, childrenHtml) => tabPanel(childrenHtml);

package/dist/components/tabs.d.ts

@@ -0,0 +1,30 @@
+import type { HtmlComponent } from '../registry.js';
+/**
+ * `::::tabs :::tab{label="..."} ... ::: :::tab{label="..."} ... ::: ::::` —
+ * a tabbed panel switcher.
+ *
+ * FAITHFULNESS LIMITATION: `@markii/react`'s `Tabs` inspects its own
+ * (structured) React children to find `tab` directives, reads each one's
+ * `label` attribute, and renders a `role="tablist"` button bar plus only
+ * the active panel, switching on click via `useState`. This HTML engine
+ * hands every component its children pre-rendered to a single opaque HTML
+ * string (`childrenHtml`) — by the time `Tabs` runs, each `tab` child has
+ * already been rendered by the `Tab` component above into its own
+ * `.mk-tab` panel, and the `label` attribute that lived on each `tab`
+ * directive is gone; there is no supported way for this component to
+ * recover it, and the engine's render pipeline (`render.ts`) is explicitly
+ * out of scope to change for this.
+ *
+ * So this is the simplest correct rendering available from a string: every
+ * tab panel is shown, in document order, with no tablist button bar and no
+ * JS-driven active-tab switching (this package is zero-JS by design; see
+ * `@markii/html`'s package description). A reader sees all tabs' content at
+ * once, wrapped in `.mk-tabs` so the surrounding CSS still applies to
+ * whatever it can (panel spacing via `.mk-tab`). Static-HTML consumers
+ * (publishing, CI, archive) generally want the content anyway, and no
+ * content is silently dropped. A future slice could restore full
+ * faithfulness (e.g. CSS-only radio-button tabs) if `render.ts` grows a way
+ * to hand a container component its children pre-parsed rather than
+ * pre-rendered.
+ */
+export declare const Tabs: HtmlComponent;

package/dist/components/tabs.js

@@ -0,0 +1,33 @@
+/**
+ * `::::tabs :::tab{label="..."} ... ::: :::tab{label="..."} ... ::: ::::` —
+ * a tabbed panel switcher.
+ *
+ * FAITHFULNESS LIMITATION: `@markii/react`'s `Tabs` inspects its own
+ * (structured) React children to find `tab` directives, reads each one's
+ * `label` attribute, and renders a `role="tablist"` button bar plus only
+ * the active panel, switching on click via `useState`. This HTML engine
+ * hands every component its children pre-rendered to a single opaque HTML
+ * string (`childrenHtml`) — by the time `Tabs` runs, each `tab` child has
+ * already been rendered by the `Tab` component above into its own
+ * `.mk-tab` panel, and the `label` attribute that lived on each `tab`
+ * directive is gone; there is no supported way for this component to
+ * recover it, and the engine's render pipeline (`render.ts`) is explicitly
+ * out of scope to change for this.
+ *
+ * So this is the simplest correct rendering available from a string: every
+ * tab panel is shown, in document order, with no tablist button bar and no
+ * JS-driven active-tab switching (this package is zero-JS by design; see
+ * `@markii/html`'s package description). A reader sees all tabs' content at
+ * once, wrapped in `.mk-tabs` so the surrounding CSS still applies to
+ * whatever it can (panel spacing via `.mk-tab`). Static-HTML consumers
+ * (publishing, CI, archive) generally want the content anyway, and no
+ * content is silently dropped. A future slice could restore full
+ * faithfulness (e.g. CSS-only radio-button tabs) if `render.ts` grows a way
+ * to hand a container component its children pre-parsed rather than
+ * pre-rendered.
+ */
+export const Tabs = (_attributes, childrenHtml) => {
+    if (!childrenHtml.trim())
+        return '';
+    return `<div class="mk-tabs">${childrenHtml}</div>`;
+};

package/dist/doc-css.generated.d.ts

@@ -0,0 +1,2 @@
+/** The shared document stylesheet (@markii/react's doc.css), embedded as a string for exportHtmlDocument's <style> block. */
+export declare const DOC_CSS: string;

package/dist/doc-css.generated.js

@@ -0,0 +1,5 @@
+// GENERATED FILE — do not edit by hand.
+// Regenerate with: node scripts/generate-doc-css.ts
+// Source of truth: packages/platforms/markii-react/src/doc.css
+/** The shared document stylesheet (@markii/react's doc.css), embedded as a string for exportHtmlDocument's <style> block. */
+export const DOC_CSS = "/*\n * Document rhythm: components own their insides only, never outer margins.\n * This single rule spaces every block-level child of `.doc` identically —\n * paragraphs, headings, and components alike — so new components always\n * sit correctly in the flow with zero per-component tuning.\n */\n.doc > * + * {\n  margin-block-start: 1rem;\n}\n\n.doc {\n  color: #1a1a1a;\n  font-family:\n    system-ui,\n    -apple-system,\n    'Segoe UI',\n    sans-serif;\n  line-height: 1.6;\n}\n\n.doc pre {\n  overflow-x: auto;\n  background: #f4f4f5;\n  padding: 0.75rem 1rem;\n  border-radius: 6px;\n}\n\n.doc code {\n  background: #f0f0f2;\n  border-radius: 3px;\n  padding: 0.1em 0.35em;\n  font-size: 0.9em;\n}\n\n.doc pre code {\n  background: none;\n  padding: 0;\n}\n\n/* ---------- GFM table ---------- */\n\n/*\n * `display: block` on the table itself (rather than wrapping it in an\n * extra element the renderer doesn't otherwise inject) is what makes a wide\n * table scroll horizontally instead of overflowing the page or the doc\n * column — the table box becomes independently scrollable content, the\n * same trick used by GitHub's own Markdown rendering.\n */\n.doc table {\n  display: block;\n  overflow-x: auto;\n  border-collapse: collapse;\n  font-size: 0.95em;\n}\n\n.doc th,\n.doc td {\n  border: 1px solid #e4e4e7;\n  padding: 0.4rem 0.75rem;\n  text-align: left;\n}\n\n.doc th {\n  font-weight: 600;\n  background: #f8fafc;\n}\n\n.doc tr:nth-child(even) {\n  background: #fafafa;\n}\n\n/* ---------- GFM task list ---------- */\n\n/*\n * `li:has(> input[type=\"checkbox\"])` scopes bullet removal + checkbox\n * alignment to task-list items only — an ordinary `<ul>`/`<ol>` item keeps\n * its normal bullet/number, since GFM only adds a leading `<input>` to\n * items that used `- [ ]`/`- [x]` syntax.\n */\n.doc li:has(> input[type='checkbox']) {\n  list-style: none;\n  margin-inline-start: -1.5em;\n}\n\n.doc li > input[type='checkbox'] {\n  margin-inline-end: 0.5em;\n  vertical-align: middle;\n}\n\n/* ---------- callout ---------- */\n\n.mk-callout {\n  border: 1px solid var(--mk-callout-border, #94a3b8);\n  border-left-width: 4px;\n  border-radius: 6px;\n  padding: 0.75rem 1rem;\n  background: var(--mk-callout-bg, #f8fafc);\n}\n\n.mk-callout--info {\n  --mk-callout-border: #3b82f6;\n  --mk-callout-bg: #eff6ff;\n}\n\n.mk-callout--warning {\n  --mk-callout-border: #d97706;\n  --mk-callout-bg: #fffbeb;\n}\n\n.mk-callout--danger {\n  --mk-callout-border: #dc2626;\n  --mk-callout-bg: #fef2f2;\n}\n\n.mk-callout__header {\n  display: flex;\n  align-items: center;\n  gap: 0.5rem;\n  font-weight: 600;\n}\n\n.mk-callout__icon {\n  line-height: 1;\n}\n\n/*\n * `display: flex; flex-direction: column` is load-bearing here, not just\n * `> * + *` margin: several block-holding components (`stat`, `badge`)\n * declare their OWN outer display as `inline-flex`/`inline-block` (correct\n * for sitting inline in a sentence), so without a flex/grid parent they\n * flow side-by-side on the same line instead of stacking — a\n * `margin-block-start` on a same-line inline-level sibling creates no\n * visible gap. Making the body a column flex container forces every\n * child's *used* display to blockify (CSS Flexbox: a flex item's outer\n * display is always block-level), so they stack regardless of the\n * component's own declared display, and the margin rule below then has\n * something to actually separate.\n */\n.mk-callout__body {\n  display: flex;\n  flex-direction: column;\n}\n\n.mk-callout__body > :first-child {\n  margin-block-start: 0.5rem;\n}\n\n.mk-callout__body > * + * {\n  margin-block-start: 0.5rem;\n}\n\n/* ---------- kbd ---------- */\n\n.mk-kbd {\n  display: inline-block;\n  vertical-align: baseline;\n  line-height: 1.4;\n  height: 1.4em;\n  padding: 0 0.4em;\n  font-family: ui-monospace, 'SFMono-Regular', Menlo, monospace;\n  font-size: 0.85em;\n  border: 1px solid #c9ccd1;\n  border-bottom-width: 2px;\n  border-radius: 4px;\n  background: #f6f7f9;\n  box-shadow: inset 0 -1px 0 rgba(0, 0, 0, 0.05);\n}\n\n/* ---------- rating ---------- */\n\n.mk-rating {\n  display: inline-flex;\n  gap: 0.15em;\n  font-size: 1.1em;\n  color: #cbd5e1;\n}\n\n.mk-rating__star--filled {\n  color: #f59e0b;\n}\n\n/* ---------- value interpolation ---------- */\n\n.mk-value {\n  display: inline;\n  vertical-align: baseline;\n}\n\n.mk-value--stale {\n  color: #92400e;\n  border-bottom: 1px dashed #d97706;\n}\n\n.mk-value--missing {\n  font-family: ui-monospace, 'SFMono-Regular', Menlo, monospace;\n  font-size: 0.9em;\n  color: #94a3b8;\n  font-style: italic;\n}\n\n/*\n * Failure-kind modifiers (`@markii/runtime`'s `FailureKind`, docs/scripting.md) —\n * layered on top of `.mk-value--missing`, only ever added when the\n * resolution's root entry carried a `failureKind` on a genuine error (see\n * `ValueDirective`). Each just tints the dashed-underline treatment a\n * distinct hue so a reader can tell \"script bug\" apart from \"needs\n * permission\" / \"needs a manual run\" / \"hit a resource limit\" at a glance,\n * with the full message still available via the `title` tooltip.\n */\n.mk-value--script-error {\n  border-bottom: 1px dashed #ef4444;\n}\n\n.mk-value--capability-denied {\n  border-bottom: 1px dashed #d97706;\n}\n\n.mk-value--tier-blocked {\n  border-bottom: 1px dashed #2563eb;\n}\n\n.mk-value--limit {\n  border-bottom: 1px dashed #7c3aed;\n}\n\n/* ---------- script marker ---------- */\n\n.mk-script {\n  border: 1px solid #d4d4d8;\n  border-radius: 6px;\n  background: #fafafa;\n}\n\n.mk-script__summary {\n  cursor: pointer;\n  padding: 0.5rem 0.75rem;\n  font-family: ui-monospace, 'SFMono-Regular', Menlo, monospace;\n  font-size: 0.85em;\n  color: #52525b;\n}\n\n.mk-script[open] > .mk-script__summary {\n  border-bottom: 1px solid #e4e4e7;\n}\n\n.mk-script__code {\n  margin: 0.75rem;\n  margin-block-start: 0;\n}\n\n.mk-script__empty {\n  margin: 0.75rem;\n  margin-block-start: 0;\n  font-size: 0.85em;\n  font-style: italic;\n  color: #94a3b8;\n}\n\n/* ---------- details ---------- */\n\n.mk-details {\n  border: 1px solid #d4d4d8;\n  border-radius: 6px;\n  padding: 0.75rem 1rem;\n  background: #fafafa;\n}\n\n.mk-details__summary {\n  cursor: pointer;\n  font-weight: 600;\n}\n\n.mk-details[open] > .mk-details__summary {\n  margin-block-end: 0.5rem;\n}\n\n/* Blockifies inline-flex/inline-block children (`stat`, `badge`, ...) so they stack — see `.mk-callout__body`'s comment above for why this is load-bearing. */\n.mk-details__body {\n  display: flex;\n  flex-direction: column;\n}\n\n.mk-details__body > :first-child {\n  margin-block-start: 0.5rem;\n}\n\n.mk-details__body > * + * {\n  margin-block-start: 0.5rem;\n}\n\n/* ---------- card ---------- */\n\n.mk-card {\n  border: 1px solid #e4e4e7;\n  border-radius: 8px;\n  padding: 1rem;\n  background: #fff;\n}\n\n.mk-card__title {\n  font-weight: 600;\n  margin-block-end: 0.5rem;\n}\n\n/* Blockifies inline-flex/inline-block children (`stat`, `badge`, ...) so they stack — see `.mk-callout__body`'s comment above for why this is load-bearing. */\n.mk-card__body {\n  display: flex;\n  flex-direction: column;\n}\n\n.mk-card__body > :first-child {\n  margin-block-start: 0;\n}\n\n.mk-card__body > * + * {\n  margin-block-start: 0.5rem;\n}\n\n/* ---------- badge ---------- */\n\n.mk-badge {\n  display: inline-block;\n  vertical-align: baseline;\n  line-height: 1.4;\n  height: 1.4em;\n  padding: 0 0.6em;\n  font-size: 0.8em;\n  font-weight: 600;\n  border-radius: 999px;\n  color: var(--mk-badge-fg, #334155);\n  background: var(--mk-badge-bg, #e2e8f0);\n}\n\n.mk-badge--info {\n  --mk-badge-fg: #1d4ed8;\n  --mk-badge-bg: #dbeafe;\n}\n\n.mk-badge--success {\n  --mk-badge-fg: #15803d;\n  --mk-badge-bg: #dcfce7;\n}\n\n.mk-badge--warning {\n  --mk-badge-fg: #b45309;\n  --mk-badge-bg: #fef3c7;\n}\n\n.mk-badge--danger {\n  --mk-badge-fg: #b91c1c;\n  --mk-badge-bg: #fee2e2;\n}\n\n/* ---------- figure ---------- */\n\n.mk-figure {\n  margin: 0;\n}\n\n.mk-figure__img {\n  display: block;\n  max-width: 100%;\n  height: auto;\n  border-radius: 6px;\n}\n\n.mk-figure__caption {\n  margin-block-start: 0.5rem;\n  font-size: 0.9em;\n  color: #52525b;\n}\n\n.mk-figure__caption > :first-child {\n  margin-block-start: 0;\n}\n\n.mk-figure__caption > * + * {\n  margin-block-start: 0.5rem;\n}\n\n/* ---------- tabs ---------- */\n\n.mk-tabs__list {\n  display: flex;\n  gap: 0.25rem;\n  border-bottom: 1px solid #e4e4e7;\n}\n\n.mk-tabs__button {\n  cursor: pointer;\n  border: none;\n  background: none;\n  padding: 0.5rem 0.9rem;\n  font: inherit;\n  font-weight: 600;\n  color: #71717a;\n  border-bottom: 2px solid transparent;\n  margin-block-end: -1px;\n}\n\n.mk-tabs__button--active {\n  color: #1d4ed8;\n  border-bottom-color: #1d4ed8;\n}\n\n/* Blockifies inline-flex/inline-block children (`stat`, `badge`, ...) so they stack — see `.mk-callout__body`'s comment above for why this is load-bearing. */\n.mk-tab {\n  display: flex;\n  flex-direction: column;\n  padding-block-start: 0.75rem;\n}\n\n.mk-tab > :first-child {\n  margin-block-start: 0;\n}\n\n.mk-tab > * + * {\n  margin-block-start: 0.5rem;\n}\n\n/* ---------- stat ---------- */\n\n.mk-stat {\n  display: inline-flex;\n  flex-direction: column;\n  gap: 0.15rem;\n}\n\n.mk-stat__value {\n  font-size: 1.8em;\n  font-weight: 700;\n  line-height: 1.2;\n}\n\n.mk-stat__label {\n  font-size: 0.85em;\n  color: #71717a;\n}\n\n.mk-stat__delta {\n  font-size: 0.85em;\n  font-weight: 600;\n  color: #71717a;\n}\n\n.mk-stat__delta--up {\n  color: #15803d;\n}\n\n.mk-stat__delta--down {\n  color: #b91c1c;\n}\n\n.mk-stat__delta--flat {\n  color: #71717a;\n}\n\n/* ---------- progress ---------- */\n\n.mk-progress {\n  display: flex;\n  align-items: center;\n  gap: 0.6rem;\n}\n\n.mk-progress__label {\n  font-size: 0.85em;\n  color: #52525b;\n  flex: 0 0 auto;\n}\n\n.mk-progress__track {\n  flex: 1 1 auto;\n  height: 0.6rem;\n  border-radius: 999px;\n  background: #e4e4e7;\n  overflow: hidden;\n}\n\n.mk-progress__bar {\n  height: 100%;\n  background: #3b82f6;\n  border-radius: inherit;\n}\n\n.mk-progress__percent {\n  flex: 0 0 auto;\n  font-size: 0.85em;\n  font-variant-numeric: tabular-nums;\n  color: #52525b;\n}\n\n/* ---------- chart ---------- */\n\n.mk-chart {\n  display: block;\n  max-width: 100%;\n}\n\n.mk-chart__line {\n  fill: none;\n  stroke: #3b82f6;\n  stroke-width: 2;\n  stroke-linejoin: round;\n  stroke-linecap: round;\n}\n\n.mk-chart__bar {\n  fill: #3b82f6;\n}\n\n.mk-chart--empty {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  font-size: 0.8em;\n  font-style: italic;\n  color: #94a3b8;\n  border: 1px dashed #d4d4d8;\n  border-radius: 6px;\n}\n\n/* ---------- data-binding state (docs/scripting.md) ---------- */\n\n/*\n * The block twins of the `.mk-value--*` markers above: a data-bound\n * component (`stat`, `progress`, `chart`) whose `data=` binding is stale or\n * failed keeps its ordinary QUIET body — `—`, a `0%` bar, `no data` — and\n * says so only through these hooks plus its `title` tooltip. No rule here\n * may add body text (`content:` is deliberately absent) or an outer margin;\n * the failure taxonomy's wording lives in one place only, `components/\n * failure-presentation.ts`.\n *\n * The hues match `.mk-value--*` exactly, so the same failing name reads the\n * same whether it surfaced inline via `:value[...]` or as a component.\n */\n.mk-stat--stale,\n.mk-progress--stale,\n.mk-chart--stale {\n  opacity: 0.8;\n}\n\n.mk-stat--script-error,\n.mk-progress--script-error,\n.mk-chart--script-error {\n  border-bottom: 2px solid #ef4444;\n}\n\n.mk-stat--capability-denied,\n.mk-progress--capability-denied,\n.mk-chart--capability-denied {\n  border-bottom: 2px solid #d97706;\n}\n\n.mk-stat--tier-blocked,\n.mk-progress--tier-blocked,\n.mk-chart--tier-blocked {\n  border-bottom: 2px solid #2563eb;\n}\n\n.mk-stat--limit,\n.mk-progress--limit,\n.mk-chart--limit {\n  border-bottom: 2px solid #7c3aed;\n}\n\n/* ---------- layout presets (docs/format.md) ---------- */\n\n/*\n * `render.tsx` only wraps a directive in a `mk-width-*`/`mk-align-*` `<div>`\n * when at least one of these classes actually applies, so the wrapper below\n * IS the element sitting directly in `.doc`'s rhythm flow — never\n * `margin-block` here, that's `.doc > * + *`'s job alone; setting it on the\n * wrapper too would double up spacing. `max-width: min(<size>, 100%)` keeps\n * every preset from ever overflowing the document column, even on a narrow\n * viewport where the size below is wider than the column itself.\n */\n.mk-width-narrow {\n  max-width: min(30rem, 100%);\n}\n\n.mk-width-wide {\n  max-width: min(64rem, 100%);\n}\n\n/* \"full\" is the full available column width — not a viewport-bleed hack with negative margins. */\n.mk-width-full {\n  max-width: 100%;\n}\n\n.mk-align-left {\n  margin-inline-end: auto;\n}\n\n.mk-align-center {\n  margin-inline: auto;\n}\n\n.mk-align-right {\n  margin-inline-start: auto;\n}\n\n/*\n * The five `:::center`/`:::right`/`:::wide`/`:::narrow`/`:::full` layout\n * wrappers (docs/format.md, `layout-wrapper.tsx`) reuse the `mk-width-*`/\n * `mk-align-*` classes above and add `mk-layout` on top for the rules below,\n * which only make sense on a container that has its OWN plain-markdown\n * children (a table, an image, a paragraph) rather than on the bare\n * attribute-interception wrapper `render.tsx` emits for `width=`/`align=`.\n *\n * No outer margin on `.mk-layout` itself, same rule as every component\n * (Architecture rule 4) — `.doc > * + *` spaces the wrapper against its\n * siblings. This rule instead restores RHYTHM *inside* the wrapper's own\n * scope, mirroring `.mk-card__body > * + *`: without it, the wrapper's\n * children would have no spacing between them at all, since `.doc > * + *`\n * only ever sees the wrapper `<div>` as a whole, never reaches inside it.\n */\n.mk-layout > * + * {\n  margin-block-start: 1rem;\n}\n\n/* `center`/`right` additionally set text alignment for everything in scope — not just the shrink-to-fit block alignment below. */\n.mk-layout.mk-align-center {\n  text-align: center;\n}\n\n.mk-layout.mk-align-right {\n  text-align: right;\n}\n\n/*\n * `.mk-align-center`/`.mk-align-right` above (shared with the `align=`\n * attribute wrapper) only center/right-align the wrapper `<div>` ITSELF\n * within ITS container — they say nothing about the wrapper's own children.\n * These two rules do that: they shrink-to-fit and align every direct child\n * of the wrapper's scope, which is what actually centers/right-aligns a\n * narrower-than-column table or image sitting inside `:::center`/`:::right`.\n */\n.mk-layout.mk-align-center > * {\n  margin-inline: auto;\n}\n\n.mk-layout.mk-align-right > * {\n  margin-inline-start: auto;\n  margin-inline-end: 0;\n}\n\n/*\n * `.doc table` (above) sets `display: block` for horizontal-scroll\n * overflow, which also makes the table fill its column — defeating\n * shrink-to-fit alignment before it can even apply. These two rules size a\n * table down to its content instead, so the `margin-inline` rules above\n * have a narrower box to actually move. `.doc th`/`.doc td` set\n * `text-align: left` directly on the cells, so this scope's `text-align`\n * never flips table cell text — only the table's own position in the\n * scope, and any non-table text alongside it.\n */\n.mk-layout.mk-align-center > table,\n.mk-layout.mk-align-right > table {\n  width: fit-content;\n  max-width: 100%;\n}\n\n/* ---------- row ---------- */\n\n.mk-row {\n  display: grid;\n  gap: 1rem;\n  grid-template-columns: repeat(auto-fit, minmax(min(16rem, 100%), 1fr));\n}\n\n/*\n * `minmax(0, 1fr)` — a bare `1fr` track can still grow past an equal share\n * to fit a wide intrinsic-content cell (e.g. a `chart` SVG, a long code\n * span); pinning the minimum to `0` is what keeps such a cell, and\n * therefore the whole row, from blowing out past its column.\n */\n.mk-row--cols-2 {\n  grid-template-columns: repeat(2, minmax(0, 1fr));\n}\n\n.mk-row--cols-3 {\n  grid-template-columns: repeat(3, minmax(0, 1fr));\n}\n\n.mk-row--cols-4 {\n  grid-template-columns: repeat(4, minmax(0, 1fr));\n}\n\n/*\n * No separate blockification rule is needed here, unlike `.mk-card__body`'s:\n * a grid container (which `.mk-row` is) already promotes every direct\n * child's outer display to block-level as a grid item, same as a flex\n * container does — an inline-flex/inline-block component (`stat`, `badge`,\n * ...) used directly as a row cell already stacks/sizes as a proper grid\n * cell with no extra rule required.\n */\n\n@media (max-width: 40rem) {\n  .mk-row,\n  .mk-row--cols-2,\n  .mk-row--cols-3,\n  .mk-row--cols-4 {\n    grid-template-columns: 1fr;\n  }\n}\n\n/*\n * `:::row{align=...}` (docs/format.md): `align` is intercepted like on any\n * other block directive (`render.tsx`/`layout.ts`), wrapping `.mk-row` in\n * the same generic `mk-align-*` `<div>` every other directive gets — but\n * `margin-inline: auto` (the rule above, under \"layout presets\") has\n * nothing to move: a `.mk-row` grid already fills the document column, so\n * shrink-to-fit placement of the row itself is meaningless. These three\n * rules give `align` on a row its own, more useful meaning instead: they\n * set `text-align` on the row, which every cell's content INHERITS (plain\n * CSS inheritance — `.mk-cell` sets no `text-align` of its own, so nothing\n * blocks it). Scoped to `> .mk-row` specifically, so a non-row directive's\n * `align` wrapper is completely unaffected.\n *\n * Locality wins for free: a more local `:::center`/`:::left`/`:::right`\n * wrapper written inside one cell (`.mk-layout.mk-align-*` above) sets\n * `text-align` directly on itself, and an element's own declared value\n * always wins over one it only inherited — no specificity fight needed.\n */\n.mk-align-left > .mk-row {\n  text-align: left;\n}\n\n.mk-align-center > .mk-row {\n  text-align: center;\n}\n\n.mk-align-right > .mk-row {\n  text-align: right;\n}\n\n/* ---------- cell ---------- */\n\n/*\n * `:::cell` (`cell.tsx`) is a TRANSPARENT grouping container: it has no\n * border, background, padding, or outer margin of its own — its whole job is\n * making several blocks count as ONE `.mk-row` grid cell, so anything visual\n * here would betray that. `.mk-cell` therefore has no rule at all; only the\n * rhythm-restoring rule below exists, mirroring `.mk-layout > * + *`:\n * `.doc > * + *` sees the cell as a single box and never reaches inside it,\n * so without this its children would sit flush against each other.\n */\n.mk-cell > * + * {\n  margin-block-start: 1rem;\n}\n\n/* ---------- unknown directive fallback ---------- */\n\n.mk-unknown {\n  border: 1px dashed #94a3b8;\n  border-radius: 6px;\n  color: #475569;\n}\n\n.mk-unknown--block {\n  padding: 0.75rem 1rem;\n}\n\n.mk-unknown--inline {\n  display: inline-flex;\n  align-items: baseline;\n  gap: 0.4em;\n  padding: 0 0.4em;\n  vertical-align: baseline;\n}\n\n.mk-unknown__label {\n  font-size: 0.85em;\n  font-style: italic;\n  margin: 0;\n}\n\n.mk-unknown__content > :first-child {\n  margin-block-start: 0.5rem;\n}\n\n.mk-unknown__content > * + * {\n  margin-block-start: 0.5rem;\n}\n";

package/dist/document.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `exportHtmlDocument`'s options. Everything is optional: with no options at
+ * all the result is a complete, valid, self-contained HTML document — the
+ * "publish a note" default this function exists for (AGENTS.md: `@markii/html`
+ * is "for stopped-changing documents (publish/CI/email/archive)").
+ */
+export interface ExportHtmlDocumentOptions {
+    /** The document `<title>`. Defaults to `'Markii document'`. HTML-escaped. */
+    title?: string;
+    /** The document `<html lang="...">` attribute. Defaults to `'en'`. */
+    lang?: string;
+    /**
+     * Extra CSS appended after the shared `doc.css` (e.g. a host's own theme
+     * overrides). Inserted verbatim inside the `<style>` block — this is
+     * trusted host-authored CSS, not user content, so it is never escaped.
+     */
+    extraCss?: string;
+}
+/**
+ * Wraps an already-rendered document body (typically `renderMarkToHtml`'s
+ * output) in a complete, self-contained HTML document: doctype, `<html>`/
+ * `<head>`/`<body>`, a `<meta charset>`, a `<title>`, and a `<style>` block
+ * carrying the shared `doc.css` — the same stylesheet `@markii/react` ships
+ * (`packages/platforms/markii-react/src/doc.css`), embedded as a generated
+ * string constant (`./doc-css.generated.ts`, produced by
+ * `scripts/generate-doc-css.ts`) rather than duplicated by hand, so the two
+ * renderers can never drift on document rhythm or component internals.
+ *
+ * `body` is inserted verbatim: it is expected to already be safe HTML (the
+ * output of `renderMarkToHtml`/`renderMarkNodeToHtml`, which sanitizes and
+ * escapes as it renders) — this function does not re-escape it, exactly as
+ * a `<body>` wrapper around already-rendered markup should not. `title` and
+ * `lang`, by contrast, ARE escaped/attribute-safe here, since they are
+ * ordinary strings a caller may have sourced from frontmatter or user input.
+ *
+ * The whole class of components this renders (`.doc`'s wrapper) expects a
+ * `<div class="doc">` root — callers that pass `renderMarkToHtml`'s raw
+ * output (which does not add that wrapper itself) get it added here, so the
+ * exported document's rhythm rules apply without every caller having to
+ * remember the wrapper class.
+ */
+export declare function exportHtmlDocument(body: string, options?: ExportHtmlDocumentOptions): string;

package/dist/document.js

@@ -0,0 +1,44 @@
+import { DOC_CSS } from './doc-css.generated.js';
+import { escapeHtml } from './escape.js';
+const DEFAULT_TITLE = 'Markii document';
+const DEFAULT_LANG = 'en';
+/**
+ * Wraps an already-rendered document body (typically `renderMarkToHtml`'s
+ * output) in a complete, self-contained HTML document: doctype, `<html>`/
+ * `<head>`/`<body>`, a `<meta charset>`, a `<title>`, and a `<style>` block
+ * carrying the shared `doc.css` — the same stylesheet `@markii/react` ships
+ * (`packages/platforms/markii-react/src/doc.css`), embedded as a generated
+ * string constant (`./doc-css.generated.ts`, produced by
+ * `scripts/generate-doc-css.ts`) rather than duplicated by hand, so the two
+ * renderers can never drift on document rhythm or component internals.
+ *
+ * `body` is inserted verbatim: it is expected to already be safe HTML (the
+ * output of `renderMarkToHtml`/`renderMarkNodeToHtml`, which sanitizes and
+ * escapes as it renders) — this function does not re-escape it, exactly as
+ * a `<body>` wrapper around already-rendered markup should not. `title` and
+ * `lang`, by contrast, ARE escaped/attribute-safe here, since they are
+ * ordinary strings a caller may have sourced from frontmatter or user input.
+ *
+ * The whole class of components this renders (`.doc`'s wrapper) expects a
+ * `<div class="doc">` root — callers that pass `renderMarkToHtml`'s raw
+ * output (which does not add that wrapper itself) get it added here, so the
+ * exported document's rhythm rules apply without every caller having to
+ * remember the wrapper class.
+ */
+export function exportHtmlDocument(body, options = {}) {
+    const title = options.title ?? DEFAULT_TITLE;
+    const lang = options.lang ?? DEFAULT_LANG;
+    const css = options.extraCss ? `${DOC_CSS}\n${options.extraCss}` : DOC_CSS;
+    return (`<!doctype html>\n` +
+        `<html lang="${escapeHtml(lang)}">\n` +
+        `<head>\n` +
+        `<meta charset="utf-8">\n` +
+        `<meta name="viewport" content="width=device-width, initial-scale=1">\n` +
+        `<title>${escapeHtml(title)}</title>\n` +
+        `<style>\n${css}\n</style>\n` +
+        `</head>\n` +
+        `<body>\n` +
+        `<div class="doc">\n${body}\n</div>\n` +
+        `</body>\n` +
+        `</html>\n`);
+}

package/dist/escape.d.ts

@@ -0,0 +1,7 @@
+/**
+ * HTML-escapes a string for safe insertion into either element text or a
+ * quoted attribute value. This is the engine's single escaping primitive:
+ * the plain-hast serialization is handled by `hast-util-to-html`, and every
+ * string a component or the fallback builds by hand goes through here.
+ */
+export declare function escapeHtml(value: string): string;

package/dist/escape.js

@@ -0,0 +1,23 @@
+/**
+ * The five characters that must never reach rendered HTML unescaped. `&`,
+ * `<`, and `>` matter in text; `"` and `'` matter inside an attribute value.
+ * Escaping all five unconditionally means one function is correct in both
+ * places, so a component author calling `ctx.esc` never has to know whether
+ * a string is about to land in text or in an attribute.
+ */
+const HTML_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+/**
+ * HTML-escapes a string for safe insertion into either element text or a
+ * quoted attribute value. This is the engine's single escaping primitive:
+ * the plain-hast serialization is handled by `hast-util-to-html`, and every
+ * string a component or the fallback builds by hand goes through here.
+ */
+export function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
+}

package/dist/failure-presentation.d.ts

@@ -0,0 +1,14 @@
+import type { FailureKind, ValueStatus } from '@markii/runtime';
+/** The short phrase for `kind`, or `undefined` if absent or not one of the four taxonomy members. */
+export declare function failurePhrase(kind: FailureKind | undefined): string | undefined;
+/** The `title` (tooltip) text for a failed/missing binding: the short phrase for `kind`, with `error` appended when there is one. */
+export declare function failureTitle(error: string | undefined, kind: FailureKind | undefined): string | undefined;
+/** The BEM-ish modifier class for `kind` under `base`, or `undefined` when `kind` is absent or out of taxonomy. */
+export declare function failureKindClass(base: string, kind: FailureKind | undefined): string | undefined;
+/**
+ * The full class list for a data-bound component's root element: `base`,
+ * plus `<base>--stale` for a stale binding, plus `<base>--<failureKind>` when
+ * the binding failed with a recognized kind. `extra` (a component's own
+ * state modifiers, e.g. `mk-chart--empty`) is kept adjacent to the base.
+ */
+export declare function dataStateClassName(base: string, status: ValueStatus | undefined, kind: FailureKind | undefined, extra?: readonly string[]): string;

package/dist/failure-presentation.js

@@ -0,0 +1,56 @@
+/**
+ * The `@markii/html` port of `@markii/react`'s `components/failure-
+ * presentation.ts` — the ONE place UI wording and CSS-class hooks for
+ * `@markii/runtime`'s failure taxonomy live in this engine. Ported (not
+ * imported) for the same reason `./resolve.ts` is ported: the module is not
+ * part of `@markii/react`'s public export surface, and the two renderers are
+ * independent implementations of the same presentation contract
+ * (docs/scripting.md), kept identical in wording and class vocabulary so a
+ * failing name reads the same in both.
+ *
+ * The presentation contract (AGENTS.md's cleanliness principle): a failure
+ * NEVER becomes body text. It surfaces as exactly two things — a `title`
+ * tooltip and a modifier class — layered on the component's quiet empty/
+ * stale state.
+ */
+/** Human-facing phrase per `FailureKind`. Null-prototype so an out-of-taxonomy `kind` can never resolve through the prototype chain. */
+const FAILURE_PHRASE = Object.assign(Object.create(null), {
+    'script-error': 'script error',
+    'capability-denied': 'needs permission',
+    'tier-blocked': 'requires manual run',
+    limit: 'limit exceeded',
+});
+/** The short phrase for `kind`, or `undefined` if absent or not one of the four taxonomy members. */
+export function failurePhrase(kind) {
+    if (kind === undefined)
+        return undefined;
+    return Object.hasOwn(FAILURE_PHRASE, kind) ? FAILURE_PHRASE[kind] : undefined;
+}
+/** The `title` (tooltip) text for a failed/missing binding: the short phrase for `kind`, with `error` appended when there is one. */
+export function failureTitle(error, kind) {
+    const phrase = failurePhrase(kind);
+    if (!phrase)
+        return error ? error : undefined;
+    return error ? `${phrase}: ${error}` : phrase;
+}
+/** The BEM-ish modifier class for `kind` under `base`, or `undefined` when `kind` is absent or out of taxonomy. */
+export function failureKindClass(base, kind) {
+    if (kind === undefined || !failurePhrase(kind))
+        return undefined;
+    return `${base}--${kind}`;
+}
+/**
+ * The full class list for a data-bound component's root element: `base`,
+ * plus `<base>--stale` for a stale binding, plus `<base>--<failureKind>` when
+ * the binding failed with a recognized kind. `extra` (a component's own
+ * state modifiers, e.g. `mk-chart--empty`) is kept adjacent to the base.
+ */
+export function dataStateClassName(base, status, kind, extra) {
+    const classes = [base, ...(extra ?? [])];
+    if (status === 'stale')
+        classes.push(`${base}--stale`);
+    const kindClass = failureKindClass(base, kind);
+    if (kindClass)
+        classes.push(kindClass);
+    return classes.join(' ');
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { renderMarkToHtml, renderMarkNodeToHtml } from './render.js';
+export { escapeHtml } from './escape.js';
+export { exportHtmlDocument, type ExportHtmlDocumentOptions, } from './document.js';
+export { resolveStorePath, resolveScopedPath, VAULT_NAME_PREFIX, type StorePathResolution, type ValueScope, } from './resolve.js';
+export { failurePhrase, failureTitle, failureKindClass, dataStateClassName, } from './failure-presentation.js';
+export { stringifyStoredValue } from './value-format.js';
+export { createHtmlRegistry, mergeHtmlRegistries, registryAliases, readRegistryComponent, resolveDirectiveAlias, REGISTRY_ALIASES, type DirectiveAttributes, type HtmlRegistry, type HtmlRegistryEntry, type HtmlComponent, type HtmlRenderContext, type RegistryAlias, type RegistryAliases, type ResolvedDirective, type ValueResolution, } from './registry.js';
+export { resolveLayoutAttributes, LAYOUT_ATTRIBUTE_KEYS, type ResolvedLayoutAttributes, } from './layout.js';

package/dist/index.js

@@ -0,0 +1,13 @@
+// @markii/html: a framework-free static HTML renderer for Markii documents.
+// It consumes @markii/core's sanitized hast and emits an HTML string, so a
+// stopped-changing document can be rendered for publishing, CI, email, or an
+// archive with no React runtime. It is one platform renderer among possible
+// many; the React renderer (@markii/react) is another consumer of the same core.
+export { renderMarkToHtml, renderMarkNodeToHtml } from './render.js';
+export { escapeHtml } from './escape.js';
+export { exportHtmlDocument, } from './document.js';
+export { resolveStorePath, resolveScopedPath, VAULT_NAME_PREFIX, } from './resolve.js';
+export { failurePhrase, failureTitle, failureKindClass, dataStateClassName, } from './failure-presentation.js';
+export { stringifyStoredValue } from './value-format.js';
+export { createHtmlRegistry, mergeHtmlRegistries, registryAliases, readRegistryComponent, resolveDirectiveAlias, REGISTRY_ALIASES, } from './registry.js';
+export { resolveLayoutAttributes, LAYOUT_ATTRIBUTE_KEYS, } from './layout.js';