@nifrajs/web 5.5.0 → 5.6.0

package/src/server-components/runtime.ts

@@ -20,9 +20,11 @@ import {
 import { BoundedComponentTasks, componentAbort } from "./scheduler.ts"
 import { componentValue } from "./schema.ts"
 import type {
+  ComponentHoles,
   ComponentInstance,
   ComponentOwner,
   ComponentRecord,
+  ComponentRender,
   ServerComponent,
   ServerComponentContext,
   ServerComponentHandle,
@@ -42,6 +44,11 @@ export interface ServerComponentsOptions {
   readonly build: string
   readonly adapter: ServerComponentRenderAdapter
   readonly owners: Readonly<Record<string, ComponentOwner>>
+  /**
+   * Experimental: route id to the server components its partially prerendered holes may show, each
+   * through `serverHole`. A route is an owner or hosts holes, never both.
+   */
+  readonly holes?: Readonly<Record<string, ComponentHoles>>
   readonly capabilities?: readonly CapabilityDefinition[]
   readonly assets?: readonly string[]
 }
@@ -103,20 +110,19 @@ export function createServerComponents(options: ServerComponentsOptions): Server
   )
   if (capabilities.size !== (options.capabilities?.length ?? 0))
     throw new ServerComponentError("component_contract")
-  for (const [routeId, owner] of Object.entries(options.owners)) {
-    if (
-      typeof owner.instances !== "function" ||
-      (owner.scope !== "anonymous" && typeof owner.scope !== "function")
-    )
-      throw new ServerComponentError("component_contract")
+  /** A route's component allowlist, by reference, each within the capabilities the route grants. */
+  const allowlist = (
+    list: readonly ServerComponentHandle[],
+    granted: readonly string[] = [],
+  ): ReadonlyMap<string, ServerComponentHandle> => {
     const components = new Map<string, ServerComponentHandle>()
-    const allowed = new Set(owner.capabilities ?? [])
+    const allowed = new Set(granted)
     for (const capability of allowed) {
       const declared = capabilities.get(capability)
       if (declared === undefined || (declared.zone === "domain" && declared.access !== "read"))
         throw new ServerComponentError("component_contract")
     }
-    for (const component of owner.components) {
+    for (const component of list) {
       if (
         !isServerComponent(component) ||
         component.reference === undefined ||
@@ -128,11 +134,106 @@ export function createServerComponents(options: ServerComponentsOptions): Server
       if (serverComponentCapabilities(component).some((capability) => !allowed.has(capability)))
         throw new ServerComponentError("component_contract")
     }
-    owners.set(routeId, { owner, components })
+    return components
+  }
+  for (const [routeId, owner] of Object.entries(options.owners)) {
+    if (
+      typeof owner.instances !== "function" ||
+      (owner.scope !== "anonymous" && typeof owner.scope !== "function")
+    )
+      throw new ServerComponentError("component_contract")
+    owners.set(routeId, { owner, components: allowlist(owner.components, owner.capabilities) })
+  }
+  const holes = new Map<
+    string,
+    { capabilities: readonly string[]; components: ReadonlyMap<string, ServerComponentHandle> }
+  >()
+  for (const [routeId, entry] of Object.entries(options.holes ?? {})) {
+    // An owner route renders whole, so its holes never run.
+    if (owners.has(routeId) || !Array.isArray(entry.components))
+      throw new ServerComponentError("component_contract")
+    holes.set(routeId, {
+      capabilities: entry.capabilities ?? [],
+      components: allowlist(entry.components, entry.capabilities),
+    })
+  }
+  /** A rendered instance as a record: its range HTML checked, its payload and island props public. */
+  const recordOf = (
+    instance: {
+      readonly id: string
+      readonly reference: string
+      readonly key: ComponentRecord["key"]
+      readonly parent?: string | undefined
+      readonly input: ComponentRecord["input"]
+    },
+    rendered: ComponentRender,
+  ): ComponentRecord => {
+    const record: ComponentRecord = {
+      instance: instance.id,
+      reference: instance.reference,
+      key: instance.key,
+      parent: instance.parent ?? null,
+      input: instance.input,
+      html: componentRangeHTML(rendered.html, assets),
+    }
+    if (rendered.payload !== undefined)
+      Object.assign(record, {
+        payload: componentValue(rendered.payload, COMPONENT_LIMITS.outputBytes),
+      })
+    if (rendered.islands !== undefined)
+      Object.assign(record, {
+        islands: rendered.islands.map((island) => ({
+          ...island,
+          props: componentValue(island.props),
+        })),
+      })
+    return record
   }
   return {
     owns: (routeId) => owners.has(routeId),
-    capabilities: (routeId) => owners.get(routeId)?.owner.capabilities ?? [],
+    capabilities: (routeId) =>
+      owners.get(routeId)?.owner.capabilities ?? holes.get(routeId)?.capabilities ?? [],
+    hosts: (routeId) => holes.has(routeId),
+    async hole(routeId, component, key, input, context) {
+      const reference = isServerComponent(component) ? component.reference : undefined
+      const handle =
+        reference === undefined ? undefined : holes.get(routeId)?.components.get(reference)
+      if (
+        reference === undefined ||
+        handle === undefined ||
+        handle !== component ||
+        !componentKey(key)
+      )
+        throw new ServerComponentError("component_contract")
+      const signal = AbortSignal.any([
+        context.signal,
+        AbortSignal.timeout(COMPONENT_LIMITS.executionMs),
+      ])
+      const ctx: ServerComponentContext = Object.create(context, {
+        signal: { value: signal, enumerable: true },
+      })
+      const value = componentValue(input, COMPONENT_LIMITS.inputBytes)
+      const id = await serverComponentIdentity(routeId, handle, key, null)
+      return admission.run(signal, async () => {
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The route's hole allowlist identifies this handle; authorization validates the input before any callback runs.
+        const authorized = await authorizeServerComponent(handle as ServerComponent, value, ctx)
+        const prepared = await prepareAuthorizedServerComponent(authorized)
+        const rendered = await options.adapter.render(prepared.view, prepared.props, {
+          reference,
+          instance: id,
+          signal,
+          children: [],
+        })
+        if (signal.aborted) throw componentAbort(signal)
+        if (typeof rendered.html !== "string") throw new ServerComponentError("component_contract")
+        if ((rendered.islands?.length ?? 0) > COMPONENT_LIMITS.instances)
+          throw new ServerComponentError("component_limit", 413)
+        const record = recordOf({ id, reference, key, input: value }, rendered)
+        if (encoder.encode(JSON.stringify(record)).length > COMPONENT_LIMITS.outputBytes)
+          throw new ServerComponentError("component_limit", 413)
+        return record
+      })
+    },
     classify(request, routeId) {
       const selection = readComponentRequest(request)
       if (selection === undefined) return undefined
@@ -275,29 +376,10 @@ export function createServerComponents(options: ServerComponentsOptions): Server
               if (signal.aborted) throw componentAbort(signal)
               if (typeof rendered.html !== "string")
                 throw new ServerComponentError("component_contract")
-              const html = componentRangeHTML(rendered.html, assets)
+              const record = recordOf({ ...instance, id }, rendered)
               count += rendered.islands?.length ?? 0
               if (count > COMPONENT_LIMITS.instances)
                 throw new ServerComponentError("component_limit", 413)
-              const record: ComponentRecord = {
-                instance: id,
-                reference: instance.reference,
-                key: instance.key,
-                parent: instance.parent ?? null,
-                input: instance.input,
-                html,
-              }
-              if (rendered.payload !== undefined)
-                Object.assign(record, {
-                  payload: componentValue(rendered.payload, COMPONENT_LIMITS.outputBytes),
-                })
-              if (rendered.islands !== undefined)
-                Object.assign(record, {
-                  islands: rendered.islands.map((island) => ({
-                    ...island,
-                    props: componentValue(island.props),
-                  })),
-                })
               const size = encoder.encode(JSON.stringify(record)).length
               bytes += size
               if (

package/src/server-components/state.ts

@@ -50,6 +50,69 @@ function island(value: unknown): ComponentIsland {
   if (item.slots !== undefined) Object.assign(result, { slots: item.slots })
   return result
 }
+/** One record, checked as each of a state's is; `ids` and `islandIds` collect what must be unique. */
+function componentRecord(
+  value: unknown,
+  ids: Set<string>,
+  islandIds: Set<string>,
+): ComponentRecord {
+  const record = object(
+    value,
+    ["instance", "reference", "key", "parent", "input", "html"],
+    ["payload", "islands"],
+  )
+  if (
+    !componentToken(record.instance) ||
+    ids.has(record.instance) ||
+    !componentToken(record.reference) ||
+    !componentKey(record.key) ||
+    (record.parent !== null && !componentToken(record.parent)) ||
+    typeof record.html !== "string"
+  )
+    throw new ServerComponentError("component_protocol", 400)
+  ids.add(record.instance)
+  validateComponentHTML(record.html)
+  if (
+    record.islands !== undefined &&
+    (!Array.isArray(record.islands) || record.islands.length > COMPONENT_LIMITS.instances)
+  )
+    throw new ServerComponentError("component_protocol", 400)
+  const islands =
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
+    record.islands === undefined ? undefined : (record.islands as unknown[]).map(island)
+  for (const island of islands ?? []) {
+    if (islandIds.has(island.renderId)) throw new ServerComponentError("component_protocol", 400)
+    islandIds.add(island.renderId)
+  }
+  const result: ComponentRecord = {
+    instance: record.instance,
+    reference: record.reference,
+    key: record.key,
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
+    parent: record.parent as string | null,
+    html: record.html,
+    input: componentValue(record.input, COMPONENT_LIMITS.inputBytes),
+  }
+  if (record.payload !== undefined)
+    Object.assign(result, {
+      payload: componentValue(record.payload, COMPONENT_LIMITS.outputBytes),
+    })
+  if (islands !== undefined) Object.assign(result, { islands })
+  return result
+}
+
+/** A record that arrives alone, as a partially prerendered hole's does, checked as a state's are. */
+export function parseComponentRecord(value: unknown): ComponentRecord {
+  const record = componentRecord(
+    componentValue(value, COMPONENT_LIMITS.documentBytes),
+    new Set(),
+    new Set(),
+  )
+  if ((record.islands?.length ?? 0) >= COMPONENT_LIMITS.instances)
+    throw new ServerComponentError("component_limit", 413)
+  return record
+}
+
 export function parseComponentState(
   value: unknown,
   maxBytes: number = COMPONENT_LIMITS.documentBytes,
@@ -72,52 +135,11 @@ export function parseComponentState(
   const islandIds = new Set<string>()
   let instances = state.records.length
   const records: ComponentRecord[] = state.records.map((value: unknown) => {
-    const record = object(
-      value,
-      ["instance", "reference", "key", "parent", "input", "html"],
-      ["payload", "islands"],
-    )
-    if (
-      !componentToken(record.instance) ||
-      ids.has(record.instance) ||
-      !componentToken(record.reference) ||
-      !componentKey(record.key) ||
-      (record.parent !== null && !componentToken(record.parent)) ||
-      typeof record.html !== "string"
-    )
-      throw new ServerComponentError("component_protocol", 400)
-    ids.add(record.instance)
-    validateComponentHTML(record.html)
-    if (
-      record.islands !== undefined &&
-      (!Array.isArray(record.islands) || record.islands.length > COMPONENT_LIMITS.instances)
-    )
-      throw new ServerComponentError("component_protocol", 400)
-    const islands =
-      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
-      record.islands === undefined ? undefined : (record.islands as unknown[]).map(island)
-    for (const island of islands ?? []) {
-      if (islandIds.has(island.renderId)) throw new ServerComponentError("component_protocol", 400)
-      islandIds.add(island.renderId)
-    }
-    instances += islands?.length ?? 0
+    const record = componentRecord(value, ids, islandIds)
+    instances += record.islands?.length ?? 0
     if (instances > COMPONENT_LIMITS.instances)
       throw new ServerComponentError("component_limit", 413)
-    const result: ComponentRecord = {
-      instance: record.instance,
-      reference: record.reference,
-      key: record.key,
-      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
-      parent: record.parent as string | null,
-      html: record.html,
-      input: componentValue(record.input, COMPONENT_LIMITS.inputBytes),
-    }
-    if (record.payload !== undefined)
-      Object.assign(result, {
-        payload: componentValue(record.payload, COMPONENT_LIMITS.outputBytes),
-      })
-    if (islands !== undefined) Object.assign(result, { islands })
-    return result
+    return record
   })
   // Refreshes contain a single child and may name its already mounted parent. Documents carry the full forest.
   for (const record of records) {

package/src/server-components/types.ts

@@ -98,6 +98,12 @@ export interface ComponentOwner {
   readonly scope: "anonymous" | ((ctx: ServerComponentContext) => string | Promise<string>)
 }
 
+/** Experimental: the server components a partially prerendered route's holes may show. */
+export interface ComponentHoles {
+  readonly components: readonly ServerComponentHandle[]
+  readonly capabilities?: readonly string[]
+}
+
 export interface ServerComponentHandle {
   readonly reference?: string
   readonly input: StandardSchemaV1
@@ -135,4 +141,14 @@ export interface ServerComponentRuntime {
   ): Promise<ComponentState>
   response(state: ComponentState, selection: import("./protocol.ts").ComponentRequest): Response
   failure(error: unknown): Response
+  /** Whether the route's partially prerendered holes may show server components. */
+  hosts?(routeId: string): boolean
+  /** Render `component` as the route's hole `key`, with the hole loader's output as its input. */
+  hole?(
+    routeId: string,
+    component: object,
+    key: string,
+    input: unknown,
+    context: ServerComponentContext,
+  ): Promise<ComponentRecord>
 }

package/src/vite.ts

@@ -23,10 +23,21 @@ import { isHiddenPath } from "@nifrajs/core/static-file"
 import { CLIENT_BATCH_MAX_BYTES } from "./dev-client.ts"
 import { DEV_REQUEST_ID_HEADER, DEV_SERVER_FILES } from "./dev-feed.ts"
 import { listenOrExplain } from "./dev-port.ts"
-import { createDevSession, type DevAppHooks, isDevAgentPath } from "./dev-session.ts"
+import {
+  createDevSession,
+  type DevAppHooks,
+  isDevAgentPath,
+  isLoopbackHost,
+} from "./dev-session.ts"
 import { discoverRoutes } from "./fs.ts"
-import { DEFAULT_DEV_PORT, generateClientEntry, setSsrModuleLoader } from "./index.ts"
+import {
+  DEFAULT_DEV_PORT,
+  generateClientEntry,
+  type LiveClientEntry,
+  setSsrModuleLoader,
+} from "./index.ts"
 import { admitViteTags } from "./internal/dev-csp.ts"
+import { type UpgradableApp, upgradeOnNode } from "./internal/dev-websocket.ts"
 import { viteDedupePackages } from "./internal/identity-policy.ts"
 import {
   assertIdentityParity,
@@ -49,7 +60,7 @@ import { viteServerFnStub } from "./plugins/vite-server-fn.ts"
 import { viteZoneGuard } from "./plugins/vite-zone-guard.ts"
 
 /** Minimal app surface - `createWebApp(...)` satisfies it. */
-interface FetchApp {
+interface FetchApp extends UpgradableApp {
   fetch(request: Request): Response | Promise<Response>
 }
 
@@ -79,7 +90,10 @@ interface ViteLike {
   /** The module graph, used to invalidate a changed file AND its transitive importers before reload. */
   readonly moduleGraph?: ViteModuleGraph
   /** The resolved config: `publicDir` is absolute, or `""` when the public directory is off. */
-  readonly config?: { readonly publicDir?: string }
+  readonly config?: {
+    readonly publicDir?: string
+    readonly server?: { readonly allowedHosts?: true | readonly string[] }
+  }
   readonly watcher: {
     on(event: "change" | "add" | "unlink", cb: (path: string) => void): void
     on(event: "ready", cb: () => void): void
@@ -163,6 +177,8 @@ export interface ViteDevServerOptions {
    * fix (default `true`). Off, the errors still reach the feed.
    */
   readonly indicator?: boolean
+  /** The app runs `createWebApp({ live })`: the same option as the build's (`BuildClientOptions.live`). */
+  readonly live?: LiveClientEntry | undefined
 }
 
 export interface ViteDevServer {
@@ -236,7 +252,7 @@ const readAgentBody = async (req: IncomingMessage, max: number): Promise<Buffer
 function toWebRequest(req: IncomingMessage, body: Buffer | undefined): Request {
   const headers = new Headers()
   for (const [key, value] of Object.entries(req.headers)) {
-    if (typeof value === "string") headers.set(key, value)
+    if (typeof value === "string") appendJoined(headers, key, value)
     else if (Array.isArray(value)) for (const v of value) headers.append(key, v)
   }
   const url = `http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`
@@ -252,6 +268,23 @@ function toWebRequest(req: IncomingMessage, body: Buffer | undefined): Request {
   return new Request(url, init as unknown as ConstructorParameters<typeof Request>[1])
 }
 
+/**
+ * Node joins a repeated field into one string, and a trailing space there means the last member was
+ * empty (each field line is trimmed). `Headers` strips the whitespace around each value it is given,
+ * so the empty members are appended one by one to keep the "a, " production shows.
+ */
+function appendJoined(headers: Headers, name: string, joined: string): void {
+  const delimiter = name === "cookie" ? "; " : ", "
+  let base = joined
+  let empty = 0
+  while (base.endsWith(delimiter)) {
+    base = base.slice(0, -delimiter.length)
+    empty++
+  }
+  headers.append(name, base)
+  for (; empty > 0; empty--) headers.append(name, "")
+}
+
 /** The bits of a Node ServerResponse `pipeWebBodyToNode` touches - structural, to avoid a node:http dep here. */
 interface NodeResLike {
   /** Set once the socket is gone: `close` has fired, and a write returns `false` for good. */
@@ -395,7 +428,11 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
     const manifest = discoverRoutes(routesDir)
     writeFileSync(
       resolvePath(root, DEV_ENTRY),
-      generateClientEntry(manifest, { clientModule: options.clientModule, resolve: toUrl }),
+      generateClientEntry(manifest, {
+        clientModule: options.clientModule,
+        resolve: toUrl,
+        live: options.live,
+      }),
     )
   }
   const usePolling = options.poll ?? process.env.CHOKIDAR_USEPOLLING === "1"
@@ -457,6 +494,38 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
     handleWithVite(req, res)
   })
 
+  // The app's own WebSocket routes. Vite's HMR socket rides this server with a listener of its own,
+  // so its handshakes, and any no app route takes, are left to the other listeners.
+  server.on("upgrade", (req, socket, head) => {
+    const protocol = req.headers["sec-websocket-protocol"] ?? ""
+    if (protocol.includes("vite-hmr") || protocol.includes("vite-ping")) return
+    if (!allowsHost(req.headers.host)) {
+      socket.on("error", () => {})
+      socket.end("HTTP/1.1 403 Forbidden\r\ncontent-length: 0\r\nconnection: close\r\n\r\n")
+      return
+    }
+    void upgradeOnNode(app, toWebRequest(req, undefined), req, socket, head)
+  })
+
+  /** Vite's own rule for a handshake's Host: a loopback name, or one `server.allowedHosts` lists. */
+  function allowsHost(host: string | undefined): boolean {
+    if (isLoopbackHost(host)) return true
+    const allowed = vite.config?.server?.allowedHosts
+    if (allowed === true) return true
+    if (allowed === undefined || host === undefined) return false
+    let name: string
+    try {
+      name = new URL(`http://${host}`).hostname
+    } catch {
+      return false
+    }
+    return allowed.some(
+      (entry) =>
+        entry === name ||
+        (entry.startsWith(".") && (name === entry.slice(1) || name.endsWith(entry))),
+    )
+  }
+
   // Vite's public middleware serves every file under the public directory, dotfiles included. A
   // build ships no hidden file and the Bun pipeline's `servePublicDir` refuses one, so a request for
   // `/.env` or `/.git/config` goes to the app here too, as it does in production.

package/dist/nano.d.ts

@@ -1,125 +0,0 @@
-/**
- * `@nifrajs/web/nano` - the smallest state layer that still lets an island drive a keyed list.
- *
- * The islands lane (`@nifrajs/web/islands`) is imperative and correct-by-construction, but it has no
- * state primitive: every DOM update is hand-written, and a list means rebuilding the whole container.
- * nano adds a small, closed set of primitives and stops:
- *
- *   - `signal(v)`  - a current-value cell you read with `.get()` and write with `.set()`.
- *   - `computed(fn, [deps])` - a derived cell. Its dependencies are DECLARED, never auto-tracked.
- *   - `resource(fetcher, [deps])` - an async cell with an explicit pending/error/ready value. This is
- *     nano's answer to "suspense": no thrown promise, no magic boundary, just a value you can bind.
- *   - `bind` / `bindList` / `bindResource` - explicit, one-directional DOM bindings that each return
- *     their teardown.
- *
- * The design rule is the whole point: every reactive edge is a call you can see - a `bind(...)` or a
- * `computed(fn, [deps])`. There is no re-render scope, no VDOM, no template compiler, and no effect
- * that silently subscribes to whatever it happened to read. That is what removes the three failure
- * modes an AI (or a human) hits in a framework - stale closures, wrong effect deps, hydration
- * mismatch - and, just as importantly, it is what makes every remaining mistake STATICALLY
- * detectable: a missing dep is `[deps]` that doesn't list a signal the body reads; a leak is a `bind`
- * whose cleanup isn't returned. A framework's reactivity can't be linted like that; nano's can.
- *
- * Where nano stops: no client router and no nested/composable view state (a component tree that mounts
- * and unmounts its own children). When an app needs those, it has outgrown a vanilla page - reach for
- * a framework adapter (`@nifrajs/web-preact`), not more nano.
- *
- * Browser code: it touches the DOM and is meant to run in an island enhancer, never under SSR.
- */
-/** A value you can read now and be told about later. Both `signal` and `computed` are `Readable`, so
- * `bind`/`bindList` accept either. */
-export interface Readable<T> {
-    get(): T;
-    subscribe(listener: (value: T) => void): () => void;
-}
-/** A writable cell. `set` notifies subscribers only when the value actually changes (`Object.is`), so
- * a redundant write costs nothing. */
-export interface Signal<T> extends Readable<T> {
-    set(value: T): void;
-}
-/** A current-value cell. `signal(0)` -> `.get()` reads, `.set(1)` writes and notifies. */
-export declare function signal<T>(initial: T): Signal<T>;
-/**
- * A derived cell. `computed(() => a.get() + b.get(), [a, b])` recomputes whenever a declared
- * dependency changes and notifies its own subscribers when the derived value changes.
- *
- * The `deps` array is mandatory and explicit ON PURPOSE - it is the contract a linter checks against
- * the signals the body reads (`NF-C023`). Auto-tracking would remove the array but reintroduce the
- * exact "why didn't this update" bug that makes framework reactivity hard to get right.
- */
-export declare function computed<T>(compute: () => T, deps: readonly Readable<unknown>[]): Readable<T>;
-/** The three states of an async cell. A discriminated union on `status` so a consumer must handle
- * every branch - there is no "value that might secretly be loading", the failure mode of ad-hoc
- * `isLoading` booleans. `value`/`error` are narrowed by `status`. */
-export type ResourceState<T> = {
-    readonly status: "pending";
-    readonly value: undefined;
-    readonly error: undefined;
-} | {
-    readonly status: "ready";
-    readonly value: T;
-    readonly error: undefined;
-} | {
-    readonly status: "error";
-    readonly value: undefined;
-    readonly error: unknown;
-};
-/** An async cell: a `Readable` of `ResourceState<T>` plus `refetch()`. This is nano's answer to
- * "suspense" - an explicit pending/error/ready value, never a thrown promise or a magic boundary. */
-export interface Resource<T> extends Readable<ResourceState<T>> {
-    refetch(): void;
-}
-/**
- * An async derived cell. `resource(fetcher, [deps])` runs `fetcher` immediately and again whenever a
- * declared dependency changes, exposing the result as an explicit `{ status, value, error }`.
- *
- * Two footguns are handled here so they cannot be got wrong by hand:
- *   - Races: each run holds a generation; a stale run's resolution is dropped, and its `AbortSignal` is
- *     aborted, so an earlier-started-later-finishing fetch never overwrites a newer one.
- *   - Deps: like `computed`, dependencies are DECLARED (`NF-C023` checks the fetcher's `.get()` reads
- *     against the array). A `resource` that reads a signal its deps omit won't refetch when it changes.
- */
-export declare function resource<T>(fetcher: (signal: AbortSignal) => Promise<T>, deps?: readonly Readable<unknown>[]): Resource<T>;
-/**
- * Bind one element to a source: `apply(el, value)` runs once immediately and again on every change.
- * Returns the unsubscribe - hand it back as the island's cleanup (or collect several).
- *
- *   bind(count, remaining, (el, n) => { el.textContent = String(n) })
- */
-export declare function bind<T>(el: HTMLElement, source: Readable<T>, apply: (el: HTMLElement, value: T) => void): () => void;
-/** How a `bindList` turns items into keyed DOM. `key` MUST be stable and unique per item (never the
- * array index) - it is what lets add/remove/reorder touch only the changed rows. */
-export interface BindListOptions<T> {
-    key(item: T): string | number;
-    create(item: T): HTMLElement;
-    update?(el: HTMLElement, item: T): void;
-}
-/**
- * Bind a list signal to a container with keyed reconciliation: new items are `create`d, surviving
- * items are `update`d in place (keeping focus, scroll, and selection), removed items are detached,
- * and the children are ordered to match the array. Returns the unsubscribe.
- *
- * This is the one imperative task too error-prone to hand-write each time - it is why nano exists on
- * top of islands rather than leaving you to rebuild the container on every change.
- */
-export declare function bindList<T>(source: Readable<readonly T[]>, container: HTMLElement, options: BindListOptions<T>): () => void;
-/** How a `bindResource` maps each async state to the DOM. `ready` is required (there is always a
- * success shape to render); `pending`/`error` are optional. Every branch is explicit - no hidden
- * "still loading" state can slip through as a rendered `undefined`. */
-export interface BindResourceHandlers<T> {
-    ready(el: HTMLElement, value: T): void;
-    pending?(el: HTMLElement): void;
-    error?(el: HTMLElement, error: unknown): void;
-}
-/**
- * Bind an element to a `resource`, dispatching on `status`. Like `bind`, it applies immediately and
- * on every change and returns the unsubscribe - collect it (a discarded disposer is `NF-C021`).
- *
- *   bindResource(el, user, {
- *     pending: (n) => { n.textContent = "Loading…" },
- *     ready: (n, u) => { n.textContent = u.name },
- *     error: (n) => { n.textContent = "Failed to load" },
- *   })
- */
-export declare function bindResource<T>(el: HTMLElement, source: Readable<ResourceState<T>>, handlers: BindResourceHandlers<T>): () => void;
-//# sourceMappingURL=nano.d.ts.map

package/dist/nano.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"nano.d.ts","sourceRoot":"","sources":["../src/nano.ts"],"names":[],"mappings":"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"}