@garretapp/sdk 0.1.0

package/dist/react.cjs

@@ -0,0 +1,496 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/react.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);
+  }
+};
+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);
+}
+
+// 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 () => {
+      };
+    }
+  };
+}
+function EmptyState({ children }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "gx-empty", children });
+}
+function ErrorState({ children }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "gx-error", children });
+}
+function Scroll({ children }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "gx-scroll", children });
+}
+function Item({
+  leading,
+  trailing,
+  onClick,
+  onContextMenu,
+  children
+}) {
+  const cls = `gx-item${onClick ? " gx-item--interactive" : ""}`;
+  const inner = /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    leading,
+    /* @__PURE__ */ jsxRuntime.jsx("span", { className: "gx-item-content", children }),
+    trailing
+  ] });
+  return onClick ? /* @__PURE__ */ jsxRuntime.jsx("button", { className: cls, onClick, onContextMenu, children: inner }) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: cls, onContextMenu, children: inner });
+}
+function Accordion({
+  title,
+  aside,
+  defaultOpen = true,
+  children
+}) {
+  const [open, setOpen] = react.useState(defaultOpen);
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { children: [
+    /* @__PURE__ */ jsxRuntime.jsxs("button", { className: "gx-accordion-head", onClick: () => setOpen((o) => !o), children: [
+      /* @__PURE__ */ jsxRuntime.jsx(
+        "svg",
+        {
+          width: "11",
+          height: "11",
+          viewBox: "0 0 24 24",
+          fill: "none",
+          stroke: "currentColor",
+          strokeWidth: 2.5,
+          strokeLinecap: "round",
+          strokeLinejoin: "round",
+          style: { color: "var(--gx-text-3)", flexShrink: 0, transform: open ? "rotate(90deg)" : "", transition: "transform .12s" },
+          children: /* @__PURE__ */ jsxRuntime.jsx("polyline", { points: "9 6 15 12 9 18" })
+        }
+      ),
+      /* @__PURE__ */ jsxRuntime.jsx("span", { className: "gx-accordion-title", children: title }),
+      aside != null && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "gx-accordion-aside", children: aside })
+    ] }),
+    open && /* @__PURE__ */ jsxRuntime.jsx("div", { children })
+  ] });
+}
+function Badge({ tone = "neutral", children }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("span", { className: `gx-badge gx-badge--${tone}`, children });
+}
+function Dot({ tone = "neutral", title }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("span", { className: `gx-dot gx-dot--${tone}`, title });
+}
+function SettingsPanel({ onDone, children }) {
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "gx-form", children: [
+    children,
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "gx-form-footer", children: [
+      /* @__PURE__ */ jsxRuntime.jsx("span", { className: "gx-form-note", children: "Changes save automatically" }),
+      /* @__PURE__ */ jsxRuntime.jsx("button", { className: "gx-btn", onClick: onDone, children: "Done" })
+    ] })
+  ] });
+}
+function FieldGroup({ label, children }) {
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "gx-group-wrap", children: [
+    label != null && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "gx-group-label", children: label }),
+    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "gx-group", children })
+  ] });
+}
+function Field({ label, children }) {
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "gx-field", children: [
+    /* @__PURE__ */ jsxRuntime.jsx("label", { className: "gx-field-label", children: label }),
+    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "gx-field-control", children })
+  ] });
+}
+function TextInput({
+  value,
+  placeholder,
+  secret,
+  onCommit
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "input",
+    {
+      className: "gx-input",
+      type: secret ? "password" : "text",
+      defaultValue: value,
+      placeholder,
+      onBlur: (e) => onCommit(e.target.value),
+      onKeyDown: (e) => e.key === "Enter" && onCommit(e.target.value)
+    }
+  );
+}
+function NumberInput({ value, onCommit }) {
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "input",
+    {
+      className: "gx-input",
+      type: "number",
+      defaultValue: value == null ? "" : String(value),
+      onBlur: (e) => onCommit(Number(e.target.value) || 0)
+    }
+  );
+}
+function Select({
+  value,
+  options,
+  onChange
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx("select", { className: "gx-select", value, onChange: (e) => onChange(e.target.value), children: options.map(([v, label]) => /* @__PURE__ */ jsxRuntime.jsx("option", { value: v, children: label }, v)) });
+}
+function Switch({ on, onChange }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("button", { className: `gx-switch${on ? " gx-switch--on" : ""}`, role: "switch", "aria-checked": on, onClick: () => onChange(!on), children: /* @__PURE__ */ jsxRuntime.jsx("span", { className: "gx-switch-knob" }) });
+}
+
+// src/react.ts
+var singleton;
+function hostClient() {
+  if (!singleton) {
+    const transport = getHostTransport();
+    if (!transport) throw new GarretError("UNAVAILABLE", "this extension has no host process");
+    singleton = createHostClient(transport, { instanceId: getInstanceId() });
+  }
+  return singleton;
+}
+function useHost() {
+  return react.useMemo(() => hostClient(), []);
+}
+function useGarret() {
+  return getGarret();
+}
+function useHostEvent(channel, handler, deps = []) {
+  react.useEffect(() => {
+    const off = hostClient().on(channel, handler);
+    return off;
+  }, [channel, ...deps]);
+}
+function useStream(factory, deps = [], opts) {
+  const enabled = opts?.enabled ?? true;
+  const [chunks, setChunks] = react.useState([]);
+  const [result, setResult] = react.useState(void 0);
+  const [error, setError] = react.useState(void 0);
+  const [status, setStatus] = react.useState("idle");
+  const ref = react.useRef(null);
+  react.useEffect(() => {
+    if (!enabled) {
+      setStatus("idle");
+      return;
+    }
+    setChunks([]);
+    setResult(void 0);
+    setError(void 0);
+    setStatus("streaming");
+    const call = factory();
+    ref.current = call;
+    call.onData((c) => setChunks((xs) => [...xs, c])).onEnd((r) => {
+      setResult(r);
+      setStatus("done");
+    }).onError((e) => {
+      setError(e);
+      setStatus("error");
+    });
+    return () => call.cancel();
+  }, [enabled, ...deps]);
+  const cancel = react.useCallback(() => ref.current?.cancel(), []);
+  return { chunks, result, error, status, cancel };
+}
+function useConfig() {
+  const rt = getRuntime();
+  const [cfg, setCfg] = react.useState(rt?.config.get() ?? {});
+  react.useEffect(() => rt?.config.subscribe((c) => setCfg(c)), [rt]);
+  const patch = react.useCallback((p) => rt?.config.set(p, false), [rt]);
+  const replace = react.useCallback((v) => rt?.config.set(v, true), [rt]);
+  return [cfg, patch, replace];
+}
+function useActive() {
+  const g = getGarret();
+  const [active, setActive] = react.useState(g.active);
+  react.useEffect(() => g.onActiveChange(setActive), [g]);
+  return active;
+}
+function useOpenSettings(cb) {
+  const g = getGarret();
+  const ref = react.useRef(cb);
+  ref.current = cb;
+  react.useEffect(() => g.onOpenSettings(() => ref.current()), [g]);
+}
+function useInstanceConfig(defaults) {
+  const g = getGarret();
+  const [cfg, setCfg] = react.useState(defaults);
+  const [loaded, setLoaded] = react.useState(false);
+  react.useEffect(() => {
+    let alive = true;
+    const unsub = g.onReady(() => {
+      void (async () => {
+        const saved = {};
+        await Promise.all(
+          Object.keys(defaults).map(async (k) => {
+            const v = await g.instanceStorage.get(k);
+            if (v !== void 0) saved[k] = v;
+          })
+        );
+        if (alive) {
+          setCfg({ ...defaults, ...saved });
+          setLoaded(true);
+        }
+      })();
+    });
+    return () => {
+      alive = false;
+      unsub();
+    };
+  }, []);
+  const set = react.useCallback(
+    (patch) => {
+      setCfg((c) => ({ ...c, ...patch }));
+      for (const [k, v] of Object.entries(patch)) void g.instanceStorage.set(k, v);
+    },
+    [g]
+  );
+  return { cfg, set, loaded };
+}
+function useProps() {
+  const g = getGarret();
+  const [props, setProps] = react.useState({});
+  react.useEffect(() => g.onReady((p) => setProps(p)), [g]);
+  return props;
+}
+
+exports.Accordion = Accordion;
+exports.Badge = Badge;
+exports.Dot = Dot;
+exports.EmptyState = EmptyState;
+exports.ErrorState = ErrorState;
+exports.Field = Field;
+exports.FieldGroup = FieldGroup;
+exports.GarretError = GarretError;
+exports.Item = Item;
+exports.NumberInput = NumberInput;
+exports.Scroll = Scroll;
+exports.Select = Select;
+exports.SettingsPanel = SettingsPanel;
+exports.Switch = Switch;
+exports.TextInput = TextInput;
+exports.useActive = useActive;
+exports.useConfig = useConfig;
+exports.useGarret = useGarret;
+exports.useHost = useHost;
+exports.useHostEvent = useHostEvent;
+exports.useInstanceConfig = useInstanceConfig;
+exports.useOpenSettings = useOpenSettings;
+exports.useProps = useProps;
+exports.useStream = useStream;

package/dist/react.d.cts

@@ -0,0 +1,128 @@
+import { G as GarretError, E as EventMap, H as HostClient, f as StreamCall } from './types-BxSYAH_H.cjs';
+import { G as GarretPlatform } from './platform-DnI7gJTx.cjs';
+export { S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls } from './platform-DnI7gJTx.cjs';
+import { ReactNode } from 'react';
+import './protocol-Do0BJdeE.cjs';
+
+/**
+ * Garret widget design system — GENERIC React building blocks that emit the classes the app's shared
+ * theme styles (`<link rel="stylesheet" href="~theme.css">`). No widget-specific components: these are
+ * primitives (rows, badges, accordions, a settings-form kit) that consumers compose into their own UI.
+ * Import from `@garretapp/sdk/react`.
+ */
+type Tone = 'neutral' | 'accent' | 'success' | 'warning' | 'danger';
+/** Centered muted message (supports rich children). */
+declare function EmptyState({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+/** Error message (in the danger color). */
+declare function ErrorState({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+/** A scrolling content region. */
+declare function Scroll({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+/** A generic list row: optional `leading` / `trailing` slots around the content. Interactive (hover +
+ *  pointer) when `onClick` is given. Renders a <button> if clickable, else a <div>. */
+declare function Item({ leading, trailing, onClick, onContextMenu, children }: {
+    leading?: ReactNode;
+    trailing?: ReactNode;
+    onClick?: () => void;
+    onContextMenu?: (e: React.MouseEvent) => void;
+    children: ReactNode;
+}): JSX.Element;
+/** A collapsible section: a header (title + optional `aside`, e.g. a count) and a rotating chevron. */
+declare function Accordion({ title, aside, defaultOpen, children }: {
+    title: ReactNode;
+    aside?: ReactNode;
+    defaultOpen?: boolean;
+    children: ReactNode;
+}): JSX.Element;
+/** A small pill; `tone` sets the color. */
+declare function Badge({ tone, children }: {
+    tone?: Tone;
+    children: ReactNode;
+}): JSX.Element;
+/** A small status dot; same tones. */
+declare function Dot({ tone, title }: {
+    tone?: Tone;
+    title?: string;
+}): JSX.Element;
+/** The container a widget renders when the host opens its settings (see `useOpenSettings`). Adds a
+ *  footer with a Done button. */
+declare function SettingsPanel({ onDone, children }: {
+    onDone: () => void;
+    children: ReactNode;
+}): JSX.Element;
+/** An inset grouped container (System-Settings style). Group related Fields; `label` is optional. */
+declare function FieldGroup({ label, children }: {
+    label?: ReactNode;
+    children: ReactNode;
+}): JSX.Element;
+declare function Field({ label, children }: {
+    label: ReactNode;
+    children: ReactNode;
+}): JSX.Element;
+/** Uncontrolled text input — commits on blur / Enter (so typing doesn't churn state per keystroke). */
+declare function TextInput({ value, placeholder, secret, onCommit }: {
+    value?: string;
+    placeholder?: string;
+    secret?: boolean;
+    onCommit: (v: string) => void;
+}): JSX.Element;
+declare function NumberInput({ value, onCommit }: {
+    value?: number;
+    onCommit: (v: number) => void;
+}): JSX.Element;
+declare function Select({ value, options, onChange }: {
+    value: string;
+    options: [value: string, label: string][];
+    onChange: (v: string) => void;
+}): JSX.Element;
+declare function Switch({ on, onChange }: {
+    on: boolean;
+    onChange: (v: boolean) => void;
+}): JSX.Element;
+
+/** Typed proxy of your host's methods. Stream-vs-Promise is inferred from each method's `Api` return
+ *  type — nothing to configure. */
+declare function useHost<Api, Events extends EventMap = EventMap>(): HostClient<Api>;
+/** Platform capabilities (storage/secrets/fetch/service/notify/…). Available in both tiers. */
+declare function useGarret(): GarretPlatform;
+/** Subscribe to a typed host event. `useHostEvent<Events, 'changed'>('changed', p => …)`. */
+declare function useHostEvent<E extends EventMap, K extends keyof E & string>(channel: K, handler: (payload: E[K]) => void, deps?: unknown[]): void;
+type StreamStatus = 'idle' | 'streaming' | 'done' | 'error';
+interface UseStreamResult<Chunk, Result> {
+    chunks: Chunk[];
+    result: Result | undefined;
+    error: GarretError | undefined;
+    status: StreamStatus;
+    cancel: () => void;
+}
+/** Consume a stream in React without manual effect+cleanup. `deps` auto-cancel + restart; pass
+ *  `{ enabled: false }` to defer (e.g. until the user triggers a run). */
+declare function useStream<Chunk, Result = void>(factory: () => StreamCall<Chunk, Result>, deps?: unknown[], opts?: {
+    enabled?: boolean;
+}): UseStreamResult<Chunk, Result>;
+/** This placement's settings. `patch` shallow-merges; `replace` overwrites. */
+declare function useConfig<T>(): [T, (patch: Partial<T>) => void, (value: T) => void];
+/** Board activity — `false` when ambient/idle. Gate polling / rAF / animations on it. */
+declare function useActive(): boolean;
+/** Run `cb` when the host (frame ⋯→Settings) asks this widget to reveal its own config UI. */
+declare function useOpenSettings(cb: () => void): void;
+/** Per-placement config backed by `g.instanceStorage` (isolated per widget instance). Loads once the
+ *  runtime binds (calls before bind reject); `set` writes through to storage + state. `loaded` gates
+ *  the first data fetch so you don't fetch with defaults before the saved config arrives. */
+declare function useInstanceConfig<T extends Record<string, unknown>>(defaults: T): {
+    cfg: T;
+    set: (patch: Partial<T>) => void;
+    loaded: boolean;
+};
+
+/** Launch props for a spawned surface window (`g.surfaces.open(..., { props })`). `{}` for the board
+ *  surface. Delivered via `onReady`'s callback (a contextBridge getter would be frozen at exposure
+ *  time), so this re-renders when the runtime binds. The `T` is an unchecked cast — validate it yourself. */
+declare function useProps<T = Record<string, unknown>>(): T;
+
+export { Accordion, Badge, Dot, EmptyState, ErrorState, Field, FieldGroup, GarretError, GarretPlatform, Item, NumberInput, Scroll, Select, SettingsPanel, type StreamStatus, Switch, TextInput, type Tone, type UseStreamResult, useActive, useConfig, useGarret, useHost, useHostEvent, useInstanceConfig, useOpenSettings, useProps, useStream };