@markii/html 0.16.0 → 0.17.0-next.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sadigaxund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/failure-presentation.d.ts

@@ -34,3 +34,26 @@ export declare const NOTICE_ATTRIBUTE = "data-mk-notice";
 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;
+/** The diagnostic text for a host `renderCode` callback that threw; the code block rendered as usual. Identical across the engines. */
+export declare function codeRendererFailedTitle(): string;
+/** The diagnostic text for a registered block component written as an inline directive, which renders as the inline fallback instead. */
+export declare function formMismatchTitle(directive: string): string;
+/**
+ * The words of a fallback label for a directive that names a component of
+ * an installed pack with no view in this engine. Followed by the directive
+ * name in a `<code>` element. A static HTML file is what this engine makes,
+ * so that is what the label calls the missing view.
+ */
+export declare const NO_ENGINE_VIEW_LABEL = "no HTML view for";
+/**
+ * The diagnostic text for the same case (also the fallback box's tooltip):
+ * the pack, and the engines the component does ship a view for.
+ */
+export declare function noEngineViewTitle(directive: string, pack: string, engines: readonly string[]): string;
+/**
+ * The visible separator between an inline fallback's label and its content,
+ * emitted as real text (`mk-unknown__separator`) so a copy or a plain-text
+ * export reads the same as `@markii/ansi`'s output. An inline fallback with
+ * no content shows the bare label and no separator.
+ */
+export declare const INLINE_FALLBACK_SEPARATOR = ": ";

package/dist/failure-presentation.js

@@ -82,3 +82,35 @@ export function invalidAttributeValueTitle(directive, attribute, value) {
 export function unsafeImageSrcTitle(directive) {
     return `${directive}: image source was refused as unsafe and was not shown`;
 }
+/** The diagnostic text for a host `renderCode` callback that threw; the code block rendered as usual. Identical across the engines. */
+export function codeRendererFailedTitle() {
+    return 'code block: the host code renderer failed, so the plain block was shown';
+}
+/** The diagnostic text for a registered block component written as an inline directive, which renders as the inline fallback instead. */
+export function formMismatchTitle(directive) {
+    return `${directive}: block component was written inline and was not rendered`;
+}
+/**
+ * The words of a fallback label for a directive that names a component of
+ * an installed pack with no view in this engine. Followed by the directive
+ * name in a `<code>` element. A static HTML file is what this engine makes,
+ * so that is what the label calls the missing view.
+ */
+export const NO_ENGINE_VIEW_LABEL = 'no HTML view for';
+/**
+ * The diagnostic text for the same case (also the fallback box's tooltip):
+ * the pack, and the engines the component does ship a view for.
+ */
+export function noEngineViewTitle(directive, pack, engines) {
+    const has = engines.length > 0
+        ? `it has views for: ${engines.join(', ')}`
+        : 'it has no views for any engine';
+    return `The ${pack} pack has no HTML view for this component; ${has}`;
+}
+/**
+ * The visible separator between an inline fallback's label and its content,
+ * emitted as real text (`mk-unknown__separator`) so a copy or a plain-text
+ * export reads the same as `@markii/ansi`'s output. An inline fallback with
+ * no content shows the bare label and no separator.
+ */
+export const INLINE_FALLBACK_SEPARATOR = ': ';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { renderMarkToHtml, renderMarkNodeToHtml, renderMarkInlineToHtml, type RenderMarkOptions, } from './render.js';
+export { renderMarkToHtml, renderMarkNodeToHtml, renderMarkInlineToHtml, type RenderCode, type RenderCodeBlock, type RenderMarkOptions, } from './render.js';
 export { type ResolveImageSrc } from './image-resolve.js';
 export { type ResolveHref } from './href-resolve.js';
 export { escapeHtml } from './escape.js';

package/dist/render.d.ts

@@ -2,7 +2,7 @@ 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 { OnDiagnostic, UnavailableComponent } from '@markii/stdlib';
 import type { ResolveImageSrc } from './image-resolve.js';
 import type { ResolveHref } from './href-resolve.js';
 /**
@@ -12,6 +12,15 @@ import type { ResolveHref } from './href-resolve.js';
  * `@markii/react`'s identical `MarkRoot` type alias.
  */
 type MarkRoot = ReturnType<typeof parse>;
+/** A fenced code block as offered to `RenderMarkOptions.renderCode`. */
+export interface RenderCodeBlock {
+    /** The info-string language, or `undefined` when the fence names none. */
+    readonly lang: string | undefined;
+    /** The raw code text, without the fence lines. */
+    readonly code: string;
+}
+/** The `renderCode` callback: host HTML for a code block, or `undefined` to render it as usual. */
+export type RenderCode = (code: RenderCodeBlock) => string | undefined;
 /**
  * Renders Markii text to a static HTML string using `registry` to resolve
  * directive names. Pipeline: `@markii/core`'s `toHast` (parse -> tag directive
@@ -65,9 +74,31 @@ type MarkRoot = ReturnType<typeof parse>;
  * `RenderMarkOptions`, so the two engines cannot diverge.
  */
 export interface RenderMarkOptions {
+    /**
+     * Replaces the output for an ordinary fenced code block. Called with the
+     * info-string language (`undefined` when the fence names none) and the
+     * raw code text. Return an HTML string to use it, or `undefined` to render
+     * the block as usual. Never called for script fences (the collapsed
+     * `{name=...}` markers) or for inline code.
+     *
+     * The returned string is HOST-TRUSTED output and is inserted as-is, with
+     * no escaping and no sanitizing: the host owns the escaping. Escape the
+     * code text yourself if you wrap it in markup. A callback that throws
+     * renders the block as usual and reports a `'code-renderer-failed'`
+     * event through `onDiagnostic`.
+     */
+    readonly renderCode?: RenderCode;
     readonly resolveImageSrc?: ResolveImageSrc;
     readonly resolveHref?: ResolveHref;
     readonly onDiagnostic?: OnDiagnostic;
+    /**
+     * Components of installed packs that this render cannot draw, as plain
+     * data from the host. A directive named here renders the usual fallback
+     * box labeled "no HTML view for" instead of "unknown component", and
+     * `onDiagnostic` gets a `'no-engine-view'` event. Omitted, the render is
+     * unchanged.
+     */
+    readonly unavailableComponents?: readonly UnavailableComponent[];
     /**
      * 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

package/dist/render.js

@@ -4,8 +4,8 @@ import { readRegistryComponent, registryLayoutAxis, resolveDirectiveAlias, } fro
 import { resolveLayoutAttributes } from './layout.js';
 import { escapeHtml } from './escape.js';
 import { resolveScopedPath } from './resolve.js';
-import { failureKindClass, failureTitle, EMPTY_INLINE_MARKER_CLASS, emptyInlineTitle, invalidAttributeValueTitle, } from './failure-presentation.js';
-import { formatValue, getContract, reportDiagnostic, INTERACTIVE_ATTRIBUTE, } from '@markii/stdlib';
+import { failureKindClass, failureTitle, EMPTY_INLINE_MARKER_CLASS, emptyInlineTitle, codeRendererFailedTitle, formMismatchTitle, INLINE_FALLBACK_SEPARATOR, invalidAttributeValueTitle, NO_ENGINE_VIEW_LABEL, noEngineViewTitle, } from './failure-presentation.js';
+import { createUnavailableComponentLookup, formatValue, getContract, reportDiagnostic, INTERACTIVE_ATTRIBUTE, } from '@markii/stdlib';
 import { resolveImageAttribute } from './image-resolve.js';
 import { resolveHrefAttribute } from './href-resolve.js';
 function isMarkRoot(node) {
@@ -213,6 +213,8 @@ function isRegisteredInline(entry) {
 /** The fallback label line, worded for the reason and the form the directive was written in. Returns HTML. */
 function fallbackLabel(name, inline, reason) {
     const code = `<code>${escapeHtml(name)}</code>`;
+    if (reason === 'no-engine-view')
+        return `${NO_ENGINE_VIEW_LABEL} ${code}`;
     if (reason === 'form-mismatch') {
         return inline
             ? `block component ${code} written inline`
@@ -220,24 +222,39 @@ function fallbackLabel(name, inline, reason) {
     }
     return `unknown component ${code}`;
 }
+/**
+ * The separator an inline fallback's label ends with when the fallback has
+ * content to show after it, matching `@markii/ansi`'s `label: content`.
+ * Nested inside the label span so it takes the label's styling.
+ */
+function inlineSeparator(childrenHtml) {
+    return childrenHtml.trim() === ''
+        ? ''
+        : `<span class="mk-unknown__separator">${INLINE_FALLBACK_SEPARATOR}</span>`;
+}
 /**
  * The unknown-directive fallback, matching `@markii/react`'s `UnknownDirective`
  * markup and class names byte-for-byte so one stylesheet covers both renderers.
  * An inline directive is built from `<span>`s (it lives inside a paragraph); a
  * block directive gets the dashed `<div>` box with its inner content preserved.
  */
-function unknownDirective(name, inline, childrenHtml, reason) {
-    const reasonClass = reason === 'form-mismatch' ? ' mk-unknown--mismatch' : '';
+function unknownDirective(name, inline, childrenHtml, reason, title) {
+    const reasonClass = reason === 'form-mismatch'
+        ? ' mk-unknown--mismatch'
+        : reason === 'no-engine-view'
+            ? ' mk-unknown--no-view'
+            : '';
+    const titleAttr = title === undefined ? '' : ` title="${escapeHtml(title)}"`;
     const label = fallbackLabel(name, inline, reason);
     if (inline) {
-        return (`<span class="mk-unknown mk-unknown--inline${reasonClass}">` +
-            `<span class="mk-unknown__label">${label}</span>` +
+        return (`<span class="mk-unknown mk-unknown--inline${reasonClass}"${titleAttr}>` +
+            `<span class="mk-unknown__label">${label}${inlineSeparator(childrenHtml)}</span>` +
             `${childrenHtml}</span>`);
     }
     const content = childrenHtml
         ? `<div class="mk-unknown__content">${childrenHtml}</div>`
         : '';
-    return (`<div class="mk-unknown mk-unknown--block${reasonClass}">` +
+    return (`<div class="mk-unknown mk-unknown--block${reasonClass}"${titleAttr}>` +
         `<p class="mk-unknown__label">${label}</p>${content}</div>`);
 }
 /**
@@ -251,7 +268,7 @@ function componentError(name, inline, childrenHtml) {
     const code = `<code>${escapeHtml(name)}</code>`;
     if (inline) {
         return (`<span class="mk-unknown mk-unknown--inline mk-unknown--error">` +
-            `<span class="mk-unknown__label">component ${code} failed to render</span>` +
+            `<span class="mk-unknown__label">component ${code} failed to render${inlineSeparator(childrenHtml)}</span>` +
             `${childrenHtml}</span>`);
     }
     const content = childrenHtml
@@ -365,7 +382,7 @@ function invalidEnumAttribute(name, attributes) {
     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) {
+function renderDirectiveContent(name, kind, attributes, childrenHtml, plainLabel, registry, ctx, scope, layoutClassName, unavailable) {
     if (name === VALUE_DIRECTIVE_NAME) {
         return ctx.valueMarker(plainLabel, attributes.format ?? undefined, attributes.decimals ?? undefined);
     }
@@ -373,9 +390,24 @@ function renderDirectiveContent(name, kind, attributes, childrenHtml, plainLabel
     const entry = Object.hasOwn(registry, name) ? registry[name] : undefined;
     const component = readRegistryComponent(entry);
     if (!entry || component == null) {
+        const missingView = unavailable?.(name);
+        if (missingView !== undefined) {
+            const title = noEngineViewTitle(name, missingView.pack, missingView.engines);
+            reportDiagnostic(ctx.onDiagnostic, {
+                kind: 'no-engine-view',
+                directive: name,
+                message: title,
+            });
+            return unknownDirective(name, inline, childrenHtml, 'no-engine-view', title);
+        }
         return unknownDirective(name || '(unnamed)', inline, childrenHtml, 'unregistered');
     }
     if (isFormMismatch(entry, kind)) {
+        reportDiagnostic(ctx.onDiagnostic, {
+            kind: 'form-mismatch',
+            directive: name,
+            message: formMismatchTitle(name),
+        });
         return unknownDirective(name || '(unnamed)', inline, childrenHtml, 'form-mismatch');
     }
     const binding = resolveDataAttribute(attributes, scope);
@@ -417,7 +449,7 @@ function renderDirectiveContent(name, kind, attributes, childrenHtml, plainLabel
     return rendered;
 }
 /** Turns one `<mk-directive>` element (children already transformed) into its HTML string, including the layout wrapper for block directives. */
-function renderDirective(element, registry, ctx, scope) {
+function renderDirective(element, registry, ctx, scope, unavailable) {
     const written = stringProperty(element, 'data-mk-name') ?? '';
     const kind = stringProperty(element, 'data-mk-kind');
     const rawAttributes = parseAttributes(stringProperty(element, 'data-mk-attrs'));
@@ -436,7 +468,7 @@ function renderDirective(element, registry, ctx, scope) {
     const ownedAxis = registryLayoutAxis(registry, name);
     const { attributes, className } = resolveLayoutAttributes(aliased, ownedAxis);
     const isLayoutScope = ownedAxis !== undefined && isBlock;
-    const content = renderDirectiveContent(name, kind, attributes, childrenHtml, plainLabel, registry, ctx, scope, isLayoutScope ? className : undefined);
+    const content = renderDirectiveContent(name, kind, attributes, childrenHtml, plainLabel, registry, ctx, scope, isLayoutScope ? className : undefined, unavailable);
     return isBlock && className && !isLayoutScope
         ? `<div class="${escapeHtml(className)}">${content}</div>`
         : content;
@@ -475,17 +507,48 @@ function applyHrefResolver(node, resolveHref) {
         node.properties.href = resolveHrefAttribute(href, resolveHref);
     }
 }
-function makeTransform(registry, ctx, scope, resolveHref) {
+/**
+ * Offers one ordinary fenced code block (a `<pre>` holding a `<code>`) to the
+ * host's `renderCode`. Returns the host's HTML, or `undefined` to render the
+ * block as usual: no callback, a callback that declines, or one that throws
+ * (reported through `onDiagnostic`, never breaking the render). A callback
+ * result that is not a string is treated as declining.
+ */
+function applyRenderCode(node, renderCode, onDiagnostic) {
+    if (!renderCode)
+        return undefined;
+    const codeNode = findChildElement(node, 'code');
+    if (!codeNode)
+        return undefined;
+    try {
+        const result = renderCode({
+            lang: getLanguage(codeNode) || undefined,
+            code: getCodeText(codeNode),
+        });
+        return typeof result === 'string' ? result : undefined;
+    }
+    catch {
+        reportDiagnostic(onDiagnostic, {
+            kind: 'code-renderer-failed',
+            message: codeRendererFailedTitle(),
+        });
+        return undefined;
+    }
+}
+function makeTransform(registry, ctx, scope, resolveHref, unavailable, renderCode) {
     function transform(node) {
         if (node.type !== 'element')
             return node;
         node.children = node.children.map((child) => transform(child));
         if (node.tagName === DIRECTIVE_TAG)
-            return raw(renderDirective(node, registry, ctx, scope));
+            return raw(renderDirective(node, registry, ctx, scope, unavailable));
         if (node.tagName === 'pre') {
             const marker = renderScriptMarker(node);
             if (marker !== undefined)
                 return raw(marker);
+            const custom = applyRenderCode(node, renderCode, ctx.onDiagnostic);
+            if (custom !== undefined)
+                return raw(custom);
         }
         if (node.tagName === 'img') {
             applyImageResolver(node, ctx.resolveImageSrc);
@@ -504,15 +567,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, resolveImageSrc, resolveHref, onDiagnostic) {
+function renderRoot(root, registry, scope, resolveImageSrc, resolveHref, onDiagnostic, unavailable, renderCode) {
     const ctx = createBaseContext(scope, resolveImageSrc, onDiagnostic);
-    const transform = makeTransform(registry, ctx, scope, resolveHref);
+    const transform = makeTransform(registry, ctx, scope, resolveHref, unavailable, renderCode);
     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);
+        return renderRoot(toHast(text), registry, { store: options?.store ?? store, vault: options?.vault ?? vault }, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, createUnavailableComponentLookup(options?.unavailableComponents), options?.renderCode);
     }
     catch (error) {
         return renderFailureFallback(error);
@@ -533,7 +596,7 @@ export function renderMarkToHtml(text, registry, store, vault, options) {
  */
 export function renderMarkNodeToHtml(node, registry, store, vault, options) {
     try {
-        return renderRoot(nodeOrRootToHast(node), registry, { store: options?.store ?? store, vault: options?.vault ?? vault }, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic);
+        return renderRoot(nodeOrRootToHast(node), registry, { store: options?.store ?? store, vault: options?.vault ?? vault }, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, createUnavailableComponentLookup(options?.unavailableComponents), options?.renderCode);
     }
     catch (error) {
         return renderFailureFallback(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/html",
-  "version": "0.16.0",
+  "version": "0.17.0-next.1",
   "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.16.0",
-    "@markii/runtime": "^0.16.0",
-    "@markii/stdlib": "^0.16.0"
+    "@markii/core": "^0.17.0-next.1",
+    "@markii/runtime": "^0.17.0-next.1",
+    "@markii/stdlib": "^0.17.0-next.1"
   },
   "devDependencies": {
     "@types/hast": "^3.0.4"