devframe 0.9.4 → 0.9.6

package/dist/constants.mjs

@@ -1,4 +1,4 @@
-import { t as DEVFRAME_EVENTS } from "./events-DKfSmoTj.mjs";
+import { t as DEVFRAME_EVENTS } from "./events-4daw0uK9.mjs";
 //#region src/constants.ts
 const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**

package/dist/{context-_i51nYOs.d.mts → context-BhBzOXVa.d.mts}

@@ -1,7 +1,7 @@
-import { d as RpcFunctionsCollectorBase } from "./index-DOg4S5wk.mjs";
-import { _ as RpcFunctionDefinition, v as RpcFunctionDefinitionAny } from "./types-BBLeGfpt.mjs";
-import { d as DevframeRpcConnection, u as DevframeNodeRpcSessionMeta } from "./ws-server-DLtEoLdR.mjs";
-import { a as RemoteAssetsStore, o as StaticAssetsSource } from "./remote-assets-Bg4gCUZ_.mjs";
+import { d as RpcFunctionsCollectorBase } from "./index-BzyopqxV.mjs";
+import { _ as RpcFunctionDefinition, v as RpcFunctionDefinitionAny } from "./types-CMdPYhOx.mjs";
+import { d as DevframeRpcConnection, u as DevframeNodeRpcSessionMeta } from "./ws-server-Di2oqr4q.mjs";
+import { a as RemoteAssetsStore, o as StaticAssetsSource } from "./remote-assets-B13_vRkJ.mjs";
 import { m as defineDiagnostics } from "./nostics-SPGDgHEP.mjs";
 import { BirpcReturn } from "birpc";
 import { StandardSchemaV1 } from "@standard-schema/spec";
@@ -444,8 +444,8 @@ interface DevframeHost {
    * for cross-origin or sandboxed iframes. Implementations serve the same
    * meta they expose at the hub's own base.
    *
-   * Optional in the type, but a host that mounts a devframe with a servable
-   * `distDir` yet omits this hook triggers a `DF8106` diagnostic, since the
+   * Optional in the type, but a host that mounts a devframe with servable
+   * `clientAssets` yet omits this hook triggers a `DF8106` diagnostic, since the
    * SPA's `./__connection.json` fetch would otherwise fall through and break
    * silently. A static-snapshot host that bakes the meta into its served files
    * can implement it as a no-op to acknowledge this intentionally.
@@ -1234,10 +1234,11 @@ interface DevframeCliOptions {
    */
   mcp?: boolean | McpRouteOptions;
   /**
-   * Author's SPA dist — served as the devframe's UI. A local directory, or
-   * a {@link StaticAssetsSource} remote declaration (`{ package, version }`)
-   * served through devframe's caching CDN back-proxy so the assets need not
-   * ship inside the node package.
+   * Author's SPA dist — served as the devframe's UI.
+   *
+   * @deprecated Moved to the top-level {@link DevframeDefinition.clientAssets}.
+   * Set `clientAssets` on the definition instead. This field is still read as a
+   * fallback when `clientAssets` is unset, so existing definitions keep working.
    */
   distDir?: StaticAssetsSource;
   /**
@@ -1357,7 +1358,7 @@ interface DevframeDefinition {
    * consuming app's.
    *
    * - **Remote assets** — becomes the default `resolveFrom` for any remote
-   *   {@link StaticAssetsSource} the devframe hosts (its `cli.distDir`, and
+   *   {@link StaticAssetsSource} the devframe hosts (its `clientAssets`, and
    *   every `ctx.views.hostStatic` call) that doesn't set one explicitly, so a
    *   locally installed copy of the assets package is served with zero
    *   network. A per-asset `resolveFrom` still wins, and an explicit
@@ -1434,6 +1435,17 @@ interface DevframeDefinition {
    * `client.services.has(pkg)` and degrade.
    */
   services?: DevframeServiceInput[];
+  /**
+   * Author's SPA dist — served as the devframe's UI. A local directory, or
+   * a {@link StaticAssetsSource} remote declaration (`{ package, version }`)
+   * served through devframe's caching CDN back-proxy so the assets need not
+   * ship inside the node package.
+   *
+   * Consumed by every adapter that serves the UI (`dev`, `build`, `vite`,
+   * `next`, and the hub install path). When unset, the deprecated
+   * {@link DevframeCliOptions.distDir} is read as a fallback.
+   */
+  clientAssets?: StaticAssetsSource;
   /** RPC-level configuration for this devframe (see {@link DevframeRpcOptions}). */
   rpc?: DevframeRpcOptions;
   /** Server-side setup — the primary entrypoint. Runs in every runtime. */

package/dist/{context-CO7eZHJy.d.mts → context-HOnG-WvG.d.mts}

@@ -1,4 +1,4 @@
-import { k as SharedState, o as DevframeNodeContext } from "./context-_i51nYOs.mjs";
+import { k as SharedState, o as DevframeNodeContext } from "./context-BhBzOXVa.mjs";
 //#region src/node/hub-internals/context.d.ts
 interface InternalAnonymousAuthStorage {
   trusted: Record<string, {

package/dist/{context-BUJGvlje.mjs → context-KUqAfawQ.mjs}

@@ -1,6 +1,6 @@
 import { n as randomToken } from "./crypto-token-XCqTSMg9.mjs";
 import { t as createStorage } from "./storage-BXNVhKyR.mjs";
-import { n as revokeAuthToken, t as revokeActiveConnectionsForToken } from "./revoke-3Q6aDKWk.mjs";
+import { n as revokeAuthToken, t as revokeActiveConnectionsForToken } from "./revoke-COLW0cOi.mjs";
 import { join } from "pathe";
 //#region src/node/hub-internals/context.ts
 const internalContextMap = /* @__PURE__ */ new WeakMap();

package/dist/{context-CQW0lSw8.mjs → context-omlma_1n.mjs}

@@ -2,17 +2,15 @@ import { i as defineDiagnostics } from "./nostics-CzECRXpE.mjs";
 import { t as diagnostics } from "./diagnostics-CD8nlgll.mjs";
 import { RpcFunctionsCollectorBase } from "./rpc/index.mjs";
 import { defineRpcFunction } from "./index.mjs";
-import { t as DEVFRAME_EVENTS } from "./events-DKfSmoTj.mjs";
+import { t as DEVFRAME_EVENTS } from "./events-4daw0uK9.mjs";
 import { DEVFRAME_SERVICES_STATE_KEY } from "./constants.mjs";
 import { t as diagnostics$1 } from "./diagnostics-BXWW3VK-.mjs";
-import { r as createEventEmitter, t as DevframeAgentHost } from "./host-agent-B84av916.mjs";
+import { a as DevframeAgentHost, i as satisfiesVersionRange, n as expandResolveFrom, r as importServicePackage, s as createEventEmitter, t as deepMergeOptionSets } from "./services-install-CqqQVls5.mjs";
 import { n as createDebug, t as resolveStaticAssetsSource } from "./remote-assets-DezQmPQU.mjs";
 import { t as createStorage } from "./storage-BXNVhKyR.mjs";
-import { createRequire } from "node:module";
 import { createSharedState } from "devframe/utils/shared-state";
 import process from "node:process";
-import { pathToFileURL } from "node:url";
-import { isAbsolute, join } from "pathe";
+import { join } from "pathe";
 import { existsSync } from "node:fs";
 //#region src/node/host-diagnostics.ts
 var DevframeDiagnosticsHost = class {
@@ -763,151 +761,6 @@ var RpcFunctionsHostImpl = class extends RpcFunctionsCollectorBase {
 	}
 };
 //#endregion
-//#region src/node/services-install.ts
-/**
-* Turn a `resolveFrom` value (a file path, a file URL like `import.meta.url`,
-* or a directory) into something `createRequire` accepts — a directory gets a
-* synthetic filename appended so resolution starts inside it.
-*/
-function toRequireBase(resolveFrom) {
-	if (resolveFrom.startsWith("file://")) return resolveFrom;
-	if ((resolveFrom.split(/[/\\]/).pop() ?? "").includes(".")) return resolveFrom;
-	return join(resolveFrom, "_devframe_resolve.js");
-}
-/**
-* Normalize an `install()` `resolveFrom` into a resolution base. Paths and
-* file URLs pass through (the common case: the declaring plugin's
-* `importMetaUrl`, so a service it declares resolves against the plugin's own
-* dependencies); a bare npm package name resolves to that package's location
-* from `cwd`. An unresolvable package name reads as no base (the caller's
-* workspace fallbacks apply).
-*/
-function expandResolveFrom(resolveFrom, cwd) {
-	if (resolveFrom.startsWith("file://") || resolveFrom.startsWith(".") || isAbsolute(resolveFrom)) return resolveFrom;
-	const require = createRequire(join(cwd, "_devframe_resolve.js"));
-	try {
-		return require.resolve(`${resolveFrom}/package.json`);
-	} catch {}
-	try {
-		return require.resolve(resolveFrom);
-	} catch {}
-}
-/**
-* Import a service package's module, trying each `resolveFrom` candidate in
-* order (so a plugin-declared service resolves against the plugin's own
-* dependency tree first, then the workspace fallback). Throws the last
-* resolution error when no candidate succeeds.
-*/
-async function importServicePackage(pkg, resolveFroms) {
-	const candidates = [...new Set(resolveFroms.filter((x) => typeof x === "string" && x.length > 0))];
-	let lastError = /* @__PURE__ */ new Error(`no resolution base available for "${pkg}"`);
-	for (const from of candidates) {
-		let resolved;
-		try {
-			resolved = createRequire(toRequireBase(from)).resolve(pkg);
-		} catch (error) {
-			lastError = error;
-			continue;
-		}
-		return await import(
-			/* webpackIgnore: true */
-			/* @vite-ignore */
-			/* turbopackIgnore: true */
-			pathToFileURL(resolved).href
-);
-	}
-	throw lastError;
-}
-function parseVersion(input) {
-	const [core, ...prerelease] = input.trim().replace(/^v/, "").split("-");
-	if (!core) return void 0;
-	const parts = core.split(".").map((part) => Number.parseInt(part, 10));
-	if (parts.length === 0 || parts.some((part) => Number.isNaN(part) || part < 0)) return void 0;
-	while (parts.length < 3) parts.push(0);
-	return {
-		parts,
-		...prerelease.length ? { prerelease: prerelease.join("-") } : {}
-	};
-}
-function compareVersions(a, b) {
-	for (let i = 0; i < 3; i++) {
-		const diff = (a.parts[i] ?? 0) - (b.parts[i] ?? 0);
-		if (diff !== 0) return diff;
-	}
-	if (a.prerelease && !b.prerelease) return -1;
-	if (!a.prerelease && b.prerelease) return 1;
-	if (a.prerelease && b.prerelease) return a.prerelease < b.prerelease ? -1 : a.prerelease > b.prerelease ? 1 : 0;
-	return 0;
-}
-function satisfiesComparator(version, comparator) {
-	const raw = comparator.trim();
-	if (!raw || raw === "*" || raw === "x") return true;
-	const operatorMatch = raw.match(/^([\^~]|>=|<=|[><=])?(.+)$/);
-	if (!operatorMatch) return false;
-	const operator = operatorMatch[1];
-	const rest = operatorMatch[2].trim();
-	const segments = rest.replace(/\.[x*]/gi, "").split(".").filter(Boolean);
-	const base = parseVersion(rest.replace(/[x*]/gi, "0"));
-	if (!base) return false;
-	switch (operator) {
-		case ">": return compareVersions(version, base) > 0;
-		case ">=": return compareVersions(version, base) >= 0;
-		case "<": return compareVersions(version, base) < 0;
-		case "<=": return compareVersions(version, base) <= 0;
-		case "^": {
-			if (compareVersions(version, base) < 0) return false;
-			const fixedIndex = base.parts.findIndex((part) => part !== 0);
-			const lockUpTo = fixedIndex === -1 ? base.parts.length - 1 : fixedIndex;
-			for (let i = 0; i <= lockUpTo; i++) if ((version.parts[i] ?? 0) !== (base.parts[i] ?? 0)) return false;
-			return true;
-		}
-		case "~": {
-			if (compareVersions(version, base) < 0) return false;
-			const lockUpTo = segments.length >= 2 ? 1 : 0;
-			for (let i = 0; i <= lockUpTo; i++) if ((version.parts[i] ?? 0) !== (base.parts[i] ?? 0)) return false;
-			return true;
-		}
-		default:
-			for (let i = 0; i < Math.max(segments.length, 3); i++) if (i < segments.length && (version.parts[i] ?? 0) !== (base.parts[i] ?? 0)) return false;
-			return segments.length >= 3 ? compareVersions(version, base) === 0 : true;
-	}
-}
-/**
-* Pragmatic semver range check for service version declarations — supports
-* the common forms (`1.2.3`, `^1.2.3`, `~1.2`, `>=1 <3`, `1.x`, `*`, and
-* `||`-joined alternatives) without pulling in a semver dependency. An
-* unparseable version or range reads as **not satisfied**.
-*/
-function satisfiesVersionRange(version, range) {
-	const parsed = parseVersion(version);
-	if (!parsed) return false;
-	const alternatives = range.split("||").map((alt) => alt.trim()).filter(Boolean);
-	if (alternatives.length === 0) return true;
-	return alternatives.some((alternative) => alternative.split(/\s+/).every((comparator) => satisfiesComparator(parsed, comparator)));
-}
-function isPlainObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** Deep-merge two values with the service option-set rules (see below). */
-function deepMergeTwo(a, b) {
-	if (Array.isArray(a) && Array.isArray(b)) return [.../* @__PURE__ */ new Set([...a, ...b])];
-	if (isPlainObject(a) && isPlainObject(b)) {
-		const out = { ...a };
-		for (const key of Object.keys(b)) out[key] = key in a ? deepMergeTwo(a[key], b[key]) : b[key];
-		return out;
-	}
-	return b;
-}
-/**
-* Default option-set merge when a service declares no `mergeOptions`:
-* deep-merge in declaration order — objects recurse, arrays union-dedupe,
-* scalars take the later value. Covers the built-in services (`roots` /
-* `langs` union, `themes` per-key last-wins) without a custom hook.
-*/
-function deepMergeOptionSets(sets) {
-	return sets.reduce((merged, set) => deepMergeTwo(merged, set));
-}
-//#endregion
 //#region src/node/host-services.ts
 const debug = createDebug("devframe:services");
 function isServiceDefinition(input) {

package/dist/{dev-lpIvwagf.mjs → dev-Czit5IP4.mjs}

@@ -1,10 +1,11 @@
+import { resolveClientAssets } from "./index.mjs";
 import { DEVFRAME_CONNECTION_META_FILENAME } from "./constants.mjs";
 import { t as diagnostics } from "./diagnostics-BXWW3VK-.mjs";
-import { t as createHostContext } from "./context-CQW0lSw8.mjs";
+import { t as createHostContext } from "./context-omlma_1n.mjs";
 import { t as resolveStaticAssetsSource } from "./remote-assets-DezQmPQU.mjs";
 import { i as resolveMcpConnectionMeta, n as resolveBasePath, r as resolveDevServerPort, t as normalizeBasePath } from "./_shared-BM3PdYli.mjs";
 import { t as createH3DevframeHost } from "./host-h3-fRbF9yor.mjs";
-import { i as normalizeHttpServerUrl, n as resolveInstanceRegister, t as createInstanceShell } from "./instance-shell-B-uevnK-.mjs";
+import { a as importRuntimeModule, i as normalizeHttpServerUrl, n as resolveInstanceRegister, t as createInstanceShell } from "./instance-shell-CpVW4zG0.mjs";
 import { open } from "./utils/open.mjs";
 import { mountStaticHandler } from "./utils/serve-static.mjs";
 import { createServer } from "node:http";
@@ -37,7 +38,7 @@ function getInstanceInternals(handler) {
 */
 function initDevframe(def, options) {
 	const base = normalizeBasePath(options.base);
-	const distDir = options.distDir === false ? void 0 : options.distDir ?? def.cli?.distDir;
+	const distDir = options.distDir === false ? void 0 : options.distDir ?? resolveClientAssets(def);
 	const app = options.app ?? new H3();
 	const host = options.host ?? def.cli?.host ?? "localhost";
 	const shell = createInstanceShell({
@@ -91,7 +92,7 @@ function initDevframe(def, options) {
 				const mcpPath = joinURL(base, mcpMeta.path);
 				let mountMcpHttp;
 				try {
-					({mountMcpHttp} = await import("./http-BKiqHcXX.mjs").then((n) => n.t));
+					({mountMcpHttp} = await importRuntimeModule("devframe/adapters/mcp"));
 				} catch (error) {
 					const reason = error instanceof Error ? error.message : String(error);
 					throw diagnostics.DF0017({
@@ -142,7 +143,7 @@ function initDevframe(def, options) {
 * h3 + WebSocket RPC + (optionally) the author's SPA mounted at the
 * resolved base path.
 *
-* When `distDir` is omitted (and `def.cli?.distDir` is unset) the
+* When `distDir` is omitted (and the definition's client assets are unset) the
 * server runs in **bridge mode**: only `__connection.json` and the WS
 * endpoint are mounted, with no SPA mount. The SPA is expected to be
 * hosted elsewhere (e.g. by a parent Vite/Nuxt dev server) — see

package/dist/{events-DKfSmoTj.mjs → events-4daw0uK9.mjs}

@@ -5,7 +5,7 @@
 * broadcast notifications — so these names live in one place instead of
 * scattered string literals.
 *
-* **Keep this in sync with [`docs/guide/events.md`](../../../docs/guide/events.md)**
+* **Keep this in sync with [`docs/content/8.references/3.events.md`](../../../docs/content/8.references/3.events.md)**
 * (the "Core devframe events" section): every name here appears in that page's
 * tables, and every name there resolves to an entry here. Add, rename, or
 * remove a name in both places in the same change, and reference
@@ -58,8 +58,22 @@ const DEVFRAME_EVENTS = {
 		streamingEnd: "devframe:streaming:end",
 		streamingUploadCancel: "devframe:streaming:upload-cancel"
 	},
+	/**
+	* In-page channel notifications the page script pushes to its panels
+	* (page script → panel), `devframe:` prefix. The paired request methods
+	* (`devframe:in-page:page-state:subscribe`/`set`/`patch`) are call
+	* endpoints, not events, and are defined at their handlers
+	* (`in-page-channel/state.ts`).
+	*/
+	inPageChannel: {
+		panelStateUpdated: "devframe:in-page:panel-state:updated",
+		panelStatePatch: "devframe:in-page:panel-state:patch"
+	},
 	/** `postMessage` channels the runtime posts across window boundaries. */
-	postMessage: { remoteAssetsError: "devframe:remote-assets-error" }
+	postMessage: {
+		remoteAssetsError: "devframe:remote-assets-error",
+		inPageChannel: "devframe:in-page-channel"
+	}
 };
 //#endregion
 export { DEVFRAME_EVENTS as t };

package/dist/in-page-channel/index.d.mts

@@ -0,0 +1,306 @@
+import { D as InferArgsType, E as Thenable, O as InferReturnType, T as RpcReturnSchema, i as RpcArgsSchema } from "../types-CMdPYhOx.mjs";
+import { k as SharedState, zt as EventEmitter } from "../context-BhBzOXVa.mjs";
+import { BirpcReturn } from "birpc";
+//#region src/in-page-channel/types.d.ts
+/**
+ * The shared contract of one in-page channel, declared once (usually in a
+ * `shared/protocol.ts` both sides import) and passed to both endpoints as a
+ * type parameter. Purely a type — the only runtime companion is the
+ * channel-name constant declared next to it.
+ */
+interface InPageChannelProtocol {
+  /** Functions implemented by the page script, callable by panels. */
+  pageScript?: Record<string, (...args: any[]) => any>;
+  /** Functions implemented by panels, callable by the page script. */
+  panel?: Record<string, (...args: any[]) => any>;
+  /**
+   * Shared-state slots. The page script is the authority: it owns the
+   * canonical value; panels are seeded on connect and converge through
+   * syncId-deduplicated patches.
+   */
+  sharedStates?: Record<string, object>;
+}
+type SideFunctions<S> = S extends Record<string, (...args: any[]) => any> ? S : Record<string, never>;
+type PageScriptFunctions<P extends InPageChannelProtocol> = SideFunctions<NonNullable<P['pageScript']>>;
+type PanelFunctions<P extends InPageChannelProtocol> = SideFunctions<NonNullable<P['panel']>>;
+type SharedStates<P extends InPageChannelProtocol> = P['sharedStates'] extends Record<string, object> ? P['sharedStates'] : Record<string, never>;
+type FnArgs<F> = F extends ((...args: infer A) => any) ? A : never;
+type FnReturn<F> = F extends ((...args: any[]) => infer R) ? Awaited<R> : never;
+/**
+ * Types of an in-page channel function — `RpcFunctionType` minus the
+ * server-only `static`: `event` is fire-and-forget (the only type valid for
+ * fan-out), `action` performs, `query` requests data (the default).
+ */
+type InPageFunctionType = 'action' | 'event' | 'query';
+/**
+ * An in-page channel function definition — the `defineRpcFunction` authoring
+ * shape (`name`, `type`, Standard-Schema `args`/`returns`,
+ * `jsonSerializable`, `handler`) narrowed to the browser: there is no
+ * `dump`/`snapshot`/`cacheable`/`agent`. When `jsonSerializable` is `true`,
+ * payloads are strictly validated at the receiving endpoint and misshapen
+ * values reject the call with a descriptive `InPageChannelError` instead of
+ * a cryptic `DataCloneError` in the port.
+ */
+type InPageFunctionDefinition<NAME extends string, TYPE extends InPageFunctionType = 'query', ARGS extends any[] = [], RETURN = void, AS extends RpcArgsSchema | undefined = undefined, RS extends RpcReturnSchema | undefined = undefined> = [AS, RS] extends [undefined, undefined] ? {
+  name: NAME;
+  type?: TYPE;
+  args?: AS;
+  returns?: RS;
+  jsonSerializable?: boolean;
+  handler: (...args: ARGS) => RETURN;
+} : {
+  name: NAME;
+  type?: TYPE;
+  /** Standard Schema array validating (and typing) the arguments. */
+  args: AS;
+  /** Standard Schema typing the resolved return value. */
+  returns: RS;
+  jsonSerializable?: boolean;
+  handler: (...args: InferArgsType<AS>) => Thenable<InferReturnType<RS>>;
+};
+/** Loosely-typed definition — the registration unit both endpoints accept. */
+type InPageFunctionDefinitionAny = InPageFunctionDefinition<string, any, any, any, any, any>;
+/**
+ * Connection lifecycle of a panel endpoint: `connecting` (handshake retry
+ * loop running, outgoing traffic buffered) → `connected` → back to
+ * `connecting` on port loss, or `closed` after `close()` (permanent).
+ */
+type InPageChannelStatus = 'connecting' | 'connected' | 'closed';
+interface InPageChannelCommonOptions {
+  /**
+   * Channel name, namespaced with the devframe id by convention
+   * (e.g. `devframes:plugin:a11y`). Both endpoints must use the same name.
+   */
+  name: string;
+  /** Implementations of this endpoint's side of the protocol. */
+  functions?: readonly InPageFunctionDefinitionAny[];
+  /**
+   * Origins accepted during the handshake (and used as `targetOrigin` when
+   * posting handshake messages). The in-page channel is same-origin by
+   * definition, so this defaults to `[location.origin]`.
+   */
+  allowedOrigins?: string[];
+  /**
+   * Timeout for request/response calls, in milliseconds; `-1` disables.
+   * Rejections are `InPageChannelError`s (code `timeout`) carrying the
+   * endpoint status, so a hanging call explains itself.
+   * @default 15000
+   */
+  callTimeoutMs?: number;
+  /**
+   * Liveness heartbeat guarding against silently dead ports. Defaults to a
+   * 5s ping / 12s silence window; pass `false` to disable — on both
+   * endpoints together.
+   */
+  heartbeat?: {
+    intervalMs?: number;
+    timeoutMs?: number;
+  } | false;
+  /**
+   * Applied to each outgoing argument and handler result before posting —
+   * the place to unwrap framework reactivity (Vue `toRaw`, Solid `unwrap`)
+   * into plain structured-cloneable values.
+   */
+  serialize?: (value: unknown) => unknown;
+  /** Applied to each incoming argument and call result. */
+  deserialize?: (value: unknown) => unknown;
+}
+/** Options for {@link createPageScriptChannel}. */
+interface CreatePageScriptChannelOptions extends InPageChannelCommonOptions {
+  /**
+   * Window whose `message` events carry panel hellos. Defaults to the
+   * global `window`; pass `false` to skip the handshake listener entirely
+   * (bring-your-own ports via `addPanelPort` only).
+   */
+  window?: Window | false;
+}
+/** Options for {@link connectPanelChannel}. */
+interface ConnectPanelChannelOptions extends InPageChannelCommonOptions {
+  /**
+   * The panel's own window (listens for the handshake grant). Defaults to
+   * the global `window`; pass `false` with `transport` to skip the handshake.
+   */
+  window?: Window | false;
+  /**
+   * Windows the hello is posted to. Defaults to the panel's ancestor chain
+   * plus its `opener` — the places a same-tab page script can live. When
+   * empty and no `transport` is given, the endpoint stays `connecting` and
+   * warns once.
+   */
+  targets?: Window[];
+  /** Pre-established port to the page script, bypassing the handshake. */
+  transport?: MessagePort;
+  /**
+   * Pin this panel to one page-script instance id. By default the panel
+   * auto-pairs with the most recent page script that answers — almost
+   * always "my own tab's page script".
+   */
+  instanceId?: string;
+  /**
+   * Base interval between handshake hello retries, in milliseconds; each
+   * retry backs off ×1.5 up to a 3s cap, forever (the page script may load
+   * later than the panel).
+   * @default 300
+   */
+  helloIntervalMs?: number;
+  /**
+   * Maximum `callEvent` payloads buffered while `connecting`, flushed on
+   * connect; when full, the oldest is dropped with a console warning.
+   * @default 64
+   */
+  eventBufferLimit?: number;
+}
+/**
+ * The channel shared-state accessor — mirrors `rpc.sharedState`, with the
+ * page script playing the server's role as rendezvous and authority. The
+ * page script's first `get` of a key must provide `initialValue`; a panel's
+ * `get` without one resolves once the authority's first replay arrives.
+ */
+interface InPageSharedStateHost<P extends InPageChannelProtocol> {
+  get: <K extends keyof SharedStates<P> & string>(key: K, options?: {
+    initialValue?: SharedStates<P>[K];
+  }) => Promise<SharedState<SharedStates<P>[K]>>;
+}
+/** Emitter events of a page-script endpoint. */
+interface PageScriptChannelEvents<P extends InPageChannelProtocol> {
+  'panel:connected': (panel: PanelPeer<P>) => void;
+  'panel:disconnected': (panel: PanelPeer<P>) => void;
+}
+/** One connected panel, as seen from the page script. */
+interface PanelPeer<P extends InPageChannelProtocol> {
+  /** Unique id of the panel endpoint (stable across its lifetime, not reloads). */
+  readonly id: string;
+  /** Call one panel's function and await the result. */
+  call: <K extends keyof PanelFunctions<P> & string>(name: K, ...args: FnArgs<PanelFunctions<P>[K]>) => Promise<FnReturn<PanelFunctions<P>[K]>>;
+  /** Disconnect this panel. */
+  close: () => void;
+}
+/**
+ * The page-script endpoint of an in-page channel: answers panel handshakes,
+ * holds one dedicated port per connected panel, fans events out to all of
+ * them, and is the authority for the channel's shared states.
+ */
+interface PageScriptChannel<P extends InPageChannelProtocol> {
+  readonly name: string;
+  /**
+   * This page context's instance id (persisted per tab in sessionStorage),
+   * carried in every handshake so panels can pin to one instance when the
+   * same app is open in several tabs.
+   */
+  readonly instanceId: string;
+  /** Currently connected panels. */
+  readonly panels: readonly PanelPeer<P>[];
+  readonly events: Pick<EventEmitter<PageScriptChannelEvents<P>>, 'on' | 'once'>;
+  /**
+   * Fan a fire-and-forget event out to every connected panel; panels that
+   * don't implement the function ignore it.
+   */
+  callEvent: <K extends keyof PanelFunctions<P> & string>(name: K, ...args: FnArgs<PanelFunctions<P>[K]>) => void;
+  /** Page-script-authoritative shared states, replayed to joining panels. */
+  readonly sharedState: InPageSharedStateHost<P>;
+  /** Adopt a pre-established port as a panel peer (bring-your-own transport). */
+  addPanelPort: (port: MessagePort) => PanelPeer<P>;
+  /** Tear the endpoint down: disconnect every panel, stop answering hellos. */
+  close: () => void;
+}
+/** Emitter events of a panel endpoint. */
+interface PanelChannelEvents {
+  'status:updated': (status: InPageChannelStatus) => void;
+}
+/**
+ * The panel endpoint of an in-page channel: finds the page script with a
+ * retrying same-origin handshake, survives reloads on either side by
+ * re-handshaking, and buffers outgoing traffic while `connecting`.
+ */
+interface PanelChannel<P extends InPageChannelProtocol> {
+  readonly name: string;
+  readonly status: InPageChannelStatus;
+  /** The paired page script's instance id, once connected. */
+  readonly pageScript: {
+    instanceId: string;
+  } | undefined;
+  readonly events: Pick<EventEmitter<PanelChannelEvents>, 'on' | 'once'>;
+  /**
+   * Resolves once connected. With `timeoutMs`, rejects with an
+   * `InPageChannelError` (code `timeout`) when no page script answered in
+   * time — the hook for a "no page script found" fallback UI.
+   */
+  whenConnected: (timeoutMs?: number) => Promise<void>;
+  /**
+   * Call a page-script function and await the result. While `connecting`
+   * the call is buffered and sent on connect; it rejects with code
+   * `timeout` when `callTimeoutMs` elapses first.
+   */
+  call: <K extends keyof PageScriptFunctions<P> & string>(name: K, ...args: FnArgs<PageScriptFunctions<P>[K]>) => Promise<FnReturn<PageScriptFunctions<P>[K]>>;
+  /**
+   * Fire-and-forget to the page script. While `connecting` the event is
+   * buffered (up to `eventBufferLimit`) and flushed on connect.
+   */
+  callEvent: <K extends keyof PageScriptFunctions<P> & string>(name: K, ...args: FnArgs<PageScriptFunctions<P>[K]>) => void;
+  /** Shared states mirrored from the page-script authority. */
+  readonly sharedState: InPageSharedStateHost<P>;
+  /** Tear the endpoint down permanently. */
+  close: () => void;
+}
+//#endregion
+//#region src/in-page-channel/internal.d.ts
+/** Stable failure codes of the in-page channel. */
+type InPageChannelErrorCode = 'timeout' |
+/** The endpoint was closed (or closed while calls were pending). */
+'closed' |
+/** A `jsonSerializable` payload contained a non-JSON value. */
+'not-serializable' |
+/** The port refused to clone a payload (`DataCloneError`). */
+'not-cloneable' |
+/** Standard-Schema validation of incoming arguments failed. */
+'invalid-args' |
+/** A shared-state key was first accessed without its initial value. */
+'state-uninitialized';
+/** A coded in-page channel error; every failure mode carries a stable `code`. */
+declare class InPageChannelError extends Error {
+  readonly code: InPageChannelErrorCode;
+  name: string;
+  constructor(code: InPageChannelErrorCode, message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region src/in-page-channel/page-script.d.ts
+/**
+ * Create the page-script endpoint of an in-page channel.
+ *
+ * It listens for panel hellos on the host page's window and answers each
+ * with a dedicated `MessageChannel` port (same-origin enforced both ways),
+ * keeping one live peer per panel — dock iframe, popup, and Document-PiP
+ * panels all handshake the same way, and a panel reload is simply a new
+ * handshake. No server is involved at any point.
+ */
+declare function createPageScriptChannel<P extends InPageChannelProtocol>(options: CreatePageScriptChannelOptions): PageScriptChannel<P>;
+//#endregion
+//#region src/in-page-channel/panel.d.ts
+/**
+ * Connect the panel endpoint of an in-page channel.
+ *
+ * The panel initiates: it posts a versioned hello to every window a
+ * same-tab page script can live in (its ancestor chain and its `opener`),
+ * retrying with backoff until one answers with a dedicated port — so boot
+ * order never matters, and a reload of either side is just a re-handshake
+ * (`WindowProxy` references survive navigations). While `connecting`,
+ * outgoing calls and events are buffered; when no page script exists at all
+ * (e.g. the panel opened standalone), the endpoint stays `connecting` and
+ * the UI can key a fallback state off `status` / `whenConnected()`.
+ */
+declare function connectPanelChannel<P extends InPageChannelProtocol>(options: ConnectPanelChannelOptions): PanelChannel<P>;
+//#endregion
+//#region src/in-page-channel/index.d.ts
+/**
+ * Define one in-page channel function — the `defineRpcFunction` authoring
+ * shape narrowed to the browser (see {@link InPageFunctionDefinition}).
+ * Pure identity: it only types the definition. Functions live in
+ * side-specific files and are passed to their endpoint via `functions`; the
+ * shared protocol file carries only the contract type and the channel-name
+ * constant.
+ */
+declare function defineChannelFunction<NAME extends string, TYPE extends InPageFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>): InPageFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS>;
+//#endregion
+export { type ConnectPanelChannelOptions, type CreatePageScriptChannelOptions, InPageChannelError, type InPageChannelErrorCode, type InPageChannelProtocol, type InPageChannelStatus, type InPageFunctionDefinition, type PageScriptChannel, type PanelChannel, type PanelPeer, connectPanelChannel, createPageScriptChannel, defineChannelFunction };