@ggui-ai/gadgets 0.1.0-rc.1

package/dist/index.mjs

@@ -0,0 +1,790 @@
+// src/createGguiGadget.ts
+import {
+  strictGadgetDescriptorSchema
+} from "@ggui-ai/protocol";
+var WrapperConformanceError = class extends Error {
+  code = "wrapper_conformance";
+  violations;
+  constructor(label, violations) {
+    const labelTail = label ? ` (${label})` : "";
+    const summary = violations.map((v) => `  - ${v.path.join(".") || "<root>"}: ${v.message}`).join("\n");
+    super(`gadget spec conformance failed${labelTail}
+${summary}`);
+    this.name = "WrapperConformanceError";
+    this.violations = violations;
+  }
+};
+function createGguiGadget(spec) {
+  const {
+    hookImpl,
+    hook,
+    description,
+    usage,
+    example,
+    gotchas,
+    permission,
+    required,
+    ...packageFields
+  } = spec;
+  const violations = [];
+  if (typeof hookImpl !== "function") {
+    violations.push({
+      path: ["hookImpl"],
+      message: "`hookImpl` MUST be a React hook function"
+    });
+  }
+  const hookExport = {
+    hook,
+    description,
+    usage,
+    example,
+    ...gotchas !== void 0 ? { gotchas } : {},
+    ...permission !== void 0 ? { permission } : {},
+    ...required !== void 0 ? { required } : {}
+  };
+  const descriptorDraft = {
+    ...packageFields,
+    exports: [hookExport]
+  };
+  const parsed = strictGadgetDescriptorSchema.safeParse(descriptorDraft);
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      violations.push({
+        // zod's path is `(string | number | symbol)[]`; we coerce
+        // symbol segments to strings for our author-facing message.
+        path: issue.path.map(
+          (segment) => typeof segment === "symbol" ? segment.toString() : segment
+        ),
+        message: issue.message
+      });
+    }
+  }
+  if (!parsed.success || violations.length > 0) {
+    throw new WrapperConformanceError(
+      typeof spec.hook === "string" ? spec.hook : void 0,
+      violations
+    );
+  }
+  const descriptor = parsed.data;
+  const wrapped = ((options) => hookImpl(options));
+  return Object.assign(wrapped, {
+    descriptor: Object.freeze(descriptor)
+  });
+}
+
+// src/defineGadgetPackage.ts
+import {
+  strictGadgetDescriptorSchema as strictGadgetDescriptorSchema2
+} from "@ggui-ai/protocol";
+function defineGadgetPackage(spec) {
+  const { exports: exportSpecs, ...packageFields } = spec;
+  const violations = [];
+  if (exportSpecs.length === 0) {
+    violations.push({
+      path: ["exports"],
+      message: "a gadget package MUST declare at least one export"
+    });
+  }
+  const exports = exportSpecs.map((entry, index) => {
+    if (typeof entry.impl !== "function") {
+      violations.push({
+        path: ["exports", index, "impl"],
+        message: "`impl` MUST be a function (a React hook or component)"
+      });
+    }
+    const teaching = {
+      description: entry.description,
+      usage: entry.usage,
+      example: entry.example,
+      ...entry.gotchas !== void 0 ? { gotchas: entry.gotchas } : {},
+      ...entry.permission !== void 0 ? { permission: entry.permission } : {},
+      ...entry.required !== void 0 ? { required: entry.required } : {}
+    };
+    return "hook" in entry ? { hook: entry.hook, ...teaching } : { component: entry.component, ...teaching };
+  });
+  const parsed = strictGadgetDescriptorSchema2.safeParse({
+    ...packageFields,
+    exports
+  });
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      violations.push({
+        path: issue.path.map(
+          (segment) => typeof segment === "symbol" ? segment.toString() : segment
+        ),
+        message: issue.message
+      });
+    }
+  }
+  if (!parsed.success || violations.length > 0) {
+    throw new WrapperConformanceError(spec.package, violations);
+  }
+  return parsed.data;
+}
+
+// src/catalog-adapter.ts
+var InMemoryGadgetCatalog = class {
+  #byApp;
+  constructor(byApp) {
+    this.#byApp = byApp;
+  }
+  /**
+   * Convenience factory for the common "every app gets the same
+   * catalog" case (the OSS stdlib seed pattern). Apps not explicitly
+   * keyed fall back to the supplied default.
+   */
+  static withDefault(defaultEntries, perApp) {
+    const merged = /* @__PURE__ */ new Map();
+    if (perApp) {
+      for (const [appId, entries] of perApp) merged.set(appId, entries);
+    }
+    return new InMemoryGadgetCatalogWithFallback(merged, defaultEntries);
+  }
+  async list(appId) {
+    return this.#byApp.get(appId) ?? [];
+  }
+};
+var InMemoryGadgetCatalogWithFallback = class extends InMemoryGadgetCatalog {
+  #fallback;
+  constructor(byApp, fallback) {
+    super(byApp);
+    this.#fallback = fallback;
+  }
+  async list(appId) {
+    const direct = await super.list(appId);
+    return direct.length > 0 ? direct : this.#fallback;
+  }
+};
+var CachingGadgetCatalog = class {
+  #inner;
+  #ttlMs;
+  #now;
+  #cache = /* @__PURE__ */ new Map();
+  #inflight = /* @__PURE__ */ new Map();
+  constructor(inner, options = {}) {
+    this.#inner = inner;
+    this.#ttlMs = options.ttlMs ?? 3e4;
+    this.#now = options.now ?? Date.now;
+  }
+  async list(appId) {
+    const now = this.#now();
+    const cached = this.#cache.get(appId);
+    if (cached !== void 0 && cached.expiresAt > now) {
+      return cached.entries;
+    }
+    const inflight = this.#inflight.get(appId);
+    if (inflight !== void 0) return inflight;
+    const fetchPromise = (async () => {
+      try {
+        const entries = await this.#inner.list(appId);
+        if (this.#ttlMs > 0) {
+          this.#cache.set(appId, {
+            entries,
+            expiresAt: this.#now() + this.#ttlMs
+          });
+        }
+        return entries;
+      } finally {
+        this.#inflight.delete(appId);
+      }
+    })();
+    this.#inflight.set(appId, fetchPromise);
+    return fetchPromise;
+  }
+  /**
+   * Drop the cached entry for `appId`. Right for operator-triggered
+   * invalidation (gadget registered / unregistered / updated). When
+   * `appId` is omitted, drops every cached entry.
+   */
+  invalidate(appId) {
+    if (appId === void 0) {
+      this.#cache.clear();
+      return;
+    }
+    this.#cache.delete(appId);
+  }
+};
+
+// src/getPublicEnv.ts
+function getPublicEnv(key, opts, target = globalThis) {
+  const root = target.__ggui__;
+  if (!root) {
+    throw new Error(
+      `getPublicEnv('${key}'): globalThis.__ggui__ is not initialized. This function must be invoked from inside a ggui-rendered component or wrapper hook, after the iframe runtime has booted.`
+    );
+  }
+  const env = root.publicEnv ?? {};
+  if (Object.prototype.hasOwnProperty.call(env, key)) {
+    return env[key];
+  }
+  if (opts?.optional) return void 0;
+  const available = Object.keys(env);
+  throw new Error(
+    `getPublicEnv('${key}'): not provided in App.publicEnv. Available: [${available.join(", ") || "(none)"}]. Operators set this on the App record; gadget authors declare the key in 'requires' so the push gate verifies it before mount.`
+  );
+}
+
+// src/useGeolocation.ts
+import { useCallback, useRef, useState } from "react";
+function toCoords(position) {
+  const c = position.coords;
+  const base = {
+    latitude: c.latitude,
+    longitude: c.longitude,
+    accuracy: c.accuracy,
+    timestamp: position.timestamp
+  };
+  return {
+    ...base,
+    ...c.altitude !== null && { altitude: c.altitude },
+    ...c.altitudeAccuracy !== null && {
+      altitudeAccuracy: c.altitudeAccuracy
+    },
+    ...c.heading !== null && { heading: c.heading },
+    ...c.speed !== null && { speed: c.speed }
+  };
+}
+function mapGeolocationError(err) {
+  if (err.code === err.PERMISSION_DENIED) {
+    return { code: "permission_denied", message: err.message };
+  }
+  if (err.code === err.TIMEOUT) {
+    return { code: "timeout", message: err.message };
+  }
+  return { code: "unknown", message: err.message };
+}
+var useGeolocation = (options) => {
+  const [value, setValue] = useState(void 0);
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(void 0);
+  const watchIdRef = useRef(null);
+  const start = useCallback(async () => {
+    if (typeof navigator === "undefined" || !navigator.geolocation) {
+      const e = {
+        code: "not_supported",
+        message: "Geolocation API unavailable in this environment."
+      };
+      setError(e);
+      setStatus("error");
+      return void 0;
+    }
+    setStatus("prompting");
+    setError(void 0);
+    const positionOptions = {
+      enableHighAccuracy: options?.enableHighAccuracy ?? false,
+      maximumAge: options?.maximumAge ?? 0,
+      timeout: options?.timeout ?? Number.POSITIVE_INFINITY
+    };
+    if (options?.watch) {
+      return new Promise((resolve) => {
+        let firstResolved = false;
+        watchIdRef.current = navigator.geolocation.watchPosition(
+          (position) => {
+            const coords = toCoords(position);
+            setValue(coords);
+            setStatus("active");
+            if (!firstResolved) {
+              firstResolved = true;
+              resolve(coords);
+            }
+          },
+          (err) => {
+            const mapped = mapGeolocationError(err);
+            setError(mapped);
+            setStatus(mapped.code === "permission_denied" ? "denied" : "error");
+            if (!firstResolved) {
+              firstResolved = true;
+              resolve(void 0);
+            }
+          },
+          positionOptions
+        );
+      });
+    }
+    return new Promise((resolve) => {
+      navigator.geolocation.getCurrentPosition(
+        (position) => {
+          const coords = toCoords(position);
+          setValue(coords);
+          setStatus("completed");
+          resolve(coords);
+        },
+        (err) => {
+          const mapped = mapGeolocationError(err);
+          setError(mapped);
+          setStatus(mapped.code === "permission_denied" ? "denied" : "error");
+          resolve(void 0);
+        },
+        positionOptions
+      );
+    });
+  }, [options?.enableHighAccuracy, options?.maximumAge, options?.timeout, options?.watch]);
+  const stop = useCallback(() => {
+    if (watchIdRef.current !== null && typeof navigator !== "undefined") {
+      navigator.geolocation.clearWatch(watchIdRef.current);
+      watchIdRef.current = null;
+    }
+    setStatus("completed");
+  }, []);
+  return {
+    value,
+    status,
+    ...error !== void 0 ? { error } : {},
+    start,
+    stop
+  };
+};
+
+// src/useClipboardWrite.ts
+import { useCallback as useCallback2, useState as useState2 } from "react";
+function mapWriteError(err) {
+  if (err instanceof Error) {
+    if (err.name === "NotAllowedError") {
+      return { code: "permission_denied", message: err.message };
+    }
+    return { code: "unknown", message: err.message };
+  }
+  return { code: "unknown", message: String(err) };
+}
+var useClipboardWrite = (options) => {
+  const [value, setValue] = useState2(void 0);
+  const [status, setStatus] = useState2("idle");
+  const [error, setError] = useState2(void 0);
+  const start = useCallback2(async () => {
+    if (typeof navigator === "undefined" || !navigator.clipboard || typeof navigator.clipboard.writeText !== "function") {
+      const e = {
+        code: "not_supported",
+        message: "Clipboard write API unavailable in this environment."
+      };
+      setError(e);
+      setStatus("error");
+      return void 0;
+    }
+    const text = options?.text;
+    if (typeof text !== "string") {
+      const e = {
+        code: "unknown",
+        message: "useClipboardWrite: `text` option is required at start() time."
+      };
+      setError(e);
+      setStatus("error");
+      return void 0;
+    }
+    setStatus("prompting");
+    setError(void 0);
+    try {
+      await navigator.clipboard.writeText(text);
+      setValue(text);
+      setStatus("completed");
+      return text;
+    } catch (err) {
+      const mapped = mapWriteError(err);
+      setError(mapped);
+      setStatus(mapped.code === "permission_denied" ? "denied" : "error");
+      return void 0;
+    }
+  }, [options?.text]);
+  return {
+    value,
+    status,
+    ...error !== void 0 ? { error } : {},
+    start
+  };
+};
+
+// src/useClipboardPaste.ts
+import { useCallback as useCallback3, useState as useState3 } from "react";
+function mapReadError(err) {
+  if (err instanceof Error) {
+    if (err.name === "NotAllowedError") {
+      return { code: "permission_denied", message: err.message };
+    }
+    return { code: "unknown", message: err.message };
+  }
+  return { code: "unknown", message: String(err) };
+}
+var useClipboardPaste = () => {
+  const [value, setValue] = useState3(void 0);
+  const [status, setStatus] = useState3("idle");
+  const [error, setError] = useState3(void 0);
+  const start = useCallback3(async () => {
+    if (typeof navigator === "undefined" || !navigator.clipboard || typeof navigator.clipboard.readText !== "function") {
+      const e = {
+        code: "not_supported",
+        message: "Clipboard read API unavailable in this environment."
+      };
+      setError(e);
+      setStatus("error");
+      return void 0;
+    }
+    setStatus("prompting");
+    setError(void 0);
+    try {
+      const text = await navigator.clipboard.readText();
+      setValue(text);
+      setStatus("completed");
+      return text;
+    } catch (err) {
+      const mapped = mapReadError(err);
+      setError(mapped);
+      setStatus(mapped.code === "permission_denied" ? "denied" : "error");
+      return void 0;
+    }
+  }, []);
+  return {
+    value,
+    status,
+    ...error !== void 0 ? { error } : {},
+    start
+  };
+};
+
+// src/useNotifications.ts
+import { useCallback as useCallback4, useState as useState4 } from "react";
+var useNotifications = (options) => {
+  const [value, setValue] = useState4(
+    void 0
+  );
+  const [status, setStatus] = useState4("idle");
+  const [error, setError] = useState4(void 0);
+  const start = useCallback4(async () => {
+    if (typeof Notification === "undefined") {
+      const e = {
+        code: "not_supported",
+        message: "Notification API unavailable in this environment."
+      };
+      setError(e);
+      setStatus("error");
+      return void 0;
+    }
+    if (!options?.title) {
+      const e = {
+        code: "unknown",
+        message: "useNotifications: `title` option required at start()."
+      };
+      setError(e);
+      setStatus("error");
+      return void 0;
+    }
+    setStatus("prompting");
+    setError(void 0);
+    let permission = Notification.permission;
+    if (permission === "default") {
+      try {
+        permission = await Notification.requestPermission();
+      } catch (err) {
+        const e = {
+          code: "unknown",
+          message: err instanceof Error ? err.message : String(err)
+        };
+        setError(e);
+        setStatus("error");
+        return void 0;
+      }
+    }
+    if (permission !== "granted") {
+      const e = {
+        code: "permission_denied",
+        message: "Notification permission not granted."
+      };
+      setError(e);
+      setStatus("denied");
+      return void 0;
+    }
+    return new Promise((resolve) => {
+      const notif = new Notification(options.title, {
+        ...options.body !== void 0 ? { body: options.body } : {},
+        ...options.icon !== void 0 ? { icon: options.icon } : {},
+        ...options.tag !== void 0 ? { tag: options.tag } : {}
+      });
+      const finish = (outcome) => {
+        const result = {
+          outcome,
+          ...options.tag !== void 0 ? { tag: options.tag } : {}
+        };
+        setValue(result);
+        setStatus("completed");
+        resolve(result);
+      };
+      notif.onclick = () => finish("clicked");
+      notif.onclose = () => finish("closed");
+    });
+  }, [options?.title, options?.body, options?.icon, options?.tag]);
+  return {
+    value,
+    status,
+    ...error !== void 0 ? { error } : {},
+    start
+  };
+};
+
+// src/useFilePicker.ts
+import { useCallback as useCallback5, useState as useState5 } from "react";
+function fileToPicked(file) {
+  return {
+    name: file.name,
+    size: file.size,
+    type: file.type,
+    _file: file
+  };
+}
+var useFilePicker = (options) => {
+  const [value, setValue] = useState5(void 0);
+  const [status, setStatus] = useState5("idle");
+  const [error, setError] = useState5(void 0);
+  const start = useCallback5(async () => {
+    if (typeof document === "undefined") {
+      const e = {
+        code: "not_supported",
+        message: "File picker requires a DOM environment."
+      };
+      setError(e);
+      setStatus("error");
+      return void 0;
+    }
+    setStatus("prompting");
+    setError(void 0);
+    return new Promise((resolve) => {
+      const input = document.createElement("input");
+      input.type = "file";
+      if (options?.multiple) input.multiple = true;
+      if (options?.accept) input.accept = options.accept;
+      input.onchange = () => {
+        const files = input.files ? Array.from(input.files) : [];
+        if (files.length === 0) {
+          const e = {
+            code: "aborted",
+            message: "File picker cancelled by user."
+          };
+          setError(e);
+          setStatus("denied");
+          resolve(void 0);
+          return;
+        }
+        const result = {
+          files: files.map(fileToPicked)
+        };
+        setValue(result);
+        setStatus("completed");
+        resolve(result);
+      };
+      input.click();
+    });
+  }, [options?.multiple, options?.accept]);
+  return {
+    value,
+    status,
+    ...error !== void 0 ? { error } : {},
+    start
+  };
+};
+
+// src/useMicrophone.ts
+import { useCallback as useCallback6, useRef as useRef2, useState as useState6 } from "react";
+function mapGetUserMediaError(err) {
+  if (err instanceof Error) {
+    if (err.name === "NotAllowedError") {
+      return { code: "permission_denied", message: err.message };
+    }
+    if (err.name === "NotFoundError" || err.name === "OverconstrainedError") {
+      return { code: "not_supported", message: err.message };
+    }
+    return { code: "unknown", message: err.message };
+  }
+  return { code: "unknown", message: String(err) };
+}
+var useMicrophone = (options) => {
+  const [value, setValue] = useState6(void 0);
+  const [status, setStatus] = useState6("idle");
+  const [error, setError] = useState6(void 0);
+  const recorderRef = useRef2(null);
+  const streamRef = useRef2(null);
+  const startedAtRef = useRef2(0);
+  const resolveRef = useRef2(null);
+  const start = useCallback6(async () => {
+    if (typeof navigator === "undefined" || !navigator.mediaDevices || typeof navigator.mediaDevices.getUserMedia !== "function" || typeof MediaRecorder === "undefined") {
+      const e = {
+        code: "not_supported",
+        message: "MediaRecorder / getUserMedia unavailable."
+      };
+      setError(e);
+      setStatus("error");
+      return void 0;
+    }
+    setStatus("prompting");
+    setError(void 0);
+    let stream;
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    } catch (err) {
+      const mapped = mapGetUserMediaError(err);
+      setError(mapped);
+      setStatus(mapped.code === "permission_denied" ? "denied" : "error");
+      return void 0;
+    }
+    streamRef.current = stream;
+    const mimeType = options?.mimeType ?? "audio/webm";
+    let recorder;
+    try {
+      recorder = new MediaRecorder(stream, { mimeType });
+    } catch {
+      recorder = new MediaRecorder(stream);
+    }
+    recorderRef.current = recorder;
+    const chunks = [];
+    recorder.ondataavailable = (event) => {
+      if (event.data && event.data.size > 0) chunks.push(event.data);
+    };
+    return new Promise((resolve) => {
+      resolveRef.current = resolve;
+      recorder.onstop = () => {
+        const blob = new Blob(chunks, { type: recorder.mimeType });
+        const durationMs = Date.now() - startedAtRef.current;
+        const result = {
+          blob,
+          durationMs,
+          mimeType: recorder.mimeType
+        };
+        setValue(result);
+        setStatus("completed");
+        streamRef.current?.getTracks().forEach((t) => t.stop());
+        streamRef.current = null;
+        recorderRef.current = null;
+        resolveRef.current = null;
+        resolve(result);
+      };
+      startedAtRef.current = Date.now();
+      recorder.start();
+      setStatus("active");
+    });
+  }, [options?.mimeType]);
+  const stop = useCallback6(() => {
+    if (recorderRef.current && recorderRef.current.state === "recording") {
+      recorderRef.current.stop();
+    } else {
+      setStatus("completed");
+    }
+  }, []);
+  return {
+    value,
+    status,
+    ...error !== void 0 ? { error } : {},
+    start,
+    stop
+  };
+};
+
+// src/useCamera.ts
+import { useCallback as useCallback7, useRef as useRef3, useState as useState7 } from "react";
+function mapCameraError(err) {
+  if (err instanceof Error) {
+    if (err.name === "NotAllowedError") {
+      return { code: "permission_denied", message: err.message };
+    }
+    if (err.name === "NotFoundError" || err.name === "OverconstrainedError") {
+      return { code: "not_supported", message: err.message };
+    }
+    return { code: "unknown", message: err.message };
+  }
+  return { code: "unknown", message: String(err) };
+}
+var useCamera = (options) => {
+  const [value, setValue] = useState7(void 0);
+  const [status, setStatus] = useState7("idle");
+  const [error, setError] = useState7(void 0);
+  const streamRef = useRef3(null);
+  const stop = useCallback7(() => {
+    if (streamRef.current) {
+      streamRef.current.getTracks().forEach((t) => t.stop());
+      streamRef.current = null;
+    }
+    setStatus("completed");
+  }, []);
+  const start = useCallback7(async () => {
+    if (typeof navigator === "undefined" || !navigator.mediaDevices || typeof navigator.mediaDevices.getUserMedia !== "function" || typeof document === "undefined") {
+      const e = {
+        code: "not_supported",
+        message: "getUserMedia / DOM unavailable."
+      };
+      setError(e);
+      setStatus("error");
+      return void 0;
+    }
+    setStatus("prompting");
+    setError(void 0);
+    let stream;
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({
+        video: options?.facingMode ? { facingMode: options.facingMode } : true
+      });
+    } catch (err) {
+      const mapped = mapCameraError(err);
+      setError(mapped);
+      setStatus(mapped.code === "permission_denied" ? "denied" : "error");
+      return void 0;
+    }
+    streamRef.current = stream;
+    setStatus("active");
+    try {
+      const video = document.createElement("video");
+      video.srcObject = stream;
+      video.muted = true;
+      await video.play();
+      await new Promise(
+        (resolve) => requestAnimationFrame(() => resolve())
+      );
+      const canvas = document.createElement("canvas");
+      const width = video.videoWidth || 640;
+      const height = video.videoHeight || 480;
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext("2d");
+      if (!ctx) {
+        const e = {
+          code: "unknown",
+          message: "2D canvas context unavailable."
+        };
+        setError(e);
+        setStatus("error");
+        stop();
+        return void 0;
+      }
+      ctx.drawImage(video, 0, 0, width, height);
+      const mimeType = options?.mimeType ?? "image/png";
+      const dataUrl = options?.quality !== void 0 ? canvas.toDataURL(mimeType, options.quality) : canvas.toDataURL(mimeType);
+      const result = { dataUrl, width, height, mimeType };
+      setValue(result);
+      setStatus("completed");
+      stop();
+      return result;
+    } catch (err) {
+      const mapped = mapCameraError(err);
+      setError(mapped);
+      setStatus("error");
+      stop();
+      return void 0;
+    }
+  }, [options?.facingMode, options?.mimeType, options?.quality, stop]);
+  return {
+    value,
+    status,
+    ...error !== void 0 ? { error } : {},
+    start,
+    stop
+  };
+};
+export {
+  CachingGadgetCatalog,
+  InMemoryGadgetCatalog,
+  WrapperConformanceError,
+  createGguiGadget,
+  defineGadgetPackage,
+  getPublicEnv,
+  useCamera,
+  useClipboardPaste,
+  useClipboardWrite,
+  useFilePicker,
+  useGeolocation,
+  useMicrophone,
+  useNotifications
+};