@markii/ansi 0.0.1

package/dist/resolve.d.ts

@@ -0,0 +1,60 @@
+import type { AnsiValueStore, AnsiVaultStore, FailureKind, ValueStatus } from './value-types.js';
+/**
+ * This engine's port of `@markii/html`'s `resolve.ts` (itself a port of
+ * `@markii/react`'s `store-path.ts`): resolves a `data=`/`:value[]` name
+ * (optionally dotted, optionally `@`-prefixed for the vault) against a
+ * value store. Ported rather than shared for the same reason `@markii/html`
+ * ports it rather than importing `@markii/react`: each platform renderer is
+ * an independent implementation of the same contract (docs/scripting.md),
+ * kept behaviorally identical by test coverage, not by a shared runtime
+ * dependency between renderers. The one difference from `@markii/html`'s
+ * copy is the store type: `./value-types.js`'s structural `AnsiValueStore`/
+ * `AnsiVaultStore` instead of `@markii/runtime`'s concrete types, so this
+ * package never needs `@markii/runtime` at runtime (see `value-types.ts`).
+ * The resolution semantics are otherwise unchanged, byte for byte.
+ */
+/** What resolving a (possibly dotted) name against a store produces. */
+export interface StorePathResolution {
+    value: unknown;
+    status: ValueStatus;
+    /** The root entry's error message, if it has one — carried through regardless of how the rest of the path resolved. Always a `string` when present. */
+    error?: string;
+    /** The root entry's `failureKind`, carried through exactly like `error`. Absent when the root entry didn't carry one, or on a host-store fault (never invented). */
+    failureKind?: FailureKind;
+}
+/**
+ * Best-effort description of something host code threw, for the tooltip
+ * channel. Every step is itself guarded: `instanceof`, `.message`, and
+ * `String(...)` can all throw when the thrown value is a revoked `Proxy` or
+ * an object with hostile traps/getters.
+ */
+export declare function describeHostFault(err: unknown): string;
+/** The one-character prefix that routes a `data=`/`:value[]` name at the vault store instead of the note store (docs/scripting.md). */
+export declare const VAULT_NAME_PREFIX = "@";
+/** Where a `resolveScopedPath` lookup may read from. Either half may be absent. */
+export interface ValueScope {
+    store?: AnsiValueStore;
+    vault?: AnsiVaultStore;
+}
+/**
+ * Resolves a `data=`/`:value[]` name against `store`, walking a dotted path.
+ * Never throws, including against a hostile or buggy host store.
+ */
+export declare function resolveStorePath(store: AnsiValueStore | undefined, dottedName: string): StorePathResolution;
+/**
+ * Resolves a `data=`/`:value[]` name against a `ValueScope`, routing an
+ * `@`-prefixed name at `scope.vault` instead of `scope.store` ("bare name =
+ * mine, `@name` = the vault's"). Never throws.
+ */
+export declare function resolveScopedPath(scope: ValueScope, dottedName: string): StorePathResolution;
+/** What `safeRead` produces: the extracted fields, plus the thrown message when the extraction had to be abandoned. */
+export interface SafeRead<T> {
+    fields: T;
+    fault?: string;
+}
+/**
+ * Runs `read` — an extraction that touches an untrusted bound `data` value —
+ * and falls back to `fallback()` if any part of it throws. Ported from
+ * `@markii/react`'s `safe-data.ts` by way of `@markii/html`'s `resolve.ts`.
+ */
+export declare function safeRead<T>(read: () => T, fallback: () => T): SafeRead<T>;

package/dist/resolve.js

@@ -0,0 +1,152 @@
+const MISSING = { value: undefined, status: 'missing' };
+/** `ValueStatus`'s members, for validating a status read back off an untrusted entry. */
+const VALUE_STATUSES = [
+    'fresh',
+    'stale',
+    'error',
+    'missing',
+];
+function isValueStatus(value) {
+    return (typeof value === 'string' &&
+        VALUE_STATUSES.includes(value));
+}
+/**
+ * The message a host-data fault falls back to when even describing the
+ * thrown value throws. Deliberately generic: it only ever reaches a tooltip.
+ */
+const HOST_FAULT_MESSAGE = 'value store threw while reading this name';
+/**
+ * Best-effort description of something host code threw, for the tooltip
+ * channel. Every step is itself guarded: `instanceof`, `.message`, and
+ * `String(...)` can all throw when the thrown value is a revoked `Proxy` or
+ * an object with hostile traps/getters.
+ */
+export function describeHostFault(err) {
+    try {
+        if (err instanceof Error) {
+            const { message } = err;
+            if (typeof message === 'string' && message !== '')
+                return message;
+        }
+        const text = String(err);
+        return text === '' ? HOST_FAULT_MESSAGE : text;
+    }
+    catch {
+        return HOST_FAULT_MESSAGE;
+    }
+}
+/** The degraded resolution for a HOST-STORE FAULT: resolves to `'missing'`, carrying the thrown message as `error`, never inventing a `failureKind`. */
+function hostFault(err) {
+    return { value: undefined, status: 'missing', error: describeHostFault(err) };
+}
+/** The one-character prefix that routes a `data=`/`:value[]` name at the vault store instead of the note store (docs/scripting.md). */
+export const VAULT_NAME_PREFIX = '@';
+/** Reads the four `StoredValue` fields off an entry a host store handed back. MAY THROW; every caller wraps it. */
+function readEntry(entry) {
+    const value = entry.value;
+    const status = entry.status;
+    const error = entry.error;
+    const failureKind = entry.failureKind;
+    return {
+        value,
+        status: isValueStatus(status) ? status : 'missing',
+        error: typeof error === 'string' ? error : undefined,
+        failureKind: typeof failureKind === 'string'
+            ? failureKind
+            : undefined,
+    };
+}
+/** The partial-path degradation: `missing`, but still carrying the root entry's own error/kind. */
+function partialMiss(entry) {
+    return {
+        value: undefined,
+        status: 'missing',
+        error: entry.error,
+        failureKind: entry.failureKind,
+    };
+}
+/**
+ * Walks `segments[1:]` into `entry.value`. Never throws: a hostile stored
+ * value (a revoked `Proxy`, throwing traps) degrades to `hostFault` rather
+ * than escaping. `Object.hasOwn` is the load-bearing guard against a segment
+ * like `__proto__`/`constructor` resolving through the prototype chain.
+ */
+function walkSegments(entry, segments) {
+    let current = entry.value;
+    for (let index = 1; index < segments.length; index += 1) {
+        const segment = segments[index];
+        if (!segment || current === null || typeof current !== 'object') {
+            return partialMiss(entry);
+        }
+        let next;
+        try {
+            if (!Object.hasOwn(current, segment))
+                return partialMiss(entry);
+            next = current[segment];
+        }
+        catch (err) {
+            return hostFault(err);
+        }
+        current = next;
+    }
+    return {
+        value: current,
+        status: entry.status,
+        error: entry.error,
+        failureKind: entry.failureKind,
+    };
+}
+/** The shared never-throw shell around a store lookup. */
+function resolveEntryPath(lookup, segments) {
+    let entry;
+    try {
+        const raw = lookup();
+        if (!raw)
+            return MISSING;
+        entry = readEntry(raw);
+    }
+    catch (err) {
+        return hostFault(err);
+    }
+    return walkSegments(entry, segments);
+}
+/**
+ * Resolves a `data=`/`:value[]` name against `store`, walking a dotted path.
+ * Never throws, including against a hostile or buggy host store.
+ */
+export function resolveStorePath(store, dottedName) {
+    const segments = dottedName.split('.');
+    const root = segments[0];
+    if (!root)
+        return MISSING;
+    return resolveEntryPath(() => store?.get(root), segments);
+}
+/**
+ * Resolves a `data=`/`:value[]` name against a `ValueScope`, routing an
+ * `@`-prefixed name at `scope.vault` instead of `scope.store` ("bare name =
+ * mine, `@name` = the vault's"). Never throws.
+ */
+export function resolveScopedPath(scope, dottedName) {
+    if (dottedName.startsWith(VAULT_NAME_PREFIX)) {
+        const remainder = dottedName.slice(VAULT_NAME_PREFIX.length);
+        const segments = remainder.split('.');
+        const root = segments[0];
+        if (!root)
+            return MISSING;
+        return resolveEntryPath(() => scope.vault?.get(root), segments);
+    }
+    return resolveStorePath(scope.store, dottedName);
+}
+/**
+ * Runs `read` — an extraction that touches an untrusted bound `data` value —
+ * and falls back to `fallback()` if any part of it throws. Ported from
+ * `@markii/react`'s `safe-data.ts` by way of `@markii/html`'s `resolve.ts`.
+ */
+export function safeRead(read, fallback) {
+    try {
+        return { fields: read() };
+    }
+    catch (err) {
+        return { fields: fallback(), fault: describeHostFault(err) };
+    }
+}

package/dist/sanitize.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The one place control characters are removed from author text before it
+ * reaches this engine's output (security critical). A Markii note is
+ * untrusted text: without this module, a note containing a raw ESC byte
+ * could move the terminal's cursor, recolor everything after it, or smuggle
+ * an OSC 8 hyperlink into the reader's terminal, all through nothing more
+ * exotic than a code fence or a link's visible text. The only escape
+ * sequences this engine's output ever carries are the ones `./ansi.ts`
+ * itself generates.
+ *
+ * Every piece of text that reaches the rendered output must pass through
+ * one of the three functions below before it is printed: an attribute
+ * value a component prints, a resolved stored value, a URL, alt text, code,
+ * and a code fence's language label all qualify. There is no fourth path.
+ */
+/**
+ * Sanitizes INLINE author text (a paragraph, a heading, link text, alt
+ * text, an attribute value a component prints): every C0 control (ESC
+ * included) and DEL, and every C1 control, is removed. A tab, carriage
+ * return, or line feed collapses to a single space instead of vanishing
+ * outright, since those three are the ones a reader would otherwise
+ * perceive as "the words ran together" rather than "a character was
+ * stripped". Everything else passes through unchanged.
+ */
+export declare function stripControlCharacters(value: string): string;
+/** The fixed number of spaces one tab expands to inside a preformatted block. Matches the common terminal default. */
+export declare const BLOCK_TAB_WIDTH = 4;
+/**
+ * Sanitizes PREFORMATTED text (a code fence's body): CRLF and a lone CR
+ * both normalize to LF so a block's line breaks behave consistently
+ * regardless of the author's line-ending style, LF itself is kept (a code
+ * block is allowed to span lines), and a tab expands to `BLOCK_TAB_WIDTH`
+ * spaces so `./measure.ts`'s width accounting never has to special-case a
+ * tab stop. Every other C0 control (ESC included), DEL, and C1 control is
+ * dropped outright: unlike inline text, a code block has no "reads as a
+ * word boundary" fallback worth preserving for a stray control byte.
+ */
+export declare function sanitizeBlockText(value: string): string;
+/**
+ * Sanitizes a URL immediately before it is embedded in an OSC 8 hyperlink
+ * sequence (`./ansi.ts`'s `hyperlink`). OSC 8's own terminator is BEL
+ * (U+0007) or ST, so a BEL or ESC byte smuggled into the URL text would
+ * prematurely close the engine's own escape sequence and let whatever
+ * follows be interpreted as raw terminal input; every C0 control, DEL, and
+ * C1 control is removed for that reason. A space is dropped too: OSC 8's
+ * URL parameter is not a place a real URL would ever legitimately contain
+ * one, and stripping it removes one more way to pad a payload without
+ * having to reason about whether some particular terminal treats a literal
+ * space specially inside the sequence.
+ */
+export declare function sanitizeUrlText(value: string): string;

package/dist/sanitize.js

@@ -0,0 +1,101 @@
+/**
+ * The one place control characters are removed from author text before it
+ * reaches this engine's output (security critical). A Markii note is
+ * untrusted text: without this module, a note containing a raw ESC byte
+ * could move the terminal's cursor, recolor everything after it, or smuggle
+ * an OSC 8 hyperlink into the reader's terminal, all through nothing more
+ * exotic than a code fence or a link's visible text. The only escape
+ * sequences this engine's output ever carries are the ones `./ansi.ts`
+ * itself generates.
+ *
+ * Every piece of text that reaches the rendered output must pass through
+ * one of the three functions below before it is printed: an attribute
+ * value a component prints, a resolved stored value, a URL, alt text, code,
+ * and a code fence's language label all qualify. There is no fourth path.
+ */
+/** Every C0 control code point (U+0000 to U+001F) plus DEL (U+007F). */
+function isC0OrDel(code) {
+    return (code >= 0x00 && code <= 0x1f) || code === 0x7f;
+}
+/** Every C1 control code point (U+0080 to U+009F), including the C1 CSI (U+009B). */
+function isC1(code) {
+    return code >= 0x80 && code <= 0x9f;
+}
+/**
+ * Sanitizes INLINE author text (a paragraph, a heading, link text, alt
+ * text, an attribute value a component prints): every C0 control (ESC
+ * included) and DEL, and every C1 control, is removed. A tab, carriage
+ * return, or line feed collapses to a single space instead of vanishing
+ * outright, since those three are the ones a reader would otherwise
+ * perceive as "the words ran together" rather than "a character was
+ * stripped". Everything else passes through unchanged.
+ */
+export function stripControlCharacters(value) {
+    let result = '';
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code === 0x09 || code === 0x0a || code === 0x0d) {
+            result += ' ';
+            continue;
+        }
+        if (isC0OrDel(code) || isC1(code))
+            continue;
+        result += char;
+    }
+    return result;
+}
+/** The fixed number of spaces one tab expands to inside a preformatted block. Matches the common terminal default. */
+export const BLOCK_TAB_WIDTH = 4;
+/**
+ * Sanitizes PREFORMATTED text (a code fence's body): CRLF and a lone CR
+ * both normalize to LF so a block's line breaks behave consistently
+ * regardless of the author's line-ending style, LF itself is kept (a code
+ * block is allowed to span lines), and a tab expands to `BLOCK_TAB_WIDTH`
+ * spaces so `./measure.ts`'s width accounting never has to special-case a
+ * tab stop. Every other C0 control (ESC included), DEL, and C1 control is
+ * dropped outright: unlike inline text, a code block has no "reads as a
+ * word boundary" fallback worth preserving for a stray control byte.
+ */
+export function sanitizeBlockText(value) {
+    const normalized = value.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    let result = '';
+    for (const char of normalized) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code === 0x0a) {
+            result += '\n';
+            continue;
+        }
+        if (code === 0x09) {
+            result += ' '.repeat(BLOCK_TAB_WIDTH);
+            continue;
+        }
+        if (isC0OrDel(code) || isC1(code))
+            continue;
+        result += char;
+    }
+    return result;
+}
+/**
+ * Sanitizes a URL immediately before it is embedded in an OSC 8 hyperlink
+ * sequence (`./ansi.ts`'s `hyperlink`). OSC 8's own terminator is BEL
+ * (U+0007) or ST, so a BEL or ESC byte smuggled into the URL text would
+ * prematurely close the engine's own escape sequence and let whatever
+ * follows be interpreted as raw terminal input; every C0 control, DEL, and
+ * C1 control is removed for that reason. A space is dropped too: OSC 8's
+ * URL parameter is not a place a real URL would ever legitimately contain
+ * one, and stripping it removes one more way to pad a payload without
+ * having to reason about whether some particular terminal treats a literal
+ * space specially inside the sequence.
+ */
+export function sanitizeUrlText(value) {
+    let result = '';
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code === 0x20)
+            continue;
+        if (isC0OrDel(code) || isC1(code))
+            continue;
+        result += char;
+    }
+    return result;
+}

package/dist/style.d.ts

@@ -0,0 +1,9 @@
+import { type ColorLevel } from './ansi.js';
+import type { AnsiTheme, Tier1Token } from './theme.js';
+/**
+ * Applies `theme`'s color for `token` to `text` at `level`. Returns `text`
+ * unchanged at `level: 'none'` (no escapes to justify) and for a `null`
+ * theme entry (a token this engine does not treat as a color, such as a
+ * width preset) — both are "nothing to apply", not an error.
+ */
+export declare function style(text: string, token: Tier1Token, theme: AnsiTheme, level: ColorLevel): string;

package/dist/style.js

@@ -0,0 +1,13 @@
+import { colorize } from './ansi.js';
+/**
+ * Applies `theme`'s color for `token` to `text` at `level`. Returns `text`
+ * unchanged at `level: 'none'` (no escapes to justify) and for a `null`
+ * theme entry (a token this engine does not treat as a color, such as a
+ * width preset) — both are "nothing to apply", not an error.
+ */
+export function style(text, token, theme, level) {
+    const color = theme[token];
+    if (!color)
+        return text;
+    return colorize(text, color, level);
+}

package/dist/theme.d.ts

@@ -0,0 +1,36 @@
+import type { AnsiColor } from './ansi.js';
+/**
+ * The terminal engine's theme: one entry per Tier 1 token `doc.css`
+ * declares (`packages/platforms/markii-react/src/doc.css`'s `.doc` block,
+ * the one that sets `--mk-bg`). Today that is the ten neutrals, the five
+ * semantic hues, and the four width presets — nineteen tokens in total.
+ *
+ * `theme-coverage.test.ts` parses that block the same way
+ * `apps/obsidian/src/theme-coverage.test.ts` parses it for the Obsidian
+ * theme layer, and fails whenever a Tier 1 token gets added to `doc.css`
+ * without a matching entry here: the same drift alarm every host theme
+ * layer carries (AGENTS.md's "New Tier 1 token" maintenance rule), applied
+ * to a THIRD kind of consumer (a color model, not a stylesheet).
+ */
+export type Tier1Token = '--mk-bg' | '--mk-raised' | '--mk-fg' | '--mk-surface' | '--mk-surface-strong' | '--mk-border' | '--mk-muted' | '--mk-faint' | '--mk-accent' | '--mk-on-accent' | '--mk-info' | '--mk-success' | '--mk-warning' | '--mk-danger' | '--mk-limit' | '--mk-width-fit' | '--mk-width-narrow' | '--mk-width-wide' | '--mk-width-full';
+/**
+ * A token maps to a real `AnsiColor`, or to `null` when the token is not a
+ * color in a terminal at all. The four width presets are `null` for that
+ * reason: `--mk-width-narrow` etc. are CSS lengths in `doc.css`, and this
+ * engine consumes their equivalent as column arithmetic instead
+ * (`./layout.ts`'s `applyLayout`), not as a printable color.
+ */
+export type AnsiTheme = Readonly<Record<Tier1Token, AnsiColor | null>>;
+/**
+ * The default theme, derived from `doc.css`'s LIGHT palette (the ten
+ * neutrals, the five semantic hues; the four width tokens are `null`, see
+ * `AnsiTheme`'s doc comment). Each entry's `ansi16` is a human judgment
+ * call, not a formula: the nearest of the eight standard terminal colors to
+ * the source hex, since 16-color terminals have no way to represent most of
+ * these hues exactly. `ansi256`/`truecolor` are derived mechanically from
+ * the same hex value, so only `ansi16` needed a human decision per token.
+ *
+ * A render option lets a caller pass a different `AnsiTheme` instead (see
+ * `render.ts`'s `RenderMarkOptions.theme`).
+ */
+export declare const defaultAnsiTheme: AnsiTheme;

package/dist/theme.js

@@ -0,0 +1,79 @@
+/** Parses a `#rrggbb` literal into an `[r, g, b]` triple. Used only to build the theme's truecolor entries from the hex values `doc.css` itself carries. */
+function hex(value) {
+    const r = Number.parseInt(value.slice(1, 3), 16);
+    const g = Number.parseInt(value.slice(3, 5), 16);
+    const b = Number.parseInt(value.slice(5, 7), 16);
+    return [r, g, b];
+}
+/**
+ * The standard xterm 216-color-cube plus grayscale-ramp formula for mapping
+ * a truecolor value down to the 256-color palette: an exact gray maps into
+ * the 24-step grayscale ramp (indices 232-255), everything else maps into
+ * the 6x6x6 color cube (indices 16-231). This is arithmetic, not a table
+ * lookup, so it introduces no dependency.
+ */
+function rgbToAnsi256(r, g, b) {
+    if (r === g && g === b) {
+        if (r < 8)
+            return 16;
+        if (r > 248)
+            return 231;
+        return Math.round(((r - 8) / 247) * 24) + 232;
+    }
+    const toCube = (channel) => Math.round((channel / 255) * 5);
+    return 16 + 36 * toCube(r) + 6 * toCube(g) + toCube(b);
+}
+/** Builds an `AnsiColor` from a `doc.css` hex literal and a hand-picked nearest ANSI-16 foreground code (the approximation this module's comment documents). */
+function color(hexValue, ansi16) {
+    const truecolor = hex(hexValue);
+    return { ansi16, ansi256: rgbToAnsi256(...truecolor), truecolor };
+}
+/**
+ * The default theme, derived from `doc.css`'s LIGHT palette (the ten
+ * neutrals, the five semantic hues; the four width tokens are `null`, see
+ * `AnsiTheme`'s doc comment). Each entry's `ansi16` is a human judgment
+ * call, not a formula: the nearest of the eight standard terminal colors to
+ * the source hex, since 16-color terminals have no way to represent most of
+ * these hues exactly. `ansi256`/`truecolor` are derived mechanically from
+ * the same hex value, so only `ansi16` needed a human decision per token.
+ *
+ * A render option lets a caller pass a different `AnsiTheme` instead (see
+ * `render.ts`'s `RenderMarkOptions.theme`).
+ */
+export const defaultAnsiTheme = {
+    // #fff — near-white ground; nearest ANSI-16 is plain white.
+    '--mk-bg': color('#ffffff', 37),
+    // #fff — same as --mk-bg (raised surfaces are un-tinted in the light theme).
+    '--mk-raised': color('#ffffff', 37),
+    // #1a1a1a — near-black body text.
+    '--mk-fg': color('#1a1a1a', 30),
+    // #f4f4f5 — a hair off white.
+    '--mk-surface': color('#f4f4f5', 37),
+    // #f0f0f2 — a hair off white, slightly deeper than --mk-surface.
+    '--mk-surface-strong': color('#f0f0f2', 37),
+    // #e4e4e7 — a light hairline gray, closer to white than to black.
+    '--mk-border': color('#e4e4e7', 37),
+    // #52525b — a mid-dark gray; bright black (90) reads as "gray" in most terminals.
+    '--mk-muted': color('#52525b', 90),
+    // #94a3b8 — a light blue-gray, closer to white than to any saturated hue.
+    '--mk-faint': color('#94a3b8', 37),
+    // #3b82f6 — a clear blue.
+    '--mk-accent': color('#3b82f6', 34),
+    // #fff — ink meant to sit on a solid accent fill; white is the nearest ANSI-16.
+    '--mk-on-accent': color('#ffffff', 37),
+    // #3b82f6 — same blue as --mk-accent (doc.css deliberately reuses it).
+    '--mk-info': color('#3b82f6', 34),
+    // #15803d — a clear green.
+    '--mk-success': color('#15803d', 32),
+    // #d97706 — an amber; nearest ANSI-16 is plain yellow.
+    '--mk-warning': color('#d97706', 33),
+    // #dc2626 — a clear red.
+    '--mk-danger': color('#dc2626', 31),
+    // #7c3aed — a violet; nearest ANSI-16 is plain magenta.
+    '--mk-limit': color('#7c3aed', 35),
+    // Width presets: consumed as column arithmetic by ./layout.ts, never as a color.
+    '--mk-width-fit': null,
+    '--mk-width-narrow': null,
+    '--mk-width-wide': null,
+    '--mk-width-full': null,
+};

package/dist/url-resolve.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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. Ported verbatim from `@markii/html`'s `url-resolve.ts` (itself
+ * mirroring `@markii/react`'s), engine-neutral, so all three 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,82 @@
+/**
+ * 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. Ported verbatim from `@markii/html`'s `url-resolve.ts` (itself
+ * mirroring `@markii/react`'s), engine-neutral, so all three 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/dist/value-format.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A thin, unformatted wrapper around `@markii/stdlib`'s `formatValue`
+ * (called with no `format`, i.e. `'plain'`), mirroring `@markii/html`'s
+ * `stringifyStoredValue`: this engine's name for "the `:value[...]`
+ * default coercion", used wherever a caller has no `format=`/`decimals=`
+ * attribute to thread through. Every engine's `:value[...]` and every
+ * `format=`-aware component calls `formatValue` directly instead, so a
+ * number, date, or percentage reads identically across all three
+ * (docs/format.md).
+ *
+ * Never throws, for the same reason `formatValue` itself never throws.
+ */
+export declare function stringifyStoredValue(value: unknown): string;