@kumikijs/runtime 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -86,6 +86,19 @@ declare function smoke(app: AppShape, root: HTMLElement, opts?: SmokeOptions): P
 //#region src/index.d.ts
 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:
+ * `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
+ * shown — instead of escaping the DOM event handler / render uncaught. The
+ * reducer-test harness already catches it to power `expect = {panic: ...}`.
+ */
+declare class KumikiPanic extends Error {
+  readonly isKumikiPanic: true;
+  readonly location: string | undefined;
+  constructor(message: string, location?: string);
+}
 type TileNode = {
   kind: "page" | "column" | "row" | "card" | "box";
   children: TileNode[];
@@ -372,7 +385,15 @@ declare const _stdlib: {
   freshId(): string;
   now(): number;
   recordCopy(rec: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
-  unwrap(opt: unknown): unknown;
+  /**
+   * `.get` — the polymorphic unwrap for Option AND Result. Per 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
+   * `.get-err` behaved oppositely — #24.)
+   */
+  unwrap(opt: unknown): unknown; /** `panic(message)` — raise Kumiki's controlled stop-the-program signal. */
+  panic(message: unknown): never;
   optionGetOr(opt: unknown, def: unknown): unknown;
   Some(v: unknown): {
     _tag: "Some";
@@ -403,7 +424,15 @@ declare const _stdlib: {
   setDiff(a: Record<string, true> | undefined | null, b: Record<string, true> | undefined | null): Record<string, true>; /** Option(T).or / Result(T,E).or — receiver when Some/Ok, else `other`. */
   or(v: unknown, other: unknown): unknown; /** Result(T,E).map-err(fn) — maps the Err payload, passes Ok through unchanged. */
   mapErr(r: unknown, fn: (e: unknown) => unknown): unknown; /** Polymorphic `.diff`: numeric magnitude (Time/Duration) or Set difference. */
-  diff(a: unknown, b: unknown): unknown;
+  diff(a: unknown, b: unknown): unknown; /** List(T).head → Option(T). */
+  listHead(xs: unknown[] | undefined | null): unknown; /** List(T).tail → List(T) (all but the first; empty list stays empty). */
+  listTail(xs: unknown[] | undefined | null): unknown[]; /** List(T).last → Option(T). */
+  listLast(xs: unknown[] | undefined | null): unknown; /** Set(T).to-list / Option(T).to-list → List(T). */
+  toList(v: unknown): unknown[]; /** Result(T,E).get-err → E; panics (KumikiPanic) if the value is Ok. */
+  getErr(r: unknown): unknown; /** Result(T,E).to-option → Option(T): Ok(v) → Some(v), Err(_) → None. */
+  toOption(r: unknown): unknown; /** Text.parse-int → Option(Int) (truncates; mirrors `Int.parse`). */
+  parseIntOpt(s: unknown): unknown; /** Text.parse-float → Option(Float) (mirrors `Float.parse`). */
+  parseFloatOpt(s: unknown): unknown;
 };
 declare const builtinEffects: {
   storageRead(input: unknown): Promise<EffectResult>;
@@ -411,4 +440,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, 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, 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 };

package/dist/index.js

@@ -361,6 +361,27 @@ function errStr(e) {
 }
 //#endregion
 //#region src/index.ts
+/**
+* A controlled panic — Kumiki's "stop the program" signal (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
+* shown — instead of escaping the DOM event handler / render uncaught. The
+* reducer-test harness already catches it to power `expect = {panic: ...}`.
+*/
+var KumikiPanic = class extends Error {
+	isKumikiPanic = true;
+	location;
+	constructor(message, location) {
+		super(message);
+		this.name = "KumikiPanic";
+		this.location = location;
+	}
+};
+/** True for a KumikiPanic — also matches across realms where `instanceof` fails. */
+function isPanic(e) {
+	return e instanceof KumikiPanic || typeof e === "object" && e !== null && e.isKumikiPanic === true;
+}
 function parseLocation(routes, loc) {
 	const path = loc.pathname || "/";
 	const query = {};
@@ -448,7 +469,13 @@ function mount(app, target) {
 			};
 		}
 		maybeReapplyTheme(app);
-		const dom = renderTile(pickRootTile(app));
+		let dom;
+		try {
+			dom = renderTile(pickRootTile(app));
+		} catch (e) {
+			reportPanic("render", e);
+			dom = renderPanicFallback(e);
+		}
 		if (currentRoot) target.replaceChild(dom, currentRoot);
 		else target.appendChild(dom);
 		currentRoot = dom;
@@ -475,9 +502,38 @@ function mount(app, target) {
 			text: "(no root)"
 		};
 	}
+	let inPanicHandler = false;
+	/**
+	* Handle a caught live panic per 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.
+	*/
+	function handleLivePanic(location, e) {
+		reportPanic(location, e);
+		if (inPanicHandler) return;
+		const handlers = app.reducers.filter((h) => h.event.kind === "lifecycle" && h.event.name === "app.error");
+		if (handlers.length === 0) return;
+		const info = {
+			message: panicInfo(e).message,
+			location
+		};
+		inPanicHandler = true;
+		try {
+			for (const h of handlers) applyReducer(h, { $event: info });
+		} finally {
+			inPanicHandler = false;
+		}
+	}
 	function applyReducer(r, payload) {
 		if (disposed) return;
-		const result = r.apply(slotValues, payload);
+		let result;
+		try {
+			result = r.apply(slotValues, payload);
+		} catch (e) {
+			handleLivePanic(`reducer "${r.name}"`, e);
+			return;
+		}
 		for (const [k, v] of Object.entries(result.slots)) {
 			const meta = app.slots[k];
 			if (meta?.refine && !meta.refine(v)) continue;
@@ -747,6 +803,39 @@ function _setPathHelper(obj, path, value) {
 		[head]: _setPathHelper(cur[head], rest, value)
 	};
 }
+/** Message + optional source location for a caught throw (panic or otherwise). */
+function panicInfo(e) {
+	if (isPanic(e)) return {
+		message: e.message,
+		location: e.location
+	};
+	if (e instanceof Error) return {
+		message: e.message,
+		location: void 0
+	};
+	return {
+		message: String(e),
+		location: void 0
+	};
+}
+/**
+* Surface a caught live panic so the verification tiers still see it: smoke()
+* and runScenario() both patch console.error into their issue/error buffers, so
+* a controlled panic is reported as a failure rather than silently swallowed.
+*/
+function reportPanic(where, e) {
+	const { message } = panicInfo(e);
+	console.error(`[kumiki] ${isPanic(e) ? "panic" : "error"} in ${where}: ${message}`);
+}
+/** A minimal top-level fallback for a render panic with no enclosing boundary. */
+function renderPanicFallback(e) {
+	const { message, location } = panicInfo(e);
+	const div = document.createElement("div");
+	div.dataset.kumikiPanic = location ?? "";
+	div.setAttribute("role", "alert");
+	div.textContent = `Something went wrong: ${message}`;
+	return div;
+}
 function renderTile(node) {
 	const el = renderTileNode(node);
 	applyMotion(el, node.props);
@@ -1726,13 +1815,26 @@ const _stdlib = {
 			...patch
 		};
 	},
+	/**
+	* `.get` — the polymorphic unwrap for Option AND Result. Per 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
+	* `.get-err` behaved oppositely — #24.)
+	*/
 	unwrap(opt) {
 		if (opt && typeof opt === "object" && "_tag" in opt) {
 			const o = opt;
-			if (o._tag === "Some") return o._0;
+			if (o._tag === "Some" || o._tag === "Ok") return o._0;
+			if (o._tag === "None") throw new KumikiPanic("get called on None");
+			if (o._tag === "Err") throw new KumikiPanic("get called on an Err value");
 		}
 		return opt;
 	},
+	/** `panic(message)` — raise Kumiki's controlled stop-the-program signal. */
+	panic(message) {
+		throw new KumikiPanic(String(message));
+	},
 	optionGetOr(opt, def) {
 		if (opt && typeof opt === "object" && "_tag" in opt) {
 			const o = opt;
@@ -1848,6 +1950,56 @@ const _stdlib = {
 	diff(a, b) {
 		if (typeof a === "number" || typeof b === "number") return Math.abs(a - b);
 		return _stdlib.setDiff(a, b);
+	},
+	/** List(T).head → Option(T). */
+	listHead(xs) {
+		const a = xs ?? [];
+		return a.length > 0 ? _stdlib.Some(a[0]) : _stdlib.None;
+	},
+	/** List(T).tail → List(T) (all but the first; empty list stays empty). */
+	listTail(xs) {
+		return (xs ?? []).slice(1);
+	},
+	/** List(T).last → Option(T). */
+	listLast(xs) {
+		const a = xs ?? [];
+		return a.length > 0 ? _stdlib.Some(a[a.length - 1]) : _stdlib.None;
+	},
+	/** Set(T).to-list / Option(T).to-list → List(T). */
+	toList(v) {
+		if (v && typeof v === "object" && "_tag" in v) {
+			const o = v;
+			return o._tag === "Some" ? [o._0] : [];
+		}
+		if (Array.isArray(v)) return [...v];
+		if (v && typeof v === "object") return Object.keys(v);
+		return [];
+	},
+	/** Result(T,E).get-err → E; panics (KumikiPanic) if the value is Ok. */
+	getErr(r) {
+		if (r && typeof r === "object" && "_tag" in r) {
+			const t = r;
+			if (t._tag === "Err") return t._0;
+		}
+		throw new KumikiPanic("get-err called on a non-Err value");
+	},
+	/** Result(T,E).to-option → Option(T): Ok(v) → Some(v), Err(_) → None. */
+	toOption(r) {
+		if (r && typeof r === "object" && "_tag" in r) {
+			const t = r;
+			if (t._tag === "Ok") return _stdlib.Some(t._0);
+		}
+		return _stdlib.None;
+	},
+	/** Text.parse-int → Option(Int) (truncates; mirrors `Int.parse`). */
+	parseIntOpt(s) {
+		const n = Number(s);
+		return String(s).trim() !== "" && Number.isFinite(n) ? _stdlib.Some(Math.trunc(n)) : _stdlib.None;
+	},
+	/** Text.parse-float → Option(Float) (mirrors `Float.parse`). */
+	parseFloatOpt(s) {
+		const n = Number(s);
+		return String(s).trim() !== "" && Number.isFinite(n) ? _stdlib.Some(n) : _stdlib.None;
 	}
 };
 const builtinEffects = {
@@ -1942,4 +2094,4 @@ const builtinEffects = {
 	}
 };
 //#endregion
-export { _stdlib, builtinEffects, mount, runScenario, smoke };
+export { KumikiPanic, _stdlib, builtinEffects, mount, runScenario, smoke };

package/package.json

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