@async/framework 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.6.0 - 2026-06-17
+
+- Added `Loader` as the canonical public loader factory, including
+  `Async.Loader(...)` for UMD script-tag usage, while keeping `AsyncLoader` as
+  a compatibility alias.
+- Added generated root CDN artifacts: `framework.min.js`, `framework.umd.js`,
+  `framework.umd.min.js`, `framework.ts`, and `framework.d.ts`.
+- Added package exports and docs for ESM, compact ESM, UMD, compact UMD, and
+  TypeScript source/types entrypoints.
+- Added exported helpers to the UMD-only `globalThis.Async` object for
+  script-tag CDN usage while keeping ESM `Async` as the app hub export.
+- Added UMD namespace conflict checks so generated helpers cannot silently
+  overwrite app-hub fields such as `use`, `start`, or `registry`.
+- Added `registry:lint`, a cached package linter that emits a local registry
+  manifest and detects conflicting signal, handler, server, partial, route, or
+  component declarations while skipping generated root bundles.
+
+## 0.5.0 - 2026-06-17
+
+- Added `this.suspense(signalRef, views)` for component-owned async boundary
+  templates without adding a wrapper, rerender loop, hydration, or promise
+  throwing.
+- Added `signal:prop:*` property bindings and tests for inline signal refs in
+  `signal:text`, `signal:attr:*`, and `signal:prop:*`.
+- Added explicit `unregister(id)` APIs to runtime registries and component
+  cleanup for scoped signals, async signals, computed signals, and handlers.
+- Added boundary swap cleanup for mounted component fragments and old DOM
+  bindings.
+- Added server-call normalization for async signals, including returned signal
+  effects, proxy abort propagation, and stable server error messages.
+- Added `prevent` as a command-event alias for `preventDefault`.
+
 ## 0.4.0 - 2026-06-17
 
 - Added a generated root `framework.js` ESM bundle for UNPKG browser imports.

package/README.md

@@ -90,9 +90,18 @@ and package lifecycle tooling. Browser consumers import ESM directly.
 
 ## CDN
 
-The package ships a root `framework.js` ESM bundle for UNPKG and can be loaded
-without a build step. Use `@latest` for quick prototypes, and pin an exact
-version in production:
+The package ships root CDN artifacts for UNPKG and can be loaded without a
+build step. Use `@latest` for quick prototypes, and pin an exact version in
+production:
+
+| File | Format | Use |
+| --- | --- | --- |
+| `framework.js` | ESM | Readable browser module bundle |
+| `framework.min.js` | ESM | Compact browser module bundle |
+| `framework.umd.js` | UMD | Readable script-tag/CommonJS-style bundle |
+| `framework.umd.min.js` | UMD | Compact script-tag/CommonJS-style bundle and default CDN file |
+| `framework.ts` | TypeScript source facade | TS-aware runtimes and higher-layer tooling |
+| `framework.d.ts` | Type declarations | TypeScript declarations for the public API |
 
 ```html
 <main async:container>
@@ -121,6 +130,29 @@ version in production:
 </script>
 ```
 
+For a plain script tag, use the UMD bundle. In this UMD-only global form,
+`globalThis.Async` is the app hub plus the exported helper functions, with
+`globalThis.AsyncFramework` kept as an alias. Lower-level bootloader code can
+call `Async.Loader(...)` directly.
+
+```html
+<script src="https://unpkg.com/@async/framework@latest/framework.umd.min.js"></script>
+<script>
+  Async.use({
+    signal: {
+      count: Async.createSignal(0)
+    },
+    handler: {
+      increment() {
+        this.signals.update("count", (count) => count + 1);
+      }
+    }
+  });
+
+  Async.start({ root: document });
+</script>
+```
+
 You can also use an import map so app code imports `@async/framework` by name:
 
 ```html
@@ -157,8 +189,8 @@ You can also use an import map so app code imports `@async/framework` by name:
 
 ```js
 import {
-  AsyncLoader,
   Async,
+  Loader,
   attributeName,
   asyncSignal,
   createApp,
@@ -188,6 +220,9 @@ import {
 } from "@async/framework";
 ```
 
+`Loader` is the canonical loader factory. `AsyncLoader` remains as a
+compatibility alias for older code.
+
 ### App Hub
 
 `Async` is an exported app hub singleton. It is not installed on `globalThis`
@@ -253,6 +288,7 @@ Naming rules:
 | `create*` | Runtime instance or mutable runtime primitive |
 | `Async.use(...)` | App-level declaration registration |
 | `registry.register(...)` | Low-level registration on a concrete runtime registry |
+| `registry.unregister(...)` | Low-level removal from a concrete runtime registry |
 
 Singular registry keys are canonical: `signal`, `handler`, `server`,
 `partial`, `route`, `component`, and nested `cache.browser` / `cache.server`.
@@ -314,6 +350,7 @@ signals.set("count", 1);
 signals.update("count", (count) => count + 1);
 signals.subscribe("count", (count) => console.log(count));
 signals.ref("count").value;
+signals.unregister("count");
 ```
 
 Initializer maps are supported:
@@ -376,7 +413,7 @@ reruns and the previous run is aborted.
 
 ## HTML Protocol
 
-AsyncLoader scans regular HTML attributes:
+Loader scans regular HTML attributes:
 
 | Attribute | Behavior |
 | --- | --- |
@@ -389,6 +426,7 @@ AsyncLoader scans regular HTML attributes:
 | `signal:text="product.title"` | Text binding |
 | `signal:value="productId"` | Form value binding with writeback |
 | `signal:attr:disabled="product.$loading"` | Attribute binding |
+| `signal:prop:checked="selected"` | DOM property binding |
 | `class:selected="selected"` | Class toggle from a signal path |
 | `signal:class="buttonClasses"` | Class set from a signal value: string, object, or array |
 | `async:boundary="product"` | Async or streamed replacement boundary |
@@ -428,6 +466,24 @@ Async.start({
 That maps to `data-async-container`, `data-on-click="save"`,
 `data-signal-text="product.title"`, and `data-class-selected="selected"`.
 
+Inside `html` templates, signal refs can be passed directly to binding
+attributes:
+
+```js
+const title = this.signal("Keyboard");
+const disabled = this.signal(false);
+const checked = this.signal(true);
+
+return html`
+  <h1 signal:text="${title}"></h1>
+  <button signal:attr:disabled="${disabled}">Save</button>
+  <input type="checkbox" signal:prop:checked="${checked}">
+`;
+```
+
+Use `signal:value` for form value binding with writeback. Use `signal:prop:*`
+when you only need one-way DOM property updates.
+
 Named class toggles use their own top-level namespace:
 
 ```html
@@ -518,6 +574,7 @@ Plain commands resolve through the handler registry. Built-ins are registered by
 default:
 
 ```txt
+prevent
 preventDefault
 stopPropagation
 stopImmediatePropagation
@@ -584,6 +641,12 @@ await server.cart.add("sku-1", 2);
 
 Server responses can include `value`, `signals`, `boundary`, `html`, `redirect`,
 or `error`. Signal patches are applied before boundary swaps and redirects.
+Namespace calls such as `server.cart.add(...)` return the unwrapped `value`.
+
+When an async signal calls a server namespace function, the framework passes the
+active abort signal through proxy calls. Returned server effects such as
+`signals`, `cache.browser`, `boundary/html`, and `redirect` are applied before
+the async signal stores the unwrapped `value`.
 
 ### Router And Partials
 
@@ -764,7 +827,7 @@ createApp(browserApp, {
 ## Components
 
 Components are scoped fragment functions. They return strings or `html`
-templates; AsyncLoader inserts and scans the result. There is no virtual node
+templates; Loader inserts and scans the result. There is no virtual node
 type and no rerender loop.
 
 ```js
@@ -794,7 +857,7 @@ const Toggle = defineComponent(function Toggle() {
   `;
 });
 
-const loader = AsyncLoader({ root: document });
+const loader = Loader({ root: document });
 loader.mount(document.querySelector("#app"), Toggle);
 ```
 
@@ -812,10 +875,55 @@ Component helpers:
 | `this.handler(name, fn)` | Scoped named handler registry entry |
 | `this.handler(fn)` | Generated scoped handler registry entry |
 | `this.render(Component, props)` | Child fragment rendering |
+| `this.suspense(signalRef, views)` | Async boundary template helper |
 | `this.on(event, fn)` | Fragment lifecycle fallback for `attach`, `visible`, and `destroy` |
 | `this.onMount(fn)` | Compatibility alias for `this.on("attach", fn)` |
 | `this.onVisible(fn)` | Compatibility alias for `this.on("visible", fn)` |
 
+`this.suspense(...)` is sugar for Loader boundaries:
+`asyncSignal + async:boundary + async:* templates`. It emits only templates. The
+caller owns the boundary element, and the loader chooses the loading, ready, or
+error template from the async signal status.
+
+```js
+const Product = defineComponent(function Product() {
+  const product = this.asyncSignal("product", async function () {
+    return this.server.products.get("sku-1");
+  });
+
+  return html`
+    <article async:boundary="${product.id}">
+      ${this.suspense(product, {
+        loading() {
+          return html`<p>Loading...</p>`;
+        },
+        ready(product) {
+          return html`<h1 signal:text="${product.id}.title"></h1>`;
+        },
+        error(product) {
+          return html`<p signal:text="${product.id}.$error.message"></p>`;
+        }
+      })}
+    </article>
+  `;
+});
+```
+
+The shorthand form treats the callback as the ready template:
+
+```js
+this.suspense(product, (product) => html`
+  <h1 signal:text="${product.id}.title"></h1>
+`);
+```
+
+`this.suspense(...)` is not React Suspense. It does not throw promises,
+hydrate, diff, rerender a component tree, or emit a wrapper element.
+
+Component-scoped signals and handlers are unregistered when the mounted
+fragment is destroyed. `loader.swap(...)` cleans up old DOM bindings and mounted
+component fragments under the swapped boundary before inserting the new HTML.
+
 Put component lifecycle on the component root element when there is one:
 
 ```js
@@ -894,10 +1002,19 @@ Useful commands:
 ```bash
 pnpm run pipeline:verify
 pnpm run pipeline:pages
+pnpm run registry:lint
 pnpm run pipeline:release:doctor
 pnpm run release:check
 ```
 
+`registry:lint` scans package source and examples for declared registry ids
+such as signals, handlers, server functions, partials, routes, and components.
+It writes `.async/registry-manifest.json` plus a per-file cache at
+`.async/registry-lint-cache.json`, skips generated root bundles such as
+`framework.umd.min.js`, and fails only when the same registry type and id are
+declared with different normalized content. Duplicate declarations with the
+same content are reported as dedupe candidates, not errors.
+
 GitHub Pages builds through the generated `pages` job. This private repository
 needs GitHub Pages support enabled before the generated job can deploy.
 

package/examples/cache/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>AsyncLoader Cache</title>
+    <title>Async Loader Cache</title>
   </head>
   <body>
     <main async:container>

package/examples/components/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="utf-8">
-    <title>AsyncLoader Components</title>
+    <title>Async Loader Components</title>
   </head>
   <body>
     <main id="app"></main>

package/examples/components/main.js

@@ -1,4 +1,4 @@
-import { AsyncLoader, defineComponent, html } from "../../src/index.js";
+import { Loader, defineComponent, html } from "../../src/index.js";
 
 const Toggle = defineComponent(function Toggle() {
   const selected = this.signal(false);
@@ -22,5 +22,5 @@ const Toggle = defineComponent(function Toggle() {
   `;
 });
 
-const loader = AsyncLoader({ root: document });
+const loader = Loader({ root: document });
 loader.mount(document.querySelector("#app"), Toggle);

package/examples/counter/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="utf-8">
-    <title>AsyncLoader Counter</title>
+    <title>Async Loader Counter</title>
   </head>
   <body async:container>
     <main>

package/examples/partials/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>AsyncLoader Partials</title>
+    <title>Async Loader Partials</title>
   </head>
   <body>
     <main async:container>

package/examples/product/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="utf-8">
-    <title>AsyncLoader Product</title>
+    <title>Async Loader Product</title>
   </head>
   <body async:container>
     <main>

package/examples/product/main.js

@@ -1,4 +1,4 @@
-import { AsyncLoader, createSignal, createSignalRegistry, delay } from "../../src/index.js";
+import { Loader, createSignal, createSignalRegistry, delay } from "../../src/index.js";
 
 const products = {
   "sku-1": {
@@ -21,4 +21,4 @@ signals.asyncSignal("product", async function () {
   return products[id];
 });
 
-AsyncLoader({ root: document.body, signals }).start();
+Loader({ root: document.body, signals }).start();

package/examples/router/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>AsyncLoader CSR Router</title>
+    <title>Async Loader CSR Router</title>
   </head>
   <body>
     <main async:container>

package/examples/server-call/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>AsyncLoader Server Call</title>
+    <title>Async Loader Server Call</title>
   </head>
   <body>
     <main async:container>

package/examples/ssr/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>AsyncLoader SSR Activation</title>
+    <title>Async Loader SSR Activation</title>
   </head>
   <body>
     <main id="app" async:container></main>

package/examples/streaming/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="utf-8">
-    <title>AsyncLoader Streaming</title>
+    <title>Async Loader Streaming</title>
   </head>
   <body async:container>
     <main>