@ai-matrx/desktop-protocol 0.1.0 → 0.2.0

package/dist/react.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/react.ts","../src/error.ts"],"sourcesContent":["/**\n * `@ai-matrx/desktop-protocol/react` — hooks over the client: provider, connection state, typed\n * one-shot requests, events. The client owns every hard part (reconnect, reattach, credits); these\n * hooks only bind it to React's lifecycle.\n */\nimport { createContext, createElement, useCallback, useContext, useEffect, useRef, useState, useSyncExternalStore } from \"react\";\nimport type { Context, ReactNode } from \"react\";\nimport type { DesktopClient, DesktopClientState, EventHandler, EventName, RequestOptions } from \"./client/types\";\nimport { DesktopProtocolError } from \"./error\";\nimport type { OpName, OpParams, OpResult } from \"./schema/registry\";\n\n// The context lives on globalThis: an ESM and a CJS copy of this entry in one app (Next.js\n// does this) would otherwise create two contexts and a provider the hooks cannot see.\nconst CONTEXT_SLOT = Symbol.for(\"ai-matrx.desktop-protocol.client-context\");\nfunction clientContext(): Context<DesktopClient | null> {\n  const slot = globalThis as { [CONTEXT_SLOT]?: Context<DesktopClient | null> };\n  return (slot[CONTEXT_SLOT] ??= createContext<DesktopClient | null>(null));\n}\n\nexport function DesktopClientProvider(props: { client: DesktopClient; children?: ReactNode }): ReactNode {\n  return createElement(clientContext().Provider, { value: props.client }, props.children);\n}\n\n/** The client from the nearest provider (or the one passed in). Throws when there is neither. */\nexport function useDesktopClient(client?: DesktopClient): DesktopClient {\n  const fromContext = useContext(clientContext());\n  const resolved = client ?? fromContext;\n  if (!resolved) throw new Error(\"useDesktopClient: wrap the tree in <DesktopClientProvider client={…}> or pass a client\");\n  return resolved;\n}\n\n/** Live connection state (status, welcome, attempts, retryInMs, lastError). Connects on mount when idle. */\nexport function useDesktopConnection(client?: DesktopClient): DesktopClientState {\n  const c = useDesktopClient(client);\n  const state = useSyncExternalStore(c.subscribe, c.getState, c.getState);\n  useEffect(() => {\n    if (c.getState().status === \"idle\") c.connect();\n  }, [c]);\n  return state;\n}\n\nexport interface DesktopRequestState<N extends OpName> {\n  data: OpResult<N> | undefined;\n  error: DesktopProtocolError | undefined;\n  loading: boolean;\n  /** Re-run now; resolves with the fresh result. */\n  refetch: () => Promise<OpResult<N> | undefined>;\n}\n\nexport interface UseDesktopRequestOptions extends Omit<RequestOptions, \"signal\"> {\n  /** Default true. False = do not run until refetch() or enabled flips true. */\n  enabled?: boolean;\n  client?: DesktopClient;\n}\n\n/**\n * Run a unary op and keep its latest result. Re-runs when `op` or the params' JSON changes, and\n * after a reconnect if the last attempt failed with a retryable error. Aborts on unmount.\n */\nexport function useDesktopRequest<N extends OpName>(op: N, params: OpParams<N>, options: UseDesktopRequestOptions = {}): DesktopRequestState<N> {\n  const c = useDesktopClient(options.client);\n  const enabled = options.enabled ?? true;\n  const key = JSON.stringify(params);\n  const [data, setData] = useState<OpResult<N> | undefined>(undefined);\n  const [error, setError] = useState<DesktopProtocolError | undefined>(undefined);\n  const [loading, setLoading] = useState<boolean>(enabled);\n  const paramsRef = useRef(params);\n  paramsRef.current = params;\n  const runRef = useRef(0);\n  const abortRef = useRef<AbortController | null>(null);\n  const timeoutMs = options.timeoutMs;\n\n  const run = useCallback(async (): Promise<OpResult<N> | undefined> => {\n    const runId = ++runRef.current;\n    abortRef.current?.abort();\n    const abort = new AbortController();\n    abortRef.current = abort;\n    setLoading(true);\n    try {\n      const result = await c.request(op, paramsRef.current, timeoutMs === undefined ? { signal: abort.signal } : { signal: abort.signal, timeoutMs });\n      if (runId === runRef.current) {\n        setData(result);\n        setError(undefined);\n      }\n      return result;\n    } catch (caught) {\n      const err = caught instanceof DesktopProtocolError ? caught : new DesktopProtocolError(\"INTERNAL\", String(caught), { cause: caught });\n      if (runId === runRef.current && err.code !== \"CANCELLED\") setError(err);\n      return undefined;\n    } finally {\n      if (runId === runRef.current) setLoading(false);\n    }\n    // `key` stands for the params' content: a new object with equal JSON is not a new request.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [c, op, key, timeoutMs]);\n\n  useEffect(() => {\n    if (!enabled) {\n      setLoading(false);\n      return;\n    }\n    void run();\n    return () => {\n      abortRef.current?.abort();\n    };\n  }, [enabled, run]);\n\n  // A retryable failure (device offline, connection lost) re-runs once the client is open again.\n  const status = useSyncExternalStore(c.subscribe, () => c.getState().status, () => c.getState().status);\n  useEffect(() => {\n    if (enabled && status === \"open\" && error?.retryable) void run();\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [status]);\n\n  return { data, error, loading, refetch: run };\n}\n\n/** Subscribe to one protocol event (fs.changed, exec.exited, relay.device_status, …) for the component's life. */\nexport function useDesktopEvent<E extends EventName>(name: E, handler: EventHandler<E>, options: { client?: DesktopClient } = {}): void {\n  const c = useDesktopClient(options.client);\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n  useEffect(() => c.on(name, ((payload, resourceId) => handlerRef.current(payload, resourceId)) as EventHandler<E>), [c, name]);\n}\n","/**\n * The one error type every package entry throws. It carries the wire ErrorCode (SPEC §5), so a\n * caller branches on `code`/`retryable`/`data.reason` and never parses a message. Zod-free on\n * purpose: `./frame` (the relay hot path) throws it without pulling the schema graph.\n */\nimport type { ErrorCodeName, ErrorData } from \"./types\";\n\nexport class DesktopProtocolError extends Error {\n  readonly code: ErrorCodeName;\n  readonly retryable: boolean;\n  readonly data: ErrorData | undefined;\n\n  constructor(code: ErrorCodeName, message: string, options: { retryable?: boolean; data?: ErrorData; cause?: unknown } = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = \"DesktopProtocolError\";\n    this.code = code;\n    this.retryable = options.retryable ?? false;\n    this.data = options.data;\n  }\n\n  /** The wire body (ProtocolErrorBody) — what a core or relay sends for this error. */\n  toBody(): { code: ErrorCodeName; message: string; retryable: boolean; data?: ErrorData } {\n    return this.data === undefined\n      ? { code: this.code, message: this.message, retryable: this.retryable }\n      : { code: this.code, message: this.message, retryable: this.retryable, data: this.data };\n  }\n}\n\nexport function isDesktopProtocolError(value: unknown): value is DesktopProtocolError {\n  return value instanceof DesktopProtocolError || (value instanceof Error && value.name === \"DesktopProtocolError\" && \"code\" in value);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/react.ts","../src/client/wake.ts","../src/error.ts"],"sourcesContent":["/**\n * `@ai-matrx/desktop-protocol/react` — hooks over the client: provider, connection state, typed\n * one-shot requests, events. The client owns every hard part (reconnect, reattach, credits); these\n * hooks only bind it to React's lifecycle.\n */\nimport { createContext, createElement, useCallback, useContext, useEffect, useRef, useState, useSyncExternalStore } from \"react\";\nimport type { Context, ReactNode } from \"react\";\nimport type { DesktopClient, DesktopClientState, EventHandler, EventName, RequestOptions } from \"./client/types\";\nimport { bindDesktopWake } from \"./client/wake\";\nimport { DesktopProtocolError } from \"./error\";\nimport type { OpName, OpParams, OpResult } from \"./schema/registry\";\n\n// The context lives on globalThis: an ESM and a CJS copy of this entry in one app (Next.js\n// does this) would otherwise create two contexts and a provider the hooks cannot see.\nconst CONTEXT_SLOT = Symbol.for(\"ai-matrx.desktop-protocol.client-context\");\nfunction clientContext(): Context<DesktopClient | null> {\n  const slot = globalThis as { [CONTEXT_SLOT]?: Context<DesktopClient | null> };\n  return (slot[CONTEXT_SLOT] ??= createContext<DesktopClient | null>(null));\n}\n\nexport function DesktopClientProvider(props: { client: DesktopClient; children?: ReactNode }): ReactNode {\n  return createElement(clientContext().Provider, { value: props.client }, props.children);\n}\n\n/** The client from the nearest provider (or the one passed in). Throws when there is neither. */\nexport function useDesktopClient(client?: DesktopClient): DesktopClient {\n  const fromContext = useContext(clientContext());\n  const resolved = client ?? fromContext;\n  if (!resolved) throw new Error(\"useDesktopClient: wrap the tree in <DesktopClientProvider client={…}> or pass a client\");\n  return resolved;\n}\n\n/** Live connection state (status, welcome, attempts, retryInMs, lastError). Connects on mount when idle. */\nexport function useDesktopConnection(client?: DesktopClient): DesktopClientState {\n  const c = useDesktopClient(client);\n  const state = useSyncExternalStore(c.subscribe, c.getState, c.getState);\n  useEffect(() => {\n    if (c.getState().status === \"idle\") c.connect();\n  }, [c]);\n  return state;\n}\n\nexport interface DesktopRequestState<N extends OpName> {\n  data: OpResult<N> | undefined;\n  error: DesktopProtocolError | undefined;\n  loading: boolean;\n  /** Re-run now; resolves with the fresh result. */\n  refetch: () => Promise<OpResult<N> | undefined>;\n}\n\nexport interface UseDesktopRequestOptions extends Omit<RequestOptions, \"signal\"> {\n  /** Default true. False = do not run until refetch() or enabled flips true. */\n  enabled?: boolean;\n  client?: DesktopClient;\n}\n\n/**\n * Run a unary op and keep its latest result. Re-runs when `op` or the params' JSON changes, and\n * after a reconnect if the last attempt failed with a retryable error. Aborts on unmount.\n */\nexport function useDesktopRequest<N extends OpName>(op: N, params: OpParams<N>, options: UseDesktopRequestOptions = {}): DesktopRequestState<N> {\n  const c = useDesktopClient(options.client);\n  const enabled = options.enabled ?? true;\n  const key = JSON.stringify(params);\n  const [data, setData] = useState<OpResult<N> | undefined>(undefined);\n  const [error, setError] = useState<DesktopProtocolError | undefined>(undefined);\n  const [loading, setLoading] = useState<boolean>(enabled);\n  const paramsRef = useRef(params);\n  paramsRef.current = params;\n  const runRef = useRef(0);\n  const abortRef = useRef<AbortController | null>(null);\n  const timeoutMs = options.timeoutMs;\n\n  const run = useCallback(async (): Promise<OpResult<N> | undefined> => {\n    const runId = ++runRef.current;\n    abortRef.current?.abort();\n    const abort = new AbortController();\n    abortRef.current = abort;\n    setLoading(true);\n    try {\n      const result = await c.request(op, paramsRef.current, timeoutMs === undefined ? { signal: abort.signal } : { signal: abort.signal, timeoutMs });\n      if (runId === runRef.current) {\n        setData(result);\n        setError(undefined);\n      }\n      return result;\n    } catch (caught) {\n      const err = caught instanceof DesktopProtocolError ? caught : new DesktopProtocolError(\"INTERNAL\", String(caught), { cause: caught });\n      if (runId === runRef.current && err.code !== \"CANCELLED\") setError(err);\n      return undefined;\n    } finally {\n      if (runId === runRef.current) setLoading(false);\n    }\n    // `key` stands for the params' content: a new object with equal JSON is not a new request.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [c, op, key, timeoutMs]);\n\n  useEffect(() => {\n    if (!enabled) {\n      setLoading(false);\n      return;\n    }\n    void run();\n    return () => {\n      abortRef.current?.abort();\n    };\n  }, [enabled, run]);\n\n  // A retryable failure (device offline, connection lost) re-runs once the client is open again.\n  const status = useSyncExternalStore(c.subscribe, () => c.getState().status, () => c.getState().status);\n  useEffect(() => {\n    if (enabled && status === \"open\" && error?.retryable) void run();\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [status]);\n\n  return { data, error, loading, refetch: run };\n}\n\n/** Subscribe to one protocol event (fs.changed, exec.exited, relay.device_status, …) for the component's life. */\nexport function useDesktopEvent<E extends EventName>(name: E, handler: EventHandler<E>, options: { client?: DesktopClient } = {}): void {\n  const c = useDesktopClient(options.client);\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n  useEffect(() => c.on(name, ((payload, resourceId) => handlerRef.current(payload, resourceId)) as EventHandler<E>), [c, name]);\n}\n\n/**\n * Reconnect the moment the person is back: page visible again, a bfcache restore, the network\n * returning, window focus. Each calls `client.wake()` — dial now if reconnecting, probe if open.\n */\nexport function useDesktopWake(client?: DesktopClient, options: { probeMs?: number } = {}): void {\n  const c = useDesktopClient(client);\n  const probeMs = options.probeMs;\n  useEffect(() => bindDesktopWake(c, probeMs === undefined ? {} : { probeMs }), [c, probeMs]);\n}\n","/**\n * Wire a client's wake() to the browser events that mean \"the person is back\": the page becomes\n * visible again (iOS Safari suspends a background tab's sockets), a back/forward-cache restore\n * (`pageshow` with persisted), and the network returning (`online`). Framework-free; the React\n * binding is `useDesktopWake` in `./react`.\n */\nimport type { DesktopClient, WakeOptions } from \"./types\";\n\n/** The subset of window/document the binding listens on — injectable for tests and non-DOM hosts. */\nexport interface WakeTargets {\n  window: Pick<Window, \"addEventListener\" | \"removeEventListener\">;\n  document: Pick<Document, \"addEventListener\" | \"removeEventListener\" | \"visibilityState\">;\n}\n\nexport function bindDesktopWake(client: Pick<DesktopClient, \"wake\">, options: WakeOptions & { targets?: WakeTargets } = {}): () => void {\n  const targets: WakeTargets | null =\n    options.targets ?? (typeof window !== \"undefined\" && typeof document !== \"undefined\" ? { window, document } : null);\n  if (!targets) return () => undefined;\n  const wakeOptions: WakeOptions = options.probeMs === undefined ? {} : { probeMs: options.probeMs };\n  const onVisibility = () => {\n    if (targets.document.visibilityState === \"visible\") client.wake(wakeOptions);\n  };\n  const onWake = () => client.wake(wakeOptions);\n  targets.document.addEventListener(\"visibilitychange\", onVisibility);\n  targets.window.addEventListener(\"pageshow\", onWake);\n  targets.window.addEventListener(\"online\", onWake);\n  targets.window.addEventListener(\"focus\", onWake);\n  return () => {\n    targets.document.removeEventListener(\"visibilitychange\", onVisibility);\n    targets.window.removeEventListener(\"pageshow\", onWake);\n    targets.window.removeEventListener(\"online\", onWake);\n    targets.window.removeEventListener(\"focus\", onWake);\n  };\n}\n","/**\n * The one error type every package entry throws. It carries the wire ErrorCode (SPEC §5), so a\n * caller branches on `code`/`retryable`/`data.reason` and never parses a message. Zod-free on\n * purpose: `./frame` (the relay hot path) throws it without pulling the schema graph.\n */\nimport type { ErrorCodeName, ErrorData } from \"./types\";\n\nexport class DesktopProtocolError extends Error {\n  readonly code: ErrorCodeName;\n  readonly retryable: boolean;\n  readonly data: ErrorData | undefined;\n\n  constructor(code: ErrorCodeName, message: string, options: { retryable?: boolean; data?: ErrorData; cause?: unknown } = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = \"DesktopProtocolError\";\n    this.code = code;\n    this.retryable = options.retryable ?? false;\n    this.data = options.data;\n  }\n\n  /** The wire body (ProtocolErrorBody) — what a core or relay sends for this error. */\n  toBody(): { code: ErrorCodeName; message: string; retryable: boolean; data?: ErrorData } {\n    return this.data === undefined\n      ? { code: this.code, message: this.message, retryable: this.retryable }\n      : { code: this.code, message: this.message, retryable: this.retryable, data: this.data };\n  }\n}\n\nexport function isDesktopProtocolError(value: unknown): value is DesktopProtocolError {\n  return value instanceof DesktopProtocolError || (value instanceof Error && value.name === \"DesktopProtocolError\" && \"code\" in value);\n}\n"],"mappings":"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","names":[]}

package/dist/react.d.cts

@@ -889,6 +889,18 @@ interface DesktopClient {
     on<E extends EventName>(name: E, handler: EventHandler<E>): () => void;
     /** Hand the relay a fresh token without dropping the socket. */
     reauth(token: string): void;
+    /**
+     * The app came back to the foreground or the network changed (`visibilitychange` → visible,
+     * `pageshow`, `online`). Reconnecting → dial now instead of waiting out the backoff. Open → probe:
+     * a ping must be answered within `probeMs` (default 4000) or the socket is treated as dead and
+     * redialed at once. A phone resumed from sleep often holds a socket the OS already killed, and two
+     * silent heartbeats would cost 50 s. Resource streams reattach with `since_seq` as usual.
+     */
+    wake(options?: WakeOptions): void;
+}
+interface WakeOptions {
+    /** How long an open socket has to answer the probe ping. Default 4000. */
+    probeMs?: number;
 }
 
 declare function DesktopClientProvider(props: {
@@ -920,5 +932,12 @@ declare function useDesktopRequest<N extends OpName>(op: N, params: OpParams<N>,
 declare function useDesktopEvent<E extends EventName>(name: E, handler: EventHandler<E>, options?: {
     client?: DesktopClient;
 }): void;
+/**
+ * Reconnect the moment the person is back: page visible again, a bfcache restore, the network
+ * returning, window focus. Each calls `client.wake()` — dial now if reconnecting, probe if open.
+ */
+declare function useDesktopWake(client?: DesktopClient, options?: {
+    probeMs?: number;
+}): void;
 
-export { DesktopClientProvider, type DesktopRequestState, type UseDesktopRequestOptions, useDesktopClient, useDesktopConnection, useDesktopEvent, useDesktopRequest };
+export { DesktopClientProvider, type DesktopRequestState, type UseDesktopRequestOptions, useDesktopClient, useDesktopConnection, useDesktopEvent, useDesktopRequest, useDesktopWake };

package/dist/react.d.ts

@@ -889,6 +889,18 @@ interface DesktopClient {
     on<E extends EventName>(name: E, handler: EventHandler<E>): () => void;
     /** Hand the relay a fresh token without dropping the socket. */
     reauth(token: string): void;
+    /**
+     * The app came back to the foreground or the network changed (`visibilitychange` → visible,
+     * `pageshow`, `online`). Reconnecting → dial now instead of waiting out the backoff. Open → probe:
+     * a ping must be answered within `probeMs` (default 4000) or the socket is treated as dead and
+     * redialed at once. A phone resumed from sleep often holds a socket the OS already killed, and two
+     * silent heartbeats would cost 50 s. Resource streams reattach with `since_seq` as usual.
+     */
+    wake(options?: WakeOptions): void;
+}
+interface WakeOptions {
+    /** How long an open socket has to answer the probe ping. Default 4000. */
+    probeMs?: number;
 }
 
 declare function DesktopClientProvider(props: {
@@ -920,5 +932,12 @@ declare function useDesktopRequest<N extends OpName>(op: N, params: OpParams<N>,
 declare function useDesktopEvent<E extends EventName>(name: E, handler: EventHandler<E>, options?: {
     client?: DesktopClient;
 }): void;
+/**
+ * Reconnect the moment the person is back: page visible again, a bfcache restore, the network
+ * returning, window focus. Each calls `client.wake()` — dial now if reconnecting, probe if open.
+ */
+declare function useDesktopWake(client?: DesktopClient, options?: {
+    probeMs?: number;
+}): void;
 
-export { DesktopClientProvider, type DesktopRequestState, type UseDesktopRequestOptions, useDesktopClient, useDesktopConnection, useDesktopEvent, useDesktopRequest };
+export { DesktopClientProvider, type DesktopRequestState, type UseDesktopRequestOptions, useDesktopClient, useDesktopConnection, useDesktopEvent, useDesktopRequest, useDesktopWake };

package/dist/react.js

@@ -3,6 +3,27 @@
 // src/react.ts
 import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState, useSyncExternalStore } from "react";
 
+// src/client/wake.ts
+function bindDesktopWake(client, options = {}) {
+  const targets = options.targets ?? (typeof window !== "undefined" && typeof document !== "undefined" ? { window, document } : null);
+  if (!targets) return () => void 0;
+  const wakeOptions = options.probeMs === void 0 ? {} : { probeMs: options.probeMs };
+  const onVisibility = () => {
+    if (targets.document.visibilityState === "visible") client.wake(wakeOptions);
+  };
+  const onWake = () => client.wake(wakeOptions);
+  targets.document.addEventListener("visibilitychange", onVisibility);
+  targets.window.addEventListener("pageshow", onWake);
+  targets.window.addEventListener("online", onWake);
+  targets.window.addEventListener("focus", onWake);
+  return () => {
+    targets.document.removeEventListener("visibilitychange", onVisibility);
+    targets.window.removeEventListener("pageshow", onWake);
+    targets.window.removeEventListener("online", onWake);
+    targets.window.removeEventListener("focus", onWake);
+  };
+}
+
 // src/error.ts
 var DesktopProtocolError = class extends Error {
   code;
@@ -99,11 +120,17 @@ function useDesktopEvent(name, handler, options = {}) {
   handlerRef.current = handler;
   useEffect(() => c.on(name, ((payload, resourceId) => handlerRef.current(payload, resourceId))), [c, name]);
 }
+function useDesktopWake(client, options = {}) {
+  const c = useDesktopClient(client);
+  const probeMs = options.probeMs;
+  useEffect(() => bindDesktopWake(c, probeMs === void 0 ? {} : { probeMs }), [c, probeMs]);
+}
 export {
   DesktopClientProvider,
   useDesktopClient,
   useDesktopConnection,
   useDesktopEvent,
-  useDesktopRequest
+  useDesktopRequest,
+  useDesktopWake
 };
 //# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/react.ts","../src/error.ts"],"sourcesContent":["/**\n * `@ai-matrx/desktop-protocol/react` — hooks over the client: provider, connection state, typed\n * one-shot requests, events. The client owns every hard part (reconnect, reattach, credits); these\n * hooks only bind it to React's lifecycle.\n */\nimport { createContext, createElement, useCallback, useContext, useEffect, useRef, useState, useSyncExternalStore } from \"react\";\nimport type { Context, ReactNode } from \"react\";\nimport type { DesktopClient, DesktopClientState, EventHandler, EventName, RequestOptions } from \"./client/types\";\nimport { DesktopProtocolError } from \"./error\";\nimport type { OpName, OpParams, OpResult } from \"./schema/registry\";\n\n// The context lives on globalThis: an ESM and a CJS copy of this entry in one app (Next.js\n// does this) would otherwise create two contexts and a provider the hooks cannot see.\nconst CONTEXT_SLOT = Symbol.for(\"ai-matrx.desktop-protocol.client-context\");\nfunction clientContext(): Context<DesktopClient | null> {\n  const slot = globalThis as { [CONTEXT_SLOT]?: Context<DesktopClient | null> };\n  return (slot[CONTEXT_SLOT] ??= createContext<DesktopClient | null>(null));\n}\n\nexport function DesktopClientProvider(props: { client: DesktopClient; children?: ReactNode }): ReactNode {\n  return createElement(clientContext().Provider, { value: props.client }, props.children);\n}\n\n/** The client from the nearest provider (or the one passed in). Throws when there is neither. */\nexport function useDesktopClient(client?: DesktopClient): DesktopClient {\n  const fromContext = useContext(clientContext());\n  const resolved = client ?? fromContext;\n  if (!resolved) throw new Error(\"useDesktopClient: wrap the tree in <DesktopClientProvider client={…}> or pass a client\");\n  return resolved;\n}\n\n/** Live connection state (status, welcome, attempts, retryInMs, lastError). Connects on mount when idle. */\nexport function useDesktopConnection(client?: DesktopClient): DesktopClientState {\n  const c = useDesktopClient(client);\n  const state = useSyncExternalStore(c.subscribe, c.getState, c.getState);\n  useEffect(() => {\n    if (c.getState().status === \"idle\") c.connect();\n  }, [c]);\n  return state;\n}\n\nexport interface DesktopRequestState<N extends OpName> {\n  data: OpResult<N> | undefined;\n  error: DesktopProtocolError | undefined;\n  loading: boolean;\n  /** Re-run now; resolves with the fresh result. */\n  refetch: () => Promise<OpResult<N> | undefined>;\n}\n\nexport interface UseDesktopRequestOptions extends Omit<RequestOptions, \"signal\"> {\n  /** Default true. False = do not run until refetch() or enabled flips true. */\n  enabled?: boolean;\n  client?: DesktopClient;\n}\n\n/**\n * Run a unary op and keep its latest result. Re-runs when `op` or the params' JSON changes, and\n * after a reconnect if the last attempt failed with a retryable error. Aborts on unmount.\n */\nexport function useDesktopRequest<N extends OpName>(op: N, params: OpParams<N>, options: UseDesktopRequestOptions = {}): DesktopRequestState<N> {\n  const c = useDesktopClient(options.client);\n  const enabled = options.enabled ?? true;\n  const key = JSON.stringify(params);\n  const [data, setData] = useState<OpResult<N> | undefined>(undefined);\n  const [error, setError] = useState<DesktopProtocolError | undefined>(undefined);\n  const [loading, setLoading] = useState<boolean>(enabled);\n  const paramsRef = useRef(params);\n  paramsRef.current = params;\n  const runRef = useRef(0);\n  const abortRef = useRef<AbortController | null>(null);\n  const timeoutMs = options.timeoutMs;\n\n  const run = useCallback(async (): Promise<OpResult<N> | undefined> => {\n    const runId = ++runRef.current;\n    abortRef.current?.abort();\n    const abort = new AbortController();\n    abortRef.current = abort;\n    setLoading(true);\n    try {\n      const result = await c.request(op, paramsRef.current, timeoutMs === undefined ? { signal: abort.signal } : { signal: abort.signal, timeoutMs });\n      if (runId === runRef.current) {\n        setData(result);\n        setError(undefined);\n      }\n      return result;\n    } catch (caught) {\n      const err = caught instanceof DesktopProtocolError ? caught : new DesktopProtocolError(\"INTERNAL\", String(caught), { cause: caught });\n      if (runId === runRef.current && err.code !== \"CANCELLED\") setError(err);\n      return undefined;\n    } finally {\n      if (runId === runRef.current) setLoading(false);\n    }\n    // `key` stands for the params' content: a new object with equal JSON is not a new request.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [c, op, key, timeoutMs]);\n\n  useEffect(() => {\n    if (!enabled) {\n      setLoading(false);\n      return;\n    }\n    void run();\n    return () => {\n      abortRef.current?.abort();\n    };\n  }, [enabled, run]);\n\n  // A retryable failure (device offline, connection lost) re-runs once the client is open again.\n  const status = useSyncExternalStore(c.subscribe, () => c.getState().status, () => c.getState().status);\n  useEffect(() => {\n    if (enabled && status === \"open\" && error?.retryable) void run();\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [status]);\n\n  return { data, error, loading, refetch: run };\n}\n\n/** Subscribe to one protocol event (fs.changed, exec.exited, relay.device_status, …) for the component's life. */\nexport function useDesktopEvent<E extends EventName>(name: E, handler: EventHandler<E>, options: { client?: DesktopClient } = {}): void {\n  const c = useDesktopClient(options.client);\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n  useEffect(() => c.on(name, ((payload, resourceId) => handlerRef.current(payload, resourceId)) as EventHandler<E>), [c, name]);\n}\n","/**\n * The one error type every package entry throws. It carries the wire ErrorCode (SPEC §5), so a\n * caller branches on `code`/`retryable`/`data.reason` and never parses a message. Zod-free on\n * purpose: `./frame` (the relay hot path) throws it without pulling the schema graph.\n */\nimport type { ErrorCodeName, ErrorData } from \"./types\";\n\nexport class DesktopProtocolError extends Error {\n  readonly code: ErrorCodeName;\n  readonly retryable: boolean;\n  readonly data: ErrorData | undefined;\n\n  constructor(code: ErrorCodeName, message: string, options: { retryable?: boolean; data?: ErrorData; cause?: unknown } = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = \"DesktopProtocolError\";\n    this.code = code;\n    this.retryable = options.retryable ?? false;\n    this.data = options.data;\n  }\n\n  /** The wire body (ProtocolErrorBody) — what a core or relay sends for this error. */\n  toBody(): { code: ErrorCodeName; message: string; retryable: boolean; data?: ErrorData } {\n    return this.data === undefined\n      ? { code: this.code, message: this.message, retryable: this.retryable }\n      : { code: this.code, message: this.message, retryable: this.retryable, data: this.data };\n  }\n}\n\nexport function isDesktopProtocolError(value: unknown): value is DesktopProtocolError {\n  return value instanceof DesktopProtocolError || (value instanceof Error && value.name === \"DesktopProtocolError\" && \"code\" in value);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/react.ts","../src/client/wake.ts","../src/error.ts"],"sourcesContent":["/**\n * `@ai-matrx/desktop-protocol/react` — hooks over the client: provider, connection state, typed\n * one-shot requests, events. The client owns every hard part (reconnect, reattach, credits); these\n * hooks only bind it to React's lifecycle.\n */\nimport { createContext, createElement, useCallback, useContext, useEffect, useRef, useState, useSyncExternalStore } from \"react\";\nimport type { Context, ReactNode } from \"react\";\nimport type { DesktopClient, DesktopClientState, EventHandler, EventName, RequestOptions } from \"./client/types\";\nimport { bindDesktopWake } from \"./client/wake\";\nimport { DesktopProtocolError } from \"./error\";\nimport type { OpName, OpParams, OpResult } from \"./schema/registry\";\n\n// The context lives on globalThis: an ESM and a CJS copy of this entry in one app (Next.js\n// does this) would otherwise create two contexts and a provider the hooks cannot see.\nconst CONTEXT_SLOT = Symbol.for(\"ai-matrx.desktop-protocol.client-context\");\nfunction clientContext(): Context<DesktopClient | null> {\n  const slot = globalThis as { [CONTEXT_SLOT]?: Context<DesktopClient | null> };\n  return (slot[CONTEXT_SLOT] ??= createContext<DesktopClient | null>(null));\n}\n\nexport function DesktopClientProvider(props: { client: DesktopClient; children?: ReactNode }): ReactNode {\n  return createElement(clientContext().Provider, { value: props.client }, props.children);\n}\n\n/** The client from the nearest provider (or the one passed in). Throws when there is neither. */\nexport function useDesktopClient(client?: DesktopClient): DesktopClient {\n  const fromContext = useContext(clientContext());\n  const resolved = client ?? fromContext;\n  if (!resolved) throw new Error(\"useDesktopClient: wrap the tree in <DesktopClientProvider client={…}> or pass a client\");\n  return resolved;\n}\n\n/** Live connection state (status, welcome, attempts, retryInMs, lastError). Connects on mount when idle. */\nexport function useDesktopConnection(client?: DesktopClient): DesktopClientState {\n  const c = useDesktopClient(client);\n  const state = useSyncExternalStore(c.subscribe, c.getState, c.getState);\n  useEffect(() => {\n    if (c.getState().status === \"idle\") c.connect();\n  }, [c]);\n  return state;\n}\n\nexport interface DesktopRequestState<N extends OpName> {\n  data: OpResult<N> | undefined;\n  error: DesktopProtocolError | undefined;\n  loading: boolean;\n  /** Re-run now; resolves with the fresh result. */\n  refetch: () => Promise<OpResult<N> | undefined>;\n}\n\nexport interface UseDesktopRequestOptions extends Omit<RequestOptions, \"signal\"> {\n  /** Default true. False = do not run until refetch() or enabled flips true. */\n  enabled?: boolean;\n  client?: DesktopClient;\n}\n\n/**\n * Run a unary op and keep its latest result. Re-runs when `op` or the params' JSON changes, and\n * after a reconnect if the last attempt failed with a retryable error. Aborts on unmount.\n */\nexport function useDesktopRequest<N extends OpName>(op: N, params: OpParams<N>, options: UseDesktopRequestOptions = {}): DesktopRequestState<N> {\n  const c = useDesktopClient(options.client);\n  const enabled = options.enabled ?? true;\n  const key = JSON.stringify(params);\n  const [data, setData] = useState<OpResult<N> | undefined>(undefined);\n  const [error, setError] = useState<DesktopProtocolError | undefined>(undefined);\n  const [loading, setLoading] = useState<boolean>(enabled);\n  const paramsRef = useRef(params);\n  paramsRef.current = params;\n  const runRef = useRef(0);\n  const abortRef = useRef<AbortController | null>(null);\n  const timeoutMs = options.timeoutMs;\n\n  const run = useCallback(async (): Promise<OpResult<N> | undefined> => {\n    const runId = ++runRef.current;\n    abortRef.current?.abort();\n    const abort = new AbortController();\n    abortRef.current = abort;\n    setLoading(true);\n    try {\n      const result = await c.request(op, paramsRef.current, timeoutMs === undefined ? { signal: abort.signal } : { signal: abort.signal, timeoutMs });\n      if (runId === runRef.current) {\n        setData(result);\n        setError(undefined);\n      }\n      return result;\n    } catch (caught) {\n      const err = caught instanceof DesktopProtocolError ? caught : new DesktopProtocolError(\"INTERNAL\", String(caught), { cause: caught });\n      if (runId === runRef.current && err.code !== \"CANCELLED\") setError(err);\n      return undefined;\n    } finally {\n      if (runId === runRef.current) setLoading(false);\n    }\n    // `key` stands for the params' content: a new object with equal JSON is not a new request.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [c, op, key, timeoutMs]);\n\n  useEffect(() => {\n    if (!enabled) {\n      setLoading(false);\n      return;\n    }\n    void run();\n    return () => {\n      abortRef.current?.abort();\n    };\n  }, [enabled, run]);\n\n  // A retryable failure (device offline, connection lost) re-runs once the client is open again.\n  const status = useSyncExternalStore(c.subscribe, () => c.getState().status, () => c.getState().status);\n  useEffect(() => {\n    if (enabled && status === \"open\" && error?.retryable) void run();\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [status]);\n\n  return { data, error, loading, refetch: run };\n}\n\n/** Subscribe to one protocol event (fs.changed, exec.exited, relay.device_status, …) for the component's life. */\nexport function useDesktopEvent<E extends EventName>(name: E, handler: EventHandler<E>, options: { client?: DesktopClient } = {}): void {\n  const c = useDesktopClient(options.client);\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n  useEffect(() => c.on(name, ((payload, resourceId) => handlerRef.current(payload, resourceId)) as EventHandler<E>), [c, name]);\n}\n\n/**\n * Reconnect the moment the person is back: page visible again, a bfcache restore, the network\n * returning, window focus. Each calls `client.wake()` — dial now if reconnecting, probe if open.\n */\nexport function useDesktopWake(client?: DesktopClient, options: { probeMs?: number } = {}): void {\n  const c = useDesktopClient(client);\n  const probeMs = options.probeMs;\n  useEffect(() => bindDesktopWake(c, probeMs === undefined ? {} : { probeMs }), [c, probeMs]);\n}\n","/**\n * Wire a client's wake() to the browser events that mean \"the person is back\": the page becomes\n * visible again (iOS Safari suspends a background tab's sockets), a back/forward-cache restore\n * (`pageshow` with persisted), and the network returning (`online`). Framework-free; the React\n * binding is `useDesktopWake` in `./react`.\n */\nimport type { DesktopClient, WakeOptions } from \"./types\";\n\n/** The subset of window/document the binding listens on — injectable for tests and non-DOM hosts. */\nexport interface WakeTargets {\n  window: Pick<Window, \"addEventListener\" | \"removeEventListener\">;\n  document: Pick<Document, \"addEventListener\" | \"removeEventListener\" | \"visibilityState\">;\n}\n\nexport function bindDesktopWake(client: Pick<DesktopClient, \"wake\">, options: WakeOptions & { targets?: WakeTargets } = {}): () => void {\n  const targets: WakeTargets | null =\n    options.targets ?? (typeof window !== \"undefined\" && typeof document !== \"undefined\" ? { window, document } : null);\n  if (!targets) return () => undefined;\n  const wakeOptions: WakeOptions = options.probeMs === undefined ? {} : { probeMs: options.probeMs };\n  const onVisibility = () => {\n    if (targets.document.visibilityState === \"visible\") client.wake(wakeOptions);\n  };\n  const onWake = () => client.wake(wakeOptions);\n  targets.document.addEventListener(\"visibilitychange\", onVisibility);\n  targets.window.addEventListener(\"pageshow\", onWake);\n  targets.window.addEventListener(\"online\", onWake);\n  targets.window.addEventListener(\"focus\", onWake);\n  return () => {\n    targets.document.removeEventListener(\"visibilitychange\", onVisibility);\n    targets.window.removeEventListener(\"pageshow\", onWake);\n    targets.window.removeEventListener(\"online\", onWake);\n    targets.window.removeEventListener(\"focus\", onWake);\n  };\n}\n","/**\n * The one error type every package entry throws. It carries the wire ErrorCode (SPEC §5), so a\n * caller branches on `code`/`retryable`/`data.reason` and never parses a message. Zod-free on\n * purpose: `./frame` (the relay hot path) throws it without pulling the schema graph.\n */\nimport type { ErrorCodeName, ErrorData } from \"./types\";\n\nexport class DesktopProtocolError extends Error {\n  readonly code: ErrorCodeName;\n  readonly retryable: boolean;\n  readonly data: ErrorData | undefined;\n\n  constructor(code: ErrorCodeName, message: string, options: { retryable?: boolean; data?: ErrorData; cause?: unknown } = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = \"DesktopProtocolError\";\n    this.code = code;\n    this.retryable = options.retryable ?? false;\n    this.data = options.data;\n  }\n\n  /** The wire body (ProtocolErrorBody) — what a core or relay sends for this error. */\n  toBody(): { code: ErrorCodeName; message: string; retryable: boolean; data?: ErrorData } {\n    return this.data === undefined\n      ? { code: this.code, message: this.message, retryable: this.retryable }\n      : { code: this.code, message: this.message, retryable: this.retryable, data: this.data };\n  }\n}\n\nexport function isDesktopProtocolError(value: unknown): value is DesktopProtocolError {\n  return value instanceof DesktopProtocolError || (value instanceof Error && value.name === \"DesktopProtocolError\" && \"code\" in value);\n}\n"],"mappings":"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","names":[]}

package/dist/{registry-DTcTGycI.d.cts → registry-DJbrsZ4u.d.cts}

@@ -59,6 +59,13 @@ declare const PONG_TEXT: "{\"type\":\"pong\"}";
 declare const CloseCode: {
     readonly NORMAL: 1000;
     readonly GOING_AWAY: 1001;
+    /** Never sent by anyone: what a socket reports when it drops without a close frame. A relay
+     *  deploy (every Durable Object restarts) arrives as this — reconnect immediately. */
+    readonly ABNORMAL: 1006;
+    /** Relay → clients: the device (re)connected, so the core session they spoke to is gone —
+     *  reconnect, hello, and reattach with since_seq. */
+    readonly DEVICE_RECONNECTED: 1012;
+    readonly TRY_AGAIN_LATER: 1013;
     readonly AUTH_INVALID: 4001;
     readonly AUTH_FORBIDDEN: 4003;
     readonly DEVICE_NOT_FOUND: 4004;
@@ -68,6 +75,9 @@ declare const CloseCode: {
     readonly PROTOCOL_ERROR: 4400;
     readonly UPGRADE_REQUIRED: 4426;
 };
+/** Every close code above, as a schema (so Python sees the same table). */
+declare const CloseCodeValue: z.ZodLiteral<1000 | 1001 | 1006 | 1012 | 1013 | 4001 | 4003 | 4004 | 4008 | 4009 | 4010 | 4400 | 4426>;
+type CloseCodeValue = z.output<typeof CloseCodeValue>;
 declare const ClientType: z.ZodEnum<{
     screen: "screen";
     web: "web";
@@ -2324,7 +2334,38 @@ declare const NAMED_SCHEMAS: {
             }, z.core.$strict>>;
         }, z.core.$strict>;
     }, z.core.$strict>], "ok">;
+    readonly RelayCallHello: z.ZodObject<{
+        type: z.ZodLiteral<"hello">;
+        id: z.ZodLiteral<"hello">;
+        protocolVersion: z.ZodString;
+        clientType: z.ZodLiteral<"server">;
+        clientVersion: z.ZodString;
+    }, z.core.$strict>;
+    readonly RelayCallEnvelope: z.ZodObject<{
+        id: z.ZodLiteral<"call">;
+        type: z.ZodLiteral<"request">;
+        cap: z.ZodString;
+        op: z.ZodString;
+        params: z.ZodUnknown;
+    }, z.core.$strict>;
+    readonly RelayHopEnvelopeHeader: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        flags: z.ZodLiteral<0>;
+        channel: z.ZodLiteral<255>;
+        cid: z.ZodInt;
+        sid: z.ZodLiteral<0>;
+        seq: z.ZodLiteral<0>;
+    }, z.core.$strict>;
+    readonly RelayHopConnectionEnd: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        flags: z.ZodLiteral<1>;
+        channel: z.ZodLiteral<255>;
+        cid: z.ZodInt;
+        sid: z.ZodLiteral<0>;
+        seq: z.ZodLiteral<0>;
+    }, z.core.$strict>;
+    readonly CloseCodeValue: z.ZodLiteral<1000 | 1001 | 1006 | 1012 | 1013 | 4001 | 4003 | 4004 | 4008 | 4009 | 4010 | 4400 | 4426>;
 };
 type NamedSchemaId = keyof typeof NAMED_SCHEMAS;
 
-export { StreamMsg as A, ClientType as C, DesktopProtocolError as D, EndReason as E, HelloMsg as H, Limits as L, NAMED_SCHEMAS as N, type OpName as O, PING_TEXT as P, RelayMsg as R, StreamMeta as S, Welcome as W, type OpParams as a, type OpResult as b, OPS as c, EVENTS as d, CancelMsg as e, ClientToCoreMsg as f, CloseCode as g, CoreToClientMsg as h, isDesktopProtocolError as i, CreditMsg as j, EndMsg as k, ErrorCode as l, type ErrorCodeName as m, type ErrorData as n, ErrorMsg as o, ErrorReason as p, type ErrorReasonName as q, EventMsg as r, type EventName as s, type NamedSchemaId as t, OpDescriptor as u, type OpSpec as v, PONG_TEXT as w, ProtocolErrorBody as x, RequestMsg as y, ResponseMsg as z };
+export { ResponseMsg as A, StreamMsg as B, ClientType as C, DesktopProtocolError as D, EndReason as E, HelloMsg as H, Limits as L, NAMED_SCHEMAS as N, type OpName as O, PING_TEXT as P, RelayMsg as R, StreamMeta as S, Welcome as W, type OpParams as a, type OpResult as b, OPS as c, EVENTS as d, CancelMsg as e, ClientToCoreMsg as f, CloseCode as g, CloseCodeValue as h, isDesktopProtocolError as i, CoreToClientMsg as j, CreditMsg as k, EndMsg as l, ErrorCode as m, type ErrorCodeName as n, type ErrorData as o, ErrorMsg as p, ErrorReason as q, type ErrorReasonName as r, EventMsg as s, type EventName as t, type NamedSchemaId as u, OpDescriptor as v, type OpSpec as w, PONG_TEXT as x, ProtocolErrorBody as y, RequestMsg as z };

package/dist/{registry-DTcTGycI.d.ts → registry-DJbrsZ4u.d.ts}

@@ -59,6 +59,13 @@ declare const PONG_TEXT: "{\"type\":\"pong\"}";
 declare const CloseCode: {
     readonly NORMAL: 1000;
     readonly GOING_AWAY: 1001;
+    /** Never sent by anyone: what a socket reports when it drops without a close frame. A relay
+     *  deploy (every Durable Object restarts) arrives as this — reconnect immediately. */
+    readonly ABNORMAL: 1006;
+    /** Relay → clients: the device (re)connected, so the core session they spoke to is gone —
+     *  reconnect, hello, and reattach with since_seq. */
+    readonly DEVICE_RECONNECTED: 1012;
+    readonly TRY_AGAIN_LATER: 1013;
     readonly AUTH_INVALID: 4001;
     readonly AUTH_FORBIDDEN: 4003;
     readonly DEVICE_NOT_FOUND: 4004;
@@ -68,6 +75,9 @@ declare const CloseCode: {
     readonly PROTOCOL_ERROR: 4400;
     readonly UPGRADE_REQUIRED: 4426;
 };
+/** Every close code above, as a schema (so Python sees the same table). */
+declare const CloseCodeValue: z.ZodLiteral<1000 | 1001 | 1006 | 1012 | 1013 | 4001 | 4003 | 4004 | 4008 | 4009 | 4010 | 4400 | 4426>;
+type CloseCodeValue = z.output<typeof CloseCodeValue>;
 declare const ClientType: z.ZodEnum<{
     screen: "screen";
     web: "web";
@@ -2324,7 +2334,38 @@ declare const NAMED_SCHEMAS: {
             }, z.core.$strict>>;
         }, z.core.$strict>;
     }, z.core.$strict>], "ok">;
+    readonly RelayCallHello: z.ZodObject<{
+        type: z.ZodLiteral<"hello">;
+        id: z.ZodLiteral<"hello">;
+        protocolVersion: z.ZodString;
+        clientType: z.ZodLiteral<"server">;
+        clientVersion: z.ZodString;
+    }, z.core.$strict>;
+    readonly RelayCallEnvelope: z.ZodObject<{
+        id: z.ZodLiteral<"call">;
+        type: z.ZodLiteral<"request">;
+        cap: z.ZodString;
+        op: z.ZodString;
+        params: z.ZodUnknown;
+    }, z.core.$strict>;
+    readonly RelayHopEnvelopeHeader: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        flags: z.ZodLiteral<0>;
+        channel: z.ZodLiteral<255>;
+        cid: z.ZodInt;
+        sid: z.ZodLiteral<0>;
+        seq: z.ZodLiteral<0>;
+    }, z.core.$strict>;
+    readonly RelayHopConnectionEnd: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        flags: z.ZodLiteral<1>;
+        channel: z.ZodLiteral<255>;
+        cid: z.ZodInt;
+        sid: z.ZodLiteral<0>;
+        seq: z.ZodLiteral<0>;
+    }, z.core.$strict>;
+    readonly CloseCodeValue: z.ZodLiteral<1000 | 1001 | 1006 | 1012 | 1013 | 4001 | 4003 | 4004 | 4008 | 4009 | 4010 | 4400 | 4426>;
 };
 type NamedSchemaId = keyof typeof NAMED_SCHEMAS;
 
-export { StreamMsg as A, ClientType as C, DesktopProtocolError as D, EndReason as E, HelloMsg as H, Limits as L, NAMED_SCHEMAS as N, type OpName as O, PING_TEXT as P, RelayMsg as R, StreamMeta as S, Welcome as W, type OpParams as a, type OpResult as b, OPS as c, EVENTS as d, CancelMsg as e, ClientToCoreMsg as f, CloseCode as g, CoreToClientMsg as h, isDesktopProtocolError as i, CreditMsg as j, EndMsg as k, ErrorCode as l, type ErrorCodeName as m, type ErrorData as n, ErrorMsg as o, ErrorReason as p, type ErrorReasonName as q, EventMsg as r, type EventName as s, type NamedSchemaId as t, OpDescriptor as u, type OpSpec as v, PONG_TEXT as w, ProtocolErrorBody as x, RequestMsg as y, ResponseMsg as z };
+export { ResponseMsg as A, StreamMsg as B, ClientType as C, DesktopProtocolError as D, EndReason as E, HelloMsg as H, Limits as L, NAMED_SCHEMAS as N, type OpName as O, PING_TEXT as P, RelayMsg as R, StreamMeta as S, Welcome as W, type OpParams as a, type OpResult as b, OPS as c, EVENTS as d, CancelMsg as e, ClientToCoreMsg as f, CloseCode as g, CloseCodeValue as h, isDesktopProtocolError as i, CoreToClientMsg as j, CreditMsg as k, EndMsg as l, ErrorCode as m, type ErrorCodeName as n, type ErrorData as o, ErrorMsg as p, ErrorReason as q, type ErrorReasonName as r, EventMsg as s, type EventName as t, type NamedSchemaId as u, OpDescriptor as v, type OpSpec as w, PONG_TEXT as x, ProtocolErrorBody as y, RequestMsg as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/desktop-protocol",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The one wire contract between Matrx 2 (the desktop app) and every client that drives it — phone, web app, extension, server: zod schemas for the envelope and every cap.op, the 16-byte binary frame codec, a reconnecting request/stream/credit/reattach client, React hooks, and a generated JSON Schema + Pydantic twin that CI keeps byte-identical.",
   "type": "module",
   "main": "./dist/index.cjs",