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

package/dist/runtime/machine/fsm/machine.js

@@ -0,0 +1,248 @@
+import { batch, signal, untrack } from "../../core/signal.js";
+// src/runtime/machine/fsm/machine.ts
+/**
+* The state machine core: a config-first FSM, forked from @xstate/fsm 2.1.0
+* (MIT, © Stately, https://github.com/statelyai/xstate).
+*
+* The machine is HEADLESS: state, transitions, and its own arguments. It
+* knows nothing about props, markup, or the DOM.
+*
+* Why fork rather than depend: the package is correct, tiny, MIT, and the
+* last stable was published in 2023 — a frozen base is a solid foundation
+* and a poor dependency. This fork adapts it to this runtime's needs and
+* keeps the config shape agents and the studio know:
+*
+*   const machine = createMachine({
+*     initial: "idle",
+*     context: { value: [] },
+*     states: {
+*       idle: { on: {
+*         TOGGLE: [
+*           { cond: "isOpen", actions: [{ assign: "collapse" }] },
+*           { actions: [{ assign: "expand" }] },
+*         ],
+*       } },
+*     },
+*   }, { conds: {...}, assigns: {...}, actions: {...} });
+*
+* Transition resolution is PURE (`machine.transition`), and `interpret`
+* executes the resolved actions. The delta from upstream, all deliberate:
+*
+* 1. **Named conds and assigns.** `cond: "name"` resolves from
+*    `implementations.conds`; `{ assign: "name" }` from
+*    `implementations.assigns`. Upstream allows only inline functions, which
+*    puts code inside the config — the config is meant to be data for the
+*    studio's visualizer, test derivation, and agent authoring. Assigns are
+*    pure context transforms, so naming them keeps the whole config
+*    serializable with a lookup table of reviewed pure functions beside it.
+* 2. **Per-field signals.** `interpret` backs `state.value` and each field of
+*    `state.context` with an `alien-signals` signal updated inside `batch()`.
+* 3. **No status enum beyond stopped.** Scope disposal owns teardown;
+*    `stop()` is what `dispose()` calls.
+*/
+const INIT = { type: "xstate.init" };
+function toEvent(event) {
+	return event;
+}
+function stateOf(value, context) {
+	return {
+		value,
+		context,
+		matches: (v) => v === value
+	};
+}
+/**
+* Whether a value is a list of transitions. `Array.isArray` does not
+* narrow a readonly array, so the test is named.
+*/
+function isList(value) {
+	return Array.isArray(value);
+}
+const EMPTY = [];
+function normalize(entry) {
+	if (entry === void 0) return EMPTY;
+	return (isList(entry) ? entry : [entry]).map((candidate) => typeof candidate === "string" ? {
+		target: candidate,
+		cond: void 0,
+		assign: void 0
+	} : {
+		target: candidate.target,
+		cond: candidate.cond,
+		assign: candidate.assign
+	});
+}
+function isMatch(candidate, ctx, event) {
+	return candidate.cond === void 0 || candidate.cond(ctx, event);
+}
+/**
+* Apply a transition's context writes, in order. Each write sees the
+* context the previous one left, so a chain reads what the chain wrote.
+*/
+function fold(assigns, startContext, event) {
+	if (assigns === void 0) return startContext;
+	let context = startContext;
+	for (const entry of assigns) {
+		const assign = "assign" in entry ? entry.assign : entry;
+		context = {
+			...context,
+			...assign(context, event)
+		};
+	}
+	return context;
+}
+function createMachine(spec) {
+	const compile = (on) => {
+		const table = /* @__PURE__ */ new Map();
+		for (const [name, entry] of Object.entries(on ?? {})) table.set(name, normalize(entry));
+		return table;
+	};
+	const config = {
+		...spec.id === void 0 ? {} : { id: spec.id },
+		initial: spec.initial,
+		context: spec.context,
+		...spec.on === void 0 ? {} : { on: spec.on },
+		states: spec.states
+	};
+	const rootTable = compile(spec.on);
+	const stateTables = /* @__PURE__ */ new Map();
+	for (const [stateName, stateDef] of Object.entries(spec.states)) stateTables.set(stateName, compile(stateDef.on));
+	const initial = fold(config.states[config.initial]?.entry, config.context ?? {}, INIT);
+	return {
+		config,
+		fields: spec.fields ?? {},
+		initialState: {
+			value: config.initial,
+			context: initial,
+			matches: (v) => v === config.initial
+		},
+		transition(stateOrValue, eventOrType) {
+			const event = toEvent(eventOrType);
+			const from = typeof stateOrValue === "string" ? stateOf(stateOrValue, config.context ?? {}) : stateOrValue;
+			const current = from.value;
+			const ctx = from.context;
+			const stateDef = config.states[current];
+			const name = event.type;
+			const first = stateTables.get(current)?.get(name) ?? EMPTY;
+			const second = rootTable.get(name) ?? EMPTY;
+			for (let tier = 0; tier < 2; tier++) {
+				const list = tier === 0 ? first : second;
+				for (let i = 0; i < list.length; i++) {
+					const candidate = list[i];
+					const { target, assign } = candidate;
+					if (!isMatch(candidate, ctx, event)) continue;
+					if (target === void 0) return {
+						value: current,
+						context: fold(assign === void 0 ? void 0 : isList(assign) ? assign : [assign], ctx, event),
+						matches: (v) => v === current
+					};
+					const nextDef = config.states[target];
+					const context = fold(stateDef?.exit, ctx, event);
+					const written = fold(assign === void 0 ? void 0 : isList(assign) ? assign : [assign], context, event);
+					return {
+						value: target,
+						context: fold(nextDef?.entry, written, event),
+						matches: (v) => v === target
+					};
+				}
+			}
+			return stateOf(current, ctx);
+		}
+	};
+}
+function interpret(machine) {
+	let rawState = machine.initialState.value;
+	let rawContext = { ...machine.initialState.context };
+	let stopped = false;
+	const stateSig = signal(rawState);
+	const fieldSignals = /* @__PURE__ */ new Map();
+	const reactiveContext = {};
+	const ensureField = (key, initialValue) => {
+		let sig = fieldSignals.get(key);
+		if (sig !== void 0) return sig;
+		sig = signal(initialValue);
+		fieldSignals.set(key, sig);
+		Object.defineProperty(reactiveContext, key, {
+			enumerable: true,
+			configurable: true,
+			get() {
+				return sig();
+			},
+			set(next) {
+				const rec = rawContext;
+				if (!Object.is(rec[key], next)) {
+					rec[key] = next;
+					sig(next);
+				}
+			}
+		});
+		return sig;
+	};
+	for (const [key, val] of Object.entries(rawContext)) ensureField(key, val);
+	const commitState = (nextValue, nextContext) => {
+		batch(() => {
+			if (nextValue !== rawState) {
+				rawState = nextValue;
+				stateSig(nextValue);
+			}
+			const prevRec = rawContext;
+			const nextRec = nextContext;
+			rawContext = { ...nextContext };
+			for (const key of Object.keys(nextRec)) {
+				const val = nextRec[key];
+				const sig = fieldSignals.get(key);
+				if (sig === void 0) ensureField(key, val);
+				else if (!Object.is(prevRec[key], val)) sig(val);
+			}
+		});
+	};
+	const stateView = {
+		get value() {
+			return stateSig();
+		},
+		get context() {
+			return reactiveContext;
+		},
+		matches: (v) => stateSig() === v
+	};
+	const service = {
+		setContext(patch) {
+			commitState(rawState, {
+				...rawContext,
+				...patch
+			});
+		},
+		send(event) {
+			if (stopped) return;
+			const next = untrack(() => machine.transition({
+				value: rawState,
+				context: rawContext,
+				matches: (v) => v === rawState
+			}, event));
+			commitState(next.value, next.context);
+		},
+		start(next) {
+			stopped = false;
+			if (next !== void 0) {
+				const value = typeof next === "string" ? next : next.value;
+				const context = typeof next === "string" ? machine.initialState.context : next.context;
+				const seeded = fold(machine.config.states[value]?.entry, context, INIT);
+				commitState(value, seeded);
+			} else commitState(machine.initialState.value, machine.initialState.context);
+			return service;
+		},
+		stop() {
+			stopped = true;
+			return service;
+		},
+		get state() {
+			return stateView;
+		},
+		get stopped() {
+			return stopped;
+		}
+	};
+	return service;
+}
+export { createMachine, interpret };
+
+//# sourceMappingURL=machine.js.map

package/dist/runtime/math/index.d.ts

@@ -0,0 +1,2 @@
+import { clampValue, closestIndex, getNextStepValue, getPercentValue, getPreviousStepValue, getValuePercent, getValueRanges, isInteractive, round10, snapValueToStep } from "./numbers.js";
+export { clampValue, closestIndex, getNextStepValue, getPercentValue, getPreviousStepValue, getValuePercent, getValueRanges, isInteractive, round10, snapValueToStep };

package/dist/runtime/math/index.js

@@ -0,0 +1 @@
+export { clampValue, closestIndex, getNextStepValue, getPercentValue, getPreviousStepValue, getValuePercent, getValueRanges, isInteractive, round10, snapValueToStep } from "./numbers.js";

package/dist/runtime/math/numbers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Value math: pure functions over numbers and arrays, typed to return
+ * `number` (never `number | undefined`).
+ *
+ * Vendored from `@zag-js/utils` (`dist/number.mjs`, MIT) with two changes:
+ * the NaN-guard is explicit (`nan` → 0 is preserved — a missing value is
+ * the bound, not an error), and every function declares its real return
+ * type so call sites need no `as number`. The logic is byte-identical;
+ * only the types are tighter. If the upstream changes, re-vendor and
+ * re-run this file's tests.
+ *
+ * Plus the generic shapes components kept re-deriving: `closestIndex`
+ * (later wins ties — thumb stacking needs determinism), `round10`, and
+ * `isInteractive` (structural: any context with the two flags).
+ *
+ * Rules for this module: pure functions only (no machine, DOM, or signal
+ * imports), total (no `null` returns — a missing value is the bound), and
+ * deterministic (same inputs, same outputs — testable without a machine).
+ */
+/** Clamp into range; NaN reads as the lower bound. */
+export declare function clampValue(v: number, vmin: number, vmax: number): number;
+/** The position of a value in its range, as 0..1. */
+export declare function getValuePercent(v: number, vmin: number, vmax: number): number;
+/** The value at a percent of a stepped range, clamped. */
+export declare function getPercentValue(p: number, vmin: number, vmax: number, step: number): number;
+/** Snap to the step grid with float-precision correction, clamped to the
+ * largest valid step (not just the max — `max` may not sit on the grid). */
+export declare function snapValueToStep(v: number, vmin: number, vmax: number, step: number): number;
+/** Per-thumb clamp windows from neighbors plus the gap. */
+export declare function getValueRanges(vs: readonly number[], vmin: number, vmax: number, gap: number): readonly {
+  readonly min: number;
+  readonly max: number;
+  readonly value: number;
+}[];
+/** Step the thumb at `index` up, clamped to its neighbors. */
+export declare function getNextStepValue(index: number, ctx: {
+  readonly values: readonly number[];
+  readonly min: number;
+  readonly max: number;
+  readonly step: number;
+}): readonly number[];
+/** Step the thumb at `index` down, clamped to its neighbors. */
+export declare function getPreviousStepValue(index: number, ctx: {
+  readonly values: readonly number[];
+  readonly min: number;
+  readonly max: number;
+  readonly step: number;
+}): readonly number[];
+/** Later thumbs win ties: deterministic under stacking. */
+export declare function closestIndex(values: readonly number[], pointValue: number): number;
+/** Round to 10 decimal places: float-arithmetic residue cleanup. */
+export declare function round10(value: number): number;
+/** An interactive context: neither read-only nor disabled. Structural —
+ * any context with the two flags qualifies, no base type required. */
+export declare function isInteractive<C extends {
+  readonly readOnly?: boolean;
+  readonly disabled?: boolean;
+}>(context: C): boolean;

package/dist/runtime/math/numbers.js

@@ -0,0 +1,115 @@
+// src/runtime/math/numbers.ts
+/**
+* Value math: pure functions over numbers and arrays, typed to return
+* `number` (never `number | undefined`).
+*
+* Vendored from `@zag-js/utils` (`dist/number.mjs`, MIT) with two changes:
+* the NaN-guard is explicit (`nan` → 0 is preserved — a missing value is
+* the bound, not an error), and every function declares its real return
+* type so call sites need no `as number`. The logic is byte-identical;
+* only the types are tighter. If the upstream changes, re-vendor and
+* re-run this file's tests.
+*
+* Plus the generic shapes components kept re-deriving: `closestIndex`
+* (later wins ties — thumb stacking needs determinism), `round10`, and
+* `isInteractive` (structural: any context with the two flags).
+*
+* Rules for this module: pure functions only (no machine, DOM, or signal
+* imports), total (no `null` returns — a missing value is the bound), and
+* deterministic (same inputs, same outputs — testable without a machine).
+*/
+const { abs, floor, max, min, pow, round, sign } = Math;
+const nan = (v) => Number.isNaN(v) ? 0 : v;
+/** Clamp into range; NaN reads as the lower bound. */
+function clampValue(v, vmin, vmax) {
+	return min(max(nan(v), vmin), vmax);
+}
+/** The position of a value in its range, as 0..1. */
+function getValuePercent(v, vmin, vmax) {
+	return (nan(v) - vmin) / (vmax - vmin);
+}
+function roundValue(v, vmin, step) {
+	return round((nan(v) - vmin) / step) * step + vmin;
+}
+/** The value at a percent of a stepped range, clamped. */
+function getPercentValue(p, vmin, vmax, step) {
+	return clampValue(roundValue(p * (vmax - vmin) + vmin, vmin, step), vmin, vmax);
+}
+function roundToStepPrecision(v, step) {
+	let rv = v;
+	const ss = step.toString();
+	const pi = ss.indexOf(".");
+	const p = pi >= 0 ? ss.length - pi : 0;
+	if (p > 0) {
+		const pw = pow(10, p);
+		rv = round(rv * pw) / pw;
+	}
+	return rv;
+}
+/** Snap to the step grid with float-precision correction, clamped to the
+* largest valid step (not just the max — `max` may not sit on the grid). */
+function snapValueToStep(v, vmin, vmax, step) {
+	const min2 = vmin != null ? Number(vmin) : 0;
+	const max2 = Number(vmax);
+	const remainder = (v - min2) % step;
+	let snapped = abs(remainder) * 2 >= step ? v + sign(remainder) * (step - abs(remainder)) : v - remainder;
+	snapped = roundToStepPrecision(snapped, step);
+	if (!Number.isNaN(min2) && snapped < min2) snapped = min2;
+	else if (!Number.isNaN(max2) && snapped > max2) {
+		const stepsInRange = floor((max2 - min2) / step);
+		const largestValidStep = min2 + stepsInRange * step;
+		snapped = stepsInRange <= 0 || largestValidStep < min2 ? max2 : largestValidStep;
+	}
+	return roundToStepPrecision(snapped, step);
+}
+/** Per-thumb clamp windows from neighbors plus the gap. */
+function getValueRanges(vs, vmin, vmax, gap) {
+	return vs.map((v, i) => ({
+		min: i === 0 ? vmin : (vs[i - 1] ?? vmin) + gap,
+		max: i === vs.length - 1 ? vmax : (vs[i + 1] ?? vmax) - gap,
+		value: v
+	}));
+}
+function getMinValueAtIndex(index, values, vmin) {
+	return index === 0 ? vmin : values[index - 1] ?? vmin;
+}
+function getMaxValueAtIndex(index, values, vmax) {
+	return index === values.length - 1 ? vmax : values[index + 1] ?? vmax;
+}
+/** Step the thumb at `index` up, clamped to its neighbors. */
+function getNextStepValue(index, ctx) {
+	const next = [...ctx.values];
+	next[index] = snapValueToStep((ctx.values[index] ?? ctx.min) + ctx.step, getMinValueAtIndex(index, ctx.values, ctx.min), getMaxValueAtIndex(index, ctx.values, ctx.max), ctx.step);
+	return next;
+}
+/** Step the thumb at `index` down, clamped to its neighbors. */
+function getPreviousStepValue(index, ctx) {
+	const next = [...ctx.values];
+	next[index] = snapValueToStep((ctx.values[index] ?? ctx.min) - ctx.step, getMinValueAtIndex(index, ctx.values, ctx.min), getMaxValueAtIndex(index, ctx.values, ctx.max), ctx.step);
+	return next;
+}
+/** Later thumbs win ties: deterministic under stacking. */
+function closestIndex(values, pointValue) {
+	let closest = 0;
+	let distance = Math.abs((values[0] ?? 0) - pointValue);
+	for (let i = 1; i < values.length; i += 1) {
+		const next = Math.abs((values[i] ?? 0) - pointValue);
+		if (next <= distance) {
+			closest = i;
+			distance = next;
+		}
+	}
+	return closest;
+}
+/** Round to 10 decimal places: float-arithmetic residue cleanup. */
+function round10(value) {
+	return Math.round(value * 1e10) / 1e10;
+}
+/** An interactive context: neither read-only nor disabled. Structural —
+* any context with the two flags qualifies, no base type required. */
+function isInteractive(context) {
+	return context.readOnly !== true && context.disabled !== true;
+}
+export { clampValue, closestIndex, getNextStepValue, getPercentValue, getPreviousStepValue, getValuePercent, getValueRanges, isInteractive, round10, snapValueToStep };
+
+//# sourceMappingURL=numbers.js.map

package/dist/runtime/props.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The prop grammar's coercion, owned by the syntax.
+ *
+ * One implementation serves every boundary: the parser calls in at build
+ * time to turn a declared prop's text into a value, and the element bridge
+ * builds its attribute parsers here. No other module parses a prop's text
+ * form — the scalar and object-array branches below are the only ones.
+ *
+ * The module is deliberately pure (no signals, no DOM) so the runtime can
+ * depend on it without a cycle back.
+ */
+/**
+ * bool: presence (`""`, `"true"`, absent) is true, `"false"` is false,
+ * anything else is the fallback.
+ */
+/**
+ * The initial-value twin of a prop: `value` -> `defaultValue`.
+ *
+ * The convention is the framework's: a host that writes `value` owns the
+ * value, and a host that writes only `defaultValue` seeds it. Resolving
+ * the twin before the machine's factory is called means the machine's
+ * arguments are the live values, and the machine never sees the twin.
+ */
+export declare function defaultTwin(prop: string): string;
+/**
+ * Resolve the twins in a prop bag: for each `defaultX`, the prop `X`
+ * falls back to it.
+ *
+ * The fallback applies only when the host did not write `X`: a host
+ * that writes the live prop owns the value, and a host that writes only
+ * the twin seeds it. The bag is read live, so the resolution is a copy
+ * — the host's own bag is never mutated.
+ */
+export declare function resolveTwins(props: Record<string, unknown>, authored?: (name: string) => boolean): Record<string, unknown>;
+/**
+ * Whether a value is a plain record: an object, not null, not an array.
+ * The components' props arrive as records; the framework's grammar
+ * speaks in records, so the test belongs here.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function coerceBool(raw: string | null | undefined, fallback: boolean | undefined): boolean | undefined;
+/** string: absent is empty. */
+export declare function coerceString(raw: string | null | undefined): string;
+/** int: absent or malformed is the fallback, never NaN. */
+export declare function coerceInt(raw: string | null | undefined, fallback: number | undefined): number | undefined;
+/**
+ * string[] from scope text: a bare comma list, or a bracketed one (`[a, b]`).
+ * The grammar reserves top-level commas for prop separation, so the brackets
+ * are optional.
+ */
+export declare function coerceList(raw: string | null | undefined): string[];
+/** A JSON-encoded array; malformed or non-array is the fallback. */
+export declare function coerceJsonArray(raw: string | null | undefined, fallback: unknown[]): unknown[];
+/**
+ * Object-array items: plain objects survive, the rest drop; declared `int`
+ * fields coerce, malformed becoming `undefined`.
+ */
+export declare function coerceObjectArrayItems(value: unknown, fallback: unknown[], fields?: readonly {
+  readonly name: string;
+  readonly type: string;
+}[]): Record<string, unknown>[];

package/dist/runtime/props.js

@@ -0,0 +1,113 @@
+// src/runtime/props.ts
+/**
+* The prop grammar's coercion, owned by the syntax.
+*
+* One implementation serves every boundary: the parser calls in at build
+* time to turn a declared prop's text into a value, and the element bridge
+* builds its attribute parsers here. No other module parses a prop's text
+* form — the scalar and object-array branches below are the only ones.
+*
+* The module is deliberately pure (no signals, no DOM) so the runtime can
+* depend on it without a cycle back.
+*/
+/**
+* bool: presence (`""`, `"true"`, absent) is true, `"false"` is false,
+* anything else is the fallback.
+*/
+/**
+* The initial-value twin of a prop: `value` -> `defaultValue`.
+*
+* The convention is the framework's: a host that writes `value` owns the
+* value, and a host that writes only `defaultValue` seeds it. Resolving
+* the twin before the machine's factory is called means the machine's
+* arguments are the live values, and the machine never sees the twin.
+*/
+function defaultTwin(prop) {
+	return `default${prop.charAt(0).toUpperCase()}${prop.slice(1)}`;
+}
+/**
+* Resolve the twins in a prop bag: for each `defaultX`, the prop `X`
+* falls back to it.
+*
+* The fallback applies only when the host did not write `X`: a host
+* that writes the live prop owns the value, and a host that writes only
+* the twin seeds it. The bag is read live, so the resolution is a copy
+* — the host's own bag is never mutated.
+*/
+function resolveTwins(props, authored) {
+	const out = { ...props };
+	for (const key of Object.keys(props)) {
+		if (!key.startsWith("default")) continue;
+		const twin = key.charAt(7).toLowerCase() + key.slice(8);
+		if (authored !== void 0 && authored(twin)) continue;
+		out[twin] = props[key];
+	}
+	return out;
+}
+/**
+* Whether a value is a plain record: an object, not null, not an array.
+* The components' props arrive as records; the framework's grammar
+* speaks in records, so the test belongs here.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function coerceBool(raw, fallback) {
+	if (raw === null || raw === void 0 || raw === "" || raw === "true") return true;
+	if (raw === "false") return false;
+	return fallback;
+}
+/** string: absent is empty. */
+function coerceString(raw) {
+	return raw ?? "";
+}
+/** int: absent or malformed is the fallback, never NaN. */
+function coerceInt(raw, fallback) {
+	if (raw === null || raw === void 0) return fallback;
+	const n = parseInt(raw, 10);
+	return Number.isNaN(n) ? fallback : n;
+}
+/**
+* string[] from scope text: a bare comma list, or a bracketed one (`[a, b]`).
+* The grammar reserves top-level commas for prop separation, so the brackets
+* are optional.
+*/
+function coerceList(raw) {
+	if (raw === null || raw === void 0 || raw === "") return [];
+	const trimmed = raw.trim();
+	return (trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed).split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+}
+/** A JSON-encoded array; malformed or non-array is the fallback. */
+function coerceJsonArray(raw, fallback) {
+	if (raw === null || raw === void 0 || raw === "") return fallback;
+	try {
+		const parsed = JSON.parse(raw);
+		return Array.isArray(parsed) ? parsed : fallback;
+	} catch {
+		return fallback;
+	}
+}
+/**
+* Object-array items: plain objects survive, the rest drop; declared `int`
+* fields coerce, malformed becoming `undefined`.
+*/
+function coerceObjectArrayItems(value, fallback, fields) {
+	if (!Array.isArray(value)) return fallback;
+	const out = [];
+	for (const item of value) {
+		if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+		const obj = { ...item };
+		if (fields) {
+			for (const field of fields) if (field.type === "int") {
+				const v = obj[field.name];
+				const n = typeof v === "number" ? v : parseInt(String(v), 10);
+				obj[field.name] = Number.isNaN(n) ? void 0 : n;
+			}
+		}
+		out.push(obj);
+	}
+	return out;
+}
+export { coerceBool, coerceInt, coerceJsonArray, coerceList, coerceObjectArrayItems, coerceString, defaultTwin, isRecord, resolveTwins };
+
+//# sourceMappingURL=props.js.map

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

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+import { OwnerScope } from "../core/signal.js";
+import { Factory, Handle } from "./table.js";
+/** Turns an attribute's string into the value the component reads. */
+export type AttributeParser = (value: string | null) => unknown;
+/**
+ * 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.
+ */
+export declare const attrParsers: {
+  readonly bool: (value: string | null) => boolean | undefined;
+  readonly string: (value: string | null) => string;
+  readonly int: (value: string | null) => number | undefined;
+  readonly "string[]": (value: string | null) => string[];
+  readonly "object[]": (value: string | null) => unknown[];
+};
+export interface ElementSpec {
+  /** Property names. Each becomes a live read on `ctx.props`. */
+  props?: readonly string[];
+  /**
+   * Attribute name to parser. Declaring one puts it in `observedAttributes`,
+   * so writing the attribute updates the same prop a property write would.
+   */
+  attributes?: Readonly<Record<string, AttributeParser>>;
+  /**
+   * Builds the component. Runs inside the element's scope on every connection,
+   * so an `effect` created here dies with the element.
+   */
+  build(context: BuildContext): void;
+}
+export interface BuildContext {
+  /** The element itself. The bridge's root accessor wants exactly this. */
+  readonly el: HTMLElement;
+  /** The declared props. Every read is a live read of the current value. */
+  readonly props: Readonly<Record<string, unknown>>;
+  /** The scope for this connection. Pass it to `createMachine`. */
+  readonly scope: OwnerScope;
+  /** Resolve a handle to its instance, walking up the scope chain. */
+  resolve<T>(handle: Handle): T | undefined;
+  /** Instantiate (on first call) and register a handle in this scope. */
+  watch<T>(handle: Handle, factory: Factory<T>, commands?: readonly string[], name?: string): T;
+  /** Consume a handle from the nearest ancestor that provides it. */
+  consume<T>(handle: Handle): T | undefined;
+  /**
+   * Whether a prop was written by the host (property or attribute) as
+   * opposed to left at its coerced default. Machines use it to tell a
+   * controlled value from a seed.
+   */
+  authored(name: string): boolean;
+}
+/**
+ * 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.
+ */
+export declare function writeProp(el: Element, name: string, value: unknown): boolean;
+/** 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. */
+export declare function scopeOf(node: Element): OwnerScope | undefined;
+/** 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. */
+export declare function runInElement<T>(el: Element, fn: () => T): T;
+/**
+ * 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.
+ */
+export declare function uniqueId(tag: string): string;
+/**
+ * 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.
+ */
+export declare function define(tag: string, spec: ElementSpec): void;