@garretapp/sdk 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @garretapp/sdk
+
+Build widgets for **Garret** — the desktop widget layer. One SDK for a widget's UI (React hooks +
+a native design system) and its optional host (raw Node).
+
+```bash
+npm install @garretapp/sdk
+```
+
+## UI (React)
+
+`@garretapp/sdk/react` gives you hooks to talk to Garret plus a generic component library that matches
+the native macOS look. Link the app-served theme once and compose:
+
+```tsx
+import { createRoot } from 'react-dom/client'
+import {
+  useGarret, useActive, useInstanceConfig, useOpenSettings,
+  Scroll, Item, Accordion, Badge, Dot, EmptyState, ErrorState,
+  SettingsPanel, FieldGroup, Field, TextInput, Select, Switch
+} from '@garretapp/sdk/react'
+
+function Widget() {
+  const g = useGarret()
+  const { cfg, set, loaded } = useInstanceConfig({ query: '' })
+  // g.fetch (brokered), g.shared.storage/secrets, g.instanceStorage, g.openExternal, …
+  return <Scroll>{/* compose Item / Badge / Dot / … */}</Scroll>
+}
+createRoot(document.getElementById('root')!).render(<Widget />)
+```
+
+```html
+<!-- served by Garret on your widget's own origin -->
+<link rel="stylesheet" href="~theme.css" />
+```
+
+**Hooks:** `useGarret`, `useActive`, `useOpenSettings`, `useInstanceConfig`, `useConfig`, `useProps`,
+`useHost`, `useHostEvent`, `useStream`.
+
+**Components (generic building blocks):** `Scroll`, `Item`, `Accordion`, `Badge`, `Dot`,
+`EmptyState`, `ErrorState`, `SettingsPanel`, `FieldGroup`, `Field`, `TextInput`, `NumberInput`,
+`Select`, `Switch`. Tones are generic — `neutral | accent | success | warning | danger` — you map
+your domain to them.
+
+`@garretapp/sdk/ui` exposes the same platform without React (`getGarret()`).
+
+## Host (Node)
+
+`@garretapp/sdk/host` — `defineHost()` for widgets that ship a raw-Node backend (spawn processes,
+native deps). Optional; pure-UI widgets don't need it.
+
+## Capabilities
+
+A widget declares what it can reach in its `garret.manifest.json` (`network:<host>`, `secrets`,
+`openExternal`, `embed`, `windows`, …); Garret enforces them in its main process.
+
+MIT © Sudharsan Selvaraj

package/dist/chunk-ENIDFSMM.js

@@ -0,0 +1,29 @@
+// src/errors.ts
+var GarretError = class _GarretError extends Error {
+  code;
+  hint;
+  constructor(code, message, options) {
+    super(message);
+    this.name = "GarretError";
+    this.code = code;
+    this.hint = options?.hint;
+    Object.setPrototypeOf(this, _GarretError.prototype);
+  }
+};
+function garretErrorFromWire(code, message, hint) {
+  const known = [
+    "BINARY_NOT_FOUND",
+    "NOT_FOUND",
+    "PERMISSION",
+    "UNAVAILABLE",
+    "BAD_ARGS",
+    "TIMEOUT",
+    "CANCELLED",
+    "NETWORK",
+    "INTERNAL"
+  ];
+  const c = known.includes(code) ? code : "INTERNAL";
+  return new GarretError(c, message, hint ? { hint } : void 0);
+}
+
+export { GarretError, garretErrorFromWire };

package/dist/chunk-RZJO3X6O.js

@@ -0,0 +1,9 @@
+// src/types.ts
+function defineManifest(manifest) {
+  return manifest;
+}
+function defineConfig(schema) {
+  return schema;
+}
+
+export { defineConfig, defineManifest };

package/dist/chunk-ZJYHRC5C.js

@@ -0,0 +1,206 @@
+import { GarretError, garretErrorFromWire } from './chunk-ENIDFSMM.js';
+
+// src/client.ts
+var MAX_PREATTACH_CHUNKS = 1e3;
+var IDLE_TIMEOUT_MS = 3e4;
+function createHostClient(transport, opts) {
+  const calls = /* @__PURE__ */ new Map();
+  const events = /* @__PURE__ */ new Map();
+  const eventBuffer = /* @__PURE__ */ new Map();
+  let seq = 0;
+  const nextId = () => `${opts.instanceId}:${++seq}`;
+  const settle = (id, fn) => {
+    const s = calls.get(id);
+    if (!s) return;
+    clearTimeout(s.timer);
+    calls.delete(id);
+    fn(s);
+  };
+  const timeoutError = (method) => new GarretError("TIMEOUT", `"${method}" timed out`);
+  const off = transport.onMessage((msg) => {
+    switch (msg.t) {
+      case "res":
+        settle(msg.id, (s) => s.resolve(msg.result));
+        break;
+      case "stream_end":
+        settle(msg.id, (s) => {
+          s.onEnd.forEach((cb) => cb(msg.result));
+          s.resolve(msg.result);
+        });
+        break;
+      case "err":
+        settle(msg.id, (s) => {
+          const e = garretErrorFromWire(msg.code, msg.message, msg.hint);
+          s.onError.forEach((cb) => cb(e));
+          s.reject(e);
+        });
+        break;
+      case "stream_err":
+        settle(msg.id, (s) => {
+          const e = garretErrorFromWire(msg.code, msg.message);
+          s.onError.forEach((cb) => cb(e));
+          s.reject(e);
+        });
+        break;
+      case "chunk": {
+        const s = calls.get(msg.id);
+        if (!s) break;
+        clearTimeout(s.timer);
+        s.timer = setTimeout(() => settle(msg.id, (st) => st.reject(timeoutError(msg.id))), IDLE_TIMEOUT_MS);
+        if (s.onData.length) s.onData.forEach((cb) => cb(msg.data));
+        else if (s.buffer.length < MAX_PREATTACH_CHUNKS) s.buffer.push(msg.data);
+        else s.overflow = true;
+        break;
+      }
+      case "event": {
+        const subs = events.get(msg.channel);
+        if (subs && subs.size) subs.forEach((cb) => cb(msg.payload));
+        else {
+          const buf = eventBuffer.get(msg.channel) ?? [];
+          if (buf.length < 100) buf.push(msg.payload);
+          eventBuffer.set(msg.channel, buf);
+        }
+        break;
+      }
+    }
+  });
+  function makeCall(method, args) {
+    const id = nextId();
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    promise.catch(() => {
+    });
+    const s = {
+      onData: [],
+      onEnd: [],
+      onError: [],
+      buffer: [],
+      overflow: false,
+      resolve,
+      reject,
+      timer: setTimeout(() => {
+        const e = timeoutError(method);
+        settle(id, (st) => {
+          st.onError.forEach((cb) => cb(e));
+          st.reject(e);
+        });
+      }, IDLE_TIMEOUT_MS)
+    };
+    calls.set(id, s);
+    transport.send({ t: "req", id, method, args });
+    const flush = (cb) => {
+      const buf = s.buffer;
+      s.buffer = [];
+      buf.forEach((c) => cb(c));
+    };
+    const call = {
+      then: (onF, onR) => promise.then(onF, onR),
+      catch: (onR) => promise.catch(onR),
+      finally: (cb) => promise.finally(cb),
+      result: () => promise,
+      onData(cb) {
+        s.onData.push(cb);
+        flush(cb);
+        return call;
+      },
+      onEnd(cb) {
+        s.onEnd.push(cb);
+        return call;
+      },
+      onError(cb) {
+        s.onError.push(cb);
+        return call;
+      },
+      cancel() {
+        if (!calls.has(id)) return;
+        clearTimeout(s.timer);
+        calls.delete(id);
+        transport.send({ t: "cancel", id });
+      }
+    };
+    return call;
+  }
+  const base = {
+    on(channel, cb) {
+      let set = events.get(channel);
+      if (!set) events.set(channel, set = /* @__PURE__ */ new Set());
+      set.add(cb);
+      const buffered = eventBuffer.get(channel);
+      if (buffered?.length) {
+        eventBuffer.delete(channel);
+        buffered.forEach((p) => cb(p));
+      }
+      return () => set.delete(cb);
+    },
+    dispose() {
+      off();
+      for (const s of calls.values()) clearTimeout(s.timer);
+      calls.clear();
+      events.clear();
+      eventBuffer.clear();
+    }
+  };
+  return new Proxy(base, {
+    get(target, prop) {
+      if (prop in target) return target[prop];
+      return (args) => makeCall(prop, args);
+    }
+  });
+}
+
+// src/platform.ts
+function getRuntime() {
+  return typeof window !== "undefined" ? window.__garret : void 0;
+}
+function getHostTransport() {
+  return getRuntime()?.hostTransport ?? null;
+}
+function getInstanceId() {
+  return getRuntime()?.instanceId ?? "dev";
+}
+function nope() {
+  throw new GarretError("UNAVAILABLE", "not running inside Garret");
+}
+var stubStorage = { get: nope, set: nope, delete: nope, keys: nope, clear: nope };
+var stubSecrets = { get: nope, set: nope, delete: nope };
+function getGarret() {
+  const rt = getRuntime();
+  if (rt) return rt;
+  return {
+    inGarret: false,
+    storage: stubStorage,
+    instanceStorage: stubStorage,
+    secrets: stubSecrets,
+    shared: { storage: stubStorage, secrets: stubSecrets },
+    fetch: async () => {
+      throw new GarretError("UNAVAILABLE", "g.fetch is only available inside Garret");
+    },
+    service: () => ({ status: nope, query: nope }),
+    notify: () => {
+    },
+    openExternal: async () => false,
+    clipboard: { readText: nope, writeText: nope },
+    active: true,
+    onActiveChange: () => () => {
+    },
+    onOpenSettings: () => () => {
+    },
+    surfaces: { open: nope, onClosed: () => () => {
+    } },
+    window: { setAspectRatio: () => {
+    }, resize: () => {
+    }, close: () => {
+    } },
+    onReady: (cb) => {
+      cb({});
+      return () => {
+      };
+    }
+  };
+}
+
+export { createHostClient, getGarret, getHostTransport, getInstanceId, getRuntime };

package/dist/host.cjs

@@ -0,0 +1,263 @@
+'use strict';
+
+var child_process = require('child_process');
+var fs = require('fs');
+var path = require('path');
+var crypto = require('crypto');
+
+// src/host.ts
+
+// src/errors.ts
+var GarretError = class _GarretError extends Error {
+  code;
+  hint;
+  constructor(code, message, options) {
+    super(message);
+    this.name = "GarretError";
+    this.code = code;
+    this.hint = options?.hint;
+    Object.setPrototypeOf(this, _GarretError.prototype);
+  }
+};
+
+// src/host.ts
+var port = globalThis.process?.parentPort;
+function send(msg) {
+  port?.postMessage(msg);
+}
+var STREAM_RUNTIME = /* @__PURE__ */ Symbol("garret.stream");
+function isStream(v) {
+  return typeof v === "object" && v !== null && STREAM_RUNTIME in v;
+}
+function defineHost(factory) {
+  const children = /* @__PURE__ */ new Set();
+  const disposers = [];
+  const streams = /* @__PURE__ */ new Map();
+  let disposed = false;
+  const scrubbedEnv = (base) => {
+    const env = {};
+    for (const [k, v] of Object.entries(base)) if (!k.startsWith("GARRET_")) env[k] = v;
+    return env;
+  };
+  const track = (child) => {
+    children.add(child);
+    child.on("exit", () => children.delete(child));
+    const r = child;
+    r.text = () => new Promise((resolve, reject) => {
+      let out = "";
+      child.stdout?.on("data", (d) => out += d.toString());
+      child.on("error", reject);
+      child.on("close", () => resolve(out));
+    });
+    return r;
+  };
+  const ctx = {
+    emit: (channel, payload) => send({ t: "event", channel, payload }),
+    stream: (fn) => ({ [STREAM_RUNTIME]: fn }),
+    // Scrub GARRET_* from the FINAL merged env, always — a caller-supplied opts.env must never
+    // reopen the leak (the vault key would otherwise reach adb/scrcpy/shells the author didn't write).
+    spawn: (argv, opts) => track(
+      child_process.spawn(argv[0], argv.slice(1), {
+        ...opts,
+        shell: false,
+        env: scrubbedEnv({ ...process.env, ...opts?.env ?? {} })
+      })
+    ),
+    spawnShell: (command, opts) => track(child_process.spawn(command, { ...opts, shell: true, env: scrubbedEnv({ ...process.env, ...opts?.env ?? {} }) })),
+    resolveBinary,
+    storage: makeStorage(dataDir),
+    secrets: makeSecrets(dataDir, secretKey),
+    // Pack-shared store only when the host was launched with GARRET_PACK_SHARED_DIR (pack declares `shared`).
+    shared: process.env.GARRET_PACK_SHARED_DIR ? { storage: makeStorage(sharedDir), secrets: makeSecrets(sharedDir, sharedSecretKey) } : void 0,
+    fetch: (...a) => fetch(...a),
+    onDispose: (cb) => disposers.push(cb),
+    log: (...args) => console.error("[host]", ...args)
+  };
+  async function runDispose() {
+    if (disposed) return;
+    disposed = true;
+    for (const ac of streams.values()) ac.abort();
+    for (const cb of disposers) {
+      try {
+        await cb();
+      } catch {
+      }
+    }
+    for (const c of children) c.kill();
+    process.exit(0);
+  }
+  function driveStream(id, fn) {
+    const ac = new AbortController();
+    streams.set(id, ac);
+    const done = (final) => {
+      if (!streams.has(id)) return;
+      streams.delete(id);
+      final();
+    };
+    const out = {
+      push: (chunk) => streams.has(id) && send({ t: "chunk", id, data: chunk }),
+      end: (result) => done(() => send({ t: "stream_end", id, result })),
+      error: (err) => done(() => send({ t: "stream_err", id, ...wireError(err) }))
+    };
+    Promise.resolve().then(() => fn(out, ac.signal)).catch((err) => out.error(err));
+  }
+  async function handleCall(id, method, args) {
+    const methods = ready;
+    const fn = methods?.[method];
+    if (typeof fn !== "function") {
+      return send({ t: "err", id, code: "BAD_ARGS", message: `unknown method: ${method}` });
+    }
+    try {
+      const result = await fn(args);
+      if (isStream(result)) driveStream(id, result[STREAM_RUNTIME]);
+      else send({ t: "res", id, result });
+    } catch (err) {
+      send({ t: "err", id, ...wireError(err) });
+    }
+  }
+  let ready;
+  port?.on("message", (e) => {
+    const msg = e.data;
+    if (!msg || typeof msg !== "object") return;
+    switch (msg.t) {
+      case "req":
+      case "stream_start":
+        void handleCall(msg.id, msg.method, msg.args);
+        break;
+      case "cancel":
+        streams.get(msg.id)?.abort();
+        streams.delete(msg.id);
+        break;
+      case "dispose":
+        void runDispose();
+        break;
+    }
+  });
+  process.on("SIGTERM", () => void runDispose());
+  Promise.resolve().then(() => factory(ctx)).then((methods) => {
+    ready = methods;
+    send({ t: "ready" });
+  }).catch((err) => {
+    console.error("[host] factory failed during startup:", err);
+    process.exit(1);
+  });
+}
+function wireError(err) {
+  if (err instanceof GarretError) return { code: err.code, message: err.message, hint: err.hint };
+  if (err instanceof Error && err.name === "AbortError") return { code: "CANCELLED", message: err.message };
+  return { code: "INTERNAL", message: err instanceof Error ? err.message : String(err) };
+}
+var PROBE = {
+  darwin: ["/opt/homebrew/bin", "/usr/local/bin", "/opt/homebrew/sbin"],
+  linux: ["/usr/local/bin", "/usr/bin", "/snap/bin", `${process.env.HOME}/.local/bin`],
+  win32: [`${process.env.LOCALAPPDATA}\\Microsoft\\WinGet\\Packages`, "C:\\ProgramData\\chocolatey\\bin"]
+};
+async function resolveBinary(name, opts) {
+  const platform = process.platform;
+  const exe = platform === "win32" ? `${name}.exe` : name;
+  const dirs = [...process.env.PATH?.split(path.delimiter) ?? [], ...PROBE[platform] ?? []];
+  for (const dir of dirs) {
+    if (!dir || dir.includes("undefined")) continue;
+    const full = path.join(dir, exe);
+    try {
+      fs.accessSync(full, fs.constants.X_OK);
+      return full;
+    } catch {
+    }
+  }
+  throw new GarretError("BINARY_NOT_FOUND", `${name} not found on PATH`, {
+    hint: opts?.hint ?? `install ${name} via your package manager`
+  });
+}
+function dirFromEnv(name) {
+  const dir = process.env[name];
+  if (!dir) throw new GarretError("UNAVAILABLE", "storage/secrets unavailable (no data dir)");
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+var dataDir = () => dirFromEnv("GARRET_EXT_DATA_DIR");
+var sharedDir = () => dirFromEnv("GARRET_PACK_SHARED_DIR");
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeJsonAtomic(file, obj) {
+  const tmp = `${file}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(obj));
+  fs.renameSync(tmp, file);
+}
+function makeChain() {
+  let chain = Promise.resolve();
+  return (fn) => {
+    const next = chain.then(fn, fn);
+    chain = next.catch(() => void 0);
+    return next;
+  };
+}
+function makeStorage(dir) {
+  const queue = makeChain();
+  const file = () => path.join(dir(), "storage.json");
+  return {
+    get: async (key) => readJson(file())[key],
+    set: (key, value) => queue(() => {
+      const f = file();
+      const all = readJson(f);
+      all[key] = value;
+      writeJsonAtomic(f, all);
+    }),
+    delete: (key) => queue(() => {
+      const f = file();
+      const all = readJson(f);
+      delete all[key];
+      writeJsonAtomic(f, all);
+    }),
+    keys: async () => Object.keys(readJson(file())),
+    clear: () => queue(() => writeJsonAtomic(file(), {}))
+  };
+}
+function keyFromEnv(name) {
+  const hex = process.env[name];
+  if (!hex) throw new GarretError("UNAVAILABLE", "secrets unavailable on this platform");
+  return Buffer.from(hex, "hex");
+}
+var secretKey = () => keyFromEnv("GARRET_EXT_SECRET_KEY");
+var sharedSecretKey = () => keyFromEnv("GARRET_PACK_SHARED_KEY");
+function makeSecrets(dir, getKey) {
+  const queue = makeChain();
+  const file = () => path.join(dir(), "secrets.json");
+  return {
+    get: async (key) => {
+      const box = readJson(file())[key];
+      if (!box) return void 0;
+      const decipher = crypto.createDecipheriv("aes-256-gcm", getKey(), Buffer.from(box.iv, "base64"));
+      decipher.setAuthTag(Buffer.from(box.tag, "base64"));
+      try {
+        return decipher.update(Buffer.from(box.ct, "base64")).toString("utf8") + decipher.final("utf8");
+      } catch {
+        throw new GarretError("INTERNAL", `secret "${key}" failed to decrypt`);
+      }
+    },
+    set: (key, value) => queue(() => {
+      const iv = crypto.randomBytes(12);
+      const cipher = crypto.createCipheriv("aes-256-gcm", getKey(), iv);
+      const ct = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+      const box = { v: 1, iv: iv.toString("base64"), tag: cipher.getAuthTag().toString("base64"), ct: ct.toString("base64") };
+      const f = file();
+      const all = readJson(f);
+      all[key] = box;
+      writeJsonAtomic(f, all);
+    }),
+    delete: (key) => queue(() => {
+      const f = file();
+      const all = readJson(f);
+      delete all[key];
+      writeJsonAtomic(f, all);
+    })
+  };
+}
+
+exports.GarretError = GarretError;
+exports.defineHost = defineHost;

package/dist/host.d.cts

@@ -0,0 +1,54 @@
+import { SpawnOptions, ChildProcess } from 'node:child_process';
+import { E as EventMap, S as Stream } from './types-BxSYAH_H.cjs';
+export { G as GarretError } from './types-BxSYAH_H.cjs';
+
+interface StreamOut<Chunk, Result> {
+    push(chunk: Chunk): void;
+    end(result: Result): void;
+    error(err: unknown): void;
+}
+type StreamFn<Chunk, Result> = (out: StreamOut<Chunk, Result>, signal: AbortSignal) => void | Promise<void>;
+/** A ChildProcess with a convenience `.text()` (buffers stdout to a string). */
+interface SpawnResult extends ChildProcess {
+    text(): Promise<string>;
+}
+interface Storage {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+    clear(): Promise<void>;
+}
+interface Secrets {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+interface HostContext<Events extends EventMap = EventMap> {
+    emit<K extends keyof Events & string>(channel: K, payload: Events[K]): void;
+    stream<Chunk, Result = void>(fn: StreamFn<Chunk, Result>): Stream<Chunk, Result>;
+    spawn(argv: string[], opts?: SpawnOptions): SpawnResult;
+    spawnShell(command: string, opts?: SpawnOptions): SpawnResult;
+    resolveBinary(name: string, opts?: {
+        hint?: string;
+    }): Promise<string>;
+    storage: Storage;
+    secrets: Secrets;
+    /** Pack-shared storage/secrets — present ONLY when the pack declares a `shared` namespace. All the
+     *  pack's widgets read/write the same store (e.g. one account token); isolated from other packs. */
+    shared?: {
+        storage: Storage;
+        secrets: Secrets;
+    };
+    fetch: typeof fetch;
+    onDispose(cb: () => void | Promise<void>): void;
+    log(...args: unknown[]): void;
+}
+type Methods<Api> = Record<keyof Api, (args?: any) => any>;
+/**
+ * Define your host. `factory(ctx)` returns the methods your UI calls (use function declarations so
+ * a method can call a sibling — see docs P9). May be async; `ready` is sent only after it resolves.
+ */
+declare function defineHost<Api extends Methods<Api>, Events extends EventMap = EventMap>(factory: (ctx: HostContext<Events>) => Api | Promise<Api>): void;
+
+export { type HostContext, type Secrets, type SpawnResult, type Storage, Stream, type StreamFn, type StreamOut, defineHost };

package/dist/host.d.ts

@@ -0,0 +1,54 @@
+import { SpawnOptions, ChildProcess } from 'node:child_process';
+import { E as EventMap, S as Stream } from './types-BxSYAH_H.js';
+export { G as GarretError } from './types-BxSYAH_H.js';
+
+interface StreamOut<Chunk, Result> {
+    push(chunk: Chunk): void;
+    end(result: Result): void;
+    error(err: unknown): void;
+}
+type StreamFn<Chunk, Result> = (out: StreamOut<Chunk, Result>, signal: AbortSignal) => void | Promise<void>;
+/** A ChildProcess with a convenience `.text()` (buffers stdout to a string). */
+interface SpawnResult extends ChildProcess {
+    text(): Promise<string>;
+}
+interface Storage {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+    clear(): Promise<void>;
+}
+interface Secrets {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+interface HostContext<Events extends EventMap = EventMap> {
+    emit<K extends keyof Events & string>(channel: K, payload: Events[K]): void;
+    stream<Chunk, Result = void>(fn: StreamFn<Chunk, Result>): Stream<Chunk, Result>;
+    spawn(argv: string[], opts?: SpawnOptions): SpawnResult;
+    spawnShell(command: string, opts?: SpawnOptions): SpawnResult;
+    resolveBinary(name: string, opts?: {
+        hint?: string;
+    }): Promise<string>;
+    storage: Storage;
+    secrets: Secrets;
+    /** Pack-shared storage/secrets — present ONLY when the pack declares a `shared` namespace. All the
+     *  pack's widgets read/write the same store (e.g. one account token); isolated from other packs. */
+    shared?: {
+        storage: Storage;
+        secrets: Secrets;
+    };
+    fetch: typeof fetch;
+    onDispose(cb: () => void | Promise<void>): void;
+    log(...args: unknown[]): void;
+}
+type Methods<Api> = Record<keyof Api, (args?: any) => any>;
+/**
+ * Define your host. `factory(ctx)` returns the methods your UI calls (use function declarations so
+ * a method can call a sibling — see docs P9). May be async; `ready` is sent only after it resolves.
+ */
+declare function defineHost<Api extends Methods<Api>, Events extends EventMap = EventMap>(factory: (ctx: HostContext<Events>) => Api | Promise<Api>): void;
+
+export { type HostContext, type Secrets, type SpawnResult, type Storage, Stream, type StreamFn, type StreamOut, defineHost };