@askrjs/askr 0.3.0 → 0.4.0

package/README.md

@@ -1,24 +1,46 @@
 # Askr
 
-[![CI](https://github.com/askrjs/askr/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/askrjs/askr/actions/workflows/ci.yml)
+[![CI](https://github.com/askrjs/askr/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/askrjs/askr/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/%40askrjs%2Faskr.svg)](https://www.npmjs.com/package/@askrjs/askr)
 
-Askr is a lane-scheduled UI runtime for TypeScript applications. Its
-single-threaded scheduler serializes queued framework work; it is not a
-message-passing actor system. Askr provides explicit reactivity, routed
-application startup, server-side rendering, and static-site generation
-entrypoints.
+A TypeScript UI runtime with getter-based state, fine-grained bindings,
+transactional commits with rollback, and one route graph for SPA, SSR, and SSG.
+
+## How Askr works
+
+- **Getter-based state with automatic tracking.** `state()` gives you a getter
+  and a setter. Calling the getter while a component renders subscribes that
+  component; you do not list dependencies for state or `derive()`.
+- **Component re-render plus fine-grained bindings.** A state change re-runs
+  the components that read it. A function child or prop, such as
+  `{() => count()}`, is a binding: it updates its own DOM node without
+  re-running the component around it.
+- **Transactional commits with rollback.** Each render is prepared and applied
+  as one transaction. If a component throws or the DOM commit fails, Askr
+  restores the last committed DOM, and the listeners, refs, resources, and
+  subscriptions created by the failed render never become live. The error goes
+  to the nearest `ErrorBoundary`, or is rethrown when no boundary catches it.
+  Bindings keep showing current state across a rollback.
+- **One route graph.** The registry from `createRouteRegistry()` drives browser
+  navigation (`createSPA`), hydration (`hydrateSPA`), server rendering
+  (`renderRouteRequest`), and static generation (`createStaticGen`).
+
+Writes made in one event handler are batched into one scheduled render, and
+queued work runs in a fixed order. See [Update ordering](docs/concepts/determinism.md)
+for exactly what Askr guarantees and what it does not.
 
 ## Quick Start
 
-```ts
+```tsx
 import { state } from '@askrjs/askr';
 import { createIsland } from '@askrjs/askr/boot';
 
 function Counter() {
   const [count, setCount] = state(0);
 
-  return <button onClick={() => setCount((value) => value + 1)}>{count()}</button>;
+  return (
+    <button onClick={() => setCount((value) => value + 1)}>{count()}</button>
+  );
 }
 
 createIsland({ root: document.body, component: Counter });
@@ -35,23 +57,34 @@ The tuple form above and the direct callable form below are equivalent; see
 `selector()`, `defineScope()`, `readScope()`, `getSignal()`, and the JSX
 runtime exports.
 
-Public APIs prefer functions and closures over classes. Lexical ownership uses
-`defineScope()` and `readScope()`; there are no compatibility aliases for the
-clean-break vocabulary.
+Public APIs are mostly functions and closures. Error classes such as
+`RouteDataLoadError` and `SSRDataMissingError` live on their subpaths.
+Lexical ownership uses `defineScope()` and `readScope()`;
+there are no compatibility aliases for the clean-break vocabulary.
 
 App startup, routing, async resources, data helpers, and error boundaries live
 on their own subpaths.
 
-### Explicit reactivity
+### Getter-based state
 
 State is read through getter functions and updated through setter functions.
+Reads are explicit calls, but dependency tracking is automatic: a component
+re-renders when state it read during its last committed render changes.
+
+`state()`, `derive()`, `selector()`, `resource()`, and the other render-scoped
+primitives are hooks in the React sense. Each call is matched to its slot by
+call position, so call them unconditionally and in the same order on every
+render; the runtime throws when the order changes (see
+[Runtime Enforcement](docs/concepts/runtime-enforcement.md)). `resource()`
+takes a dependency array that decides when its loader re-runs.
 
 #### State usage forms
 
 `state()` returns one callable state cell that is also iterable. Destructuring
-it gives the cell as the getter and its `.set()` method as the setter:
+it gives the cell as the getter and its `.set()` method as the setter. Call
+`state()` inside a component function:
 
-```ts
+```tsx
 const [count, setCount] = state(0);
 console.log(count());
 setCount(1);
@@ -94,27 +127,26 @@ createSPA({
 
 `resource()` manages async work with cancellation support.
 
-```ts
+```tsx
 import { resource } from '@askrjs/askr/resources';
 
 function Data({ id }: { id: string }) {
-  const data = resource(async ({ signal }) => {
-    const response = await fetch(`/api/${id}`, { signal });
-    return response.json();
-  }, [id]);
+  const data = resource(
+    async ({ signal }) => {
+      const response = await fetch(`/api/${id}`, { signal });
+      return response.json();
+    },
+    [id]
+  );
 
   if (data.pending) return <div>Loading...</div>;
   if (data.error) return <div>Failed to load</div>;
-return <div>{data.value.name}</div>;
+  return <div>{data.value?.name}</div>;
 }
 ```
 
-`@askrjs/askr/data` is the canonical entrypoint for all query, mutation,
-invalidation, and data-runtime helpers. The root package retains query creation
-and collection, definition and serving, prefetch, and hydration exports for
-compatibility with existing applications. Mutation, invalidation, and
-data-runtime control remain subpath-only. New code should import the whole data surface from
-`@askrjs/askr/data` rather than split related imports across entrypoints.
+`@askrjs/askr/data` is the only entrypoint for query, mutation, invalidation,
+and data-runtime helpers; the root package does not re-export them.
 
 ### Developer error boundaries
 
@@ -125,7 +157,7 @@ a `resetKey` tied to your app state. The boundary protects both initial mount
 and scheduled post-mount updates. Portal content follows its logical writer
 boundary and can also recover through a boundary around its host.
 
-```ts
+```tsx
 import { ErrorBoundary } from '@askrjs/askr/components';
 
 function App() {
@@ -139,7 +171,7 @@ function App() {
 
 ## Documentation
 
-- [Documentation Index](docs/index.md)
+- [Documentation Index](docs/README.md)
 - [Installation](docs/getting-started/installation.md)
 - [Quick Start](docs/getting-started/quick-start.md)
 - [State Guide](docs/guides/state.md)
@@ -147,7 +179,7 @@ function App() {
 - [Resources Guide](docs/guides/resources.md)
 - [SSG Guide](docs/guides/ssg.md)
 - [Runtime Enforcement](docs/concepts/runtime-enforcement.md)
-- [Determinism](docs/concepts/determinism.md)
+- [Update Ordering](docs/concepts/determinism.md)
 - [API Reference](docs/reference/api.md)
 
 ## Release Notes

package/capabilities.json

@@ -6,12 +6,22 @@
       "intent": "reactive state and derived views",
       "package": "@askrjs/askr",
       "import": "@askrjs/askr",
-      "exports": ["state", "derive", "selector", "For"],
+      "exports": ["state", "derive", "selector"],
       "constraints": ["component render scope", "stable call order"],
-      "stability": "stable",
+      "stability": "preview",
       "docs": "https://github.com/askrjs/askr/blob/main/docs/guides/state.md",
       "docsPath": "docs/guides/state.md"
     },
+    {
+      "intent": "declarative control flow",
+      "package": "@askrjs/askr",
+      "import": "@askrjs/askr/control",
+      "exports": ["For", "Show", "Case", "Match"],
+      "constraints": ["control boundaries keep their rendered ranges"],
+      "stability": "preview",
+      "docs": "https://github.com/askrjs/askr/blob/main/docs/guides/control-flow.md",
+      "docsPath": "docs/guides/control-flow.md"
+    },
     {
       "intent": "data queries and mutations",
       "package": "@askrjs/askr",
@@ -28,7 +38,7 @@
         "fetches are cancellable",
         "query collections require component render scope"
       ],
-      "stability": "stable",
+      "stability": "preview",
       "docs": "https://github.com/askrjs/askr/blob/main/docs/core/data.md",
       "docsPath": "docs/core/data.md"
     },
@@ -40,7 +50,7 @@
       "constraints": [
         "fixtures are test-only and do not perform network requests"
       ],
-      "stability": "stable",
+      "stability": "preview",
       "docs": "https://github.com/askrjs/askr/blob/main/docs/contributing/testing.md",
       "docsPath": "docs/contributing/testing.md"
     },
@@ -50,7 +60,7 @@
       "import": "@askrjs/askr/router",
       "exports": ["route", "Link", "navigate", "createRouteRegistry"],
       "constraints": ["route registry owns navigation"],
-      "stability": "stable",
+      "stability": "preview",
       "docs": "https://github.com/askrjs/askr/blob/main/docs/guides/router.md",
       "docsPath": "docs/guides/router.md"
     },
@@ -60,7 +70,7 @@
       "import": "@askrjs/askr/ssr",
       "exports": ["renderToString"],
       "constraints": ["browser globals require lazy client targets"],
-      "stability": "stable",
+      "stability": "preview",
       "docs": "https://github.com/askrjs/askr/blob/main/docs/guides/ssr.md",
       "docsPath": "docs/guides/ssr.md"
     },
@@ -70,7 +80,7 @@
       "import": "@askrjs/askr/ssg",
       "exports": ["createStaticGen"],
       "constraints": ["routes must be deterministic"],
-      "stability": "stable",
+      "stability": "preview",
       "docs": "https://github.com/askrjs/askr/blob/main/docs/guides/ssg.md",
       "docsPath": "docs/guides/ssg.md"
     },
@@ -80,7 +90,7 @@
       "import": "@askrjs/askr/components",
       "exports": ["ErrorBoundary"],
       "constraints": ["portal hosts are finalized during render"],
-      "stability": "stable",
+      "stability": "preview",
       "docs": "https://github.com/askrjs/askr/blob/main/docs/reference/api.md",
       "docsPath": "docs/reference/api.md"
     },
@@ -90,7 +100,7 @@
       "import": "@askrjs/askr/foundations/structures",
       "exports": ["Portal", "DefaultPortal"],
       "constraints": ["portal hosts are finalized during render"],
-      "stability": "stable",
+      "stability": "preview",
       "docs": "https://github.com/askrjs/askr/blob/main/docs/reference/api.md",
       "docsPath": "docs/reference/api.md"
     }

package/dist/actions/index.js

@@ -1,14 +1,15 @@
-import { d as getCurrentAppRenderRuntime } from "../scope-Cq_iYbTR.js";
-import { r as getCurrentRenderData } from "../render-context-B7ohlh6t.js";
-import { t as state } from "../state-BXJfudq1.js";
-import { r as jsxs, t as jsx } from "../jsx-runtime-CPJXAOBF.js";
-import { c as resolveDataRuntimeState, s as invalidateQueriesForRuntime } from "../data-runtime-CxoY98lX.js";
-import { r as isCurrentAsyncGeneration } from "../shared-kU8yvryp.js";
+import { a as state } from "../state-DWO1KzkX.js";
+import { r as currentAppRuntime } from "../hooks-BimKStr4.js";
+import { r as getCurrentRenderData } from "../render-context-DGHnEveC.js";
+import { i as jsxs, n as jsx } from "../jsx-runtime-C4idqHY0.js";
+import { c as invalidateQueriesForRuntime, u as resolveDataRuntimeState } from "../data-runtime-C1bFAlba.js";
+import { c as resolveNavigationUrl } from "../url-CnbfpX0K.js";
+import { n as isCurrentAsyncGeneration } from "../shared-O2ZnmYAf.js";
 //#region src/actions/runtime.ts
 const emptyFramework = Object.freeze({});
 /** @internal Read Askr-owned state from the current application root. */
 function readActionFramework() {
-	return getCurrentAppRenderRuntime()?.framework ?? emptyFramework;
+	return currentAppRuntime()?.framework ?? emptyFramework;
 }
 //#endregion
 //#region src/actions/index.tsx
@@ -62,13 +63,46 @@ function initialStatus(actionId) {
 		error: replay
 	} : { pending: false };
 }
+/**
+* Validate an action redirect and return its absolute URL. Path-like targets
+* that leave the origin, including dot segments that collapse to `//host`,
+* are refused by {@link resolveNavigationUrl}; explicit URLs on another origin
+* are refused here. The absolute form keeps `location.assign()` on the origin.
+*/
 function normalizeActionRedirect(value) {
 	const current = new URL(location.href);
-	const target = new URL(value, current);
+	const target = resolveNavigationUrl(value, current.href);
 	if (target.protocol !== "http:" && target.protocol !== "https:" || target.origin !== current.origin) throw new TypeError("Action redirects must stay on the current origin.");
-	return `${target.pathname}${target.search}${target.hash}`;
+	return target.href;
 }
-/** Returns a command handle, rather than a hook. */
+/**
+* The `Error` an action submission rejects with for a failed or unreadable
+* response. The message always carries the HTTP status, plus a string
+* error, or the `detail`, `message`, or `title` of an error object or RFC 7807
+* problem body. The server value, or the body parse failure, is kept as
+* `cause`.
+*/
+function actionFailure(status, cause) {
+	let detail = typeof cause === "string" ? cause : void 0;
+	if (cause && typeof cause === "object" && !(cause instanceof Error)) {
+		const fields = cause;
+		detail = [
+			fields.detail,
+			fields.message,
+			fields.title
+		].find((field) => typeof field === "string");
+	}
+	const error = /* @__PURE__ */ new Error(detail ? `Action failed (${status}): ${detail}` : `Action failed (${status}).`);
+	if (cause !== void 0) error.cause = cause;
+	return error;
+}
+/**
+* Bind an action descriptor to the calling component and return its
+* `{ state, submit }` handle. `action()` allocates its status with `state()`,
+* so it follows the same rule: call it during component render, at the top
+* level and in the same order on every render. `submit()` itself may be
+* called from event handlers or other async work.
+*/
 function action(descriptor) {
 	const token = csrfToken();
 	const runtime = resolveDataRuntimeState();
@@ -94,8 +128,18 @@ function action(descriptor) {
 					},
 					body: JSON.stringify(input)
 				});
-				const envelope = await response.json();
-				if (!response.ok) throw envelope.error ?? validationError(envelope, descriptor.id) ?? /* @__PURE__ */ new Error(`Action failed (${response.status}).`);
+				let parsed;
+				try {
+					const body = await response.text();
+					parsed = response.ok && body === "" ? void 0 : JSON.parse(body);
+				} catch (cause) {
+					throw actionFailure(response.status, cause);
+				}
+				const envelope = parsed ?? {};
+				if (!response.ok) {
+					if (envelope.error != null) throw actionFailure(response.status, envelope.error);
+					throw validationError(envelope, descriptor.id) ?? actionFailure(response.status, parsed ?? void 0);
+				}
 				const redirect = typeof envelope.redirect === "string" ? normalizeActionRedirect(envelope.redirect) : void 0;
 				const invalidates = Array.isArray(envelope.invalidates) ? envelope.invalidates.filter((prefix) => typeof prefix === "string") : descriptor.invalidates;
 				for (const prefix of invalidates) invalidateQueriesForRuntime(runtime, prefix, true);

package/dist/benchmark.js

@@ -1,9 +1,8 @@
-import { r as flushRuntimeScheduler } from "./access-CEA2pOry.js";
-import { t as state } from "./state-BXJfudq1.js";
-import { t as selector } from "./selector-BSPVkjKP.js";
-import { i as For } from "./control-BR_mrX__.js";
-import { r as jsxs, t as jsx } from "./jsx-runtime-CPJXAOBF.js";
-import { r as createIsland, s as installRendererBridge } from "./boot-BMBMWUGI.js";
+import { y as flushSync } from "./instance-BAnfmXOR.js";
+import { a as state, i as selector } from "./state-DWO1KzkX.js";
+import { i as jsxs, n as jsx } from "./jsx-runtime-C4idqHY0.js";
+import { r as createIsland } from "./boot-DaoTYoCw.js";
+import { n as For } from "./control-nfpT2fbK.js";
 //#region src/bench/components/benchmark-row.tsx
 function BenchmarkRow({ item, isSelected, onSelect, onRemove }) {
 	return /* @__PURE__ */ jsxs("tr", {
@@ -57,13 +56,10 @@ function BenchmarkTable({ rows, isSelected, onSelect, onRemove }) {
 		}) })
 	});
 }
-//#endregion
-//#region src/bench/benchmark-entry.tsx
-installRendererBridge();
 const benchmarkMetadata = {
 	packageName: "@askrjs/askr",
-	packageVersion: "0.3.0",
-	buildLabel: "0.3.0-local"
+	packageVersion: "0.4.0",
+	buildLabel: "0.4.0-local"
 };
 function getBenchmarkMetadata() {
 	return { ...benchmarkMetadata };
@@ -75,7 +71,6 @@ function mountBenchmark(root, initialRows) {
 	const App = () => {
 		dataState = state(initialRowsTyped);
 		selectedState = state(null);
-		dataState._hasBeenRead = true;
 		const isSelected = selector(selectedState);
 		const select = (id) => selectedState.set(id);
 		const remove = (id) => {
@@ -96,15 +91,15 @@ function mountBenchmark(root, initialRows) {
 		root,
 		component: App
 	});
-	flushRuntimeScheduler();
+	flushSync();
 	return {
 		setRows(rows) {
 			dataState.set(rows);
-			flushRuntimeScheduler();
+			flushSync();
 		},
 		setSelected(id) {
 			selectedState.set(id);
-			flushRuntimeScheduler();
+			flushSync();
 		},
 		cleanup() {}
 	};

package/dist/boot/index.d.ts

@@ -21,6 +21,7 @@ type IslandsConfig = {
   cspNonce?: string;
 };
 type BootRouteSource = {
+  /** Pass a route registry built via `createRouteRegistry()`; hydration uses the one the server rendered with. */
   registry: RouteRegistry;
 };
 /** Configuration for {@link createSPA}. */
@@ -29,7 +30,7 @@ type SPAConfig = BootRouteSource & {
   cspNonce?: string;
   /** Optional data runtime, primarily for routed test fixtures. */
   dataRuntime?: DataRuntime;
-  /** Pass a route registry built via `createRouteRegistry(() => { ... })`. */
+  /** Auth resolution and redirect options; defaults to the registry's `auth`. */
   auth?: RouteAuthOptions;
   scrollRestoration?: boolean | ScrollRestorationOptions;
   cleanupStrict?: boolean;
@@ -40,7 +41,7 @@ type HydrateSPAConfig = BootRouteSource & {
   root: Element | string;
   cspNonce?: string;
   dataRuntime?: DataRuntime;
-  /** Pass the same explicit route registry used for the server render. */
+  /** Auth resolution and redirect options; defaults to the registry's `auth`. */
   auth?: RouteAuthOptions;
   scrollRestoration?: boolean | ScrollRestorationOptions;
   cleanupStrict?: boolean;

package/dist/boot/index.js

@@ -1,2 +1,2 @@
-import { a as cleanupApp, i as createIslands, n as createSPA, o as hasApp, r as createIsland, t as hydrateSPA } from "../boot-BMBMWUGI.js";
+import { a as cleanupApp, i as createIslands, n as createSPA, o as hasApp, r as createIsland, t as hydrateSPA } from "../boot-DaoTYoCw.js";
 export { cleanupApp, createIsland, createIslands, createSPA, hasApp, hydrateSPA };