@astroscope/wormhole 2.0.0 → 3.0.1

package/README.md

@@ -6,9 +6,11 @@ Share dynamic server data with React islands and client scripts — typed, strea
 
 Astro recommends [nanostores](https://docs.astro.build/en/recipes/sharing-state/) for sharing state between islands, but nanostores are client-only — there's no built-in way to hydrate them with server data during SSR.
 
-`@astroscope/wormhole` bridges this gap: define your wormholes in a registry, resolve their values per request in a single middleware, and read them anywhere — Astro frontmatter, React islands, `<script>` blocks — through one typed `wormholes` proxy. Client code imports nothing of yours: the data streams into the HTML exactly where it is needed.
+`@astroscope/wormhole` bridges this gap: define your wormholes in a registry — each with the handler that resolves its value per request — and read them anywhere — Astro frontmatter, React islands, `<script>` blocks — through one typed `wormholes` proxy. Client code imports nothing of yours: the data streams into the HTML exactly where it is needed.
 
-**Delivery is sliced per island.** The build scans your client code to see which wormholes each component reads; at runtime every island receives exactly those, embedded in the HTML right before it. A wormhole no client code reads ships **zero bytes**.
+**Loading is scoped per route.** The build scans server and client code to see which wormholes each route can reach; at runtime only those handlers run for a request. A wormhole nothing on the route reads costs **nothing** — no database call, no bytes.
+
+**Delivery is sliced per island.** Every island receives exactly the wormholes its code reads, embedded in the HTML right before it. A wormhole no client code reads ships **zero bytes**.
 
 **Typical use cases:**
 
@@ -20,11 +22,11 @@ Astro recommends [nanostores](https://docs.astro.build/en/recipes/sharing-state/
 
 ## Important notes
 
-- **No secrets in wormholes.** Wormhole data is serialized into inline `<script>` tags and sent to the browser. Never store tokens, API keys, credentials, or any sensitive data in a wormhole. (In dev, *all* open wormholes ship with every page; production slicing is an optimization, not a security boundary.)
+- **No secrets in wormholes.** Wormhole data is serialized into inline `<script>` tags and sent to the browser. Never store tokens, API keys, credentials, or any sensitive data in a wormhole. (In dev, _all_ open wormholes ship with every page; production slicing is an optimization, not a security boundary.)
 - **Requires `@astroscope/node`** — per-island delivery uses its islands pipeline in production.
-- **The registry is server-only.** Client code must never import `src/wormholes.ts` — it accesses values through the `wormholes` proxy instead. (Importing it in client code throws at once.)
-- **`set()` is client-only.** Server values are request-scoped and come from the middleware.
-- **Values are deeply readonly.** `get()`, `subscribe()` and `useWormhole()` expose the value as `DeepReadonly<T>` — in-place mutation would silently bypass subscribers. The only way to update is `set()` with a new value: `wormholes.counter.set({ ...wormholes.counter.get(), count: 1 })`.
+- **The registry is server-only.** It carries the handlers, and with them your server code. Client code must never import `src/wormholes.ts` — it accesses values through the `wormholes` proxy instead. (The client build fails on such an import, and the eslint plugin's `no-registry-import` rule flags it in island code.)
+- **`set()` is client-only.** Server values are request-scoped and come from the handlers.
+- **Values are deeply readonly.** `get()`, `subscribe()` and `useWormhole()` expose the value as `ReadonlyDeep<T>` — in-place mutation would silently bypass subscribers. The only way to update is `set()` with a new value: `wormholes.counter.set({ ...wormholes.counter.get(), count: 1 })`.
 - **Prerendered pages get no wormhole data** — values are per-request by definition.
 
 ## Examples
@@ -39,6 +41,7 @@ npm install @astroscope/wormhole
 
 ```ts
 // astro.config.ts
+import { defineConfig } from 'astro/config';
 import node from '@astroscope/node';
 import wormhole from '@astroscope/wormhole';
 
@@ -49,13 +52,13 @@ export default defineConfig({
 });
 ```
 
-The integration registers the build-time scanner and generates a type stub from your registry, so `wormholes.<name>` is fully typed everywhere.
+The integration registers the build-time scanner, injects the middleware after your own `src/middleware.ts` (so handlers see everything it put on `locals`), and generates a type stub from your registry, so `wormholes.<name>` is fully typed everywhere. `wormhole({ exclude })` takes the same patterns as other astroscope middlewares (defaults to `RECOMMENDED_EXCLUDES`).
 
 ## Usage
 
 ### 1. Define the registry
 
-One file, one export named `wormholes` — the keys are the wormhole names (same pattern as Astro Actions' `src/actions/index.ts`):
+One file, one export named `wormholes` — the keys are the wormhole names, each entry carries its handler (same pattern as Astro Actions' `src/actions/index.ts`):
 
 ```ts
 // src/wormholes.ts
@@ -67,30 +70,18 @@ export type Session = {
 };
 
 export const wormholes = {
-  session: defineWormhole<Session>(),
-  cart: defineWormhole<{ items: string[] }>(),
-};
-```
-
-`src/wormholes/index.ts` works too.
-
-### 2. Resolve values in middleware
-
-```ts
-// src/middleware.ts
-import { createWormholeMiddleware } from '@astroscope/wormhole/server';
-
-export const onRequest = createWormholeMiddleware({
-  values: async (ctx) => ({
-    session: { user: 'Alice', role: 'admin' },
-    cart: await loadCart(ctx),
+  session: defineWormhole({
+    handler: (ctx): Session => ({ user: ctx.locals.user, role: ctx.locals.role }),
   }),
-});
+  cart: defineWormhole({
+    handler: async (ctx) => loadCart(ctx),
+  }),
+};
 ```
 
-The `values` return type is checked against your registry. Omit a key (or return `undefined` for it) to leave that wormhole closed for the request. Each request is isolated.
+`src/wormholes/index.ts` works too. A handler receives the request's `APIContext` and runs only for routes the build found a reader on; return `undefined` to leave the wormhole closed for the request. Each request is isolated.
 
-### 3. Read anywhere
+### 2. Read anywhere
 
 #### Astro frontmatter (SSR)
 
@@ -137,7 +128,7 @@ export function UserBadge() {
 </script>
 ```
 
-### 4. Update from the client
+### 3. Update from the client
 
 Call `set()` to update the wormhole — every `useWormhole()` hook and `subscribe()` callback on the page reacts, across islands:
 
@@ -171,21 +162,17 @@ export function RoleToggle() {
 
 The single access point, typed from your registry. `wormholes.cart` returns a `Wormhole<T>`:
 
-| Method                    | Description                                                                      |
-| ------------------------- | -------------------------------------------------------------------------------- |
-| `wormholes.x.get()`       | Read the current value as `DeepReadonly<T>` (server: request scope; client: streamed data) |
-| `wormholes.x.set(data)`   | Replace the value and notify all subscribers (client only)                        |
-| `wormholes.x.subscribe(fn)` | Listen for `set()` updates, returns an unsubscribe function                     |
+| Method                      | Description                                                                                |
+| --------------------------- | ------------------------------------------------------------------------------------------ |
+| `wormholes.x.get()`         | Read the current value as `ReadonlyDeep<T>` (server: request scope; client: streamed data) |
+| `wormholes.x.set(data)`     | Replace the value and notify all subscribers (client only)                                 |
+| `wormholes.x.subscribe(fn)` | Listen for `set()` updates, returns an unsubscribe function                                |
 
 Accesses must be static (`wormholes.cart`, `wormholes['cart']`). A dynamic access (`wormholes[name]`) still works, but the build can no longer tell which wormholes that chunk needs and delivers all open ones to its islands.
 
-### `defineWormhole<T>()` <sub>registry only</sub>
+### `defineWormhole({ handler, eager? })` <sub>registry only</sub>
 
-Creates a typed wormhole for the registry; the name comes from the registry key. Registry entries are full `Wormhole<T>` objects, so server code can also import `wormholes` from your own registry file directly.
-
-### `createWormholeMiddleware({ values, exclude? })` <sub>server only</sub>
-
-Creates the middleware: resolves `values(ctx)` per request, opens them for server-side `get()`, and delivers them to the client. `exclude` accepts the same patterns as other astroscope middlewares (defaults to `RECOMMENDED_EXCLUDES`).
+Creates a typed wormhole for the registry; the value type is inferred from the handler (or given as `defineWormhole<T>(...)`), the name comes from the registry key. `eager: true` runs the handler on every request instead of only where the build found a reader — for wormholes read by islands the build cannot attribute to a route (components chosen dynamically at render time). Registry entries are full `Wormhole<T>` objects, so server code can also import `wormholes` from your own registry file directly.
 
 ### `openWormholes(wh, data, fn)` <sub>server only</sub>
 
@@ -195,13 +182,15 @@ Provides values to server code that runs outside the request pipeline — tests,
 
 React hook that reads a wormhole and re-renders on `set()`. During SSR it reads the request scope, so server and client render identically.
 
-### `DeepReadonly<T>` / `UnwrapWormholes<R>`
+### `UnwrapWormholes<R>`
 
-Exported helper types. `DeepReadonly<T>` is the recursively-readonly value type; `UnwrapWormholes` maps a registry shape to its value types.
+Exported helper type mapping a registry shape to its value types. The recursively-readonly value type is `ReadonlyDeep<T>` from `@entwico/dash`.
 
 ## How it works
 
-At build time the integration scans your client code to see which wormholes each component reads, and generates the types for the `wormholes` proxy from your registry. At runtime the middleware resolves your values once per request, and each island's data is embedded in the HTML right before it — so it is always there before the island's code runs, even while the page is still streaming. On the client, `set()` updates the shared data and notifies subscribers, keeping islands and scripts in sync.
+Routes the build could not attribute (dev, astro's own routes) load everything. On the client, `set()` updates the shared data and notifies subscribers, keeping islands and scripts in sync.
+
+Each handler runs under its own `wormhole <name>` span beneath the request span — they run in parallel, and the trace shows which one holds the page's first byte — and records `astro.wormhole.handler.duration` {`astro.wormhole.name`}. A throwing handler is counted on `astro.wormhole.handler.failures` {`astro.wormhole.name`, `error.type`}, logged with its name, and fails the request. All through the adapter's telemetry, so nothing runs without its SDK.
 
 ## License
 

package/dist/als-CntRqWdO.js

@@ -0,0 +1,7 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/als.ts
+const als = globalThis[Symbol.for("@astroscope/wormhole/als")] ??= new AsyncLocalStorage();
+//#endregion
+export { als as t };
+
+//# sourceMappingURL=als-CntRqWdO.js.map

package/dist/als-CntRqWdO.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"als-CntRqWdO.js","names":[],"sources":["../src/als.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\n\n// a single ALS holds an immutable map of all open wormholes (keyed by wormhole key);\n// keyed on globalThis so the vite-runner and native module instances share one context\n// eslint-disable-next-line unicorn/no-global-object-property-assignment -- `Symbol.for` slot on globalThis, shared by the vite-runner and native module instances\nexport const als: AsyncLocalStorage<ReadonlyMap<string, unknown>> = ((globalThis as any)[\n  Symbol.for('@astroscope/wormhole/als')\n] ??= new AsyncLocalStorage());\n"],"mappings":";;AAKA,MAAa,MAAwD,WACnE,OAAO,IAAI,0BAA0B,OACjC,IAAI,kBAAkB"}

package/dist/{define-BO-pYQc1.js → define-DAoqsUVA.js}

@@ -1,19 +1,37 @@
+import { t as als } from "./als-CntRqWdO.js";
 import { t as wormholeKey } from "./key-BqTy1gM3.js";
-import { AsyncLocalStorage } from "node:async_hooks";
-//#region src/als.ts
-const als = globalThis[Symbol.for("@astroscope/wormhole/als")] ??= new AsyncLocalStorage();
-//#endregion
 //#region src/define.ts
 const ASSIGN = Symbol.for("@astroscope/wormhole.assign");
+const SOURCE = Symbol.for("@astroscope/wormhole.source");
 /**
-* Define a wormhole for the `src/wormholes.ts` registry. The wormhole's name is the
-* registry key — it is assigned when the registry is passed to
-* `createWormholeMiddleware()` (or `assignWormholeNames()`).
+* Define a wormhole for the `src/wormholes.ts` registry, actions-style. The
+* handler resolves the value per request; the middleware calls it only for routes
+* the build found a reader on (frontmatter, islands, scripts) — or on every
+* request with `eager: true`. The wormhole's name is the registry key, assigned
+* when the registry is passed to `createWormholeMiddleware()` (or
+* `assignWormholeNames()`).
 *
 * **Security:** wormhole data is serialized into the HTML and sent to the browser.
 * Never store secrets (tokens, API keys, credentials) in a wormhole.
+*
+* @example
+* ```typescript
+* export const wormholes = {
+*   cart: defineWormhole({ handler: (ctx) => ctx.locals.cart }),
+*   config: defineWormhole({ handler: () => loadConfig(), eager: true }),
+* };
+* ```
 */
-function defineWormhole() {
+function defineWormhole(definition) {
+	const wormhole = createWormhole();
+	wormhole[SOURCE] = {
+		handler: definition.handler,
+		eager: definition.eager ?? false
+	};
+	return wormhole;
+}
+/** the server-side wormhole object without a handler — the `wormholes` proxy stubs (internal) */
+function createWormhole() {
 	let name;
 	const requireName = () => {
 		if (name === void 0) throw new Error("wormhole is not registered — pass its registry to createWormholeMiddleware()");
@@ -44,6 +62,10 @@ function defineWormhole() {
 		}
 	};
 }
+/** the definition a registry entry was created with — undefined for proxy stubs */
+function getWormholeSource(wormhole) {
+	return wormhole[SOURCE];
+}
 /**
 * Assign each wormhole its registry key as name. Called by `createWormholeMiddleware()`;
 * exposed for setups that read wormholes on the server without the middleware.
@@ -51,11 +73,11 @@ function defineWormhole() {
 function assignWormholeNames(registry) {
 	for (const [name, wormhole] of Object.entries(registry)) {
 		const assign = wormhole[ASSIGN];
-		if (typeof assign !== "function") throw new Error(`registry entry "${name}" is not a wormhole — the registry must contain defineWormhole() values only`);
+		if (typeof assign !== "function") throw new TypeError(`registry entry "${name}" is not a wormhole — the registry must contain defineWormhole() values only`);
 		assign(name);
 	}
 }
 //#endregion
-export { defineWormhole as n, als as r, assignWormholeNames as t };
+export { getWormholeSource as i, createWormhole as n, defineWormhole as r, assignWormholeNames as t };
 
-//# sourceMappingURL=define-BO-pYQc1.js.map
+//# sourceMappingURL=define-DAoqsUVA.js.map

package/dist/define-DAoqsUVA.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-DAoqsUVA.js","names":[],"sources":["../src/define.ts"],"sourcesContent":["import type { ReadonlyDeep } from '@entwico/dash';\nimport { als } from './als.js';\nimport { wormholeKey } from './key.js';\nimport type { Wormhole, WormholeDefinition, WormholeHandler } from './types.js';\n\n// name assignment and the handler must survive dual module instances (vite runner +\n// native), so both ride the wormhole object itself under Symbol.for keys\nconst ASSIGN = Symbol.for('@astroscope/wormhole.assign');\nconst SOURCE = Symbol.for('@astroscope/wormhole.source');\n\n/** how the middleware opens a wormhole: its handler and whether every route loads it */\nexport type WormholeSource = { handler: WormholeHandler<unknown>; eager: boolean };\n\ntype Internal = Wormhole<unknown> & { [ASSIGN](next: string): void; [SOURCE]?: WormholeSource | undefined };\n\n/**\n * Define a wormhole for the `src/wormholes.ts` registry, actions-style. The\n * handler resolves the value per request; the middleware calls it only for routes\n * the build found a reader on (frontmatter, islands, scripts) — or on every\n * request with `eager: true`. The wormhole's name is the registry key, assigned\n * when the registry is passed to `createWormholeMiddleware()` (or\n * `assignWormholeNames()`).\n *\n * **Security:** wormhole data is serialized into the HTML and sent to the browser.\n * Never store secrets (tokens, API keys, credentials) in a wormhole.\n *\n * @example\n * ```typescript\n * export const wormholes = {\n *   cart: defineWormhole({ handler: (ctx) => ctx.locals.cart }),\n *   config: defineWormhole({ handler: () => loadConfig(), eager: true }),\n * };\n * ```\n */\nexport function defineWormhole<T>(definition: WormholeDefinition<T>): Wormhole<T> {\n  const wormhole = createWormhole() as Internal;\n\n  wormhole[SOURCE] = { handler: definition.handler as WormholeHandler<unknown>, eager: definition.eager ?? false };\n\n  return wormhole as Wormhole<T>;\n}\n\n/** the server-side wormhole object without a handler — the `wormholes` proxy stubs (internal) */\nexport function createWormhole<T>(): Wormhole<T> {\n  let name: string | undefined;\n\n  const requireName = (): string => {\n    if (name === undefined) {\n      throw new Error('wormhole is not registered — pass its registry to createWormholeMiddleware()');\n    }\n\n    return name;\n  };\n\n  const key = (): string => wormholeKey(requireName());\n\n  // methods must not rely on `this` — consumers pass them around detached\n  // (e.g. useSyncExternalStore(wormhole.subscribe, wormhole.get, wormhole.get))\n  const wormhole: Wormhole<T> & { [ASSIGN](next: string): void } = {\n    get name() {\n      return requireName();\n    },\n\n    get key() {\n      return key();\n    },\n\n    get(): ReadonlyDeep<T> {\n      const value = als.getStore()?.get(key());\n\n      if (value === undefined) {\n        throw new Error(\n          `wormhole \"${requireName()}\" is not open for this request — is it provided by the wormhole middleware?`,\n        );\n      }\n\n      return value as ReadonlyDeep<T>;\n    },\n\n    set(): void {\n      throw new Error(\n        `wormhole \"${requireName()}\" set() cannot be called on the server — values are request-scoped and provided by the middleware`,\n      );\n    },\n\n    subscribe(): () => void {\n      // server values never change within a request — nothing to notify\n      return () => {};\n    },\n\n    [ASSIGN](next: string): void {\n      if (name !== undefined && name !== next) {\n        throw new Error(`wormhole is registered under two names: \"${name}\" and \"${next}\"`);\n      }\n\n      name = next;\n    },\n  };\n\n  return wormhole;\n}\n\n/** the definition a registry entry was created with — undefined for proxy stubs */\nexport function getWormholeSource<T>(wormhole: Wormhole<T>): WormholeSource | undefined {\n  return (wormhole as unknown as Internal)[SOURCE];\n}\n\n/**\n * Assign each wormhole its registry key as name. Called by `createWormholeMiddleware()`;\n * exposed for setups that read wormholes on the server without the middleware.\n */\nexport function assignWormholeNames(registry: Record<string, object>): void {\n  for (const [name, wormhole] of Object.entries(registry)) {\n    const assign = (wormhole as { [ASSIGN]?: (next: string) => void })[ASSIGN];\n\n    if (typeof assign !== 'function') {\n      throw new TypeError(\n        `registry entry \"${name}\" is not a wormhole — the registry must contain defineWormhole() values only`,\n      );\n    }\n\n    assign(name);\n  }\n}\n"],"mappings":";;;AAOA,MAAM,SAAS,OAAO,IAAI,6BAA6B;AACvD,MAAM,SAAS,OAAO,IAAI,6BAA6B;;;;;;;;;;;;;;;;;;;;AA0BvD,SAAgB,eAAkB,YAAgD;CAChF,MAAM,WAAW,eAAe;CAEhC,SAAS,UAAU;EAAE,SAAS,WAAW;EAAqC,OAAO,WAAW,SAAS;CAAM;CAE/G,OAAO;AACT;;AAGA,SAAgB,iBAAiC;CAC/C,IAAI;CAEJ,MAAM,oBAA4B;EAChC,IAAI,SAAS,KAAA,GACX,MAAM,IAAI,MAAM,8EAA8E;EAGhG,OAAO;CACT;CAEA,MAAM,YAAoB,YAAY,YAAY,CAAC;CA6CnD,OAAO;EAxCL,IAAI,OAAO;GACT,OAAO,YAAY;EACrB;EAEA,IAAI,MAAM;GACR,OAAO,IAAI;EACb;EAEA,MAAuB;GACrB,MAAM,QAAQ,IAAI,SAAS,CAAC,EAAE,IAAI,IAAI,CAAC;GAEvC,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MACR,aAAa,YAAY,EAAE,4EAC7B;GAGF,OAAO;EACT;EAEA,MAAY;GACV,MAAM,IAAI,MACR,aAAa,YAAY,EAAE,kGAC7B;EACF;EAEA,YAAwB;GAEtB,aAAa,CAAC;EAChB;EAEA,CAAC,QAAQ,MAAoB;GAC3B,IAAI,SAAS,KAAA,KAAa,SAAS,MACjC,MAAM,IAAI,MAAM,4CAA4C,KAAK,SAAS,KAAK,EAAE;GAGnF,OAAO;EACT;CAGY;AAChB;;AAGA,SAAgB,kBAAqB,UAAmD;CACtF,OAAQ,SAAiC;AAC3C;;;;;AAMA,SAAgB,oBAAoB,UAAwC;CAC1E,KAAK,MAAM,CAAC,MAAM,aAAa,OAAO,QAAQ,QAAQ,GAAG;EACvD,MAAM,SAAU,SAAmD;EAEnE,IAAI,OAAO,WAAW,YACpB,MAAM,IAAI,UACR,mBAAmB,KAAK,6EAC1B;EAGF,OAAO,IAAI;CACb;AACF"}

package/dist/index.browser.d.ts

@@ -1,9 +1,9 @@
-import { a as WormholeRegistry, i as WormholeMap, n as UnwrapWormholes, r as Wormhole, t as DeepReadonly } from "./types-okMd-V3s.js";
+import { a as WormholeMap, i as WormholeHandler, n as Wormhole, o as WormholeRegistry, r as WormholeDefinition, t as UnwrapWormholes } from "./types-v_ftArqH.js";
 //#region src/index.browser.d.ts
-declare const wormholes: WormholeMap;
-declare function defineWormhole(): never;
-declare function assignWormholeNames(): never;
-declare function wormholeIntegration(): never;
+export declare const wormholes: WormholeMap;
+export declare function defineWormhole(): never;
+export declare function assignWormholeNames(): never;
+export default function wormholeIntegration(): never;
 //#endregion
-export { type DeepReadonly, type UnwrapWormholes, type Wormhole, type WormholeMap, type WormholeRegistry, assignWormholeNames, wormholeIntegration as default, defineWormhole, wormholes };
+export type { UnwrapWormholes, Wormhole, WormholeDefinition, WormholeHandler, WormholeMap, WormholeRegistry };
 //# sourceMappingURL=index.browser.d.ts.map

package/dist/index.browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.d.ts","names":[],"sources":["../src/index.browser.ts"],"mappings":";;cAiEa,WAAW;iBAMR;iBAMA;iBAIQ"}
+{"version":3,"file":"index.browser.d.ts","names":[],"sources":["../src/index.browser.ts"],"mappings":";;qBA0Ea,WAAW;wBAMR;wBAMA;wBAIQ"}

package/dist/index.browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.js","names":[],"sources":["../src/index.browser.ts"],"sourcesContent":["import { wormholeKey } from './key.js';\nimport type { DeepReadonly, Wormhole, WormholeMap } from './types.js';\n\nexport type { DeepReadonly, UnwrapWormholes, Wormhole, WormholeMap, WormholeRegistry } from './types.js';\n\n/**\n * Browser side of the `wormholes` proxy. Values live on `self.__wormholes__` — written\n * by the inline merge scripts the server emits before each island (and at stream end\n * for script consumers), or by client-side `set()` calls. The entry protocol is\n * `{ v: value, l: listeners }`, shared with the emitted scripts, so writes land in\n * either order.\n */\n\ntype Entry = { v?: unknown; l?: ((value: unknown) => void)[] | undefined };\n\nconst store: Record<string, Entry> = ((globalThis as any).__wormholes__ ??= {});\n\nconst stubs = new Map<string, Wormhole<unknown>>();\n\nfunction stub(name: string): Wormhole<unknown> {\n  let wormhole = stubs.get(name);\n\n  if (wormhole) {\n    return wormhole;\n  }\n\n  const entry = (): Entry => (store[name] ??= {});\n\n  wormhole = {\n    name,\n    key: wormholeKey(name),\n\n    get(): DeepReadonly<unknown> {\n      const value = entry().v;\n\n      if (value === undefined) {\n        throw new Error(`wormhole \"${name}\" has no data — is it provided by the wormhole middleware?`);\n      }\n\n      return value;\n    },\n\n    set(data): void {\n      const current = entry();\n\n      current.v = data;\n      current.l?.forEach((fn) => fn(data));\n    },\n\n    subscribe(fn): () => void {\n      const current = entry();\n\n      (current.l ??= []).push(fn);\n\n      return () => {\n        current.l = current.l?.filter((listener) => listener !== fn);\n      };\n    },\n  };\n\n  stubs.set(name, wormhole);\n\n  return wormhole;\n}\n\nexport const wormholes: WormholeMap = new Proxy({} as WormholeMap, {\n  get(_target, prop) {\n    return typeof prop === 'string' ? stub(prop) : undefined;\n  },\n});\n\nexport function defineWormhole(): never {\n  throw new Error(\n    'defineWormhole() is server-only — do not import the wormhole registry in client code; access wormholes via the `wormholes` proxy instead',\n  );\n}\n\nexport function assignWormholeNames(): never {\n  throw new Error('assignWormholeNames() is server-only');\n}\n\nexport default function wormholeIntegration(): never {\n  throw new Error('the @astroscope/wormhole integration is server-only');\n}\n"],"mappings":";;AAeA,MAAM,QAAgC,WAAoB,kBAAkB,CAAC;AAE7E,MAAM,wBAAQ,IAAI,IAA+B;AAEjD,SAAS,KAAK,MAAiC;CAC7C,IAAI,WAAW,MAAM,IAAI,IAAI;CAE7B,IAAI,UACF,OAAO;CAGT,MAAM,cAAsB,MAAM,UAAU,CAAC;CAE7C,WAAW;EACT;EACA,KAAK,YAAY,IAAI;EAErB,MAA6B;GAC3B,MAAM,QAAQ,MAAM,CAAC,CAAC;GAEtB,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,aAAa,KAAK,2DAA2D;GAG/F,OAAO;EACT;EAEA,IAAI,MAAY;GACd,MAAM,UAAU,MAAM;GAEtB,QAAQ,IAAI;GACZ,QAAQ,GAAG,SAAS,OAAO,GAAG,IAAI,CAAC;EACrC;EAEA,UAAU,IAAgB;GACxB,MAAM,UAAU,MAAM;GAEtB,CAAC,QAAQ,MAAM,CAAC,EAAA,CAAG,KAAK,EAAE;GAE1B,aAAa;IACX,QAAQ,IAAI,QAAQ,GAAG,QAAQ,aAAa,aAAa,EAAE;GAC7D;EACF;CACF;CAEA,MAAM,IAAI,MAAM,QAAQ;CAExB,OAAO;AACT;AAEA,MAAa,YAAyB,IAAI,MAAM,CAAC,GAAkB,EACjE,IAAI,SAAS,MAAM;CACjB,OAAO,OAAO,SAAS,WAAW,KAAK,IAAI,IAAI,KAAA;AACjD,EACF,CAAC;AAED,SAAgB,iBAAwB;CACtC,MAAM,IAAI,MACR,0IACF;AACF;AAEA,SAAgB,sBAA6B;CAC3C,MAAM,IAAI,MAAM,sCAAsC;AACxD;AAEA,SAAwB,sBAA6B;CACnD,MAAM,IAAI,MAAM,qDAAqD;AACvE"}
+{"version":3,"file":"index.browser.js","names":[],"sources":["../src/index.browser.ts"],"sourcesContent":["import type { ReadonlyDeep } from '@entwico/dash';\nimport { wormholeKey } from './key.js';\nimport type { Wormhole, WormholeMap } from './types.js';\n\nexport type {\n  UnwrapWormholes,\n  Wormhole,\n  WormholeDefinition,\n  WormholeHandler,\n  WormholeMap,\n  WormholeRegistry,\n} from './types.js';\n\n/**\n * Browser side of the `wormholes` proxy. Values live on `self.__wormholes__` — written\n * by the inline merge scripts the server emits before each island (and at stream end\n * for script consumers), or by client-side `set()` calls. The entry protocol is\n * `{ v: value, l: listeners }`, shared with the emitted scripts, so writes land in\n * either order.\n */\n\ntype Entry = { v?: unknown; l?: ((value: unknown) => void)[] | undefined };\n\n// eslint-disable-next-line unicorn/no-global-object-property-assignment -- `self.__wormholes__` is the entry store shared with the emitted merge scripts\nconst store: Record<string, Entry> = ((globalThis as any).__wormholes__ ??= {});\n\nconst stubs = new Map<string, Wormhole<unknown>>();\n\nfunction stub(name: string): Wormhole<unknown> {\n  let wormhole = stubs.get(name);\n\n  if (wormhole) {\n    return wormhole;\n  }\n\n  const entry = (): Entry => (store[name] ??= {});\n\n  wormhole = {\n    name,\n    key: wormholeKey(name),\n\n    get(): ReadonlyDeep<unknown> {\n      const value = entry().v;\n\n      if (value === undefined) {\n        throw new Error(`wormhole \"${name}\" has no data — is it provided by the wormhole middleware?`);\n      }\n\n      return value;\n    },\n\n    set(data): void {\n      const current = entry();\n\n      current.v = data;\n      current.l?.forEach((fn) => fn(data));\n    },\n\n    subscribe(fn): () => void {\n      const current = entry();\n\n      (current.l ??= []).push(fn);\n\n      return () => {\n        current.l = current.l?.filter((listener) => listener !== fn);\n      };\n    },\n  };\n\n  stubs.set(name, wormhole);\n\n  return wormhole;\n}\n\nexport const wormholes: WormholeMap = new Proxy({} as WormholeMap, {\n  get(_target, prop) {\n    return typeof prop === 'string' ? stub(prop) : undefined;\n  },\n});\n\nexport function defineWormhole(): never {\n  throw new Error(\n    'defineWormhole() is server-only — do not import the wormhole registry in client code; access wormholes via the `wormholes` proxy instead',\n  );\n}\n\nexport function assignWormholeNames(): never {\n  throw new Error('assignWormholeNames() is server-only');\n}\n\nexport default function wormholeIntegration(): never {\n  throw new Error('the @astroscope/wormhole integration is server-only');\n}\n"],"mappings":";;AAwBA,MAAM,QAAgC,WAAoB,kBAAkB,CAAC;AAE7E,MAAM,wBAAQ,IAAI,IAA+B;AAEjD,SAAS,KAAK,MAAiC;CAC7C,IAAI,WAAW,MAAM,IAAI,IAAI;CAE7B,IAAI,UACF,OAAO;CAGT,MAAM,cAAsB,MAAM,UAAU,CAAC;CAE7C,WAAW;EACT;EACA,KAAK,YAAY,IAAI;EAErB,MAA6B;GAC3B,MAAM,QAAQ,MAAM,CAAC,CAAC;GAEtB,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,aAAa,KAAK,2DAA2D;GAG/F,OAAO;EACT;EAEA,IAAI,MAAY;GACd,MAAM,UAAU,MAAM;GAEtB,QAAQ,IAAI;GACZ,QAAQ,GAAG,SAAS,OAAO,GAAG,IAAI,CAAC;EACrC;EAEA,UAAU,IAAgB;GACxB,MAAM,UAAU,MAAM;GAEtB,CAAC,QAAQ,MAAM,CAAC,EAAA,CAAG,KAAK,EAAE;GAE1B,aAAa;IACX,QAAQ,IAAI,QAAQ,GAAG,QAAQ,aAAa,aAAa,EAAE;GAC7D;EACF;CACF;CAEA,MAAM,IAAI,MAAM,QAAQ;CAExB,OAAO;AACT;AAEA,MAAa,YAAyB,IAAI,MAAM,CAAC,GAAkB,EACjE,IAAI,SAAS,MAAM;CACjB,OAAO,OAAO,SAAS,WAAW,KAAK,IAAI,IAAI,KAAA;AACjD,EACF,CAAC;AAED,SAAgB,iBAAwB;CACtC,MAAM,IAAI,MACR,0IACF;AACF;AAEA,SAAgB,sBAA6B;CAC3C,MAAM,IAAI,MAAM,sCAAsC;AACxD;AAEA,SAAwB,sBAA6B;CACnD,MAAM,IAAI,MAAM,qDAAqD;AACvE"}

package/dist/index.d.ts

@@ -1,33 +1,51 @@
-import { a as WormholeRegistry, i as WormholeMap, n as UnwrapWormholes, r as Wormhole, t as DeepReadonly } from "./types-okMd-V3s.js";
+import { a as WormholeMap, i as WormholeHandler, n as Wormhole, o as WormholeRegistry, r as WormholeDefinition, t as UnwrapWormholes } from "./types-v_ftArqH.js";
+import { ExcludePattern } from "@astroscope/node/excludes";
 import { AstroIntegration } from "astro";
 //#region src/integration.d.ts
+type WormholeIntegrationOptions = {
+  /** patterns the middleware skips — no handler runs, nothing is delivered; defaults to RECOMMENDED_EXCLUDES */
+  exclude?: ExcludePattern[] | undefined;
+};
 /**
- * Astro integration for wormholes with per-island payload slicing.
+ * Astro integration for wormholes with per-route loading and per-island delivery.
  *
  * Resolves the `src/wormholes.ts` registry and exposes it to the middleware as a
- * virtual module, registers the vite plugin that scans client code for
- * `wormholes.<name>` accesses and maps them onto the emitted chunks, and generates
- * the registry type stub that types the `wormholes` proxy. Delivery happens at
- * runtime: the wormhole middleware opens per-request values, and the islands
- * emitter (via `@astroscope/node`) writes each island's slice before its tag.
+ * virtual module, injects the middleware after the project's own (so handlers see
+ * everything earlier middleware put on `locals`), registers the vite plugin that
+ * scans server and client code for `wormholes.<name>` accesses and maps them onto
+ * routes and chunks, and generates the registry type stub that types the
+ * `wormholes` proxy. Delivery happens at runtime: the middleware runs the handlers
+ * the route needs, and the islands emitter (via `@astroscope/node`) writes each
+ * island's slice before its tag.
  */
-declare function wormholeIntegration(): AstroIntegration;
+export default function wormholeIntegration(options?: WormholeIntegrationOptions): AstroIntegration;
 //#endregion
 //#region src/define.d.ts
 /**
- * Define a wormhole for the `src/wormholes.ts` registry. The wormhole's name is the
- * registry key — it is assigned when the registry is passed to
- * `createWormholeMiddleware()` (or `assignWormholeNames()`).
+ * Define a wormhole for the `src/wormholes.ts` registry, actions-style. The
+ * handler resolves the value per request; the middleware calls it only for routes
+ * the build found a reader on (frontmatter, islands, scripts) — or on every
+ * request with `eager: true`. The wormhole's name is the registry key, assigned
+ * when the registry is passed to `createWormholeMiddleware()` (or
+ * `assignWormholeNames()`).
  *
  * **Security:** wormhole data is serialized into the HTML and sent to the browser.
  * Never store secrets (tokens, API keys, credentials) in a wormhole.
+ *
+ * @example
+ * ```typescript
+ * export const wormholes = {
+ *   cart: defineWormhole({ handler: (ctx) => ctx.locals.cart }),
+ *   config: defineWormhole({ handler: () => loadConfig(), eager: true }),
+ * };
+ * ```
  */
-declare function defineWormhole<T>(): Wormhole<T>;
+export declare function defineWormhole<T>(definition: WormholeDefinition<T>): Wormhole<T>;
 /**
  * Assign each wormhole its registry key as name. Called by `createWormholeMiddleware()`;
  * exposed for setups that read wormholes on the server without the middleware.
  */
-declare function assignWormholeNames(registry: Record<string, object>): void;
+export declare function assignWormholeNames(registry: Record<string, object>): void;
 //#endregion
 //#region src/index.d.ts
 /**
@@ -37,7 +55,7 @@ declare function assignWormholeNames(registry: Record<string, object>): void;
  * server-rendered islands alike. Typed via the registry type stub the integration
  * generates from `src/wormholes.ts`.
  */
-declare const wormholes: WormholeMap;
+export declare const wormholes: WormholeMap;
 //#endregion
-export { type DeepReadonly, type UnwrapWormholes, type Wormhole, type WormholeMap, type WormholeRegistry, assignWormholeNames, wormholeIntegration as default, defineWormhole, wormholes };
+export type { UnwrapWormholes, Wormhole, WormholeDefinition, WormholeHandler, WormholeIntegrationOptions, WormholeMap, WormholeRegistry };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/integration.ts","../src/define.ts","../src/index.ts"],"mappings":";;;;;;;;;;;;;iBAgBwB,uBAAuB;;;;;;;;;;;iBCA/B,eAAe,MAAM,SAAS;;;;;iBA+D9B,oBAAoB,UAAU;;;;;;;;;;cClDjC,WAAW"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/integration.ts","../src/define.ts","../src/index.ts"],"mappings":";;;;KAQY;;EAEV,UAAU;;;;;;;;;;;;;;wBAeY,oBAAoB,UAAS,6BAAkC;;;;;;;;;;;;;;;;;;;;;;wBCSvE,eAAe,GAAG,YAAY,mBAAmB,KAAK,SAAS;;;;;wBA6E/D,oBAAoB,UAAU;;;;;;;;;;qBC1EjC,WAAW"}

package/dist/index.js

@@ -1,12 +1,16 @@
-import { n as defineWormhole, t as assignWormholeNames } from "./define-BO-pYQc1.js";
+import { n as createWormhole, r as defineWormhole, t as assignWormholeNames } from "./define-DAoqsUVA.js";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { collectRouteIslands, routeEntrypoints, stripQuery } from "@astroscope/node/islands";
+import { serializeExcludePatterns } from "@astroscope/node/excludes";
 //#region src/extraction/vite-plugin.ts
 const WORMHOLE_VIRTUAL_MODULE_ID = "virtual:@astroscope/wormhole/manifest";
 const REGISTRY_VIRTUAL_MODULE_ID = "virtual:@astroscope/wormhole/registry";
+const CONFIG_VIRTUAL_MODULE_ID = "virtual:@astroscope/wormhole/config";
 const RESOLVED_VIRTUAL_MODULE_ID = `\0${WORMHOLE_VIRTUAL_MODULE_ID}`;
 const RESOLVED_REGISTRY_STUB_ID = `\0${REGISTRY_VIRTUAL_MODULE_ID}`;
+const RESOLVED_CONFIG_VIRTUAL_MODULE_ID = `\0${CONFIG_VIRTUAL_MODULE_ID}`;
 const MANIFEST_FILE_NAME = "wormhole-manifest.json";
 const SCAN_EXTENSIONS = [
 	".ts",
@@ -14,13 +18,17 @@ const SCAN_EXTENSIONS = [
 	".js",
 	".jsx"
 ];
+const SERVER_SCAN_EXTENSIONS = [...SCAN_EXTENSIONS, ".astro"];
 /** chunk file name → manifest key, e.g. `_astro/Counter.abc.js` → `Counter.abc` */
 function chunkFileNameToName(fileName) {
 	return fileName.slice(fileName.lastIndexOf("/") + 1).replace(/\.js$/, "");
 }
 function wormholeVitePlugin(options) {
 	let isBuild = false;
-	const moduleScans = /* @__PURE__ */ new Map();
+	const clientScans = /* @__PURE__ */ new Map();
+	const serverScans = /* @__PURE__ */ new Map();
+	const routeNames = /* @__PURE__ */ new Map();
+	const patternsByFile = /* @__PURE__ */ new Map();
 	return {
 		name: "@astroscope/wormhole/extract",
 		configResolved(config) {
@@ -28,10 +36,13 @@ function wormholeVitePlugin(options) {
 		},
 		resolveId(id) {
 			if (id === "virtual:@astroscope/wormhole/manifest") return RESOLVED_VIRTUAL_MODULE_ID;
+			if (id === "virtual:@astroscope/wormhole/config") return RESOLVED_CONFIG_VIRTUAL_MODULE_ID;
 			if (id === "virtual:@astroscope/wormhole/registry") return options.registryPath ?? RESOLVED_REGISTRY_STUB_ID;
 		},
 		load(id) {
 			if (id === RESOLVED_REGISTRY_STUB_ID) return "export const wormholes = {};";
+			if (id === RESOLVED_CONFIG_VIRTUAL_MODULE_ID) return `export const exclude = ${options.exclude ? serializeExcludePatterns(options.exclude) : "null"};`;
+			if (id === options.registryPath && this.environment?.name === "client") throw new Error(`[@astroscope/wormhole] ${path.relative(process.cwd(), id)} is server-only — client code reads wormholes through the \`wormholes\` proxy from '@astroscope/wormhole'`);
 			if (id !== RESOLVED_VIRTUAL_MODULE_ID) return;
 			if (!isBuild) return "export const manifest = null;";
 			return `
@@ -60,13 +71,37 @@ export { manifest };
 `;
 		},
 		async transform(code, id) {
-			if (!isBuild || this.environment && this.environment.name !== "client") return;
+			if (!isBuild || !this.environment) return;
 			if (id.includes("node_modules")) return;
-			if (!SCAN_EXTENSIONS.some((ext) => id.endsWith(ext))) return;
+			const client = this.environment.name === "client";
+			const extensions = client ? SCAN_EXTENSIONS : SERVER_SCAN_EXTENSIONS;
+			const file = extensions.some((ext) => id.endsWith(ext)) ? id : stripQuery(id);
+			if (extensions.every((ext) => !file.endsWith(ext))) return;
 			if (!code.includes("@astroscope/wormhole")) return;
-			const { scanWormholeAccess } = await import("./scan-4GXufA9_.js");
-			const scan = scanWormholeAccess(code, id);
-			if (scan) moduleScans.set(id, scan);
+			const { scanWormholeAccess } = await import("./scan-BDYo2M_0.js");
+			const scan = scanWormholeAccess(code, file);
+			if (scan) (client ? clientScans : serverScans).set(client ? id : stripQuery(id), scan);
+		},
+		async generateBundle() {
+			if (this.environment.name === "client") return;
+			const { routes, patternsByModule } = await collectRouteIslands(this, options.pages());
+			for (const pattern of routes.keys()) routeNames.set(pattern, routeNames.get(pattern) ?? /* @__PURE__ */ new Set());
+			for (const [id, patterns] of patternsByModule) {
+				const file = stripQuery(id);
+				let owners = patternsByFile.get(file);
+				if (!owners) {
+					owners = /* @__PURE__ */ new Set();
+					patternsByFile.set(file, owners);
+				}
+				patterns.forEach((pattern) => owners.add(pattern));
+				const scan = serverScans.get(file);
+				if (!scan) continue;
+				for (const pattern of patterns) {
+					const names = routeNames.get(pattern);
+					scan.names.forEach((name) => names.add(name));
+					if (scan.dynamic) names.add("*");
+				}
+			}
 		},
 		writeBundle(outputOptions, bundle) {
 			if (this.environment.name !== "client" || !outputOptions.dir) return;
@@ -79,7 +114,7 @@ export { manifest };
 				const names = /* @__PURE__ */ new Set();
 				let dynamic = false;
 				for (const moduleId of chunk.moduleIds) {
-					const scan = moduleScans.get(moduleId);
+					const scan = clientScans.get(moduleId);
 					scan?.names.forEach((name) => names.add(name));
 					dynamic ||= scan?.dynamic ?? false;
 				}
@@ -90,17 +125,30 @@ export { manifest };
 				if ((chunk.isEntry || chunk.isDynamicEntry) && chunk.facadeModuleId?.includes("astro&type=script")) scriptEntries.push(chunk.fileName);
 			}
 			const scriptNames = /* @__PURE__ */ new Set();
-			const visited = /* @__PURE__ */ new Set();
-			const walkScripts = (fileName) => {
-				if (visited.has(fileName)) return;
-				visited.add(fileName);
-				chunkNamesByFileName.get(fileName)?.forEach((name) => scriptNames.add(name));
-				chunkEdges.get(fileName)?.forEach(walkScripts);
-			};
-			scriptEntries.forEach(walkScripts);
+			for (const entry of scriptEntries) {
+				const names = /* @__PURE__ */ new Set();
+				const visited = /* @__PURE__ */ new Set();
+				const walk = (fileName) => {
+					if (visited.has(fileName)) return;
+					visited.add(fileName);
+					chunkNamesByFileName.get(fileName)?.forEach((name) => names.add(name));
+					chunkEdges.get(fileName)?.forEach((imported) => walk(imported));
+				};
+				walk(entry);
+				names.forEach((name) => scriptNames.add(name));
+				const owner = bundle[entry]?.type === "chunk" ? stripQuery(bundle[entry].facadeModuleId ?? "") : "";
+				const owners = patternsByFile.get(owner) ?? routeNames.keys();
+				for (const pattern of owners) {
+					const route = routeNames.get(pattern);
+					names.forEach((name) => route?.add(name));
+				}
+			}
+			const routes = {};
+			for (const [pattern, names] of routeNames) routes[pattern] = [...names];
 			const manifest = {
 				chunks,
-				scripts: [...scriptNames]
+				scripts: [...scriptNames],
+				routes
 			};
 			const chunksDir = path.resolve(outputOptions.dir, "..", "server", "chunks");
 			if (fs.existsSync(chunksDir)) fs.writeFileSync(path.join(chunksDir, MANIFEST_FILE_NAME), JSON.stringify(manifest));
@@ -111,22 +159,38 @@ export { manifest };
 //#endregion
 //#region src/integration.ts
 /**
-* Astro integration for wormholes with per-island payload slicing.
+* Astro integration for wormholes with per-route loading and per-island delivery.
 *
 * Resolves the `src/wormholes.ts` registry and exposes it to the middleware as a
-* virtual module, registers the vite plugin that scans client code for
-* `wormholes.<name>` accesses and maps them onto the emitted chunks, and generates
-* the registry type stub that types the `wormholes` proxy. Delivery happens at
-* runtime: the wormhole middleware opens per-request values, and the islands
-* emitter (via `@astroscope/node`) writes each island's slice before its tag.
+* virtual module, injects the middleware after the project's own (so handlers see
+* everything earlier middleware put on `locals`), registers the vite plugin that
+* scans server and client code for `wormholes.<name>` accesses and maps them onto
+* routes and chunks, and generates the registry type stub that types the
+* `wormholes` proxy. Delivery happens at runtime: the middleware runs the handlers
+* the route needs, and the islands emitter (via `@astroscope/node`) writes each
+* island's slice before its tag.
 */
-function wormholeIntegration() {
+function wormholeIntegration(options = {}) {
 	const resolveRegistryPath = (srcDir) => ["wormholes.ts", path.join("wormholes", "index.ts")].map((candidate) => path.join(fileURLToPath(srcDir), candidate)).find((candidate) => fs.existsSync(candidate)) ?? null;
+	let root = "";
+	let resolvedRoutes = [];
 	return {
 		name: "@astroscope/wormhole",
 		hooks: {
-			"astro:config:setup": ({ config, updateConfig }) => {
-				updateConfig({ vite: { plugins: [wormholeVitePlugin({ registryPath: resolveRegistryPath(config.srcDir) })] } });
+			"astro:config:setup": ({ config, updateConfig, addMiddleware }) => {
+				root = fileURLToPath(config.root);
+				addMiddleware({
+					order: "post",
+					entrypoint: "@astroscope/wormhole/middleware"
+				});
+				updateConfig({ vite: { plugins: [wormholeVitePlugin({
+					registryPath: resolveRegistryPath(config.srcDir),
+					exclude: options.exclude ?? null,
+					pages: () => routeEntrypoints(root, resolvedRoutes)
+				})] } });
+			},
+			"astro:routes:resolved": ({ routes }) => {
+				resolvedRoutes = routes;
 			},
 			"astro:config:done": ({ config, injectTypes, logger }) => {
 				const registryPath = resolveRegistryPath(config.srcDir);
@@ -154,7 +218,7 @@ const stubs = /* @__PURE__ */ new Map();
 function stub(name) {
 	let wormhole = stubs.get(name);
 	if (!wormhole) {
-		wormhole = defineWormhole();
+		wormhole = createWormhole();
 		assignWormholeNames({ [name]: wormhole });
 		stubs.set(name, wormhole);
 	}