@kumikijs/runtime 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,3 +1,44 @@
+//#region src/element.d.ts
+/** Maps one observed attribute to a slot, with an optional parser (default: raw string). */
+type AttributeSlotBinding = {
+  slot: string;
+  parse?: (raw: string | null) => unknown;
+};
+type KumikiElementOptions = {
+  /** Host implementations for custom capabilities (the inbound seam), forwarded to mount. */providers?: Record<string, CapabilityProvider>;
+  /**
+   * Custom-capability names to surface as DOM CustomEvents on the element. For
+   * each, emitting the effect dispatches `CustomEvent(cap, { detail: input })`
+   * (bubbling, composed) and resolves ok — so a host can bind via
+   * `addEventListener(cap, …)` / framework `@cap`. A `providers[cap]` entry
+   * takes precedence over the passthrough for the same capability.
+   */
+  events?: string[]; /** Observed attributes mapped to slots; updates flow in on connect and on change. */
+  attributeSlots?: Record<string, AttributeSlotBinding>;
+  /**
+   * Render into an open shadow root for full style isolation: the app's
+   * theme/motion/state `<style>` nodes are injected into the shadow root (not the
+   * document head), so host-page CSS does not bleed in and Kumiki's CSS does not
+   * leak out. Default: false (light DOM — the runtime's document-level styles
+   * apply, matching a standalone Kumiki page).
+   */
+  shadow?: boolean;
+  /**
+   * Routing source forwarded to mount (#36). An embedded element rarely owns the
+   * top-level URL, so a routed Kumiki app inside it should usually use
+   * `"memory"` (an in-memory path) rather than the default `"history"`, which
+   * reads/writes the host page's location/history.
+   */
+  router?: "history" | "memory"; /** Initial path for the memory router (default `"/"`). */
+  initialPath?: string;
+};
+/**
+ * Register `app` as the custom element `tagName`. Idempotent: if the tag is
+ * already defined this is a no-op (so re-imports / HMR don't throw). Requires a
+ * DOM environment.
+ */
+declare function defineKumikiElement(tagName: string, app: AppShape | (() => AppShape), options?: KumikiElementOptions): void;
+//#endregion
 //#region src/scenario.d.ts
 /** One thing to do to the app. Exactly one field should be set. */
 type Action = {
@@ -56,6 +97,8 @@ type ScenarioReport = {
 };
 declare function runScenario(app: AppShape, root: HTMLElement, scenario: Scenario, opts?: {
   settleMs?: number;
+  router?: "history" | "memory";
+  initialPath?: string;
 }): Promise<ScenarioReport>;
 //#endregion
 //#region src/smoke.d.ts
@@ -87,7 +130,7 @@ declare function smoke(app: AppShape, root: HTMLElement, opts?: SmokeOptions): P
 type RefinementCheck = (v: unknown) => boolean;
 type EventHandler = (el: Record<string, unknown>) => void;
 /**
- * A controlled panic — Kumiki's "stop the program" signal (spec/stdlib.md §2.2:
+ * A controlled panic — Kumiki's "stop the program" signal (docs/spec/stdlib.md §2.2:
  * `panic(message)`; `Option/Result.get` on the empty case; `Result.get-err` on
  * `Ok`). On the live path a panic is caught — the dispatch episode is rolled
  * back (no partial slot writes) and an error boundary / top-level fallback is
@@ -264,8 +307,42 @@ type EffectResult = {
   kind: "err";
   value: unknown;
 };
+/**
+ * A host-supplied implementation for a custom capability (one registered via
+ * `kumiki.caps.json`). This is Kumiki's inbound ecosystem seam: arbitrary JS /
+ * npm libraries live here, behind a typed, mockable capability boundary, so the
+ * Kumiki core stays pure (no language-level FFI). `input` is the effect's
+ * (already `map-request`-mapped) request; the return may be sync or async.
+ */
+type CapabilityProvider = (input: unknown, caps: CapabilityRegistry) => Promise<EffectResult> | EffectResult;
 type CapabilityRegistry = {
-  has(cap: string): boolean;
+  has(cap: string): boolean; /** The host provider registered for `cap` at mount, or undefined. */
+  provider(cap: string): CapabilityProvider | undefined;
+};
+/** Options accepted by `mount`. */
+type MountOptions = {
+  /** Host implementations for custom capabilities, keyed by capability name. */providers?: Record<string, CapabilityProvider>;
+  /**
+   * Where Kumiki injects its `<style>` nodes (motion / theme / state styles).
+   * Defaults to `document` (styles go in `<head>`). Pass a `ShadowRoot` to keep
+   * them encapsulated — used by `defineKumikiElement({ shadow: true })`.
+   */
+  styleRoot?: Document | ShadowRoot;
+  /**
+   * The element whose inline style carries theme background/foreground/font
+   * (the `<body>` equivalent). Defaults to `document.body`; the shadow element
+   * passes its in-shadow container so theming stays encapsulated.
+   */
+  styleHost?: HTMLElement;
+  /**
+   * Routing source (#36). `"history"` (default) reads/writes the ambient
+   * document `location` / `history`. `"memory"` holds the current path in
+   * memory and never touches `history.*` — for embedded / sandboxed hosts (the
+   * docs playground `srcdoc`, a Web Component) where the Kumiki app does not own
+   * the top-level URL and `history.pushState` throws in an opaque origin.
+   */
+  router?: "history" | "memory"; /** Initial path for the memory router (default `"/"`). Ignored in history mode. */
+  initialPath?: string;
 };
 type RouteEntry = {
   pattern: string; /** Returns the TileNode for this route given the current state. */
@@ -301,7 +378,7 @@ type AppShape = {
   live?: Record<string, unknown>;
   _rerender?: () => void;
 };
-declare function mount(app: AppShape, target: HTMLElement): {
+declare function mount(app: AppShape, target: HTMLElement, options?: MountOptions): {
   dispose: () => void;
 };
 type TestResult = {
@@ -386,7 +463,7 @@ declare const _stdlib: {
   now(): number;
   recordCopy(rec: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
   /**
-   * `.get` — the polymorphic unwrap for Option AND Result. Per spec/stdlib.md
+   * `.get` — the polymorphic unwrap for Option AND Result. Per docs/spec/stdlib.md
    * §2.2 it PANICS on the empty case (`None` / `Err`); `Some(v)` / `Ok(v)`
    * unwrap to `v`. A plain (non-variant) value passes through unchanged. (Before
    * v0.3 this returned the value unchanged on the empty case, so `.get` and
@@ -440,4 +517,4 @@ declare const builtinEffects: {
   httpFetch(method: string, input: unknown, baseUrl: string): Promise<EffectResult>;
 };
 //#endregion
-export { type Action, AppShape, CapabilityRegistry, EffectResult, type EffectScript, EffectSpec, EmitSpec, EventHandler, type Expect, KumikiPanic, RedirectEntry, ReducerSpec, RefinementCheck, RouteEntry, type Scenario, type ScenarioReport, type ScenarioStep, SlotMeta, type SmokeIssue, type SmokeOptions, type SmokePhase, type SmokeReport, type StepResult, TestResult, Theme, ThemeValue, TileNode, TileProps, _stdlib, builtinEffects, mount, runScenario, smoke };
+export { type Action, AppShape, type AttributeSlotBinding, CapabilityProvider, CapabilityRegistry, EffectResult, type EffectScript, EffectSpec, EmitSpec, EventHandler, type Expect, type KumikiElementOptions, KumikiPanic, MountOptions, RedirectEntry, ReducerSpec, RefinementCheck, RouteEntry, type Scenario, type ScenarioReport, type ScenarioStep, SlotMeta, type SmokeIssue, type SmokeOptions, type SmokePhase, type SmokeReport, type StepResult, TestResult, Theme, ThemeValue, TileNode, TileProps, _stdlib, builtinEffects, defineKumikiElement, mount, runScenario, smoke };

package/dist/index.js

@@ -1,3 +1,87 @@
+//#region src/element.ts
+/**
+* Register `app` as the custom element `tagName`. Idempotent: if the tag is
+* already defined this is a no-op (so re-imports / HMR don't throw). Requires a
+* DOM environment.
+*/
+function defineKumikiElement(tagName, app, options = {}) {
+	if (typeof customElements === "undefined") throw new Error("defineKumikiElement requires a DOM environment (customElements is undefined).");
+	if (customElements.get(tagName)) return;
+	const makeApp = typeof app === "function" ? app : () => app;
+	const attributeSlots = options.attributeSlots ?? {};
+	const observed = Object.keys(attributeSlots);
+	const buildProviders = (el) => {
+		const merged = {};
+		for (const cap of options.events ?? []) merged[cap] = (input) => {
+			el.dispatchEvent(new CustomEvent(cap, {
+				detail: input,
+				bubbles: true,
+				composed: true
+			}));
+			return {
+				kind: "ok",
+				value: null
+			};
+		};
+		return Object.assign(merged, options.providers ?? {});
+	};
+	class KumikiAppElement extends HTMLElement {
+		static get observedAttributes() {
+			return observed;
+		}
+		handle = null;
+		app = null;
+		connectedCallback() {
+			if (this.handle) return;
+			this.app = makeApp();
+			let target = this;
+			const mountOpts = { providers: buildProviders(this) };
+			if (options.router) mountOpts.router = options.router;
+			if (options.initialPath !== void 0) mountOpts.initialPath = options.initialPath;
+			if (options.shadow) {
+				const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
+				root.replaceChildren();
+				const container = document.createElement("div");
+				root.appendChild(container);
+				target = container;
+				mountOpts.styleRoot = root;
+				mountOpts.styleHost = container;
+			}
+			this.handle = mount(this.app, target, mountOpts);
+			for (const attr of observed) if (this.hasAttribute(attr)) this.applyAttr(attr, this.getAttribute(attr));
+		}
+		disconnectedCallback() {
+			this.handle?.dispose();
+			this.handle = null;
+		}
+		attributeChangedCallback(name, _old, value) {
+			if (this.handle) this.applyAttr(name, value);
+		}
+		applyAttr(name, raw) {
+			const binding = attributeSlots[name];
+			if (!binding) return;
+			this.setSlot(binding.slot, binding.parse ? binding.parse(raw) : raw);
+		}
+		/** Write a live slot (respects its refinement) and re-render. */
+		setSlot(name, value) {
+			this.app?._setSlot?.(name, value);
+		}
+		/** Write several live slots at once. */
+		setSlots(values) {
+			for (const [name, value] of Object.entries(values)) this.setSlot(name, value);
+		}
+		/** Read a single live slot value. */
+		getSlot(name) {
+			return this.app?.live?.[name];
+		}
+		/** A snapshot of the current live slot values. */
+		get slots() {
+			return { ...this.app?.live ?? {} };
+		}
+	}
+	customElements.define(tagName, KumikiAppElement);
+}
+//#endregion
 //#region src/scenario.ts
 const settle$1 = (ms) => new Promise((r) => setTimeout(r, ms));
 async function runScenario(app, root, scenario, opts = {}) {
@@ -45,9 +129,12 @@ async function runScenario(app, root, scenario, opts = {}) {
 		};
 	};
 	const dispatchable = app;
+	const mountOpts = {};
+	if (opts.router) mountOpts.router = opts.router;
+	if (opts.initialPath !== void 0) mountOpts.initialPath = opts.initialPath;
 	try {
 		try {
-			mount(app, root);
+			mount(app, root, mountOpts);
 		} catch (e) {
 			steps.push(mkStep(void 0, "mount", [`mount threw: ${errStr$1(e)}`], [], app, root, []));
 			return finish();
@@ -362,7 +449,7 @@ function errStr(e) {
 //#endregion
 //#region src/index.ts
 /**
-* A controlled panic — Kumiki's "stop the program" signal (spec/stdlib.md §2.2:
+* A controlled panic — Kumiki's "stop the program" signal (docs/spec/stdlib.md §2.2:
 * `panic(message)`; `Option/Result.get` on the empty case; `Result.get-err` on
 * `Ok`). On the live path a panic is caught — the dispatch episode is rolled
 * back (no partial slot writes) and an error boundary / top-level fallback is
@@ -382,6 +469,69 @@ var KumikiPanic = class extends Error {
 function isPanic(e) {
 	return e instanceof KumikiPanic || typeof e === "object" && e !== null && e.isKumikiPanic === true;
 }
+function historyRouter() {
+	return {
+		read: () => ({
+			pathname: location.pathname,
+			search: location.search,
+			hash: location.hash
+		}),
+		push: (p) => history.pushState(null, "", p),
+		replace: (p) => history.replaceState(null, "", p),
+		back: () => history.back(),
+		subscribe: (cb) => {
+			const h = () => cb();
+			window.addEventListener("popstate", h);
+			return () => window.removeEventListener("popstate", h);
+		}
+	};
+}
+/** Split a raw path into the `{ pathname, search, hash }` parseLocation reads. */
+function splitPath(p) {
+	let rest = p || "/";
+	let hash = "";
+	const hi = rest.indexOf("#");
+	if (hi !== -1) {
+		hash = rest.slice(hi);
+		rest = rest.slice(0, hi);
+	}
+	let search = "";
+	const qi = rest.indexOf("?");
+	if (qi !== -1) {
+		search = rest.slice(qi);
+		rest = rest.slice(0, qi);
+	}
+	return {
+		pathname: rest || "/",
+		search,
+		hash
+	};
+}
+function memoryRouter(initialPath = "/") {
+	const stack = [initialPath || "/"];
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		read: () => splitPath(stack[stack.length - 1] ?? "/"),
+		push: (p) => {
+			stack.push(p);
+		},
+		replace: (p) => {
+			stack[stack.length - 1] = p;
+		},
+		back: () => {
+			if (stack.length > 1) {
+				stack.pop();
+				for (const l of listeners) l();
+			}
+		},
+		subscribe: (cb) => {
+			listeners.add(cb);
+			return () => {
+				listeners.delete(cb);
+			};
+		}
+	};
+}
 function parseLocation(routes, loc) {
 	const path = loc.pathname || "/";
 	const query = {};
@@ -439,15 +589,20 @@ function emptyRoute() {
 		hash: null
 	};
 }
-function mount(app, target) {
+function mount(app, target, options = {}) {
 	if (!app.live) {
 		app.live = {};
 		for (const [k, v] of Object.entries(app.slots)) app.live[k] = v.value;
 	}
 	if (!("route" in app.live)) app.live.route = emptyRoute();
+	currentStyleRoot = options.styleRoot ?? document;
+	currentStyleHost = options.styleHost ?? null;
+	stateStylesEl = null;
 	ensureMotionStyles(app);
 	const slotValues = app.live;
-	const dispatcher = makeEffectDispatcher(app, makeCapabilityRegistry(app.caps), (effect, outcome, value, key) => {
+	const router = options.router === "memory" ? memoryRouter(options.initialPath) : historyRouter();
+	let routerUnsub;
+	const dispatcher = makeEffectDispatcher(app, makeCapabilityRegistry(app.caps, options.providers), (effect, outcome, value, key) => {
 		handleEffectResult(effect, outcome, value, key);
 	});
 	let currentRoot = null;
@@ -504,7 +659,7 @@ function mount(app, target) {
 	}
 	let inPanicHandler = false;
 	/**
-	* Handle a caught live panic per spec/lifecycle.md §7.2: the dispatch episode
+	* Handle a caught live panic per docs/spec/lifecycle.md §7.2: the dispatch episode
 	* is already rolled back (the caller never applied the failed result), so we
 	* surface it (console.error → smoke/scenario see it) and fire the `app.error`
 	* reducer(s) with `$event = PanicInfo`, exactly as §7.2.3 specifies.
@@ -550,19 +705,24 @@ function mount(app, target) {
 		render();
 	}
 	function handleEffectResult(effect, outcome, value, key) {
-		for (const r of app.reducers) if (r.event.kind === "effect" && r.event.effect === effect && r.event.outcome === outcome) applyReducer(r, {
-			$1: value,
-			$2: key
-		});
+		let matched = 0;
+		for (const r of app.reducers) if (r.event.kind === "effect" && r.event.effect === effect && r.event.outcome === outcome) {
+			applyReducer(r, {
+				$1: value,
+				$2: key
+			});
+			matched++;
+		}
+		if (outcome === "err" && matched === 0) reportUnhandledEffectError(effect, value);
 	}
 	function updateRoute(newPath, replace) {
-		if (replace) history.replaceState(null, "", newPath);
-		else history.pushState(null, "", newPath);
+		if (replace) router.replace(newPath);
+		else router.push(newPath);
 		syncRouteFromLocation();
 	}
 	function syncRouteFromLocation() {
 		const oldRoute = slotValues.route;
-		const newRoute = parseLocation(app.routes, location);
+		const newRoute = parseLocation(app.routes, router.read());
 		slotValues.route = newRoute;
 		if (oldRoute && oldRoute.pattern !== newRoute.pattern) {
 			for (const r of app.reducers) if (r.event.kind === "lifecycle" && r.event.name === `route.leave(${JSON.stringify(oldRoute.pattern)})`) applyReducer(r, { $route: oldRoute });
@@ -570,17 +730,17 @@ function mount(app, target) {
 		for (const r of app.reducers) if (r.event.kind === "lifecycle" && r.event.name === `route.enter(${JSON.stringify(newRoute.pattern)})`) applyReducer(r, { $route: newRoute });
 		render();
 	}
-	registerBuiltinEffects(app, updateRoute, () => slotValues, () => render());
+	registerBuiltinEffects(app, updateRoute, () => router.back(), () => slotValues, () => render());
 	lastAppliedThemeName = null;
 	applyThemeDefaults(app);
 	lastAppliedThemeName = app.live?.[app.themeName ?? ""] ?? app.themeName ?? null;
 	if (app.routes && app.routes.length > 0) {
-		for (const r of app.routes) if ("redirectTo" in r && matchPattern(r.pattern, location.pathname)) {
-			history.replaceState(null, "", r.redirectTo);
+		for (const r of app.routes) if ("redirectTo" in r && matchPattern(r.pattern, router.read().pathname)) {
+			router.replace(r.redirectTo);
 			break;
 		}
-		slotValues.route = parseLocation(app.routes, location);
-		window.addEventListener("popstate", () => syncRouteFromLocation());
+		slotValues.route = parseLocation(app.routes, router.read());
+		routerUnsub = router.subscribe(syncRouteFromLocation);
 	}
 	app._rerender = render;
 	app._dispatch = (reducerName, el) => {
@@ -617,13 +777,17 @@ function mount(app, target) {
 		for (const h of anonTimers) clearInterval(h);
 		for (const h of namedTimers.values()) clearInterval(h);
 		namedTimers.clear();
+		routerUnsub?.();
 		target.replaceChildren();
 		dispatcher.dispose();
 	} };
 }
-function makeCapabilityRegistry(allowed) {
+function makeCapabilityRegistry(allowed, providers) {
 	const ok = new Set(allowed);
-	return { has: (c) => ok.has(c) };
+	return {
+		has: (c) => ok.has(c),
+		provider: (c) => providers?.[c]
+	};
 }
 function makeEffectDispatcher(app, caps, onResult) {
 	const state = {
@@ -699,44 +863,51 @@ function makeEffectDispatcher(app, caps, onResult) {
 		}
 	};
 }
-function registerBuiltinEffects(app, navigate, getLive, rerender) {
+function registerBuiltinEffects(app, navigate, back, getLive, rerender) {
+	const overridable = (cap, fn) => {
+		return async (input, caps) => {
+			const p = caps.provider(cap);
+			if (p) return p(input, caps);
+			return fn(input);
+		};
+	};
 	app.effects.navigate = {
 		name: "navigate",
 		cap: "nav.push",
-		invoke: async (input) => {
+		invoke: overridable("nav.push", async (input) => {
 			navigate(buildPath(input), false);
 			return {
 				kind: "ok",
 				value: null
 			};
-		}
+		})
 	};
 	app.effects["navigate-replace"] = {
 		name: "navigate-replace",
 		cap: "nav.replace",
-		invoke: async (input) => {
+		invoke: overridable("nav.replace", async (input) => {
 			navigate(buildPath(input), true);
 			return {
 				kind: "ok",
 				value: null
 			};
-		}
+		})
 	};
 	app.effects["navigate-back"] = {
 		name: "navigate-back",
 		cap: "nav.back",
-		invoke: async () => {
-			history.back();
+		invoke: overridable("nav.back", async () => {
+			back();
 			return {
 				kind: "ok",
 				value: null
 			};
-		}
+		})
 	};
 	app.effects.toast = {
 		name: "toast",
 		cap: "notification.show",
-		invoke: async (input) => {
+		invoke: overridable("notification.show", async (input) => {
 			const t = input;
 			const banner = document.createElement("div");
 			banner.style.cssText = "position:fixed;bottom:24px;right:24px;padding:8px 16px;background:#1a1a1a;color:#fff;border-radius:8px;z-index:9999;";
@@ -747,18 +918,18 @@ function registerBuiltinEffects(app, navigate, getLive, rerender) {
 				kind: "ok",
 				value: null
 			};
-		}
+		})
 	};
 	app.effects.log = {
 		name: "log",
 		cap: "log.write",
-		invoke: async (input) => {
+		invoke: overridable("log.write", async (input) => {
 			console.log("[kumiki]", input);
 			return {
 				kind: "ok",
 				value: null
 			};
-		}
+		})
 	};
 }
 function buildPath(x) {
@@ -827,6 +998,19 @@ function reportPanic(where, e) {
 	const { message } = panicInfo(e);
 	console.error(`[kumiki] ${isPanic(e) ? "panic" : "error"} in ${where}: ${message}`);
 }
+/**
+* Surface an effect `err` result that no `.err` reducer consumes (#37). A failed
+* capability must never fail silently — the storage-unavailable case (sandbox /
+* private mode) otherwise looks like the app does nothing. Reported via
+* console.error so the verification tiers (smoke / runScenario, which patch
+* console.error) flag it, consistent with the v0.3 panic model. Production noise
+* is the app's own choice: wire an `.err` reducer to handle (or deliberately
+* ignore) the error.
+*/
+function reportUnhandledEffectError(effect, value) {
+	const message = value && typeof value === "object" && "message" in value ? String(value.message) : String(value);
+	console.error(`[kumiki] effect "${effect}" returned an error with no .err reducer: ${message}`);
+}
 /** A minimal top-level fallback for a render panic with no enclosing boundary. */
 function renderPanicFallback(e) {
 	const { message, location } = panicInfo(e);
@@ -1215,10 +1399,8 @@ function applyResponsive(_el, raw, set) {
 		return;
 	}
 }
-let animationStylesInjected = false;
 function ensureAnimationStyles() {
-	if (animationStylesInjected) return;
-	animationStylesInjected = true;
+	if (findStyleNode("kumiki-animations")) return;
 	const css = `
 @keyframes kumiki-fade { from { opacity: 0 } to { opacity: 1 } }
 @keyframes kumiki-slide-up { from { transform: translateY(8px); opacity: 0 } to { transform: translateY(0); opacity: 1 } }
@@ -1234,7 +1416,7 @@ function ensureAnimationStyles() {
 	const style = document.createElement("style");
 	style.id = "kumiki-animations";
 	style.appendChild(document.createTextNode(css));
-	document.head.appendChild(style);
+	appendStyleNode(style);
 }
 function applyTransition(el, props) {
 	if (!props) return;
@@ -1278,15 +1460,32 @@ function motionCss(name, spec) {
 	return [`@keyframes ${cls} { from { ${from} } to { ${to} } }`, `.${cls} { animation-name: ${cls}; animation-duration: ${motionDuration(s.duration)}; animation-timing-function: ${easing}; animation-iteration-count: ${iteration}; animation-direction: ${direction}; animation-fill-mode: both; }`].join("\n");
 }
 /** Inject the app's motion keyframes + a `prefers-reduced-motion` guard at mount. */
+let currentStyleRoot = null;
+let currentStyleHost = null;
+/** Find a Kumiki style node by id within the active style root. */
+function findStyleNode(id) {
+	return (currentStyleRoot ?? document).getElementById(id);
+}
+/** Append a style node to the active style root (document head, or a shadow root). */
+function appendStyleNode(style) {
+	const root = currentStyleRoot ?? document;
+	const head = root.head;
+	if (head) head.appendChild(style);
+	else root.appendChild(style);
+}
+/** The element that carries body-level theme styles (background/fg/font). */
+function styleHostEl() {
+	return currentStyleHost ?? document.body;
+}
 function ensureMotionStyles(app) {
 	const motions = app.motions ?? {};
 	const rules = Object.entries(motions).map(([name, spec]) => motionCss(name, spec));
 	rules.push(`@media (prefers-reduced-motion: reduce) { .kumiki-motion, .kumiki-anim { animation: none !important } }`);
-	let style = document.getElementById("kumiki-motions");
+	let style = findStyleNode("kumiki-motions");
 	if (!style) {
 		style = document.createElement("style");
 		style.id = "kumiki-motions";
-		document.head.appendChild(style);
+		appendStyleNode(style);
 	}
 	style.textContent = rules.join("\n");
 }
@@ -1313,9 +1512,12 @@ function applyStateStyles(el, props) {
 		el.dataset.kumikiState = el.dataset.kumikiState ? `${el.dataset.kumikiState} ${id}` : id;
 		const decls = stateStyleDecls(sub);
 		if (!stateStylesEl) {
-			stateStylesEl = document.createElement("style");
-			stateStylesEl.id = "kumiki-state-styles";
-			document.head.appendChild(stateStylesEl);
+			stateStylesEl = findStyleNode("kumiki-state-styles");
+			if (!stateStylesEl) {
+				stateStylesEl = document.createElement("style");
+				stateStylesEl.id = "kumiki-state-styles";
+				appendStyleNode(stateStylesEl);
+			}
 		}
 		const selector = state === "hover" ? ":hover" : state === "focus" ? ":focus" : state === "active" ? ":active" : state === "disabled" ? ":disabled" : "[data-kumiki-selected]";
 		stateStylesEl.appendChild(document.createTextNode(`[data-kumiki-state~="${id}"]${selector} { ${decls} }\n`));
@@ -1351,12 +1553,13 @@ function applyThemeDefaults(app) {
 	const colors = theme.colors ?? {};
 	const typography = theme.typography ?? {};
 	const sizes = typography.size ?? {};
-	if (typeof colors.bg === "string") document.body.style.background = colors.bg;
-	if (typeof colors.fg === "string") document.body.style.color = colors.fg;
-	if (typeof typography.family === "string") document.body.style.fontFamily = typography.family;
-	if (typeof sizes.md === "string") document.body.style.fontSize = sizes.md;
-	if (typeof typography["line-height"] === "string") document.body.style.lineHeight = String(typography["line-height"]);
-	const prior = document.getElementById("kumiki-theme-base");
+	const host = styleHostEl();
+	if (typeof colors.bg === "string") host.style.background = colors.bg;
+	if (typeof colors.fg === "string") host.style.color = colors.fg;
+	if (typeof typography.family === "string") host.style.fontFamily = typography.family;
+	if (typeof sizes.md === "string") host.style.fontSize = sizes.md;
+	if (typeof typography["line-height"] === "string") host.style.lineHeight = String(typography["line-height"]);
+	const prior = findStyleNode("kumiki-theme-base");
 	if (prior) prior.remove();
 	const css = document.createElement("style");
 	css.id = "kumiki-theme-base";
@@ -1399,7 +1602,7 @@ function applyThemeDefaults(app) {
 }
 [data-kumiki-tile="markdown"] p { margin: 0 0 12px; }
 `));
-	document.head.appendChild(css);
+	appendStyleNode(css);
 }
 function themeShadow(theme, key) {
 	const shadow = theme.shadow;
@@ -1816,7 +2019,7 @@ const _stdlib = {
 		};
 	},
 	/**
-	* `.get` — the polymorphic unwrap for Option AND Result. Per spec/stdlib.md
+	* `.get` — the polymorphic unwrap for Option AND Result. Per docs/spec/stdlib.md
 	* §2.2 it PANICS on the empty case (`None` / `Err`); `Some(v)` / `Ok(v)`
 	* unwrap to `v`. A plain (non-variant) value passes through unchanged. (Before
 	* v0.3 this returned the value unchanged on the empty case, so `.get` and
@@ -2094,4 +2297,4 @@ const builtinEffects = {
 	}
 };
 //#endregion
-export { KumikiPanic, _stdlib, builtinEffects, mount, runScenario, smoke };
+export { KumikiPanic, _stdlib, builtinEffects, defineKumikiElement, mount, runScenario, smoke };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kumikijs/runtime",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Kumiki DOM runtime — mounts compiled Kumiki apps, dispatches effects, manages the signal graph.",
   "license": "Apache-2.0",