@astroscope/wormhole 1.1.0 → 3.0.0

package/README.md

@@ -1,14 +1,16 @@
 # @astroscope/wormhole
 
-> **Note:** This package is in active development. APIs may change between versions.
-
-Share dynamic server data with React islands and client scripts — typed, reactive.
+Share dynamic server data with React islands and client scripts — typed, streamed with the HTML, sliced per island.
 
 ## Why this library?
 
 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: populate data in middleware, read it in Astro frontmatter, React islands, or `<script>` blocks — same typed API on server and client. Multiple wormholes per page, reactive updates across all consumers, zero configuration.
+`@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.
+
+**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,9 +22,12 @@ Astro recommends [nanostores](https://docs.astro.build/en/recipes/sharing-state/
 
 ## Important notes
 
-- **No secrets in wormholes.** All wormhole data is serialized into an inline `<script>` tag and sent to the browser. Never store tokens, API keys, credentials, or any sensitive data in a wormhole.
-- **`set()` is client-only.** Calling `set()` does not work on the server. Use `open(wormhole, data, fn)` from `@astroscope/wormhole/server` to populate data in middleware.
-- **Values are deeply readonly.** `get()`, `subscribe()` and `useWormhole()` expose the value as `DeepReadonly<T>` — in-place mutation would silently bypass subscribers (and on the server would corrupt the request-scoped store). The only way to update is `set()` with a new value: `wh.set({ ...wh.get(), count: 1 })`.
+- **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.** 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
 
@@ -34,72 +39,56 @@ See the [demo/wormhole](../../demo/wormhole) directory for a working example.
 npm install @astroscope/wormhole
 ```
 
+```ts
+// astro.config.ts
+import node from '@astroscope/node';
+import wormhole from '@astroscope/wormhole';
+
+export default defineConfig({
+  output: 'server',
+  adapter: node(),
+  integrations: [wormhole()],
+});
+```
+
+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 a wormhole
+### 1. Define the registry
 
-Create a shared file imported by both server and client code:
+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
 import { defineWormhole } from '@astroscope/wormhole';
 
-export type UserState = {
+export type Session = {
   user: string;
   role: string;
 };
 
-export const userState = defineWormhole<UserState>('user');
-```
-
-### 2. Populate in middleware
-
-Use `open()` from the server entry point to provide data during request handling:
-
-```ts
-// src/middleware.ts
-import { open } from '@astroscope/wormhole/server';
-import { defineMiddleware } from 'astro:middleware';
-import { userState } from './wormholes';
-
-export const onRequest = defineMiddleware((ctx, next) => {
-  const data = { user: 'Alice', role: 'admin' };
-
-  return open(userState, data, () => next());
-});
+export const wormholes = {
+  session: defineWormhole({
+    handler: (ctx): Session => ({ user: ctx.locals.user, role: ctx.locals.role }),
+  }),
+  cart: defineWormhole({
+    handler: async (ctx) => loadCart(ctx),
+  }),
+};
 ```
 
-`open()` uses `AsyncLocalStorage` under the hood — each request gets its own isolated data.
-
-### 3. Bridge to the client
+`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.
 
-Add `<WormholeScript>` to your layout to serialize the data into an inline script:
-
-```astro
----
-import { WormholeScript } from '@astroscope/wormhole/astro';
-import { userState } from '../wormholes';
----
-
-<html>
-  <head>
-    <WormholeScript wormhole={userState} />
-  </head>
-  <body>
-    <slot />
-  </body>
-</html>
-```
-
-### 4. Read in components
+### 2. Read anywhere
 
 #### Astro frontmatter (SSR)
 
 ```astro
 ---
-import { userState } from '../wormholes';
+import { wormholes } from '@astroscope/wormhole';
 
-const { user } = userState.get();
+const { user } = wormholes.session.get();
 ---
 
 <p>Hello, {user}</p>
@@ -108,11 +97,11 @@ const { user } = userState.get();
 #### React islands
 
 ```tsx
+import { wormholes } from '@astroscope/wormhole';
 import { useWormhole } from '@astroscope/wormhole/react';
-import { userState } from '../wormholes';
 
 export function UserBadge() {
-  const { user, role } = useWormhole(userState);
+  const { user, role } = useWormhole(wormholes.session);
 
   return (
     <span>
@@ -128,34 +117,33 @@ export function UserBadge() {
 <p>User: <strong id="user">-</strong></p>
 
 <script>
-  import { userState } from '../wormholes';
+  import { wormholes } from '@astroscope/wormhole';
 
-  document.getElementById('user')!.textContent = userState.get().user;
+  document.getElementById('user')!.textContent = wormholes.session.get().user;
 
-  userState.subscribe((data) => {
+  wormholes.session.subscribe((data) => {
     document.getElementById('user')!.textContent = data.user;
   });
 </script>
 ```
 
-### 5. Update from the client
+### 3. Update from the client
 
-Call `set()` to update the wormhole — all `useWormhole()` hooks and `subscribe()` callbacks react immediately:
+Call `set()` to update the wormhole — every `useWormhole()` hook and `subscribe()` callback on the page reacts, across islands:
 
 ```tsx
+import { wormholes } from '@astroscope/wormhole';
 import { useWormhole } from '@astroscope/wormhole/react';
 import { actions } from 'astro:actions';
-import { userState } from '../wormholes';
 
 export function RoleToggle() {
-  const { user, role } = useWormhole(userState);
+  const { user, role } = useWormhole(wormholes.session);
 
   async function toggle() {
-    const newRole = role === 'admin' ? 'viewer' : 'admin';
-    const result = await actions.updateRole({ role: newRole });
+    const result = await actions.updateRole({ role: role === 'admin' ? 'viewer' : 'admin' });
 
     if (!result.error) {
-      userState.set(result.data);
+      wormholes.session.set(result.data);
     }
   }
 
@@ -169,83 +157,39 @@ export function RoleToggle() {
 
 ## API
 
-### `defineWormhole<T>(name)`
+### `wormholes` <sub>proxy, server + client</sub>
 
-Creates a typed wormhole channel. The returned object is universal — works on both server and client.
+The single access point, typed from your registry. `wormholes.cart` returns a `Wormhole<T>`:
 
-```ts
-import { defineWormhole } from '@astroscope/wormhole';
+| 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                                |
 
-const wh = defineWormhole<{ count: number }>('counter');
-```
-
-| Method             | Description                                                                                         |
-| ------------------ | --------------------------------------------------------------------------------------------------- |
-| `wh.get()`         | Read current value as `DeepReadonly<T>` (from `AsyncLocalStorage` on server, from `globalThis` or local store on client) |
-| `wh.set(data)`     | Replace value with a new one and notify all subscribers (client-side)                               |
-| `wh.subscribe(fn)` | Listen for changes, returns unsubscribe function                                                    |
-| `wh.name`          | The wormhole name                                                                                   |
-| `wh.key`           | The internal `globalThis` key                                                                       |
-
-### `DeepReadonly<T>`
-
-Exported helper type — recursively `readonly` version of `T`. Wormhole values are exposed with this type; use it in your own function signatures when passing wormhole data around:
-
-```ts
-import type { DeepReadonly } from '@astroscope/wormhole';
-
-function isWithinCart(cart: DeepReadonly<Cart>, id: string) {
-  return cart.items.some((item) => item.productId === id);
-}
-```
-
-### `open(wh, data, fn)` <sub>server only</sub>
-
-Runs `fn` with `data` available via `wh.get()` for the duration of the call. Uses `AsyncLocalStorage` for request isolation.
-
-```ts
-import { open } from '@astroscope/wormhole/server';
+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.
 
-return open(myWormhole, { count: 0 }, () => next());
-```
+### `defineWormhole({ handler, eager? })` <sub>registry only</sub>
 
-To open several wormholes at once, pass an array of `[wormhole, data]` pairs — each pair is type-checked against its own wormhole:
+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.
 
-```ts
-return open([
-  [cartStore, cart],
-  [sessionStore, session],
-], () => next());
-```
+### `openWormholes(wh, data, fn)` <sub>server only</sub>
 
-Nested `open()` calls shadow only the wormholes they name; everything else stays visible.
+Provides values to server code that runs outside the request pipeline — tests, out-of-request rendering. Never delivered to the client; inside the app, the middleware is the way. Accepts a single pair or an array of `[wormhole, data]` pairs.
 
 ### `useWormhole(wh)` <sub>React only</sub>
 
-React hook that reads the wormhole and re-renders on changes. Uses `useSyncExternalStore` internally.
+React hook that reads a wormhole and re-renders on `set()`. During SSR it reads the request scope, so server and client render identically.
 
-```tsx
-import { useWormhole } from '@astroscope/wormhole/react';
-
-const data = useWormhole(myWormhole);
-```
+### `UnwrapWormholes<R>`
 
-### `<WormholeScript wormhole={wh} />` <sub>Astro only</sub>
-
-Serializes the current wormhole value into an inline `<script>` tag for client hydration.
-
-```astro
-import {WormholeScript} from '@astroscope/wormhole/astro';
-
-<WormholeScript wormhole={myWormhole} />
-```
+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
 
-1. **Middleware** calls `open(wh, data, next)` — stores data in `AsyncLocalStorage` and sets `globalThis[key]` to read from it
-2. **`<WormholeScript>`** calls `wh.get()` during SSR, serializes the result into `<script is:inline>globalThis[key] = function(){return data;}</script>`
-3. **Client** calls `wh.get()` — reads from `globalThis[key]()` (the serialized getter)
-4. **`set()`** updates a local store and notifies all subscribers — `useWormhole()` hooks and `subscribe()` callbacks re-render/fire
+At build time the integration scans the code for `wormholes.<name>` reads: server modules are attributed to the routes whose page or endpoint reaches them, client modules to the emitted chunks. It also generates the types for the `wormholes` proxy from your registry. At runtime the middleware runs, in parallel, the handlers of everything the request's route can reach — frontmatter and endpoint reads, the islands the page hydrates (via `@astroscope/node`'s route map), its `<script>` blocks — 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. 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\nexport const als: AsyncLocalStorage<ReadonlyMap<string, unknown>> = ((globalThis as any)[\n  Symbol.for('@astroscope/wormhole/als')\n] ??= new AsyncLocalStorage());\n"],"mappings":";;AAIA,MAAa,MAAwD,WACnE,OAAO,IAAI,0BAA0B,OACjC,IAAI,kBAAkB"}

package/dist/define-1UkPnsXV.js

@@ -0,0 +1,83 @@
+import { t as als } from "./als-CntRqWdO.js";
+import { t as wormholeKey } from "./key-BqTy1gM3.js";
+//#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, 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(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()");
+		return name;
+	};
+	const key = () => wormholeKey(requireName());
+	return {
+		get name() {
+			return requireName();
+		},
+		get key() {
+			return key();
+		},
+		get() {
+			const value = als.getStore()?.get(key());
+			if (value === void 0) throw new Error(`wormhole "${requireName()}" is not open for this request — is it provided by the wormhole middleware?`);
+			return value;
+		},
+		set() {
+			throw new Error(`wormhole "${requireName()}" set() cannot be called on the server — values are request-scoped and provided by the middleware`);
+		},
+		subscribe() {
+			return () => {};
+		},
+		[ASSIGN](next) {
+			if (name !== void 0 && name !== next) throw new Error(`wormhole is registered under two names: "${name}" and "${next}"`);
+			name = next;
+		}
+	};
+}
+/** 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.
+*/
+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`);
+		assign(name);
+	}
+}
+//#endregion
+export { getWormholeSource as i, createWormhole as n, defineWormhole as r, assignWormholeNames as t };
+
+//# sourceMappingURL=define-1UkPnsXV.js.map

package/dist/define-1UkPnsXV.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-1UkPnsXV.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 Error(\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,MACR,mBAAmB,KAAK,6EAC1B;EAGF,OAAO,IAAI;CACb;AACF"}

package/dist/index.browser.d.ts

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

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

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

package/dist/index.browser.js

@@ -0,0 +1,48 @@
+import { t as wormholeKey } from "./key-BqTy1gM3.js";
+//#region src/index.browser.ts
+const store = globalThis.__wormholes__ ??= {};
+const stubs = /* @__PURE__ */ new Map();
+function stub(name) {
+	let wormhole = stubs.get(name);
+	if (wormhole) return wormhole;
+	const entry = () => store[name] ??= {};
+	wormhole = {
+		name,
+		key: wormholeKey(name),
+		get() {
+			const value = entry().v;
+			if (value === void 0) throw new Error(`wormhole "${name}" has no data — is it provided by the wormhole middleware?`);
+			return value;
+		},
+		set(data) {
+			const current = entry();
+			current.v = data;
+			current.l?.forEach((fn) => fn(data));
+		},
+		subscribe(fn) {
+			const current = entry();
+			(current.l ??= []).push(fn);
+			return () => {
+				current.l = current.l?.filter((listener) => listener !== fn);
+			};
+		}
+	};
+	stubs.set(name, wormhole);
+	return wormhole;
+}
+const wormholes = new Proxy({}, { get(_target, prop) {
+	return typeof prop === "string" ? stub(prop) : void 0;
+} });
+function defineWormhole() {
+	throw new Error("defineWormhole() is server-only — do not import the wormhole registry in client code; access wormholes via the `wormholes` proxy instead");
+}
+function assignWormholeNames() {
+	throw new Error("assignWormholeNames() is server-only");
+}
+function wormholeIntegration() {
+	throw new Error("the @astroscope/wormhole integration is server-only");
+}
+//#endregion
+export { assignWormholeNames, wormholeIntegration as default, defineWormhole, wormholes };
+
+//# sourceMappingURL=index.browser.js.map

package/dist/index.browser.js.map

@@ -0,0 +1 @@
+{"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\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":";;AAuBA,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,13 +1,61 @@
-import { n as Wormhole, t as DeepReadonly } from "./types-Q2gaO_N_.js";
-
+import { a as WormholeMap, i as WormholeHandler, n as Wormhole, o as WormholeRegistry, r as WormholeDefinition, t as UnwrapWormholes } from "./types-DiWa8aQg.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-route loading and per-island delivery.
+ *
+ * Resolves the `src/wormholes.ts` registry and exposes it to the middleware as a
+ * 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.
+ */
+export default function wormholeIntegration(options?: WormholeIntegrationOptions): AstroIntegration;
+//#endregion
 //#region src/define.d.ts
 /**
- * Define a wormhole that transfers state from server middleware to client components.
+ * 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 }),
+ * };
+ * ```
+ */
+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.
+ */
+export declare function assignWormholeNames(registry: Record<string, object>): void;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Access wormholes by name — `wormholes.cart.get()`. This is the server side of the
+ * proxy (the browser build ships its own): values come from the request's
+ * wormhole middleware scope, so it works in frontmatter, endpoints, and
+ * server-rendered islands alike. Typed via the registry type stub the integration
+ * generates from `src/wormholes.ts`.
  */
-declare function defineWormhole<T>(name: string): Wormhole<T>;
+export declare const wormholes: WormholeMap;
 //#endregion
-export { type DeepReadonly, type Wormhole, defineWormhole };
+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/define.ts"],"mappings":";;;;;AAQA;;;;iBAAgB,cAAA,IAAkB,IAAA,WAAe,QAAQ,CAAC,CAAA"}
+{"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"}