@astroscope/wormhole 1.0.0 → 2.0.0

package/README.md

@@ -1,14 +1,14 @@
 # @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, 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.
+
+**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**.
 
 **Typical use cases:**
 
@@ -20,9 +20,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.** 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 })`.
+- **Prerendered pages get no wormhole data** — values are per-request by definition.
 
 ## Examples
 
@@ -34,72 +37,68 @@ 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 and generates a type stub from your registry, so `wormholes.<name>` is fully typed everywhere.
+
 ## 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 (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');
+export const wormholes = {
+  session: defineWormhole<Session>(),
+  cart: defineWormhole<{ items: string[] }>(),
+};
 ```
 
-### 2. Populate in middleware
+`src/wormholes/index.ts` works too.
 
-Use `open()` from the server entry point to provide data during request handling:
+### 2. Resolve values in middleware
 
 ```ts
 // src/middleware.ts
-import { open } from '@astroscope/wormhole/server';
-import { defineMiddleware } from 'astro:middleware';
-import { userState } from './wormholes';
+import { createWormholeMiddleware } from '@astroscope/wormhole/server';
 
-export const onRequest = defineMiddleware((ctx, next) => {
-  const data = { user: 'Alice', role: 'admin' };
-
-  return open(userState, data, () => next());
+export const onRequest = createWormholeMiddleware({
+  values: async (ctx) => ({
+    session: { user: 'Alice', role: 'admin' },
+    cart: await loadCart(ctx),
+  }),
 });
 ```
 
-`open()` uses `AsyncLocalStorage` under the hood — each request gets its own isolated data.
-
-### 3. Bridge to the client
+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.
 
-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
+### 3. 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 +107,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 +127,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
+### 4. 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,72 +167,41 @@ 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 `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                     |
 
-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                                                                       |
+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.
 
-### `DeepReadonly<T>`
+### `defineWormhole<T>()` <sub>registry only</sub>
 
-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:
+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.
 
-```ts
-import type { DeepReadonly } from '@astroscope/wormhole';
+### `createWormholeMiddleware({ values, exclude? })` <sub>server only</sub>
 
-function isWithinCart(cart: DeepReadonly<Cart>, id: string) {
-  return cart.items.some((item) => item.productId === id);
-}
-```
+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`).
 
-### `open(wh, data, fn)` <sub>server only</sub>
+### `openWormholes(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';
-
-return open(myWormhole, { count: 0 }, () => next());
-```
+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);
-```
-
-### `<WormholeScript wormhole={wh} />` <sub>Astro only</sub>
+### `DeepReadonly<T>` / `UnwrapWormholes<R>`
 
-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 types. `DeepReadonly<T>` is the recursively-readonly value type; `UnwrapWormholes` maps a registry shape to its value types.
 
 ## 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 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.
 
 ## License
 

package/dist/define-BO-pYQc1.js

@@ -0,0 +1,61 @@
+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");
+/**
+* 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()`).
+*
+* **Security:** wormhole data is serialized into the HTML and sent to the browser.
+* Never store secrets (tokens, API keys, credentials) in a wormhole.
+*/
+function defineWormhole() {
+	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;
+		}
+	};
+}
+/**
+* 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 { defineWormhole as n, als as r, assignWormholeNames as t };
+
+//# sourceMappingURL=define-BO-pYQc1.js.map

package/dist/define-BO-pYQc1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-BO-pYQc1.js","names":[],"sources":["../src/als.ts","../src/define.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","import { als } from './als.js';\nimport { wormholeKey } from './key.js';\nimport type { DeepReadonly, Wormhole } from './types.js';\n\n// name assignment must survive dual module instances (vite runner + native), so the\n// assigner rides the wormhole object itself under a Symbol.for key\nconst ASSIGN = Symbol.for('@astroscope/wormhole.assign');\n\n/**\n * Define a wormhole for the `src/wormholes.ts` registry. The wormhole's name is the\n * registry key — it is assigned when the registry is passed to\n * `createWormholeMiddleware()` (or `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 */\nexport function defineWormhole<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(): DeepReadonly<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 DeepReadonly<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/**\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":";;;AAIA,MAAa,MAAwD,WACnE,OAAO,IAAI,0BAA0B,OACjC,IAAI,kBAAkB;;;ACA5B,MAAM,SAAS,OAAO,IAAI,6BAA6B;;;;;;;;;AAUvD,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;;;;;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 WormholeRegistry, i as WormholeMap, n as UnwrapWormholes, r as Wormhole, t as DeepReadonly } from "./types-okMd-V3s.js";
+//#region src/index.browser.d.ts
+declare const wormholes: WormholeMap;
+declare function defineWormhole(): never;
+declare function assignWormholeNames(): never;
+declare function wormholeIntegration(): never;
+//#endregion
+export { type DeepReadonly, type UnwrapWormholes, type Wormhole, type WormholeMap, type WormholeRegistry, assignWormholeNames, wormholeIntegration as default, defineWormhole, wormholes };
+//# 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":";;cAiEa,WAAW;iBAMR;iBAMA;iBAIQ"}

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 { 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"}

package/dist/index.d.ts

@@ -1,13 +1,43 @@
-import { n as Wormhole, t as DeepReadonly } from "./types-0PQTD8gI.js";
-
+import { a as WormholeRegistry, i as WormholeMap, n as UnwrapWormholes, r as Wormhole, t as DeepReadonly } from "./types-okMd-V3s.js";
+import { AstroIntegration } from "astro";
+//#region src/integration.d.ts
+/**
+ * Astro integration for wormholes with per-island payload slicing.
+ *
+ * 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.
+ */
+declare function wormholeIntegration(): 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. The wormhole's name is the
+ * registry key — it is 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.
  */
-declare function defineWormhole<T>(name: string): Wormhole<T>;
+declare function defineWormhole<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;
+//#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 const wormholes: WormholeMap;
 //#endregion
-export { type DeepReadonly, type Wormhole, defineWormhole };
+export { type DeepReadonly, type UnwrapWormholes, type Wormhole, type WormholeMap, type WormholeRegistry, assignWormholeNames, wormholeIntegration as default, defineWormhole, wormholes };
 //# 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":";;;;;;;;;;;;;iBAgBwB,uBAAuB;;;;;;;;;;;iBCA/B,eAAe,MAAM,SAAS;;;;;iBA+D9B,oBAAoB,UAAU;;;;;;;;;;cClDjC,WAAW"}