@jarenjs/view 0.34.0

package/dist/types/helpers/svg.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @file Shared SVG vnode builders over the view `h()` constructor — the
+ * single home for the small helper set that `@jarenjs/calc` and
+ * `@jarenjs/mermaid` (and any future SVG-emitting component) draw from.
+ *
+ * Every helper returns a tagged-array vnode; nothing here touches the DOM.
+ * The root is `['svg', {viewBox,…}, …]` so the view patcher namespaces the
+ * whole subtree (VIEW-FORMAT §5.4) and the serializer escapes text. These
+ * builders are geometry-defensive: coordinates flow through `num` so a
+ * NaN/±Inf never reaches the emitted string.
+ */
+/**
+ * Clamp a value to a finite number (defends the geometry against
+ * NaN/±Inf).
+ * @param {number} n
+ * @param {number} [fallback]
+ * @returns {number}
+ */
+export declare function num(n: number, fallback?: number): number;
+/**
+ * Quantize a coordinate to two decimals — the precision SVG geometry is
+ * emitted at, which keeps path data short and makes repeated renders of the
+ * same shape produce identical strings. Non-finite input passes straight
+ * through, so pair this with `num` wherever the value reaches an attribute.
+ * @param {number} v
+ * @returns {number}
+ */
+export declare function coord(v: number): number;
+/**
+ * The point at distance `r` from `(cx, cy)` along `angle` (radians,
+ * 0 = east, y growing downward — SVG screen orientation). Raw
+ * coordinates: quantization (`coord`/`num`) stays at the call site so a
+ * caller's emitted bytes are its own choice.
+ * @param {number} cx
+ * @param {number} cy
+ * @param {number} r
+ * @param {number} angle
+ * @returns {{ x: number, y: number }}
+ */
+export declare function polarPoint(cx: number, cy: number, r: number, angle: number): {
+    x: number;
+    y: number;
+};
+/**
+ * The `text-anchor` for a label placed radially outward at `angle`
+ * (radians, 0 = east, y growing downward). Labels near the left or right
+ * of the circle read away from it (`end`/`start`); the deadband around
+ * ±90° keeps top and bottom labels centred rather than flipping anchor on
+ * a hair's difference in angle.
+ * @param {number} angle
+ * @returns {'start'|'end'|'middle'}
+ */
+export declare function anchorForAngle(angle: number): 'start' | 'end' | 'middle';
+/**
+ * The root `<svg>`. The caller supplies the `class` string; theme tokens
+ * become CSS custom properties on the element (via `theme.cssVars`) so the
+ * stylesheet can re-theme without a re-render, and `theme.tokens.fontFamily`
+ * is written as the base font.
+ * @param {string} className the root element's `class`
+ * @param {number} width
+ * @param {number} height
+ * @param {{ cssVars: Record<string,string>, tokens: Record<string,string> }} theme
+ * `max-width: 100%` is written inline so a standalone SVG never overflows its
+ * container. It is inline because the theme variables are, and that means it
+ * outranks any stylesheet — so a caller whose content must NOT be scaled down
+ * (a diagram, where shrinking scales the text below legibility) has to opt out
+ * here rather than in CSS.
+ * @param {any[]} children
+ * @param {string} [key]
+ * @param {{ fit?: boolean, fontFamily?: string }} [options] `fit: false` omits
+ *   the inline `max-width`, leaving the element at its natural size for a
+ *   scrolling frame; `fontFamily` overrides the theme's base font for a root
+ *   whose type is part of its meaning (an error box quotes source, so it sets
+ *   monospace) — it must be written here because the theme variables are
+ *   inline, and an inline font outranks any stylesheet rule
+ * @returns {any}
+ */
+export declare function svgRoot(className: string, width: number, height: number, theme: {
+    cssVars: Record<string, string>;
+    tokens: Record<string, string>;
+}, children: any[], key?: string, options?: {
+    fit?: boolean;
+    fontFamily?: string;
+}): any;
+/**
+ * A `<g>` group.
+ * @param {Record<string,any>} props
+ * @param {any[]} children
+ * @returns {any}
+ */
+export declare function group(props: Record<string, any>, children: any[]): any;
+/**
+ * A `<rect>` (optionally rounded via props).
+ * @param {number} x @param {number} y @param {number} w @param {number} height
+ * @param {Record<string,any>} props
+ * @returns {any}
+ */
+export declare function rect(x: number, y: number, w: number, height: number, props: Record<string, any>): any;
+/**
+ * A `<circle>`.
+ * @param {number} cx @param {number} cy @param {number} r
+ * @param {Record<string,any>} props
+ * @returns {any}
+ */
+export declare function circle(cx: number, cy: number, r: number, props: Record<string, any>): any;
+/**
+ * A `<line>`.
+ * @param {number} x1 @param {number} y1 @param {number} x2 @param {number} y2
+ * @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export declare function line(x1: number, y1: number, x2: number, y2: number, props?: Record<string, any>): any;
+/**
+ * A `<path>` from a `d` string.
+ * @param {string} d @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export declare function path(d: string, props?: Record<string, any>): any;
+/**
+ * A `<polyline>` from `{x,y}` points (open; defaults to no fill).
+ * @param {{x:number,y:number}[]} points @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export declare function polyline(points: {
+    x: number;
+    y: number;
+}[], props?: Record<string, any>): any;
+/**
+ * A `<polygon>` from `{x,y}` points (closed).
+ * @param {{x:number,y:number}[]} points @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export declare function polygon(points: {
+    x: number;
+    y: number;
+}[], props?: Record<string, any>): any;
+/**
+ * A single-line `<text>` anchored at (x,y). `str` is coerced with
+ * `String()` so numeric labels emit as text.
+ * @param {number} x @param {number} y @param {any} str @param {number} fontSize
+ * @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export declare function textAt(x: number, y: number, str: any, fontSize: number, props?: Record<string, any>): any;
+/**
+ * A `<text>` block, one `<tspan>` per line, vertically centered on `cy`.
+ * @param {number} cx @param {number} cy
+ * @param {string[]} lines
+ * @param {number} fontSize
+ * @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export declare function textLines(cx: number, cy: number, lines: string[], fontSize: number, props?: Record<string, any>): any;
+/**
+ * Build an SVG path `d` from a list of `{x,y}` points, breaking the line
+ * on `null` entries (discontinuities / out-of-range samples). Returns
+ * `''` when there is nothing to draw.
+ * @param {Array<{x:number,y:number}|null>} points
+ * @returns {string}
+ */
+export declare function polylinePath(points: Array<{
+    x: number;
+    y: number;
+} | null>): string;

package/dist/types/helpers/theme.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file Shared theme-resolution mechanics for SVG-emitting components.
+ *
+ * `resolveTheme` is the prefix-driven kernel behind each component's
+ * `createTheme`: it resolves a theme name (or an overrides object) into a
+ * flat token table of concrete values *and* a matching set of
+ * `--<prefix>-*` CSS custom properties. Components keep their own token
+ * tables and pass their CSS-variable prefix; the resolution logic lives
+ * here once. Theme tokens are a view concern, so this is view/helpers, not
+ * core — but the pure `kebabCase` transform it uses is core's.
+ */
+/**
+ * Resolve a theme against a component's token tables.
+ *
+ * `nameOrOverrides` is either a theme name (falling back to `default` when
+ * unknown) or an overrides object; an overrides object may name a base via
+ * its `theme` property. The returned `cssVars` stamp every token as
+ * `--<prefix>-<kebab-case-key>`.
+ *
+ * An overrides object may also carry a reserved `vars` key: a map of token
+ * key → **host** custom-property name (e.g. `{ nodeFill: '--accent-soft' }`).
+ * Linked tokens keep their concrete value in `tokens` (so presentation
+ * attributes stay standalone-valid) but stamp their cssVar as
+ * `var(<host-property>, <concrete>)` — the stamped SVG then follows the
+ * host's tokens (light/dark and all) live, with the concrete color as the
+ * fallback outside any host. `vars` never leaks into `tokens`.
+ *
+ * @param {Record<string, Record<string, string>>} themes the component's
+ *   named token tables (must include a `default`)
+ * @param {string} prefix the CSS-variable prefix (e.g. `mm`, `calc`),
+ *   without the leading `--`
+ * The name `'host'` is reserved: it selects the component's own host-var
+ * map wholesale, which is how a consumer asks for "theme me from the page"
+ * without knowing which tokens are linkable. It resolves to
+ * `{ vars: hostVars }`, so a component that passes no `hostVars` simply has
+ * no `'host'` theme and falls back to `default` like any other unknown name.
+ *
+ * @param {string | Record<string, any>} [nameOrOverrides]
+ * @param {Record<string, string>} [hostVars] the component's token key →
+ *   host custom-property map, used when `nameOrOverrides` is `'host'`
+ * @returns {{ name: string, tokens: Record<string, string>, cssVars: Record<string, string> }}
+ */
+export declare function resolveTheme(themes: Record<string, Record<string, string>>, prefix: string, nameOrOverrides?: string | Record<string, any>, hostVars?: Record<string, string>): {
+    name: string;
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+};

package/dist/types/helpers/url.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @file URL safety policies for values written into vnode attributes.
+ *
+ * A URL that reaches an `href`/`src` can execute script (`javascript:`,
+ * `vbscript:`) or smuggle a whole document into the page's origin
+ * (`data:text/html`), so every producer that turns *authored* text into a
+ * vnode must filter it. This module is the one home for that decision.
+ *
+ * There are deliberately **two** policies, because the safe answer depends
+ * on where the URL came from, and picking the wrong one is the trap this
+ * file exists to prevent:
+ *
+ * - {@link sanitizeHref} is an **allow-list**: only the listed schemes and
+ *   anchor/absolute/dot-relative forms survive. Use it for URLs from a
+ *   constrained producer that is expected to emit fully-formed links — a
+ *   Mermaid `click` directive, say. It rejects a bare relative reference
+ *   like `image.png`, which is correct there and wrong for prose.
+ * - {@link sanitizeUrl} is a **deny-list**: it rejects the schemes that can
+ *   execute or impersonate a document and passes everything else,
+ *   including scheme-less relative references. Use it for URLs authored in
+ *   ordinary content — Markdown link destinations and image sources — where
+ *   `docs/guide.md` and `image.png` must keep working.
+ *
+ * Both return the trimmed URL or `null`; a `null` means the caller should
+ * drop the attribute rather than emit an unsafe one.
+ */
+/**
+ * Reject `javascript:`/`data:` and other non-http(s) URLs, returning the
+ * trimmed URL when it is safe or `null` otherwise. An **allow-list**: a
+ * scheme-less relative reference (`image.png`) is rejected too, so reach
+ * for {@link sanitizeUrl} when relative references must survive.
+ *
+ * @param {any} url
+ * @returns {string|null}
+ */
+export declare function sanitizeHref(url: any): string | null;
+/**
+ * Reject only the URL schemes that can execute script or stand in for a
+ * document — `javascript:`, `vbscript:`, `file:` and `data:` other than a
+ * raster image — and pass everything else through, including scheme-less
+ * relative references. The **deny-list** policy for authored content.
+ *
+ * The scheme is read with {@link schemeOf}, which is deliberately not a
+ * literal prefix test — see there for why an embedded tab or NUL does not
+ * get a URL past this.
+ *
+ * @param {any} url
+ * @returns {string|null} the trimmed URL, or `null` when it must be dropped
+ */
+export declare function sanitizeUrl(url: any): string | null;
+/**
+ * Percent-encode a URL for a `href`/`src` attribute.
+ *
+ * Authored text is not a URL: a Markdown destination may hold spaces,
+ * backslashes, backticks or any non-ASCII character, and writing those
+ * into an attribute produces a link a browser resolves differently than
+ * the author wrote — or not at all. This maps them to their UTF-8
+ * percent-encoding while leaving the reserved characters that carry URL
+ * *structure* (`/?:@&=+$,#`) alone.
+ *
+ * An existing `%XX` is passed through rather than re-encoded to `%25XX`,
+ * so a destination an author already encoded survives a round trip; a
+ * lone `%` that does not begin an octet is encoded. Sanitizing and
+ * encoding are separate steps on purpose — encode what
+ * {@link sanitizeUrl} returned, never the other way around, or an
+ * unsafe scheme could hide behind an escape.
+ *
+ * @param {string} url a URL that has already passed a sanitizer
+ * @returns {string} the attribute-ready URL
+ */
+export declare function encodeUrlAttribute(url: string): string;

package/dist/types/html.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file Server-side rendering: vnode JSON → HTML string.
+ *
+ * No DOM, no state — a pure fold over the vnode tree, usable anywhere
+ * (Node, workers, edge runtimes). `on` bindings and `key`s are renderer
+ * instructions and produce no markup; hydration is a client-side
+ * re-render into the same container (see docs/VIEW-FORMAT.md §6). A
+ * `jaren-widget` vnode serializes its host element around the widget's
+ * declarative `ssr` fallback (§7) — still pure, no widget is mounted.
+ */
+/**
+ * Escape text content: `&`, `<`, `>`.
+ * @param {string} text
+ * @returns {string}
+ */
+export declare function escapeText(text: string): string;
+/**
+ * Escape a double-quoted attribute value: `&`, `"`.
+ * @param {string} value
+ * @returns {string}
+ */
+export declare function escapeAttribute(value: string): string;
+export type RenderToStringOptions = {
+    /**
+     * -
+     * Registered widget definitions by name: a `jaren-widget` vnode
+     * serializes its host element around the widget's `ssr(props)` vnode
+     * when the widget is registered and has one, else empty
+     * (VIEW-FORMAT §7).
+     */
+    widgets?: Record<string, {
+        ssr?: (props: any) => any;
+    }>;
+    /**
+     * - Serialize under the SAFE policy
+     * ({@link createSafePolicy}): treat the vnode as untrusted. Disallowed
+     * tags, scripting-sink and inline `on*` properties, injection-shaped tag
+     * and attribute names, and unsafe URLs are stripped, and widget vnodes are
+     * dropped. This is the SAME policy {@link createDomRenderer} applies, so a
+     * document renders to the same safe markup on the server as on the client.
+     */
+    safe?: boolean;
+    /**
+     * - In safe mode, called for everything stripped: a `tag`, a
+     * `prop`, an `on` binding (`event`) or a `widget`.
+     */
+    onUnsafe?: (info: {
+        kind: 'tag' | 'prop' | 'event' | 'widget';
+        name: string;
+    }) => void;
+};
+/**
+ * @typedef {Object} RenderToStringOptions
+ * @property {Record<string, { ssr?: (props: any) => any }>} [widgets] -
+ *   Registered widget definitions by name: a `jaren-widget` vnode
+ *   serializes its host element around the widget's `ssr(props)` vnode
+ *   when the widget is registered and has one, else empty
+ *   (VIEW-FORMAT §7).
+ * @property {boolean} [safe=false] - Serialize under the SAFE policy
+ *   ({@link createSafePolicy}): treat the vnode as untrusted. Disallowed
+ *   tags, scripting-sink and inline `on*` properties, injection-shaped tag
+ *   and attribute names, and unsafe URLs are stripped, and widget vnodes are
+ *   dropped. This is the SAME policy {@link createDomRenderer} applies, so a
+ *   document renders to the same safe markup on the server as on the client.
+ * @property {(info: { kind: 'tag' | 'prop' | 'event' | 'widget', name: string }) => void}
+ *   [onUnsafe] - In safe mode, called for everything stripped: a `tag`, a
+ *   `prop`, an `on` binding (`event`) or a `widget`.
+ */
+/**
+ * Render a vnode JSON document to an HTML string.
+ *
+ * @example
+ * renderToString(['p', { class: 'note' }, 'a < b'])
+ * // -> '<p class="note">a &lt; b</p>'
+ *
+ * @param {any} vnode
+ * @param {RenderToStringOptions} [options]
+ * @returns {string}
+ */
+export declare function renderToString(vnode: any, options?: RenderToStringOptions): string;

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file @jarenjs/view — the vnode JSON contract, the keyed DOM patcher
+ * and the SSR string renderer. See README.md and docs/VIEW-FORMAT.md.
+ */
+export { EMPTY_PROPS, WIDGET_TAG, h, isTextNode, isElementNode, isSkippedNode, isSameNode, isWidgetNode, propsOf, keyOf, childrenOf, } from './vnode.js';
+export { createDomRenderer, styleToString, } from './dom.js';
+export { renderToString, escapeText, escapeAttribute, } from './html.js';
+export { createSafePolicy, } from './safe.js';

package/dist/types/safe.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @file The safe render policy: one decision surface for untrusted vnodes,
+ * shared by the DOM renderer and the SSR serializer so the two can never
+ * disagree about what is safe.
+ *
+ * **Why this exists.** A vnode is plain JSON, and the published grammar
+ * ([`jaren-vnode.schema.json`](../schemas/jaren-vnode.schema.json)) proves a
+ * document is a well-formed *interface* — it does not prove the document is
+ * *safe to render*. The default (trusted) renderer writes any DOM property a
+ * node has, including `innerHTML` and inline `on*` handlers, and the SSR
+ * serializer trusts the tag and attribute *names* it is given. For a
+ * source-authored view that is exactly right — it is the equivalent of
+ * writing the DOM by hand. For a view that arrives from somewhere you do not
+ * control — a tenant, a remote service, a language model — it is not: a
+ * schema-valid document can still carry `['div', { innerHTML: '<img
+ * onerror=…>' }]` or a tag spelled `div><script>`.
+ *
+ * Schema validation is a structural gate, not a sanitizer. This module is the
+ * sanitizer. Pass `{ safe: true }` to {@link createDomRenderer} or
+ * {@link renderToString} and every element flows through the decisions here:
+ *
+ *  - **Tags** must be on an allow-list of known-inert HTML and SVG elements.
+ *    `script`, `iframe`, `object`, `style`, `link`, `foreignObject` and the
+ *    rest are dropped, and so is any tag whose *name* is not a bare
+ *    identifier — which is what closes structural injection through the tag
+ *    (`'div><img src=x onerror=alert(1)'`).
+ *  - **Property names** must be bare identifiers too (closing attribute-name
+ *    injection like `'x onfocus'`), must not begin with `on` (no inline
+ *    handlers), and must not be a known scripting sink (`innerHTML`,
+ *    `outerHTML`, `srcdoc`, …).
+ *  - **URL attributes** (`href`, `src`, `action`, …) are filtered through the
+ *    deny-list {@link sanitizeUrl}, so `javascript:` and a document-carrying
+ *    `data:` are dropped while ordinary links survive.
+ *  - **Inline `style`** is dropped when it carries the classic CSS vectors
+ *    (`expression(`, or a `url()` with a script scheme).
+ *  - **Event bindings** (`on`) are dropped: an untrusted document must not be
+ *    able to bind the host's application actions. Safe-mode views are
+ *    display-oriented by construction.
+ *
+ * The policy is a set of pure decisions. The DOM renderer and the SSR
+ * serializer call the *same* functions, which is what guarantees the client
+ * and the server neutralize an attack identically.
+ */
+/** A tag or property name that is a bare identifier: a letter, then letters,
+ * digits or hyphens. No spaces, `>`, `=`, `/`, colons or quotes — the
+ * characters every structural-injection payload needs. */
+declare const RE_SAFE_NAME: RegExp;
+/**
+ * The HTML elements a user interface legitimately renders. An allow-list, not
+ * a deny-list, because a deny-list silently admits the next dangerous element
+ * a browser adds. Document structure (`html`, `head`, `body`, `title`),
+ * script and style carriers (`script`, `style`, `link`, `meta`, `base`,
+ * `noscript`, `template`), and document-embedding elements (`iframe`,
+ * `object`, `embed`, `frame`, `frameset`, `portal`) are all absent by design.
+ */
+declare const SAFE_HTML_TAGS: Set<string>;
+/**
+ * The SVG drawing subset. `foreignObject` is excluded — it re-enters HTML and
+ * would reopen every vector above — and so are `script` and the event-bearing
+ * SMIL elements.
+ */
+declare const SAFE_SVG_TAGS: Set<string>;
+/** Property names denied outright: the sinks that PARSE their value as HTML.
+ * `textContent`/`innerText` are deliberately absent — they set text, which a
+ * browser escapes, so they are not injection vectors. Compared
+ * case-insensitively. */
+declare const DANGEROUS_PROPS: Set<string>;
+/** Attributes whose value is a single URL, filtered through the deny-list
+ * sanitizer. Compared case-insensitively. */
+declare const URL_ATTRS: Set<string>;
+/** Attributes whose value is a URL *list*: `srcset` is comma-separated
+ * `url descriptor` candidates, `ping` is a whitespace-separated URL list.
+ * Running the whole string through a single-URL check would miss an unsafe
+ * candidate after the first, so each is parsed and every URL is sanitized. */
+declare const URL_LIST_ATTRS: Set<string>;
+export type SafePolicy = {
+    /**
+     * - The tag to render, or
+     * `null` to drop the element and its subtree.
+     */
+    tag: (tag: string) => string | null;
+    /**
+     * - The name/value to write, `{ name, value: null }` to clear an
+     * existing attribute (a sanitized-away URL, a dangerous style), or `null` to
+     * drop the property entirely (a rejected name).
+     */
+    prop: (name: string, value: any) => {
+        name: string;
+        value: any;
+    } | null;
+    /**
+     * - Whether `on` bindings are stripped (always
+     * true for the default policy; the renderers read this to skip the `on`
+     * path in safe mode).
+     */
+    dropsEvents: boolean;
+};
+/**
+ * @typedef {Object} SafePolicy
+ * @property {(tag: string) => string | null} tag - The tag to render, or
+ *   `null` to drop the element and its subtree.
+ * @property {(name: string, value: any) => { name: string, value: any } | null}
+ *   prop - The name/value to write, `{ name, value: null }` to clear an
+ *   existing attribute (a sanitized-away URL, a dangerous style), or `null` to
+ *   drop the property entirely (a rejected name).
+ * @property {boolean} dropsEvents - Whether `on` bindings are stripped (always
+ *   true for the default policy; the renderers read this to skip the `on`
+ *   path in safe mode).
+ */
+/**
+ * Build the default safe policy. Stateless and cheap; a renderer builds one
+ * per `safe: true` and hands the *same* object to every element it renders.
+ *
+ * The policy is a set of **pure decisions** — it neither writes nor reports.
+ * The renderer owns `onUnsafe` and reports at the point it acts on a
+ * rejection, which is what lets it report the strips a policy never sees (an
+ * `on` binding, a widget) with one contract.
+ * @returns {SafePolicy}
+ */
+export declare function createSafePolicy(): SafePolicy;
+export { SAFE_HTML_TAGS, SAFE_SVG_TAGS, DANGEROUS_PROPS, URL_ATTRS, URL_LIST_ATTRS, RE_SAFE_NAME, };

package/dist/types/vnode.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @file The Jaren vnode contract — the JSON vocabulary for user interfaces.
+ *
+ * A vnode is a plain JSON value, designed to be the *output* of a JSLT
+ * stylesheet (`@jarenjs/json/jslt`) the way HTML is the output of XSLT:
+ *
+ *  - text:    a `string` or a `number` (rendered as `String(value)`)
+ *  - element: an array whose first item is a string tag:
+ *             `[tag, props?, ...children]`
+ *  - list:    an array whose first item is NOT a string — spliced into the
+ *             parent's children in place (the natural shape of a JSLT
+ *             `[{ "$apply": ... }]` body)
+ *  - skipped: `null`, `undefined`, `true` and `false` render nothing
+ *             (so `{"$if": ...}` bodies compose without wrappers)
+ *
+ * The second item of an element is its props object when it is a plain
+ * object; otherwise it is the first child. Recognized special props:
+ *
+ *  - `key`   — reconciliation identity for keyed children (never rendered)
+ *  - `on`    — `{ [eventType]: binding }`; the binding is opaque JSON handed
+ *              to the renderer's `onEvent` hook (in `@jarenjs/app`: an
+ *              action name or `{ "action": name, "with": payload }`)
+ *  - `style` — a CSS string or an object of declarations
+ *
+ * Everything in this module is allocation-light and does no validation
+ * beyond shape dispatch: the vnode grammar is published as JSON Schema in
+ * `schemas/jaren-vnode.schema.json` for validating untrusted documents.
+ */
+/** Frozen empty props object shared by all prop-less elements. */
+export declare const EMPTY_PROPS: Readonly<{}>;
+/**
+ * The reserved widget tag (VIEW-FORMAT §7). A valid custom-element name,
+ * so a renderer that predates the widget vocabulary degrades to an inert,
+ * harmless element — and the dash makes collision with real HTML tags
+ * impossible. (`$widget` is impossible: in query/JSLT rule bodies a
+ * string leaf starting with `$` is a path expression.)
+ */
+export declare const WIDGET_TAG = "jaren-widget";
+export type VNodeJson = string | number | boolean | null | undefined | VNodeElement | VNodeJson[];
+export type VNodeElement = Array<any>;
+/**
+ * A vnode JSON value.
+ * @typedef {string | number | boolean | null | undefined | VNodeElement | VNodeJson[]} VNodeJson
+ */
+/**
+ * An element vnode: `[tag, props?, ...children]`.
+ * @typedef {Array<any>} VNodeElement
+ */
+/**
+ * Is this vnode a text node (string or finite number)?
+ * @param {any} vnode
+ * @returns {vnode is string | number}
+ */
+export declare function isTextNode(vnode: any): vnode is string | number;
+/**
+ * Is this vnode an element (`[tag, ...]` with a string tag)?
+ * @param {any} vnode
+ * @returns {vnode is VNodeElement}
+ */
+export declare function isElementNode(vnode: any): vnode is VNodeElement;
+/**
+ * Is this value skipped by the renderer (`null`/`undefined`/booleans)?
+ * @param {any} vnode
+ * @returns {boolean}
+ */
+export declare function isSkippedNode(vnode: any): boolean;
+/**
+ * Is this vnode a widget node (`["jaren-widget", props]`, VIEW-FORMAT §7)?
+ * @param {any} vnode
+ * @returns {vnode is VNodeElement}
+ */
+export declare function isWidgetNode(vnode: any): vnode is VNodeElement;
+/**
+ * The props of an element vnode; `EMPTY_PROPS` when it has none.
+ * @param {VNodeElement} vnode
+ * @returns {Record<string, any>}
+ */
+export declare function propsOf(vnode: VNodeElement): Record<string, any>;
+/**
+ * The reconciliation key of an element vnode, or `undefined`.
+ * @param {any} vnode
+ * @returns {string | number | undefined}
+ */
+export declare function keyOf(vnode: any): string | number | undefined;
+/**
+ * The renderable children of an element vnode as a flat array: nested
+ * lists are spliced in place, skipped values are dropped.
+ * @param {VNodeElement} vnode
+ * @returns {VNodeJson[]}
+ */
+export declare function childrenOf(vnode: VNodeElement): VNodeJson[];
+/**
+ * Convenience element constructor for JavaScript-side views and tests —
+ * produces the same JSON an authored stylesheet would.
+ *
+ * @example
+ * h('li', { key: 7, class: 'todo' }, 'Buy milk')
+ * // -> ['li', { key: 7, class: 'todo' }, 'Buy milk']
+ *
+ * @param {string} tag
+ * @param {Record<string, any>} [props]
+ * @param {...any} children
+ * @returns {VNodeElement}
+ */
+export declare function h(tag: string, props?: Record<string, any>, ...children: any[]): VNodeElement;
+/**
+ * Two vnodes are "the same node" for reconciliation when a patch in place
+ * is possible: both text, or elements with equal tag and equal key.
+ * @param {VNodeJson} a
+ * @param {VNodeJson} b
+ * @returns {boolean}
+ */
+export declare function isSameNode(a: VNodeJson, b: VNodeJson): boolean;