@webjsdev/core 0.8.0 → 0.9.1

package/src/router-client/navigator.js

@@ -154,7 +154,9 @@ export function enableClientRouter() {
   // never calls this, and a page that ships no component never loads
   // @webjsdev/core at all, so both no-router cases resolve to a full reload
   // without either side assuming anything about the other.
-  /** @type any */ (globalThis).__webjsRefreshPage = refreshPage;
+  // It publishes the OUTCOME form (`refreshOutcome`), so the client can tell
+  // a refresh that applied from one that kept the page under a dev error.
+  /** @type any */ (globalThis).__webjsRefreshPage = refreshOutcome;
   // Both `click` and `submit` are BUBBLE phase, not capture. A component's
   // per-element `@click` / `@submit` handler (render-client.js) runs in the
   // at-target phase, BEFORE a document-level bubble listener. So onClick /
@@ -446,7 +448,24 @@ export function revalidate(url) {
  *   caller should fall back to a full load.
  */
 export async function refreshPage(mode) {
-  if (!enabled || typeof location === 'undefined') return false;
+  return (await refreshOutcome(mode)) !== 'failed';
+}
+
+/**
+ * What `refreshPage` did, for the dev live-reload client (#1689), which reads
+ * it through `globalThis.__webjsRefreshPage`: `'applied'` swapped the new
+ * render in, `'settled'` found the page already resolved (a hard navigation,
+ * a snapshot restore, or a newer navigation that owns it), `'dev-error'` kept
+ * the last good page because the dev server answered with a render error, and
+ * `'failed'` applied nothing, so the caller falls back to a full load. The dev
+ * client logs an in-place update only for `'applied'`, so the console never
+ * reports success for an edit that broke the page.
+ *
+ * @param {'page' | 'shell'} [mode]
+ * @returns {Promise<'applied' | 'settled' | 'dev-error' | 'failed'>}
+ */
+async function refreshOutcome(mode) {
+  if (!enabled || typeof location === 'undefined') return 'failed';
   // Every cached copy predates the change, so drop both caches before fetching.
   revalidate();
   // And the refusal memos (#1407), which `revalidate` deliberately leaves alone
@@ -456,9 +475,8 @@ export async function refreshPage(mode) {
   // browser does NOT download: a page gaining or losing a `Suspense(...)`
   // boundary is the plain case, since rendering one does not by itself make the
   // page client-effecting, so it classifies `page` rather than a reload. An edit
-  // to anything that SHIPS reloads instead and never arrives, which covers a
-  // `loading.{js,ts}` either direction (it can never be elided, so it is always
-  // shipped, and a brand-new one is in no graph at all).
+  // to anything that SHIPS reloads instead and never arrives, and so does a
+  // brand-new `loading.{js,ts}`, which is in no graph at all.
   clearPrefetchRefused();
   try {
     const res = await performNavigation(location.href, false, null, { refresh: mode === 'shell' ? 'shell' : 'page' });
@@ -482,10 +500,15 @@ export async function refreshPage(mode) {
     // superseded this one and owns the page now, and reloading would yank the
     // reader out of it; Turbo drops a refresh that lands mid-navigation for the
     // same reason.
-    if (!res || res.aborted) return true;
-    return res.applied;
+    //
+    // And a `devError` is not one (#1689): the dev server rendered an error for
+    // this page and the overlay shows it. The page stays as it was under the
+    // overlay, and the edit that fixes it refreshes in place.
+    if (!res || res.aborted) return 'settled';
+    if (res.devError) return 'dev-error';
+    return res.applied ? 'applied' : 'failed';
   } catch (_) {
-    return false;
+    return 'failed';
   }
 }
 
@@ -864,7 +887,12 @@ export async function performSubmission(href, method, body, frameId, form, opts)
     navigatingFlagTimer = null;
   }, 150);
 
-  const optimisticState = applyOptimisticLoading();
+  // A write keeps the page it was submitted from on screen while it runs, as a
+  // Next.js server-action form does (#1686): `loading.ts` is a navigation
+  // skeleton, and showing it for a write detached the very form being
+  // submitted, so a validation re-render lost what was typed. A safe-method
+  // submission (a search) is a navigation and keeps the skeleton.
+  const optimisticState = isSafe ? applyOptimisticLoading() : null;
 
   // Submission-state lifecycle: mark the form busy + announce the start, then
   // clear + announce the settle in the finally so EVERY exit (success,
@@ -900,6 +928,14 @@ export async function performSubmission(href, method, body, frameId, form, opts)
       await _swapCommit;
       if (myToken === currentNavigationToken) restoreFormState(typed);
     }
+    // A successful write that stayed on this page resets the form, as React
+    // does for a form whose action succeeded (#1686), so the next entry starts
+    // from the defaults the server just rendered. A redirect elsewhere leaves
+    // the page and needs nothing.
+    if (!isSafe && form && outcome && outcome.ok && outcome.applied && outcome.samePage && myToken === currentNavigationToken) {
+      await _swapCommit;
+      if (myToken === currentNavigationToken && form.isConnected && typeof form.reset === 'function') form.reset();
+    }
     // Mutating submissions invalidate cached versions of other URLs -
     // do this *after* the response applies so the new page itself is
     // snapshotted on the next nav, not pre-emptively wiped. Clear the

package/src/router-client/prefetch.js

@@ -92,10 +92,9 @@ function prefetchRefusedRecently(key) {
  * dev live-reload path, where an edit can add or remove a `Suspense` boundary
  * and so start or stop the route streaming. Only an edit to a file the browser
  * does NOT download arrives there; anything that SHIPS takes a full reload
- * instead. A `loading.{js,ts}` reloads either way, though for two different
- * reasons: editing or deleting one reloads because it can never be elided and
- * so always ships, while ADDING one reloads because a brand-new file is in no
- * set the previous build produced.
+ * instead. A `loading.{js,ts}` is a route module, so editing one arrives here
+ * like a page edit (it never ships, #1686), while ADDING one reloads because a
+ * brand-new file is in no set the previous build produced.
  *
  * NEITHER form of `revalidate` clears them, which is a cost/benefit call rather
  * than an impossibility. It is the post-MUTATION api an app calls after an RPC

package/src/router-client/root-attrs.js

@@ -0,0 +1,43 @@
+/**
+ * `<html>` and `<body>` attributes follow the server across a soft navigation
+ * (#1686). The root layout owns them (`<html class=${theme}>`, `<body
+ * class=...>`), and a Next.js developer expects a changed theme cookie to
+ * show once the action or navigation lands, as it does when the root layout
+ * re-renders there. The swap replaces content inside `<body>`, so without
+ * this the attributes stayed as the first load left them until a reload.
+ *
+ * Only attributes the SERVER rendered are touched: the server lists their
+ * names in `data-wj-html` / `data-wj-body`, so an attribute a script sets in
+ * the browser (a theme bootstrap writing `data-theme` from localStorage) is
+ * never removed. A response that did not render the root layout (a reduced
+ * `X-Webjs-Have` fragment) carries no list and changes nothing.
+ */
+
+const MARKS = /** @type {const} */ ([['documentElement', 'data-wj-html'], ['body', 'data-wj-body']]);
+
+/** @param {string | null} v */
+const names = (v) => (v || '').split(/\s+/).filter(Boolean);
+
+/**
+ * Bring the live `<html>` and `<body>` attributes in line with an incoming
+ * page's, for the attributes its server rendered.
+ * @param {Document} doc the parsed incoming page
+ */
+export function syncRootAttributes(doc) {
+  if (typeof document === 'undefined' || !doc) return;
+  for (const [key, mark] of MARKS) {
+    const incoming = /** @type {Element | null} */ (/** @type any */ (doc)[key]);
+    const live = /** @type {Element | null} */ (/** @type any */ (document)[key]);
+    if (!incoming || !live || !incoming.hasAttribute(mark)) continue;
+    const next = names(incoming.getAttribute(mark));
+    for (const n of names(live.getAttribute(mark))) {
+      if (!next.includes(n)) live.removeAttribute(n);
+    }
+    for (const n of next) {
+      const v = incoming.getAttribute(n);
+      if (v === null) live.removeAttribute(n);
+      else if (live.getAttribute(n) !== v) live.setAttribute(n, v);
+    }
+    live.setAttribute(mark, next.join(' '));
+  }
+}

package/src/router-client/stream.js

@@ -8,6 +8,7 @@
  */
 import { warnDropped } from './diagnostics.js';
 import { upgradeTree } from './upgrade.js';
+import { navigate } from './navigator.js';
 
 /**
  * Forward streamed Suspense resolver templates from the fetched body to
@@ -155,6 +156,12 @@ export function applyStreamedResolve(id, content) {
   const tpl = document.createElement('template');
   tpl.innerHTML = content;
   const inserted = [...tpl.content.childNodes];
+  // A boundary whose content threw redirect() on the server streams a marker
+  // (#1686): follow it the way a first load follows its refresh.
+  for (const n of inserted) {
+    const to = n.nodeType === 1 ? /** @type {Element} */ (n).getAttribute('data-webjs-redirect') : null;
+    if (to) { navigate(to, { replace: true }); return; }
+  }
   boundary.replaceWith(tpl.content);
   // Upgrade any custom elements now that they are connected (belt-and-braces:
   // a connected, defined element upgrades on insertion, but a fragment that was

package/src/router-client/swap.js

@@ -7,6 +7,7 @@
  * @module
  */
 import { scanSeeds } from '../action-seed-client.js';
+import { syncRootAttributes } from './root-attrs.js';
 import { collectBoundaries, planBoundarySwap } from './boundaries.js';
 import { reportFallback } from './diagnostics.js';
 import { blurOutgoingFocus, diffChildren, replaceBoundaryRange, resyncEnclosingHostSlots, swapMarkerRange } from './dom-differ.js';
@@ -113,6 +114,8 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
     if (seedsScanned) return;
     seedsScanned = true;
     try { scanSeeds(doc, { frame: !!frameId }); } catch { /* seeding is best-effort */ }
+    // The root layout's <html> / <body> attributes follow the server (#1686).
+    if (!frameId) { try { syncRootAttributes(doc); } catch { /* best-effort */ } }
   };
 
   // Every host in this parsed doc is FRAMEWORK-SERIALIZED markup (an SSR
@@ -123,7 +126,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
   // conditionally closed slot at snapshot time) where the structural
   // slot-marker detector has nothing to see. The chooser consumes and removes
   // the attribute on upgrade.
-  // (An ELIDED display-only host never upgrades, so its stamp is retained as
+  // (A server-only host never upgrades, so its stamp is retained as
   // an inert attribute; diffElementInPlace never copies it onto a live host,
   // and the upgrade path consumes it, so it cannot mis-route anything.)
   try {

package/src/routes.d.ts

@@ -73,16 +73,44 @@ export type Route = _HasRoutes extends true
   ? { [K in keyof WebjsRoutes]: RoutePattern<K & string> }[keyof WebjsRoutes]
   : string;
 
+/**
+ * The params a route key's own text declares, read without a generated
+ * `RouteParamMap`: `[x]` is a `string`, `[...x]` a `string[]` (as in Next.js)
+ * and `[[...x]]` an optional `string[]`. Segments are read left to right from
+ * the first `[`, so every one is kept; the text up to the first `]` of
+ * `[[...x]]` is `[...x`, which is how the optional form is told apart.
+ */
+type InferredParams<K extends string> =
+  K extends `${string}[${infer Seg}]${infer Rest}`
+    ? Seg extends `[...${infer N}`
+      ? { [P in N]?: string[] } & InferredParams<Rest extends `]${infer After}` ? After : Rest>
+      : Seg extends `...${infer N}`
+        ? { [P in N]: string[] } & InferredParams<Rest>
+        : { [P in Seg]: string } & InferredParams<Rest>
+    : {};
+
+/**
+ * The params for a route key with no generated entry: what its text declares,
+ * or, for a static route and for the wide `string` key, the runtime default
+ * `Record<string, string>`.
+ */
+type FallbackParams<R extends string> = string extends R
+  ? Record<string, string>
+  : keyof InferredParams<R> extends never
+    ? Record<string, string>
+    : InferredParams<R>;
+
 /**
  * The params object for a route key. A generated dynamic route resolves to
  * its `RouteParamMap` entry (`{ slug: string }`, `{ rest: string[] }`,
- * `{ slug?: string[] }`); anything else (a static route, or any route in an
- * un-generated app) resolves to `Record<string, string>`, the runtime
- * default the SSR pipeline produces.
+ * `{ slug?: string[] }`). Without one (an app that never ran `webjs types`),
+ * a dynamic route key still yields the same shape, read from the key itself,
+ * and a static route resolves to `Record<string, string>`, the runtime default
+ * the SSR pipeline produces.
  */
 export type RouteParams<R extends string> = R extends keyof RouteParamMap
   ? RouteParamMap[R]
-  : Record<string, string>;
+  : FallbackParams<R>;
 
 /**
  * A value that is BOTH synchronously usable as `T` and `await`-able to `T`
@@ -97,11 +125,9 @@ export type Awaitable<T> = T & PromiseLike<T>;
  * packages/server/src/ssr.js builds: `{ params, searchParams, url,
  * actionData }`.
  *
- * `searchParams` is typed `Record<string, string | string[]>` to match the
- * established page-context convention, even though the runtime builds it with
- * `Object.fromEntries(url.searchParams.entries())` (so a repeated key is
- * last-wins `string`, never an array). The wider type keeps a future
- * multi-value reader source-compatible.
+ * `searchParams` is `Record<string, string | string[]>`, as in Next.js: a key
+ * that repeats in the query (`?tag=a&tag=b`) is an array of every value, in
+ * order, and any other key is its string.
  *
  * `params` / `searchParams` are `Awaitable<T>` (#848): synchronously readable
  * (`params.id`) AND `await`-able (`const { id } = await params`) for Next
@@ -109,13 +135,42 @@ export type Awaitable<T> = T & PromiseLike<T>;
  * `then` (see packages/server/src/thenable-params.js), so a spread / JSON /
  * `Object.keys` sees only the data keys.
  */
-export interface PageProps<R extends string = string> {
+/**
+ * What a form action hands the page, by default: a failure result re-rendered
+ * (`{ success: false, error, fieldErrors }` is the usual shape) with the
+ * submitted text fields on `values`, or a success result carried across the
+ * redirect (`{ success: true, data }`). The common keys are typed; anything
+ * else the action returned reads as `any`, so `actionData?.data.manageKey`
+ * compiles without a cast, the way an untyped `useActionState` state does in
+ * Next. Name the exact shape with `PageProps`'s second type parameter,
+ * `PageProps<'/route', Awaited<ReturnType<typeof myAction>>>`, for full typing.
+ */
+export interface FormActionData {
+  success?: boolean;
+  error?: string;
+  /**
+   * Per-field messages. Typed loosely, as `data` is: the page cannot see the
+   * action's return type, and actions return a `Record<string, string>` as
+   * often as a validator's `Record<string, string[]>`, so either assigns
+   * without a cast.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  fieldErrors?: Record<string, any>;
+  values?: Record<string, string>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data?: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any;
+}
+
+export interface PageProps<R extends string = string, A = FormActionData> {
   /**
-   * Path params. A generated dynamic route narrows this to its exact shape
-   * (`{ slug: string }`); a static or un-generated route is
-   * `Record<string, string>`. Sync-readable and `await`-able (#848).
+   * Path params, narrowed to the route's shape (`{ slug: string }`,
+   * `{ rest: string[] }`) from the generated map or, without one, from the
+   * route key itself; a static route is `Record<string, string>`.
+   * Sync-readable and `await`-able (#848).
    */
-  params: Awaitable<R extends keyof RouteParamMap ? RouteParamMap[R] : Record<string, string>>;
+  params: Awaitable<RouteParams<R>>;
   /** Query string, as an object. Repeated keys are last-wins at runtime. Sync-readable and `await`-able (#848). */
   searchParams: Awaitable<Record<string, string | string[]>>;
   /** The full request URL string. */
@@ -125,9 +180,11 @@ export interface PageProps<R extends string = string> {
    * (#244). `undefined` on a normal GET render. Read `actionData.fieldErrors`
    * / `actionData.values` to surface validation errors and repopulate inputs.
    * On a failure `values` carries every submitted text field, with the action's
-   * own `values` on top (#1581).
+   * own `values` on top (#1581). Typed {@link FormActionData} by default; pass
+   * the action's result type as the second parameter,
+   * `PageProps<'/route', MyResult>`, to type it exactly.
    */
-  actionData?: unknown;
+  actionData?: A;
 }
 
 /**
@@ -135,7 +192,7 @@ export interface PageProps<R extends string = string> {
  * the rendered `children`. Mirrors the `{ children, params, searchParams, url
  * }` object packages/server/src/ssr.js passes a layout.
  */
-export interface LayoutProps<R extends string = string> extends PageProps<R> {
+export interface LayoutProps<R extends string = string, A = FormActionData> extends PageProps<R, A> {
   /** The nested page / inner-layout content this layout must embed. */
   children: TemplateResult;
 }
@@ -149,5 +206,5 @@ export interface LayoutProps<R extends string = string> extends PageProps<R> {
  */
 export interface RouteHandlerContext<R extends string = string> {
   /** Sync-readable and `await`-able (#848), same as `PageProps['params']`. */
-  params: Awaitable<R extends keyof RouteParamMap ? RouteParamMap[R] : Record<string, string>>;
+  params: Awaitable<RouteParams<R>>;
 }

package/src/serialize.d.ts

@@ -3,6 +3,8 @@
  * Error / typed arrays / Blob / File / FormData / Symbols / cycles).
  */
 export function stringify(value: unknown): Promise<string>;
+/** `stringify` done synchronously, for a value holding no File or Blob (it throws on one). */
+export function stringifySync(value: unknown): string;
 export function parse(text: string): unknown;
 export function serialize(value: unknown): Promise<unknown>;
 export function deserialize(value: unknown): unknown;

package/src/serialize.js

@@ -96,6 +96,23 @@ export async function stringify(value) {
   return JSON.stringify(await serialize(value));
 }
 
+/**
+ * `stringify` for a value holding no Blob, File or FormData file, done
+ * synchronously. A bound form action's arguments need it: `.bind()` returns at
+ * once and the browser renderer reads the identity synchronously. Throws on a
+ * file, whose bytes can only be read asynchronously.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function stringifySync(value) {
+  const ctx = newEncodeCtx();
+  if (walkRefs(value, ctx).length) {
+    throw new TypeError('[webjs] a File or Blob cannot be serialized synchronously (it cannot be a bound argument of a form action).');
+  }
+  return JSON.stringify(encodeOne(value, ctx));
+}
+
 /**
  * Inverse of `stringify`. Synchronous: no async types need awaiting
  * during decode (binary is already inlined as base64).
@@ -153,10 +170,24 @@ function newEncodeCtx() {
 
 /**
  * Pass 1: walk the value, count references, pre-read Blob/File bytes.
- * Async because `Blob.arrayBuffer()` is async. Iterative (uses an
- * explicit stack) to avoid recursion limits on deeply nested values.
+ * Async because `Blob.arrayBuffer()` is async. The walk itself is the
+ * synchronous `walkRefs`; only the byte reads it collects are awaited.
  */
 async function countRefs(value, ctx) {
+  for (const blob of walkRefs(value, ctx)) {
+    ctx.blobBytes.set(blob, new Uint8Array(await blob.arrayBuffer()));
+  }
+}
+
+/**
+ * Count references and assign ids to shared objects, returning the Blob/File
+ * values found (whose bytes the async path then reads). Iterative (an explicit
+ * stack) to avoid recursion limits on deeply nested values.
+ * @returns {Blob[]}
+ */
+function walkRefs(value, ctx) {
+  /** @type {Blob[]} */
+  const blobs = [];
   const stack = [value];
   while (stack.length) {
     const v = stack.pop();
@@ -165,8 +196,7 @@ async function countRefs(value, ctx) {
     ctx.refCount.set(v, cur + 1);
     if (cur > 0) continue;  // already traversed children
     if (typeof Blob !== 'undefined' && v instanceof Blob) {
-      const buf = new Uint8Array(await v.arrayBuffer());
-      ctx.blobBytes.set(v, buf);
+      blobs.push(v);
       continue;
     }
     if (typeof FormData !== 'undefined' && v instanceof FormData) {
@@ -195,6 +225,7 @@ async function countRefs(value, ctx) {
   for (const [obj, count] of ctx.refCount) {
     if (count > 1) ctx.idOf.set(obj, ctx.nextId++);
   }
+  return blobs;
 }
 
 function encodeOne(v, ctx) {

package/src/signal.d.ts

@@ -15,6 +15,13 @@ export function computed<T>(fn: () => T, options?: Record<string, unknown>): Sig
 export function isSignal(v: unknown): v is SignalState | SignalComputed;
 export function effect(fn: () => void): () => void;
 
+/**
+ * Lit's `SignalWatcher` mixin, an identity here: a `WebComponent` already
+ * re-renders when a signal it read changes.
+ */
+export function SignalWatcher<T extends abstract new (...args: any[]) => any>(Base: T): T;
+export { watch } from './directives.js';
+
 export const Signal: {
   State: new <T>(initial: T, options?: Record<string, unknown>) => SignalState<T>;
   Computed: new <T>(fn: () => T, options?: Record<string, unknown>) => SignalComputed<T>;

package/src/signal.js

@@ -426,7 +426,7 @@ class SignalComputed {
  * Watcher
  * ============================================================ */
 
-class SignalWatcher {
+class WatcherImpl {
   /** @param {() => void} notifyCb */
   constructor(notifyCb) {
     this.__notify = notifyCb;
@@ -553,7 +553,7 @@ function untrack(fn) {
   try { return fn(); } finally { activeConsumer = prev; }
 }
 
-/** @param {SignalComputed | SignalWatcher} sink */
+/** @param {SignalComputed | WatcherImpl} sink */
 function introspectSources(sink) {
   return sink.producers.slice();
 }
@@ -568,7 +568,7 @@ function hasSinks(producer) {
   return !!producer.liveConsumers && producer.liveConsumers.size > 0;
 }
 
-/** @param {SignalComputed | SignalWatcher} sink */
+/** @param {SignalComputed | WatcherImpl} sink */
 function hasSources(sink) {
   return sink.producers.length > 0;
 }
@@ -618,7 +618,7 @@ export const Signal = {
   State: SignalState,
   Computed: SignalComputed,
   subtle: {
-    Watcher: SignalWatcher,
+    Watcher: WatcherImpl,
     untrack,
     introspectSources,
     introspectSinks,
@@ -662,7 +662,7 @@ export function isSignal(v) {
  *
  * Effects are useful for browser-only side effects such as DOM
  * mutations, timers, or fetch calls. Avoid in render paths; the
- * component's built-in SignalWatcher already covers re-render.
+ * component's built-in signal watching already covers re-render.
  *
  * The spec forbids reads/writes inside a Watcher notify, so effects
  * defer the re-run to a microtask.
@@ -674,7 +674,7 @@ export function effect(fn) {
   let scheduled = false;
   let disposed = false;
   const computed_ = new SignalComputed(fn);
-  const w = new SignalWatcher(() => {
+  const w = new WatcherImpl(() => {
     if (scheduled || disposed) return;
     scheduled = true;
     queueMicrotask(() => {
@@ -692,3 +692,23 @@ export function effect(fn) {
     w.dispose();
   };
 }
+
+/**
+ * Lit's `SignalWatcher` mixin (`@lit-labs/signals`), here an IDENTITY: a
+ * `WebComponent` already re-renders when a signal it read changes, so
+ * `class X extends SignalWatcher(WebComponent)` is the same class as
+ * `class X extends WebComponent`. Kept so code written from Lit's signals
+ * package works unchanged.
+ *
+ * @template {abstract new (...args: any[]) => any} T
+ * @param {T} Base
+ * @returns {T}
+ */
+export function SignalWatcher(Base) {
+  return Base;
+}
+
+// `watch(signal)` from `@lit-labs/signals` is the fine-grained binding
+// directive WebJs already ships, re-exported so `@webjsdev/core/signals`
+// carries the whole Lit signals surface.
+export { watch } from './directives.js';

package/src/slot/polyfills.js

@@ -186,11 +186,11 @@ export function manualSlotFor(state, node) {
 /**
  * Walk up from a light slot to its owning host: the nearest SLOT_STATE
  * ancestor that actually OWNS the slot. A slot separated from that ancestor
- * by another custom element (a forwarded slot inside a foreign / elided
+ * by another custom element (a forwarded slot inside a foreign / server-only
  * component) is nobody's here: attributing it to the outer host would
  * redirect the outer host's own same-named slot, so `assign()` on such a
- * slot is inert instead (the same carve-out as every other elided-component
- * write).
+ * slot is inert instead (the same carve-out as every other write to a
+ * server-only component).
  */
 function hostOfSlot(slot) {
   for (let p = slot.parentElement; p; p = p.parentElement) {

package/src/slot.js

@@ -59,14 +59,10 @@
  * it); read assigned content from `slotchange` or after a microtask.
  *
  * Live writes need the component's JS on the page. Interception + sensors
- * install in connectedCallback, so a component the framework ELIDES (a
- * display-only slotted wrapper with no client signal) ships no JS and its
- * post-mount native writes are inert, like anything on an elided component.
- * A component that is actually interacted with ships (a client module
- * references its tag); for an imperative consumer reaching it through a
- * string selector the analyser cannot see, force the ship with
- * `static interactive = true`. Shadow components always ship (the DSD
- * carve-out), so this is the one place elision, not slots, sets the boundary.
+ * install in connectedCallback, so a server-only component (one in a
+ * `*.server.ts` file) ships no JS and its post-mount native writes are inert,
+ * like anything else on a server-only component. Every component in an
+ * ordinary file ships (#1686), so it always has them.
  *
  * Polyfill safety. Every prototype patch checks for the `data-webjs-light`
  * attribute and falls through to native otherwise, so real shadow-DOM slots

package/src/static-html.d.ts

@@ -0,0 +1,22 @@
+import type { TemplateResult } from './html.js';
+
+/** A value spliced into a template's strings (lit's `StaticValue`). */
+export interface StaticValue {
+  readonly _$webjsStatic: string;
+  readonly r: symbol;
+}
+
+/** lit's `unsafeStatic`: trusted text inserted as static markup. NEVER user input. */
+export function unsafeStatic(value: string): StaticValue;
+/** lit's `literal`: a static value whose interpolations must themselves be static. */
+export function literal(strings: TemplateStringsArray, ...values: unknown[]): StaticValue;
+/** lit's `withStatic`: wrap a template tag so it accepts static values. */
+export function withStatic<R>(
+  coreTag: (strings: TemplateStringsArray | string[], ...values: unknown[]) => R,
+): (strings: TemplateStringsArray | string[], ...values: unknown[]) => R;
+/** `html` that accepts `literal` / `unsafeStatic` values in any position. */
+export function html(strings: TemplateStringsArray | string[], ...values: unknown[]): TemplateResult;
+/** `svg` that accepts static values. */
+export function svg(strings: TemplateStringsArray | string[], ...values: unknown[]): TemplateResult;
+/** `mathml` that accepts static values. */
+export function mathml(strings: TemplateStringsArray | string[], ...values: unknown[]): TemplateResult;