@zoijs/core 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to Zoijs are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and Zoijs follows
 [Semantic Versioning](https://semver.org/) (see `VERSIONING.md`).
 
+## [1.3.0] — 2026-06-26
+
+### Added
+- **`boundary(child, fallback)`.** A render-time error boundary: it renders
+  `child`, and if `child` throws **synchronously while building its markup** (a
+  setup/render error that would otherwise break the whole `mount`), it disposes the
+  partial work — so an `effect` created before the throw can't leak — and renders
+  `fallback` (a value, or `(error) => value`) instead. Catches synchronous
+  setup/render throws only; errors in reactive *updates* are already contained per
+  binding, and *async* errors belong to `@zoijs/resource` / `@zoijs/action`'s
+  `error()` state. Logs in dev, silent in production. The public surface is now
+  **nine** functions (additive MINOR). See [RFC 0004](docs/rfcs/0004-error-boundary.md).
+
 ## [1.2.0] — 2026-06-26
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoijs/core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Zoijs — a beginner-friendly, no-build, no-Virtual-DOM frontend framework. Plain HTML, CSS, and JavaScript.",
   "type": "module",
   "main": "src/index.js",

package/src/core/boundary.js

@@ -0,0 +1,34 @@
+// boundary.js — render-time error containment (RFC 0004).
+//
+// boundary(child, fallback) renders `child`; if it throws SYNCHRONOUSLY while
+// building its markup (a setup/render throw that would otherwise break the whole
+// mount), the partial work is torn down and `fallback(error)` is rendered instead.
+//
+// Errors in reactive UPDATES are already contained per-binding by the core; async
+// errors belong to @zoijs/resource / @zoijs/action. This catches the one
+// remaining case — the synchronous setup/render throw.
+
+import { createOwner, runWithOwner, disposeOwner } from "../reactivity/owner.js";
+import { isDev } from "../reactivity/env.js";
+
+/**
+ * @template C, F
+ * @param {(() => C) | C} child     a component (or value) to render
+ * @param {((error: unknown) => F) | F} fallback  a value, or (error) => value, shown if child throws
+ * @returns {C | F} the child's result, or the fallback's, for a template slot
+ */
+export function boundary(child, fallback) {
+  // Run setup in a child scope so anything it creates before a throw (notably an
+  // effect, which runs immediately) can be disposed — no zombies. On success the
+  // scope nests under the surrounding owner and is disposed with it.
+  const owner = createOwner();
+  try {
+    return runWithOwner(owner, () => (typeof child === "function" ? child() : child));
+  } catch (err) {
+    disposeOwner(owner);
+    if (isDev()) {
+      console.error("Zoijs: boundary caught an error during render; showing fallback.", err);
+    }
+    return typeof fallback === "function" ? fallback(err) : fallback;
+  }
+}

package/src/index.d.ts

@@ -144,6 +144,27 @@ export function each<T>(
   renderFn: (item: T) => TemplateResult
 ): EachResult;
 
+/**
+ * Render `child`; if it **throws synchronously while building its markup** (a
+ * setup/render error that would otherwise break the whole `mount`), tear down the
+ * partial work and render `fallback` instead. Place the call in a template slot.
+ *
+ * Catches synchronous setup/render throws only. Errors in reactive *updates* are
+ * already contained per binding by the core; *async* errors belong to
+ * `@zoijs/resource` / `@zoijs/action`'s `error()` state. It renders once (no reset
+ * — re-mount the subtree to retry), logs in dev, and is silent in production.
+ *
+ * ```ts
+ * html`<section>
+ *   ${boundary(() => RiskyWidget(), (err) => html`<p>Couldn't load this.</p>`)}
+ * </section>`
+ * ```
+ */
+export function boundary<C, F>(
+  child: (() => C) | C,
+  fallback: ((error: unknown) => F) | F
+): C | F;
+
 /** Toggle development warnings (default: `dev` is `true`). */
 export function configure(options: { dev?: boolean }): void;
 

package/src/index.js

@@ -8,6 +8,7 @@
 export { html } from "./core/html.js";
 export { mount } from "./core/mount.js";
 export { each } from "./core/each.js";
+export { boundary } from "./core/boundary.js";
 export { createState } from "./reactivity/state.js";
 export { computed } from "./reactivity/computed.js";
 export { effect } from "./reactivity/effect.js";