@webjsdev/core 0.8.0 → 0.9.0

package/index-browser.js

@@ -23,25 +23,27 @@
  * Keep this list in sync with `./index.js` for everything else.
  */
 
-export { html, svg, isTemplate, MARKER } from './src/html.js';
-export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
+export { html, svg, mathml, isTemplate, MARKER } from './src/html.js';
+export { isServer } from './src/is-server.js';
+export { css, unsafeCSS, CSSResult, isCSS, adoptStyles, stylesToString } from './src/css.js';
 export { WebComponent, prop } from './src/component.js';
+export { defaultConverter, notEqual } from './src/converters.js';
 export { lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
-export { notFound, redirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
+export { notFound, redirect, permanentRedirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
 export { cspNonce } from './src/csp-nonce.js';
 export { asset } from './src/asset-url.js';
 // Form actions (#1155). The field name is shared with the server dispatcher;
 // `setFormActionResolver` is server-only wiring and is stripped here, because
 // a browser stub carries its own identity and needs no resolver.
-export { FORM_ACTION_FIELD, FORM_ACTION_ID_KEY } from './src/form-action.js';
+export { FORM_ACTION_FIELD, FORM_ACTION_ID_KEY, installActionBind, bindActionId, splitActionId } from './src/form-action.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
 export { richFetch } from './src/rich-fetch.js';
 export {
-  stringify, parse,
+  stringify, stringifySync, parse,
   serialize, deserialize,
 } from './src/serialize.js';
 // The client router auto-enables on bundle load: `router-client.js` calls
@@ -65,7 +67,7 @@ export { WebjsFrame } from './src/webjs-frame.js';
 export { WebjsStream, renderStream } from './src/webjs-stream.js';
 
 // Signals (TC39 Stage-1 shape), also available via '@webjsdev/core/signals'
-export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
+export { signal, computed, effect, batch, isSignal, Signal, SignalWatcher } from './src/signal.js';
 
 // Optimistic-mutation helper (thin signal wrapper, rolls back on failure)
 export { optimistic } from './src/optimistic.js';
@@ -76,6 +78,9 @@ export { takeSeed, scanSeeds, seedStats, SEED_MISS } from './src/action-seed-cli
 // Client tag-cache coordinator for HTTP-verb actions (#488): tag-based
 // browser-cache eviction after a mutation. Inert server-side.
 export { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
+// Effects an RPC action response asks the browser for (revalidatePath's
+// in-place refresh), read by the generated action stub.
+export { applyActionRefresh, followActionRedirect } from './src/action-effects-client.js';
 // Client action-abort plumbing (#492): a superseded async render aborts its
 // in-flight action fetches. Inert server-side.
 export { setActiveActionSignal, activeActionSignal } from './src/action-abort-client.js';
@@ -92,14 +97,14 @@ export {
   unsafeHTML, isUnsafeHTML, live, isLive, keyed, isKeyed, guard, isGuard,
   templateContent, isTemplateContent, ref, isRef, createRef, cache, isCache,
   until, isUntil, asyncAppend, isAsyncAppend, asyncReplace, isAsyncReplace,
-  watch, isWatch,
+  watch, isWatch, unsafeSVG, unsafeMathML, when, choose, map, join, range,
 } from './src/directives.js';
 
 // Context Protocol, also available via '@webjsdev/core/context'
-export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';
+export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent, ContextProviderEvent, ContextRoot } from './src/context.js';
 
 // Task controller, also available via '@webjsdev/core/task'
-export { Task, TaskStatus } from './src/task.js';
+export { Task, TaskStatus, initialState, shallowArrayEquals, deepArrayEquals } from './src/task.js';
 
 export { nothing, noChange } from './src/sentinels.js';
 

package/index.d.ts

@@ -9,6 +9,7 @@
  */
 
 export * from './src/component.js';
+export * from './src/converters.js';
 export type {
   Metadata,
   MetadataContext,
@@ -25,6 +26,7 @@ export type {
   AuthorMetadata,
   PreloadDescriptor,
   JsonLd,
+  GenerateMetadata,
 } from './src/metadata.d.ts';
 
 // Typed route props + the opt-in generated route union (#258). The
@@ -36,13 +38,14 @@ export type {
   RouteParams,
   PageProps,
   LayoutProps,
+  FormActionData,
   RouteHandlerContext,
   WebjsRoutes,
   RouteParamMap,
 } from './src/routes.d.ts';
 
 // The package.json `webjs` config block (#259). Typed reference for the
-// elide / headers / redirects / trailingSlash / csp / ingress-limit knobs;
+// seed / headers / redirects / trailingSlash / csp / ingress-limit knobs;
 // the companion JSON Schema (packages/server/webjs-config.schema.json) gives
 // editors native validation of package.json itself.
 export type {
@@ -74,20 +77,25 @@ export type {
   NonSerializable,
 } from './src/serializable.d.ts';
 
-export { html, svg, isTemplate, MARKER } from './src/html.js';
+export { html, svg, mathml, isTemplate, MARKER } from './src/html.js';
+export { isServer } from './src/is-server.js';
 // The `html\`\`` return type. A JSDoc typedef in html.js used across the
 // component / route / testing type surfaces; re-exported so an app or the
 // docs/website can annotate a value as `TemplateResult` (#772).
 export type { TemplateResult } from './src/html.js';
-export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
+export { css, unsafeCSS, CSSResult, isCSS, adoptStyles, stylesToString } from './src/css.js';
+export type { CSSResultGroup, CSSResultOrNative, CSSResultArray } from './src/css.js';
 export { lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
 export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';
+export type { RootPart } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
-export { notFound, redirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
+export { notFound, redirect, permanentRedirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
+export type { RedirectType } from './src/nav.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
+export type { WSConnection, ConnectOptions } from './src/websocket-client.js';
 export { richFetch } from './src/rich-fetch.js';
 export { enableClientRouter, disableClientRouter, revalidate, refreshPage, loadFrame } from './src/router-client.js';
 
@@ -103,21 +111,25 @@ export {
   unsafeHTML, isUnsafeHTML, live, isLive, keyed, isKeyed, guard, isGuard,
   templateContent, isTemplateContent, ref, isRef, createRef, cache, isCache,
   until, isUntil, asyncAppend, isAsyncAppend, asyncReplace, isAsyncReplace,
-  watch, isWatch,
+  watch, isWatch, unsafeSVG, unsafeMathML, when, choose, map, join, range,
 } from './src/directives.js';
-export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';
-export { Task, TaskStatus } from './src/task.js';
+export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent, ContextProviderEvent, ContextRoot } from './src/context.js';
+export { Task, TaskStatus, initialState, shallowArrayEquals, deepArrayEquals } from './src/task.js';
 
 // Signals (the default state primitive, invariant 5), the CSP nonce reader,
 // the wire serializer, and the streaming/frame custom elements. These mirror
 // the index.js runtime re-exports; their declarations live in the matching
 // src/*.d.ts (#388 fixed the index.d.ts drift from index.js).
-export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
+export { signal, computed, effect, batch, isSignal, Signal, SignalWatcher } from './src/signal.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
 export { asset, setAssetUrlProvider } from './src/asset-url.js';
-export { FORM_ACTION_FIELD, FORM_ACTION_ID_KEY, setFormActionResolver } from './src/form-action.js';
+export {
+  FORM_ACTION_FIELD, FORM_ACTION_ID_KEY, setFormActionResolver,
+  installActionBind, bindActionId, splitActionId,
+} from './src/form-action.js';
 export { takeSeed, scanSeeds, seedStats, SEED_MISS } from './src/action-seed-client.js';
 export { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
+export { applyActionRefresh, followActionRedirect } from './src/action-effects-client.js';
 // Client action-abort plumbing (#492): a superseded async render aborts its
 // in-flight action fetches. Inert server-side.
 export { setActiveActionSignal, activeActionSignal } from './src/action-abort-client.js';
@@ -125,7 +137,7 @@ export { setActiveActionSignal, activeActionSignal } from './src/action-abort-cl
 export {
   STREAM_CONTENT_TYPE, FRAME_CHUNK, FRAME_END, FRAME_ERROR, encodeFrame, createFrameDecoder,
 } from './src/action-stream.js';
-export { stringify, parse, serialize, deserialize } from './src/serialize.js';
+export { stringify, stringifySync, parse, serialize, deserialize } from './src/serialize.js';
 export { WebjsFrame } from './src/webjs-frame.js';
 export { WebjsStream, renderStream } from './src/webjs-stream.js';
 

package/index.js

@@ -6,26 +6,31 @@
  * renderer is only reached on the server.
  */
 
-export { html, svg, isTemplate, MARKER } from './src/html.js';
-export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
+export { html, svg, mathml, isTemplate, MARKER } from './src/html.js';
+export { isServer } from './src/is-server.js';
+export { css, unsafeCSS, CSSResult, isCSS, adoptStyles, stylesToString } from './src/css.js';
 export { WebComponent, prop } from './src/component.js';
+export { defaultConverter, notEqual } from './src/converters.js';
 export { lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
 export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
-export { notFound, redirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
+export { notFound, redirect, permanentRedirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
 export { asset, setAssetUrlProvider } from './src/asset-url.js';
 // Form actions (#1155). `FORM_ACTION_FIELD` is the hidden field both renderers
 // emit and the server's form dispatcher reads; `setFormActionResolver` is the
 // server-only wiring that maps a real action function back to its identity.
-export { FORM_ACTION_FIELD, FORM_ACTION_ID_KEY, setFormActionResolver } from './src/form-action.js';
+export {
+  FORM_ACTION_FIELD, FORM_ACTION_ID_KEY, setFormActionResolver,
+  installActionBind, bindActionId, splitActionId,
+} from './src/form-action.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
 export { richFetch } from './src/rich-fetch.js';
 export {
-  stringify, parse,
+  stringify, stringifySync, parse,
   serialize, deserialize,
 } from './src/serialize.js';
 export { enableClientRouter, disableClientRouter, navigate, revalidate, refreshPage, loadFrame } from './src/router-client.js';
@@ -33,7 +38,7 @@ export { WebjsFrame } from './src/webjs-frame.js';
 export { WebjsStream, renderStream } from './src/webjs-stream.js';
 
 // Signals (TC39 Stage-1 shape), also available via '@webjsdev/core/signals'
-export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
+export { signal, computed, effect, batch, isSignal, Signal, SignalWatcher } from './src/signal.js';
 
 // Optimistic-mutation helper (thin signal wrapper, rolls back on failure)
 export { optimistic } from './src/optimistic.js';
@@ -44,6 +49,9 @@ export { takeSeed, scanSeeds, seedStats, SEED_MISS } from './src/action-seed-cli
 // Client tag-cache coordinator for HTTP-verb actions (#488): tag-based
 // browser-cache eviction after a mutation. Inert server-side.
 export { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
+// Effects an RPC action response asks the browser for (revalidatePath's
+// in-place refresh), read by the generated action stub.
+export { applyActionRefresh, followActionRedirect } from './src/action-effects-client.js';
 // Client action-abort plumbing (#492): a superseded async render aborts its
 // in-flight action fetches. Inert server-side.
 export { setActiveActionSignal, activeActionSignal } from './src/action-abort-client.js';
@@ -60,14 +68,14 @@ export {
   unsafeHTML, isUnsafeHTML, live, isLive, keyed, isKeyed, guard, isGuard,
   templateContent, isTemplateContent, ref, isRef, createRef, cache, isCache,
   until, isUntil, asyncAppend, isAsyncAppend, asyncReplace, isAsyncReplace,
-  watch, isWatch,
+  watch, isWatch, unsafeSVG, unsafeMathML, when, choose, map, join, range,
 } from './src/directives.js';
 
 // Context Protocol, also available via '@webjsdev/core/context'
-export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';
+export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent, ContextProviderEvent, ContextRoot } from './src/context.js';
 
 // Task controller, also available via '@webjsdev/core/task'
-export { Task, TaskStatus } from './src/task.js';
+export { Task, TaskStatus, initialState, shallowArrayEquals, deepArrayEquals } from './src/task.js';
 
 export { nothing, noChange } from './src/sentinels.js';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "The runtime for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Ships the html and css template tags, the WebComponent base class, signals, directives, and the isomorphic renderers.",
   "types": "./index.d.ts",
@@ -58,7 +58,20 @@
     },
     "./signals": {
       "types": "./src/signal.d.ts",
-      "default": "./src/signal.js"
+      "source": "./src/signal.js",
+      "default": "./dist/webjs-core-browser.js"
+    },
+    "./directive": {
+      "types": "./src/directive.d.ts",
+      "default": "./src/directive.js"
+    },
+    "./async-directive": {
+      "types": "./src/async-directive.d.ts",
+      "default": "./src/async-directive.js"
+    },
+    "./static-html": {
+      "types": "./src/static-html.d.ts",
+      "default": "./src/static-html.js"
     },
     "./package.json": "./package.json"
   },

package/src/action-effects-client.d.ts

@@ -0,0 +1,5 @@
+/** Browser effects a server action's RPC response asks for (revalidatePath's in-place refresh). Read by the generated action stub. */
+export function parseRefreshHeader(value: string | null | undefined): { path: string; layout: boolean }[];
+export function refreshCovers(entry: { path: string; layout: boolean }, pathname: string): boolean;
+export function applyActionRefresh(value: string | null | undefined): Promise<boolean>;
+export function followActionRedirect(value: string): Promise<never>;

package/src/action-effects-client.js

@@ -0,0 +1,84 @@
+/**
+ * Browser-side effects a server action's RPC response asks for, the Next.js
+ * behaviours an `await action()` call has after the action ran:
+ *
+ *   - `x-webjs-refresh` (written when the action called `revalidatePath`):
+ *     evict the client router's cached copies of those paths and, when the
+ *     page on screen is one of them, re-render it in place (`refreshPage`), so
+ *     the caller sees fresh server data with no reload.
+ *   - `x-webjs-redirect` (the action threw `redirect()` / `permanentRedirect()`):
+ *     navigate there with the client router (a full load for another origin),
+ *     and reject the call with the redirect sentinel, so code after
+ *     `await action()` does not run, exactly as in Next.
+ *
+ * The generated action stub calls these; app code does not need to.
+ *
+ * @module action-effects-client
+ */
+import { revalidate, refreshPage, navigate } from './router-client/navigator.js';
+import { isRedirect } from './nav.js';
+import { parseRefreshHeader, refreshCovers } from './refresh-header.js';
+
+export { parseRefreshHeader, refreshCovers };
+
+/**
+ * Apply an `x-webjs-refresh` header: evict the cached snapshots it names, and
+ * refresh the current page in place when it is one of them (a `layout` entry
+ * refreshes the whole shell, since the layout's own markup may have changed).
+ * Resolves once the refresh applied, so `await action()` returns after the
+ * page shows the new data, as in Next.
+ * @param {string | null | undefined} value
+ * @returns {Promise<boolean>} whether the current page was refreshed
+ */
+export async function applyActionRefresh(value) {
+  const entries = parseRefreshHeader(value);
+  if (!entries.length || typeof location === 'undefined') return false;
+  let current = false;
+  let shell = false;
+  for (const e of entries) {
+    const pattern = e.layout || e.path.includes('[');
+    if (pattern) revalidate();
+    else revalidate(e.path);
+    if (refreshCovers(e, location.pathname)) {
+      current = true;
+      if (e.layout) shell = true;
+    }
+  }
+  if (!current) return false;
+  try { return await refreshPage(shell ? 'shell' : 'page'); } catch { return false; }
+}
+
+let rejectionFilterInstalled = false;
+
+/**
+ * Follow an `x-webjs-redirect` header (`<url>;<push|replace>`): a same-origin
+ * target goes through the client router, another origin is a full load.
+ * Returns a promise rejected with the redirect sentinel, and makes sure an
+ * unhandled one (a fire-and-forget `action()` in a click handler) is not
+ * reported as an error, since it is navigation.
+ * @param {string} value
+ * @returns {Promise<never>}
+ */
+export function followActionRedirect(value) {
+  const cut = value.lastIndexOf(';');
+  const url = cut === -1 ? value : value.slice(0, cut);
+  const replace = cut !== -1 && value.slice(cut + 1) === 'replace';
+  const err = new Error(`webjs: redirect(${url})`);
+  /** @type {any} */ (err).__webjs = Symbol.for('webjs.redirect');
+  /** @type {any} */ (err).url = url;
+  if (typeof location !== 'undefined') {
+    if (!rejectionFilterInstalled && typeof addEventListener === 'function') {
+      rejectionFilterInstalled = true;
+      addEventListener('unhandledrejection', (e) => { if (isRedirect(e.reason)) e.preventDefault(); });
+    }
+    let target;
+    try { target = new URL(url, location.href); } catch { target = null; }
+    if (target && target.origin === location.origin) {
+      Promise.resolve(navigate(target.pathname + target.search + target.hash, { replace })).catch(() => location.assign(target.href));
+    } else if (target) {
+      if (replace) location.replace(target.href);
+      else location.assign(target.href);
+    }
+  }
+  return Promise.reject(err);
+}

package/src/action-seed-client.js

@@ -165,7 +165,7 @@ export function scanSeeds(root, opts) {
 
   // The live document can still be holding the OUTGOING page's block, because
   // the initial scan is lazy (it runs on the first `takeSeed`) and a page whose
-  // async components all elided never triggers it, while the block sits after
+  // async components are all server-only never triggers it, while the block sits after
   // the body content outside every boundary range, so no swap removes it either.
   //
   // Strip it WITHOUT ingesting. Those values belong to a page that is being
@@ -173,7 +173,7 @@ export function scanSeeds(root, opts) {
   // them for the lazy scan to ingest LATER is what let a departed page's value
   // win a key under last-write-wins and contradict the paint. Ingesting them
   // HERE would order them correctly but keep them forever, because the very
-  // reason the block went unconsumed is that its components elided, so nothing
+  // reason the block went unconsumed is that its components never ship, so nothing
   // will ever call `takeSeed` for those keys and nothing but a hit deletes one.
   // That would grow the store by a whole page payload per navigation, in
   // production, and inflate the "still unconsumed" figure in the dev line with
@@ -183,9 +183,9 @@ export function scanSeeds(root, opts) {
   if (incomingPage) {
     drainCarriers(live, true);
     // And evict what the outgoing page ALREADY ingested. Stripping the DOM
-    // carrier is not enough: a page carrying an elided component alongside a
+    // carrier is not enough: a page carrying a server-only component alongside a
     // shipping one has its WHOLE block ingested by the lazy scan the shipping
-    // one triggers, so the elided component's keys are in the store with no
+    // one triggers, so the server-only component's keys are in the store with no
     // carrier left to strip and nothing that will ever consume them. Navigate to
     // a page that emits no seed for such a key (a streamed page emits no block
     // at all) and a component calling the same action with the same arguments
@@ -424,7 +424,7 @@ export function takeSeed(hash, fnName, argsKey) {
  * `replaced` are what `scanSeeds` merged; `hits` and `misses` are what the
  * generated RPC stubs asked for; `pending` is what is still in the store
  * unconsumed (a non-zero `pending` at rest usually means the seeding component
- * elided, so nothing on the client was ever going to call it).
+ * is server-only, so nothing on the client was ever going to call it).
  * `keyMisses` is the provable subset of `misses`: a call for an action this page
  * DID seed under other arguments, which is the only miss the client can call a
  * defect (see `seedFns`).

package/src/asset-url.js

@@ -1,10 +1,11 @@
 /**
- * Resolve a `public/` asset url to its content-fingerprinted form, so a
+ * Resolve a `public/` asset url (served at the url ROOT: `public/app.css` is
+ * `/app.css`, as in Next.js) to its content-fingerprinted form, so a
  * deploy that changes the file changes the url and no cache can serve the
  * previous bytes.
  *
  *   import { html, asset } from '@webjsdev/core';
- *   html`<link rel="stylesheet" href=${asset('/public/app.css')}>`
+ *   html`<link rel="stylesheet" href=${asset('/app.css')}>`
  *
  * On the server, `@webjsdev/server` installs a provider that appends
  * `?v=<content-hash>`; the framework then serves a `?v=`-carrying request
@@ -18,7 +19,7 @@
  * the hydrate marker and `createInstance` replaces the SSR'd children), so
  * the client value overwrites the server one. With no provider in the
  * browser, `asset()` returns the bare path there, so an `<img src=${asset(
- * '/public/logo.svg')}>` inside a shipping component paints the hashed url
+ * '/logo.svg')}>` inside a shipping component paints the hashed url
  * at SSR and then swaps it for the un-hashed one on upgrade, fetching the
  * same bytes twice and leaving the short-lived url in the DOM. It still
  * WORKS (the path is always valid), which is why this is a convention rather
@@ -28,13 +29,11 @@
  * The sibling `cspNonce()` carries the same server/browser asymmetry and the
  * same scoping, for the same hydration reason.
  *
- * Call it INSIDE the render function, not at module scope. A depth-0 call is a
- * module-scope side effect, which the elision analyser reads as client work, so
- * hoisting `const CSS = asset('/public/app.css')` pins the whole page or layout
- * into the browser bundle for no benefit. Resolver ordering is not the issue
- * (the server installs its resolver at boot, before any app module loads).
+ * Calling it at module scope works too: the server installs its resolver at
+ * boot, before any app module loads, so a hoisted `const CSS =
+ * asset('/app.css')` in a page or layout resolves the same as one in render.
  *
- * Under `webjs.basePath`, write the prefix yourself: `asset('/app/public/x.css')`.
+ * Under `webjs.basePath`, write the prefix yourself: `asset('/app/x.css')`.
  * The framework only base-path-prefixes urls IT emits, so an author-written
  * url is already your responsibility (an un-prefixed one 404s under a
  * sub-path deploy with or without this helper). `asset()` strips the prefix
@@ -58,9 +57,9 @@
  * exactly the set of urls someone deliberately marked and nothing else in the
  * document is ever read or rewritten.
  *
- * Scope note: only a `public/` path is fingerprinted, matching what the
- * static-asset route will actually serve. Anything else is returned
- * unchanged rather than guessed at.
+ * Scope note: only a file that exists under `public/` is fingerprinted,
+ * matching what the static-asset route will actually serve. Anything else is
+ * returned unchanged rather than guessed at.
  */
 
 /** @type {((path: string) => string) | null} */
@@ -85,7 +84,7 @@ export function setAssetUrlProvider(fn) {
  * resolved. Every failure mode degrades to the plain path, never to a broken
  * one.
  *
- * @param {string} path  a root-absolute same-origin path, e.g. `/public/app.css`
+ * @param {string} path  a root-absolute same-origin path, e.g. `/app.css`
  * @returns {string}
  */
 export function asset(path) {

package/src/async-directive.d.ts

@@ -0,0 +1,18 @@
+import { Directive } from './directive.js';
+import type { PartInfo } from './directive.js';
+
+export { directive, Directive, PartType } from './directive.js';
+export type { PartInfo, Part, DirectiveResult, DirectiveParameters } from './directive.js';
+
+/** lit's `AsyncDirective`: can `setValue()` outside a render and observes connection. */
+export abstract class AsyncDirective extends Directive {
+  constructor(partInfo: PartInfo);
+  /** Whether the host component is in the document. */
+  isConnected: boolean;
+  /** Commit a value to the part outside a render. A no-op on the server. */
+  setValue(value: unknown): void;
+  /** The host left the document, or the part was torn down. */
+  protected disconnected(): void;
+  /** The host came back. */
+  protected reconnected(): void;
+}

package/src/async-directive.js

@@ -0,0 +1,88 @@
+/**
+ * Async directive authoring, lit's `lit/async-directive.js` under a WebJs
+ * path: `@webjsdev/core/async-directive`.
+ *
+ * Portions derived from Lit, Copyright Google LLC, BSD-3-Clause.
+ *
+ * An `AsyncDirective` can push a value into its part outside a render with
+ * `setValue()`, and is told when the component that rendered it leaves the
+ * document (`disconnected()`) and comes back (`reconnected()`), so it can drop
+ * and re-establish a subscription.
+ *
+ * ```js
+ * import { AsyncDirective, directive } from '@webjsdev/core/async-directive';
+ *
+ * class Ticker extends AsyncDirective {
+ *   render(ms) {
+ *     this.#start(ms);
+ *     return 0;
+ *   }
+ *   #start(ms) {
+ *     clearInterval(this.id);
+ *     let n = 0;
+ *     this.id = setInterval(() => this.setValue(++n), ms);
+ *   }
+ *   disconnected() { clearInterval(this.id); }
+ *   reconnected() { this.#start(1000); }
+ * }
+ * export const ticker = directive(Ticker);
+ * ```
+ *
+ * Connection follows the HOST component (the one whose template holds the
+ * part), plus the part's own lifetime: a directive whose part is torn down, or
+ * replaced by a different directive class, is disconnected for good. On the
+ * server `setValue()` does nothing and only `render()` runs.
+ *
+ * @module async-directive
+ */
+
+import { Directive } from './directive.js';
+
+export { directive, Directive, PartType } from './directive.js';
+
+export class AsyncDirective extends Directive {
+  /** @param {{ type: number, name?: string, tagName?: string, strings?: readonly string[] }} partInfo */
+  constructor(partInfo) {
+    super(partInfo);
+    /**
+     * Whether the directive's host is in the document. `true` until the
+     * renderer reports otherwise.
+     * @type {boolean}
+     */
+    this.isConnected = true;
+    /**
+     * Installed by the client renderer: commits a value to this directive's
+     * part. Absent at SSR, where `setValue()` is a no-op.
+     * @type {((value: unknown) => void) | undefined}
+     */
+    this._$webjsCommit = undefined;
+  }
+
+  /**
+   * Commit `value` to the part outside a render, as if the directive had
+   * returned it. A no-op on the server. As in lit, stop calling it once
+   * `disconnected()` runs.
+   * @param {unknown} value
+   */
+  setValue(value) {
+    if (this._$webjsCommit) this._$webjsCommit(value);
+  }
+
+  /**
+   * Called by the renderer when the connection state changes; dispatches to
+   * `disconnected()` / `reconnected()` once per transition.
+   * @param {boolean} connected
+   */
+  _$webjsSetConnected(connected) {
+    if (connected === this.isConnected) return;
+    this.isConnected = connected;
+    if (connected) this.reconnected();
+    else this.disconnected();
+  }
+
+  /** The host left the document, or the part was torn down. Release resources. */
+  disconnected() {}
+
+  /** The host came back. Re-establish what `disconnected()` released. */
+  reconnected() {}
+}