@webjsdev/core 0.7.65 → 0.9.0

package/src/router-client/swap.js

@@ -7,12 +7,14 @@
  * @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';
 import { trackedReloadSignature } from './frames.js';
-import { addNewHeadElements, mergeHead } from './head-merge.js';
+import { addNewHeadElements, mergeHead, mergeHeadStylesheets } from './head-merge.js';
 import { morphLayoutChrome, planLayoutChrome } from './layout-chrome.js';
+import { primeLiveStylesheetKeys, releaseIncomingSheets, switchOffDepartedStylesheets } from './owned-styles.js';
 import { clearPrefetchRefused, prefetchClearAll } from './prefetch.js';
 import { snapshotCache } from './snapshot-cache.js';
 import { hardNavigate } from './state.js';
@@ -84,6 +86,13 @@ export let _swapCommit = Promise.resolve();
  *   history (a revalidation, a refresh, the popstate restore).
  */
 export function applySwap(doc, frameId, revalidating, href, incomingBuild, incomingSrc, refresh, recordHistoryNow) {
+  // The URL the incoming page came from, which its relative stylesheet hrefs
+  // resolve against, and the live sheets' keys taken NOW, while the document
+  // still has the outgoing page's URL: every commit point below records the
+  // new history entry before it merges the head (#1669).
+  let incomingBase = typeof location !== 'undefined' ? location.href : '';
+  if (href) { try { incomingBase = new URL(href, incomingBase).href; } catch { /* keep the live url */ } }
+  primeLiveStylesheetKeys();
   // SSR action seeding (#472): ingest the incoming page's seed payload BEFORE
   // its components are grafted into the live DOM and upgrade, so a
   // soft-navigated async component resolves from the seed instead of
@@ -105,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
@@ -115,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 {
@@ -279,7 +290,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
       // ADD-ONLY head merge: preserve runtime-generated head content
       // (Tailwind CSS injection, etc.) that the outer layout's scripts
       // already produced.
-      addNewHeadElements(doc.head);
+      addNewHeadElements(doc.head, { base: incomingBase, frame: true });
       // `diffChildren` -> `reconcileChildren` regrafts permanent elements
       // by node identity (it imports the incoming children first, then
       // swaps the live permanent node into the imported tree), so the live
@@ -288,6 +299,8 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
       // ALSO progressively streams a Suspense boundary gates its resolves on the
       // committed frame swap, not a stale prior _swapCommit (#1048).
       _swapCommit = runWithTransition(() => {
+        // The frame's incoming sheets loaded held; they apply with the swap.
+        releaseIncomingSheets();
         diffChildren(target, source);
         reactivateScripts(target);
         upgradeCustomElements(target);
@@ -334,7 +347,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
     // commit point without a reader having to prove reachability first, which
     // is what stops the next person adding a commit point from omitting it.
     if (recordHistoryNow) recordHistoryNow();
-    swapFullBody(doc);
+    swapFullBody(doc, incomingBase, true);
     return;
   }
 
@@ -361,7 +374,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
   if (plan && refresh === 'layouts' && !chrome) {
     ingestSeeds();
     if (recordHistoryNow) recordHistoryNow();
-    swapFullBody(doc);
+    swapFullBody(doc, incomingBase, true);
     return;
   }
 
@@ -375,11 +388,32 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
     if (recordHistoryNow) recordHistoryNow();
     const { mode, live, incoming } = plan;
     // ADD-ONLY head merge: the outer layout stays mounted, so its head-bound
-    // runtime state (Tailwind injection, etc.) must not be invalidated.
-    addNewHeadElements(doc.head);
+    // runtime state (Tailwind injection, etc.) must not be invalidated. It runs
+    // ahead of the commit, as the incoming sheets' load-before-swap copies
+    // already do (#1666, Turbo's order), so the new page's sheets apply from
+    // the swap's first frame.
+    // Its stylesheets wait for the commit (#1669, below).
+    addNewHeadElements(doc.head, { base: incomingBase, styles: false });
+    // A live element inside the range this swap replaces is on its way out,
+    // so a stylesheet link there does not count as one the page keeps.
+    /** @param {Element} el */
+    const leaving = (el) => !!(live.start.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING)
+      && !!(live.end.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_PRECEDING);
     _swapCommit = runWithTransition(() => {
+      // Everything stylesheet-related happens inside the commit, so the
+      // outgoing page, and a view transition's capture of it, keep exactly the
+      // sheets that page used, and the crossing restyles once (#1669): the
+      // incoming sheets (loaded held, stylesheets.js) are adopted, switched
+      // back on or inserted, then released, before the new markup lands.
+      mergeHeadStylesheets(doc.head, { base: incomingBase, segment: plan.segment, leaving });
+      releaseIncomingSheets();
       if (mode === 'replace') replaceBoundaryRange(live, incoming);
       else swapMarkerRange(live, incoming, doc);
+      // The swapped range's own stylesheets go with it unless the incoming
+      // page links them, in its head or its body, on a replace and on a morph
+      // alike: the server re-rendered the whole range either way, so a sheet a
+      // searchParams change dropped is retired too.
+      switchOffDepartedStylesheets(plan.segment, doc, incomingBase);
       // No key sync is needed on the anchor's own comments: the plan's anchor
       // carries EQUAL live/incoming route-keys in every tier (a changed-key
       // REPLACE anchors at a parent already compared equal; the other tiers
@@ -438,7 +472,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
   // because the user is already viewing the page).
   ingestSeeds();   // committed: past both discard branches above
   if (recordHistoryNow) recordHistoryNow();
-  swapFullBody(doc);
+  swapFullBody(doc, incomingBase, false);
 }
 
 /**
@@ -460,9 +494,12 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
  * it only past their own discard branches.
  *
  * @param {Document} doc
+ * @param {string} incomingBase  the URL the incoming page came from
+ * @param {boolean} complete  the response rendered every layout (no X-Webjs-Have), so it can retire a departed section's sheets
  */
-function swapFullBody(doc) {
-  mergeHead(doc.head);
+function swapFullBody(doc, incomingBase, complete) {
+  // Its stylesheets wait for the commit, as on a boundary swap (#1669).
+  mergeHead(doc.head, { base: incomingBase, styles: false });
   // Persist permanent elements by node identity across the full-body
   // swap: move each live [data-webjs-permanent][id] node into the matching
   // position in the incoming body BEFORE replaceChildren reads it, so the
@@ -470,7 +507,13 @@ function swapFullBody(doc) {
   regraftPermanentElements(document.body, doc.body);
   const newChildren = [...doc.body.childNodes];
   const doSwap = () => {
+    // The whole body is replaced, so every live body link is leaving.
+    mergeHeadStylesheets(doc.head, { base: incomingBase, segment: '/', leaving: () => true });
+    releaseIncomingSheets();
     document.body.replaceChildren(...newChildren);
+    // Only a response known to be complete can say a section's sheet is gone:
+    // the background restore path's head can be a reduced one (#936).
+    if (complete) switchOffDepartedStylesheets('/', doc, incomingBase);
     reactivateScripts(document.body);
     upgradeCustomElements(document.body);
     blurOutgoingFocus();

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/sentinels.d.ts

@@ -0,0 +1,2 @@
+export const nothing: unique symbol;
+export const noChange: unique symbol;

package/src/sentinels.js

@@ -0,0 +1,4 @@
+/** Clear a rendered value using Lit's position-specific rules. */
+export const nothing = Symbol.for('webjs.nothing');
+/** Keep the previously committed value. */
+export const noChange = Symbol.for('webjs.noChange');

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;