@barefootjs/client 0.13.0 → 0.15.0

package/src/reactive.ts

@@ -5,6 +5,8 @@
  * Inspired by SolidJS signals.
  */
 
+import { BF_SEAM_PUSH_SEARCH } from '@barefootjs/shared'
+
 /**
  * Phantom brand for compile-time reactivity detection.
  * The compiler checks for the '__reactive' property via TypeChecker
@@ -597,3 +599,131 @@ export function createMemo<T>(fn: () => T, __bfId?: string): Memo<T> {
   return value
 }
 
+
+// ---------------------------------------------------------------------------
+// Request-scoped environment signals (router v0.5, spec/router.md "The wedge")
+// ---------------------------------------------------------------------------
+//
+// An environment signal is ambient request/browser state — the query string,
+// later cookies — that is correct per-request under SSR (read from the adapter's
+// per-request context, never a process-wide module global, which would race) and
+// reactive on the client (a query-only navigation updates it with no swap and no
+// re-hydration; islands reconcile fine-grained). It rides the `Reactive<>` brand,
+// so the compiler's reactivity analysis wires DOM updates with no new feature.
+//
+// These live HERE, in the single physical `@barefootjs/client/reactive` module,
+// for the same reason the signal primitives do: both `@barefootjs/client` and
+// the `/runtime` entry re-export them from this one module, so a page has ONE
+// `searchParams` signal instance regardless of which entry an island imports
+// from. A relative copy bundled into each entry would create two disconnected
+// signals — the #1910 failure (the router would push into one while an island
+// reads the other).
+//
+// No import-time side effect: the underlying signal is created lazily on first
+// read and the router push seam is installed there (not at module top-level), so
+// reading is the only thing that materialises anything.
+
+/**
+ * SSR reader for request-scoped environment signals, keyed by env id
+ * (`'search'` today; `'cookie'` etc. later). Injected by an adapter / host so
+ * each value resolves per-request inside the host's async context — no shared
+ * mutable server state. ONE keyed reader serves every env signal, so a new
+ * signal needs no new seam or setter.
+ */
+let serverEnvReader: ((key: string) => string | undefined) | null = null
+
+/**
+ * Adapter/host hook: teach `@barefootjs/client` how to read the current
+ * request's environment values during SSR. The reader receives an env key
+ * (`'search'`, …) and returns the raw value, or `undefined` to defer (to the
+ * `globalThis` seam, else the empty default). Call once with a reader that
+ * resolves per-request.
+ */
+export function __bfSetServerEnvReader(
+  reader: ((key: string) => string | undefined) | null,
+): void {
+  serverEnvReader = reader
+}
+
+/**
+ * Resolve a request-scoped env value during SSR: the reader set via
+ * {@link __bfSetServerEnvReader}, else a `globalThis.__bf_serverEnvReader` seam
+ * — so a host can wire request-scoped SSR *without* importing
+ * `@barefootjs/client` (the server-side analogue of the `window.__bf_*` client
+ * seams). `undefined` when no reader resolves the key.
+ */
+function resolveServerEnv(key: string): string | undefined {
+  if (serverEnvReader) {
+    const v = serverEnvReader(key)
+    if (v !== undefined) return v
+  }
+  const seam = (
+    globalThis as unknown as { __bf_serverEnvReader?: (key: string) => string | undefined }
+  ).__bf_serverEnvReader
+  return typeof seam === 'function' ? seam(key) : undefined
+}
+
+/**
+ * Build a request-scoped reactive environment signal, keyed by `key` — the env
+ * id the SSR reader resolves (`'search'`, …). Internal: only concrete instances
+ * (`searchParams`, …) are exported.
+ */
+function createEnvSignal<T>(
+  key: string,
+  readClient: () => string,
+  parse: (raw: string) => T,
+  pushSeam: string,
+): Reactive<() => T> {
+  let getRaw: (() => string) | null = null
+
+  function ensureClientSignal(): string {
+    if (!getRaw) {
+      const [get, set] = createSignal(readClient())
+      getRaw = get
+      // Install the router push seam inside the lazily-invoked accessor (not at
+      // module top-level), so reading is the only thing with an effect.
+      const w = window as unknown as Record<string, (next: string) => void>
+      // `set` already bails on `Object.is` equality, so no equality guard is
+      // needed — and a `get()` here would register a spurious dependency if a
+      // caller ever pushed from inside an effect.
+      w[pushSeam] = (next: string) => {
+        set(next)
+      }
+    }
+    return getRaw()
+  }
+
+  return (() => {
+    if (typeof window === 'undefined') {
+      // SSR: resolve per-call inside the host's request context. Never cache a
+      // module-level signal — it would be a process-wide global that races.
+      return parse(resolveServerEnv(key) ?? '')
+    }
+    return parse(ensureClientSignal())
+  }) as Reactive<() => T>
+}
+
+/**
+ * Reactive read of the current query string as `URLSearchParams`.
+ *
+ * ```tsx
+ * const sort = createMemo(() => searchParams().get('sort') ?? 'recent')
+ * ```
+ *
+ * A same-route, query-only navigation (`/list?sort=price`) driven by
+ * `@barefootjs/router` updates this signal and the URL **without a swap or
+ * re-hydration**. On the server it reflects the current request's query.
+ *
+ * Reactivity is **router-driven**: the signal is seeded once on first read and
+ * thereafter updated only through the `window.__bf_pushSearch` seam, which
+ * `startRouter()` drives (including on `popstate`). Without the router running
+ * — or after a non-router `history` change — the value is read-once; the seam
+ * name is shared with `@barefootjs/router` via `BF_SEAM_PUSH_SEARCH`, so the
+ * installer (here) and the pusher agree by construction.
+ */
+export const searchParams = createEnvSignal(
+  'search',
+  () => window.location.search,
+  (raw) => new URLSearchParams(raw),
+  BF_SEAM_PUSH_SEARCH,
+)

package/src/runtime/hydrate.ts

@@ -43,6 +43,7 @@ import { hydratedScopes } from './hydration-state.ts'
 import { registerComponent } from './registry.ts'
 import { registerTemplate } from './template.ts'
 import { BF_SCOPE, BF_PROPS, BF_HOST, BF_SCOPE_COMMENT_PREFIX } from '@barefootjs/shared'
+import { createRoot } from '@barefootjs/client/reactive'
 import type { ComponentDef } from './types.ts'
 
 /**
@@ -185,6 +186,98 @@ export function flushHydration(): void {
   walkAllInDocumentOrder()
 }
 
+/**
+ * Re-hydrate only the scopes inside `root` (and `root` itself), in
+ * document order. Unlike `rehydrateAll()` — which schedules a walk over
+ * the *whole document* — this is a synchronous, subtree-scoped walk: its
+ * cost is O(scopes in `root`), not O(document).
+ *
+ * Intended for a client router that has just swapped a content region:
+ * the component registry is already populated from the initial load, so
+ * no deferral is needed; only the freshly inserted islands need to init.
+ */
+export function rehydrateScope(root: Element): void {
+  if (typeof document === 'undefined') return
+  // The TreeWalker visits descendants only, so handle the root itself first.
+  hydrateElementScope(root)
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_COMMENT)
+  while (walker.nextNode()) {
+    const node = walker.currentNode
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      hydrateElementScope(node as Element)
+    } else if (node.nodeType === Node.COMMENT_NODE) {
+      hydrateCommentScope(node as Comment)
+    }
+  }
+}
+
+/**
+ * Dispose every hydrated scope inside `root` (and `root` itself): runs
+ * each scope's `createRoot` dispose fn, tearing down its effects, memos,
+ * and `onCleanup` callbacks. Used by a client router before it removes a
+ * content region, so the outgoing islands release timers/listeners/
+ * subscriptions instead of leaking.
+ *
+ * Also resets the per-scope hydration marks so the *same* DOM nodes could
+ * be re-hydrated if they are ever re-inserted:
+ *   - element scopes: their `hydratedScopes` entry (via `disposeOneScope`),
+ *   - `bf-h` child scopes: their `hydratedScopes` entry (they have no own
+ *     disposer — their reactive graph is owned by an ancestor root being
+ *     disposed here),
+ *   - comment scopes: the `__bfInitialized` flag on the `<!--bf-scope:-->`
+ *     anchor (otherwise `hydrateCommentScope` short-circuits on the stale
+ *     flag and never re-initializes the scope).
+ */
+export function disposeScope(root: Element): void {
+  if (typeof document === 'undefined') return
+  disposeOneScope(root)
+  clearChildScopeMark(root)
+  const walker = document.createTreeWalker(
+    root,
+    NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_COMMENT,
+  )
+  while (walker.nextNode()) {
+    const node = walker.currentNode
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      disposeOneScope(node as Element)
+      clearChildScopeMark(node as Element)
+    } else if (node.nodeType === Node.COMMENT_NODE) {
+      clearCommentScopeFlag(node as Comment)
+    }
+  }
+}
+
+function disposeOneScope(el: Element): void {
+  const dispose = scopeDisposers.get(el)
+  if (dispose) {
+    scopeDisposers.delete(el)
+    hydratedScopes.delete(el)
+    dispose()
+  }
+}
+
+/**
+ * `bf-h` child scopes are initialized via `initChild` (not the walker), so
+ * they carry a `hydratedScopes` mark but no own disposer — their effects
+ * belong to an ancestor root that `disposeScope` is tearing down. Clear the
+ * mark so the same node can re-init if re-inserted.
+ */
+function clearChildScopeMark(el: Element): void {
+  if (el.hasAttribute(BF_HOST)) hydratedScopes.delete(el)
+}
+
+/**
+ * Comment-rooted scopes flag their init on the `<!--bf-scope:-->` comment
+ * node (`__bfInitialized`); the proxy element's `hydratedScopes` entry and
+ * disposer are cleared by `disposeOneScope`, but the comment flag must be
+ * reset here or re-hydration short-circuits.
+ */
+function clearCommentScopeFlag(comment: Comment): void {
+  if (!comment.nodeValue?.startsWith(BF_SCOPE_COMMENT_PREFIX)) return
+  const flagged = comment as unknown as { __bfInitialized?: boolean }
+  if (flagged.__bfInitialized) flagged.__bfInitialized = false
+}
+
 /**
  * Single document-order walk visiting element scopes (`[bf-s]`) and
  * comment scopes (`<!--bf-scope:Name_xxx-->`) interleaved by their
@@ -232,10 +325,29 @@ function parseProps(json: string | null, where: string): Record<string, unknown>
   }
 }
 
+/**
+ * Per-scope disposal registry. Each scope's `init` runs inside a
+ * `createRoot`, so all the effects/memos it (and its `initChild`-mounted
+ * descendants) create are owned by one root. `disposeScope(root)` calls
+ * the stored dispose fn to tear them down — enabling a client router to
+ * release the islands leaving the page precisely, instead of leaking
+ * timers/listeners or relying on GC (see `disposeScope`).
+ *
+ * Keyed by the scope element; a `WeakMap` so detached scopes are
+ * reclaimed even if `disposeScope` is never called.
+ */
+const scopeDisposers = new WeakMap<Element, () => void>()
+
 function runInit(scope: Element, def: ComponentDef, props: Record<string, unknown>): void {
   const prevScope = setCurrentScope(scope)
   try {
-    def.init(scope, props)
+    // Wrap in createRoot so the scope's reactive graph has an owner that
+    // can be disposed later. This is additive: nothing disposes the root
+    // unless `disposeScope` is called, so existing lifetimes are unchanged.
+    createRoot((dispose) => {
+      scopeDisposers.set(scope, dispose)
+      def.init(scope, props)
+    })
   } finally {
     setCurrentScope(prevScope)
   }

package/src/runtime/index.ts

@@ -22,6 +22,13 @@ export {
   beginTurn,
   endTurn,
   __bfReportOutput,
+  // Request-scoped env signal (router v0.5). The compiler emits island client JS
+  // that imports `searchParams` from `@barefootjs/client/runtime`; re-exporting
+  // it from the shared reactive module (same as the signal primitives above)
+  // means this entry and the main `@barefootjs/client` entry resolve to ONE
+  // signal instance — no second copy to disconnect from router pushes.
+  searchParams,
+  __bfSetServerEnvReader,
   type Reactive,
   type Signal,
   type Memo,
@@ -92,7 +99,7 @@ export { styleToCss } from './style.ts'
 
 // Runtime helpers
 export { findScope, find, $, $c, $t, qsa, qsaChildScope, qsaChildScopes, cssEscape } from './query.ts'
-export { hydrate, rehydrateAll, flushHydration, getRegisteredDef } from './hydrate.ts'
+export { hydrate, rehydrateAll, rehydrateScope, disposeScope, flushHydration, getRegisteredDef } from './hydrate.ts'
 export { registerComponent, getComponentInit, initChild, upsertChild } from './registry.ts'
 export { insert, type BranchConfig, type BranchTemplateResult } from './insert.ts'
 export { __bfSlot } from './branch-slot.ts'

package/src/runtime/streaming.ts

@@ -13,8 +13,14 @@
  * 3. This module swaps fallback → resolved content and triggers hydration.
  */
 
-import { BF_ASYNC, BF_ASYNC_RESOLVE } from '@barefootjs/shared'
-import { rehydrateAll } from './hydrate.ts'
+import {
+  BF_ASYNC,
+  BF_ASYNC_RESOLVE,
+  BF_SEAM_DISPOSE_WITHIN,
+  BF_SEAM_HYDRATE,
+  BF_SEAM_HYDRATE_WITHIN,
+} from '@barefootjs/shared'
+import { rehydrateAll, rehydrateScope, disposeScope } from './hydrate.ts'
 
 /**
  * Swap a streaming fallback placeholder with its resolved content.
@@ -52,7 +58,11 @@ export function __bf_swap(id: string): void {
  * Makes `__bf_swap` available as `window.__bf_swap` so that inline
  * `<script>__bf_swap("a0")</script>` tags in streaming chunks can call it.
  *
- * Also exposes `window.__bf_hydrate` for manual re-hydration triggers.
+ * Also exposes re-hydration / disposal seams for an out-of-tree client
+ * router (`@barefootjs/router`):
+ *   - `window.__bf_hydrate`        — re-hydrate the whole document
+ *   - `window.__bf_hydrate_within` — re-hydrate only a swapped subtree
+ *   - `window.__bf_dispose_within` — dispose the islands in a subtree
  *
  * Call this once, early in the page (before any streaming chunks arrive).
  */
@@ -61,5 +71,9 @@ export function setupStreaming(): void {
 
   const w = window as unknown as Record<string, unknown>
   w.__bf_swap = __bf_swap
-  w.__bf_hydrate = rehydrateAll
+  // Seam names shared with `@barefootjs/router` via `@barefootjs/shared` so the
+  // installer (here) and the reader (the router) can never drift apart.
+  w[BF_SEAM_HYDRATE] = rehydrateAll
+  w[BF_SEAM_HYDRATE_WITHIN] = rehydrateScope
+  w[BF_SEAM_DISPOSE_WITHIN] = disposeScope
 }