@async/framework 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.4.0 - 2026-06-17
+
+- Added a generated root `framework.js` ESM bundle for UNPKG browser imports.
+- Expanded the README with Async layer definitions and an htmx comparison.
+- Added `on:attach` as the canonical component attach lifecycle pseudo-event
+  with `on:mount` kept as a compatibility alias.
+- Added top-level `class:*` bindings, including aggregate `class:`
+  string/object/array class sets.
+- Added inline `html` template bindings for signal refs, class arrays/objects,
+  `value="${signalRef}"`, and generated component handlers via
+  `this.handler(fn)`.
+- Added generated component-local signals via `this.signal(initial)`.
+
+## 0.3.0 - 2026-06-17
+
+- Added a shared registry store behind `Async`, app runtimes, and concrete
+  registries so apps can inspect signals, handlers, server ids, routes,
+  partials, components, and split cache state from one place.
+- Added configurable HTML attribute prefixes, with `async:*`, `signal:*`, and
+  `on:*` as the defaults plus explicit support for `data-async-*`,
+  `data-signal-*`, and `data-on-*`.
+- Declared the UNPKG package entry explicitly so the package root can be used as
+  a no-build browser ESM CDN import.
+- Documented the UNPKG import-map setup for importing `@async/framework` by
+  package name in no-build browser apps.
+
 ## 0.2.2 - 2026-06-17
 
 - Fixed release doctor validation to accept the pipeline-generated GitHub

package/README.md

@@ -1,18 +1,18 @@
 # @async/framework
 
-Layer 1 AsyncLoader plus small Layer 2 app, routing, server, cache, and SSR
-primitives for no-build web apps: signals, async signals, delegated command
-events, scoped fragment components, server calls, route partials, and
-out-of-order boundary swaps without a virtual DOM.
+Async is a layered framework plan that starts as a no-build browser bootloader:
+signals, async signals, delegated command events, scoped fragment components,
+server calls, route partials, and out-of-order boundary swaps without a virtual
+DOM.
 
 ```bash
 pnpm add @async/framework
 ```
 
 ```html
-<main data-async-container>
+<main async:container>
   <button type="button" on:click="decrement">-</button>
-  <strong data-async-text="count"></strong>
+  <strong signal:text="count"></strong>
   <button type="button" on:click="increment">+</button>
 </main>
 <script type="module" src="./main.js"></script>
@@ -43,10 +43,10 @@ Async.start({ root: document });
 
 ## What It Is
 
-`@async/framework` is the browser bootloader layer for Async apps. It keeps the
-runtime small and explicit:
+`@async/framework` is the Layer 1 runtime plus the first Layer 2 app/server
+primitives. It keeps the runtime small and explicit:
 
-- No build step for consumers.
+- No build step for Layer 1 consumers.
 - No virtual DOM, diff path, hydration runtime, or component rerender loop.
 - Signals are the state boundary.
 - `Async.use(...)` registers app declarations before or after startup.
@@ -57,8 +57,27 @@ runtime small and explicit:
 - Boundaries can be swapped out of order and rescanned, which keeps server
   streaming and partial HTML replacement simple.
 
-Higher layers can still add JSX lowering, chunk manifests, server compilation,
-or resumability metadata later. Layer 1 stays plain HTML plus ESM.
+Higher layers can add JSX lowering, TypeScript, chunk manifests, compiler-owned
+server/client splits, and intent-first authoring later. They should compile down
+to the same runtime registries and HTML protocol.
+
+## Layers
+
+Async is designed as layers, so each level can stay useful without forcing the
+next level on every app.
+
+| Layer | Name | Requirement | Purpose |
+| --- | --- | --- | --- |
+| 1 | Runtime bootloader | No build. CDN or direct ESM import. | Signals, async signals, handlers, command events, lifecycle pseudo-events, scoped fragments, and boundary swaps. |
+| 2 | App/server layer | Light server integration. No app compiler required. | `Async.use(...)`, router modes, server function proxy, partial registry, SSR output, browser activation, and split browser/server cache. |
+| 3 | Authoring build | Build step required. | JSX, ESM, and TypeScript authoring that lowers into Layer 1 HTML attributes and Layer 2 registries. |
+| 4 | Chunk and resumability metadata | Build metadata required. | Lazy module manifests, visibility/prefetch hints, resource graphs, and resumability records that the bootloader can consume. |
+| 5 | Framework compiler | Compiler required. | Server/client partitioning, code motion, optimized registry generation, serialized closures, and deeper resumability transforms. |
+| 6 | TSRX and intent layer | Higher-level compiler required. | More declarative author intent, AI/compiler-friendly metadata, and source forms that generate lower-layer Async apps. |
+
+The package in this repository intentionally focuses on Layers 1 and 2. Layers
+3 through 6 are higher authoring surfaces, not extra runtime requirements for
+plain HTML apps.
 
 ## Install
 
@@ -69,12 +88,78 @@ pnpm add @async/framework
 The package is ESM-only and supports Node.js 24 and newer for tests, examples,
 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:
+
+```html
+<main async:container>
+  <button type="button" on:click="increment">+</button>
+  <strong signal:text="count"></strong>
+</main>
+
+<script type="module">
+  import {
+    Async,
+    createSignal
+  } from "https://unpkg.com/@async/framework@latest/framework.js";
+
+  Async.use({
+    signal: {
+      count: 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
+<script type="importmap">
+{
+  "imports": {
+    "@async/framework": "https://unpkg.com/@async/framework@latest/framework.js"
+  }
+}
+</script>
+
+<script type="module">
+  import {
+    Async,
+    createSignal
+  } from "@async/framework";
+
+  Async.use({
+    signal: {
+      count: createSignal(0)
+    },
+    handler: {
+      increment() {
+        this.signals.update("count", (count) => count + 1);
+      }
+    }
+  });
+
+  Async.start({ root: document });
+</script>
+```
+
 ## Core API
 
 ```js
 import {
   AsyncLoader,
   Async,
+  attributeName,
   asyncSignal,
   createApp,
   createCacheRegistry,
@@ -84,11 +169,13 @@ import {
   createSignal,
   createHandlerRegistry,
   createPartialRegistry,
+  createRegistryStore,
   createRouteRegistry,
   createRouter,
   createServerProxy,
   createServerRegistry,
   createSignalRegistry,
+  defineAttributeConfig,
   defineApp,
   defineCache,
   defineComponent,
@@ -170,6 +257,50 @@ Naming rules:
 Singular registry keys are canonical: `signal`, `handler`, `server`,
 `partial`, `route`, `component`, and nested `cache.browser` / `cache.server`.
 
+### Registry Inspection
+
+`Async.registry` is the global inspection surface for registered app pieces.
+Every runtime and concrete registry also points at the same backing store:
+
+```js
+Async.registry.keys("signal");
+Async.registry.entries("route");
+Async.registry.snapshot();
+
+const runtime = Async.start({ root: document });
+
+runtime.registry.keys("handler");
+runtime.signals.registry === runtime.registry;
+runtime.browser.cache.registry === runtime.registry;
+```
+
+Supported inspection types:
+
+```txt
+signal
+handler
+server
+partial
+route
+component
+cache.browser
+cache.server
+cache.browser.entries
+cache.server.entries
+```
+
+Browser runtime inspection exposes server ids as descriptors, not executable
+server functions, and does not expose server cache contents:
+
+```js
+runtime.registry.keys("server");
+runtime.registry.get("server", "products.get");
+// { id: "products.get", kind: "server" }
+
+runtime.registry.snapshot().entries.server;
+// {}
+```
+
 ### Signals
 
 ```js
@@ -249,37 +380,130 @@ AsyncLoader scans regular HTML attributes:
 
 | Attribute | Behavior |
 | --- | --- |
-| `data-async-container` | Marks a scannable app root |
+| `async:container` | Marks a scannable app root |
 | `on:click="selectProduct"` | Delegated command event |
 | `on:submit="preventDefault; save"` | Sequential command chain |
 | `on:click="server.cart.add(productId)"` | Server command with signal args |
-| `data-async-text="product.title"` | Text binding |
-| `data-async-value="productId"` | Form value binding with writeback |
-| `data-async-attr:disabled="product.$loading"` | Attribute binding |
-| `data-async-class:selected="selected"` | Class toggle |
-| `data-async-boundary="product"` | Async or streamed replacement boundary |
-| `data-async-loading="product"` | Boundary loading template |
-| `data-async-ready="product"` | Boundary ready template |
-| `data-async-error="product"` | Boundary error template |
+| `on:attach="setup"` | Component root attach lifecycle pseudo-event |
+| `on:visible="trackView"` | Component root visible lifecycle pseudo-event |
+| `signal:text="product.title"` | Text binding |
+| `signal:value="productId"` | Form value binding with writeback |
+| `signal:attr:disabled="product.$loading"` | Attribute 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 |
+| `async:loading="product"` | Boundary loading template |
+| `async:ready="product"` | Boundary ready template |
+| `async:error="product"` | Boundary error template |
 
 ```html
-<section data-async-boundary="product">
-  <template data-async-loading="product">
+<section async:boundary="product">
+  <template async:loading="product">
     <p>Loading...</p>
   </template>
-  <template data-async-ready="product">
-    <h1 data-async-text="product.title"></h1>
+  <template async:ready="product">
+    <h1 signal:text="product.title"></h1>
   </template>
-  <template data-async-error="product">
-    <p data-async-text="product.$error.message"></p>
+  <template async:error="product">
+    <p signal:text="product.$error.message"></p>
   </template>
 </section>
 ```
 
+The default prefixes are `async:`, `signal:`, and `on:`. You can switch to
+data attributes when a host needs that shape:
+
+```js
+Async.start({
+  root: document,
+  attributes: {
+    async: "data-async-",
+    class: "data-class-",
+    signal: "data-signal-",
+    on: "data-on-"
+  }
+});
+```
+
+That maps to `data-async-container`, `data-on-click="save"`,
+`data-signal-text="product.title"`, and `data-class-selected="selected"`.
+
+Named class toggles use their own top-level namespace:
+
+```html
+<button
+  class="button"
+  class:selected="selected"
+>
+  Add
+</button>
+```
+
+Aggregate class binding uses `signal:class`. It reads the current signal value
+and accepts strings, objects, and arrays:
+
+```js
+Async.use({
+  signal: {
+    buttonClasses: createSignal([
+      "button-primary",
+      { selected: true, disabled: false },
+      ["compact"]
+    ])
+  }
+});
+```
+
+```html
+<button signal:class="buttonClasses">Add</button>
+```
+
+Inside `html` templates, `signal:class` can also receive objects or arrays
+directly. Signal refs inside the object or array are tracked:
+
+```js
+const selected = this.signal("selected", false);
+const tone = this.signal("tone", "primary");
+
+return html`
+  <article signal:class="${["card", tone, { selected }]}"}>
+    ...
+  </article>
+`;
+```
+
+For component-local state that does not need a stable public id, omit the name.
+The signal is still registered under the component scope:
+
+```js
+const selected = this.signal(false);
+const tone = this.signal("primary");
+
+return html`
+  <article signal:class="${["card", selected, tone]}">
+    ...
+  </article>
+`;
+```
+
+`value="${signalRef}"` in an `html` template is equivalent to adding
+`signal:value` for that signal. It writes back on input/change:
+
+```js
+const productId = this.signal("productId", "sku-1");
+
+return html`<input value="${productId}">`;
+```
+
+`signal:class:selected="selected"` remains supported as a compatibility alias,
+but new examples should use `class:selected`. The parser-safe top-level
+aggregate form `class:="buttonClasses"` also remains supported.
+
 ### Command Events
 
-`on:*` works with any native DOM event name. `on:mount` and `on:visible` are
-reserved pseudo-events with cleanup support.
+`on:*` works with any native DOM event name. `on:attach` and `on:visible` are
+reserved component lifecycle pseudo-events with cleanup support. `on:mount`
+remains as a compatibility alias for `on:attach`.
 
 Command chains use semicolons and are awaited sequentially:
 
@@ -417,13 +641,13 @@ Router modes:
 CSR startup can use an empty route boundary:
 
 ```html
-<main data-async-container>
+<main async:container>
   <nav>
     <a href="/">Home</a>
     <a href="/products/sku-1">Product</a>
   </nav>
 
-  <section data-async-boundary="route"></section>
+  <section async:boundary="route"></section>
 </main>
 ```
 
@@ -520,10 +744,10 @@ const response = await serverRuntime.render("/products/123");
 The returned HTML includes a route boundary plus a JSON snapshot:
 
 ```html
-<section data-async-boundary="route">
+<section async:boundary="route">
   <!-- server-rendered route partial -->
 </section>
-<script type="application/json" data-async-snapshot>{}</script>
+<script type="application/json" async:snapshot>{}</script>
 ```
 
 Browser activation scans the existing HTML and attaches events. It does not
@@ -545,21 +769,25 @@ type and no rerender loop.
 
 ```js
 const Toggle = defineComponent(function Toggle() {
-  const selected = this.signal("selected", false);
-  const toggle = this.handler("toggle", function () {
-    selected.update((value) => !value);
+  const selected = this.signal(false);
+  const attach = this.handler("attach", function ({ element }) {
+    element.dataset.attached = "true";
   });
-
-  this.onMount((target) => {
-    target.dataset.mounted = "true";
+  const visible = this.handler("visible", function ({ element }) {
+    element.dataset.visible = "true";
   });
 
   return html`
     <button
       type="button"
-      on:click="${toggle}"
-      data-async-class:selected="${selected.id}"
-      data-async-attr:aria-pressed="${selected.id}"
+      on:attach="${attach}"
+      on:visible="${visible}"
+      on:click="${this.handler(function () {
+        selected.update((value) => !value);
+      })}"
+      class:selected="${selected}"
+      signal:class="${["toggle", { active: selected }]}"
+      signal:attr:aria-pressed="${selected}"
     >
       Toggle
     </button>
@@ -576,17 +804,46 @@ Component helpers:
 
 | Helper | Behavior |
 | --- | --- |
-| `this.signal(name, initial)` | Scoped get-or-create signal |
+| `this.signal(name, initial)` | Scoped named get-or-create signal |
+| `this.signal(initial)` | Generated scoped local signal |
 | `this.computed(name, fn)` | Scoped computed signal |
 | `this.asyncSignal(name, fn)` | Scoped async signal |
 | `this.effect(fn)` | Scoped effect with cleanup |
-| `this.handler(name, fn)` | Scoped handler registry entry |
+| `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.onMount(fn)` | One-shot mount hook |
-| `this.onVisible(fn)` | One-shot visibility hook |
+| `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)` |
+
+Put component lifecycle on the component root element when there is one:
+
+```js
+const attach = this.handler("attach", function ({ element }) {
+  element.dataset.attached = "true";
+});
+const visible = this.handler("visible", function ({ element }) {
+  element.dataset.visible = "true";
+});
 
-`on:mount` and `on:visible` are loader pseudo-events with cleanup support. They
-do not drive component rerenders.
+return html`<article on:attach="${attach}" on:visible="${visible}">...</article>`;
+```
+
+If a component returns text or multiple root nodes, use the scoped fallback:
+
+```js
+this.on("attach", (target) => {
+  target.dataset.attached = "true";
+});
+
+this.on("destroy", () => {
+  // Clean up fragment-scoped resources.
+});
+```
+
+`on:visible` is defined as a component lifecycle pseudo-event. It runs once when
+the component root first becomes visible. Lifecycle events do not drive
+component rerenders.
 
 ## Streaming
 
@@ -597,7 +854,7 @@ loader.swap(
   "product",
   `
     <article>
-      <h1 data-async-text="product.title"></h1>
+      <h1 signal:text="product.title"></h1>
       <button type="button" on:click="selectProduct">Select</button>
     </article>
   `
@@ -653,3 +910,22 @@ then runs release doctor.
 The core runtime is intentionally small. Bundling, lazy chunk manifests, JSX
 lowering, TSRX lowering, server resource compilation, and higher-level
 resumability metadata are deferred to later layers.
+
+## Async And htmx
+
+Async and htmx are both HTML-first and avoid a virtual DOM, but they optimize
+for different boundaries.
+
+| Area | htmx | Async |
+| --- | --- | --- |
+| Primary model | HTML attributes issue HTTP requests and swap server responses. | HTML attributes bind signals, command events, server calls, and route boundaries. |
+| State | Server-owned hypermedia state; browser state is intentionally minimal. | Browser signal registry plus server signal patches and cache snapshots. |
+| Server interaction | DOM attributes describe HTTP verbs, targets, and swaps. | `server.*(...)` commands call registered server functions and apply returned effects. |
+| Routing | Usually server navigation or htmx-boosted navigation. | CSR, SPA, SSR, SSR-SPA, and MPA router modes built around partial boundaries. |
+| Components | Server-rendered HTML fragments. | Scoped fragment functions today; higher layers can compile JSX/TSRX later. |
+| Build story | No build by default. | Layer 1 is no-build/CDN; higher layers can add build or compiler steps. |
+
+Use htmx when the server should own most interaction through hypermedia and
+HTTP swaps. Use Async when you want an HTML-first runtime that also has local
+signals, async resources, registered browser/server handlers, route partials,
+and a path to higher compiler layers without changing the Layer 1 protocol.

package/examples/cache/index.html

@@ -6,10 +6,10 @@
     <title>AsyncLoader Cache</title>
   </head>
   <body>
-    <main data-async-container>
+    <main async:container>
       <button type="button" on:click="cacheDemo.loadProduct">Load product</button>
-      <p>Product: <strong data-async-text="cacheDemo.title"></strong></p>
-      <p>Server calls: <strong data-async-text="cacheDemo.calls"></strong></p>
+      <p>Product: <strong signal:text="cacheDemo.title"></strong></p>
+      <p>Server calls: <strong signal:text="cacheDemo.calls"></strong></p>
     </main>
     <script type="module" src="./main.js"></script>
   </body>

package/examples/components/main.js

@@ -1,21 +1,21 @@
 import { AsyncLoader, defineComponent, html } from "../../src/index.js";
 
 const Toggle = defineComponent(function Toggle() {
-  const selected = this.signal("selected", false);
-  const toggle = this.handler("toggle", function () {
-    selected.update((value) => !value);
-  });
-
-  this.onMount(() => {
-    document.body.dataset.toggleMounted = "true";
+  const selected = this.signal(false);
+  const attach = this.handler("attach", function ({ element }) {
+    element.dataset.attached = "true";
   });
 
   return html`
     <button
       type="button"
-      on:click="${toggle}"
-      data-async-class:selected="${selected.id}"
-      data-async-attr:aria-pressed="${selected.id}"
+      on:attach="${attach}"
+      on:click="${this.handler(function () {
+        selected.update((value) => !value);
+      })}"
+      class:selected="${selected}"
+      signal:class="${["toggle", { active: selected }]}"
+      signal:attr:aria-pressed="${selected}"
     >
       Toggle
     </button>

package/examples/counter/index.html

@@ -4,9 +4,9 @@
     <meta charset="utf-8">
     <title>AsyncLoader Counter</title>
   </head>
-  <body data-async-container>
+  <body async:container>
     <main>
-      <p>Count: <strong data-async-text="counter.count"></strong></p>
+      <p>Count: <strong signal:text="counter.count"></strong></p>
       <button type="button" on:click="counter.decrement">-</button>
       <button type="button" on:click="counter.increment">+</button>
     </main>

package/examples/partials/index.html

@@ -6,9 +6,9 @@
     <title>AsyncLoader Partials</title>
   </head>
   <body>
-    <main data-async-container>
+    <main async:container>
       <button type="button" on:click="partialsDemo.loadProduct">Load product</button>
-      <section data-async-boundary="product"></section>
+      <section async:boundary="product"></section>
     </main>
     <script type="module" src="./main.js"></script>
   </body>

package/examples/product/index.html

@@ -4,26 +4,26 @@
     <meta charset="utf-8">
     <title>AsyncLoader Product</title>
   </head>
-  <body data-async-container>
+  <body async:container>
     <main>
       <label>
         Product
-        <select data-async-value="productId">
+        <select signal:value="productId">
           <option value="sku-1">Mechanical Keyboard</option>
           <option value="sku-2">Studio Headphones</option>
         </select>
       </label>
 
-      <section data-async-boundary="product">
-        <template data-async-loading="product">
+      <section async:boundary="product">
+        <template async:loading="product">
           <p>Loading product...</p>
         </template>
-        <template data-async-ready="product">
-          <h1 data-async-text="product.title"></h1>
-          <p data-async-text="product.description"></p>
+        <template async:ready="product">
+          <h1 signal:text="product.title"></h1>
+          <p signal:text="product.description"></p>
         </template>
-        <template data-async-error="product">
-          <p data-async-text="product.$error.message"></p>
+        <template async:error="product">
+          <p signal:text="product.$error.message"></p>
         </template>
       </section>
     </main>

package/examples/router/index.html

@@ -6,12 +6,12 @@
     <title>AsyncLoader CSR Router</title>
   </head>
   <body>
-    <main data-async-container>
+    <main async:container>
       <nav>
         <a href="/">Home</a>
         <a href="/products/sku-1">Product</a>
       </nav>
-      <section data-async-boundary="route"></section>
+      <section async:boundary="route"></section>
     </main>
     <script type="module" src="./main.js"></script>
   </body>