@spinjs/components 0.1.0-preview.2 → 0.2.0-alpha.1

package/dist/runtime/scope/element.js

@@ -0,0 +1,226 @@
+import { scope, signal } from "../core/signal.js";
+import { createScopeTable } from "./table.js";
+import { coerceBool, coerceInt, coerceJsonArray, coerceObjectArrayItems, coerceString } from "../props.js";
+// src/runtime/scope/element.ts
+/**
+* Custom elements: a scope per connection, and props that survive both sides.
+*
+* Props are properties, not attributes — an attribute is a string and a machine
+* needs objects. Attributes are supported for the primitives that are strings,
+* and land in the same live prop a property write would.
+*/
+/**
+* The scope grammar's attribute parsers, one per declared prop type. The
+* plugin emits an `attributes` map from these so an attribute written at
+* any time — a framework's string prop, or a later setAttribute — lands in
+* the same live prop a property write reaches. Kept beside the element
+* definition that consumes them, not beside the grammar that mirrors them.
+*/
+const attrParsers = {
+	bool: (value) => coerceBool(value, false),
+	string: (value) => coerceString(value),
+	int: (value) => coerceInt(value, void 0),
+	"string[]": (value) => coerceJsonArray(value, []),
+	"object[]": (value) => coerceJsonArray(value, [])
+};
+/**
+* Props the host actually WROTE — as a property set or an attribute — as
+* opposed to coerced defaults. This is the distinction controlled
+* components live on: a `defaultOpen` seeds, an authored `open` alternates.
+* Without it every declared prop reads as "set", because coercion
+* materializes a default for all of them, and a machine can never tell the
+* two apart. A controlled/uncontrolled pair does this at the prop layer
+* (`value` vs `defaultValue`); the element is where it lands here.
+*/
+const authoredProps = /* @__PURE__ */ new WeakMap();
+/** Each element's connection scope, so work that runs later — a binding
+* re-applying after the element left the build — still enters it. */
+const elementScopes = /* @__PURE__ */ new WeakMap();
+/** Per-element prop writers, registered at construction. `writeProp` reaches
+* the element's own store even for names no accessor was declared for. */
+const writers = /* @__PURE__ */ new WeakMap();
+/**
+* Write a prop through the element's store, marking it authored. Returns
+* false when `el` is not a Spin element (or predates its upgrade), so the
+* caller falls back to a plain property write the constructor picks up.
+*/
+function writeProp(el, name, value) {
+	const write = writers.get(el);
+	if (write === void 0) return false;
+	write(name, value);
+	return true;
+}
+/** The scope of the element that owns `node`: a recipe's markup renders
+* inside its custom element, so a bag spread on an inner node belongs to that
+* element's scope. */
+function scopeOf(node) {
+	for (let current = node; current !== null; current = current.parentElement) {
+		const owner = elementScopes.get(current);
+		if (owner !== void 0) return owner;
+	}
+}
+/** Runs `fn` inside the owning element's scope, so what it creates is owned
+* and disposed with the element. Outside an element (a detached fragment)
+* there is no scope to enter, and `fn` runs as-is. */
+function runInElement(el, fn) {
+	const owner = scopeOf(el);
+	return owner === void 0 ? fn() : owner.run(fn);
+}
+function authoredFor(el) {
+	let set = authoredProps.get(el);
+	if (!set) authoredProps.set(el, set = /* @__PURE__ */ new Set());
+	return set;
+}
+/** Per-tag counters for generated element ids. Page-load scoped: uniqueness
+* is what part-id scoping needs, stability across loads is not. */
+const idCounters = /* @__PURE__ */ new Map();
+/**
+* A unique id for a `tag` instance. Used when the author sets no `id`: the
+* machine scopes part ids (and aria references) by its own id, so two
+* id-less `<spin-accordion>` elements would otherwise share every part id.
+*/
+function uniqueId(tag) {
+	const next = (idCounters.get(tag) ?? 0) + 1;
+	idCounters.set(tag, next);
+	return `${tag}-${next}`;
+}
+/**
+* Registers `tag` as a custom element built by `spec`.
+*
+* `build` runs inside the element's scope on every connection, so every effect
+* it creates dies with the element.
+*/
+function define(tag, spec) {
+	const propNames = spec.props ?? [];
+	const parsers = spec.attributes ?? {};
+	const stores = /* @__PURE__ */ new WeakMap();
+	function storeFor(el) {
+		let store = stores.get(el);
+		if (!store) stores.set(el, store = /* @__PURE__ */ new Map());
+		return store;
+	}
+	function seedProps(el) {
+		const store = storeFor(el);
+		for (const name of propNames) if (!store.has(name)) store.set(name, signal(void 0));
+	}
+	function propFor(el, name) {
+		const store = storeFor(el);
+		let value = store.get(name);
+		if (!value) store.set(name, value = signal(void 0));
+		return value;
+	}
+	function propsFor(el) {
+		return new Proxy({}, {
+			get: (_target, key) => typeof key === "string" ? propFor(el, key)() : void 0,
+			has: (_target, key) => typeof key === "string" && storeFor(el).has(key),
+			ownKeys: () => {
+				const store = storeFor(el);
+				const out = [];
+				for (const name of propNames) {
+					const sig = store.get(name);
+					if (sig !== void 0 && sig() !== void 0) out.push(name);
+				}
+				for (const name of store.keys()) if (!propNames.includes(name)) out.push(name);
+				return out;
+			},
+			getOwnPropertyDescriptor: () => ({
+				configurable: true,
+				enumerable: true
+			})
+		});
+	}
+	class Component extends HTMLElement {
+		#scope;
+		#table;
+		constructor() {
+			super();
+			for (const name of propNames) {
+				const own = Object.getOwnPropertyDescriptor(this, name);
+				if (own === void 0 || own.get !== void 0 || own.set !== void 0) continue;
+				const value = own.value;
+				delete this[name];
+				authoredFor(this).add(name);
+				propFor(this, name)(coerceWrite(name, value));
+			}
+			writers.set(this, (name, next) => {
+				authoredFor(this).add(name);
+				propFor(this, name)(coerceWrite(name, next));
+			});
+		}
+		connectedCallback() {
+			if (this.#scope !== void 0) return;
+			if (this.style.display === "") {
+				const view = this.ownerDocument.defaultView;
+				if ((typeof view?.getComputedStyle === "function" ? view.getComputedStyle(this).display : "inline") === "inline") this.style.display = "block";
+			}
+			const parentScope = this.parentElement !== null ? scopeOf(this.parentElement) : void 0;
+			const owner = scope(parentScope);
+			this.#scope = owner;
+			elementScopes.set(this, owner);
+			const table = createScopeTable(owner, this);
+			this.#table = table;
+			owner.run(() => {
+				seedProps(this);
+				spec.build({
+					el: this,
+					props: propsFor(this),
+					scope: owner,
+					resolve: (handle) => table.resolve(handle),
+					watch: (handle, factory, commands, name) => {
+						const peers = table.namesOf(handle);
+						if ((name ?? "") === "" && peers.length > 0 && !peers.includes("")) throw new Error(`[spin] ${tag}: two bindings share one machine; pass a binding name`);
+						return table.watch(handle, factory, commands, name);
+					},
+					consume: (handle) => table.consume(handle),
+					authored: (name) => authoredFor(this).has(name)
+				});
+			});
+		}
+		disconnectedCallback() {
+			queueMicrotask(() => {
+				if (this.isConnected) return;
+				this.#scope?.dispose();
+				this.#scope = void 0;
+				this.#table = void 0;
+			});
+		}
+		attributeChangedCallback(name, _previous, next) {
+			authoredFor(this).add(name);
+			propFor(this, name)(parsers[name]?.(next));
+		}
+	}
+	/**
+	* The property-write boundary. A host's write coerces through the runtime's
+	* prop grammar, so the store holds grammar-shaped values whichever boundary
+	* the host wrote through. String writes take the component's own parser (the
+	* attribute path's grammar, verbatim); a host-written object or array takes
+	* the object-array branch: plain objects survive, everything else is dropped.
+	*/
+	function coerceWrite(name, next) {
+		const parser = parsers[name];
+		if (parser === void 0) return next;
+		if (typeof next === "string") return parser(next);
+		if (parser !== attrParsers["object[]"]) return next;
+		return coerceObjectArrayItems(next, []);
+	}
+	for (const name of propNames) Object.defineProperty(Component.prototype, name, {
+		get() {
+			return propFor(this, name)();
+		},
+		set(next) {
+			authoredFor(this).add(name);
+			propFor(this, name)(coerceWrite(name, next));
+		},
+		configurable: true,
+		enumerable: true
+	});
+	Object.defineProperty(Component, "observedAttributes", {
+		value: Object.keys(parsers),
+		configurable: true
+	});
+	if (customElements.get(tag) !== void 0) return;
+	customElements.define(tag, Component);
+}
+export { attrParsers, define, runInElement, scopeOf, uniqueId, writeProp };
+
+//# sourceMappingURL=element.js.map

package/dist/runtime/scope/table.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Scope-local instance table with DOM-ancestor chain lookup and dispose-on-scope-death.
+ *
+ * Each element-connection scope owns a `Map<handle, instance>`. Lookup walks
+ * the DOM ancestor chain (element → parentElement → …), so a nested element
+ * consumes the nearest ancestor's instance. First `watch` instantiates via
+ * the registered factory; scope dispose destroys instances created in it.
+ *
+ * Handle = imported object reference (machine-def module export), never a
+ * string. No central registry; the module graph is the registry.
+ */
+import { OwnerScope } from "../core/signal.js";
+/** A handle identifies a machine definition. It is the imported object reference, never a string. */
+export type Handle = object;
+/** Creates an instance from a handle. */
+export type Factory<T> = () => T;
+/** What an app controller can do with a component. */
+export interface SpinController {
+  /** Imperative calls, keyed by the name the element installs them under. */
+  readonly commands: Readonly<Record<string, (...args: never[]) => unknown>>;
+  /** Reactive reads, one thunk per observable field. */
+  readonly state: Readonly<Record<string, () => unknown>>;
+}
+export interface ScopeTable {
+  /** Look up a handle, walking up the DOM ancestor chain. Does not instantiate. */
+  resolve<T>(handle: Handle): T | undefined;
+  /** Instantiate (on first call) and register a handle in this element's scope. */
+  watch<T>(handle: Handle, factory: Factory<T>, commands?: readonly string[], name?: string): T;
+  /** Consume a handle by walking up the DOM ancestor ScopeTable chain; throws when absent. */
+  consume<T>(handle: Handle): T;
+  /** Return the SpinController view for a handle (or the primary handle if omitted). */
+  controller(handle?: Handle): SpinController | undefined;
+  /** Destroy all instances created in this scope. */
+  dispose(): void;
+}
+/** The controller view of a component's api: its non-function members as
+ * reactive reads, and the declared commands as calls.
+ *
+ * The field list is a reflection of the api, not a declaration — a field the
+ * api stops carrying stops being observable, with no list to keep in step. */
+export declare function controllerView(api: object, commands?: readonly string[]): SpinController;
+/**
+ * Creates a scope table for the given owner scope, optionally bound to an
+ * element for DOM-ancestor chain lookup.
+ *
+ * The table is registered with the scope via `own()`, so when the scope is
+ * disposed, all instances created in it are destroyed.
+ */
+export declare function createScopeTable(owner: OwnerScope, el?: Element): ScopeTable;
+/** Consume a handle from `el`'s ScopeTable chain; throws when no provider is found. */
+export declare function consume<T>(el: Element, handle: Handle): T;
+/** The controller `el` provides, or the nearest ancestor's when `el` is not connected. */
+export declare function controllerOf(el: Element, handle?: Handle): SpinController | undefined;
+/** Register a controller on `el`'s ScopeTable, creating a table when `el` is a plain host element. */
+export declare function provideController(el: Element, build: () => SpinController, handle?: Handle): void;

package/dist/runtime/scope/table.js

@@ -0,0 +1,174 @@
+import { scope } from "../core/signal.js";
+// src/runtime/scope/table.ts
+/**
+* Scope-local instance table with DOM-ancestor chain lookup and dispose-on-scope-death.
+*
+* Each element-connection scope owns a `Map<handle, instance>`. Lookup walks
+* the DOM ancestor chain (element → parentElement → …), so a nested element
+* consumes the nearest ancestor's instance. First `watch` instantiates via
+* the registered factory; scope dispose destroys instances created in it.
+*
+* Handle = imported object reference (machine-def module export), never a
+* string. No central registry; the module graph is the registry.
+*/
+/** Maps each element to its connection ScopeTable. */
+const elementTables = /* @__PURE__ */ new WeakMap();
+function apiOf(value) {
+	if (value !== null && typeof value === "object" && "api" in value) return value.api;
+	return value;
+}
+/** The controller view of a component's api: its non-function members as
+* reactive reads, and the declared commands as calls.
+*
+* The field list is a reflection of the api, not a declaration — a field the
+* api stops carrying stops being observable, with no list to keep in step. */
+function controllerView(api, commands) {
+	const record = api;
+	const state = {};
+	for (const key of Object.keys(record)) if (typeof record[key] !== "function") state[key] = () => record[key];
+	const calls = {};
+	for (const name of commands ?? []) {
+		const method = record[name];
+		if (typeof method === "function") calls[name] = method;
+	}
+	return {
+		commands: calls,
+		state
+	};
+}
+/**
+* Creates a scope table for the given owner scope, optionally bound to an
+* element for DOM-ancestor chain lookup.
+*
+* The table is registered with the scope via `own()`, so when the scope is
+* disposed, all instances created in it are destroyed.
+*/
+function createScopeTable(owner, el) {
+	const instances = /* @__PURE__ */ new Map();
+	let primary;
+	function named(handle) {
+		let byName = instances.get(handle);
+		if (byName === void 0) instances.set(handle, byName = /* @__PURE__ */ new Map());
+		return byName;
+	}
+	function firstEntry(byName) {
+		if (byName === void 0) return void 0;
+		return byName.get("") ?? byName.values().next().value;
+	}
+	owner.own(() => {
+		if (el !== void 0) elementTables.delete(el);
+		for (const byName of instances.values()) for (const [, instance] of byName) instance.dispose?.();
+		instances.clear();
+		primary = void 0;
+	});
+	function findLocal(handle) {
+		return firstEntry(instances.get(handle));
+	}
+	function findAncestor(handle) {
+		for (let current = el?.parentElement ?? null; current !== null; current = current.parentElement) {
+			const found = elementTables.get(current)?.entry(handle);
+			if (found !== void 0) return found;
+		}
+	}
+	function resolve(handle) {
+		return (findLocal(handle) ?? findAncestor(handle))?.api;
+	}
+	function consume(handle) {
+		const found = resolve(handle);
+		if (found === void 0) throw new Error(`[spin] consume: no provider found for ${handle.name ?? "machine"}`);
+		return found;
+	}
+	function watch(handle, factory, commands, name) {
+		const key = name ?? "";
+		const byName = named(handle);
+		const existing = byName.get(key);
+		if (existing !== void 0) return existing.value;
+		const value = factory();
+		const entry = {
+			value,
+			api: apiOf(value),
+			commands,
+			primary: primary === void 0,
+			dispose: getDispose(value)
+		};
+		byName.set(key, entry);
+		primary ??= {
+			handle,
+			name: key
+		};
+		return value;
+	}
+	function entry(handle) {
+		return findLocal(handle);
+	}
+	function hasNamed(handle, name) {
+		return instances.get(handle)?.has(name) ?? false;
+	}
+	function namesOf(handle) {
+		return [...instances.get(handle)?.keys() ?? []];
+	}
+	function controller(handle) {
+		const target = handle ?? primary?.handle;
+		const found = target === void 0 ? void 0 : findLocal(target) ?? (handle === void 0 ? void 0 : findAncestor(handle));
+		if (found === void 0) return void 0;
+		const api = found.api;
+		if (api !== null && typeof api === "object" && "commands" in api && "state" in api) return api;
+		return controllerView(found.api ?? {}, found.commands);
+	}
+	function dispose() {
+		if (el !== void 0) elementTables.delete(el);
+		for (const byName of instances.values()) for (const [, instance] of byName) instance.dispose?.();
+		instances.clear();
+		primary = void 0;
+	}
+	function getDispose(value) {
+		if (typeof value !== "object" || value === null) return void 0;
+		if (!("dispose" in value)) return void 0;
+		const disposeFn = value.dispose;
+		if (typeof disposeFn !== "function") return void 0;
+		return () => disposeFn();
+	}
+	const table = {
+		resolve,
+		watch,
+		consume,
+		controller,
+		dispose,
+		entry,
+		hasNamed,
+		namesOf
+	};
+	if (el !== void 0) elementTables.set(el, table);
+	return table;
+}
+/** Consume a handle from `el`'s ScopeTable chain; throws when no provider is found. */
+function consume(el, handle) {
+	for (let current = el; current !== null; current = current.parentElement) {
+		const found = elementTables.get(current)?.consume(handle);
+		if (found !== void 0) return found;
+	}
+	throw new Error(`[spin] consume: no provider found for ${handle.name ?? "machine"}`);
+}
+/** The controller `el` provides, or the nearest ancestor's when `el` is not connected. */
+function controllerOf(el, handle) {
+	for (let current = el; current !== null; current = current.parentElement) {
+		const found = elementTables.get(current)?.controller(handle);
+		if (found !== void 0) return found;
+		if (handle === void 0) return void 0;
+	}
+}
+/** Register a controller on `el`'s ScopeTable, creating a table when `el` is a plain host element. */
+function provideController(el, build, handle) {
+	let table = elementTables.get(el);
+	if (table === void 0) table = createScopeTable(scope(), el);
+	const key = handle ?? build;
+	if (table.resolve(key) !== void 0) return;
+	const built = build();
+	table.watch(key, () => ({
+		api: built,
+		dispose: void 0
+	}), Object.keys(built.commands));
+}
+export { consume, controllerOf, controllerView, createScopeTable, provideController };
+
+//# sourceMappingURL=table.js.map

package/dist/runtime/syntax/braces.d.ts

@@ -0,0 +1,2 @@
+export declare function matchBrace(source: string, start: number, end: number): number;
+export declare function skipQuoted(source: string, i: number, end: number): number;

package/dist/runtime/syntax/braces.js

@@ -0,0 +1,35 @@
+// src/runtime/syntax/braces.ts
+function matchBrace(source, start, end) {
+	let depth = 0;
+	let j = start;
+	while (j < end) {
+		const c = source[j];
+		if (c === "\"" || c === "'" || c === "`") {
+			j = skipQuoted(source, j, end);
+			continue;
+		}
+		if (c === "{") depth++;
+		else if (c === "}") {
+			depth--;
+			if (depth === 0) return j;
+		}
+		j++;
+	}
+	return end;
+}
+function skipQuoted(source, i, end) {
+	const q = source[i];
+	let j = i + 1;
+	while (j < end) {
+		if (source[j] === "\\") {
+			j += 2;
+			continue;
+		}
+		if (source[j] === q) return j + 1;
+		j++;
+	}
+	return end;
+}
+export { matchBrace, skipQuoted };
+
+//# sourceMappingURL=braces.js.map

package/dist/runtime/syntax/classes.d.ts

@@ -0,0 +1,22 @@
+/** The class strings a markup file names.
+ *
+ * A class attribute is static text or an expression. A static one names
+ * its utilities outright. An expression names them in its string
+ * literals — `class={"bg-surface" + (slider.dragging ? " scale-110" : "")}`
+ * names two — and the vocabulary check has to see through it, or a
+ * misspelled utility in a dynamic class is a dead rule nobody catches.
+ *
+ * The literals are collected, not evaluated: an expression's shape is not
+ * the compiler's business, only which utilities it names.
+ */
+import { Attr, AttrValue, ComponentIr, Node } from "./ir.js";
+/** The class tokens an attribute names. A variant group is one token
+ * that names several (`data-[open]:(bg-x text-y)`), so the groups are
+ * expanded before the tokens are split. */
+export declare function classTokensOf(value: AttrValue): string[];
+/** Every class token the markup names. */
+export declare function classTokens(ir: ComponentIr): string[];
+/** The class attribute of a node, if it has one. */
+export declare function classAttrOf(node: Extract<Node, {
+  kind: "element";
+}>): Attr | undefined;

package/dist/runtime/syntax/classes.js

@@ -0,0 +1,119 @@
+import { expandVariantGroups } from "./expand-groups.js";
+// src/runtime/syntax/classes.ts
+/** The string literals an expression holds. */
+function literalsOf(expression) {
+	const out = [];
+	const pattern = /"([^"]*)"|'([^']*)'|`([^`]*)`/g;
+	let match;
+	while ((match = pattern.exec(expression)) !== null) {
+		const value = match[1] ?? match[2] ?? match[3];
+		if (value !== void 0 && value.length > 0) out.push(value);
+	}
+	return out;
+}
+/** The class tokens an attribute names. A variant group is one token
+* that names several (`data-[open]:(bg-x text-y)`), so the groups are
+* expanded before the tokens are split. */
+function classTokensOf(value) {
+	const out = [];
+	const push = (text) => {
+		for (const token of expandVariantGroups(text).split(/\s+/)) if (token.length > 0) out.push(token);
+	};
+	if (value.kind === "static") {
+		push(value.value);
+		return out;
+	}
+	if (/^\s*[[{]/.test(value.expr)) {
+		for (const part of listPartsOf(value.expr)) if (part.kind === "string") push(part.value);
+		else for (const key of part.keys) push(key);
+		return out;
+	}
+	for (const literal of literalsOf(value.expr)) push(literal);
+	return out;
+}
+/** The parts of a class attribute's value: the strings it holds and the
+* keys of the objects it holds. */
+function listPartsOf(literal) {
+	const out = [];
+	const parts = splitTop(literal.trim().replace(/^\[/, "").replace(/\]$/, ""));
+	for (const part of parts) {
+		const text = part.trim();
+		if (text.startsWith("\"") || text.startsWith("'")) {
+			out.push({
+				kind: "string",
+				value: text.slice(1, -1)
+			});
+			continue;
+		}
+		if (text.startsWith("{")) out.push({
+			kind: "object",
+			keys: objectKeysOf(text)
+		});
+	}
+	return out;
+}
+/** The parts of a value, at its top level. */
+function splitTop(body) {
+	const out = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i <= body.length; i++) {
+		const ch = body[i];
+		if (ch === "{" || ch === "[" || ch === "(") depth++;
+		else if (ch === "}" || ch === "]" || ch === ")") depth--;
+		else if (ch === "," && depth === 0 || i === body.length) {
+			const part = body.slice(start, i).trim();
+			if (part.length > 0) out.push(part);
+			start = i + 1;
+		}
+	}
+	return out;
+}
+/** The keys of an object literal, at its top level. */
+function objectKeysOf(literal) {
+	const out = [];
+	let depth = 0;
+	let start = 0;
+	const body = literal.trim().replace(/^\{/, "").replace(/\}$/, "");
+	for (let i = 0; i <= body.length; i++) {
+		const ch = body[i];
+		if (ch === "{" || ch === "[" || ch === "(") depth++;
+		else if (ch === "}" || ch === "]" || ch === ")") depth--;
+		else if (ch === "," && depth === 0 || i === body.length) {
+			const entry = body.slice(start, i).trim();
+			start = i + 1;
+			if (entry.length === 0) continue;
+			const colon = entry.indexOf(":");
+			const key = (colon < 0 ? entry : entry.slice(0, colon)).trim();
+			const name = /^"([^"]*)"$|^'([^']*)'$/.exec(key);
+			if (name !== null) out.push(name[1] ?? name[2] ?? "");
+		}
+	}
+	return out.filter((name) => name.length > 0);
+}
+/** Every class token a node names, in the document's order. */
+function tokensOfNode(node, out) {
+	if (node.kind === "text") return;
+	if (node.kind === "for") {
+		for (const child of node.body) tokensOfNode(child, out);
+		return;
+	}
+	for (const attr of node.attrs) {
+		if (attr.name !== "class") continue;
+		for (const token of classTokensOf(attr.value)) out.push(token);
+	}
+	for (const child of node.children) tokensOfNode(child, out);
+}
+/** Every class token the markup names. */
+function classTokens(ir) {
+	const out = [];
+	for (const node of ir.nodes) tokensOfNode(node, out);
+	return out;
+}
+/** The class attribute of a node, if it has one. */
+function classAttrOf(node) {
+	return node.attrs.find((attr) => attr.name === "class");
+}
+export { classAttrOf, classTokens, classTokensOf };
+
+//# sourceMappingURL=classes.js.map

package/dist/runtime/syntax/display.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One token of example markup, as the code viewer reads it.
+ *
+ * Self-contained on purpose: the reference demonstrates the styling surface,
+ * so a syntax highlighter from a dependency would be a second stylesheet the
+ * theme cannot reach. The tokenizer is a single pass over the string and
+ * nothing else — no grammar, no recovery, no recursion.
+ */
+export type CodeTokenType = "tag" | "attr" | "string" | "comment" | "punct" | "expr" | "text";
+export interface CodeToken {
+  readonly type: CodeTokenType;
+  readonly value: string;
+}
+/**
+ * Example HTML, tokenized: tags, attribute names, string values, comments and
+ * the text between them. Everything the markup spells is preserved exactly,
+ * whitespace included, because the code view is the markup a consumer copies.
+ */
+export declare function tokenizeHtml(html: string): CodeToken[];
+/**
+ * Example HTML, formatted. Idempotent: formatting what was formatted
+ * changes nothing, because it replaces whitespace-only runs and nothing
+ * else.
+ */
+export declare function formatExampleHtml(html: string): string;