@markii/html 0.16.0 → 0.17.0-next.0

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,24 @@ 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 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,31 @@ 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 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/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';
 /**
@@ -68,6 +68,14 @@ export interface RenderMarkOptions {
     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, 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,13 +507,13 @@ function applyHrefResolver(node, resolveHref) {
         node.properties.href = resolveHrefAttribute(href, resolveHref);
     }
 }
-function makeTransform(registry, ctx, scope, resolveHref) {
+function makeTransform(registry, ctx, scope, resolveHref, unavailable) {
     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)
@@ -504,15 +536,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) {
     const ctx = createBaseContext(scope, resolveImageSrc, onDiagnostic);
-    const transform = makeTransform(registry, ctx, scope, resolveHref);
+    const transform = makeTransform(registry, ctx, scope, resolveHref, unavailable);
     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));
     }
     catch (error) {
         return renderFailureFallback(error);
@@ -533,7 +565,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));
     }
     catch (error) {
         return renderFailureFallback(error);

package/package.json

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