@nifrajs/web 5.5.0 → 5.6.0

package/src/internal/identity-epoch.ts

@@ -0,0 +1,235 @@
+/**
+ * The server half of the identity epoch: a response that signs a visitor in or out also rotates the
+ * readable epoch cookie, so every tab drops the pages it kept alive for the previous visitor.
+ *
+ * A header-only hook reads each response's `Set-Cookie`: when an identity cookie's value differs from
+ * the request's, or the cookie is deleted, the response also sets a fresh epoch with the same lifetime,
+ * so the epoch expires with an idle session. A rolling session re-sending the same value with a new
+ * lifetime re-sends the epoch it holds with that lifetime, so the two keep expiring together.
+ */
+import { type CookieOptions, parseCookies } from "@nifrajs/core/server"
+import { EPOCH_COOKIE, LOCAL_EPOCH_COOKIE } from "../identity.ts"
+
+/** `createWebApp`'s `keepAlive` option: which cookies say who is signed in. */
+export interface KeepAliveServerOptions {
+  /**
+   * Cookies whose change means a different visitor, on top of the session cookies of
+   * `@nifrajs/auth`, Better Auth and Auth.js under their default names. Name a custom session cookie
+   * here, or kept pages survive a sign-in or sign-out through it.
+   */
+  readonly identityCookies?: readonly string[]
+  /** `HttpOnly` cookies that say nothing about who is signed in; development stops asking about them. */
+  readonly ignoreCookies?: readonly string[]
+}
+
+/** The request and response a header hook sees. */
+interface HeaderView {
+  get(name: string): string | null
+  append(name: string, value: string): void
+}
+interface RequestView {
+  readonly url: string
+  header(name: string): string | null | undefined
+}
+
+// Session cookies by their default names, without a `__Secure-` / `__Host-` prefix.
+const IDENTITY_DEFAULTS = [
+  "nifra_session",
+  "better-auth.session_token",
+  "authjs.session-token",
+  "next-auth.session-token",
+]
+// `HttpOnly` cookies the same integrations write that carry no identity of their own.
+const IGNORE_DEFAULTS = [
+  "better-auth.session_data",
+  "better-auth.dont_remember",
+  "authjs.csrf-token",
+  "authjs.callback-url",
+  "authjs.pkce.code_verifier",
+  "authjs.state",
+  "authjs.nonce",
+  "next-auth.csrf-token",
+  "next-auth.callback-url",
+  "next-auth.pkce.code_verifier",
+  "next-auth.state",
+  "next-auth.nonce",
+  "__nifra_draft",
+]
+
+// `__Secure-a.0` and `__Host-a` are the cookie `a`: a prefix, then Auth.js's chunk index.
+const baseName = (name: string): string =>
+  name.replace(/^__(?:secure|host)-/i, "").replace(/\.\d+$/, "")
+
+interface SetCookie {
+  readonly name: string
+  readonly value: string
+  readonly deleted: boolean
+  readonly httpOnly: boolean
+  readonly secure: boolean
+  readonly maxAge: string | undefined
+  readonly expires: string | undefined
+}
+
+// Splits a `Set-Cookie` list joined with ", ": only a comma followed by `name=` starts a cookie, so
+// the comma inside an `Expires` date stays where it is.
+const SPLIT = /,\s*(?=[!#$%&'*+\-.^_`|~0-9A-Za-z]+=)/
+
+const parseSetCookies = (joined: string, now: number): SetCookie[] => {
+  const cookies: SetCookie[] = []
+  for (const line of joined.split(SPLIT)) {
+    const [pair = "", ...attributes] = line.split(";")
+    const at = pair.indexOf("=")
+    if (at <= 0) continue
+    let maxAge: string | undefined
+    let expires: string | undefined
+    let httpOnly = false
+    let secure = false
+    for (const attribute of attributes) {
+      const eq = attribute.indexOf("=")
+      const key = (eq === -1 ? attribute : attribute.slice(0, eq)).trim().toLowerCase()
+      const value = eq === -1 ? "" : attribute.slice(eq + 1).trim()
+      if (key === "max-age") maxAge = value
+      else if (key === "expires") expires = value
+      else if (key === "httponly") httpOnly = true
+      else if (key === "secure") secure = true
+    }
+    const name = pair.slice(0, at).trim()
+    const age = maxAge === undefined ? Number.NaN : Number(maxAge)
+    const until = expires === undefined ? Number.NaN : Date.parse(expires)
+    cookies.push({
+      name,
+      // Decoded as core decodes the request's cookies, so an encoded value compares equal to itself.
+      value: parseCookies(pair.trim())[name] ?? "",
+      deleted: age <= 0 || until <= now,
+      httpOnly,
+      secure: secure || /^__(?:secure|host)-/i.test(name),
+      maxAge,
+      expires,
+    })
+  }
+  return cookies
+}
+
+const randomEpoch = (): string => {
+  const bytes = crypto.getRandomValues(new Uint8Array(16))
+  let hex = ""
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, "0")
+  return hex
+}
+
+const EPOCH_VALUE = /^[0-9a-f]{32}$/
+
+// A forwarded protocol only picks the cookie's name: a client that lies about it loses its own epoch.
+// A browser sends a `__Host-` cookie only over https, so carrying one says so behind a TLS proxy that
+// forwards nothing, and the client, which reads that one first, must see the new value there.
+const servedOverHttps = (request: RequestView, sent: Readonly<Record<string, string>>): boolean => {
+  if (request.url.startsWith("https:") || sent[EPOCH_COOKIE] !== undefined) return true
+  const forwarded = request.header("x-forwarded-proto")
+  return forwarded?.split(",")[0]?.trim().toLowerCase() === "https"
+}
+
+const epochCookie = (
+  secure: boolean,
+  value: string,
+  lifetime: { readonly maxAge?: string | undefined; readonly expires?: string | undefined },
+): string => {
+  let cookie = `${secure ? EPOCH_COOKIE : LOCAL_EPOCH_COOKIE}=${value}; Path=/; SameSite=Lax`
+  if (secure) cookie += "; Secure"
+  if (lifetime.maxAge !== undefined) cookie += `; Max-Age=${lifetime.maxAge}`
+  if (lifetime.expires !== undefined) cookie += `; Expires=${lifetime.expires}`
+  return cookie
+}
+
+/**
+ * The response hook `createWebApp` installs for an app with a `keepAlive` route. With `development`,
+ * it also says once per cookie when an `HttpOnly` cookie it does not know changes.
+ */
+export function identityEpochHook(
+  options: KeepAliveServerOptions,
+  development: boolean,
+): (headers: HeaderView, request: RequestView) => void {
+  const identity = new Set([...IDENTITY_DEFAULTS, ...(options.identityCookies ?? []).map(baseName)])
+  const ignored = new Set([...IGNORE_DEFAULTS, ...(options.ignoreCookies ?? []).map(baseName)])
+  const reported = new Set<string>()
+  return (headers, request) => {
+    const joined = headers.get("set-cookie")
+    if (joined === null || joined === "") return
+    const sent = parseCookies(request.header("cookie") ?? null)
+    let changed: SetCookie | undefined
+    let renewed: SetCookie | undefined
+    for (const cookie of parseSetCookies(joined, Date.now())) {
+      if (cookie.name === EPOCH_COOKIE || cookie.name === LOCAL_EPOCH_COOKIE) return
+      const now = cookie.deleted ? "" : cookie.value
+      const base = baseName(cookie.name)
+      if (now === (sent[cookie.name] ?? "")) {
+        if (
+          renewed === undefined &&
+          !cookie.deleted &&
+          (cookie.maxAge !== undefined || cookie.expires !== undefined) &&
+          identity.has(base)
+        )
+          renewed = cookie
+        continue
+      }
+      if (identity.has(base)) {
+        // The first identity cookie still set gives the lifetime; a sign-out deletes them all.
+        if (changed === undefined || (changed.deleted && !cookie.deleted)) changed = cookie
+        continue
+      }
+      if (!development || !cookie.httpOnly || ignored.has(base) || reported.has(base)) continue
+      reported.add(base)
+      console.warn(
+        `[nifra/web] NIFRA_KEEPALIVE_IDENTITY_COOKIE: this app keeps pages alive, and a response changed the HttpOnly cookie "${cookie.name}", which nifra does not know as a sign-in cookie. If it says who is signed in, add it to createWebApp({ keepAlive: { identityCookies: ["${base}"] } }) so a sign-in or sign-out drops the pages kept for the previous visitor; if it does not, add it to keepAlive.ignoreCookies.`,
+      )
+    }
+    if (changed !== undefined) {
+      headers.append(
+        "set-cookie",
+        epochCookie(
+          changed.secure || servedOverHttps(request, sent),
+          randomEpoch(),
+          changed.deleted ? {} : { maxAge: changed.maxAge, expires: changed.expires },
+        ),
+      )
+      return
+    }
+    if (renewed === undefined) return
+    const lifetime = { maxAge: renewed.maxAge, expires: renewed.expires }
+    for (const secure of [true, false]) {
+      const held = sent[secure ? EPOCH_COOKIE : LOCAL_EPOCH_COOKIE]
+      if (held === undefined || !EPOCH_VALUE.test(held)) continue
+      headers.append("set-cookie", epochCookie(secure, held, lifetime))
+      return
+    }
+    // An epoch that already expired, or was never set: a fresh one, so pages kept without one drop.
+    headers.append(
+      "set-cookie",
+      epochCookie(renewed.secure || servedOverHttps(request, sent), randomEpoch(), lifetime),
+    )
+  }
+}
+
+/** The response-cookie surface {@link rotateIdentityEpoch} needs: nifra's handler context. */
+export interface IdentityEpochContext {
+  readonly request: Request
+  readonly set: { cookie(name: string, value: string, options?: CookieOptions): void }
+}
+
+/**
+ * Rotate the identity epoch from a flow that changes who is signed in without changing a cookie
+ * `createWebApp` watches - say, a session kept server-side under a cookie whose value stays the
+ * same. Every tab then drops the pages it kept alive for the previous visitor.
+ */
+export function rotateIdentityEpoch(c: IdentityEpochContext): void {
+  const request = c.request
+  const secure = servedOverHttps(
+    { url: request.url, header: (name) => request.headers.get(name) },
+    parseCookies(request.headers.get("cookie")),
+  )
+  c.set.cookie(secure ? EPOCH_COOKIE : LOCAL_EPOCH_COOKIE, randomEpoch(), {
+    path: "/",
+    sameSite: "lax",
+    secure,
+    httpOnly: false,
+  })
+}

package/src/internal/invalidation-contract.ts

@@ -0,0 +1,35 @@
+/**
+ * The seam between `createWebApp` and a cache wrapper for an action's invalidation: types and one
+ * symbol, so an app pays for the pipeline only once something runs it.
+ */
+import type { RevalidateResult } from "./render-document.ts"
+
+export interface InvalidationOp {
+  /** Names the operation in logs; never key text. */
+  readonly id: string
+  readonly paths: readonly string[]
+  readonly tags: readonly string[]
+  readonly keys: readonly string[]
+}
+
+/** What a `createWebApp` app hands a cache wrapper that owns its invalidation. */
+export interface InvalidationHandoff {
+  /** The operation the action behind `request` recorded, once. */
+  take(request: Request): InvalidationOp | undefined
+  /** The app's live publish, when it configures `live`. */
+  readonly publish: ((keys: readonly string[]) => Promise<void>) | undefined
+}
+
+export const INVALIDATION: unique symbol = Symbol.for("nifra.web.invalidation")
+
+/** The operation an action's `revalidate()` names: its paths, cache tags and live keys. */
+export function invalidationOf(revalidation: RevalidateResult<unknown>): InvalidationOp {
+  return {
+    id: crypto.randomUUID(),
+    paths: revalidation.__nifraRevalidate.filter(
+      (path) => typeof path === "string" && path.startsWith("/"),
+    ),
+    tags: revalidation.__nifraInvalidate?.tags ?? [],
+    keys: revalidation.__nifraInvalidate?.keys ?? [],
+  }
+}

package/src/internal/invalidation.ts

@@ -0,0 +1,213 @@
+/**
+ * One invalidation pipeline for everything a write makes stale, in a fixed order: data caches (tags),
+ * then the page store (paths and tags), then the live publish (keys and tags), then the CDN. A failure
+ * in either cache stage stops before the publish: clients told to reload would read the stale data and
+ * move their watermarks past the change. Every stage is idempotent, so a retry repeats from the stage
+ * that failed.
+ *
+ * `withISR` owns the pipeline when it wraps the app; without it, `createWebApp` runs the publish
+ * stage alone. Never both.
+ */
+import type { CacheStore, CdnPurgeTarget, ISRPlatform } from "../isr.ts"
+import type { InvalidationOp } from "./invalidation-contract.ts"
+
+export type { InvalidationOp } from "./invalidation-contract.ts"
+
+export type InvalidationStage = "data" | "pages" | "publish" | "cdn"
+
+export interface StageReport {
+  readonly stage: InvalidationStage
+  readonly ok: boolean
+  readonly retryable: boolean
+  readonly error?: string
+  /** The CDN took the purge but has not applied it yet (rate limit or retry). */
+  readonly queued?: true
+}
+
+export interface InvalidationReport {
+  readonly id: string
+  readonly ok: boolean
+  readonly stages: readonly StageReport[]
+}
+
+/** What the pipeline calls on a page store: any {@link CacheStore} fits. */
+export interface PagePurge {
+  delete(key: string): Promise<void>
+  readonly invalidateTag?: ((tag: string) => Promise<void>) | undefined
+}
+
+export interface InvalidationTargets {
+  readonly dataCaches?: readonly { invalidateTag(tag: string): unknown }[] | undefined
+  readonly store?: PagePurge | undefined
+  /** The page store key of a path, as the cache wrapper computes it; `null` when never stored. */
+  readonly keyOf?: ((path: string, req: Request) => string | null) | undefined
+  readonly publish?: ((keys: readonly string[]) => Promise<void>) | undefined
+  readonly cdn?: CdnPurgeTarget | undefined
+}
+
+const ORDER: readonly InvalidationStage[] = ["data", "pages", "publish", "cdn"]
+/** Retry delays after a retryable failure; inline retries stop at {@link INLINE_DEADLINE_MS}. */
+const RETRY_MS = [200, 600, 1800]
+export const INLINE_DEADLINE_MS = 2000
+
+/** Run the stages from `from` once. */
+export async function runInvalidation(
+  op: InvalidationOp,
+  targets: InvalidationTargets,
+  req: Request,
+  platform: ISRPlatform | undefined,
+  from: InvalidationStage = "data",
+): Promise<InvalidationReport> {
+  const stages: StageReport[] = []
+  for (const stage of ORDER.slice(ORDER.indexOf(from))) {
+    // Decided before any await: a stage with nothing to do costs no turn of the event loop.
+    const running = startStage(stage, op, targets, req, platform)
+    if (running === undefined) continue
+    const report = await running
+    stages.push(report)
+    // A cache stage that failed leaves data a reload would read: nothing after it may run.
+    if (!report.ok && (stage === "data" || stage === "pages")) break
+  }
+  return { id: op.id, ok: stages.every((report) => report.ok), stages }
+}
+
+/** Start a stage's work for this operation; `undefined` when it has none. Never rejects. */
+function startStage(
+  stage: InvalidationStage,
+  op: InvalidationOp,
+  targets: InvalidationTargets,
+  req: Request,
+  platform: ISRPlatform | undefined,
+): Promise<StageReport> | undefined {
+  const done: StageReport = { stage, ok: true, retryable: false }
+  let work: Promise<StageReport>
+  switch (stage) {
+    case "data": {
+      const caches = targets.dataCaches
+      if (op.tags.length === 0 || caches === undefined) return undefined
+      work = (async () => {
+        for (const cache of caches) {
+          for (const tag of op.tags) await cache.invalidateTag(tag)
+        }
+        return done
+      })()
+      break
+    }
+    case "pages": {
+      const store = targets.store
+      if (store === undefined || op.paths.length + op.tags.length === 0) return undefined
+      work = (async (): Promise<StageReport> => {
+        if (op.tags.length > 0 && store.invalidateTag === undefined) {
+          return { stage, ok: false, retryable: false, error: "tag_invalidation_not_supported" }
+        }
+        for (const path of op.paths) {
+          const key = targets.keyOf?.(path, req) ?? null
+          if (key !== null) await store.delete(key)
+        }
+        for (const tag of op.tags) await store.invalidateTag?.(tag)
+        return done
+      })()
+      break
+    }
+    case "publish": {
+      const publish = targets.publish
+      if (publish === undefined || op.keys.length + op.tags.length === 0) return undefined
+      work = (async () => {
+        await publish([...new Set([...op.keys, ...op.tags])])
+        return done
+      })()
+      break
+    }
+    case "cdn": {
+      const cdn = targets.cdn
+      if (cdn === undefined || op.paths.length + op.tags.length === 0) return undefined
+      work = (async (): Promise<StageReport> => {
+        const outcome = await cdn.purge({ tags: op.tags, paths: op.paths }, platform)
+        return outcome.cdn === "failed"
+          ? {
+              stage,
+              ok: false,
+              retryable: outcome.retryable,
+              error: outcome.error ?? "cdn_purge_failed",
+            }
+          : outcome.cdn === "queued"
+            ? { stage, ok: true, retryable: false, queued: true }
+            : done
+      })()
+      break
+    }
+  }
+  return work.catch(() => ({ stage, ok: false, retryable: true, error: `${stage}_failed` }))
+}
+
+export interface SettleOptions {
+  readonly onError?: ((report: InvalidationReport) => void) | undefined
+  /** Tests drive time; production waits on timers. */
+  readonly clock?: { now(): number; sleep(ms: number): Promise<void> }
+}
+
+const realClock = {
+  now: () => Date.now(),
+  sleep: (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
+}
+
+/**
+ * Run the pipeline for a write; never throws and never changes the response. A retryable failure
+ * retries from the failed stage, under `waitUntil` when the platform has it, else inline until
+ * {@link INLINE_DEADLINE_MS}. A failure that remains is reported once.
+ */
+export async function settleInvalidation(
+  op: InvalidationOp,
+  targets: InvalidationTargets,
+  req: Request,
+  platform: ISRPlatform | undefined,
+  options: SettleOptions = {},
+): Promise<InvalidationReport> {
+  const onError = options.onError ?? logInvalidation
+  const clock = options.clock ?? realClock
+  const started = clock.now()
+  const first = await runInvalidation(op, targets, req, platform)
+  if (first.ok) return first
+  const failed = first.stages.find((report) => !report.ok)
+  if (failed === undefined || !failed.retryable) {
+    report(onError, first)
+    return first
+  }
+  const background = typeof platform?.waitUntil === "function"
+  const retry = async (): Promise<InvalidationReport> => {
+    let last = first
+    let stage = failed.stage
+    for (const delay of RETRY_MS) {
+      if (!background && clock.now() - started + delay >= INLINE_DEADLINE_MS) break
+      await clock.sleep(delay)
+      last = await runInvalidation(op, targets, req, platform, stage)
+      const next = last.stages.find((report) => !report.ok)
+      if (next === undefined) return last
+      if (!next.retryable) break
+      stage = next.stage
+    }
+    report(onError, last)
+    return last
+  }
+  if (background) {
+    platform?.waitUntil?.(retry())
+    return first
+  }
+  return retry()
+}
+
+function report(onError: (report: InvalidationReport) => void, value: InvalidationReport): void {
+  try {
+    onError(value)
+  } catch {
+    // A failing reporter must not reach the response.
+  }
+}
+
+/** The default report: the operation id and the stage, never a path, tag or key. */
+export function logInvalidation(report: InvalidationReport): void {
+  const failed = report.stages.find((stage) => !stage.ok)
+  console.error(
+    `[nifra/web] invalidation ${report.id} gave up at the ${failed?.stage ?? "unknown"} stage (${failed?.error ?? "failed"})`,
+  )
+}

package/src/internal/island-bindings.ts

@@ -0,0 +1,191 @@
+/**
+ * The declarative binding walker - attaches signal-driven behavior to SERVER-RENDERED markup.
+ * No VDOM, no hydration re-render: the HTML the server sent (e.g. via `@nifrajs/web-vanilla`) is
+ * already the initial state; bindings update it surgically when signals change. `bindIsland` runs it.
+ *
+ * The attribute set is CLOSED and documented - six bindings, no expression language. Values are
+ * signal/handler NAMES looked up in the island's scope, never evaluated code, so markup can't
+ * inject behavior:
+ *
+ *   data-bind-text="count"                  textContent ← String(signal())
+ *   data-bind-show="isOpen"                 hidden ← !signal()
+ *   data-bind-class="active:isOpen,b:sigB"  classList.toggle per pair
+ *   data-bind-attr="aria-expanded:isOpen"   setAttribute / removeAttribute (false/null remove);
+ *                                           never an `on*` handler or `srcdoc`, and a URL attribute
+ *                                           takes only an http(s)/mailto/tel or relative URL
+ *   data-bind-value="query"                 two-way <input>/<select>/<textarea> (input and change)
+ *   data-bind-on="click:inc,submit:save"    addEventListener per pair
+ *
+ * Nothing inside a `data-island-ignore` element binds or mounts: render user HTML there, so its
+ * markup cannot reach the island's handlers or signals.
+ *
+ * A binding belongs to its nearest island: an island never binds inside a nested island's host. The
+ * nested host element itself is still the outer island's markup, so the outer island may bind it.
+ */
+
+import { type Signal, watch } from "./island-signals.ts"
+
+export type IslandScope = {
+  readonly signals: Readonly<Record<string, Signal<unknown>>>
+  readonly handlers: Readonly<Record<string, (event: Event) => void>>
+}
+
+const warned = new Set<string>()
+/** Unknown names warn once (loud in dev, resilient in prod - progressive enhancement must not
+ * throw over a typo'd attribute) and the binding is skipped. */
+function warnOnce(kind: string, name: string): void {
+  const key = `${kind}:${name}`
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(`[nifra/islands] unknown ${kind} ${JSON.stringify(name)} - binding skipped`)
+}
+
+// Own keys only: a name such as `constructor` must not resolve to what a plain object inherits.
+function named<V>(kind: string, record: Readonly<Record<string, V>>, name: string): V | undefined {
+  if (Object.hasOwn(record, name)) return record[name]
+  warnOnce(kind, name)
+  return undefined
+}
+
+/** Parse a `"key:name,key2:name2"` pair list (whitespace-tolerant). Malformed entries skip. */
+function pairs(spec: string): Array<[string, string]> {
+  const out: Array<[string, string]> = []
+  for (const part of spec.split(",")) {
+    const sep = part.indexOf(":")
+    if (sep <= 0) continue
+    const key = part.slice(0, sep).trim()
+    const name = part.slice(sep + 1).trim()
+    if (key && name) out.push([key, name])
+  }
+  return out
+}
+
+// A bound value is data (often from island state the markup carries), so an attribute that would run
+// it as code, or navigate to it as a script URL, is refused.
+const CODE_ATTRIBUTE = /^(?:on|srcdoc$)/i
+const URL_ATTRIBUTE =
+  /^(?:href|src|action|formaction|xlink:href|poster|data|background|cite|ping)$/i
+const SAFE_URL = /^(?:(?:https?|mailto|tel):|[^:/?#]*(?:[/?#]|$))/i
+
+/** The element surface the walker needs - structural, so tests can drive it without a real DOM. */
+export interface BindableElement {
+  getAttribute(name: string): string | null
+  setAttribute(name: string, value: string): void
+  removeAttribute(name: string): void
+  textContent: string | null
+  hidden: boolean
+  value?: string
+  readonly classList: { toggle(name: string, force?: boolean): unknown }
+  addEventListener(type: string, listener: (event: Event) => void): void
+  removeEventListener(type: string, listener: (event: Event) => void): void
+}
+
+export interface BindableRoot {
+  querySelectorAll(selector: string): Iterable<BindableElement>
+}
+
+/** Walk `root` and attach every `data-bind-*` binding against `scope`. Each binding's disposer
+ * (reactive effect or event listener) goes onto `stops` as it attaches, so a binding that throws
+ * midway leaves the earlier ones disposable; `stops` is returned. */
+export function bindScope(
+  root: BindableRoot,
+  scope: IslandScope,
+  stops: Array<() => void> = [],
+): Array<() => void> {
+  // Each element carrying `data-bind-<kind>` outside any ignored subtree and any nested island, with
+  // that attribute's value.
+  const each = (kind: string): Array<[BindableElement, string]> => {
+    const attribute = `data-bind-${kind}`
+    return [
+      ...root.querySelectorAll(
+        `[${attribute}]:not([data-island-ignore],[data-island-ignore] *,:scope [data-island] *)`,
+      ),
+    ].map((el) => [el, el.getAttribute(attribute) ?? ""])
+  }
+
+  for (const [el, name] of each("text")) {
+    const s = named("signal", scope.signals, name)
+    if (s) {
+      stops.push(
+        watch(s, (v) => {
+          el.textContent = String(v)
+        }),
+      )
+    }
+  }
+
+  for (const [el, name] of each("show")) {
+    const s = named("signal", scope.signals, name)
+    if (s) {
+      stops.push(
+        watch(s, (v) => {
+          el.hidden = !v
+        }),
+      )
+    }
+  }
+
+  for (const [el, spec] of each("class")) {
+    for (const [className, name] of pairs(spec)) {
+      const s = named("signal", scope.signals, name)
+      if (s) {
+        stops.push(
+          watch(s, (v) => {
+            el.classList.toggle(className, !!v)
+          }),
+        )
+      }
+    }
+  }
+
+  for (const [el, spec] of each("attr")) {
+    for (const [attr, name] of pairs(spec)) {
+      if (CODE_ATTRIBUTE.test(attr)) {
+        warnOnce("attribute", attr)
+        continue
+      }
+      const s = named("signal", scope.signals, name)
+      if (s) {
+        const isUrl = URL_ATTRIBUTE.test(attr)
+        stops.push(
+          watch(s, (v) => {
+            if (v === false || v == null || (isUrl && !SAFE_URL.test(String(v).trim())))
+              el.removeAttribute(attr)
+            else el.setAttribute(attr, String(v))
+          }),
+        )
+      }
+    }
+  }
+
+  for (const [el, name] of each("value")) {
+    const s = named("signal", scope.signals, name)
+    if (s) {
+      stops.push(
+        watch(s, (v) => {
+          const next = String(v)
+          // Skip same-value writes: resetting an input's value mid-typing moves the caret.
+          if (el.value !== next) el.value = next
+        }),
+      )
+      const input = (): void => s.set(el.value ?? "")
+      // A <select> commits on `change`, and browsers disagree on whether `input` comes first. The
+      // second event of a pair writes the same value, which the signal skips.
+      for (const type of ["input", "change"]) {
+        el.addEventListener(type, input)
+        stops.push(() => el.removeEventListener(type, input))
+      }
+    }
+  }
+
+  for (const [el, spec] of each("on")) {
+    for (const [event, name] of pairs(spec)) {
+      const handler = named("handler", scope.handlers, name)
+      if (handler === undefined) continue
+      el.addEventListener(event, handler)
+      stops.push(() => el.removeEventListener(event, handler))
+    }
+  }
+
+  return stops
+}