@async/framework

@async/framework

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.

pnpm add @async/framework

<main async:container>
  <button type="button" on:click="decrement">-</button>
  <strong signal:text="count"></strong>
  <button type="button" on:click="increment">+</button>
</main>
<script type="module" src="./main.js"></script>

import {
  Async,
  createSignal
} from "@async/framework";

Async.use({
  signal: {
    count: createSignal(0)
  },
  handler: {
    increment() {
      this.signals.update("count", (count) => count + 1);
    },
    decrement() {
      this.signals.update("count", (count) => count - 1);
    }
  }
});

Async.start({ root: document });

Why Async

Async keeps the browser path small and explicit:

• Native HTML remains the document contract.
• Signals are the state boundary.
• Async.use(...) registers app declarations before or after startup.
• Handlers run through delegated DOM events.
• Async signals use native AbortSignal cancellation.
• Browser and server cache declarations are structurally split.
• Boundaries can be swapped out of order and rescanned.

It avoids a virtual DOM, hidden hydration pass, implicit startup fetch, component rerender loop, and browser snapshots that leak server-only cache contents.

Guide: docs/start/why-async.md · Contract: specs/framework/00-system-overview.md

The Abstraction Layers

Async uses L0-L7 abstraction layers. Layers describe the authoring surface; capabilities are protocol properties that land at the lowest layer the protocol allows.

Layer	Name	Era anchor	Adds	Requires
L0	Enhance	jQuery/Backbone; htmx	Server-led HTML, native forms/actions, and behavior references on server-owned views	Script tag
L1	Interpret	angular.js: runtime, no build	Runtime-interpreted app model: registries, components, lifecycle	Script tag or ESM
L2	Bundle	Built SPAs	Build as delivery, client routing, app server	Build optional
L3	SSR	React-without-JSX + SSR server	Server-rendered components with activation, no hydration	Server; build optional
L4	Transform	React+JSX	JSX/TSX transforms lowering to protocol records	Build
L5	Stream	Streaming SSR; Suspense	Progressive documents, boundary reveal ordering	Streaming server
L6	Reorder	RSC; islands; Qwik-style server$	Out-of-order settling, co-located server functions, chunks, and plans automated by the Optimizer	Optimizer
L7	Optimize	React Compiler; TSRX	Whole-program compilation	Spec only today

Layers compose within one document: an L2-bundled SPA can host an L0-enhanced form next to an L5-streamed boundary. This package ships the no-compiler layers (L0-L3, L5) plus the first compiler-layer surfaces (./jsx, ./vite, ./runtime/*).

Guide: docs/start/layers.md · Contract: specs/framework/15-abstraction-layers.md

How It Works

The framework is a protocol stack: HTML attributes connect to registered state and behavior, server work returns explicit envelopes, route partials and stream patches replace named boundaries, and SSR activation resumes already-rendered HTML without hydration.

HTML Protocol

Loader scans regular HTML attributes. The shorthand prefixes are the author-facing syntax: async:, signal:, on:, class:, and intersect:.

Attribute	Behavior
async:container	Marks a scannable app root
async:boundary="product"	Marks a replaceable boundary
async:snapshot	Holds serialized startup state
async:component="Card"	Mounts a registered component
on:click="selectProduct"	Delegated command event
on:submit="preventDefault; save"	Sequential command chain
on:click="server.cart.add(productId)"	Server command with signal args
on:intersect="trackSection"	Continuous intersection lifecycle 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

Guide: docs/runtime/html-protocol.md · Contract: specs/framework/04-dom-protocol.md

Signals & Async Signals

Signals are the state boundary for DOM bindings, handlers, server effects, router state, and async resources. Signal writes are synchronous; bindings, lifecycle callbacks, effects, and async refreshes are scheduled in deterministic phases.

const signals = createSignalRegistry({
  productId: createSignal("sku-1")
});

const product = signals.asyncSignal("product", async function () {
  return this.server.products.get(this.signals.get("productId"));
});

Guide: docs/runtime/signals.md · Contract: specs/framework/03-reactivity-system.md

App Hub & Registries

Async is the app hub singleton. It stores declarations, materializes fresh runtime registries on startup, exposes inspection APIs, and queues loader work that runs before a root attaches.

Async.use({
  signal: { count: createSignal(0) },
  handler: {
    increment() {
      this.signals.update("count", (count) => count + 1);
    }
  }
});

Async.start({ root: document });

Guide: docs/runtime/app-hub.md · Contract: specs/framework/02-runtime-kernel.md

Components

Components are scoped fragment functions. They return strings or html templates; Loader inserts and scans the result, and scoped signals, handlers, effects, and lifecycle cleanup follow the fragment.

const Toggle = component(function Toggle() {
  const selected = this.signal(false);

  return html`
    <button on:click="${this.handler(() => selected.update((value) => !value))}"
      class:selected="${selected}">
      Toggle
    </button>
  `;
});

Guide: docs/runtime/components.md · Contract: specs/framework/05-component-system.md

Server Calls & Cache

Server registries run locally on the server. Browser proxies use an explicit transport supplied by the app; responses can return values, signal patches, browser cache patches, boundary HTML, redirects, or errors.

const server = createServerProxy({
  endpoint: "/__async/server",
  transport,
  signals,
  loader,
  router
});

await server.cart.add("sku-1", 2);

Guide: docs/runtime/server-calls.md · Contract: specs/framework/06-server-and-data-system.md

Router & Partials

The router lives behind @async/framework/router. It handles URL matching, route params, hash-based static-host routes, same-origin link and GET form interception, route partial swaps, and route-only router.* state.

Async.use({
  route: {
    "/products/:id": defineRoute("product.page")
  },
  partial: {
    "product.page"({ id }) {
      return html`<h1>Product ${id}</h1>`;
    }
  }
});

Guide: docs/runtime/router-partials.md · Contract: specs/framework/07-routing-and-partials.md

SSR & Activation

SSR uses related app definitions: a server runtime renders HTML plus snapshots, and the browser runtime activates the existing document. Activation scans and attaches; it does not hydrate, diff, patch, rerender, or fetch route fragments.

const response = await createApp(serverApp, {
  target: "server",
  request
}).render("/products/123");

Guide: docs/runtime/ssr-activation.md · Contract: specs/framework/08-resume-and-streaming.md

Streaming & Boundaries

Boundary swaps replace named regions and rescan inserted content by default. createBoundaryReceiver(...) adds per-boundary sequence tracking, signal/cache effects, and stale patch suppression for independently arriving patches.

await receiver.apply({
  boundary: "product",
  seq: 1,
  signals: { product: { title: "Keyboard" } },
  html: `<h1 signal:text="product.title"></h1>`
});

Guide: docs/runtime/streaming.md · Contract: specs/framework/08-resume-and-streaming.md

Install & Load

Install from npm:

pnpm add @async/framework

Load directly from a CDN for no-build prototypes:

<script type="module">
  import { Async, createSignal } from "https://unpkg.com/@async/framework@latest/browser.js";
</script>

Use @async/framework/vite when a Vite app needs the Hono development server lane, a browser client build lane, or JSX optimizer reports.

Guide: docs/start/install.md · Build guide: docs/build/vite-hono.md

Examples

See examples/README.md for start commands and a short description of every example.

Example	Shows
examples/counter	Signal text binding and delegated handlers
examples/product	Async signal loading, ready, and error boundaries
examples/components	Scoped fragment components and lifecycle hooks
examples/app-patterns	Framework-native app composition, derived signals, and app-level errors
examples/streaming	Boundary swaps with rescanned handlers
examples/server-call	Command events calling server functions
examples/hateoas-actions	Hono-rendered HATEOAS links and forms enhanced into partial swaps
examples/router	CSR first render and local route boundary swaps
examples/partials	Server-rendered partial fragments
examples/cache	Browser/server cache declarations
examples/ssr	Server render output and browser activation snapshot
examples/vite-hono	Hono-backed Vite dev server plus client asset build
examples/vite-jsx-streaming	JSX optimizer bootstrap with stream runtime slice selection
examples/size	Scenario-size fixtures for bundle and runtime slices

Async And htmx

Async and htmx are both HTML-first and avoid a virtual DOM, but they optimize for different boundaries. In layer model terms, htmx-style hypermedia is the L0 Enhance layer, and in Async it stays available at every layer above.

Area	htmx	Async
Primary model	HTML attributes issue HTTP requests and swap server responses.	Server-generated HTML can stay primary; Async attributes add behavior, state, actions, and boundaries.
State	Server-owned hypermedia state; browser state is intentionally minimal.	Server-led HTML can stay server-owned; browser signals are available when a view needs local state.
Server interaction	DOM attributes describe HTTP verbs, targets, and swaps.	Native method/action flows can submit to any backend; partial responses can return HTML or envelopes for boundary swaps.
Routing	Usually server navigation or htmx-boosted navigation.	MPA and SSR keep navigation server-led; CSR, SPA, and signals modes opt into client-owned routing.
Components	Server-rendered HTML fragments.	Scoped fragment functions today; the compiler layers add JSX/TSRX authoring.
Build story	No build by default.	Layers L0-L3 and L5 are no-build/CDN; the compiler layers (L4, L6, L7) add build or compiler steps.

Async supports server-led views: any backend can render HTML strings for full documents or fragments, native forms can post through ordinary method and action attributes, and browser navigation can stay native in MPA/SSR modes. Add Async attributes only where a fragment needs local signals, command handlers, server functions, boundary swaps, or streamed patches. Use htmx when its HTTP-attribute model is the desired contract. Use Async when server-led HTML should share a protocol with local signals, registered browser/server handlers, route partials, streaming boundaries, and the compiler layers. See examples/hateoas-actions for a Hono-rendered HATEOAS flow using links, forms, verbs, and partial swaps.

Guide: docs/start/why-async.md · Contract: specs/framework/15-abstraction-layers.md

Status

The core runtime is intentionally small. Build-required JSX (L4) has optimizer artifacts for event, signal, stream, and children-fragment lowering, while full compiler emission, lazy chunk manifests, TSRX lowering, server resource compilation, and higher-level resumability metadata remain compiler-layer work (L6 and L7).

Contracts: specs/framework/12-composition-patterns.md · specs/framework/15-abstraction-layers.md · specs/framework/16-whole-program-compiler.md

Documentation Map

Page	Question it answers
Getting Started	What is the smallest running app?
App Authoring Contract	Which framework-native patterns should applications and examples follow?
Install & Load	How do npm, CDN, UMD, and import-map loading work?
Why Async	What does Async keep and avoid?
Core Concepts	Which runtime pieces make up an app?
Layers	How do L0-L7 fit together?
Runtime Overview	What happens when a root starts?
App Hub & Registries	How are declarations registered, inspected, and materialized?
HTML Protocol	Which attributes connect HTML to runtime behavior?
Signals & Async Signals	How does state update and async work refresh?
Components	How do scoped fragments, children, lifecycle, and intersection work?
Router & Partials	How do routes, partials, modes, and boundaries work?
Server Calls & Cache	How do server functions, envelopes, and cache split work?
SSR & Activation	How does server-rendered HTML start in the browser?
Streaming & Boundaries	How do swaps, refresh plans, morphing, and patch ordering work?
Build Profile	What does the compiler-layer profile promise?
Vite & Hono	How does the Vite plugin wire a Hono dev server and client build?
Entrypoints	Which package subpaths expose which surfaces?
Errors & Diagnostics	Which stable codes, hints, callbacks, and events report failures?
Examples	Which runnable example demonstrates each surface?

Contributing & Release

Common checks:

pnpm run pipeline:pages
pnpm run registry:lint
git diff --check

Pipeline and release automation are generated from pipeline.ts; update that source and run the sync checks before changing generated workflow output.

Guide: CONTRIBUTING.md