@kumikijs/runtime 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -23,6 +23,14 @@ type KumikiElementOptions = {
    * 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
@@ -89,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
@@ -324,6 +334,15 @@ type MountOptions = {
    * 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. */

package/dist/index.js

@@ -36,6 +36,8 @@ function defineKumikiElement(tagName, app, options = {}) {
 			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();
@@ -127,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();
@@ -464,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 = {};
@@ -532,6 +600,8 @@ function mount(app, target, options = {}) {
 	stateStylesEl = null;
 	ensureMotionStyles(app);
 	const slotValues = app.live;
+	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);
 	});
@@ -635,19 +705,24 @@ function mount(app, target, options = {}) {
 		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 });
@@ -655,17 +730,17 @@ function mount(app, target, options = {}) {
 		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) => {
@@ -702,6 +777,7 @@ function mount(app, target, options = {}) {
 		for (const h of anonTimers) clearInterval(h);
 		for (const h of namedTimers.values()) clearInterval(h);
 		namedTimers.clear();
+		routerUnsub?.();
 		target.replaceChildren();
 		dispatcher.dispose();
 	} };
@@ -787,7 +863,7 @@ 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);
@@ -821,7 +897,7 @@ function registerBuiltinEffects(app, navigate, getLive, rerender) {
 		name: "navigate-back",
 		cap: "nav.back",
 		invoke: overridable("nav.back", async () => {
-			history.back();
+			back();
 			return {
 				kind: "ok",
 				value: null
@@ -922,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kumikijs/runtime",
-  "version": "0.4.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",