@markii/html 0.12.1 → 0.13.0

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,4 +1,5 @@
 import { isSafeUrl } from '@markii/core';
+import { resolveImageAttribute } from '../image-resolve.js';
 const DEFAULT_ALT = '';
 /**
  * `:::figure{src="..." alt="..."} caption markdown :::` — an image with a
@@ -15,11 +16,20 @@ 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 safeSrc = rawSrc && isSafeUrl(rawSrc) ? 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)}">`
         : '';

package/dist/image-resolve.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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. Everything else
+ * already resolves on its own (or is not a path at all) and is left
+ * exactly as written — the identical rule `@markii/react`'s
+ * `image-resolve.ts` applies, so the two engines cannot diverge on what
+ * counts as "relative".
+ *
+ * The scheme test mirrors `@markii/core`'s `isSafeUrl`: text before the
+ * first `:`, but only when that `:` precedes any `/`, `?`, or `#` — so a
+ * path that merely contains a colon later on (`notes/a:b.png`) still reads
+ * as relative.
+ *
+ * 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. `isSafeResolvedImageSrc` below 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
+ * `isSafeResolvedImageSrc` — 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,120 @@
+/**
+ * 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. Everything else
+ * already resolves on its own (or is not a path at all) and is left
+ * exactly as written — the identical rule `@markii/react`'s
+ * `image-resolve.ts` applies, so the two engines cannot diverge on what
+ * counts as "relative".
+ *
+ * The scheme test mirrors `@markii/core`'s `isSafeUrl`: text before the
+ * first `:`, but only when that `:` precedes any `/`, `?`, or `#` — so a
+ * path that merely contains a colon later on (`notes/a:b.png`) still reads
+ * as relative.
+ *
+ * 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. `isSafeResolvedImageSrc` below 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 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`. */
+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 source worth offering to a resolver at all. */
+function isResolvableImageSrc(value) {
+    if (value.trim() === '')
+        return false;
+    if (value.startsWith('#'))
+        return false;
+    if (value.startsWith('//'))
+        return false;
+    return schemeOf(value) === undefined;
+}
+/** Schemes that turn an `<img src>` 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. */
+const DANGEROUS_IMAGE_SCHEMES = new Set(['javascript', 'vbscript']);
+/**
+ * `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 `"java<TAB>script:alert(1)"` and `" javascript:alert(1)"`
+ * both reach the page as the `javascript:` 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.
+ */
+function forSchemeTest(value) {
+    return value
+        .replace(/[\u0009\u000a\u000d]/g, '')
+        .replace(/^[\u0000-\u0020]+/, '');
+}
+/**
+ * True unless `value` carries one of `DANGEROUS_IMAGE_SCHEMES`, judged
+ * against `forSchemeTest`'s browser-equivalent reading rather than the raw
+ * string. See this module's top comment for why this is a narrow denylist
+ * and not `@markii/core`'s author-facing `isSafeUrl` allowlist. Because it
+ * 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.
+ */
+function isSafeResolvedImageSrc(value) {
+    const scheme = schemeOf(forSchemeTest(value));
+    return scheme === undefined || !DANGEROUS_IMAGE_SCHEMES.has(scheme);
+}
+/**
+ * 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
+ * `isSafeResolvedImageSrc` — 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 (!isResolvableImageSrc(value))
+        return value;
+    let resolved;
+    try {
+        resolved = resolveImageSrc(value);
+    }
+    catch {
+        return value;
+    }
+    if (resolved === undefined)
+        return value;
+    return isSafeResolvedImageSrc(resolved) ? resolved : value;
+}

package/dist/index.d.ts

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

@@ -8,6 +8,7 @@
  */
 import type { FailureKind, ValueStatus } from '@markii/runtime';
 import type { LayoutAxis } 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,15 @@ 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;
 }
 /**
  * One registry component: receives the directive's raw string attributes

package/dist/render.d.ts

@@ -1,6 +1,7 @@
 import type { MarkNode } from '@markii/core';
 import type { ValueStore, VaultStore } from '@markii/runtime';
 import type { HtmlRegistry } from './registry.js';
+import type { ResolveImageSrc } from './image-resolve.js';
 /**
  * Renders Markii text to a static HTML string using `registry` to resolve
  * directive names. Pipeline: `@markii/core`'s `toHast` (parse -> tag directive
@@ -22,13 +23,29 @@ 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 `@markii/core`'s
+ * `isSafeUrl` before use, so it cannot introduce a `javascript:` URL the
+ * 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. The identical option on
+ * `@markii/react`'s `renderMark` uses the same rules, so the two engines
+ * cannot diverge on what a resolver is offered or how its result is used.
  */
-export declare function renderMarkToHtml(text: string, registry: HtmlRegistry, store?: ValueStore, vault?: VaultStore): string;
+export interface RenderMarkOptions {
+    readonly resolveImageSrc?: ResolveImageSrc;
+}
+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 (`@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.
+ * value-binding arguments and `resolveImageSrc` option.
  */
-export declare function renderMarkNodeToHtml(node: MarkNode, registry: HtmlRegistry, store?: ValueStore, vault?: VaultStore): string;
+export declare function renderMarkNodeToHtml(node: MarkNode, registry: HtmlRegistry, store?: ValueStore, vault?: VaultStore, options?: RenderMarkOptions): string;

package/dist/render.js

@@ -6,6 +6,7 @@ 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 { resolveImageAttribute } from './image-resolve.js';
 /** The hast tag name `@markii/core`'s `toHast` marks every directive with (`to-hast.ts`'s `DIRECTIVE_TAG`). */
 const DIRECTIVE_TAG = 'mk-directive';
 /** `data-mk-kind` value for a TEXT (inline) directive; the other two kinds (`leafDirective`/`containerDirective`) are block. */
@@ -64,7 +65,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) {
     return {
         esc: escapeHtml,
         resolve(name) {
@@ -80,6 +81,7 @@ function createBaseContext(scope) {
                 : { value: undefined, status: 'missing' };
             return buildValueMarker(trimmed, resolved, format, decimals);
         },
+        resolveImageSrc,
     };
 }
 /**
@@ -386,6 +388,20 @@ function renderDirective(element, registry, ctx, scope) {
  * children so a nested directive is already resolved by the time its parent
  * serializes it.
  */
+/**
+ * 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);
+    }
+}
 function makeTransform(registry, ctx, scope) {
     function transform(node) {
         if (node.type !== 'element')
@@ -398,6 +414,9 @@ function makeTransform(registry, ctx, scope) {
             if (marker !== undefined)
                 return raw(marker);
         }
+        if (node.tagName === 'img') {
+            applyImageResolver(node, ctx.resolveImageSrc);
+        }
         return node;
     }
     return transform;
@@ -409,37 +428,15 @@ 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);
+function renderRoot(root, registry, scope, resolveImageSrc) {
+    const ctx = createBaseContext(scope, resolveImageSrc);
     const transform = makeTransform(registry, ctx, scope);
     root.children = root.children.map(transform);
     return serialize(root.children);
 }
-/**
- * Renders Markii text to a static HTML string using `registry` to resolve
- * directive names. Pipeline: `@markii/core`'s `toHast` (parse -> tag directive
- * nodes -> remark-rehype -> sanitize URLs) -> a hast->HTML walk that swaps
- * directive elements for registry components (or the unknown-directive
- * fallback) and folds script fences into markers. Pure and never-throwing:
- * parsing is tolerant, unknown names always render a fallback, and any
- * unexpected internal error degrades to the "failed to render document" box.
- *
- * `store` is the note's value store (`@markii/runtime`, §8's pure read path)
- * — optional, matching how a missing/absent value degrades gracefully: with
- * no store, `:value[name]` renders its missing-value marker and every
- * `data=name` attribute resolves to `dataStatus: 'missing'`, but the
- * document still renders completely.
- *
- * `vault` is the optional app-scoped read seam (`@markii/runtime`'s
- * `VaultStore`) that an `@`-prefixed name (`data=@gh.stars`,
- * `:value[@gh.stars]`) resolves against instead of `store` — "bare name =
- * mine, `@name` = the vault's". With no `vault` supplied, every `@name`
- * degrades to `'missing'` the same way an absent `store` degrades a bare
- * name.
- */
-export function renderMarkToHtml(text, registry, store, vault) {
+export function renderMarkToHtml(text, registry, store, vault, options) {
     try {
-        return renderRoot(toHast(text), registry, { store, vault });
+        return renderRoot(toHast(text), registry, { store, vault }, options?.resolveImageSrc);
     }
     catch (error) {
         return renderFailureFallback(error);
@@ -450,11 +447,11 @@ export function renderMarkToHtml(text, registry, store, vault) {
  * 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.
+ * value-binding arguments and `resolveImageSrc` option.
  */
-export function renderMarkNodeToHtml(node, registry, store, vault) {
+export function renderMarkNodeToHtml(node, registry, store, vault, options) {
     try {
-        return renderRoot(nodeToHast(node), registry, { store, vault });
+        return renderRoot(nodeToHast(node), registry, { store, vault }, options?.resolveImageSrc);
     }
     catch (error) {
         return renderFailureFallback(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/html",
-  "version": "0.12.1",
+  "version": "0.13.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.13.0",
+    "@markii/runtime": "^0.13.0",
+    "@markii/stdlib": "^0.13.0"
   },
   "devDependencies": {
     "@types/hast": "^3.0.4"