@sigil-dev/runtime 0.7.4 → 0.7.6

package/index.ts

@@ -1,468 +1,618 @@
-export { Boundary } from "./boundary";
-
-export const SIGIL_SAFE = Symbol.for("sigil.safe");
-export class SafeHtml {
-	[SIGIL_SAFE] = true;
-	constructor(public v: string) {}
-	toString() {
-		return this.v;
-	}
-}
-
-
-let currentEffect: (() => void) | null = null;
-let currentDeps: Set<Set<() => void>> | null = null;
-
-let batchDepth = 0;
-const pendingEffects = new Set<() => void>();
-
-const targetDepsMap = new WeakMap<
-	object,
-	Map<string | symbol, Set<() => void>>
->();
-
-function getDeps(target: object, key: string | symbol): Set<() => void> {
-	let deps = targetDepsMap.get(target);
-	if (!deps) {
-		deps = new Map();
-		targetDepsMap.set(target, deps);
-	}
-	let set = deps.get(key);
-	if (!set) {
-		set = new Set();
-		deps.set(key, set);
-	}
-	return set;
-}
-
-function track(target: object, key: string | symbol) {
-	if (currentEffect && currentDeps) {
-		const deps = getDeps(target, key);
-		deps.add(currentEffect);
-		currentDeps.add(deps); // Set, deduplicates automatically
-	}
-}
-
-function trigger(target: object, key: string | symbol) {
-	const deps = targetDepsMap.get(target);
-	if (!deps) return;
-	const set = deps.get(key);
-	if (!set) return;
-	for (const fn of [...set]) {
-		if (batchDepth > 0) pendingEffects.add(fn);
-		else fn();
-	}
-}
-
-const proxyCache = new WeakMap<object, object>();
-const reactiveTargets = new WeakSet<object>();
-
-function createReactiveProxy<T extends object>(target: T): T {
-	const existing = proxyCache.get(target);
-	if (existing) return existing as T;
-
-	const proxy = new Proxy(target, {
-		get(target, key, receiver) {
-			if (key === "set") {
-				return (newValue: T) => {
-					const oldKeys = new Set(Object.keys(target));
-					const newKeys = new Set(Object.keys(newValue));
-					for (const k of oldKeys) {
-						if (!newKeys.has(k)) {
-							delete (target as any)[k];
-							trigger(target, k);
-						}
-					}
-					for (const k of newKeys) {
-						(target as any)[k] = (newValue as any)[k];
-						trigger(target, k);
-					}
-					if (Array.isArray(target)) {
-						trigger(target, "length");
-					}
-				};
-			}
-
-			if (key === "peek") {
-				return () => target;
-			}
-
-			if (typeof key === "symbol") {
-				return Reflect.get(target, key, receiver);
-			}
-
-			track(target, key);
-			const value = target[key as keyof T];
-
-			if (typeof value === "object" && value !== null) {
-				return createReactiveProxy(value);
-			}
-
-			return value;
-		},
-
-		set(target, key, newValue, receiver) {
-			const oldValue = target[key as keyof T];
-			const result = Reflect.set(target, key, newValue, receiver);
-			if (oldValue !== newValue) {
-				trigger(target, key as string | symbol);
-				if (
-					Array.isArray(target) &&
-					typeof key === "string" &&
-					!Number.isNaN(Number(key))
-				) {
-					trigger(target, "length");
-				}
-			}
-			return result;
-		},
-
-		deleteProperty(target, key) {
-			const result = Reflect.deleteProperty(target, key);
-			trigger(target, key as string | symbol);
-			return result;
-		},
-	});
-
-	proxyCache.set(target, proxy);
-	reactiveTargets.add(target);
-	return proxy as T;
-}
-
-// ─── createSignal (branches on type) ───
-
-export type Signal<T> = {
-	(): T;
-	set: (next: T) => void;
-	peek: () => T;
-};
-
-export function batch(fn: () => void) {
-	batchDepth++;
-	fn();
-	batchDepth--;
-	if (batchDepth === 0) {
-		// biome-ignore lint/suspicious/useIterableCallbackReturn: effects returing cleanup is intended
-		pendingEffects.forEach((e) => e());
-		pendingEffects.clear();
-	}
-}
-
-export function createSignal<T>(initial: T): Signal<T> {
-	if (typeof initial === "object" && initial !== null) {
-		const proxy = createReactiveProxy(initial);
-		const getter = () => proxy;
-		getter.set = (next: T) => (proxy as any).set(next);
-		getter.peek = () => initial;
-		return getter;
-	}
-
-	const subs = new Set<() => void>();
-	let value = initial;
-
-	const getter = () => {
-		if (currentEffect && currentDeps) {
-			subs.add(currentEffect);
-			currentDeps.add(subs);
-		}
-		return value;
-	};
-
-	getter.set = (next: T) => {
-		value = next;
-		for (const fn of [...subs]) {
-			if (batchDepth > 0) pendingEffects.add(fn);
-			else fn();
-		}
-	};
-
-	getter.peek = () => value;
-
-	return getter;
-}
-
-// biome-ignore  lint/suspicious/noConfusingVoidType: please shut up its a weird type
-export function createEffect(fn: () => void | (() => void)): () => void {
-	let cleanup: (() => void) | void;
-	const ownDeps = new Set<Set<() => void>>();
-
-	const effect = () => {
-		if (cleanup) cleanup();
-		for (const depSet of ownDeps) depSet.delete(effect);
-		ownDeps.clear();
-
-		const prevEffect = currentEffect;
-		const prevDeps = currentDeps;
-		currentEffect = effect;
-		currentDeps = ownDeps;
-		try {
-			cleanup = fn();
-		} finally {
-			currentEffect = prevEffect;
-			currentDeps = prevDeps;
-		}
-	};
-
-	effect();
-
-	const dispose = () => {
-		for (const depSet of ownDeps) depSet.delete(effect);
-		ownDeps.clear();
-		if (cleanup) cleanup();
-	};
-
-	((globalThis as any).__sigilEffectScope as (() => void)[] | undefined)?.push(
-		dispose,
-	);
-	return dispose;
-}
-
-/**
- * Run fn() and return a dispose function that tears down every effect
- * created during that call (including effects inside child createMemo calls).
- * Supports nesting: inner scopes don't leak to outer ones.
- */
-export function withEffectScope(fn: () => void): () => void {
-	const prev = (globalThis as any).__sigilEffectScope;
-	const disposers: (() => void)[] = [];
-	(globalThis as any).__sigilEffectScope = disposers;
-	try {
-		fn();
-	} finally {
-		(globalThis as any).__sigilEffectScope = prev;
-	}
-	return () => {
-		for (const d of disposers) d();
-		disposers.length = 0;
-	};
-}
-
-export function createMemo<T>(fn: () => T): Signal<T> {
-	const inner = createSignal<T>(undefined as T);
-	createEffect(() => inner.set(fn()));
-	return inner;
-}
-
-/**
- * Claim an existing element from a hydration pool by tag name, or create a new one.
- * Removes the claimed node from the pool array.
- * When falling back to createElement, appends to parent if provided (SPA mode).
- */
-export function claim(
-	nodes: ChildNode[],
-	tag: string,
-	parent?: Element,
-): Element {
-	for (let i = 0; i < nodes.length; i++) {
-		const node = nodes[i];
-		if (
-			node instanceof Element &&
-			node.tagName.toLowerCase() === tag.toLowerCase()
-		) {
-			nodes.splice(i, 1);
-			return node;
-		}
-	}
-	const el = document.createElement(tag);
-	if (parent) parent.appendChild(el);
-	return el;
-}
-
-/**
- * Claim an existing Text node from a hydration pool, or create a new empty one.
- * Removes the claimed node from the pool array.
- * When falling back to createTextNode, appends to parent if provided (SPA mode).
- */
-export function claimText(nodes: ChildNode[], parent?: Element): Text {
-	for (let i = 0; i < nodes.length; i++) {
-		const node = nodes[i];
-		if (node instanceof Text) {
-			nodes.splice(i, 1);
-			return node;
-		}
-	}
-	const text = document.createTextNode("");
-	if (parent) parent.appendChild(text);
-	return text;
-}
-
-/**
- * Claim an existing Comment node from a hydration pool, or create a new one.
- * Removes the claimed node from the pool array.
- * When falling back to createComment, appends to parent if provided (SPA mode).
- */
-export function claimComment(
-	nodes: ChildNode[],
-	text: string = "",
-	parent?: Element,
-): Comment {
-	for (let i = 0; i < nodes.length; i++) {
-		const node = nodes[i];
-		if (node instanceof Comment && node.data === text) {
-			nodes.splice(i, 1);
-			return node;
-		}
-	}
-	const comment = document.createComment(text);
-	if (parent) parent.appendChild(comment);
-	return comment;
-}
-
-/**
- * Reconcile a list of keyed DOM nodes.
- * anchor.before(node) handles both insert and move natively.
- * @param claimNode - Optional hydration callback. Called with (element, key) for
- *   server-rendered elements removed from the DOM. Returns the element to use,
- *   or null to discard.
- */
-export function reconcile<T>(
-	anchor: Partial<Comment>,
-	keyMap: Map<unknown, Node>,
-	newItems: T[],
-	getKey: (item: T) => unknown,
-	createNode: (item: T) => Node,
-	// is this meant to be unused? claimNode?: (element: Element, key: unknown) => Element | null,
-): void {
-	const newKeys = new Set(newItems.map(getKey));
-
-	// Remove nodes no longer in list (or claim them for hydration)
-	for (const [key, node] of keyMap) {
-		if (!newKeys.has(key)) {
-			node.parentNode?.removeChild(node);
-			keyMap.delete(key);
-		}
-	}
-
-	// Insert/move in order — anchor.before() handles both cases
-	for (const item of newItems) {
-		const key = getKey(item);
-		let node = keyMap.get(key);
-		if (!node) {
-			node = createNode(item);
-			keyMap.set(key, node);
-		}
-		anchor.before?.(node);
-	}
-}
-
-/**
- * Hydrate a keyed list: claim the comment anchor, walk its sibling elements
- * to build a keyMap, then reconcile with signal data.
- *
- * SSR renders items as flat siblings. Hydration claims them by position,
- * builds the keyMap, removes from DOM, then reconcile re-inserts in order.
- */
-export function hydrateKeyedList<T>(
-	nodesVar: ChildNode[],
-	signalItems: T[],
-	getKey: (item: T) => unknown,
-	createNode: (item: T) => Node,
-	parent?: Element,
-): { anchor: Comment; keyMap: Map<unknown, Node> } {
-	// 1. Claim the <!--g--> opening delimiter as anchor
-	const anchor = claimComment(nodesVar, "g", parent);
-
-	// 2. Walk siblings after anchor, collect elements up to <!--/g-->, build keyMap
-	const keyMap = new Map<unknown, Node>();
-	const anchorParent = anchor.parentNode;
-	if (anchorParent && signalItems.length > 0) {
-		const claimed: Element[] = [];
-		let next = anchor.nextSibling;
-		while (next) {
-			const current = next;
-			next = next.nextSibling;
-			// Stop at closing <!--/g--> delimiter and consume it
-			if (current instanceof Comment && current.data === "/g") {
-				current.remove();
-				break;
-			}
-			if (current instanceof Element) {
-				current.remove();
-				claimed.push(current);
-			}
-		}
-		// Map claimed elements to keys by index
-		for (let i = 0; i < claimed.length && i < signalItems.length; i++) {
-			//@ts-expect-error i is always in bounds
-			const key = getKey(signalItems[i]);
-			//@ts-expect-error i is always in bounds
-			keyMap.set(key, claimed[i]);
-		}
-	}
-
-	// 3. Reconcile — keyMap is pre-populated with claimed nodes
-	reconcile(anchor, keyMap, signalItems, getKey, createNode);
-	return { anchor, keyMap };
-}
-
-export function insert(parent: Element, value: unknown): void {
-	if (value === false || value === null || value === undefined) return;
-	if (Array.isArray(value)) {
-		for (const item of value) insert(parent, item);
-		return;
-	}
-	if (value instanceof Node) {
-		parent.appendChild(value);
-		return;
-	}
-	parent.append(String(value));
-}
-
-/**
- * Apply a use: directive to an element.
- * The directive function receives (element, params) and may return a cleanup function.
- * Cleanup runs when the enclosing $effect re-runs or the component is destroyed.
- */
-export type Directive = (node: Element, params: unknown) => void | (() => void);
-
-export function applyDirective(
-	node: Element,
-	directive: Directive | [Directive, unknown],
-): void {
-	const [fn, params] = Array.isArray(directive)
-		? directive
-		: [directive, undefined];
-	const cleanup = fn(node, params);
-	if (typeof cleanup === "function") {
-		createEffect(() => () => cleanup());
-	}
-}
-
-export type ContextKey<T> = symbol & { __type: T };
-
-const clientContextStore = new Map<symbol, unknown>();
-
-let storeProvider: (() => Map<symbol, unknown>) | null = null;
-export function __setStoreProvider(fn: () => Map<symbol, unknown>) {
-	storeProvider = fn;
-}
-
-function getStore(): Map<symbol, unknown> {
-	return storeProvider?.() ?? clientContextStore;
-}
-
-export function createContext<T>(): ContextKey<T> {
-	return Symbol() as ContextKey<T>;
-}
-
-export function setContext<T>(key: ContextKey<T>, value: T): void {
-	getStore().set(key as unknown as symbol, value);
-}
-
-export function getContext<T>(key: ContextKey<T>): T {
-	return getStore().get(key as unknown as symbol) as T;
-}
-
-const _hydrationStack: ChildNode[][] = [];
-
-export function pushHydrationNodes(nodes: ChildNode[]): void {
-    _hydrationStack.push(nodes);
-}
-
-export function popHydrationNodes(): void {
-    _hydrationStack.pop();
-}
-
-export function getHydrationNodes(): ChildNode[] {
-    return _hydrationStack[_hydrationStack.length - 1] ?? [];
-}
+export { Boundary } from "./boundary";
+export { ReactiveMap } from "./reactivity/map.ts";
+export { ReactiveSet } from "./reactivity/set.ts";
+export {
+	linear,
+	easeInQuad,
+	easeOutQuad,
+	easeInOutQuad,
+	easeInCubic,
+	easeOutCubic,
+	easeInOutCubic,
+	easeInQuart,
+	easeOutQuart,
+	easeInOutQuart,
+	easeInQuint,
+	easeOutQuint,
+	easeInOutQuint,
+	easeInSine,
+	easeOutSine,
+	easeInOutSine,
+} from "./easing.ts";
+
+export const SIGIL_SAFE = Symbol.for("sigil.safe");
+export class SafeHtml {
+	[SIGIL_SAFE] = true;
+	constructor(public v: string) {}
+	toString() {
+		return this.v;
+	}
+}
+
+
+let currentEffect: (() => void) | null = null;
+let currentDeps: Set<Set<() => void>> | null = null;
+
+let batchDepth = 0;
+let scheduledFlush = false;
+const pendingEffects = new Set<() => void>();
+const pendingPreEffects = new Set<() => void>();
+
+function flush() {
+	scheduledFlush = false;
+	// biome-ignore lint/suspicious/useIterableCallbackReturn: effects returning cleanup is intended
+	pendingPreEffects.forEach((e) => e());
+	pendingPreEffects.clear();
+	// biome-ignore lint/suspicious/useIterableCallbackReturn: effects returning cleanup is intended
+	pendingEffects.forEach((e) => e());
+	pendingEffects.clear();
+}
+
+function scheduleEffect(fn: () => void) {
+	const target = (fn as any).__sigil_pre
+		? pendingPreEffects
+		: pendingEffects;
+	target.add(fn);
+	if (batchDepth === 0 && !scheduledFlush) {
+		scheduledFlush = true;
+		queueMicrotask(flush);
+	}
+}
+
+const targetDepsMap = new WeakMap<
+	object,
+	Map<string | symbol, Set<() => void>>
+>();
+
+function getDeps(target: object, key: string | symbol): Set<() => void> {
+	let deps = targetDepsMap.get(target);
+	if (!deps) {
+		deps = new Map();
+		targetDepsMap.set(target, deps);
+	}
+	let set = deps.get(key);
+	if (!set) {
+		set = new Set();
+		deps.set(key, set);
+	}
+	return set;
+}
+
+function track(target: object, key: string | symbol) {
+	if (currentEffect && currentDeps) {
+		const deps = getDeps(target, key);
+		deps.add(currentEffect);
+		currentDeps.add(deps); // Set, deduplicates automatically
+	}
+}
+
+function trigger(target: object, key: string | symbol) {
+	const deps = targetDepsMap.get(target);
+	if (!deps) return;
+	const set = deps.get(key);
+	if (!set) return;
+	for (const fn of [...set]) {
+		scheduleEffect(fn);
+	}
+}
+
+const proxyCache = new WeakMap<object, object>();
+const proxyToTarget = new WeakMap<object, object>();
+const reactiveTargets = new WeakSet<object>();
+
+function createReactiveProxy<T extends object>(target: T): T {
+	const existing = proxyCache.get(target);
+	if (existing) return existing as T;
+
+	const proxy = new Proxy(target, {
+		get(target, key, receiver) {
+			if (key === "set") {
+				return (newValue: T) => {
+					const oldKeys = new Set(Object.keys(target));
+					const newKeys = new Set(Object.keys(newValue));
+					for (const k of oldKeys) {
+						if (!newKeys.has(k)) {
+							delete (target as any)[k];
+							trigger(target, k);
+						}
+					}
+					for (const k of newKeys) {
+						(target as any)[k] = (newValue as any)[k];
+						trigger(target, k);
+					}
+					if (Array.isArray(target)) {
+						trigger(target, "length");
+					}
+				};
+			}
+
+			if (key === "peek") {
+				return () => target;
+			}
+
+			if (typeof key === "symbol") {
+				return Reflect.get(target, key, receiver);
+			}
+
+			track(target, key);
+			const value = target[key as keyof T];
+
+			if (typeof value === "object" && value !== null) {
+				return createReactiveProxy(value);
+			}
+
+			return value;
+		},
+
+		set(target, key, newValue, receiver) {
+			const oldValue = target[key as keyof T];
+			const result = Reflect.set(target, key, newValue, receiver);
+			if (oldValue !== newValue) {
+				trigger(target, key as string | symbol);
+				if (
+					Array.isArray(target) &&
+					typeof key === "string" &&
+					!Number.isNaN(Number(key))
+				) {
+					trigger(target, "length");
+				}
+			}
+			return result;
+		},
+
+		deleteProperty(target, key) {
+			const result = Reflect.deleteProperty(target, key);
+			trigger(target, key as string | symbol);
+			return result;
+		},
+	});
+
+	proxyCache.set(target, proxy);
+	proxyToTarget.set(proxy, target);
+	reactiveTargets.add(target);
+	return proxy as T;
+}
+
+// ─── createSignal (branches on type) ───
+
+export type Signal<T> = {
+	(): T;
+	set: (next: T) => void;
+	peek: () => T;
+};
+
+export function batch(fn: () => void) {
+	batchDepth++;
+	fn();
+	batchDepth--;
+	if (batchDepth === 0) {
+		scheduledFlush = false;
+		flush();
+	}
+}
+
+export function tick(): Promise<void> {
+	return new Promise((resolve) => queueMicrotask(resolve));
+}
+
+function createPrimitiveSignal<T>(initial: T): Signal<T> {
+	const subs = new Set<() => void>();
+	let value = initial;
+
+	const getter = () => {
+		if (currentEffect && currentDeps) {
+			subs.add(currentEffect);
+			currentDeps.add(subs);
+		}
+		return value;
+	};
+
+	getter.set = (next: T) => {
+		value = next;
+		for (const fn of [...subs]) {
+			scheduleEffect(fn);
+		}
+	};
+
+	getter.peek = () => value;
+
+	return getter;
+}
+
+export function createSignal<T>(initial: T): Signal<T> {
+	if (typeof initial === "object" && initial !== null) {
+		const proxy = createReactiveProxy(initial);
+		const getter = () => proxy;
+		getter.set = (next: T) => (proxy as any).set(next);
+		getter.peek = () => initial;
+		return getter;
+	}
+
+	return createPrimitiveSignal(initial);
+}
+
+// A1: $state.raw — create signal without Proxy wrapping for objects/arrays
+export function createRawSignal<T>(initial: T): Signal<T> {
+	return createPrimitiveSignal(initial);
+}
+
+// A2: $state.snapshot — deep un-proxy a signal value
+function deepUnproxy<T>(value: T): T {
+	if (typeof value !== "object" || value === null) return value;
+	const raw = proxyToTarget.get(value as object);
+	if (!raw) return value; // not a proxy, return as-is
+	if (Array.isArray(raw)) {
+		return raw.map(deepUnproxy) as T;
+	}
+	const result: Record<string, unknown> = {};
+	for (const key of Object.keys(raw)) {
+		result[key] = deepUnproxy((raw as Record<string, unknown>)[key]);
+	}
+	return result as T;
+}
+
+export function snapshot<T>(value: T): T {
+	return deepUnproxy(value);
+}
+
+// A3: $effect.tracking() — check if inside reactive context
+export function tracking(): boolean {
+	return currentEffect !== null;
+}
+
+// A4: $inspect — dev-only effect logging
+export function createInspectEffect(
+	getValues: () => unknown[],
+	cb?: (vals: unknown[]) => void,
+): void {
+	if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+	createEffect(() => {
+		const vals = getValues();
+		if (cb) cb(vals);
+		else console.log(...vals);
+	});
+}
+
+// A5: $effect.pre — effect that flushes before DOM update
+export function createEffectPre(fn: () => void | (() => void)): () => void {
+	let cleanup: (() => void) | void;
+	const ownDeps = new Set<Set<() => void>>();
+
+	const effect = () => {
+		if (cleanup) cleanup();
+		for (const depSet of ownDeps) depSet.delete(effect);
+		ownDeps.clear();
+
+		const prevEffect = currentEffect;
+		const prevDeps = currentDeps;
+		currentEffect = effect;
+		currentDeps = ownDeps;
+		try {
+			cleanup = fn();
+		} finally {
+			currentEffect = prevEffect;
+			currentDeps = prevDeps;
+		}
+	};
+
+	(effect as any).__sigil_pre = true;
+	effect();
+
+	const dispose = () => {
+		for (const depSet of ownDeps) depSet.delete(effect);
+		ownDeps.clear();
+		if (cleanup) cleanup();
+	};
+
+	((globalThis as any).__sigilEffectScope as (() => void)[] | undefined)?.push(
+		dispose,
+	);
+	return dispose;
+}
+
+// A9: Profiler effect timing (dev)
+export function createProfilerEffect(
+	name: string,
+	fn: () => void | (() => void),
+): () => void {
+	return createEffect(() => {
+		if (typeof process !== "undefined" && process.env.NODE_ENV === "production") {
+			return fn();
+		}
+		const start = performance.now();
+		const cleanup = fn();
+		const end = performance.now();
+		console.log(`[Profiler] ${name}: ${(end - start).toFixed(2)}ms`);
+		return cleanup;
+	});
+}
+
+// biome-ignore  lint/suspicious/noConfusingVoidType: please shut up its a weird type
+export function createEffect(fn: () => void | (() => void)): () => void {
+	let cleanup: (() => void) | void;
+	const ownDeps = new Set<Set<() => void>>();
+
+	const effect = () => {
+		if (cleanup) cleanup();
+		for (const depSet of ownDeps) depSet.delete(effect);
+		ownDeps.clear();
+
+		const prevEffect = currentEffect;
+		const prevDeps = currentDeps;
+		currentEffect = effect;
+		currentDeps = ownDeps;
+		try {
+			cleanup = fn();
+		} finally {
+			currentEffect = prevEffect;
+			currentDeps = prevDeps;
+		}
+	};
+
+	effect();
+
+	const dispose = () => {
+		for (const depSet of ownDeps) depSet.delete(effect);
+		ownDeps.clear();
+		if (cleanup) cleanup();
+	};
+
+	((globalThis as any).__sigilEffectScope as (() => void)[] | undefined)?.push(
+		dispose,
+	);
+	return dispose;
+}
+
+/**
+ * Run fn() and return a dispose function that tears down every effect
+ * created during that call (including effects inside child createMemo calls).
+ * Supports nesting: inner scopes don't leak to outer ones.
+ */
+export function withEffectScope(fn: () => void): () => void {
+	const prev = (globalThis as any).__sigilEffectScope;
+	const disposers: (() => void)[] = [];
+	(globalThis as any).__sigilEffectScope = disposers;
+	try {
+		fn();
+	} finally {
+		(globalThis as any).__sigilEffectScope = prev;
+	}
+	return () => {
+		for (const d of disposers) d();
+		disposers.length = 0;
+	};
+}
+
+export function createMemo<T>(fn: () => T): Signal<T> {
+	const inner = createSignal<T>(undefined as T);
+	createEffect(() => inner.set(fn()));
+	return inner;
+}
+
+/**
+ * Claim an existing element from a hydration pool by tag name, or create a new one.
+ * Removes the claimed node from the pool array.
+ * When falling back to createElement, appends to parent if provided (SPA mode).
+ */
+export function claim(
+	nodes: ChildNode[],
+	tag: string,
+	parent?: Element,
+): Element {
+	for (let i = 0; i < nodes.length; i++) {
+		const node = nodes[i];
+		if (
+			node instanceof Element &&
+			node.tagName.toLowerCase() === tag.toLowerCase()
+		) {
+			nodes.splice(i, 1);
+			return node;
+		}
+	}
+	const el = document.createElement(tag);
+	if (parent) parent.appendChild(el);
+	return el;
+}
+
+/**
+ * Claim an existing Text node from a hydration pool, or create a new empty one.
+ * Removes the claimed node from the pool array.
+ * When falling back to createTextNode, appends to parent if provided (SPA mode).
+ */
+export function claimText(nodes: ChildNode[], parent?: Element): Text {
+	for (let i = 0; i < nodes.length; i++) {
+		const node = nodes[i];
+		if (node instanceof Text) {
+			nodes.splice(i, 1);
+			return node;
+		}
+	}
+	const text = document.createTextNode("");
+	if (parent) parent.appendChild(text);
+	return text;
+}
+
+/**
+ * Claim an existing Comment node from a hydration pool, or create a new one.
+ * Removes the claimed node from the pool array.
+ * When falling back to createComment, appends to parent if provided (SPA mode).
+ */
+export function claimComment(
+	nodes: ChildNode[],
+	text: string = "",
+	parent?: Element,
+): Comment {
+	for (let i = 0; i < nodes.length; i++) {
+		const node = nodes[i];
+		if (node instanceof Comment && node.data === text) {
+			nodes.splice(i, 1);
+			return node;
+		}
+	}
+	const comment = document.createComment(text);
+	if (parent) parent.appendChild(comment);
+	return comment;
+}
+
+/**
+ * Reconcile a list of keyed DOM nodes.
+ * anchor.before(node) handles both insert and move natively.
+ * @param claimNode - Optional hydration callback. Called with (element, key) for
+ *   server-rendered elements removed from the DOM. Returns the element to use,
+ *   or null to discard.
+ */
+export function reconcile<T>(
+	anchor: Partial<Comment>,
+	keyMap: Map<unknown, Node>,
+	newItems: T[],
+	getKey: (item: T) => unknown,
+	createNode: (item: T) => Node,
+	// is this meant to be unused? claimNode?: (element: Element, key: unknown) => Element | null,
+): void {
+	const newKeys = new Set(newItems.map(getKey));
+
+	// Remove nodes no longer in list (or claim them for hydration)
+	for (const [key, node] of keyMap) {
+		if (!newKeys.has(key)) {
+			node.parentNode?.removeChild(node);
+			keyMap.delete(key);
+		}
+	}
+
+	// Insert/move in order — anchor.before() handles both cases
+	for (const item of newItems) {
+		const key = getKey(item);
+		let node = keyMap.get(key);
+		if (!node) {
+			node = createNode(item);
+			keyMap.set(key, node);
+		}
+		anchor.before?.(node);
+	}
+}
+
+/**
+ * Hydrate a keyed list: claim the comment anchor, walk its sibling elements
+ * to build a keyMap, then reconcile with signal data.
+ *
+ * SSR renders items as flat siblings. Hydration claims them by position,
+ * builds the keyMap, removes from DOM, then reconcile re-inserts in order.
+ */
+export function hydrateKeyedList<T>(
+	nodesVar: ChildNode[],
+	signalItems: T[],
+	getKey: (item: T) => unknown,
+	createNode: (item: T) => Node,
+	parent?: Element,
+): { anchor: Comment; keyMap: Map<unknown, Node> } {
+	// 1. Claim the <!--g--> opening delimiter as anchor
+	const anchor = claimComment(nodesVar, "g", parent);
+
+	// 2. Walk siblings after anchor, collect elements up to <!--/g-->, build keyMap
+	const keyMap = new Map<unknown, Node>();
+	const anchorParent = anchor.parentNode;
+	if (anchorParent && signalItems.length > 0) {
+		const claimed: Element[] = [];
+		let next = anchor.nextSibling;
+		while (next) {
+			const current = next;
+			next = next.nextSibling;
+			// Stop at closing <!--/g--> delimiter and consume it
+			if (current instanceof Comment && current.data === "/g") {
+				current.remove();
+				break;
+			}
+			if (current instanceof Element) {
+				current.remove();
+				claimed.push(current);
+			}
+		}
+		// Map claimed elements to keys by index
+		for (let i = 0; i < claimed.length && i < signalItems.length; i++) {
+			//@ts-expect-error i is always in bounds
+			const key = getKey(signalItems[i]);
+			//@ts-expect-error i is always in bounds
+			keyMap.set(key, claimed[i]);
+		}
+	}
+
+	// 3. Reconcile — keyMap is pre-populated with claimed nodes
+	reconcile(anchor, keyMap, signalItems, getKey, createNode);
+	return { anchor, keyMap };
+}
+
+export function insert(parent: Element, value: unknown): void {
+	if (value === false || value === null || value === undefined) return;
+	if (typeof value === "function") {
+		insert(parent, value());
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) insert(parent, item);
+		return;
+	}
+	if (value instanceof Node) {
+		parent.appendChild(value);
+		return;
+	}
+	parent.append(String(value));
+}
+
+/**
+ * Apply a use: directive to an element.
+ * The directive function receives (element, params) and may return a cleanup function.
+ * Cleanup runs when the enclosing $effect re-runs or the component is destroyed.
+ */
+export type Directive = (node: Element, params: unknown) => void | (() => void);
+
+export function applyDirective(
+	node: Element,
+	directive: Directive | [Directive, unknown],
+): void {
+	const [fn, params] = Array.isArray(directive)
+		? directive
+		: [directive, undefined];
+	const cleanup = fn(node, params);
+	if (typeof cleanup === "function") {
+		createEffect(() => () => cleanup());
+	}
+}
+
+export type ContextKey<T> = symbol & { __type: T };
+
+const clientContextStore = new Map<symbol, unknown>();
+
+let storeProvider: (() => Map<symbol, unknown>) | null = null;
+export function __setStoreProvider(fn: () => Map<symbol, unknown>) {
+	storeProvider = fn;
+}
+
+function getStore(): Map<symbol, unknown> {
+	return storeProvider?.() ?? clientContextStore;
+}
+
+export function createContext<T>(): ContextKey<T> {
+	return Symbol() as ContextKey<T>;
+}
+
+export function setContext<T>(key: ContextKey<T>, value: T): void {
+	getStore().set(key as unknown as symbol, value);
+}
+
+export function getContext<T>(key: ContextKey<T>): T {
+	return getStore().get(key as unknown as symbol) as T;
+}
+
+const _hydrationStack: ChildNode[][] = [];
+
+export function pushHydrationNodes(nodes: ChildNode[]): void {
+    _hydrationStack.push(nodes);
+}
+
+export function popHydrationNodes(): void {
+    _hydrationStack.pop();
+}
+
+export function getHydrationNodes(): ChildNode[] {
+    return _hydrationStack[_hydrationStack.length - 1] ?? [];
+}