@markii/html 0.12.1 → 0.14.0

package/dist/components/details.js

@@ -1,3 +1,4 @@
+import { INTERACTIVE_ATTRIBUTE } from '@markii/stdlib';
 const DEFAULT_TITLE = 'Details';
 /**
  * `:::details{title="..." open} ... :::` — a collapsible disclosure, folded
@@ -10,7 +11,9 @@ const DEFAULT_TITLE = 'Details';
 export const Details = (attributes, childrenHtml, ctx) => {
     const title = attributes.title ?? DEFAULT_TITLE;
     const open = Object.hasOwn(attributes, 'open');
+    // `@markii/stdlib`'s `INTERACTIVE_ATTRIBUTE` (#53), mirroring
+    // `@markii/react`'s `Details`.
     return (`<details class="mk-details"${open ? ' open' : ''}>` +
-        `<summary class="mk-details__summary">${ctx.esc(title)}</summary>` +
+        `<summary class="mk-details__summary" ${INTERACTIVE_ATTRIBUTE}="">${ctx.esc(title)}</summary>` +
         `<div class="mk-details__body">${childrenHtml}</div></details>`);
 };

package/dist/components/figure.d.ts

@@ -14,5 +14,11 @@ import type { HtmlComponent } from '../registry.js';
  * exact same allowlist check the sanitizer uses) and dropping the image
  * entirely when it fails, rather than re-implementing URL-scheme parsing
  * here. Matches `@markii/react`'s `Figure` markup byte-for-byte.
+ *
+ * `ctx.resolveImageSrc` (`../render.js`'s `renderMarkToHtml` option) then
+ * gets the same chance at an already-safe `src` that an ordinary markdown
+ * image gets (`../render.js`'s `applyImageResolver`), so a host resolving
+ * relative images sees this component's picture too, not just the ones
+ * markdown itself wrote.
  */
 export declare const Figure: HtmlComponent;

package/dist/components/figure.js

@@ -1,5 +1,9 @@
 import { isSafeUrl } from '@markii/core';
+import { reportDiagnostic } from '@markii/stdlib';
+import { resolveImageAttribute } from '../image-resolve.js';
+import { unsafeImageSrcTitle } from '../failure-presentation.js';
 const DEFAULT_ALT = '';
+const DIRECTIVE_NAME = 'figure';
 /**
  * `:::figure{src="..." alt="..."} caption markdown :::` — an image with a
  * rich (markdown) caption. `src` is required; a missing `src` renders no
@@ -15,14 +19,37 @@ const DEFAULT_ALT = '';
  * exact same allowlist check the sanitizer uses) and dropping the image
  * entirely when it fails, rather than re-implementing URL-scheme parsing
  * here. Matches `@markii/react`'s `Figure` markup byte-for-byte.
+ *
+ * `ctx.resolveImageSrc` (`../render.js`'s `renderMarkToHtml` option) then
+ * gets the same chance at an already-safe `src` that an ordinary markdown
+ * image gets (`../render.js`'s `applyImageResolver`), so a host resolving
+ * relative images sees this component's picture too, not just the ones
+ * markdown itself wrote.
  */
 export const Figure = (attributes, childrenHtml, ctx) => {
     const rawSrc = attributes.src ?? null;
     const alt = attributes.alt ?? DEFAULT_ALT;
-    const src = rawSrc && isSafeUrl(rawSrc) ? rawSrc : null;
+    const refused = Boolean(rawSrc) && !isSafeUrl(rawSrc);
+    const safeSrc = rawSrc && !refused ? rawSrc : null;
+    const src = safeSrc
+        ? resolveImageAttribute(safeSrc, ctx.resolveImageSrc)
+        : null;
     const imgHtml = src
         ? `<img class="mk-figure__img" src="${ctx.esc(src)}" alt="${ctx.esc(alt)}">`
         : '';
-    return (`<figure class="mk-figure">${imgHtml}` +
-        `<figcaption class="mk-figure__caption">${childrenHtml}</figcaption></figure>`);
+    const figcaptionHtml = `<figcaption class="mk-figure__caption">${childrenHtml}</figcaption>`;
+    // AGENTS.md "clean is not silent": a refused `src` used to render a
+    // caption with no image and no explanation. Mirrors `@markii/react`'s
+    // `Figure`.
+    if (refused) {
+        const message = unsafeImageSrcTitle(DIRECTIVE_NAME);
+        reportDiagnostic(ctx.onDiagnostic, {
+            kind: 'unsafe-image-src',
+            directive: DIRECTIVE_NAME,
+            message,
+        });
+        return (`<figure class="mk-figure" data-mk-notice="" title="${ctx.esc(message)}">` +
+            `${imgHtml}${figcaptionHtml}</figure>`);
+    }
+    return `<figure class="mk-figure">${imgHtml}${figcaptionHtml}</figure>`;
 };

package/dist/doc-css.generated.js

@@ -2,4 +2,4 @@
 // 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/*\n * ============================================================================\n * TIER 1 TOKENS — the theming contract\n * ============================================================================\n * Every host that wants a themed (in particular, a dark) `.doc` remaps ONLY\n * these custom properties, deliberately scoped to `.doc` and not `:root`:\n * `doc.css` is a library stylesheet embedded into other people's pages\n * (Obsidian injects it globally), so it must stay polite and never claim\n * `:root`. A host theme layer loaded after this one, at the same\n * specificity, simply redeclares the ones below on `.doc` (or a more\n * specific selector) to win the cascade — see `apps/vscode/src/webview/\n * theme.css` and `apps/obsidian/src/obsidian-theme.css`.\n *\n * Nine neutrals + five semantic hues. This list is deliberately small: a\n * host maps ~14 tokens instead of ~60 individual selectors, and a\n * derivation layer below (Tier 2) builds every finer shade FROM these, so\n * remapping these 14 makes every callout/badge/chart/etc. variant\n * theme-correct for free.\n */\n.doc {\n  /* ---------- neutrals ---------- */\n  --mk-bg: #fff; /* page ground */\n  --mk-raised: #fff; /* raised surface for cards — distinct from ground; dark themes need real separation here where light themes get it from the border alone */\n  --mk-fg: #1a1a1a; /* body text */\n  --mk-surface: #f4f4f5; /* subtle fill one step off the ground: pre, kbd, script marker, details, default callout, zebra rows */\n  --mk-surface-strong: #f0f0f2; /* second step off the ground: inline code, th, progress track, default badge background */\n  --mk-border: #e4e4e7; /* hairlines */\n  --mk-muted: #52525b; /* secondary text: captions, labels, script summary */\n  --mk-faint: #94a3b8; /* tertiary/empty: missing values, empty-chart text, unfilled stars */\n  --mk-accent: #3b82f6; /* the single interactive/brand color: active tab, progress bar, chart stroke/fill */\n  --mk-on-accent: #fff; /* ink that sits ON a solid --mk-accent fill; a host must supply this because it cannot be derived: it depends on the accent's own lightness, not on the page palette */\n\n  /* ---------- semantic hues ---------- */\n  --mk-info: #3b82f6;\n  --mk-success: #15803d;\n  --mk-warning: #d97706;\n  --mk-danger: #dc2626;\n  --mk-limit: #7c3aed; /* the purple, used for the \"hit a resource limit\" failure kind */\n\n  /* ---------- width presets (docs/format.md) ---------- */\n  /*\n   * The sizing half of the `width=`/`:::wide` etc. layout presets, as\n   * hooks a host theme layer can override (AGENTS.md's \"New Tier 1 token\"\n   * rule) — e.g. a host with a narrower reading column can shrink\n   * `--mk-width-wide` without touching any selector below. `fit` and\n   * `full` are exposed too even though their current values are a keyword\n   * and `100%` respectively, so all four sized presets are equally\n   * themeable; `normal` (the explicit default) produces no class and no\n   * box to size, so it has no token — there is nothing for a host to hook.\n   */\n  --mk-width-fit: fit-content;\n  --mk-width-narrow: 30rem;\n  --mk-width-wide: 64rem;\n  --mk-width-full: 100%;\n}\n\n/*\n * ============================================================================\n * DARK MODE (exported documents only) + the data-mk-theme override\n * ============================================================================\n * `@markii/html`'s `exportHtmlDocument` produces a standalone page with no\n * host page around it, so this is the one place `doc.css` picks a dark\n * palette for itself, guarded by `prefers-color-scheme: dark` rather than a\n * class, since a standalone file has nothing to put a class on.\n *\n * This does not touch how a HOST theme layer works. `apps/vscode/src/\n * webview/theme.css` and `apps/obsidian/src/obsidian-theme.css` are loaded\n * AFTER `doc.css` and redeclare these same tokens on a plain `.doc`\n * selector, unconditionally. At equal specificity the later, unconditional\n * rule always wins the cascade over this earlier, media-guarded one,\n * regardless of the reader's OS preference, so a themed host's own\n * light/dark handling is unaffected either way. Only a page with no such\n * layer after it, an exported document, ever resolves these.\n *\n * A viewer with no preference at all matches neither `light` nor `dark`\n * media features, so the Tier 1 defaults above stay exactly as they were.\n *\n * `data-mk-theme` lets a page or a host that manages its OWN theme opt out\n * of, or force, this automatic palette: `data-mk-theme=\"light\"` keeps the\n * light Tier 1 defaults no matter what the OS prefers, and\n * `data-mk-theme=\"dark\"` applies the dark palette unconditionally, outside\n * any media query. Both are attribute selectors on `.doc`\n * (specificity 0,2,0), deliberately higher than the plain `.doc` this\n * media block uses (0,1,0) and higher than the host theme layers above, so\n * an explicit attribute always wins over both the OS preference and a\n * host's own remap. The media block above is left at plain `.doc` on\n * purpose, NOT `.doc:not([data-mk-theme=\"light\"])`: raising ITS specificity\n * to (0,2,0) would make it beat the host theme layers too (which redeclare\n * on plain `.doc` and rely on winning by being later in the cascade at\n * equal specificity), breaking both hosts on a dark-preference machine. A\n * host that never sets `data-mk-theme` sees no change at all; the two\n * attribute values are an opt-in a page reaches for deliberately.\n *\n * The dark values below are declared twice on purpose (media-guarded and\n * forced), because `@media` cannot wrap only part of a selector list and\n * the forced path must apply even when the OS prefers light. `doc-css-\n * tokens.test.ts` asserts the two blocks carry identical values so they\n * cannot drift apart under a one-sided edit.\n */\n@media (prefers-color-scheme: dark) {\n  .doc {\n    --mk-bg: #14161c;\n    --mk-raised: #1c1f28;\n    --mk-fg: #e5e7eb;\n    --mk-surface: #1e212b;\n    --mk-surface-strong: #262a36;\n    --mk-border: #333846;\n    --mk-muted: #a1a8ba;\n    --mk-faint: #6b7280;\n    --mk-accent: #60a5fa;\n    --mk-on-accent: #0b1220;\n\n    --mk-info: #60a5fa;\n    --mk-success: #4ade80;\n    --mk-warning: #fbbf24;\n    --mk-danger: #f87171;\n    --mk-limit: #a78bfa;\n  }\n}\n\n.doc[data-mk-theme='light'] {\n  --mk-bg: #fff;\n  --mk-raised: #fff;\n  --mk-fg: #1a1a1a;\n  --mk-surface: #f4f4f5;\n  --mk-surface-strong: #f0f0f2;\n  --mk-border: #e4e4e7;\n  --mk-muted: #52525b;\n  --mk-faint: #94a3b8;\n  --mk-accent: #3b82f6;\n  --mk-on-accent: #fff;\n\n  --mk-info: #3b82f6;\n  --mk-success: #15803d;\n  --mk-warning: #d97706;\n  --mk-danger: #dc2626;\n  --mk-limit: #7c3aed;\n}\n\n.doc[data-mk-theme='dark'] {\n  --mk-bg: #14161c;\n  --mk-raised: #1c1f28;\n  --mk-fg: #e5e7eb;\n  --mk-surface: #1e212b;\n  --mk-surface-strong: #262a36;\n  --mk-border: #333846;\n  --mk-muted: #a1a8ba;\n  --mk-faint: #6b7280;\n  --mk-accent: #60a5fa;\n  --mk-on-accent: #0b1220;\n\n  --mk-info: #60a5fa;\n  --mk-success: #4ade80;\n  --mk-warning: #fbbf24;\n  --mk-danger: #f87171;\n  --mk-limit: #a78bfa;\n}\n\n/*\n * ============================================================================\n * TIER 2 DERIVATION FORMULAS\n * ============================================================================\n * Every finer shade `doc.css` needs (a callout's tinted background, a\n * badge's tinted text) is a MIX of a Tier 1 hue against `--mk-bg`/`--mk-fg`,\n * never a literal of its own. Because the mix targets those two tokens\n * specifically, a dark host palette flips the derived shade's polarity\n * correctly with no extra work on the host's part — the whole point of\n * this refactor.\n *\n * Exactly three named percentages are used anywhere in this file. A future\n * component reuses one of these three; it does not invent a fourth.\n *\n *   --mk-mix-variant-fill:  color-mix(in srgb, <hue> 14%, var(--mk-bg))\n *     A quiet tinted background — callout body fill.\n *   --mk-mix-strong-fill:   color-mix(in srgb, <hue> 18%, var(--mk-bg))\n *     A slightly stronger tinted background — badge background.\n *   --mk-mix-ink:           color-mix(in srgb, <hue> 85%, var(--mk-fg))\n *     A hue nudged toward body text — usable as ink (badge text, star\n *     color) or as a border (callout border).\n *\n * `color-mix()` is unsupported in most email clients, and a custom property\n * whose value fails to parse does not fall back — the declaration goes\n * invalid-at-computed-value and effectively vanishes. `doc.css` is embedded\n * verbatim into `@markii/html`'s `exportHtmlDocument`, whose documented\n * targets include email and archive output, so every derived token below is\n * defined TWICE: first as a literal hex (today's existing light-mode\n * value), then, guarded by `@supports (color: color-mix(in srgb, red,\n * red))`, redefined via the real mix. A modern browser or either Electron\n * host gets live derivation that tracks a remapped Tier 1 palette; an old\n * email client silently keeps exactly today's light palette.\n */\n.doc {\n  /* ---- literal light-mode fallback (used verbatim where color-mix is unsupported) ---- */\n  --mk-info-fill: #eff6ff;\n  --mk-info-strong-fill: #dbeafe;\n  --mk-info-ink: #3b82f6;\n  --mk-success-strong-fill: #dcfce7;\n  --mk-success-ink: #15803d;\n  --mk-warning-fill: #fffbeb;\n  --mk-warning-strong-fill: #fef3c7;\n  --mk-warning-ink: #d97706;\n  --mk-danger-fill: #fef2f2;\n  --mk-danger-strong-fill: #fee2e2;\n  --mk-danger-ink: #dc2626;\n  --mk-limit-ink: #7c3aed;\n  /*\n   * The keycap's inset depth line. Not a themed hue, but not theme-neutral\n   * either: a low-alpha BLACK line is invisible on a dark surface, so the\n   * literal below is only the no-`color-mix` fallback (where the palette is\n   * the light one anyway). The derivation in the `@supports` block below\n   * expresses it against `--mk-fg` instead, so it flips to a light line\n   * when a host supplies a dark palette, which is the correct depth cue\n   * there. Kept in this block, not the Tier 1 block above, so its literal\n   * stays inside a block the no-raw-color-literal test allows.\n   */\n  --mk-shadow-sm: rgba(0, 0, 0, 0.05);\n}\n\n@supports (color: color-mix(in srgb, red, red)) {\n  .doc {\n    --mk-shadow-sm: color-mix(in srgb, var(--mk-fg) 8%, transparent);\n\n    --mk-info-fill: color-mix(in srgb, var(--mk-info) 14%, var(--mk-bg));\n    --mk-info-strong-fill: color-mix(in srgb, var(--mk-info) 18%, var(--mk-bg));\n    --mk-info-ink: color-mix(in srgb, var(--mk-info) 85%, var(--mk-fg));\n\n    --mk-success-strong-fill: color-mix(\n      in srgb,\n      var(--mk-success) 18%,\n      var(--mk-bg)\n    );\n    --mk-success-ink: color-mix(in srgb, var(--mk-success) 85%, var(--mk-fg));\n\n    --mk-warning-fill: color-mix(in srgb, var(--mk-warning) 14%, var(--mk-bg));\n    --mk-warning-strong-fill: color-mix(\n      in srgb,\n      var(--mk-warning) 18%,\n      var(--mk-bg)\n    );\n    --mk-warning-ink: color-mix(in srgb, var(--mk-warning) 85%, var(--mk-fg));\n\n    --mk-danger-fill: color-mix(in srgb, var(--mk-danger) 14%, var(--mk-bg));\n    --mk-danger-strong-fill: color-mix(\n      in srgb,\n      var(--mk-danger) 18%,\n      var(--mk-bg)\n    );\n    --mk-danger-ink: color-mix(in srgb, var(--mk-danger) 85%, var(--mk-fg));\n\n    --mk-limit-ink: color-mix(in srgb, var(--mk-limit) 85%, var(--mk-fg));\n  }\n}\n\n.doc {\n  color: var(--mk-fg);\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: var(--mk-surface);\n  padding: 0.75rem 1rem;\n  border-radius: 6px;\n}\n\n.doc code {\n  background: var(--mk-surface-strong);\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 var(--mk-border);\n  padding: 0.4rem 0.75rem;\n  text-align: left;\n}\n\n.doc th {\n  font-weight: 600;\n  background: var(--mk-surface-strong);\n}\n\n.doc tr:nth-child(even) {\n  background: var(--mk-surface);\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, var(--mk-border));\n  border-left-width: 4px;\n  border-radius: 6px;\n  padding: 0.75rem 1rem;\n  background: var(--mk-callout-bg, var(--mk-surface));\n}\n\n.mk-callout--info {\n  --mk-callout-border: var(--mk-info-ink);\n  --mk-callout-bg: var(--mk-info-fill);\n}\n\n.mk-callout--warning {\n  --mk-callout-border: var(--mk-warning-ink);\n  --mk-callout-bg: var(--mk-warning-fill);\n}\n\n.mk-callout--danger {\n  --mk-callout-border: var(--mk-danger-ink);\n  --mk-callout-bg: var(--mk-danger-fill);\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 var(--mk-border);\n  border-bottom-width: 2px;\n  border-radius: 4px;\n  background: var(--mk-surface);\n  box-shadow: inset 0 -1px 0 var(--mk-shadow-sm);\n}\n\n/* ---------- rating ---------- */\n\n.mk-rating {\n  display: inline-flex;\n  gap: 0.15em;\n  font-size: 1.1em;\n  color: var(--mk-faint);\n}\n\n.mk-rating__star--filled {\n  color: var(--mk-warning);\n}\n\n/* ---------- divider ---------- */\n\n/*\n * The `::before`/`::after` pseudo-elements are the flanking hairlines; the\n * label sits between them as ordinary flex children. The label carries its\n * own inline margin rather than a flex `gap` because an unlabeled divider\n * has no label element to create a gap around — with `gap` the rule would\n * split into two disconnected segments instead of staying one unbroken\n * line.\n */\n\n.mk-divider {\n  display: flex;\n  align-items: center;\n  color: var(--mk-faint);\n}\n\n.mk-divider::before,\n.mk-divider::after {\n  content: '';\n  flex: 1 1 0;\n  border-block-start: 1px solid var(--mk-border);\n}\n\n.mk-divider--dots::before,\n.mk-divider--dots::after {\n  border-block-start-style: dotted;\n}\n\n.mk-divider--ornament::before,\n.mk-divider--ornament::after {\n  border-block-start-color: transparent;\n}\n\n.mk-divider--label-left::before {\n  flex: 0 0 1.5rem;\n}\n\n.mk-divider--label-right::after {\n  flex: 0 0 1.5rem;\n}\n\n.mk-divider__label {\n  margin-inline: 0.75em;\n  font-size: 0.85em;\n  color: var(--mk-muted);\n}\n\n.mk-divider__ornament {\n  margin-inline: 0.35em;\n  font-size: 0.9em;\n}\n\n/* ---------- value interpolation ---------- */\n\n.mk-value {\n  display: inline;\n  vertical-align: baseline;\n}\n\n.mk-value--stale {\n  color: var(--mk-warning-ink);\n  border-bottom: 1px dashed var(--mk-warning-ink);\n}\n\n.mk-value--missing {\n  font-family: ui-monospace, 'SFMono-Regular', Menlo, monospace;\n  font-size: 0.9em;\n  color: var(--mk-faint);\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 * Failure kinds map onto the Tier 1 semantic hues: script-error -> danger,\n * capability-denied -> warning, tier-blocked -> info, limit -> limit.\n */\n.mk-value--script-error {\n  border-bottom: 1px dashed var(--mk-danger-ink);\n}\n\n.mk-value--capability-denied {\n  border-bottom: 1px dashed var(--mk-warning-ink);\n}\n\n.mk-value--tier-blocked {\n  border-bottom: 1px dashed var(--mk-info-ink);\n}\n\n.mk-value--limit {\n  border-bottom: 1px dashed var(--mk-limit-ink);\n}\n\n/* ---------- script marker ---------- */\n\n.mk-script {\n  border: 1px solid var(--mk-border);\n  border-radius: 6px;\n  background: var(--mk-surface);\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: var(--mk-muted);\n}\n\n.mk-script[open] > .mk-script__summary {\n  border-bottom: 1px solid var(--mk-border);\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: var(--mk-faint);\n}\n\n/* ---------- details ---------- */\n\n.mk-details {\n  border: 1px solid var(--mk-border);\n  border-radius: 6px;\n  padding: 0.75rem 1rem;\n  background: var(--mk-surface);\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 var(--mk-border);\n  border-radius: 8px;\n  padding: 1rem;\n  background: var(--mk-raised);\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, var(--mk-fg));\n  background: var(--mk-badge-bg, var(--mk-surface-strong));\n}\n\n.mk-badge--info {\n  --mk-badge-fg: var(--mk-info-ink);\n  --mk-badge-bg: var(--mk-info-strong-fill);\n}\n\n.mk-badge--success {\n  --mk-badge-fg: var(--mk-success-ink);\n  --mk-badge-bg: var(--mk-success-strong-fill);\n}\n\n.mk-badge--warning {\n  --mk-badge-fg: var(--mk-warning-ink);\n  --mk-badge-bg: var(--mk-warning-strong-fill);\n}\n\n.mk-badge--danger {\n  --mk-badge-fg: var(--mk-danger-ink);\n  --mk-badge-bg: var(--mk-danger-strong-fill);\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: var(--mk-muted);\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 var(--mk-border);\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: var(--mk-muted);\n  border-bottom: 2px solid transparent;\n  margin-block-end: -1px;\n}\n\n.mk-tabs__button--active {\n  color: var(--mk-accent);\n  border-bottom-color: var(--mk-accent);\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: var(--mk-muted);\n}\n\n.mk-stat__delta {\n  font-size: 0.85em;\n  font-weight: 600;\n  color: var(--mk-muted);\n}\n\n.mk-stat__delta--up {\n  color: var(--mk-success-ink);\n}\n\n.mk-stat__delta--down {\n  color: var(--mk-danger-ink);\n}\n\n.mk-stat__delta--flat {\n  color: var(--mk-muted);\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: var(--mk-muted);\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: var(--mk-border);\n  overflow: hidden;\n}\n\n.mk-progress__bar {\n  height: 100%;\n  background: var(--mk-accent);\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: var(--mk-muted);\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: var(--mk-accent);\n  stroke-width: 2;\n  stroke-linejoin: round;\n  stroke-linecap: round;\n}\n\n.mk-chart__bar {\n  fill: var(--mk-accent);\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: var(--mk-faint);\n  border: 1px dashed var(--mk-border);\n  border-radius: 6px;\n}\n\n/* ---------- table (data-bound) ---------- */\n\n/*\n * `.mk-table` is the ROOT wrapper `Table` renders (docs/format.md's\n * `::table`), holding an optional `.mk-table__caption` and the real\n * `<table class=\"mk-table__table\">`. The `<table>`/`<th>`/`<td>` elements\n * inside it are deliberately left to `.doc table`/`.doc th`/`.doc td`\n * above — the same rules a bare GFM table already gets — so `mk-table`\n * never forks or duplicates that styling; only the wrapper and its two\n * non-`<table>` children need rules of their own.\n */\n.mk-table {\n  display: block;\n}\n\n.mk-table__caption {\n  font-size: 0.85em;\n  color: var(--mk-muted);\n  margin-block-end: 0.4rem;\n}\n\n.mk-table--empty .mk-table__empty {\n  font-size: 0.85em;\n  font-style: italic;\n  color: var(--mk-faint);\n  border: 1px dashed var(--mk-border);\n  border-radius: 6px;\n  padding: 0.5rem 0.75rem;\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.mk-table--stale {\n  opacity: 0.8;\n}\n\n.mk-stat--script-error,\n.mk-progress--script-error,\n.mk-chart--script-error,\n.mk-table--script-error {\n  border-bottom: 2px solid var(--mk-danger-ink);\n}\n\n.mk-stat--capability-denied,\n.mk-progress--capability-denied,\n.mk-chart--capability-denied,\n.mk-table--capability-denied {\n  border-bottom: 2px solid var(--mk-warning-ink);\n}\n\n.mk-stat--tier-blocked,\n.mk-progress--tier-blocked,\n.mk-chart--tier-blocked,\n.mk-table--tier-blocked {\n  border-bottom: 2px solid var(--mk-info-ink);\n}\n\n.mk-stat--limit,\n.mk-progress--limit,\n.mk-chart--limit,\n.mk-table--limit {\n  border-bottom: 2px solid var(--mk-limit-ink);\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(var(--mk-width-narrow), 100%);\n}\n\n.mk-width-wide {\n  max-width: min(var(--mk-width-wide), 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: var(--mk-width-full);\n}\n\n/*\n * \"fit\" is the one preset that sets `width` rather than only capping it: it\n * shrinks the block to its own content instead of filling the column, and\n * `max-width` keeps that from overflowing when the content is wider than\n * the column. Because the box is now narrower than its container, the\n * `mk-align-*` auto margins below finally have room to work, which is what\n * makes `{width=fit align=right}` hug the content AND sit right.\n */\n.mk-width-fit {\n  width: var(--mk-width-fit);\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 `:::center`/`:::left`/`:::right`/`:::wide`/`:::narrow`/`:::full`/`:::fit`\n * layout 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/*\n * An alignment wrapper additionally sets text alignment for everything in\n * scope, not just the shrink-to-fit block alignment below. `left` carries\n * its own rule for a reason: it is the one wrapper written specifically to\n * opt a scope back OUT of an alignment it inherited (a cell of a\n * `:::row{text=center}`), and only a DECLARED value beats an inherited one.\n * Without this rule `:::left` would silently keep the centered text it was\n * written to undo.\n */\n.mk-layout.mk-align-left {\n  text-align: left;\n}\n\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/* ---------- text alignment inside a component (docs/format.md) ---------- */\n\n/*\n * The `text` attribute of `row`, `cell`, `card`, and `callout`. Deliberately\n * separate from the `mk-align-*` classes above: those place a block's BOX\n * within the column and never touch its contents, while these align the\n * content inside one component and never move its box. Two different jobs,\n * two different class names, so neither can be mistaken for the other.\n *\n * One rule per value, defined once and honored by all four components, which\n * is what lets `:::row{text=center}` reach its cells through ordinary CSS\n * inheritance: `.mk-cell` declares no `text-align` of its own, so the row's\n * value flows in, and a cell that declares its own (or an alignment wrapper\n * written inside it) wins simply by being declared.\n */\n.mk-text-left {\n  text-align: left;\n}\n\n.mk-text-center {\n  text-align: center;\n}\n\n.mk-text-right {\n  text-align: right;\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/* ---------- 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/* ---------- empty inline-component marker ---------- */\n\n/*\n * Wraps an `inline: true` component that received no content\n * (`::badge{label=\"x\"}` instead of `:badge[x]`) — see `render.tsx`'s\n * `isRegisteredInline`/`isEmptyContent` and `render.ts`'s HTML-engine\n * mirror. The component underneath renders unchanged; this is a quiet\n * perceptual hook only (a faint dashed underline, matching the treatment\n * `.mk-value--stale` already gives a quiet-but-present state), with the\n * reason carried in the `title` tooltip rather than in the page.\n */\n.mk-inline-empty {\n  border-bottom: 1px dashed var(--mk-faint);\n}\n\n/* ---------- unknown directive fallback ---------- */\n\n.mk-unknown {\n  border: 1px dashed var(--mk-faint);\n  border-radius: 6px;\n  color: var(--mk-muted);\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";
+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:where(.doc, [data-mk-root]) > * + * {\n  margin-block-start: 1rem;\n}\n\n/*\n * ============================================================================\n * TIER 1 TOKENS — the theming contract\n * ============================================================================\n * Every host that wants a themed (in particular, a dark) `.doc` remaps ONLY\n * these custom properties, deliberately scoped to `.doc` and not `:root`:\n * `doc.css` is a library stylesheet embedded into other people's pages\n * (Obsidian injects it globally), so it must stay polite and never claim\n * `:root`. A host theme layer loaded after this one, at the same\n * specificity, simply redeclares the ones below on `.doc` (or a more\n * specific selector) to win the cascade — see `apps/vscode/src/webview/\n * theme.css` and `apps/obsidian/src/obsidian-theme.css`.\n *\n * Nine neutrals + five semantic hues. This list is deliberately small: a\n * host maps ~14 tokens instead of ~60 individual selectors, and a\n * derivation layer below (Tier 2) builds every finer shade FROM these, so\n * remapping these 14 makes every callout/badge/chart/etc. variant\n * theme-correct for free.\n */\n.doc {\n  /* ---------- neutrals ---------- */\n  --mk-bg: #fff; /* page ground */\n  --mk-raised: #fff; /* raised surface for cards — distinct from ground; dark themes need real separation here where light themes get it from the border alone */\n  --mk-fg: #1a1a1a; /* body text */\n  --mk-surface: #f4f4f5; /* subtle fill one step off the ground: pre, kbd, script marker, details, default callout, zebra rows */\n  --mk-surface-strong: #f0f0f2; /* second step off the ground: inline code, th, progress track, default badge background */\n  --mk-border: #e4e4e7; /* hairlines */\n  --mk-muted: #52525b; /* secondary text: captions, labels, script summary */\n  --mk-faint: #94a3b8; /* tertiary/empty: missing values, empty-chart text, unfilled stars */\n  --mk-accent: #3b82f6; /* the single interactive/brand color: active tab, progress bar, chart stroke/fill */\n  --mk-on-accent: #fff; /* ink that sits ON a solid --mk-accent fill; a host must supply this because it cannot be derived: it depends on the accent's own lightness, not on the page palette */\n\n  /* ---------- semantic hues ---------- */\n  --mk-info: #3b82f6;\n  --mk-success: #15803d;\n  --mk-warning: #d97706;\n  --mk-danger: #dc2626;\n  --mk-limit: #7c3aed; /* the purple, used for the \"hit a resource limit\" failure kind */\n\n  /* ---------- width presets (docs/format.md) ---------- */\n  /*\n   * The sizing half of the `width=`/`:::wide` etc. layout presets, as\n   * hooks a host theme layer can override (AGENTS.md's \"New Tier 1 token\"\n   * rule) — e.g. a host with a narrower reading column can shrink\n   * `--mk-width-wide` without touching any selector below. `fit` and\n   * `full` are exposed too even though their current values are a keyword\n   * and `100%` respectively, so all four sized presets are equally\n   * themeable; `normal` (the explicit default) produces no class and no\n   * box to size, so it has no token — there is nothing for a host to hook.\n   */\n  --mk-width-fit: fit-content;\n  --mk-width-narrow: 30rem;\n  --mk-width-wide: 64rem;\n  --mk-width-full: 100%;\n}\n\n/*\n * ============================================================================\n * DARK MODE (exported documents only) + the data-mk-theme override\n * ============================================================================\n * `@markii/html`'s `exportHtmlDocument` produces a standalone page with no\n * host page around it, so this is the one place `doc.css` picks a dark\n * palette for itself, guarded by `prefers-color-scheme: dark` rather than a\n * class, since a standalone file has nothing to put a class on.\n *\n * This does not touch how a HOST theme layer works. `apps/vscode/src/\n * webview/theme.css` and `apps/obsidian/src/obsidian-theme.css` are loaded\n * AFTER `doc.css` and redeclare these same tokens on a plain `.doc`\n * selector, unconditionally. At equal specificity the later, unconditional\n * rule always wins the cascade over this earlier, media-guarded one,\n * regardless of the reader's OS preference, so a themed host's own\n * light/dark handling is unaffected either way. Only a page with no such\n * layer after it, an exported document, ever resolves these.\n *\n * A viewer with no preference at all matches neither `light` nor `dark`\n * media features, so the Tier 1 defaults above stay exactly as they were.\n *\n * `data-mk-theme` lets a page or a host that manages its OWN theme opt out\n * of, or force, this automatic palette: `data-mk-theme=\"light\"` keeps the\n * light Tier 1 defaults no matter what the OS prefers, and\n * `data-mk-theme=\"dark\"` applies the dark palette unconditionally, outside\n * any media query. Both are attribute selectors on `.doc`\n * (specificity 0,2,0), deliberately higher than the plain `.doc` this\n * media block uses (0,1,0) and higher than the host theme layers above, so\n * an explicit attribute always wins over both the OS preference and a\n * host's own remap. The media block above is left at plain `.doc` on\n * purpose, NOT `.doc:not([data-mk-theme=\"light\"])`: raising ITS specificity\n * to (0,2,0) would make it beat the host theme layers too (which redeclare\n * on plain `.doc` and rely on winning by being later in the cascade at\n * equal specificity), breaking both hosts on a dark-preference machine. A\n * host that never sets `data-mk-theme` sees no change at all; the two\n * attribute values are an opt-in a page reaches for deliberately.\n *\n * The dark values below are declared twice on purpose (media-guarded and\n * forced), because `@media` cannot wrap only part of a selector list and\n * the forced path must apply even when the OS prefers light. `doc-css-\n * tokens.test.ts` asserts the two blocks carry identical values so they\n * cannot drift apart under a one-sided edit.\n */\n@media (prefers-color-scheme: dark) {\n  .doc {\n    --mk-bg: #14161c;\n    --mk-raised: #1c1f28;\n    --mk-fg: #e5e7eb;\n    --mk-surface: #1e212b;\n    --mk-surface-strong: #262a36;\n    --mk-border: #333846;\n    --mk-muted: #a1a8ba;\n    --mk-faint: #6b7280;\n    --mk-accent: #60a5fa;\n    --mk-on-accent: #0b1220;\n\n    --mk-info: #60a5fa;\n    --mk-success: #4ade80;\n    --mk-warning: #fbbf24;\n    --mk-danger: #f87171;\n    --mk-limit: #a78bfa;\n  }\n}\n\n.doc[data-mk-theme='light'] {\n  --mk-bg: #fff;\n  --mk-raised: #fff;\n  --mk-fg: #1a1a1a;\n  --mk-surface: #f4f4f5;\n  --mk-surface-strong: #f0f0f2;\n  --mk-border: #e4e4e7;\n  --mk-muted: #52525b;\n  --mk-faint: #94a3b8;\n  --mk-accent: #3b82f6;\n  --mk-on-accent: #fff;\n\n  --mk-info: #3b82f6;\n  --mk-success: #15803d;\n  --mk-warning: #d97706;\n  --mk-danger: #dc2626;\n  --mk-limit: #7c3aed;\n}\n\n.doc[data-mk-theme='dark'] {\n  --mk-bg: #14161c;\n  --mk-raised: #1c1f28;\n  --mk-fg: #e5e7eb;\n  --mk-surface: #1e212b;\n  --mk-surface-strong: #262a36;\n  --mk-border: #333846;\n  --mk-muted: #a1a8ba;\n  --mk-faint: #6b7280;\n  --mk-accent: #60a5fa;\n  --mk-on-accent: #0b1220;\n\n  --mk-info: #60a5fa;\n  --mk-success: #4ade80;\n  --mk-warning: #fbbf24;\n  --mk-danger: #f87171;\n  --mk-limit: #a78bfa;\n}\n\n/*\n * ============================================================================\n * TIER 2 DERIVATION FORMULAS\n * ============================================================================\n * Every finer shade `doc.css` needs (a callout's tinted background, a\n * badge's tinted text) is a MIX of a Tier 1 hue against `--mk-bg`/`--mk-fg`,\n * never a literal of its own. Because the mix targets those two tokens\n * specifically, a dark host palette flips the derived shade's polarity\n * correctly with no extra work on the host's part — the whole point of\n * this refactor.\n *\n * Exactly three named percentages are used anywhere in this file. A future\n * component reuses one of these three; it does not invent a fourth.\n *\n *   --mk-mix-variant-fill:  color-mix(in srgb, <hue> 14%, var(--mk-bg))\n *     A quiet tinted background — callout body fill.\n *   --mk-mix-strong-fill:   color-mix(in srgb, <hue> 18%, var(--mk-bg))\n *     A slightly stronger tinted background — badge background.\n *   --mk-mix-ink:           color-mix(in srgb, <hue> 85%, var(--mk-fg))\n *     A hue nudged toward body text — usable as ink (badge text, star\n *     color) or as a border (callout border).\n *\n * `color-mix()` is unsupported in most email clients, and a custom property\n * whose value fails to parse does not fall back — the declaration goes\n * invalid-at-computed-value and effectively vanishes. `doc.css` is embedded\n * verbatim into `@markii/html`'s `exportHtmlDocument`, whose documented\n * targets include email and archive output, so every derived token below is\n * defined TWICE: first as a literal hex (today's existing light-mode\n * value), then, guarded by `@supports (color: color-mix(in srgb, red,\n * red))`, redefined via the real mix. A modern browser or either Electron\n * host gets live derivation that tracks a remapped Tier 1 palette; an old\n * email client silently keeps exactly today's light palette.\n *\n * Scoped to `:where(.doc, [data-mk-root])`, not `.doc` alone: a host that\n * renders into its own container class (not `.doc`) sets its Tier 1\n * overrides on that same element, and can opt this derivation layer (and\n * every other `.doc`-scoped rule below that a document needs — rhythm,\n * base typography, table/code/list styling) onto it by adding a bare\n * `data-mk-root` attribute, with no class rename and no forked stylesheet.\n * `:where()` keeps the added selector at zero specificity, so a host theme\n * layer that redeclares these on plain `.doc` still wins exactly as\n * before. Never hoisted to `:root`: a custom property resolves where it is\n * declared, so a `:root` derivation would freeze to whichever palette is\n * in scope there and could not re-derive for a differently themed\n * descendant.\n */\n:where(.doc, [data-mk-root]) {\n  /* ---- literal light-mode fallback (used verbatim where color-mix is unsupported) ---- */\n  --mk-info-fill: #eff6ff;\n  --mk-info-strong-fill: #dbeafe;\n  --mk-info-ink: #3b82f6;\n  --mk-success-strong-fill: #dcfce7;\n  --mk-success-ink: #15803d;\n  --mk-warning-fill: #fffbeb;\n  --mk-warning-strong-fill: #fef3c7;\n  --mk-warning-ink: #d97706;\n  --mk-danger-fill: #fef2f2;\n  --mk-danger-strong-fill: #fee2e2;\n  --mk-danger-ink: #dc2626;\n  --mk-limit-ink: #7c3aed;\n  /*\n   * The keycap's inset depth line. Not a themed hue, but not theme-neutral\n   * either: a low-alpha BLACK line is invisible on a dark surface, so the\n   * literal below is only the no-`color-mix` fallback (where the palette is\n   * the light one anyway). The derivation in the `@supports` block below\n   * expresses it against `--mk-fg` instead, so it flips to a light line\n   * when a host supplies a dark palette, which is the correct depth cue\n   * there. Kept in this block, not the Tier 1 block above, so its literal\n   * stays inside a block the no-raw-color-literal test allows.\n   */\n  --mk-shadow-sm: rgba(0, 0, 0, 0.05);\n}\n\n@supports (color: color-mix(in srgb, red, red)) {\n  :where(.doc, [data-mk-root]) {\n    --mk-shadow-sm: color-mix(in srgb, var(--mk-fg) 8%, transparent);\n\n    --mk-info-fill: color-mix(in srgb, var(--mk-info) 14%, var(--mk-bg));\n    --mk-info-strong-fill: color-mix(in srgb, var(--mk-info) 18%, var(--mk-bg));\n    --mk-info-ink: color-mix(in srgb, var(--mk-info) 85%, var(--mk-fg));\n\n    --mk-success-strong-fill: color-mix(\n      in srgb,\n      var(--mk-success) 18%,\n      var(--mk-bg)\n    );\n    --mk-success-ink: color-mix(in srgb, var(--mk-success) 85%, var(--mk-fg));\n\n    --mk-warning-fill: color-mix(in srgb, var(--mk-warning) 14%, var(--mk-bg));\n    --mk-warning-strong-fill: color-mix(\n      in srgb,\n      var(--mk-warning) 18%,\n      var(--mk-bg)\n    );\n    --mk-warning-ink: color-mix(in srgb, var(--mk-warning) 85%, var(--mk-fg));\n\n    --mk-danger-fill: color-mix(in srgb, var(--mk-danger) 14%, var(--mk-bg));\n    --mk-danger-strong-fill: color-mix(\n      in srgb,\n      var(--mk-danger) 18%,\n      var(--mk-bg)\n    );\n    --mk-danger-ink: color-mix(in srgb, var(--mk-danger) 85%, var(--mk-fg));\n\n    --mk-limit-ink: color-mix(in srgb, var(--mk-limit) 85%, var(--mk-fg));\n  }\n}\n\n:where(.doc, [data-mk-root]) {\n  color: var(--mk-fg);\n  font-family:\n    system-ui,\n    -apple-system,\n    'Segoe UI',\n    sans-serif;\n  line-height: 1.6;\n}\n\n:where(.doc, [data-mk-root]) pre {\n  overflow-x: auto;\n  background: var(--mk-surface);\n  padding: 0.75rem 1rem;\n  border-radius: 6px;\n}\n\n:where(.doc, [data-mk-root]) code {\n  background: var(--mk-surface-strong);\n  border-radius: 3px;\n  padding: 0.1em 0.35em;\n  font-size: 0.9em;\n}\n\n:where(.doc, [data-mk-root]) 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:where(.doc, [data-mk-root]) table {\n  display: block;\n  overflow-x: auto;\n  border-collapse: collapse;\n  font-size: 0.95em;\n}\n\n:where(.doc, [data-mk-root]) th,\n:where(.doc, [data-mk-root]) td {\n  border: 1px solid var(--mk-border);\n  padding: 0.4rem 0.75rem;\n  text-align: left;\n}\n\n:where(.doc, [data-mk-root]) th {\n  font-weight: 600;\n  background: var(--mk-surface-strong);\n}\n\n:where(.doc, [data-mk-root]) tr:nth-child(even) {\n  background: var(--mk-surface);\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:where(.doc, [data-mk-root]) li:has(> input[type='checkbox']) {\n  list-style: none;\n  margin-inline-start: -1.5em;\n}\n\n:where(.doc, [data-mk-root]) 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, var(--mk-border));\n  border-left-width: 4px;\n  border-radius: 6px;\n  padding: 0.75rem 1rem;\n  background: var(--mk-callout-bg, var(--mk-surface));\n}\n\n.mk-callout--info {\n  --mk-callout-border: var(--mk-info-ink);\n  --mk-callout-bg: var(--mk-info-fill);\n}\n\n.mk-callout--warning {\n  --mk-callout-border: var(--mk-warning-ink);\n  --mk-callout-bg: var(--mk-warning-fill);\n}\n\n.mk-callout--danger {\n  --mk-callout-border: var(--mk-danger-ink);\n  --mk-callout-bg: var(--mk-danger-fill);\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 var(--mk-border);\n  border-bottom-width: 2px;\n  border-radius: 4px;\n  background: var(--mk-surface);\n  box-shadow: inset 0 -1px 0 var(--mk-shadow-sm);\n}\n\n/* ---------- rating ---------- */\n\n.mk-rating {\n  display: inline-flex;\n  gap: 0.15em;\n  font-size: 1.1em;\n  color: var(--mk-faint);\n}\n\n.mk-rating__star--filled {\n  color: var(--mk-warning);\n}\n\n/* ---------- divider ---------- */\n\n/*\n * The `::before`/`::after` pseudo-elements are the flanking hairlines; the\n * label sits between them as ordinary flex children. The label carries its\n * own inline margin rather than a flex `gap` because an unlabeled divider\n * has no label element to create a gap around — with `gap` the rule would\n * split into two disconnected segments instead of staying one unbroken\n * line.\n */\n\n.mk-divider {\n  display: flex;\n  align-items: center;\n  color: var(--mk-faint);\n}\n\n.mk-divider::before,\n.mk-divider::after {\n  content: '';\n  flex: 1 1 0;\n  border-block-start: 1px solid var(--mk-border);\n}\n\n.mk-divider--dots::before,\n.mk-divider--dots::after {\n  border-block-start-style: dotted;\n}\n\n.mk-divider--ornament::before,\n.mk-divider--ornament::after {\n  border-block-start-color: transparent;\n}\n\n.mk-divider--label-left::before {\n  flex: 0 0 1.5rem;\n}\n\n.mk-divider--label-right::after {\n  flex: 0 0 1.5rem;\n}\n\n.mk-divider__label {\n  margin-inline: 0.75em;\n  font-size: 0.85em;\n  color: var(--mk-muted);\n}\n\n.mk-divider__ornament {\n  margin-inline: 0.35em;\n  font-size: 0.9em;\n}\n\n/* ---------- value interpolation ---------- */\n\n.mk-value {\n  display: inline;\n  vertical-align: baseline;\n}\n\n.mk-value--stale {\n  color: var(--mk-warning-ink);\n  border-bottom: 1px dashed var(--mk-warning-ink);\n}\n\n.mk-value--missing {\n  font-family: ui-monospace, 'SFMono-Regular', Menlo, monospace;\n  font-size: 0.9em;\n  color: var(--mk-faint);\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 * Failure kinds map onto the Tier 1 semantic hues: script-error -> danger,\n * capability-denied -> warning, tier-blocked -> info, limit -> limit.\n */\n.mk-value--script-error {\n  border-bottom: 1px dashed var(--mk-danger-ink);\n}\n\n.mk-value--capability-denied {\n  border-bottom: 1px dashed var(--mk-warning-ink);\n}\n\n.mk-value--tier-blocked {\n  border-bottom: 1px dashed var(--mk-info-ink);\n}\n\n.mk-value--limit {\n  border-bottom: 1px dashed var(--mk-limit-ink);\n}\n\n/* ---------- script marker ---------- */\n\n.mk-script {\n  border: 1px solid var(--mk-border);\n  border-radius: 6px;\n  background: var(--mk-surface);\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: var(--mk-muted);\n}\n\n.mk-script[open] > .mk-script__summary {\n  border-bottom: 1px solid var(--mk-border);\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: var(--mk-faint);\n}\n\n/* ---------- details ---------- */\n\n.mk-details {\n  border: 1px solid var(--mk-border);\n  border-radius: 6px;\n  padding: 0.75rem 1rem;\n  background: var(--mk-surface);\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 var(--mk-border);\n  border-radius: 8px;\n  padding: 1rem;\n  background: var(--mk-raised);\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, var(--mk-fg));\n  background: var(--mk-badge-bg, var(--mk-surface-strong));\n}\n\n.mk-badge--info {\n  --mk-badge-fg: var(--mk-info-ink);\n  --mk-badge-bg: var(--mk-info-strong-fill);\n}\n\n.mk-badge--success {\n  --mk-badge-fg: var(--mk-success-ink);\n  --mk-badge-bg: var(--mk-success-strong-fill);\n}\n\n.mk-badge--warning {\n  --mk-badge-fg: var(--mk-warning-ink);\n  --mk-badge-bg: var(--mk-warning-strong-fill);\n}\n\n.mk-badge--danger {\n  --mk-badge-fg: var(--mk-danger-ink);\n  --mk-badge-bg: var(--mk-danger-strong-fill);\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: var(--mk-muted);\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 var(--mk-border);\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: var(--mk-muted);\n  border-bottom: 2px solid transparent;\n  margin-block-end: -1px;\n}\n\n.mk-tabs__button--active {\n  color: var(--mk-accent);\n  border-bottom-color: var(--mk-accent);\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: var(--mk-muted);\n}\n\n.mk-stat__delta {\n  font-size: 0.85em;\n  font-weight: 600;\n  color: var(--mk-muted);\n}\n\n.mk-stat__delta--up {\n  color: var(--mk-success-ink);\n}\n\n.mk-stat__delta--down {\n  color: var(--mk-danger-ink);\n}\n\n.mk-stat__delta--flat {\n  color: var(--mk-muted);\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: var(--mk-muted);\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: var(--mk-border);\n  overflow: hidden;\n}\n\n.mk-progress__bar {\n  height: 100%;\n  background: var(--mk-accent);\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: var(--mk-muted);\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: var(--mk-accent);\n  stroke-width: 2;\n  stroke-linejoin: round;\n  stroke-linecap: round;\n}\n\n.mk-chart__bar {\n  fill: var(--mk-accent);\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: var(--mk-faint);\n  border: 1px dashed var(--mk-border);\n  border-radius: 6px;\n}\n\n/* ---------- table (data-bound) ---------- */\n\n/*\n * `.mk-table` is the ROOT wrapper `Table` renders (docs/format.md's\n * `::table`), holding an optional `.mk-table__caption` and the real\n * `<table class=\"mk-table__table\">`. The `<table>`/`<th>`/`<td>` elements\n * inside it are deliberately left to `.doc table`/`.doc th`/`.doc td`\n * above — the same rules a bare GFM table already gets — so `mk-table`\n * never forks or duplicates that styling; only the wrapper and its two\n * non-`<table>` children need rules of their own.\n */\n.mk-table {\n  display: block;\n}\n\n.mk-table__caption {\n  font-size: 0.85em;\n  color: var(--mk-muted);\n  margin-block-end: 0.4rem;\n}\n\n.mk-table--empty .mk-table__empty {\n  font-size: 0.85em;\n  font-style: italic;\n  color: var(--mk-faint);\n  border: 1px dashed var(--mk-border);\n  border-radius: 6px;\n  padding: 0.5rem 0.75rem;\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.mk-table--stale {\n  opacity: 0.8;\n}\n\n.mk-stat--script-error,\n.mk-progress--script-error,\n.mk-chart--script-error,\n.mk-table--script-error {\n  border-bottom: 2px solid var(--mk-danger-ink);\n}\n\n.mk-stat--capability-denied,\n.mk-progress--capability-denied,\n.mk-chart--capability-denied,\n.mk-table--capability-denied {\n  border-bottom: 2px solid var(--mk-warning-ink);\n}\n\n.mk-stat--tier-blocked,\n.mk-progress--tier-blocked,\n.mk-chart--tier-blocked,\n.mk-table--tier-blocked {\n  border-bottom: 2px solid var(--mk-info-ink);\n}\n\n.mk-stat--limit,\n.mk-progress--limit,\n.mk-chart--limit,\n.mk-table--limit {\n  border-bottom: 2px solid var(--mk-limit-ink);\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(var(--mk-width-narrow), 100%);\n}\n\n.mk-width-wide {\n  max-width: min(var(--mk-width-wide), 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: var(--mk-width-full);\n}\n\n/*\n * \"fit\" is the one preset that sets `width` rather than only capping it: it\n * shrinks the block to its own content instead of filling the column, and\n * `max-width` keeps that from overflowing when the content is wider than\n * the column. Because the box is now narrower than its container, the\n * `mk-align-*` auto margins below finally have room to work, which is what\n * makes `{width=fit align=right}` hug the content AND sit right.\n */\n.mk-width-fit {\n  width: var(--mk-width-fit);\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 * `align=` with NO width preset is a documented no-op (docs/format.md): the\n * wrapper above fills its container exactly like an unwrapped block, so\n * `margin-inline: auto` has zero free space to distribute and moves\n * nothing. That is fine in normal flow, where \"no free space\" simply means\n * \"nothing visibly happens\" — but a `.mk-row`/`.mk-row--cols-*` track is a\n * GRID, and a grid item with an auto inline margin is pulled OUT of the\n * default stretch alignment regardless of whether that margin has any space\n * to consume (CSS Box Alignment's \"auto margins win over alignment\" rule),\n * so the item shrinks to its own content size instead of filling its\n * column. For a card with no body that content size is just its padding,\n * which reads as the card collapsing into itself (#56) the instant\n * `align=` is added, even though `align=` alone was never supposed to\n * change the card's size.\n *\n * These three rules restore the no-op, but only inside `.mk-row`, and only\n * when no `mk-width-*` preset also applies: the margin goes back to a\n * literal `0`, so the item has no auto margin left to suppress stretch and\n * fills its column exactly as it would with no `align=` at all. The\n * `:not()` list is what lets `{width=narrow align=right}` keep shrinking\n * and moving inside a row: that combination still matches the base rules\n * above, since a width preset means the wrapper carries a real size for the\n * auto margin to act on rather than a no-op default full-column width.\n * `.mk-layout.mk-align-*` (the `:::center`/`:::left`/`:::right` wrappers)\n * are covered by the same plain `.mk-align-*` class, since a selector on\n * one class matches an element carrying several.\n */\n.mk-row\n  > .mk-align-left:not(.mk-width-fit):not(.mk-width-narrow):not(\n    .mk-width-wide\n  ):not(.mk-width-full),\n.mk-row\n  > .mk-align-center:not(.mk-width-fit):not(.mk-width-narrow):not(\n    .mk-width-wide\n  ):not(.mk-width-full),\n.mk-row\n  > .mk-align-right:not(.mk-width-fit):not(.mk-width-narrow):not(\n    .mk-width-wide\n  ):not(.mk-width-full) {\n  margin-inline: 0;\n}\n\n/*\n * The `:::center`/`:::left`/`:::right`/`:::wide`/`:::narrow`/`:::full`/`:::fit`\n * layout 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/*\n * An alignment wrapper additionally sets text alignment for everything in\n * scope, not just the shrink-to-fit block alignment below. `left` carries\n * its own rule for a reason: it is the one wrapper written specifically to\n * opt a scope back OUT of an alignment it inherited (a cell of a\n * `:::row{text=center}`), and only a DECLARED value beats an inherited one.\n * Without this rule `:::left` would silently keep the centered text it was\n * written to undo.\n */\n.mk-layout.mk-align-left {\n  text-align: left;\n}\n\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/* ---------- text alignment inside a component (docs/format.md) ---------- */\n\n/*\n * The `text` attribute of `row`, `cell`, `card`, and `callout`. Deliberately\n * separate from the `mk-align-*` classes above: those place a block's BOX\n * within the column and never touch its contents, while these align the\n * content inside one component and never move its box. Two different jobs,\n * two different class names, so neither can be mistaken for the other.\n *\n * One rule per value, defined once and honored by all four components, which\n * is what lets `:::row{text=center}` reach its cells through ordinary CSS\n * inheritance: `.mk-cell` declares no `text-align` of its own, so the row's\n * value flows in, and a cell that declares its own (or an alignment wrapper\n * written inside it) wins simply by being declared.\n */\n.mk-text-left {\n  text-align: left;\n}\n\n.mk-text-center {\n  text-align: center;\n}\n\n.mk-text-right {\n  text-align: right;\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/* ---------- 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/* ---------- empty inline-component marker ---------- */\n\n/*\n * Wraps an `inline: true` component that received no content\n * (`::badge{label=\"x\"}` instead of `:badge[x]`) — see `render.tsx`'s\n * `isRegisteredInline`/`isEmptyContent` and `render.ts`'s HTML-engine\n * mirror. The component underneath renders unchanged; this is a quiet\n * perceptual hook only (a faint dashed underline, matching the treatment\n * `.mk-value--stale` already gives a quiet-but-present state), with the\n * reason carried in the `title` tooltip rather than in the page.\n */\n.mk-inline-empty {\n  border-bottom: 1px dashed var(--mk-faint);\n}\n\n/* ---------- recognized-and-declined value marker ---------- */\n\n/*\n * The generic marker for a value the render pipeline recognized and\n * declined to use, rather than silently dropping it (AGENTS.md's \"clean is\n * not silent\"): a known attribute's value outside its closed enum, or a\n * `figure` `src` refused as unsafe (`failure-presentation.ts`'s\n * `NOTICE_ATTRIBUTE`). The component underneath renders exactly as it\n * would otherwise, wrapped in a plain `<span>` (inline directive) or\n * `<div>` (block directive) carrying this attribute and a `title` with the\n * reason. Styled as an attribute selector, not a class, so the same rule\n * applies no matter which element the wrapper turns out to be.\n */\n[data-mk-notice] {\n  outline: 1px dashed var(--mk-faint);\n  outline-offset: 2px;\n}\n\n/* ---------- unknown directive fallback ---------- */\n\n.mk-unknown {\n  border: 1px dashed var(--mk-faint);\n  border-radius: 6px;\n  color: var(--mk-muted);\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/failure-presentation.d.ts

@@ -22,3 +22,15 @@ export declare function dataStateClassName(base: string, status: ValueStatus | u
 export declare const EMPTY_INLINE_MARKER_CLASS = "mk-inline-empty";
 /** The `title` tooltip for `EMPTY_INLINE_MARKER_CLASS`. Ported verbatim from `@markii/react`. */
 export declare function emptyInlineTitle(name: string): string;
+/**
+ * The attribute both engines set on a component's own rendered output for a
+ * quiet marker over a recognized-and-declined value (a known attribute's
+ * value outside its enum, or a `figure` `src` refused as unsafe). Ported
+ * from `@markii/react`'s copy; see that copy's doc comment for the full
+ * rationale.
+ */
+export declare const NOTICE_ATTRIBUTE = "data-mk-notice";
+/** The `title` tooltip for `NOTICE_ATTRIBUTE` on an enum mismatch. Ported verbatim from `@markii/react`. */
+export declare function invalidAttributeValueTitle(directive: string, attribute: string, value: string): string;
+/** The `title` tooltip for `NOTICE_ATTRIBUTE` on a `figure` with a refused `src`. Ported verbatim from `@markii/react`. */
+export declare function unsafeImageSrcTitle(directive: string): string;

package/dist/failure-presentation.js

@@ -66,3 +66,19 @@ export const EMPTY_INLINE_MARKER_CLASS = 'mk-inline-empty';
 export function emptyInlineTitle(name) {
     return `${name}: no content (an attribute may have been used where directive text was expected)`;
 }
+/**
+ * The attribute both engines set on a component's own rendered output for a
+ * quiet marker over a recognized-and-declined value (a known attribute's
+ * value outside its enum, or a `figure` `src` refused as unsafe). Ported
+ * from `@markii/react`'s copy; see that copy's doc comment for the full
+ * rationale.
+ */
+export const NOTICE_ATTRIBUTE = 'data-mk-notice';
+/** The `title` tooltip for `NOTICE_ATTRIBUTE` on an enum mismatch. Ported verbatim from `@markii/react`. */
+export function invalidAttributeValueTitle(directive, attribute, value) {
+    return `${directive}: "${value}" is not a valid ${attribute} value (ignored)`;
+}
+/** The `title` tooltip for `NOTICE_ATTRIBUTE` on a `figure` with a refused `src`. Ported verbatim from `@markii/react`. */
+export function unsafeImageSrcTitle(directive) {
+    return `${directive}: image source was refused as unsafe and was not shown`;
+}

package/dist/href-resolve.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The link-rewrite twin of `./image-resolve.js`'s `resolveImageSrc`:
+ * `renderMarkToHtml`'s `resolveHref` option (`render.ts`'s
+ * `RenderMarkOptions`), applied to every `<a href>` an ordinary markdown
+ * link produces. Nothing in the standard component set builds its own
+ * `<a>` today, so this seam only ever touches links the parser itself
+ * emitted. Mirrors `@markii/react`'s `href-resolve.ts`.
+ *
+ * Same resolvability rule as images (no scheme, no protocol-relative
+ * `//host/...`, no bare `#fragment`, not empty), and the same
+ * `javascript:`/`vbscript:` refusal on the resolver's OWN return value,
+ * both shared with `./image-resolve.js` via `./url-resolve.js`, never
+ * copied, so the two seams cannot drift on what counts as a dangerous
+ * scheme.
+ */
+export type ResolveHref = (href: string) => string | undefined;
+/**
+ * The value one `<a href>` should actually carry: `value` unchanged unless
+ * `resolveHref` is present, `value` is worth resolving at all, the resolver
+ * returns something, and that something passes `isSafeResolvedUrl`. A
+ * resolver that throws is treated exactly like one that returned
+ * `undefined`: `value` is kept, and the render is never broken over one
+ * link.
+ */
+export declare function resolveHrefAttribute(value: string, resolveHref: ResolveHref | undefined): string;

package/dist/href-resolve.js

@@ -0,0 +1,25 @@
+import { isResolvableRelativeValue, isSafeResolvedUrl } from './url-resolve.js';
+/**
+ * The value one `<a href>` should actually carry: `value` unchanged unless
+ * `resolveHref` is present, `value` is worth resolving at all, the resolver
+ * returns something, and that something passes `isSafeResolvedUrl`. A
+ * resolver that throws is treated exactly like one that returned
+ * `undefined`: `value` is kept, and the render is never broken over one
+ * link.
+ */
+export function resolveHrefAttribute(value, resolveHref) {
+    if (!resolveHref)
+        return value;
+    if (!isResolvableRelativeValue(value))
+        return value;
+    let resolved;
+    try {
+        resolved = resolveHref(value);
+    }
+    catch {
+        return value;
+    }
+    if (resolved === undefined)
+        return value;
+    return isSafeResolvedUrl(resolved) ? resolved : value;
+}

package/dist/image-resolve.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The shared logic behind `renderMarkToHtml`'s `resolveImageSrc` option
+ * (see `render.ts`'s `RenderMarkOptions`), used everywhere an `<img>`
+ * reaches the output string: an ordinary markdown image (`render.ts`'s
+ * `makeTransform`, which rewrites a plain hast `img` element in place) and
+ * the standard `Figure` component, which builds its own `<img>` HTML from a
+ * directive attribute rather than from parsed markdown.
+ *
+ * A host resolver is only ever asked about a source that could plausibly
+ * be its own: one with no scheme, no protocol-relative `//host/...` form,
+ * no bare `#fragment`, and no empty/whitespace value — `./url-resolve.js`'s
+ * `isResolvableRelativeValue`, shared with `resolveHref`
+ * (`./href-resolve.js`) rather than duplicated, and the identical rule
+ * `@markii/react`'s `image-resolve.ts` applies.
+ *
+ * WHY THE RESULT CHECK IS NOT `isSafeUrl`. `isSafeUrl`'s allowlist
+ * (`http`/`https`/`mailto`/`tel`) exists to judge a URL an AUTHOR typed
+ * into the document, where any other scheme is suspicious. A resolver's
+ * RETURN VALUE is the opposite trust direction: it is the HOST's own
+ * answer for where its resolved image actually lives, and both reference
+ * hosts already return values `isSafeUrl` would reject outright — VS
+ * Code's embedded bundle assets are `data:image/...` URIs and Obsidian's
+ * vault resource path is an `app://` URL (`@markii/react`'s
+ * `image-resolve.ts` names both call sites). Applying `isSafeUrl` here
+ * would blank every image either host resolves. What still needs guarding
+ * against is a resolver, hostile or merely buggy, echoing a
+ * `javascript:`/`vbscript:` value back out — the one class of scheme that
+ * turns an `<img src>` into a script-execution vector rather than an image
+ * request. `./url-resolve.js`'s `isSafeResolvedUrl` is a narrow denylist
+ * for exactly that, not a repeat of the author-facing allowlist. Matches
+ * `@markii/react`'s identical function so the two engines cannot diverge.
+ */
+/** The shape `renderMarkToHtml`/`renderMarkNodeToHtml` accept, and the one carried on `HtmlRenderContext` for a component that builds its own `<img>`. */
+export type ResolveImageSrc = (src: string) => string | undefined;
+/**
+ * The value one `<img src>` should actually carry: `value` unchanged unless
+ * `resolveImageSrc` is present, `value` is worth resolving at all, the
+ * resolver returns something, and that something passes
+ * `isSafeResolvedUrl` — so a resolver can never smuggle a
+ * `javascript:` URL past the sanitizer that already ran on everything else
+ * in the document, while a legitimate `data:`/`app:`/host-scheme result
+ * still reaches the page. A resolver that throws is treated exactly like
+ * one that returned `undefined`: `value` is kept, and the render is never
+ * broken over one image.
+ */
+export declare function resolveImageAttribute(value: string, resolveImageSrc: ResolveImageSrc | undefined): string;

package/dist/image-resolve.js

@@ -0,0 +1,28 @@
+import { isResolvableRelativeValue, isSafeResolvedUrl } from './url-resolve.js';
+/**
+ * The value one `<img src>` should actually carry: `value` unchanged unless
+ * `resolveImageSrc` is present, `value` is worth resolving at all, the
+ * resolver returns something, and that something passes
+ * `isSafeResolvedUrl` — so a resolver can never smuggle a
+ * `javascript:` URL past the sanitizer that already ran on everything else
+ * in the document, while a legitimate `data:`/`app:`/host-scheme result
+ * still reaches the page. A resolver that throws is treated exactly like
+ * one that returned `undefined`: `value` is kept, and the render is never
+ * broken over one image.
+ */
+export function resolveImageAttribute(value, resolveImageSrc) {
+    if (!resolveImageSrc)
+        return value;
+    if (!isResolvableRelativeValue(value))
+        return value;
+    let resolved;
+    try {
+        resolved = resolveImageSrc(value);
+    }
+    catch {
+        return value;
+    }
+    if (resolved === undefined)
+        return value;
+    return isSafeResolvedUrl(resolved) ? resolved : value;
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export { renderMarkToHtml, renderMarkNodeToHtml } from './render.js';
+export { renderMarkToHtml, renderMarkNodeToHtml, renderMarkInlineToHtml, type RenderMarkOptions, } from './render.js';
+export { type ResolveImageSrc } from './image-resolve.js';
+export { type ResolveHref } from './href-resolve.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';

package/dist/index.js

@@ -3,7 +3,7 @@
 // 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 { renderMarkToHtml, renderMarkNodeToHtml, renderMarkInlineToHtml, } from './render.js';
 export { escapeHtml } from './escape.js';
 export { exportHtmlDocument, } from './document.js';
 export { resolveStorePath, resolveScopedPath, VAULT_NAME_PREFIX, } from './resolve.js';

package/dist/registry.d.ts

@@ -7,7 +7,8 @@
  * the React renderer's, so a note resolves the same way in both.
  */
 import type { FailureKind, ValueStatus } from '@markii/runtime';
-import type { LayoutAxis } from '@markii/stdlib';
+import type { LayoutAxis, OnDiagnostic } from '@markii/stdlib';
+import type { ResolveImageSrc } from './image-resolve.js';
 /**
  * Attributes parsed off a directive, e.g. `{type=warning title="Careful"}`. A
  * bare attribute (present but valueless, e.g. `{collapsed}`) arrives as
@@ -81,6 +82,26 @@ export interface HtmlRenderContext {
      * arguments and has no room for a fourth.
      */
     layoutClassName?: string;
+    /**
+     * `renderMarkToHtml`'s `resolveImageSrc` option (`render.ts`'s
+     * `RenderMarkOptions`), carried on `ctx` so a component that builds its
+     * own `<img>` from an attribute — the standard `Figure` is the only one
+     * today — can resolve it the same way an ordinary markdown image does.
+     * `undefined` when the render call supplied none, in which case a
+     * component must leave its `src` exactly as authored.
+     */
+    resolveImageSrc?: ResolveImageSrc;
+    /**
+     * `renderMarkToHtml`'s `onDiagnostic` option (`render.ts`'s
+     * `RenderMarkOptions`), carried on `ctx` so a component that decides for
+     * itself whether to render a quiet marker — the standard `Figure` is the
+     * only one today, for a `src` refused as unsafe — can report the same
+     * event a host would otherwise only see as an in-page `title` tooltip.
+     * `undefined` when the render call supplied none. Never call this
+     * directly without going through `@markii/stdlib`'s `reportDiagnostic`,
+     * which guards against a throwing callback.
+     */
+    onDiagnostic?: OnDiagnostic;
 }
 /**
  * One registry component: receives the directive's raw string attributes

package/dist/render.d.ts

@@ -1,6 +1,17 @@
+import { parse } from '@markii/core';
 import type { MarkNode } from '@markii/core';
 import type { ValueStore, VaultStore } from '@markii/runtime';
 import type { HtmlRegistry } from './registry.js';
+import type { OnDiagnostic } from '@markii/stdlib';
+import type { ResolveImageSrc } from './image-resolve.js';
+import type { ResolveHref } from './href-resolve.js';
+/**
+ * A whole parsed document, as `@markii/core`'s `parse` returns it — the
+ * type `renderMarkNodeToHtml` accepts alongside a single `MarkNode` (#44a).
+ * Named locally rather than importing `mdast`'s `Root` directly, mirroring
+ * `@markii/react`'s identical `MarkRoot` type alias.
+ */
+type MarkRoot = ReturnType<typeof parse>;
 /**
  * Renders Markii text to a static HTML string using `registry` to resolve
  * directive names. Pipeline: `@markii/core`'s `toHast` (parse -> tag directive
@@ -22,13 +33,73 @@ import type { HtmlRegistry } from './registry.js';
  * mine, `@name` = the vault's". With no `vault` supplied, every `@name`
  * degrades to `'missing'` the same way an absent `store` degrades a bare
  * name.
+ *
+ * `options.resolveImageSrc` resolves a relative `<img src>` — an ordinary
+ * markdown image or one `Figure` built from an attribute — to a URL a host
+ * can actually load. It is never asked about a source that already carries
+ * a scheme, a protocol-relative `//host/...`, a bare `#fragment`, or an
+ * empty value, and its result is re-checked against a narrow
+ * `javascript:`/`vbscript:` denylist before use (`./url-resolve.js`), so it
+ * cannot introduce a scheme the parser's own sanitizer would otherwise have
+ * dropped. Returning `undefined`, or throwing, leaves the source exactly as
+ * the author wrote it. Omitted entirely, every image renders with the
+ * source unchanged, matching every render before this option existed.
+ *
+ * `options.resolveHref` (#44b) is the identical seam for an ordinary
+ * markdown link's `<a href>`: same resolvability rule, same shared
+ * dangerous-scheme refusal, same fall-through-on-`undefined`-or-throw
+ * behavior. No standard component builds its own `<a>`, so this only ever
+ * touches a link the parser itself produced.
+ *
+ * `options.onDiagnostic`, when supplied, is called once for every quiet
+ * in-page marker this render produces for a value it recognized and
+ * declined to use outright — a known attribute's value outside its closed
+ * enum, or a `figure` `src` refused as unsafe — with
+ * `{ kind, directive, attribute, message }` (`@markii/stdlib`'s
+ * `DiagnosticEvent`), so a host can put the same information on its own
+ * diagnostics surface. Never called for an unknown-attribute NAME or for
+ * the unknown-directive/form-mismatch fallbacks, which already show
+ * themselves in the page. A callback that throws can never break the
+ * render: every call site goes through `@markii/stdlib`'s
+ * `reportDiagnostic`. Both options mirror `@markii/react`'s identical
+ * `RenderMarkOptions`, so the two engines cannot diverge.
+ */
+export interface RenderMarkOptions {
+    readonly resolveImageSrc?: ResolveImageSrc;
+    readonly resolveHref?: ResolveHref;
+    readonly onDiagnostic?: OnDiagnostic;
+    /**
+     * The note's own last-run values, the same thing the third positional
+     * parameter takes. Offered here as well so a caller that already builds
+     * an options object does not have to fill positional slots it has no
+     * other use for. When both forms are given the option wins.
+     */
+    readonly store?: ValueStore;
+    /** Values other notes published, read by an `@`-prefixed name. Same positional twin and same precedence as `store`. */
+    readonly vault?: VaultStore;
+}
+export declare function renderMarkToHtml(text: string, registry: HtmlRegistry, store?: ValueStore, vault?: VaultStore, options?: RenderMarkOptions): string;
+/**
+ * The block-level twin of `renderMarkToHtml`: renders one already-parsed
+ * mdast node OR a whole already-parsed mdast document (`@markii/core`'s
+ * `MarkNode`, or the `Root` `parse` itself returns; #44a) to HTML instead of
+ * raw document text, via `nodeOrRootToHast`. Same registry resolution, same
+ * fallbacks, same purity and never-throw guarantees, and the same optional
+ * `store`/`vault` value-binding arguments and `resolveImageSrc`/
+ * `resolveHref`/`onDiagnostic` options.
+ *
+ * A `MarkNode` and a `Root` share ONE parameter, mirroring
+ * `@markii/react`'s `renderMarkNode` (see that function's doc comment for
+ * why: the smaller surface for callers, no second near-identical export).
  */
-export declare function renderMarkToHtml(text: string, registry: HtmlRegistry, store?: ValueStore, vault?: VaultStore): string;
+export declare function renderMarkNodeToHtml(node: MarkNode | MarkRoot, registry: HtmlRegistry, store?: ValueStore, vault?: VaultStore, options?: RenderMarkOptions): string;
 /**
- * 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.
+ * Renders `text` as a single, standalone inline directive when that is all
+ * it is (#44c), mirroring `@markii/react`'s identical `renderMarkInline`:
+ * source whose only parsed block is a paragraph holding exactly one text
+ * directive renders that directive alone, WITHOUT the paragraph wrapper
+ * `renderMarkToHtml` would otherwise put around it. Any other source falls
+ * back to the exact same rendering `renderMarkToHtml` would produce.
  */
-export declare function renderMarkNodeToHtml(node: MarkNode, registry: HtmlRegistry, store?: ValueStore, vault?: VaultStore): string;
+export declare function renderMarkInlineToHtml(text: string, registry: HtmlRegistry, store?: ValueStore, vault?: VaultStore, options?: RenderMarkOptions): string;
+export {};

package/dist/render.js

@@ -1,11 +1,31 @@
-import { toHast, nodeToHast, parseMetaAttributes, isValidScriptName, isBareAttribute, } from '@markii/core';
+import { parse, toHast, nodeToHast, parseMetaAttributes, isValidScriptName, isBareAttribute, } from '@markii/core';
 import { toHtml } from 'hast-util-to-html';
 import { readRegistryComponent, registryLayoutAxis, resolveDirectiveAlias, } from './registry.js';
 import { resolveLayoutAttributes } from './layout.js';
 import { escapeHtml } from './escape.js';
 import { resolveScopedPath } from './resolve.js';
-import { failureKindClass, failureTitle, EMPTY_INLINE_MARKER_CLASS, emptyInlineTitle, } from './failure-presentation.js';
-import { formatValue } from '@markii/stdlib';
+import { failureKindClass, failureTitle, EMPTY_INLINE_MARKER_CLASS, emptyInlineTitle, invalidAttributeValueTitle, } from './failure-presentation.js';
+import { formatValue, getContract, reportDiagnostic, INTERACTIVE_ATTRIBUTE, } from '@markii/stdlib';
+import { resolveImageAttribute } from './image-resolve.js';
+import { resolveHrefAttribute } from './href-resolve.js';
+function isMarkRoot(node) {
+    return node.type === 'root';
+}
+/**
+ * Converts a `MarkNode | MarkRoot` (#44a) to a sanitized hast tree via
+ * `@markii/core`'s `nodeToHast`, mirroring `@markii/react`'s identical
+ * `nodeOrRootToHast`: for a whole `MarkRoot`, each child is run through
+ * `nodeToHast` independently and the resulting hast children concatenated.
+ */
+function nodeOrRootToHast(node) {
+    if (!isMarkRoot(node))
+        return nodeToHast(node);
+    const children = [];
+    for (const child of node.children) {
+        children.push(...nodeToHast(child).children);
+    }
+    return { type: 'root', children };
+}
 /** 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. */
@@ -64,7 +84,7 @@ function buildValueMarker(name, resolved, format, decimals) {
  * The `data*` fields are attached per-directive later (see
  * `withDataBinding`) — this base object never carries them.
  */
-function createBaseContext(scope) {
+function createBaseContext(scope, resolveImageSrc, onDiagnostic) {
     return {
         esc: escapeHtml,
         resolve(name) {
@@ -80,6 +100,8 @@ function createBaseContext(scope) {
                 : { value: undefined, status: 'missing' };
             return buildValueMarker(trimmed, resolved, format, decimals);
         },
+        resolveImageSrc,
+        onDiagnostic,
     };
 }
 /**
@@ -313,13 +335,35 @@ function renderScriptMarker(node) {
             ? `<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>` +
+            `<summary class="mk-script__summary" ${INTERACTIVE_ATTRIBUTE}="">${escapeHtml(summary)}</summary>` +
             `${body}</details>`);
     }
     catch {
         return undefined;
     }
 }
+/**
+ * Whether one of `name`'s `@markii/stdlib` contract attributes with a
+ * closed `enum` is present in `attributes` with a value outside that enum.
+ * Returns the first offending attribute/value pair found, or `undefined`.
+ * Mirrors `@markii/react`'s identical `invalidEnumAttribute`.
+ */
+function invalidEnumAttribute(name, attributes) {
+    const contract = getContract(name);
+    if (!contract)
+        return undefined;
+    for (const [attribute, schema] of Object.entries(contract.attributes)) {
+        const enumValues = schema.enum;
+        if (!enumValues)
+            continue;
+        const value = attributes[attribute];
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (!enumValues.includes(value))
+            return { attribute, value };
+    }
+    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, layoutClassName) {
     if (name === VALUE_DIRECTIVE_NAME) {
@@ -342,6 +386,25 @@ function renderDirectiveContent(name, kind, attributes, childrenHtml, plainLabel
     catch {
         return componentError(name || '(unnamed)', inline, childrenHtml);
     }
+    // The silent-value-drop mechanism (AGENTS.md "clean is not silent"),
+    // mirroring `@markii/react`'s identical check: a known attribute's value
+    // outside its closed enum still renders the component exactly as
+    // registered, wrapped in a quiet marker whose `title` carries the reason,
+    // and `onDiagnostic` gets the same event for a host's own diagnostics
+    // surface. Checked against the FINAL attributes the component actually
+    // received (`binding.attributes`), not the raw ones.
+    const invalidEnum = invalidEnumAttribute(name, binding.attributes);
+    if (invalidEnum) {
+        const message = invalidAttributeValueTitle(name, invalidEnum.attribute, invalidEnum.value);
+        reportDiagnostic(ctx.onDiagnostic, {
+            kind: 'invalid-attribute-value',
+            directive: name,
+            attribute: invalidEnum.attribute,
+            message,
+        });
+        const tag = inline ? 'span' : 'div';
+        rendered = `<${tag} data-mk-notice="" title="${escapeHtml(message)}">${rendered}</${tag}>`;
+    }
     // ITEM 1 (AGENTS.md "clean is not silent"): mirrors `@markii/react`'s
     // identical check in `renderDirectiveContent` — an `inline: true`
     // component with no content still renders exactly as registered, wrapped
@@ -386,7 +449,33 @@ function renderDirective(element, registry, ctx, scope) {
  * children so a nested directive is already resolved by the time its parent
  * serializes it.
  */
-function makeTransform(registry, ctx, scope) {
+/**
+ * Rewrites an ordinary hast `<img>` element's `src` in place through
+ * `resolveImageSrc` — the plain-markdown-image half of the seam
+ * `Figure` implements for its own attribute-built `<img>` (see
+ * `./components/figure.ts`). With no resolver at all (the common case)
+ * this is a no-op, so a fixture rendered without one produces byte-
+ * identical output to before this option existed.
+ */
+function applyImageResolver(node, resolveImageSrc) {
+    const src = node.properties.src;
+    if (typeof src === 'string') {
+        node.properties.src = resolveImageAttribute(src, resolveImageSrc);
+    }
+}
+/**
+ * Rewrites an ordinary hast `<a>` element's `href` in place through
+ * `resolveHref` (#44b) — the link-rewrite twin of `applyImageResolver`. No
+ * standard component builds its own `<a>`, so this is the only place a link
+ * href is ever resolved. With no resolver at all this is a no-op.
+ */
+function applyHrefResolver(node, resolveHref) {
+    const href = node.properties.href;
+    if (typeof href === 'string') {
+        node.properties.href = resolveHrefAttribute(href, resolveHref);
+    }
+}
+function makeTransform(registry, ctx, scope, resolveHref) {
     function transform(node) {
         if (node.type !== 'element')
             return node;
@@ -398,6 +487,12 @@ function makeTransform(registry, ctx, scope) {
             if (marker !== undefined)
                 return raw(marker);
         }
+        if (node.tagName === 'img') {
+            applyImageResolver(node, ctx.resolveImageSrc);
+        }
+        if (node.tagName === 'a') {
+            applyHrefResolver(node, resolveHref);
+        }
         return node;
     }
     return transform;
@@ -409,54 +504,86 @@ function renderFailureFallback(error) {
         `<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);
+function renderRoot(root, registry, scope, resolveImageSrc, resolveHref, onDiagnostic) {
+    const ctx = createBaseContext(scope, resolveImageSrc, onDiagnostic);
+    const transform = makeTransform(registry, ctx, scope, resolveHref);
     root.children = root.children.map(transform);
     return serialize(root.children);
 }
+export function renderMarkToHtml(text, registry, store, vault, options) {
+    try {
+        return renderRoot(toHast(text), registry, { store: options?.store ?? store, vault: options?.vault ?? vault }, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic);
+    }
+    catch (error) {
+        return renderFailureFallback(error);
+    }
+}
 /**
- * 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.
+ * The block-level twin of `renderMarkToHtml`: renders one already-parsed
+ * mdast node OR a whole already-parsed mdast document (`@markii/core`'s
+ * `MarkNode`, or the `Root` `parse` itself returns; #44a) to HTML instead of
+ * raw document text, via `nodeOrRootToHast`. Same registry resolution, same
+ * fallbacks, same purity and never-throw guarantees, and the same optional
+ * `store`/`vault` value-binding arguments and `resolveImageSrc`/
+ * `resolveHref`/`onDiagnostic` options.
  *
- * `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.
+ * A `MarkNode` and a `Root` share ONE parameter, mirroring
+ * `@markii/react`'s `renderMarkNode` (see that function's doc comment for
+ * why: the smaller surface for callers, no second near-identical export).
  */
-export function renderMarkToHtml(text, registry, store, vault) {
+export function renderMarkNodeToHtml(node, registry, store, vault, options) {
     try {
-        return renderRoot(toHast(text), registry, { store, vault });
+        return renderRoot(nodeOrRootToHast(node), registry, { store: options?.store ?? store, vault: options?.vault ?? vault }, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic);
     }
     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.
+ * Whether `root` is exactly one paragraph holding exactly one text
+ * directive (`:name[...]`) and nothing else, mirroring `@markii/react`'s
+ * identical `loneInlineDirective`. Returns that inner directive node when
+ * so, `undefined` otherwise.
  */
-export function renderMarkNodeToHtml(node, registry, store, vault) {
+function loneInlineDirective(root) {
+    if (root.children.length !== 1)
+        return undefined;
+    const [only] = root.children;
+    if (!only || only.type !== 'paragraph')
+        return undefined;
+    if (only.children.length !== 1)
+        return undefined;
+    const [inner] = only.children;
+    // Compared against a widened `{ type?: unknown }` view, not
+    // `PhrasingContent` directly: `'textDirective'` only joins that union when
+    // something in the compilation imports `mdast-util-directive`'s ambient
+    // augmentation, which this file has no other reason to do. Matches
+    // `isMarkRoot`'s identical widen-then-compare shape just above, and
+    // `@markii/react`'s identical fix in its own copy of this function.
+    return inner && inner.type === 'textDirective'
+        ? inner
+        : undefined;
+}
+/**
+ * Renders `text` as a single, standalone inline directive when that is all
+ * it is (#44c), mirroring `@markii/react`'s identical `renderMarkInline`:
+ * source whose only parsed block is a paragraph holding exactly one text
+ * directive renders that directive alone, WITHOUT the paragraph wrapper
+ * `renderMarkToHtml` would otherwise put around it. Any other source falls
+ * back to the exact same rendering `renderMarkToHtml` would produce.
+ */
+export function renderMarkInlineToHtml(text, registry, store, vault, options) {
     try {
-        return renderRoot(nodeToHast(node), registry, { store, vault });
+        const root = parse(text);
+        const lone = loneInlineDirective(root);
+        if (lone) {
+            return renderMarkNodeToHtml(lone, registry, store, vault, options);
+        }
     }
-    catch (error) {
-        return renderFailureFallback(error);
+    catch {
+        // Falls through to the ordinary whole-document render below, whose own
+        // try/catch produces the shared failure fallback if parsing (again) or
+        // rendering fails.
     }
+    return renderMarkToHtml(text, registry, store, vault, options);
 }

package/dist/url-resolve.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The scheme-safety logic shared by every host-resolver seam on this
+ * engine's `RenderMarkOptions`: `resolveImageSrc` (`./image-resolve.js`)
+ * and `resolveHref` (`./href-resolve.js`). Both seams follow the identical
+ * shape: offer a host resolver a value that looks like ITS OWN relative
+ * path, then refuse a `javascript:`/`vbscript:` scheme in whatever the
+ * resolver hands back. That logic lives here ONCE and each seam's module
+ * only adds the one-line wrapper that names its own option
+ * (`resolveImageSrc` vs `resolveHref`). See `./image-resolve.js`'s top
+ * comment for the full rationale: why the result is checked against a
+ * narrow denylist here, not `@markii/core`'s author-facing `isSafeUrl`
+ * allowlist. Mirrors `@markii/react`'s `url-resolve.ts` so the two engines
+ * cannot diverge on what counts as a dangerous scheme.
+ */
+/**
+ * The scheme text before the first `:` when one is present in scheme
+ * position, lowercased; `undefined` for a schemeless value. Delimiter rule
+ * matches `@markii/core`'s `isSafeUrl`.
+ */
+export declare function schemeOf(value: string): string | undefined;
+/**
+ * True for a value worth offering to a resolver at all: no scheme, no
+ * protocol-relative `//host/...` form, no bare `#fragment`, not
+ * empty/whitespace.
+ */
+export declare function isResolvableRelativeValue(value: string): boolean;
+/**
+ * Schemes that turn a resolved URL into a script-execution vector.
+ * Everything else a resolver returns (`https:`, `data:`, `app:`, a host's
+ * own custom scheme) is a legitimate resolved location, not a smuggled
+ * script.
+ */
+export declare const DANGEROUS_URL_SCHEMES: Set<string>;
+/**
+ * `value` reduced to what a browser will actually parse a scheme out of:
+ * ASCII tab, line feed and carriage return removed wherever they appear,
+ * then leading C0 controls and spaces stripped. The URL parser ignores
+ * exactly these, so a tab or newline spliced into the middle of a scheme
+ * name, or leading whitespace/control characters before it, both still
+ * reach the page as that scheme. A scheme test that reads the raw text
+ * instead would call both of them schemeless and wave them through, which
+ * is the difference between a denylist that holds and one that only looks
+ * like it does.
+ */
+export declare function forSchemeTest(value: string): string;
+/**
+ * True unless `value` carries one of `DANGEROUS_URL_SCHEMES`, judged
+ * against `forSchemeTest`'s browser-equivalent reading rather than the raw
+ * string. Because this IS a denylist, an unrecognized scheme is allowed, so
+ * the parsing it rests on has to match the browser's exactly: an allowlist
+ * fails closed on a spelling it does not recognize, and this cannot.
+ */
+export declare function isSafeResolvedUrl(value: string): boolean;

package/dist/url-resolve.js

@@ -0,0 +1,81 @@
+/**
+ * The scheme-safety logic shared by every host-resolver seam on this
+ * engine's `RenderMarkOptions`: `resolveImageSrc` (`./image-resolve.js`)
+ * and `resolveHref` (`./href-resolve.js`). Both seams follow the identical
+ * shape: offer a host resolver a value that looks like ITS OWN relative
+ * path, then refuse a `javascript:`/`vbscript:` scheme in whatever the
+ * resolver hands back. That logic lives here ONCE and each seam's module
+ * only adds the one-line wrapper that names its own option
+ * (`resolveImageSrc` vs `resolveHref`). See `./image-resolve.js`'s top
+ * comment for the full rationale: why the result is checked against a
+ * narrow denylist here, not `@markii/core`'s author-facing `isSafeUrl`
+ * allowlist. Mirrors `@markii/react`'s `url-resolve.ts` so the two engines
+ * cannot diverge on what counts as a dangerous scheme.
+ */
+/**
+ * The scheme text before the first `:` when one is present in scheme
+ * position, lowercased; `undefined` for a schemeless value. Delimiter rule
+ * matches `@markii/core`'s `isSafeUrl`.
+ */
+export function schemeOf(value) {
+    const colon = value.indexOf(':');
+    if (colon === -1)
+        return undefined;
+    const slash = value.indexOf('/');
+    const questionMark = value.indexOf('?');
+    const numberSign = value.indexOf('#');
+    const hasSchemeBeforeDelimiter = (slash === -1 || colon < slash) &&
+        (questionMark === -1 || colon < questionMark) &&
+        (numberSign === -1 || colon < numberSign);
+    return hasSchemeBeforeDelimiter
+        ? value.slice(0, colon).toLowerCase()
+        : undefined;
+}
+/**
+ * True for a value worth offering to a resolver at all: no scheme, no
+ * protocol-relative `//host/...` form, no bare `#fragment`, not
+ * empty/whitespace.
+ */
+export function isResolvableRelativeValue(value) {
+    if (value.trim() === '')
+        return false;
+    if (value.startsWith('#'))
+        return false;
+    if (value.startsWith('//'))
+        return false;
+    return schemeOf(value) === undefined;
+}
+/**
+ * Schemes that turn a resolved URL into a script-execution vector.
+ * Everything else a resolver returns (`https:`, `data:`, `app:`, a host's
+ * own custom scheme) is a legitimate resolved location, not a smuggled
+ * script.
+ */
+export const DANGEROUS_URL_SCHEMES = new Set(['javascript', 'vbscript']);
+const TAB_NEWLINE_CR = new RegExp('[\\u0009\\u000a\\u000d]', 'g');
+const LEADING_C0_OR_SPACE = new RegExp('^[\\u0000-\\u0020]+');
+/**
+ * `value` reduced to what a browser will actually parse a scheme out of:
+ * ASCII tab, line feed and carriage return removed wherever they appear,
+ * then leading C0 controls and spaces stripped. The URL parser ignores
+ * exactly these, so a tab or newline spliced into the middle of a scheme
+ * name, or leading whitespace/control characters before it, both still
+ * reach the page as that scheme. A scheme test that reads the raw text
+ * instead would call both of them schemeless and wave them through, which
+ * is the difference between a denylist that holds and one that only looks
+ * like it does.
+ */
+export function forSchemeTest(value) {
+    return value.replace(TAB_NEWLINE_CR, '').replace(LEADING_C0_OR_SPACE, '');
+}
+/**
+ * True unless `value` carries one of `DANGEROUS_URL_SCHEMES`, judged
+ * against `forSchemeTest`'s browser-equivalent reading rather than the raw
+ * string. Because this IS a denylist, an unrecognized scheme is allowed, so
+ * the parsing it rests on has to match the browser's exactly: an allowlist
+ * fails closed on a spelling it does not recognize, and this cannot.
+ */
+export function isSafeResolvedUrl(value) {
+    const scheme = schemeOf(forSchemeTest(value));
+    return scheme === undefined || !DANGEROUS_URL_SCHEMES.has(scheme);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/html",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "A framework-free static HTML renderer for Markii (.mk.md): a registry-driven hast-to-HTML string engine. Zero React; for stopped-changing documents (publish, CI, email, archive).",
   "keywords": [
     "markdown",
@@ -54,9 +54,9 @@
   },
   "dependencies": {
     "hast-util-to-html": "^9.0.0",
-    "@markii/core": "^0.12.1",
-    "@markii/runtime": "^0.12.1",
-    "@markii/stdlib": "^0.12.1"
+    "@markii/core": "^0.14.0",
+    "@markii/runtime": "^0.14.0",
+    "@markii/stdlib": "^0.14.0"
   },
   "devDependencies": {
     "@types/hast": "^3.0.4"