@mindees/core 0.3.0 → 0.5.0

package/dist/animation/animation.d.ts

@@ -0,0 +1,69 @@
+import { Easing } from "./easing.js";
+
+//#region src/animation/animation.d.ts
+/** A frame source: subscribe with a per-frame `tick(nowMs)`, get back an unsubscribe. (`requestAnimationFrame` on web, vsync on native, a manual ticker in tests.) */
+type FrameSource = (tick: (nowMs: number) => void) => () => void;
+/** A running animation: stop it, or await natural completion. */
+interface AnimationHandle {
+  /** Stop now (keeps the current value); `done` resolves `false`. Idempotent. */
+  stop(): void;
+  /** Resolves `true` on natural completion, `false` if interrupted/stopped. Settles exactly once. */
+  readonly done: Promise<boolean>;
+}
+/** A reactive, animatable number. Call to read (tracks); `.set` jumps (untracked, stops any driver). */
+interface AnimatedValue {
+  (): number;
+  /** Jump to `v` immediately, cancelling any running driver. */
+  set(v: number): void;
+  /** The current per-frame velocity (units/sec) — seeds spring-interrupts-spring. */
+  readonly velocity: () => number;
+  /** Stop any running driver, keeping the current value. */
+  stop(): void;
+}
+/** Inject (or clear) the frame source that drives animations. `null` (default) → jump-to-final. */
+declare function setFrameSource(src: FrameSource | null): void;
+/** The current frame source, or `null`. */
+declare function getFrameSource(): FrameSource | null;
+/** Create an {@link AnimatedValue} (a reactive number you can drive with {@link timing}/{@link spring}). */
+declare function animate(initial: number): AnimatedValue;
+/** Animate `av` to `to` over `duration` ms with `easing` (RN `Animated.timing`). */
+declare function timing(av: AnimatedValue, opts: {
+  readonly to: number;
+  readonly duration?: number;
+  readonly easing?: Easing;
+  readonly delay?: number;
+  readonly onComplete?: (finished: boolean) => void;
+}): AnimationHandle;
+/** Animate `av` to `to` with spring physics (RN/Reanimated `withSpring`, Flutter `SpringSimulation`). */
+declare function spring(av: AnimatedValue, opts: {
+  readonly to: number;
+  readonly stiffness?: number;
+  readonly damping?: number;
+  readonly mass?: number;
+  readonly velocity?: number;
+  readonly restDelta?: number;
+  readonly restVelocity?: number;
+  readonly onComplete?: (finished: boolean) => void;
+}): AnimationHandle;
+/**
+ * Map an accessor through a piecewise-linear range (RN `Animated.interpolate`). Returns a plain
+ * accessor, so it tracks `value` and re-reads inside the consuming style each frame — glitch-free
+ * for free. `inputRange` must be monotonically increasing and match `outputRange` length (≥2).
+ */
+declare function interpolate(value: () => number, inputRange: readonly number[], outputRange: readonly number[], opts?: {
+  readonly extrapolate?: 'clamp' | 'extend';
+}): () => number;
+/** A `requestAnimationFrame`-backed {@link FrameSource} for the web (the host wires this at startup). */
+declare function rafFrameSource(): FrameSource;
+/** A manually-driven {@link FrameSource} for deterministic tests: call `tick(nowMs)` to advance. */
+declare function manualFrameSource(): {
+  source: FrameSource;
+  tick: (nowMs: number) => void;
+};
+/** @internal Test-only: number of running animations. */
+declare function _activeAnimationCount(): number;
+/** @internal Test-only: reset all engine state between tests. */
+declare function _resetAnimation(): void;
+//#endregion
+export { AnimatedValue, AnimationHandle, FrameSource, _activeAnimationCount, _resetAnimation, animate, getFrameSource, interpolate, manualFrameSource, rafFrameSource, setFrameSource, spring, timing };
+//# sourceMappingURL=animation.d.ts.map

package/dist/animation/animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation.d.ts","names":[],"sources":["../../src/animation/animation.ts"],"mappings":";;;;KAiBY,WAAA,IAAe,IAA6B,GAAtB,KAAA;;UAGjB,eAAA;EAQA;EANf,IAAA;;WAES,IAAA,EAAM,OAAO;AAAA;;UAIP,aAAA;EAAA;EAOX;EAJJ,GAAA,CAAI,CAAA;EAkCU;EAAA,SAhCL,QAAA;;EAET,IAAA;AAAA;AAyDF;AAAA,iBA3BgB,cAAA,CAAe,GAAuB,EAAlB,WAAW;;iBA2B/B,cAAA,IAAkB,WAAW;AAAA;AAAA,iBAqD7B,OAAA,CAAQ,OAAA,WAAkB,aAAa;;iBAyFvC,MAAA,CACd,EAAA,EAAI,aAAA,EACJ,IAAA;EAAA,SACW,EAAA;EAAA,SACA,QAAA;EAAA,SACA,MAAA,GAAS,MAAA;EAAA,SACT,KAAA;EAAA,SACA,UAAA,IAAc,QAAA;AAAA,IAExB,eAAA;;iBA+Ba,MAAA,CACd,EAAA,EAAI,aAAA,EACJ,IAAA;EAAA,SACW,EAAA;EAAA,SACA,SAAA;EAAA,SACA,OAAA;EAAA,SACA,IAAA;EAAA,SACA,QAAA;EAAA,SACA,SAAA;EAAA,SACA,YAAA;EAAA,SACA,UAAA,IAAc,QAAA;AAAA,IAExB,eAAe;;;;;;iBAiDF,WAAA,CACd,KAAA,gBACA,UAAA,qBACA,WAAA,qBACA,IAAA;EAAA,SAAkB,WAAA;AAAA;;iBAgCJ,cAAA,IAAkB,WAAW;;iBAe7B,iBAAA;EAAuB,MAAA,EAAQ,WAAW;EAAE,IAAA,GAAO,KAAA;AAAA;;iBAcnD,qBAAA;;iBAKA,eAAA"}

package/dist/animation/animation.js

@@ -0,0 +1,294 @@
+import { batch, getOwner, onCleanup, signal, untrack } from "../reactive/reactive.js";
+import { linear } from "./easing.js";
+//#region src/animation/animation.ts
+/**
+* The animation engine — RN `Animated`/Reanimated + Flutter `AnimationController` parity, built
+* entirely on the reactive core. An {@link AnimatedValue} **is a signal**, so reading it inside a
+* `style` accessor re-renders only that node (no renderer surface). One injected {@link FrameSource}
+* (mirroring `setReactiveScheduler`) drives a single loop that ticks every active driver inside one
+* `batch()` per frame — so a style reading several animated values recomputes once (glitch-free).
+*
+* With no frame source (SSR / headless / tests until one is wired) animations **jump to their final
+* value** synchronously: deterministic, never a hang, server output shows the end state.
+*
+* @module
+*/
+const MAX_DT = .064;
+const SPRING_MAX_FRAMES = 600;
+const DEFAULT_DURATION = 250;
+const internals = /* @__PURE__ */ new WeakMap();
+const active = /* @__PURE__ */ new Set();
+let frameSource = null;
+let unsubscribe = null;
+let lastNow = -1;
+/** Inject (or clear) the frame source that drives animations. `null` (default) → jump-to-final. */
+function setFrameSource(src) {
+	if (src === frameSource) return;
+	if (unsubscribe) {
+		unsubscribe();
+		unsubscribe = null;
+	}
+	frameSource = src;
+	if (src === null) batch(() => {
+		for (const d of [...active]) {
+			writeValue(d.av, d.target);
+			active.delete(d);
+			const st = internals.get(d.av);
+			if (st) st.driver = null;
+			d.settle(true);
+		}
+	});
+	else if (active.size > 0) ensureLoop();
+}
+/** The current frame source, or `null`. */
+function getFrameSource() {
+	return frameSource;
+}
+function writeValue(av, v) {
+	untrack(() => internals.get(av)?.signal.set(v));
+}
+function maybeSleep() {
+	if (active.size === 0 && unsubscribe) {
+		unsubscribe();
+		unsubscribe = null;
+	}
+}
+function ensureLoop() {
+	if (unsubscribe === null && frameSource !== null) {
+		lastNow = -1;
+		unsubscribe = frameSource(onFrame);
+	}
+}
+function onFrame(now) {
+	if (lastNow < 0) lastNow = now;
+	const dt = Math.min(Math.max(0, (now - lastNow) / 1e3), MAX_DT);
+	batch(() => {
+		for (const d of [...active]) {
+			if (!active.has(d)) continue;
+			let running;
+			try {
+				running = d.tick(now, dt);
+			} catch {
+				running = false;
+			}
+			if (!running) {
+				active.delete(d);
+				const st = internals.get(d.av);
+				if (st) st.driver = null;
+				d.settle(true);
+			}
+		}
+	});
+	lastNow = now;
+	maybeSleep();
+}
+/** Create an {@link AnimatedValue} (a reactive number you can drive with {@link timing}/{@link spring}). */
+function animate(initial) {
+	const s = signal(initial);
+	const state = {
+		signal: s,
+		vel: { v: 0 },
+		driver: null
+	};
+	const av = Object.assign(() => s(), {
+		set(v) {
+			stopDriver(av);
+			untrack(() => s.set(v));
+		},
+		velocity: () => state.vel.v,
+		stop() {
+			stopDriver(av);
+		}
+	});
+	internals.set(av, state);
+	return av;
+}
+function stopDriver(av) {
+	const st = internals.get(av);
+	if (st?.driver) {
+		const d = st.driver;
+		active.delete(d);
+		st.driver = null;
+		d.settle(false);
+		maybeSleep();
+	}
+}
+/**
+* Begin a driver on `av`: settle any prior driver (last-write-wins), capture the current value as
+* the start, and either jump-to-final (no frame source) or join the loop. Returns the handle.
+*/
+function start(av, opts, build) {
+	const st = internals.get(av);
+	if (!st) throw new TypeError("animation driver: value was not created with animate()");
+	stopDriver(av);
+	let settled = false;
+	let resolveDone;
+	const done = new Promise((r) => {
+		resolveDone = r;
+	});
+	const settle = (finished) => {
+		if (settled) return;
+		settled = true;
+		resolveDone(finished);
+		opts.onComplete?.(finished);
+	};
+	const from = untrack(av);
+	if (frameSource === null) {
+		writeValue(av, opts.to);
+		settle(true);
+		return {
+			stop: () => settle(false),
+			done
+		};
+	}
+	const tick = build(from, settle);
+	const driver = {
+		av,
+		target: opts.to,
+		tick,
+		settle
+	};
+	st.driver = driver;
+	active.add(driver);
+	if (getOwner() !== null) onCleanup(() => {
+		if (st.driver === driver) stopDriver(av);
+	});
+	ensureLoop();
+	return {
+		stop: () => stopDriver(av),
+		done
+	};
+}
+/** Animate `av` to `to` over `duration` ms with `easing` (RN `Animated.timing`). */
+function timing(av, opts) {
+	const duration = Number.isFinite(opts.duration) ? opts.duration : DEFAULT_DURATION;
+	const easing = opts.easing ?? linear;
+	const delay = Number.isFinite(opts.delay) ? opts.delay : 0;
+	return start(av, opts, (from, _settle) => {
+		let startTime = -1;
+		let prev = from;
+		const settleAt = () => {
+			internals.get(av).vel.v = 0;
+			writeValue(av, opts.to);
+			return false;
+		};
+		return (now, dt) => {
+			if (startTime < 0) startTime = now;
+			const elapsed = now - startTime - delay;
+			if (elapsed < 0) return true;
+			const t = duration <= 0 ? 1 : Math.min(elapsed / duration, 1);
+			const next = from + (opts.to - from) * easing(t);
+			if (!Number.isFinite(next)) return settleAt();
+			if (dt > 0) internals.get(av).vel.v = (next - prev) / dt;
+			prev = next;
+			if (t >= 1) return settleAt();
+			writeValue(av, next);
+			return true;
+		};
+	});
+}
+/** Animate `av` to `to` with spring physics (RN/Reanimated `withSpring`, Flutter `SpringSimulation`). */
+function spring(av, opts) {
+	const stiffness = Math.max(0, opts.stiffness ?? 170);
+	const damping = Math.max(0, opts.damping ?? 26);
+	const mass = Math.max(1e-4, opts.mass ?? 1);
+	const restDelta = opts.restDelta ?? .01;
+	const restVelocity = opts.restVelocity ?? .01;
+	const omega = Math.sqrt(stiffness / mass);
+	return start(av, opts, (from) => {
+		let x = from;
+		let v = opts.velocity ?? internals.get(av).vel.v;
+		let frames = 0;
+		return (_now, dt) => {
+			frames++;
+			const steps = Math.max(1, Math.ceil(dt * omega / 1.5));
+			const sub = dt / steps;
+			for (let i = 0; i < steps; i++) {
+				const a = (-stiffness * (x - opts.to) - damping * v) / mass;
+				v += a * sub;
+				x += v * sub;
+			}
+			if (!Number.isFinite(x)) {
+				internals.get(av).vel.v = 0;
+				writeValue(av, opts.to);
+				return false;
+			}
+			internals.get(av).vel.v = v;
+			if (Math.abs(x - opts.to) < restDelta && Math.abs(v) < restVelocity || frames > SPRING_MAX_FRAMES) {
+				internals.get(av).vel.v = 0;
+				writeValue(av, opts.to);
+				return false;
+			}
+			writeValue(av, x);
+			return true;
+		};
+	});
+}
+/**
+* Map an accessor through a piecewise-linear range (RN `Animated.interpolate`). Returns a plain
+* accessor, so it tracks `value` and re-reads inside the consuming style each frame — glitch-free
+* for free. `inputRange` must be monotonically increasing and match `outputRange` length (≥2).
+*/
+function interpolate(value, inputRange, outputRange, opts) {
+	if (inputRange.length !== outputRange.length || inputRange.length < 2) throw new RangeError("interpolate: inputRange and outputRange must be the same length (>= 2)");
+	const extrapolate = opts?.extrapolate ?? "clamp";
+	const n = inputRange.length;
+	return () => {
+		const x = value();
+		if (Number.isNaN(x)) return outputRange[0];
+		const lerp = (i) => {
+			const x0 = inputRange[i];
+			const x1 = inputRange[i + 1];
+			const y0 = outputRange[i];
+			const y1 = outputRange[i + 1];
+			if (x1 === x0) return y0;
+			return y0 + (y1 - y0) * (x - x0) / (x1 - x0);
+		};
+		if (x <= inputRange[0]) return extrapolate === "extend" ? lerp(0) : outputRange[0];
+		if (x >= inputRange[n - 1]) return extrapolate === "extend" ? lerp(n - 2) : outputRange[n - 1];
+		for (let i = 0; i < n - 1; i++) if (x >= inputRange[i] && x <= inputRange[i + 1]) return lerp(i);
+		return outputRange[n - 1];
+	};
+}
+/** A `requestAnimationFrame`-backed {@link FrameSource} for the web (the host wires this at startup). */
+function rafFrameSource() {
+	return (tick) => {
+		const raf = globalThis.requestAnimationFrame;
+		const caf = globalThis.cancelAnimationFrame;
+		if (!raf) return () => {};
+		let id = raf(function loop(t) {
+			tick(t);
+			id = raf(loop);
+		});
+		return () => caf?.(id);
+	};
+}
+/** A manually-driven {@link FrameSource} for deterministic tests: call `tick(nowMs)` to advance. */
+function manualFrameSource() {
+	let cb = null;
+	return {
+		source: (t) => {
+			cb = t;
+			return () => {
+				cb = null;
+			};
+		},
+		tick: (nowMs) => cb?.(nowMs)
+	};
+}
+/** @internal Test-only: number of running animations. */
+function _activeAnimationCount() {
+	return active.size;
+}
+/** @internal Test-only: reset all engine state between tests. */
+function _resetAnimation() {
+	if (unsubscribe) unsubscribe();
+	unsubscribe = null;
+	active.clear();
+	frameSource = null;
+	lastNow = -1;
+}
+//#endregion
+export { _activeAnimationCount, _resetAnimation, animate, getFrameSource, interpolate, manualFrameSource, rafFrameSource, setFrameSource, spring, timing };
+
+//# sourceMappingURL=animation.js.map

package/dist/animation/animation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation.js","names":[],"sources":["../../src/animation/animation.ts"],"sourcesContent":["/**\n * The animation engine — RN `Animated`/Reanimated + Flutter `AnimationController` parity, built\n * entirely on the reactive core. An {@link AnimatedValue} **is a signal**, so reading it inside a\n * `style` accessor re-renders only that node (no renderer surface). One injected {@link FrameSource}\n * (mirroring `setReactiveScheduler`) drives a single loop that ticks every active driver inside one\n * `batch()` per frame — so a style reading several animated values recomputes once (glitch-free).\n *\n * With no frame source (SSR / headless / tests until one is wired) animations **jump to their final\n * value** synchronously: deterministic, never a hang, server output shows the end state.\n *\n * @module\n */\n\nimport { batch, getOwner, onCleanup, type Signal, signal, untrack } from '../reactive'\nimport { type Easing, linear } from './easing'\n\n/** A frame source: subscribe with a per-frame `tick(nowMs)`, get back an unsubscribe. (`requestAnimationFrame` on web, vsync on native, a manual ticker in tests.) */\nexport type FrameSource = (tick: (nowMs: number) => void) => () => void\n\n/** A running animation: stop it, or await natural completion. */\nexport interface AnimationHandle {\n  /** Stop now (keeps the current value); `done` resolves `false`. Idempotent. */\n  stop(): void\n  /** Resolves `true` on natural completion, `false` if interrupted/stopped. Settles exactly once. */\n  readonly done: Promise<boolean>\n}\n\n/** A reactive, animatable number. Call to read (tracks); `.set` jumps (untracked, stops any driver). */\nexport interface AnimatedValue {\n  (): number\n  /** Jump to `v` immediately, cancelling any running driver. */\n  set(v: number): void\n  /** The current per-frame velocity (units/sec) — seeds spring-interrupts-spring. */\n  readonly velocity: () => number\n  /** Stop any running driver, keeping the current value. */\n  stop(): void\n}\n\ninterface Driver {\n  readonly av: AnimatedValue\n  /** Target value, used to jump-to-final if the frame source detaches mid-flight. */\n  readonly target: number\n  /** Advance by this frame; return `true` while still running. */\n  tick(nowMs: number, dt: number): boolean\n  /** Resolve the handle + fire onComplete exactly once. */\n  settle(finished: boolean): void\n}\n\ninterface Internal {\n  readonly signal: Signal<number>\n  readonly vel: { v: number }\n  driver: Driver | null\n}\n\nconst MAX_DT = 0.064 // clamp huge gaps (backgrounded tab / GC / breakpoint) so springs can't explode\nconst SPRING_MAX_FRAMES = 600 // ~10s @60fps: a non-converging spring fails safely instead of forever\nconst DEFAULT_DURATION = 250 // matches Atlas tokens.duration.standard (kept literal to avoid an atlas dep)\n\nconst internals = new WeakMap<AnimatedValue, Internal>()\nconst active = new Set<Driver>()\nlet frameSource: FrameSource | null = null\nlet unsubscribe: (() => void) | null = null\nlet lastNow = -1 // -1 = uninitialized (a real frame can arrive at now=0)\n\n/** Inject (or clear) the frame source that drives animations. `null` (default) → jump-to-final. */\nexport function setFrameSource(src: FrameSource | null): void {\n  if (src === frameSource) return\n  // Detach the current loop FIRST so any change — including a non-null→non-null swap — can never\n  // leak the old subscription (which would keep driving) nor block resubscribing under the new one.\n  if (unsubscribe) {\n    unsubscribe()\n    unsubscribe = null\n  }\n  frameSource = src\n  if (src === null) {\n    // Detaching entirely: flush every active driver to its final value so nothing is left frozen\n    // (symmetric with the start-time SSR fallback).\n    batch(() => {\n      for (const d of [...active]) {\n        writeValue(d.av, d.target)\n        active.delete(d)\n        const st = internals.get(d.av)\n        if (st) st.driver = null\n        d.settle(true)\n      }\n    })\n  } else if (active.size > 0) {\n    ensureLoop() // resubscribe in-flight animations under the new source\n  }\n}\n\n/** The current frame source, or `null`. */\nexport function getFrameSource(): FrameSource | null {\n  return frameSource\n}\n\nfunction writeValue(av: AnimatedValue, v: number): void {\n  untrack(() => internals.get(av)?.signal.set(v))\n}\n\nfunction maybeSleep(): void {\n  if (active.size === 0 && unsubscribe) {\n    unsubscribe()\n    unsubscribe = null\n  }\n}\n\nfunction ensureLoop(): void {\n  if (unsubscribe === null && frameSource !== null) {\n    lastNow = -1\n    unsubscribe = frameSource(onFrame)\n  }\n}\n\nfunction onFrame(now: number): void {\n  if (lastNow < 0) lastNow = now // first frame establishes the baseline (dt = 0, no jump)\n  // Clamp to [0, MAX_DT]: never integrate backward on a non-monotonic timestamp, never explode on a\n  // huge gap (backgrounded tab / GC / breakpoint).\n  const dt = Math.min(Math.max(0, (now - lastNow) / 1000), MAX_DT)\n  // One batch per frame: every driver's write coalesces into a single flush, so a style reading\n  // multiple animated values recomputes exactly once (glitch-free).\n  batch(() => {\n    for (const d of [...active]) {\n      // A sibling's onComplete this frame may have stopped this driver — don't tick a removed one\n      // (would violate stop()'s \"keeps current value\" contract with an extra write).\n      if (!active.has(d)) continue\n      let running: boolean\n      try {\n        running = d.tick(now, dt)\n      } catch {\n        running = false // isolate a throwing driver (mirrors flushEffects' error isolation)\n      }\n      if (!running) {\n        active.delete(d)\n        const st = internals.get(d.av)\n        if (st) st.driver = null\n        d.settle(true)\n      }\n    }\n  })\n  lastNow = now\n  maybeSleep()\n}\n\n/** Create an {@link AnimatedValue} (a reactive number you can drive with {@link timing}/{@link spring}). */\nexport function animate(initial: number): AnimatedValue {\n  const s = signal(initial)\n  const state: Internal = { signal: s, vel: { v: 0 }, driver: null }\n  const av: AnimatedValue = Object.assign(() => s(), {\n    set(v: number): void {\n      stopDriver(av) // a manual jump cancels any running animation (RN setValue semantics)\n      untrack(() => s.set(v))\n    },\n    velocity: () => state.vel.v,\n    stop(): void {\n      stopDriver(av)\n    },\n  })\n  internals.set(av, state)\n  return av\n}\n\nfunction stopDriver(av: AnimatedValue): void {\n  const st = internals.get(av)\n  if (st?.driver) {\n    const d = st.driver\n    active.delete(d)\n    st.driver = null\n    d.settle(false)\n    maybeSleep()\n  }\n}\n\n/** Options shared by drivers. */\ninterface DriverOptions {\n  readonly to: number\n  readonly onComplete?: (finished: boolean) => void\n}\n\n/**\n * Begin a driver on `av`: settle any prior driver (last-write-wins), capture the current value as\n * the start, and either jump-to-final (no frame source) or join the loop. Returns the handle.\n */\nfunction start(\n  av: AnimatedValue,\n  opts: DriverOptions,\n  build: (from: number, settle: (finished: boolean) => void) => Driver['tick'],\n): AnimationHandle {\n  const st = internals.get(av)\n  if (!st) throw new TypeError('animation driver: value was not created with animate()')\n  stopDriver(av) // last-write-wins: at most one driver per value\n\n  let settled = false\n  let resolveDone!: (finished: boolean) => void\n  const done = new Promise<boolean>((r) => {\n    resolveDone = r\n  })\n  const settle = (finished: boolean): void => {\n    if (settled) return\n    settled = true\n    resolveDone(finished)\n    opts.onComplete?.(finished)\n  }\n\n  const from = untrack(av) // start from the CURRENT rendered value (continuous retarget)\n\n  // No frame source → jump to the final value synchronously (SSR / headless / not-yet-wired).\n  if (frameSource === null) {\n    writeValue(av, opts.to)\n    settle(true)\n    return { stop: () => settle(false), done }\n  }\n\n  const tick = build(from, settle)\n  const driver: Driver = { av, target: opts.to, tick, settle }\n  st.driver = driver\n  active.add(driver)\n\n  // Auto-stop when the owner that started the animation is disposed (unmount), so the loop never\n  // writes a dead signal and never leaks a frame subscription.\n  if (getOwner() !== null) {\n    onCleanup(() => {\n      if (st.driver === driver) stopDriver(av)\n    })\n  }\n\n  ensureLoop()\n  return {\n    stop: () => stopDriver(av),\n    done,\n  }\n}\n\n/** Animate `av` to `to` over `duration` ms with `easing` (RN `Animated.timing`). */\nexport function timing(\n  av: AnimatedValue,\n  opts: {\n    readonly to: number\n    readonly duration?: number\n    readonly easing?: Easing\n    readonly delay?: number\n    readonly onComplete?: (finished: boolean) => void\n  },\n): AnimationHandle {\n  // Sanitize: `??` only catches null/undefined, so a NaN/Infinity duration would write NaN forever\n  // (permanent under Object.is) — fall back to the default for any non-finite duration.\n  const duration = Number.isFinite(opts.duration) ? (opts.duration as number) : DEFAULT_DURATION\n  const easing = opts.easing ?? linear\n  const delay = Number.isFinite(opts.delay) ? (opts.delay as number) : 0\n  return start(av, opts, (from, _settle) => {\n    let startTime = -1 // -1 = uninitialized (a real frame can arrive at now=0)\n    let prev = from\n    const settleAt = (): boolean => {\n      internals.get(av)!.vel.v = 0 // at rest: velocity is 0 (so a following spring doesn't inherit phantom momentum)\n      writeValue(av, opts.to)\n      return false\n    }\n    return (now, dt) => {\n      if (startTime < 0) startTime = now\n      const elapsed = now - startTime - delay\n      if (elapsed < 0) return true // still in the delay window\n      const t = duration <= 0 ? 1 : Math.min(elapsed / duration, 1)\n      const next = from + (opts.to - from) * easing(t)\n      if (!Number.isFinite(next)) return settleAt() // defensive: never write NaN/Infinity\n      if (dt > 0) internals.get(av)!.vel.v = (next - prev) / dt\n      prev = next\n      if (t >= 1) return settleAt()\n      writeValue(av, next)\n      return true\n    }\n  })\n}\n\n/** Animate `av` to `to` with spring physics (RN/Reanimated `withSpring`, Flutter `SpringSimulation`). */\nexport function spring(\n  av: AnimatedValue,\n  opts: {\n    readonly to: number\n    readonly stiffness?: number\n    readonly damping?: number\n    readonly mass?: number\n    readonly velocity?: number\n    readonly restDelta?: number\n    readonly restVelocity?: number\n    readonly onComplete?: (finished: boolean) => void\n  },\n): AnimationHandle {\n  const stiffness = Math.max(0, opts.stiffness ?? 170)\n  const damping = Math.max(0, opts.damping ?? 26)\n  const mass = Math.max(1e-4, opts.mass ?? 1)\n  const restDelta = opts.restDelta ?? 0.01\n  const restVelocity = opts.restVelocity ?? 0.01\n  const omega = Math.sqrt(stiffness / mass) // natural frequency, for substep stability\n  return start(av, opts, (from) => {\n    let x = from\n    let v = opts.velocity ?? internals.get(av)!.vel.v\n    let frames = 0\n    return (_now, dt) => {\n      frames++\n      // Semi-implicit (symplectic) Euler is only conditionally stable (omega·dt < ~2). Stiffness is\n      // user-controlled, so SUBSTEP the frame's dt to keep each step well inside the stable region —\n      // a stiff spring stays finite instead of diverging to Infinity/NaN.\n      const steps = Math.max(1, Math.ceil((dt * omega) / 1.5))\n      const sub = dt / steps\n      for (let i = 0; i < steps; i++) {\n        const a = (-stiffness * (x - opts.to) - damping * v) / mass\n        v += a * sub\n        x += v * sub\n      }\n      if (!Number.isFinite(x)) {\n        // Defensive: never write NaN/Infinity (permanent under Object.is) — snap to the target.\n        internals.get(av)!.vel.v = 0\n        writeValue(av, opts.to)\n        return false\n      }\n      internals.get(av)!.vel.v = v\n      if (\n        (Math.abs(x - opts.to) < restDelta && Math.abs(v) < restVelocity) ||\n        frames > SPRING_MAX_FRAMES\n      ) {\n        internals.get(av)!.vel.v = 0\n        writeValue(av, opts.to)\n        return false\n      }\n      writeValue(av, x)\n      return true\n    }\n  })\n}\n\n/**\n * Map an accessor through a piecewise-linear range (RN `Animated.interpolate`). Returns a plain\n * accessor, so it tracks `value` and re-reads inside the consuming style each frame — glitch-free\n * for free. `inputRange` must be monotonically increasing and match `outputRange` length (≥2).\n */\nexport function interpolate(\n  value: () => number,\n  inputRange: readonly number[],\n  outputRange: readonly number[],\n  opts?: { readonly extrapolate?: 'clamp' | 'extend' },\n): () => number {\n  if (inputRange.length !== outputRange.length || inputRange.length < 2) {\n    throw new RangeError('interpolate: inputRange and outputRange must be the same length (>= 2)')\n  }\n  const extrapolate = opts?.extrapolate ?? 'clamp'\n  const n = inputRange.length\n  return () => {\n    const x = value()\n    if (Number.isNaN(x)) return outputRange[0] as number // a NaN source maps to the first output, not the last\n    const lerp = (i: number): number => {\n      const x0 = inputRange[i] as number\n      const x1 = inputRange[i + 1] as number\n      const y0 = outputRange[i] as number\n      const y1 = outputRange[i + 1] as number\n      if (x1 === x0) return y0 // zero-width segment → avoid divide-by-zero\n      return y0 + ((y1 - y0) * (x - x0)) / (x1 - x0)\n    }\n    if (x <= (inputRange[0] as number)) {\n      return extrapolate === 'extend' ? lerp(0) : (outputRange[0] as number)\n    }\n    if (x >= (inputRange[n - 1] as number)) {\n      return extrapolate === 'extend' ? lerp(n - 2) : (outputRange[n - 1] as number)\n    }\n    for (let i = 0; i < n - 1; i++) {\n      if (x >= (inputRange[i] as number) && x <= (inputRange[i + 1] as number)) return lerp(i)\n    }\n    return outputRange[n - 1] as number // unreachable for monotonic input\n  }\n}\n\n/** A `requestAnimationFrame`-backed {@link FrameSource} for the web (the host wires this at startup). */\nexport function rafFrameSource(): FrameSource {\n  return (tick) => {\n    const raf = (globalThis as { requestAnimationFrame?: (cb: (t: number) => void) => number })\n      .requestAnimationFrame\n    const caf = (globalThis as { cancelAnimationFrame?: (id: number) => void }).cancelAnimationFrame\n    if (!raf) return () => {} // no rAF (non-browser) → caller already degrades to jump-to-final\n    let id = raf(function loop(t: number) {\n      tick(t)\n      id = raf(loop)\n    })\n    return () => caf?.(id)\n  }\n}\n\n/** A manually-driven {@link FrameSource} for deterministic tests: call `tick(nowMs)` to advance. */\nexport function manualFrameSource(): { source: FrameSource; tick: (nowMs: number) => void } {\n  let cb: ((nowMs: number) => void) | null = null\n  return {\n    source: (t) => {\n      cb = t\n      return () => {\n        cb = null\n      }\n    },\n    tick: (nowMs) => cb?.(nowMs),\n  }\n}\n\n/** @internal Test-only: number of running animations. */\nexport function _activeAnimationCount(): number {\n  return active.size\n}\n\n/** @internal Test-only: reset all engine state between tests. */\nexport function _resetAnimation(): void {\n  if (unsubscribe) unsubscribe()\n  unsubscribe = null\n  active.clear()\n  frameSource = null\n  lastNow = -1\n}\n"],"mappings":"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"}

package/dist/animation/easing.d.ts

@@ -0,0 +1,25 @@
+//#region src/animation/easing.d.ts
+/**
+ * Easing curves for the animation system. A few named curves plus a {@link cubicBezier} factory
+ * that parses a CSS `cubic-bezier(x1,y1,x2,y2)` string — so Atlas's `easing` tokens (which are such
+ * strings) map straight onto the animation engine without a circular dependency.
+ *
+ * @module
+ */
+/** An easing function: maps normalized time `t` in `[0,1]` to an eased progress (usually `[0,1]`). */
+type Easing = (t: number) => number;
+declare const linear: Easing;
+declare const easeInQuad: Easing;
+declare const easeOutQuad: Easing;
+declare const easeInOutQuad: Easing;
+declare const easeOutCubic: Easing;
+/**
+ * Build an {@link Easing} from a CSS `cubic-bezier(x1, y1, x2, y2)` string (spaces tolerated, as in
+ * Atlas's tokens). Solves `x(t) = input` via Newton-Raphson with a bisection fallback, then returns
+ * `y(t)`. A malformed string falls back to {@link linear} — it never returns `NaN` (a `NaN` written
+ * into a signal would be permanent under `Object.is` and freeze every binding).
+ */
+declare function cubicBezier(css: string): Easing;
+//#endregion
+export { Easing, cubicBezier, easeInOutQuad, easeInQuad, easeOutCubic, easeOutQuad, linear };
+//# sourceMappingURL=easing.d.ts.map

package/dist/animation/easing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"easing.d.ts","names":[],"sources":["../../src/animation/easing.ts"],"mappings":";;AASA;;;;AAA+B;AAE/B;;KAFY,MAAA,IAAU,CAAS;AAAA,cAElB,MAAA,EAAQ,MAAiB;AAAA,cACzB,UAAA,EAAY,MAAqB;AAAA,cACjC,WAAA,EAAa,MAA2B;AAAA,cACxC,aAAA,EAAe,MAA4D;AAAA,cAC3E,YAAA,EAAc,MAAgC;;AAHb;AAC9C;;;;iBA0BgB,WAAA,CAAY,GAAA,WAAc,MAAM"}

package/dist/animation/easing.js

@@ -0,0 +1,61 @@
+//#region src/animation/easing.ts
+const linear = (t) => t;
+const easeInQuad = (t) => t * t;
+const easeOutQuad = (t) => t * (2 - t);
+const easeInOutQuad = (t) => t < .5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+const easeOutCubic = (t) => 1 - (1 - t) ** 3;
+/** Evaluate a 1-D cubic Bézier (control points `0, a, b, 1`) at parameter `t`. */
+function bezier(t, a, b) {
+	const c = 3 * a;
+	const bb = 3 * (b - a) - c;
+	return (((1 - c - bb) * t + bb) * t + c) * t;
+}
+/** Derivative of {@link bezier} w.r.t. `t` (for Newton-Raphson). */
+function bezierSlope(t, a, b) {
+	const c = 3 * a;
+	const bb = 3 * (b - a) - c;
+	return (3 * (1 - c - bb) * t + 2 * bb) * t + c;
+}
+/**
+* Build an {@link Easing} from a CSS `cubic-bezier(x1, y1, x2, y2)` string (spaces tolerated, as in
+* Atlas's tokens). Solves `x(t) = input` via Newton-Raphson with a bisection fallback, then returns
+* `y(t)`. A malformed string falls back to {@link linear} — it never returns `NaN` (a `NaN` written
+* into a signal would be permanent under `Object.is` and freeze every binding).
+*/
+function cubicBezier(css) {
+	const match = /cubic-bezier\(([^)]+)\)/.exec(css);
+	if (!match?.[1]) return linear;
+	const parts = match[1].split(",").map((s) => Number.parseFloat(s.trim()));
+	if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return linear;
+	const [x1, y1, x2, y2] = parts;
+	const solveT = (x) => {
+		let t = x;
+		for (let i = 0; i < 8; i++) {
+			const xt = bezier(t, x1, x2) - x;
+			if (Math.abs(xt) < 1e-6) return t;
+			const slope = bezierSlope(t, x1, x2);
+			if (Math.abs(slope) < 1e-6) break;
+			t -= xt / slope;
+		}
+		let lo = 0;
+		let hi = 1;
+		let mid = x;
+		for (let i = 0; i < 30; i++) {
+			mid = (lo + hi) / 2;
+			const xt = bezier(mid, x1, x2);
+			if (Math.abs(xt - x) < 1e-6) break;
+			if (xt < x) lo = mid;
+			else hi = mid;
+		}
+		return mid;
+	};
+	return (t) => {
+		if (t <= 0) return 0;
+		if (t >= 1) return 1;
+		return bezier(solveT(t), y1, y2);
+	};
+}
+//#endregion
+export { cubicBezier, easeInOutQuad, easeInQuad, easeOutCubic, easeOutQuad, linear };
+
+//# sourceMappingURL=easing.js.map

package/dist/animation/easing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"easing.js","names":[],"sources":["../../src/animation/easing.ts"],"sourcesContent":["/**\n * Easing curves for the animation system. A few named curves plus a {@link cubicBezier} factory\n * that parses a CSS `cubic-bezier(x1,y1,x2,y2)` string — so Atlas's `easing` tokens (which are such\n * strings) map straight onto the animation engine without a circular dependency.\n *\n * @module\n */\n\n/** An easing function: maps normalized time `t` in `[0,1]` to an eased progress (usually `[0,1]`). */\nexport type Easing = (t: number) => number\n\nexport const linear: Easing = (t) => t\nexport const easeInQuad: Easing = (t) => t * t\nexport const easeOutQuad: Easing = (t) => t * (2 - t)\nexport const easeInOutQuad: Easing = (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t)\nexport const easeOutCubic: Easing = (t) => 1 - (1 - t) ** 3\n\n/** Evaluate a 1-D cubic Bézier (control points `0, a, b, 1`) at parameter `t`. */\nfunction bezier(t: number, a: number, b: number): number {\n  const c = 3 * a\n  const bb = 3 * (b - a) - c\n  const aa = 1 - c - bb\n  return ((aa * t + bb) * t + c) * t\n}\n\n/** Derivative of {@link bezier} w.r.t. `t` (for Newton-Raphson). */\nfunction bezierSlope(t: number, a: number, b: number): number {\n  const c = 3 * a\n  const bb = 3 * (b - a) - c\n  const aa = 1 - c - bb\n  return (3 * aa * t + 2 * bb) * t + c\n}\n\n/**\n * Build an {@link Easing} from a CSS `cubic-bezier(x1, y1, x2, y2)` string (spaces tolerated, as in\n * Atlas's tokens). Solves `x(t) = input` via Newton-Raphson with a bisection fallback, then returns\n * `y(t)`. A malformed string falls back to {@link linear} — it never returns `NaN` (a `NaN` written\n * into a signal would be permanent under `Object.is` and freeze every binding).\n */\nexport function cubicBezier(css: string): Easing {\n  const match = /cubic-bezier\\(([^)]+)\\)/.exec(css)\n  if (!match?.[1]) return linear\n  const parts = match[1].split(',').map((s) => Number.parseFloat(s.trim()))\n  if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return linear\n  const [x1, y1, x2, y2] = parts as [number, number, number, number]\n\n  const solveT = (x: number): number => {\n    let t = x\n    for (let i = 0; i < 8; i++) {\n      const xt = bezier(t, x1, x2) - x\n      if (Math.abs(xt) < 1e-6) return t\n      const slope = bezierSlope(t, x1, x2)\n      if (Math.abs(slope) < 1e-6) break\n      t -= xt / slope\n    }\n    // Bisection fallback (always converges on the monotonic [0,1] domain).\n    let lo = 0\n    let hi = 1\n    let mid = x\n    for (let i = 0; i < 30; i++) {\n      mid = (lo + hi) / 2\n      const xt = bezier(mid, x1, x2)\n      if (Math.abs(xt - x) < 1e-6) break\n      if (xt < x) lo = mid\n      else hi = mid\n    }\n    return mid\n  }\n\n  return (t) => {\n    if (t <= 0) return 0\n    if (t >= 1) return 1\n    return bezier(solveT(t), y1, y2)\n  }\n}\n"],"mappings":";AAWA,MAAa,UAAkB,MAAM;AACrC,MAAa,cAAsB,MAAM,IAAI;AAC7C,MAAa,eAAuB,MAAM,KAAK,IAAI;AACnD,MAAa,iBAAyB,MAAO,IAAI,KAAM,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,KAAK;AACtF,MAAa,gBAAwB,MAAM,KAAK,IAAI,MAAM;;AAG1D,SAAS,OAAO,GAAW,GAAW,GAAmB;CACvD,MAAM,IAAI,IAAI;CACd,MAAM,KAAK,KAAK,IAAI,KAAK;CAEzB,UADW,IAAI,IAAI,MACL,IAAI,MAAM,IAAI,KAAK;AACnC;;AAGA,SAAS,YAAY,GAAW,GAAW,GAAmB;CAC5D,MAAM,IAAI,IAAI;CACd,MAAM,KAAK,KAAK,IAAI,KAAK;CAEzB,QAAQ,KADG,IAAI,IAAI,MACF,IAAI,IAAI,MAAM,IAAI;AACrC;;;;;;;AAQA,SAAgB,YAAY,KAAqB;CAC/C,MAAM,QAAQ,0BAA0B,KAAK,GAAG;CAChD,IAAI,CAAC,QAAQ,IAAI,OAAO;CACxB,MAAM,QAAQ,MAAM,GAAG,MAAM,GAAG,EAAE,KAAK,MAAM,OAAO,WAAW,EAAE,KAAK,CAAC,CAAC;CACxE,IAAI,MAAM,WAAW,KAAK,MAAM,MAAM,MAAM,OAAO,MAAM,CAAC,CAAC,GAAG,OAAO;CACrE,MAAM,CAAC,IAAI,IAAI,IAAI,MAAM;CAEzB,MAAM,UAAU,MAAsB;EACpC,IAAI,IAAI;EACR,KAAK,IAAI,IAAI,GAAG,IAAI,GAAG,KAAK;GAC1B,MAAM,KAAK,OAAO,GAAG,IAAI,EAAE,IAAI;GAC/B,IAAI,KAAK,IAAI,EAAE,IAAI,MAAM,OAAO;GAChC,MAAM,QAAQ,YAAY,GAAG,IAAI,EAAE;GACnC,IAAI,KAAK,IAAI,KAAK,IAAI,MAAM;GAC5B,KAAK,KAAK;EACZ;EAEA,IAAI,KAAK;EACT,IAAI,KAAK;EACT,IAAI,MAAM;EACV,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,KAAK;GAC3B,OAAO,KAAK,MAAM;GAClB,MAAM,KAAK,OAAO,KAAK,IAAI,EAAE;GAC7B,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,MAAM;GAC7B,IAAI,KAAK,GAAG,KAAK;QACZ,KAAK;EACZ;EACA,OAAO;CACT;CAEA,QAAQ,MAAM;EACZ,IAAI,KAAK,GAAG,OAAO;EACnB,IAAI,KAAK,GAAG,OAAO;EACnB,OAAO,OAAO,OAAO,CAAC,GAAG,IAAI,EAAE;CACjC;AACF"}

package/dist/component/component.d.ts

@@ -25,7 +25,7 @@ type Component<P = Record<string, unknown>> = (props: P) => MindeesNode;
  * and patches exactly that region when its signals change (the fine-grained
  * update model, à la SolidJS). Static trees never need it; reactive UIs do.
  */
-type MindeesNode = MindeesElement | KeyedRegion<any> | string | number | boolean | null | undefined | (() => MindeesNode) | MindeesNode[];
+type MindeesNode = MindeesElement | KeyedRegion<any> | PortalRegion | string | number | boolean | null | undefined | (() => MindeesNode) | MindeesNode[];
 /** The tag of an element: a host string (e.g. `"view"`) or a component function. */
 type ElementType = string | Component<never>;
 /** A virtual element: a tag, its props, and its children. */
@@ -74,6 +74,30 @@ interface KeyedRegionOptions<T> {
 declare function keyedRegion<T>(options: KeyedRegionOptions<T>): KeyedRegion<T>;
 /** Type guard: is `value` a {@link KeyedRegion}? */
 declare function isKeyedRegion(value: unknown): value is KeyedRegion;
+/** Brand identifying a portal region (children relocated to an overlay target above the tree). */
+declare const PORTAL: unique symbol;
+/**
+ * A portal: its children render into a different host parent (an overlay/root layer) than their
+ * position in the tree, while staying owned by the logical owner so reactive disposal + unmount
+ * still work. The renderer materializes it (`bindPortalChild`); build one with {@link portal}.
+ */
+interface PortalRegion {
+  readonly $$portal: typeof PORTAL;
+  /** Children to relocate, normalized to a (reactive) accessor. */
+  readonly children: () => MindeesNode;
+  /** Optional explicit host target (an `N`); else the backend's overlay root; else the local parent. Opaque to core. */
+  readonly mount: unknown;
+}
+/**
+ * Build a {@link PortalRegion} — relocate `children` to an overlay target. Pass `opts.mount` to
+ * override the target host node; otherwise the renderer uses the backend's overlay root (or, with
+ * no overlay, mounts in place — the SSR-correct default).
+ */
+declare function portal(children: MindeesNode | (() => MindeesNode), opts?: {
+  readonly mount?: unknown;
+}): PortalRegion;
+/** Type guard: is `value` a {@link PortalRegion}? */
+declare function isPortal(value: unknown): value is PortalRegion;
 interface PropsWithKey {
   key?: string | number | null;
   children?: MindeesNode;
@@ -142,5 +166,5 @@ declare function renderComponent<P>(component: Component<P>, props: P): {
 /** Whether code is currently running inside a reactive ownership scope. */
 declare function hasOwner(): boolean;
 //#endregion
-export { Component, Context, ContextProvider, ELEMENT_TYPE, ElementType, Fragment, KEYED_REGION, KeyedRegion, KeyedRegionOptions, MindeesElement, MindeesNode, SelectorEquals, createContext, createElement, createProvider, hasOwner, isElement, isKeyedRegion, keyedRegion, renderComponent };
+export { Component, Context, ContextProvider, ELEMENT_TYPE, ElementType, Fragment, KEYED_REGION, KeyedRegion, KeyedRegionOptions, MindeesElement, MindeesNode, PORTAL, PortalRegion, SelectorEquals, createContext, createElement, createProvider, hasOwner, isElement, isKeyedRegion, isPortal, keyedRegion, portal, renderComponent };
 //# sourceMappingURL=component.d.ts.map

package/dist/component/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","names":[],"sources":["../../src/component/component.ts"],"mappings":";;AAwBA;;;;;;;;;;;;;;AAA8E;AAU9E;AAAA,KAVY,SAAA,KAAc,MAAA,sBAA4B,KAAA,EAAO,CAAA,KAAM,WAAA;;;;;;;;;KAUvD,WAAA,GACR,cAAA,GAKA,WAAA,8DAMO,WAAA,IACP,WAAA;;KAGQ,WAAA,YAAuB,SAAS;;UAG3B,cAAA;EAAA,SACN,QAAA,SAAiB,YAAA;EAAA,SACjB,IAAA,EAAM,WAAA;EAAA,SACN,KAAA,EAAO,QAAA,CAAS,MAAA;EAAA,SAChB,QAAA,WAAmB,WAAA;EAAA,SACnB,GAAA;AAAA;;cAIE,YAAA;;cAGA,QAAA;;cAGA,YAAA;;;;;;;UAQI,WAAA;EAAA,SACN,OAAA,SAAgB,YAAA;EArBT;EAAA,SAuBP,IAAA,iBAAqB,CAAA;EAtBrB;EAAA,SAwBA,KAAA,GAAQ,IAAA,QAAY,CAAA,EAAG,KAAA,mBAAwB,WAAA;EAvB/C;EAAA,SAyBA,GAAA,IAAO,IAAA,EAAM,CAAA,EAAG,KAAA;EAzBb;EAAA,SA2BH,QAAA,SAAiB,WAAA;AAAA;;UAIX,kBAAA;EA3BuD;EAAA,SA6B7D,IAAA,WAAe,CAAA,qBAAsB,CAAA;EA1BqB;EAAA,SA4B1D,QAAA,GAAW,IAAA,QAAY,CAAA,EAAG,KAAA,mBAAwB,WAAA;EA5BQ;EAAA,SA8B1D,GAAA,IAAO,IAAA,EAAM,CAAA,EAAG,KAAA;EA3Bd;EAAA,SA6BF,QAAA,SAAiB,WAAA;AAAA;;iBAIZ,WAAA,IAAe,OAAA,EAAS,kBAAA,CAAmB,CAAA,IAAK,WAAA,CAAY,CAAA;AAzB5E;AAAA,iBAsCgB,aAAA,CAAc,KAAA,YAAiB,KAAA,IAAS,WAAW;AAAA,UAQzD,YAAA;EACR,GAAA;EACA,QAAA,GAAW,WAAW;AAAA;;;;;;;;iBAUR,aAAA,CACd,IAAA,EAAM,WAAA,UAAqB,QAAA,EAC3B,KAAA,IAAS,MAAA,oBAA0B,YAAA,aAChC,QAAA,EAAU,WAAA,KACZ,cAAA;;iBAea,SAAA,CAAU,KAAA,YAAiB,KAAA,IAAS,cAAc;;KAatD,cAAA,OAAqB,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAC;;UAG1B,OAAA;EAxFyC;EAAA,SA0F/C,EAAA;EAxFa;EAAA,SA0Fb,YAAA,EAAc,CAAC;AAAA;;;;AAxFa;UA+FtB,eAAA;EA3FkB;EA6FjC,GAAA,CAAI,KAAA,EAAO,CAAA;EA3Fa;EA6FxB,IAAA,IAAQ,CAAA;EA3FwB;;;;;EAiGhC,MAAA,IAAU,QAAA,GAAW,KAAA,EAAO,CAAA,KAAM,CAAA,EAAG,MAAA,GAAS,cAAA,CAAe,CAAA,UAAW,CAAA;AAAA;;iBAI1D,aAAA,IAAiB,YAAA,EAAc,CAAA,GAAI,OAAA,CAAQ,CAAA;;;;;;;;;;;iBAc3C,cAAA,IAAkB,OAAA,EAAS,OAAA,CAAQ,CAAA,GAAI,OAAA,GAAU,CAAA,GAAI,eAAA,CAAgB,CAAA;;;AA/G9C;AAIvC;;;;;;iBAuIgB,eAAA,IACd,SAAA,EAAW,SAAA,CAAU,CAAA,GACrB,KAAA,EAAO,CAAA;EACJ,IAAA,EAAM,WAAA;EAAa,OAAA;AAAA;;iBAqBR,QAAA"}
+{"version":3,"file":"component.d.ts","names":[],"sources":["../../src/component/component.ts"],"mappings":"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"}

package/dist/component/component.js

@@ -36,6 +36,24 @@ function keyedRegion(options) {
 function isKeyedRegion(value) {
 	return typeof value === "object" && value !== null && value.$$keyed === KEYED_REGION;
 }
+/** Brand identifying a portal region (children relocated to an overlay target above the tree). */
+const PORTAL = Symbol.for("mindees.portal");
+/**
+* Build a {@link PortalRegion} — relocate `children` to an overlay target. Pass `opts.mount` to
+* override the target host node; otherwise the renderer uses the backend's overlay root (or, with
+* no overlay, mounts in place — the SSR-correct default).
+*/
+function portal(children, opts) {
+	return {
+		$$portal: PORTAL,
+		children: typeof children === "function" ? children : () => children,
+		mount: opts?.mount
+	};
+}
+/** Type guard: is `value` a {@link PortalRegion}? */
+function isPortal(value) {
+	return typeof value === "object" && value !== null && value.$$portal === PORTAL;
+}
 /**
 * Create a virtual element. `type` is a host-component string or a component
 * function; `Fragment` groups children without a wrapper.
@@ -118,6 +136,6 @@ function hasOwner() {
 	return getOwner() !== null;
 }
 //#endregion
-export { ELEMENT_TYPE, Fragment, KEYED_REGION, createContext, createElement, createProvider, hasOwner, isElement, isKeyedRegion, keyedRegion, renderComponent };
+export { ELEMENT_TYPE, Fragment, KEYED_REGION, PORTAL, createContext, createElement, createProvider, hasOwner, isElement, isKeyedRegion, isPortal, keyedRegion, portal, renderComponent };
 
 //# sourceMappingURL=component.js.map