@ai-matrx/applets 0.2.7

package/dist/frame.cjs

@@ -0,0 +1,977 @@
+"use client";
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/frame/index.tsx
+var frame_exports = {};
+__export(frame_exports, {
+  APPLETS_REACT_ENTRY: () => APPLETS_REACT_ENTRY,
+  appletScope: () => appletScope,
+  mountApplet: () => mountApplet,
+  mountAppletAsync: () => mountAppletAsync
+});
+module.exports = __toCommonJS(frame_exports);
+var React7 = __toESM(require("react"), 1);
+var import_code_runtime = require("@ai-matrx/code-runtime");
+
+// src/react/index.ts
+var react_exports = {};
+__export(react_exports, {
+  Applet: () => Applet,
+  AppletFrame: () => AppletFrame,
+  DataPage: () => DataPage,
+  Kind: () => Kind,
+  Link: () => Link,
+  Pages: () => Pages,
+  defineActions: () => defineActions,
+  matchPage: () => matchPage,
+  navigate: () => navigate,
+  newQueryClient: () => newQueryClient,
+  useAction: () => useAction,
+  useColumns: () => useColumns,
+  useJob: () => useJob,
+  useJobs: () => useJobs,
+  usePage: () => usePage,
+  useRow: () => useRow,
+  useRows: () => useRows,
+  useSources: () => useSources,
+  useValue: () => useValue
+});
+
+// src/react/context.tsx
+var React = __toESM(require("react"), 1);
+var import_react_query = require("@tanstack/react-query");
+var import_react = require("@ai-matrx/records/data/react");
+
+// src/types.ts
+var PAGE_ACTION_STREAM = "actions";
+var NAV_STREAM = "nav";
+var runStream = (requestId) => `run:${requestId}`;
+var valueStream = (name) => `value:${name}`;
+function fail(code, message, retryable = false, diagnostic) {
+  const error = { code, message, retryable };
+  if (diagnostic !== void 0) error.diagnostic = diagnostic;
+  return { ok: false, error };
+}
+function fromRecordsError(error) {
+  const out = { code: error.code, message: error.message, retryable: error.code === "unreachable" || error.code === "timed_out" };
+  if (error.diagnostic !== void 0) out.diagnostic = error.diagnostic;
+  return out;
+}
+function toAppletError(err, code = "internal") {
+  if (err && typeof err === "object") {
+    const o = err;
+    if (typeof o.code === "string" && typeof o.message === "string") {
+      const out = { code: o.code, message: o.message, retryable: o.retryable === true };
+      if (typeof o.diagnostic === "string") out.diagnostic = o.diagnostic;
+      return out;
+    }
+    if (err instanceof Error) return { code, message: err.message, retryable: false };
+  }
+  return { code, message: String(err), retryable: false };
+}
+
+// src/react/context.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var EventHub = class {
+  constructor(channel) {
+    this.channel = channel;
+  }
+  channel;
+  streams = /* @__PURE__ */ new Map();
+  bySubscription = /* @__PURE__ */ new Map();
+  detach = null;
+  subscribe(stream, listener) {
+    if (!this.detach) this.detach = this.channel.receive((m) => this.deliver(m));
+    let entry = this.streams.get(stream);
+    if (!entry) {
+      const created = { listeners: /* @__PURE__ */ new Set(), subscriptionId: null, ready: Promise.resolve() };
+      created.ready = this.channel.events.on(stream, null).then(
+        ({ subscriptionId }) => {
+          if (this.streams.get(stream) !== created) {
+            void this.channel.events.off(subscriptionId);
+            return;
+          }
+          created.subscriptionId = subscriptionId;
+          this.bySubscription.set(subscriptionId, stream);
+        },
+        (err) => {
+          void this.channel.reportError({ ...toAppletError(err), where: `events.on(${stream})` });
+        }
+      );
+      this.streams.set(stream, created);
+      entry = created;
+    }
+    const current = entry;
+    current.listeners.add(listener);
+    return {
+      ready: current.ready,
+      unsubscribe: () => {
+        current.listeners.delete(listener);
+        if (current.listeners.size > 0 || this.streams.get(stream) !== current) return;
+        this.streams.delete(stream);
+        if (current.subscriptionId) {
+          this.bySubscription.delete(current.subscriptionId);
+          void this.channel.events.off(current.subscriptionId);
+        }
+        if (this.streams.size === 0 && this.detach) {
+          this.detach();
+          this.detach = null;
+        }
+      }
+    };
+  }
+  deliver(message) {
+    const stream = this.bySubscription.get(message.subscriptionId);
+    if (!stream) return;
+    for (const l of [...this.streams.get(stream)?.listeners ?? []]) l(message.payload);
+  }
+};
+function frameDataEvents(hub) {
+  return {
+    on(event, listener) {
+      return hub.subscribe(event, (payload) => listener(payload)).unsubscribe;
+    }
+  };
+}
+function dataScopeFor(channel, hub) {
+  return { port: channel.data, portKey: channel.hostId, events: frameDataEvents(hub) };
+}
+var CONTEXT_KEY = /* @__PURE__ */ Symbol.for("ai-matrx.applets.frameContext");
+function frameContext() {
+  const g = globalThis;
+  let ctx = g[CONTEXT_KEY];
+  if (!ctx) {
+    ctx = React.createContext(null);
+    ctx.displayName = "AppletFrame";
+    g[CONTEXT_KEY] = ctx;
+  }
+  return ctx;
+}
+function newQueryClient() {
+  return new import_react_query.QueryClient({
+    defaultOptions: {
+      // Events keep the cache true (rows:<alias>, value:<name>, run:<id>), so a key is requested once.
+      queries: { staleTime: Number.POSITIVE_INFINITY, retry: false, refetchOnWindowFocus: false, refetchOnReconnect: false },
+      mutations: { retry: false }
+    }
+  });
+}
+var DETACHED_KEY = /* @__PURE__ */ Symbol.for("ai-matrx.applets.detached");
+var NO_FRAME = {
+  code: "no_frame",
+  message: "This part of the Applet is not inside an AppletFrame.",
+  retryable: false
+};
+var NO_FRAME_DATA = { code: "not_supported", message: NO_FRAME.message, diagnostic: NO_FRAME.code };
+function detachedChannel() {
+  const refuse = async () => ({ ok: false, error: NO_FRAME });
+  const refuseData = async () => ({ ok: false, error: NO_FRAME_DATA });
+  const reject = async () => {
+    throw NO_FRAME;
+  };
+  return {
+    hostId: "detached",
+    viewer: reject,
+    record: reject,
+    child: reject,
+    kinds: { definition: refuse, component: refuse },
+    pages: { definition: refuse },
+    data: {
+      sources: refuseData,
+      columns: refuseData,
+      list: refuseData,
+      get: refuseData,
+      create: refuseData,
+      update: refuseData,
+      archive: refuseData,
+      restore: refuseData
+    },
+    intelligence: {
+      describe: refuse,
+      run: refuse,
+      result: refuse,
+      answer: refuse,
+      rejoin: refuse,
+      listRuns: refuse,
+      createSoft: refuse
+    },
+    surface: {
+      mount: refuse,
+      unmount: async () => void 0,
+      getValue: async () => void 0,
+      setValue: reject,
+      listActions: async () => [],
+      runAction: refuse,
+      completeAction: async () => void 0
+    },
+    nav: { go: reject, current: async () => ({ path: [], params: {} }) },
+    events: { on: reject, off: async () => void 0 },
+    reportError: async () => void 0,
+    receive: () => () => void 0,
+    forHost: () => null
+  };
+}
+function detachedFrame() {
+  const g = globalThis;
+  let frame = g[DETACHED_KEY];
+  if (!frame) {
+    const channel = detachedChannel();
+    const hub = new EventHub(channel);
+    frame = { channel, hub, queryClient: newQueryClient(), dataScope: dataScopeFor(channel, hub), actions: /* @__PURE__ */ new Map(), parent: null, attached: false };
+    g[DETACHED_KEY] = frame;
+  }
+  return frame;
+}
+function useFrame() {
+  return React.useContext(frameContext()) ?? detachedFrame();
+}
+function useOptionalFrame() {
+  return React.useContext(frameContext());
+}
+var keys = {
+  root: (hostId) => ["applets", hostId],
+  record: (hostId) => ["applets", hostId, "record"],
+  viewer: (hostId) => ["applets", hostId, "viewer"],
+  nav: (hostId) => ["applets", hostId, "nav"]
+};
+function recordQuery(channel) {
+  return { queryKey: keys.record(channel.hostId), queryFn: () => channel.record() };
+}
+function viewerQuery(channel) {
+  return { queryKey: keys.viewer(channel.hostId), queryFn: () => channel.viewer() };
+}
+var FRAMES_KEY = /* @__PURE__ */ Symbol.for("ai-matrx.applets.frames");
+function liveFrames() {
+  const g = globalThis;
+  let list = g[FRAMES_KEY];
+  if (!list) {
+    list = [];
+    g[FRAMES_KEY] = list;
+  }
+  return list;
+}
+function AppletFrame({ host, queryClient, children, ...renderers }) {
+  const parent = useOptionalFrame();
+  const Context = frameContext();
+  const [frame] = React.useState(() => {
+    const hub = new EventHub(host);
+    const value = {
+      channel: host,
+      hub,
+      queryClient: queryClient ?? parent?.queryClient ?? newQueryClient(),
+      dataScope: dataScopeFor(host, hub),
+      actions: /* @__PURE__ */ new Map(),
+      parent,
+      attached: true
+    };
+    const inherit = (key) => {
+      const own = renderers[key] ?? (key === "renderKind" || key === "renderDataPage" ? parent?.[key] : void 0);
+      if (own !== void 0) value[key] = own;
+    };
+    inherit("renderKind");
+    inherit("renderDataPage");
+    inherit("renderApplet");
+    inherit("pageComponent");
+    return value;
+  });
+  React.useEffect(() => {
+    const frames = liveFrames();
+    frames.push(frame);
+    let cancelled = false;
+    let mountId = null;
+    void (async () => {
+      try {
+        const record = await frame.queryClient.fetchQuery(recordQuery(host));
+        const parentName = parent ? (await parent.queryClient.fetchQuery(recordQuery(parent.channel))).surfaceName : null;
+        if (cancelled) return;
+        const mounted = await host.surface.mount(record.surfaceName, parentName);
+        if (!mounted.ok) {
+          void host.reportError({ ...mounted.error, where: "surface.mount" });
+          return;
+        }
+        if (cancelled) void host.surface.unmount(mounted.data.mountId);
+        else mountId = mounted.data.mountId;
+      } catch (err) {
+        void host.reportError({ ...toAppletError(err), where: "AppletFrame mount" });
+      }
+    })();
+    const { unsubscribe } = frame.hub.subscribe(PAGE_ACTION_STREAM, (payload) => {
+      void routePageAction(frame, payload);
+    });
+    return () => {
+      cancelled = true;
+      unsubscribe();
+      if (mountId) void host.surface.unmount(mountId);
+      const i = frames.indexOf(frame);
+      if (i >= 0) frames.splice(i, 1);
+    };
+  }, [frame, host, parent]);
+  const { port, events, portKey } = frame.dataScope;
+  const body = /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Context.Provider, { value: frame, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react.DataPortProvider, { port, portKey, queryClient: frame.queryClient, ...events ? { events } : {}, children }) });
+  return parent?.queryClient === frame.queryClient ? body : /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_query.QueryClientProvider, { client: frame.queryClient, children: body });
+}
+async function routePageAction(frame, event) {
+  const { channel } = frame;
+  const handler = frame.actions.get(event.action);
+  if (!handler) {
+    await channel.surface.completeAction(event.runId, fail("action_unhandled", `This page has no handler for "${event.action}".`));
+    return;
+  }
+  let viewerId = null;
+  try {
+    viewerId = (await frame.queryClient.fetchQuery(viewerQuery(channel))).userId;
+  } catch {
+    viewerId = null;
+  }
+  try {
+    const data = await handler(event.input, { runId: event.runId, by: event.by ?? "applet", viewerId });
+    await channel.surface.completeAction(event.runId, { ok: true, data });
+  } catch (err) {
+    await channel.surface.completeAction(event.runId, { ok: false, error: toAppletError(err) });
+  }
+}
+
+// src/react/data.ts
+var React2 = __toESM(require("react"), 1);
+var import_react2 = require("@ai-matrx/records/data/react");
+async function unwrap(answer) {
+  const r = await answer;
+  if (!r.ok) throw r.error;
+  return r.data;
+}
+function asAppletError(err) {
+  return err == null ? null : toAppletError(err);
+}
+function queryStatus(q, saving) {
+  if (q.status === "error") return "error";
+  if (saving) return "saving";
+  if (q.status === "pending") return q.fetchStatus === "idle" ? "idle" : "loading";
+  return "ready";
+}
+function toResult(answer) {
+  return answer.ok ? answer : { ok: false, error: fromRecordsError(answer.error) };
+}
+function scopeOf(frame) {
+  return frame.attached ? void 0 : frame.dataScope;
+}
+function readStatus(loading, failed, saving) {
+  if (failed) return "error";
+  if (saving) return "saving";
+  return loading ? "loading" : "ready";
+}
+function useWriter(frame, alias) {
+  const mutations = (0, import_react2.useDataMutations)(alias, scopeOf(frame));
+  const [pending, setPending] = React2.useState(0);
+  const [writeError, setWriteError] = React2.useState(null);
+  const track = async (work) => {
+    setPending((n) => n + 1);
+    try {
+      const answer = toResult(await work());
+      setWriteError(answer.ok ? null : answer.error);
+      return answer;
+    } catch (err) {
+      const error = toAppletError(err);
+      setWriteError(error);
+      return { ok: false, error };
+    } finally {
+      setPending((n) => n - 1);
+    }
+  };
+  return {
+    saving: pending > 0,
+    error: writeError,
+    create: (values) => track(() => mutations.create(values)),
+    update: (id, patch, baseVersion) => track(async () => {
+      if (baseVersion !== void 0) return mutations.update(id, patch, { baseVersion });
+      const first = await mutations.update(id, patch);
+      if (first.ok || first.error.code !== "stale_read") return first;
+      const read = await frame.channel.data.get(alias, id);
+      if (!read.ok) return read;
+      if (!read.data) return { ok: false, error: { code: "not_found", message: "This record is not here any more." } };
+      return mutations.update(id, patch, { baseVersion: read.data._version });
+    }),
+    archive: (id) => track(() => mutations.archive(id)),
+    restore: (id) => track(() => mutations.restore(id))
+  };
+}
+function useRows(source, q) {
+  const frame = useFrame();
+  const list = (0, import_react2.useDataRows)(source, q ?? {}, scopeOf(frame));
+  const writer = useWriter(frame, source);
+  return {
+    rows: list.rows,
+    total: list.total,
+    status: readStatus(list.loading, list.error !== null, writer.saving),
+    error: (list.error ? fromRecordsError(list.error) : null) ?? writer.error,
+    hasMore: list.hasMore,
+    loadMore: list.loadMore,
+    newer: list.newer,
+    refresh: list.refresh,
+    create: writer.create,
+    update: (id, patch) => writer.update(id, patch, list.rows.find((r) => r._id === id)?._version),
+    archive: writer.archive,
+    restore: writer.restore
+  };
+}
+function useRow(source, id) {
+  const frame = useFrame();
+  const one = (0, import_react2.useDataRow)(source, id, scopeOf(frame));
+  const writer = useWriter(frame, source);
+  const row = one.data ?? null;
+  return {
+    row,
+    status: readStatus(one.loading, one.error !== null, writer.saving),
+    error: (one.error ? fromRecordsError(one.error) : null) ?? writer.error,
+    update: (patch) => writer.update(id, patch, row?._version),
+    archive: () => writer.archive(id),
+    refresh: one.refresh
+  };
+}
+function useColumns(source) {
+  const frame = useFrame();
+  const q = (0, import_react2.useDataColumns)(source, scopeOf(frame));
+  return { columns: q.data ?? [], status: readStatus(q.loading, q.error !== null, false), error: q.error ? fromRecordsError(q.error) : null };
+}
+function useSources() {
+  const frame = useFrame();
+  const q = (0, import_react2.useDataSources)(scopeOf(frame));
+  return { sources: q.data ?? [], status: readStatus(q.loading, q.error !== null, false), error: q.error ? fromRecordsError(q.error) : null };
+}
+
+// src/react/jobs.ts
+var React3 = __toESM(require("react"), 1);
+var import_react_query2 = require("@tanstack/react-query");
+var IDLE = { status: "idle", error: null, text: "", result: null, inputs: [] };
+var TERMINAL = /* @__PURE__ */ new Set(["done", "complete", "completed", "succeeded", "success"]);
+function reduce(state, action) {
+  switch (action.type) {
+    case "reset":
+      return { ...IDLE, status: action.status };
+    case "fail":
+      return { ...state, status: "error", error: action.error };
+    case "status":
+      return { ...state, status: action.status };
+    case "catch-up":
+      if (state.status === "done") return state;
+      return { ...state, status: "done", result: action.envelope, text: state.text || action.text };
+    case "event": {
+      const e = action.event;
+      switch (e.type) {
+        case "text":
+          return { ...state, text: state.text + e.delta };
+        case "status":
+          if (TERMINAL.has(e.status)) return { ...state, status: "done" };
+          if (e.status === "error" || e.status === "failed") return { ...state, status: "error" };
+          return state.status === "done" ? state : { ...state, status: "running" };
+        case "needs_input":
+          return { ...state, status: "needs_input", inputs: e.inputs };
+        case "result":
+          return { ...state, status: "done", result: e.envelope };
+        case "error":
+          return { ...state, status: "error", error: e.error };
+      }
+    }
+  }
+  return state;
+}
+var runsKey = (hostId, key) => ["applets", hostId, "runs", key];
+function useJob(alias) {
+  const frame = useFrame();
+  const { channel, queryClient: qc, hub } = frame;
+  const [state, dispatch] = React3.useReducer(reduce, IDLE);
+  const refRef = React3.useRef(null);
+  const unsubscribeRef = React3.useRef(null);
+  React3.useEffect(
+    () => () => {
+      unsubscribeRef.current?.();
+      unsubscribeRef.current = null;
+    },
+    []
+  );
+  const record = (0, import_react_query2.useQuery)({ ...recordQuery(channel) }, qc);
+  const key = record.data?.mandates.find((m) => m.alias === alias)?.key ?? null;
+  const appletId = record.data?.id;
+  const runs = (0, import_react_query2.useQuery)(
+    {
+      queryKey: runsKey(channel.hostId, key ?? ""),
+      queryFn: () => unwrap(channel.intelligence.listRuns(key ?? "", appletId)),
+      enabled: key !== null
+    },
+    qc
+  );
+  const run = async (variables, opts) => {
+    unsubscribeRef.current?.();
+    unsubscribeRef.current = null;
+    dispatch({ type: "reset", status: "resolving" });
+    try {
+      const rec = await qc.fetchQuery(recordQuery(channel));
+      const mandate = rec.mandates.find((m) => m.alias === alias);
+      if (!mandate) {
+        const error = { code: "job_not_found", message: `This Applet has no job named "${alias}".`, retryable: false };
+        dispatch({ type: "fail", error });
+        return { ok: false, error };
+      }
+      const viewer = await qc.fetchQuery(viewerQuery(channel));
+      const req = {
+        key: mandate.key,
+        organizationId: viewer.activeOrganizationId,
+        appletId: rec.id,
+        surfaceName: rec.surfaceName
+      };
+      if (variables !== void 0) req.variables = variables;
+      if (opts?.userInput !== void 0) req.userInput = opts.userInput;
+      const started = await channel.intelligence.run(req);
+      if (!started.ok) {
+        dispatch({ type: "fail", error: started.error });
+        return started;
+      }
+      const ref = started.data;
+      refRef.current = ref;
+      dispatch({ type: "status", status: "running" });
+      let finished = false;
+      const sub = hub.subscribe(runStream(ref.requestId), (payload) => {
+        const event = payload;
+        dispatch({ type: "event", event });
+        if (!finished && (event.type === "result" || event.type === "error" || event.type === "status" && TERMINAL.has(event.status))) {
+          finished = true;
+          void qc.invalidateQueries({ queryKey: runsKey(channel.hostId, mandate.key) });
+        }
+      });
+      unsubscribeRef.current = sub.unsubscribe;
+      await sub.ready;
+      const now = await channel.intelligence.result(ref);
+      if (now.ok && !finished && (now.data.envelope !== null || TERMINAL.has(now.data.status))) {
+        finished = true;
+        dispatch({ type: "catch-up", text: now.data.text, envelope: now.data.envelope });
+      }
+      void qc.invalidateQueries({ queryKey: runsKey(channel.hostId, mandate.key) });
+      return started;
+    } catch (err) {
+      const error = toAppletError(err);
+      dispatch({ type: "fail", error });
+      return { ok: false, error };
+    }
+  };
+  const answer = async (values) => {
+    const ref = refRef.current;
+    if (!ref) return { ok: false, error: { code: "no_run", message: "There is no run waiting for an answer.", retryable: false } };
+    dispatch({ type: "status", status: "running" });
+    const answered = await channel.intelligence.answer(ref, values);
+    if (!answered.ok) dispatch({ type: "fail", error: answered.error });
+    return answered;
+  };
+  return { run, answer, runs: runs.data ?? [], ...state };
+}
+function useJobs() {
+  const { channel, queryClient } = useFrame();
+  const q = (0, import_react_query2.useQuery)(
+    {
+      queryKey: ["applets", channel.hostId, "jobs"],
+      queryFn: async () => {
+        const rec = await queryClient.fetchQuery(recordQuery(channel));
+        return Promise.all(
+          rec.mandates.map(async (m) => {
+            const d = await channel.intelligence.describe(m.key);
+            if (!d.ok) throw d.error;
+            return { alias: m.alias, key: m.key, label: d.data.label, goal: d.data.goal, outputKind: d.data.outputKind };
+          })
+        );
+      }
+    },
+    queryClient
+  );
+  return { jobs: q.data ?? [], status: queryStatus(q, false), error: asAppletError(q.error) };
+}
+
+// src/react/surface.ts
+var React4 = __toESM(require("react"), 1);
+var import_react_query3 = require("@tanstack/react-query");
+var valueKey = (hostId, name) => ["applets", hostId, "value", name];
+function useValue(name) {
+  const frame = useFrame();
+  const { channel, queryClient: qc, hub } = frame;
+  const q = (0, import_react_query3.useQuery)({ queryKey: valueKey(channel.hostId, name), queryFn: async () => await channel.surface.getValue(name) ?? null }, qc);
+  React4.useEffect(() => {
+    const { unsubscribe } = hub.subscribe(valueStream(name), (payload) => {
+      qc.setQueryData(valueKey(channel.hostId, name), payload ?? null);
+    });
+    return unsubscribe;
+  }, [hub, qc, channel, name]);
+  const set = (next) => {
+    qc.setQueryData(valueKey(channel.hostId, name), next);
+    channel.surface.setValue(name, next).catch((err) => {
+      void channel.reportError({ ...toAppletError(err), where: `setValue(${name})` });
+    });
+  };
+  return [q.data ?? void 0, set];
+}
+function useAction(name, options) {
+  const { channel } = useFrame();
+  const [status, setStatus] = React4.useState("idle");
+  const [error, setError] = React4.useState(null);
+  const run = async (input) => {
+    setStatus("loading");
+    try {
+      const answer = await channel.surface.runAction(name, input ?? null, options?.by ?? "person");
+      if (answer.ok) {
+        setError(null);
+        setStatus("ready");
+        return answer;
+      }
+      const err = { code: answer.error.code, message: answer.error.message, retryable: answer.error.retryable };
+      if (answer.error.diagnostic !== void 0) err.diagnostic = answer.error.diagnostic;
+      setError(err);
+      setStatus("error");
+      return { ok: false, error: err };
+    } catch (thrown) {
+      const err = toAppletError(thrown);
+      setError(err);
+      setStatus("error");
+      return { ok: false, error: err };
+    }
+  };
+  return { run, status, error };
+}
+function defineActions(handlers) {
+  const frame = useFrame();
+  const latest = React4.useRef(handlers);
+  latest.current = handlers;
+  const names = Object.keys(handlers).sort().join("\0");
+  React4.useEffect(() => {
+    const registered = names.split("\0").filter(Boolean);
+    for (const name of registered) {
+      frame.actions.set(name, (input, ctx) => {
+        const handler = latest.current[name];
+        if (!handler) throw { code: "action_unhandled", message: `This page has no handler for "${name}".`, retryable: false };
+        return handler(input, ctx);
+      });
+    }
+    return () => {
+      for (const name of registered) frame.actions.delete(name);
+    };
+  }, [frame, names]);
+}
+
+// src/react/nav.tsx
+var React5 = __toESM(require("react"), 1);
+var import_react_query4 = require("@tanstack/react-query");
+var import_controls = require("@ai-matrx/design-system/controls");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function parse(to) {
+  const [pathPart = "", queryPart = ""] = to.split("?");
+  const params = {};
+  for (const pair of queryPart.split("&").filter(Boolean)) {
+    const [k = "", v = ""] = pair.split("=");
+    params[decodeURIComponent(k)] = decodeURIComponent(v);
+  }
+  return { path: pathPart.split("/").filter(Boolean), params };
+}
+function go(frame, to) {
+  frame.queryClient.setQueryData(keys.nav(frame.channel.hostId), parse(to));
+  frame.channel.nav.go(to).catch((err) => {
+    void frame.channel.reportError({ ...toAppletError(err), where: `nav.go(${to})` });
+  });
+}
+function navigate(to) {
+  const roots = liveFrames().filter((f) => f.parent === null);
+  const frame = roots[roots.length - 1];
+  if (!frame) {
+    console.error(`[applets] navigate("${to}") was called with no AppletFrame mounted.`);
+    return;
+  }
+  go(frame, to);
+}
+function useLocation(frame) {
+  const { channel, queryClient: qc, hub } = frame;
+  const q = (0, import_react_query4.useQuery)({ queryKey: keys.nav(channel.hostId), queryFn: () => channel.nav.current() }, qc);
+  React5.useEffect(() => {
+    const { unsubscribe } = hub.subscribe(NAV_STREAM, (payload) => {
+      qc.setQueryData(keys.nav(channel.hostId), payload);
+    });
+    return unsubscribe;
+  }, [hub, qc, channel]);
+  return q.data ?? { path: [], params: {} };
+}
+function segments(path) {
+  return path.split("/").filter(Boolean);
+}
+function matchPage(pages, path) {
+  let best = null;
+  for (const page of pages) {
+    const want = segments(page.path);
+    if (want.length !== path.length) continue;
+    const params = {};
+    let score = 0;
+    let hit = true;
+    want.forEach((w, i) => {
+      const got = path[i] ?? "";
+      if (w.startsWith(":")) params[w.slice(1)] = got;
+      else if (w === got) score += 1;
+      else hit = false;
+    });
+    if (hit && (!best || score > best.score)) best = { page, params, score };
+  }
+  return best ? { page: best.page, params: best.params } : null;
+}
+function usePage() {
+  const frame = useFrame();
+  const location = useLocation(frame);
+  const record = (0, import_react_query4.useQuery)({ ...recordQuery(frame.channel) }, frame.queryClient);
+  const pages = record.data?.pages ?? [];
+  const matched = matchPage(pages, location.path) ?? (location.path.length === 0 && pages[0] ? { page: pages[0], params: {} } : null);
+  return {
+    path: location.path,
+    page: matched ? { path: matched.page.path, title: matched.page.title } : { path: `/${location.path.join("/")}`, title: "" },
+    params: { ...location.params, ...matched?.params ?? {} },
+    navigate: (to) => go(frame, to)
+  };
+}
+function Link({ to, onClick, children, ...rest }) {
+  const frame = useFrame();
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+    "a",
+    {
+      ...rest,
+      href: to,
+      onClick: (event) => {
+        onClick?.(event);
+        if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+        event.preventDefault();
+        go(frame, to);
+      },
+      children
+    }
+  );
+}
+function topOf(pages, page) {
+  let current = page;
+  for (let guard = 0; current.parent && guard < pages.length; guard += 1) {
+    const up = pages.find((p) => p.path === current.parent);
+    if (!up) break;
+    current = up;
+  }
+  return current;
+}
+function Pages({ layout = "tabs", components }) {
+  const frame = useFrame();
+  const location = useLocation(frame);
+  const record = (0, import_react_query4.useQuery)({ ...recordQuery(frame.channel) }, frame.queryClient);
+  const pages = record.data?.pages ?? [];
+  const top = pages.filter((p) => !p.parent);
+  const matched = matchPage(pages, location.path)?.page ?? (location.path.length === 0 ? top[0] : void 0);
+  const selected = matched ? topOf(pages, matched).path : null;
+  const open = (path) => go(frame, path);
+  const Component = matched ? components?.[matched.file] ?? frame.pageComponent?.(matched.file) ?? null : null;
+  const body = matched ? Component ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(Component, {}) : /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { "data-applet-stand-in": "page", className: "text-sm text-muted-foreground", children: [
+    "Page file ",
+    matched.file,
+    " is not compiled in this frame"
+  ] }) : record.isPending ? null : /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { "data-applet-stand-in": "no-page", className: "text-sm text-muted-foreground", children: [
+    "No page at /",
+    location.path.join("/")
+  ] });
+  let navigation = null;
+  if (layout === "tabs" && top.length > 0) {
+    navigation = /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_controls.Tabs, { "aria-label": "Pages", value: selected, onValueChange: open, data: top.map((p) => ({ value: p.path, label: p.title })) });
+  } else if (layout === "menu" && top.length > 0) {
+    navigation = /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_controls.Select, { "aria-label": "Pages", value: selected ?? top[0]?.path ?? "", onValueChange: open, options: top.map((p) => ({ value: p.path, label: p.title })) });
+  } else if (layout === "sidebar") {
+    navigation = /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("nav", { "aria-label": "Pages", className: "flex w-48 shrink-0 flex-col gap-1 border-r border-border p-2", children: top.map((p) => /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      "button",
+      {
+        type: "button",
+        "aria-current": p.path === selected ? "page" : void 0,
+        "data-state": p.path === selected ? "on" : "off",
+        className: "rounded-md px-2 py-1 text-left text-sm text-foreground data-[state=off]:text-muted-foreground data-[state=on]:bg-muted",
+        onClick: () => open(p.path),
+        children: p.title
+      },
+      p.path
+    )) });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { "data-applet-pages": layout, className: layout === "sidebar" ? "flex h-full min-h-0" : "flex h-full min-h-0 flex-col", children: [
+    navigation,
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "min-h-0 flex-1", children: body })
+  ] });
+}
+
+// src/react/nesting.tsx
+var React6 = __toESM(require("react"), 1);
+var import_jsx_runtime3 = require("react/jsx-runtime");
+function StandIn({ what, children }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { "data-applet-stand-in": what, className: "rounded-md border border-dashed border-border p-2 text-sm text-muted-foreground", children });
+}
+function Applet({ id }) {
+  const frame = useFrame();
+  const [child, setChild] = React6.useState(null);
+  const [error, setError] = React6.useState(null);
+  React6.useEffect(() => {
+    let cancelled = false;
+    frame.channel.child(id).then(
+      ({ hostId }) => {
+        if (cancelled) return;
+        const scoped = frame.channel.forHost(hostId);
+        if (scoped) setChild(scoped);
+        else setError({ code: "host_not_found", message: `The host for Applet ${id} did not answer.`, retryable: true });
+      },
+      (err) => {
+        if (!cancelled) setError(toAppletError(err));
+      }
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [frame, id]);
+  if (error) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(StandIn, { what: "applet-error", children: error.message });
+  if (!child) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { "data-applet-loading": id, "aria-busy": "true" });
+  if (!frame.renderApplet) return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(StandIn, { what: "applet", children: [
+    "Applet ",
+    id,
+    " needs mountApplet to render"
+  ] });
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_jsx_runtime3.Fragment, { children: frame.renderApplet(child) });
+}
+function Kind({ kind, value }) {
+  const frame = useFrame();
+  if (frame.renderKind) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_jsx_runtime3.Fragment, { children: frame.renderKind(kind, value) });
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(StandIn, { what: `kind:${kind}`, children: [
+    "No renderer for kind ",
+    kind,
+    " in this frame"
+  ] });
+}
+function DataPage({ id }) {
+  const frame = useFrame();
+  const [state, setState] = React6.useState(null);
+  React6.useEffect(() => {
+    let cancelled = false;
+    void frame.channel.pages.definition(id).then((r) => {
+      if (!cancelled) setState(r.ok ? { definition: r.data } : { error: r.error });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [frame, id]);
+  if (!state) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { "data-applet-loading": id, "aria-busy": "true" });
+  if ("error" in state) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(StandIn, { what: "data-page-error", children: state.error.message });
+  if (!frame.renderDataPage) return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(StandIn, { what: "data-page", children: [
+    "Page ",
+    id,
+    " needs a host page renderer"
+  ] });
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_jsx_runtime3.Fragment, { children: frame.renderDataPage(id, state.definition) });
+}
+
+// src/frame/index.tsx
+var import_jsx_runtime4 = require("react/jsx-runtime");
+var APPLETS_REACT_ENTRY = "@ai-matrx/applets/react";
+function appletScope(record, scope) {
+  const entries = [.../* @__PURE__ */ new Set([...record.scope.entries, ...scope.entries, "react", APPLETS_REACT_ENTRY])];
+  const overrides = { ...record.scope.overrides ?? {}, ...scope.overrides ?? {} };
+  return { entries, overrides, shadowDangerousGlobals: record.scope.shadowDangerousGlobals || scope.shadowDangerousGlobals };
+}
+function provideHooks() {
+  (0, import_code_runtime.provideScopeModules)({ [APPLETS_REACT_ENTRY]: () => react_exports });
+}
+function mountApplet(record, host, scope, options = {}) {
+  provideHooks();
+  const spec = appletScope(record, scope);
+  const origin = `applet:${record.id}@${record.version}`;
+  const unresolvedSeen = [];
+  const compileOptions = {
+    origin,
+    onUnresolved: (o, list) => {
+      const lines = list.map((u) => u.importPath ? `${u.identifier} from "${u.importPath}"` : u.identifier);
+      unresolvedSeen.push(...lines);
+      if (options.onUnresolved) options.onUnresolved(o, lines);
+      else if (lines.length) {
+        void host.reportError({ code: "unresolved_import", message: `Missing in this Applet: ${lines.join(", ")}`, retryable: false, where: o });
+      }
+    }
+  };
+  let compiled;
+  try {
+    compiled = (0, import_code_runtime.compile)(record.files, record.entry, spec, compileOptions);
+  } catch (err) {
+    return { ok: false, error: toAppletError(err, "compile_failed") };
+  }
+  if (!compiled.ok) return { ok: false, error: compiled.error };
+  const Entry = compiled.Component;
+  const pageCache = /* @__PURE__ */ new Map([[record.entry, Entry]]);
+  const pageComponent = (file) => {
+    if (!pageCache.has(file)) {
+      if (!(file in record.files)) pageCache.set(file, null);
+      else {
+        const page = (0, import_code_runtime.compile)(record.files, file, spec, { ...compileOptions, origin: `${origin}#${file}` });
+        if (!page.ok) void host.reportError({ ...page.error, where: `${origin}#${file}` });
+        pageCache.set(file, page.ok ? page.Component : null);
+      }
+    }
+    return pageCache.get(file) ?? null;
+  };
+  const renderApplet = (child) => /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(NestedApplet, { channel: child, scope, options });
+  function MountedApplet() {
+    const renderers = { pageComponent, renderApplet };
+    if (options.renderKind) renderers.renderKind = options.renderKind;
+    if (options.renderDataPage) renderers.renderDataPage = options.renderDataPage;
+    return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(AppletFrame, { host, ...renderers, children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(Entry, {}) });
+  }
+  MountedApplet.displayName = `Applet(${record.slug})`;
+  return { ok: true, Component: MountedApplet, unresolved: compiled.unresolved };
+}
+async function mountAppletAsync(record, host, scope, options = {}) {
+  provideHooks();
+  await (0, import_code_runtime.prepareScope)(appletScope(record, scope));
+  return mountApplet(record, host, scope, options);
+}
+function NestedApplet({ channel, scope, options }) {
+  const [mounted, setMounted] = React7.useState(null);
+  React7.useEffect(() => {
+    let cancelled = false;
+    channel.record().then(
+      (record) => {
+        if (!cancelled) setMounted(mountApplet(record, channel, scope, options));
+      },
+      (err) => {
+        if (!cancelled) setMounted({ ok: false, error: toAppletError(err) });
+      }
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [channel, scope, options]);
+  if (!mounted) return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { "data-applet-loading": channel.hostId, "aria-busy": "true" });
+  if (!mounted.ok) {
+    return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { "data-applet-stand-in": "applet-error", className: "rounded-md border border-dashed border-border p-2 text-sm text-muted-foreground", children: mounted.error.message });
+  }
+  const Component = mounted.Component;
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(Component, {});
+}
+//# sourceMappingURL=frame.cjs.map