@markii/html 0.6.0

package/dist/layout.d.ts

@@ -0,0 +1,31 @@
+import type { DirectiveAttributes } from './registry.js';
+/**
+ * The closed set of layout-preset attributes (docs/format.md): a small,
+ * non-freeform-CSS vocabulary any block directive can carry regardless of
+ * which component renders it. These two keys are reserved: always intercepted
+ * before a component sees its `attributes`, whether or not their value turns
+ * out to be valid. This mirrors `@markii/react`'s `layout.ts` exactly, so the
+ * two renderers strip and classify the same keys the same way.
+ */
+export declare const LAYOUT_ATTRIBUTE_KEYS: readonly ["width", "align"];
+export interface ResolvedLayoutAttributes {
+    /** `attributes` with every reserved layout key (present, valid or not) removed. */
+    attributes: DirectiveAttributes;
+    /** Space-joined layout classes, or `undefined` if none applied: never an empty string. */
+    className?: string;
+}
+/**
+ * Splits docs/format.md's closed layout-attribute set (`width`, `align`) off
+ * `attributes`, returning the remaining attributes untouched plus the combined
+ * class string those two attributes resolve to, if any.
+ *
+ * Both keys are stripped whenever the key is present on the input, regardless
+ * of whether its value is valid; they are reserved layout attributes, so
+ * interception wins over a same-named attribute a component might otherwise
+ * read itself. Presence is checked with `Object.hasOwn`, so a directive
+ * attribute literally named `constructor` or `__proto__` is never mistaken for
+ * a real key via the prototype chain. An invalid or hostile value never
+ * produces a class: it is dropped silently, exactly like an absent attribute.
+ * Never throws.
+ */
+export declare function resolveLayoutAttributes(attributes: DirectiveAttributes): ResolvedLayoutAttributes;

package/dist/layout.js

@@ -0,0 +1,75 @@
+/**
+ * The closed set of layout-preset attributes (docs/format.md): a small,
+ * non-freeform-CSS vocabulary any block directive can carry regardless of
+ * which component renders it. These two keys are reserved: always intercepted
+ * before a component sees its `attributes`, whether or not their value turns
+ * out to be valid. This mirrors `@markii/react`'s `layout.ts` exactly, so the
+ * two renderers strip and classify the same keys the same way.
+ */
+export const LAYOUT_ATTRIBUTE_KEYS = ['width', 'align'];
+/** `width=normal` is the explicit default: it maps to no class, same as an absent `width`. */
+const NORMAL_WIDTH = 'normal';
+/**
+ * `width` value -> class. Null-prototype so a hostile value like `__proto__`
+ * or `constructor` cannot resolve through the prototype chain to an inherited
+ * `Object.prototype` member; it simply misses the lookup, same as any other
+ * unrecognized value.
+ */
+const WIDTH_CLASSES = Object.assign(Object.create(null), {
+    narrow: 'mk-width-narrow',
+    wide: 'mk-width-wide',
+    full: 'mk-width-full',
+});
+/** `align` value -> class. Same null-prototype defense as `WIDTH_CLASSES`. */
+const ALIGN_CLASSES = Object.assign(Object.create(null), {
+    left: 'mk-align-left',
+    center: 'mk-align-center',
+    right: 'mk-align-right',
+});
+function widthClassFor(value) {
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    if (value === NORMAL_WIDTH)
+        return undefined;
+    return WIDTH_CLASSES[value];
+}
+function alignClassFor(value) {
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    return ALIGN_CLASSES[value];
+}
+/**
+ * Splits docs/format.md's closed layout-attribute set (`width`, `align`) off
+ * `attributes`, returning the remaining attributes untouched plus the combined
+ * class string those two attributes resolve to, if any.
+ *
+ * Both keys are stripped whenever the key is present on the input, regardless
+ * of whether its value is valid; they are reserved layout attributes, so
+ * interception wins over a same-named attribute a component might otherwise
+ * read itself. Presence is checked with `Object.hasOwn`, so a directive
+ * attribute literally named `constructor` or `__proto__` is never mistaken for
+ * a real key via the prototype chain. An invalid or hostile value never
+ * produces a class: it is dropped silently, exactly like an absent attribute.
+ * Never throws.
+ */
+export function resolveLayoutAttributes(attributes) {
+    let rest = attributes;
+    const classes = [];
+    if (Object.hasOwn(rest, 'width')) {
+        const { width, ...remainder } = rest;
+        rest = remainder;
+        const widthClass = widthClassFor(width);
+        if (widthClass)
+            classes.push(widthClass);
+    }
+    if (Object.hasOwn(rest, 'align')) {
+        const { align, ...remainder } = rest;
+        rest = remainder;
+        const alignClass = alignClassFor(align);
+        if (alignClass)
+            classes.push(alignClass);
+    }
+    return classes.length > 0
+        ? { attributes: rest, className: classes.join(' ') }
+        : { attributes: rest };
+}

package/dist/registry.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The registry contract for the HTML engine: the string-emitting twin of
+ * `@markii/react`'s `registry.ts`. Everything here is framework-free by
+ * construction (no React types), because a component is a plain function
+ * from attributes and already-rendered children to an HTML string. The
+ * alias, merge, and hostile-configuration rules are deliberately identical to
+ * the React renderer's, so a note resolves the same way in both.
+ */
+import type { FailureKind, ValueStatus } from '@markii/runtime';
+/**
+ * Attributes parsed off a directive, e.g. `{type=warning title="Careful"}`. A
+ * bare attribute (present but valueless, e.g. `{collapsed}`) arrives as
+ * `null`. A key that was never written is simply absent.
+ */
+export type DirectiveAttributes = Record<string, string | null | undefined>;
+/**
+ * A `data=`/`:value[...]` name resolved against the render's value store
+ * (and, for an `@`-prefixed name, its vault) — the string engine's read-only
+ * view of `./resolve.js`'s `StorePathResolution`. Never carries a `Proxy` or
+ * any other live handle: `value` is whatever the store returned, but
+ * `status`/`error`/`failureKind` are already validated primitives.
+ */
+export interface ValueResolution {
+    value: unknown;
+    status: ValueStatus;
+    error?: string;
+    failureKind?: FailureKind;
+}
+/**
+ * The render context handed to every component. `esc` is the engine's single
+ * HTML-escaping primitive (see `./escape`), so a component never hand-rolls
+ * escaping.
+ *
+ * `resolve` looks up a `data=`-style name (dotted paths, `@`-prefixed vault
+ * names) against the store/vault the current render was called with; it
+ * degrades to `{ value: undefined, status: 'missing' }` when there is no
+ * store/vault, or the name doesn't resolve — it never throws. `valueMarker`
+ * is the empty/stale-state presentation for a resolved name, matching
+ * `@markii/react`'s `ValueDirective` exactly (the missing-value `{name}`
+ * span, the stale underline, the failure-kind tooltip); it is what powers
+ * the `:value[...]` built-in and is exposed here so a data-bound component
+ * can render the identical marker for a name it resolves itself.
+ *
+ * `data`/`dataStatus`/`dataError`/`dataFailureKind` mirror `@markii/react`'s
+ * `MarkComponentProps` fields, just carried on `ctx` instead of a fourth
+ * function parameter (the `HtmlComponent` signature is `(attributes,
+ * childrenHtml, ctx)`, with no room for a fifth argument). They are present
+ * ONLY when the directive actually had a `data=` attribute — `dataStatus`
+ * is always one of the four `ValueStatus` values in that case, even when the
+ * name didn't resolve (`'missing'`); all four are `undefined` together when
+ * there was no `data=` attribute at all, exactly like the `'data' in
+ * binding` distinction `@markii/react`'s `renderDirectiveContent` makes.
+ */
+export interface HtmlRenderContext {
+    /** HTML-escapes a string for safe insertion into text or a quoted attribute value. */
+    esc(value: string): string;
+    /** Resolves a `data=`/`:value[...]` name against the current render's store/vault. Never throws. */
+    resolve(name: string): ValueResolution;
+    /** The quiet missing/stale/failure-tinted marker for `name`, matching `@markii/react`'s `ValueDirective` markup exactly. Never throws. */
+    valueMarker(name: string): string;
+    data?: unknown;
+    dataStatus?: ValueStatus;
+    dataError?: string;
+    dataFailureKind?: FailureKind;
+}
+/**
+ * One registry component: receives the directive's raw string attributes
+ * (bare attributes as `null`), its inner markdown already rendered to an HTML
+ * string, and the render context, and returns the HTML string to emit.
+ * Attribute parsing, validation, and defaulting are the component's own job,
+ * exactly as in the React contract.
+ */
+export type HtmlComponent = (attributes: DirectiveAttributes, childrenHtml: string, ctx: HtmlRenderContext) => string;
+/**
+ * One registry entry: the component plus whether it is meant to be used
+ * inline (text directive) vs as a block (leaf/container directive). Only an
+ * explicit `inline: false` drives the form/kind mismatch rule; `undefined`
+ * says nothing about kind.
+ */
+export interface HtmlRegistryEntry {
+    component: HtmlComponent;
+    inline?: boolean;
+}
+/** One alias: a second name for an existing component, optionally carrying preset attributes. */
+export interface RegistryAlias {
+    name: string;
+    attributes?: DirectiveAttributes;
+}
+/** Alias name -> what it stands for. */
+export type RegistryAliases = Record<string, RegistryAlias>;
+/**
+ * The symbol an alias table hangs off a registry under: a symbol rather than
+ * a string key so it can never collide with a directive name, never show up
+ * in `Object.keys`, and still ride across `Object.assign` (so `mergeHtml`
+ * `Registries` carries it). Mirrors `@markii/react`'s `REGISTRY_ALIASES`.
+ */
+export declare const REGISTRY_ALIASES: unique symbol;
+/** Directive name -> component registration, plus an optional alias table under `REGISTRY_ALIASES`. */
+export interface HtmlRegistry {
+    [name: string]: HtmlRegistryEntry;
+    [REGISTRY_ALIASES]?: RegistryAliases;
+}
+/** Reads a registry's alias table, or `undefined` when it has none. Returned as-is; treat as read-only. */
+export declare function registryAliases(registry: HtmlRegistry): RegistryAliases | undefined;
+/**
+ * Creates a registry from a plain object of entries plus an optional alias
+ * table. The returned map has a `null` prototype so a directive named
+ * `constructor`, `toString`, `hasOwnProperty`, etc. cannot resolve to an
+ * inherited member; only entries actually registered are ever found.
+ */
+export declare function createHtmlRegistry(entries?: HtmlRegistry, aliases?: RegistryAliases): HtmlRegistry;
+/**
+ * Merges any number of registries, later ones taking precedence, into a
+ * null-prototype map. Alias tables merge per name, not wholesale, so a later
+ * registry that defines any alias does not silently drop earlier ones.
+ */
+export declare function mergeHtmlRegistries(...registries: HtmlRegistry[]): HtmlRegistry;
+/**
+ * Reads `entry.component`, or `undefined` if `entry` is nullish or the read
+ * itself throws. A hand-built registry can define `component` as a throwing
+ * getter (or a trapping `Proxy`); a throwing read degrades to "no component
+ * here", identical to a genuinely absent one, never an exception escaping the
+ * renderer (docs/spec.md requirement 4).
+ */
+export declare function readRegistryComponent(entry: HtmlRegistryEntry | undefined): HtmlComponent | undefined;
+/** A directive name and attributes after alias resolution. */
+export interface ResolvedDirective {
+    name: string;
+    attributes: DirectiveAttributes;
+}
+/**
+ * Resolves one directive name through the registry's alias table. Four rules,
+ * in order: a real component wins over any alias; an unaliased name passes
+ * through; an alias is followed exactly one hop (a chain lands on the
+ * unknown-directive fallback rather than chaining); author attributes win over
+ * the alias's presets. Never throws; a malformed alias degrades to the
+ * ordinary unknown-directive path. Identical to `@markii/react`'s rule.
+ */
+export declare function resolveDirectiveAlias(registry: HtmlRegistry, name: string, attributes: DirectiveAttributes): ResolvedDirective;

package/dist/registry.js

@@ -0,0 +1,118 @@
+/**
+ * The registry contract for the HTML engine: the string-emitting twin of
+ * `@markii/react`'s `registry.ts`. Everything here is framework-free by
+ * construction (no React types), because a component is a plain function
+ * from attributes and already-rendered children to an HTML string. The
+ * alias, merge, and hostile-configuration rules are deliberately identical to
+ * the React renderer's, so a note resolves the same way in both.
+ */
+/**
+ * The symbol an alias table hangs off a registry under: a symbol rather than
+ * a string key so it can never collide with a directive name, never show up
+ * in `Object.keys`, and still ride across `Object.assign` (so `mergeHtml`
+ * `Registries` carries it). Mirrors `@markii/react`'s `REGISTRY_ALIASES`.
+ */
+export const REGISTRY_ALIASES = Symbol('markii.html.registry.aliases');
+/** Reads a registry's alias table, or `undefined` when it has none. Returned as-is; treat as read-only. */
+export function registryAliases(registry) {
+    return registry[REGISTRY_ALIASES];
+}
+/**
+ * Combines alias tables left-to-right into one null-prototype map, later
+ * tables winning per name. Returns `undefined` when no input carried aliases,
+ * so an alias-free merge stays alias-free.
+ */
+function mergeAliasTables(tables) {
+    const present = tables.filter((table) => table !== undefined);
+    if (present.length === 0)
+        return undefined;
+    const merged = Object.create(null);
+    for (const table of present) {
+        for (const name of Object.keys(table))
+            merged[name] = table[name];
+    }
+    return merged;
+}
+/**
+ * Creates a registry from a plain object of entries plus an optional alias
+ * table. The returned map has a `null` prototype so a directive named
+ * `constructor`, `toString`, `hasOwnProperty`, etc. cannot resolve to an
+ * inherited member; only entries actually registered are ever found.
+ */
+export function createHtmlRegistry(entries = {}, aliases) {
+    const registry = Object.assign(Object.create(null), entries);
+    const merged = mergeAliasTables([registryAliases(entries), aliases]);
+    if (merged)
+        registry[REGISTRY_ALIASES] = merged;
+    return registry;
+}
+/**
+ * Merges any number of registries, later ones taking precedence, into a
+ * null-prototype map. Alias tables merge per name, not wholesale, so a later
+ * registry that defines any alias does not silently drop earlier ones.
+ */
+export function mergeHtmlRegistries(...registries) {
+    const merged = Object.assign(Object.create(null), ...registries);
+    const aliases = mergeAliasTables(registries.map(registryAliases));
+    if (aliases)
+        merged[REGISTRY_ALIASES] = aliases;
+    else
+        delete merged[REGISTRY_ALIASES];
+    return merged;
+}
+/**
+ * Reads `entry.component`, or `undefined` if `entry` is nullish or the read
+ * itself throws. A hand-built registry can define `component` as a throwing
+ * getter (or a trapping `Proxy`); a throwing read degrades to "no component
+ * here", identical to a genuinely absent one, never an exception escaping the
+ * renderer (docs/spec.md requirement 4).
+ */
+export function readRegistryComponent(entry) {
+    if (!entry)
+        return undefined;
+    try {
+        return entry.component ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether `registry` has a real, usable component under `name` (own property, non-nullish, non-throwing). */
+function hasComponent(registry, name) {
+    return (Object.hasOwn(registry, name) &&
+        readRegistryComponent(registry[name]) != null);
+}
+/** Merges an alias's preset attributes under the author's own, author winning on collision ("closest to the text wins"). */
+function mergeAliasAttributes(preset, author) {
+    if (!preset)
+        return author;
+    const result = {};
+    for (const [key, value] of Object.entries(preset))
+        result[key] = value;
+    for (const [key, value] of Object.entries(author))
+        result[key] = value;
+    return result;
+}
+/**
+ * Resolves one directive name through the registry's alias table. Four rules,
+ * in order: a real component wins over any alias; an unaliased name passes
+ * through; an alias is followed exactly one hop (a chain lands on the
+ * unknown-directive fallback rather than chaining); author attributes win over
+ * the alias's presets. Never throws; a malformed alias degrades to the
+ * ordinary unknown-directive path. Identical to `@markii/react`'s rule.
+ */
+export function resolveDirectiveAlias(registry, name, attributes) {
+    if (hasComponent(registry, name))
+        return { name, attributes };
+    const aliases = registryAliases(registry);
+    if (!aliases || !Object.hasOwn(aliases, name))
+        return { name, attributes };
+    const alias = aliases[name];
+    if (typeof alias?.name !== 'string' || alias.name === '') {
+        return { name, attributes };
+    }
+    return {
+        name: alias.name,
+        attributes: mergeAliasAttributes(alias.attributes, attributes),
+    };
+}

package/dist/render.d.ts

@@ -0,0 +1,34 @@
+import type { MarkNode } from '@markii/core';
+import type { ValueStore, VaultStore } from '@markii/runtime';
+import type { HtmlRegistry } from './registry.js';
+/**
+ * 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 declare function renderMarkToHtml(text: string, registry: HtmlRegistry, store?: ValueStore, vault?: VaultStore): 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.
+ */
+export declare function renderMarkNodeToHtml(node: MarkNode, registry: HtmlRegistry, store?: ValueStore, vault?: VaultStore): string;