// sandbox.js — the HOST side of member-built apps (docs/member-apps.md).
//
// A member app is user content, not admin-vetted code, so the page never runs
// it. Instead each member app registers a PROXY through the ordinary mini-app
// framework — so it appears in New chat's Apps list, gets a personal thread,
// folds events, and snapshots like any app — while the untrusted code itself
// runs only inside an opaque-origin <iframe sandbox="allow-scripts"> pointed
// at /app-sandbox (no cookies, no storage, no parent DOM, no network; see
// memberapps.go for the frame's CSP).
//
// The proxy's fold is a trusted, generic queue: every wire event of the app's
// types appends to `pend`. The frame folds those events with the app's real
// (untrusted) reducer and reports folded state back; the host then swaps the
// report in as `v` and trims `pend` (installMemberAppState in apps.js). At
// every moment `v + pend` IS the fold at the thread's snapshot horizon, so
// the framework's snapshot machinery persists sandboxed state unchanged.
//
// Trust rules enforced here, on every message out of a frame:
//   - an app may only emit/schedule events of its OWN manifest types (all
//     prefixed "<name>." — it can't spoof chat.*, another app, or a bare
//     text message);
//   - events are deep-sanitized: plain JSON data only, no __proto__ keys, no
//     injected name/ts/uid, notices clamped to plain strings with no action
//     chips, hard size caps, a rate limit;
//   - state reports are size-capped and JSON-normalized.
// Nothing else crosses: no keys, no tokens, no other threads' data, no DOM.

import { defineApp, appByName, isAppType, commandTakenBy, installMemberAppState, memberCtx, foldHostEvent } from "./apps.js";
import { decrypt, encrypt } from "./crypto.js";

// Injected by shell.js: seed a member app's snapshot state before an off-thread
// command runs its (transient) logic frame, and re-render the active surfaces
// after companion chat projections fold in. Both no-ops until set.
let memberSeeder = null;
export function setMemberSeeder(fn) {
  memberSeeder = fn;
}
let surfaceRefresh = null;
export function setSurfaceRefresh(fn) {
  surfaceRefresh = fn;
}

// Injected by shell.js: the privileged context App Studio needs to list /
// deploy / retire member apps — an accessor returning
// { token, instanceKey, uid, name, openApp(name) }. An accessor (not a value)
// because the instance key arrives after boot. No-op until set.
let memberAdmin = null;
export function setMemberAdmin(fn) {
  memberAdmin = fn;
}

// How many queued-but-unfolded events a proxy retains while no frame is alive
// to fold them (the frame drains the queue whenever the app is open). Beyond
// the cap the oldest are dropped and the state flagged, so a pathological
// backlog degrades visibly instead of growing without bound.
const MAX_PEND = 500;

// Caps on what a frame may hand us (the server's blob cap is 64 KB and the
// thread-state cap 256 KB — stay comfortably inside both).
const MAX_EVENT_JSON = 32 * 1024;
// The whole proxy snapshot (state + pend + projected chat) is encrypted then
// base64'd (~1.37×) into one thread_state blob capped at 256 KB server-side, and
// several apps may share that slot — so keep the plaintext budget well under it.
const MAX_STATE_JSON = 150 * 1024;
const EMIT_BURST = 30; // emits allowed per window…
const EMIT_WINDOW_MS = 10_000; // …per this window

// The theme custom properties forwarded into frames — the same table
// docs/building-member-apps.md promises authors.
const THEME_VARS = [
  "--bg", "--panel", "--sidebar", "--ink", "--muted", "--border",
  "--accent", "--accent-ink", "--link", "--bubble-me", "--bubble-me-ink",
  "--bubble-them", "--danger", "--warn", "--radius", "--shadow",
  "--font-display", "--ui-cursor",
];

// ---- manifest + event validation (pure; unit-tested in Node) --------------

const NAME_RE = /^[a-z][a-z0-9-]{1,23}$/;
const TYPE_TAIL_RE = /^[a-z0-9_-]{1,40}(\.[a-z0-9_-]{1,40})*$/;
const CMD_RE = /^\/[a-z][a-z0-9-]{0,30}$/;

// validateManifest checks a decrypted member-app manifest and returns an
// error string, or null when it's sound. The manifest is untrusted (any
// member can deploy a blob), so nothing here is advisory: the proxy registers
// exactly and only what validates.
export function validateManifest(m) {
  if (!m || typeof m !== "object") return "manifest missing";
  if (m.v !== 1) return "unsupported manifest version";
  if (typeof m.name !== "string" || !NAME_RE.test(m.name)) return "bad app name";
  if (typeof m.title !== "string" || !m.title.trim() || m.title.length > 40) return "bad title";
  if (typeof m.glyph !== "string" || !m.glyph || m.glyph.length > 8) return "bad glyph";
  if (m.scope !== undefined && m.scope !== "personal") return "only personal member apps are supported";
  if (!Array.isArray(m.types) || m.types.length < 1 || m.types.length > 64) return "bad types list";
  for (const t of m.types) {
    if (typeof t !== "string" || !t.startsWith(m.name + ".")) return `event type "${t}" must be prefixed "${m.name}."`;
    if (!TYPE_TAIL_RE.test(t.slice(m.name.length + 1))) return `bad event type "${t}"`;
  }
  // Optional command METADATA (names + typeahead text); the handlers live in
  // the app source and run in the frame. Only the shapes are checked here.
  if (m.commands !== undefined) {
    if (!Array.isArray(m.commands) || m.commands.length > 16) return "bad commands list";
    for (const c of m.commands) {
      if (!c || typeof c !== "object") return "bad command";
      if (typeof c.name !== "string" || !CMD_RE.test(c.name)) return `bad command name "${c && c.name}"`;
      if (c.desc !== undefined && (typeof c.desc !== "string" || c.desc.length > 80)) return "bad command desc";
      if (c.args !== undefined && (typeof c.args !== "string" || c.args.length > 40)) return "bad command args";
    }
  }
  // Optional native chrome (docs/icons.md): an SF Symbols name — dotted
  // lowercase words, bounded. The emoji glyph stays the identity; a name
  // native can't resolve falls back to it. `mark` is deliberately NOT a
  // member-app field (vendored brand assets — impersonation).
  if (m.symbol !== undefined && (typeof m.symbol !== "string" || m.symbol.length > 60 || !/^[a-z0-9.]+$/.test(m.symbol))) return "bad symbol";
  // Optional companion opt-in: the app projects each event into a Chat view.
  if (m.chat !== undefined && typeof m.chat !== "boolean") return "bad chat flag";
  // Optional group opt-in: the app may ALSO be added to a group chat, where
  // one shared instance runs for everyone (same meaning as a built-in app's
  // `groupCapable` — see apps.js). Orthogonal to `scope`, which stays
  // "personal": the app still gets its own personal thread too.
  if (m.groupCapable !== undefined && typeof m.groupCapable !== "boolean") return "bad groupCapable flag";
  // Optional space opt-in: the app may be installed FOR THE WHOLE SPACE — one
  // shared instance in the hidden space thread, its commands available in
  // every chat (same meaning as a built-in app's `spaceCapable` — see apps.js
  // and docs/space-apps.md).
  if (m.spaceCapable !== undefined && typeof m.spaceCapable !== "boolean") return "bad spaceCapable flag";
  // Optional places-first declaration (docs/space-apps.md): any NON-EMPTY
  // subset of ["you","chat","space"] — a member app needs somewhere to live,
  // but which places is the author's call: personal-only is the common shape,
  // and a space-only app (one shared copy, gif-style) is just as legal.
  // Overrides the boolean flags above. (Legacy manifests without places imply
  // "you" — that generation was personal by definition.)
  if (m.places !== undefined) {
    if (!Array.isArray(m.places) || !m.places.every((x) => x === "you" || x === "chat" || x === "space")) return "bad places list";
    if (!m.places.length) return "places must name at least one place";
  }
  // Optional listed:false — the implicitly-placed shape (the /gif model,
  // docs/space-apps.md): the app stays out of the catalogues, and a
  // space-only unlisted app's one copy is used on first command, no add
  // gesture. Anything but a boolean is a malformed manifest.
  if (m.listed !== undefined && typeof m.listed !== "boolean") return "bad listed flag";
  // Optional one-line reason a place is off ("why can't I add this here?"),
  // shown muted in the Apps sheet on unsupported places.
  if (m.placeNote !== undefined && (typeof m.placeNote !== "string" || m.placeNote.length > 120)) return "bad placeNote";
  // Optional quiet opt-in: a command answering in place must not force this
  // app's personal thread into view (same meaning as a built-in app's `quiet`
  // — see apps.js, issue #227).
  if (m.quiet !== undefined && typeof m.quiet !== "boolean") return "bad quiet flag";
  // Optional defaultCommand: plain text in the Chat view runs it. Must name a
  // command the app declares (so the host has a handler to route text to).
  if (m.defaultCommand !== undefined) {
    if (typeof m.defaultCommand !== "string" || !CMD_RE.test(m.defaultCommand)) return "bad defaultCommand";
    if (!(m.commands || []).some((c) => c.name === m.defaultCommand)) {
      return `defaultCommand "${m.defaultCommand}" isn't one of the app's commands`;
    }
  }
  return null;
}

const BAD_KEYS = new Set(["__proto__", "constructor", "prototype"]);

// cleanJSON deep-copies untrusted structured data into plain JSON values:
// objects/arrays/strings/finite numbers/booleans/null only, hostile keys
// rejected, depth-bounded. Returns undefined when the value can't be accepted.
export function cleanJSON(v, depth = 0) {
  if (depth > 8) return undefined;
  if (v === null) return null;
  const t = typeof v;
  if (t === "string") return v.length > 8192 ? undefined : v;
  if (t === "number") return Number.isFinite(v) ? v : undefined;
  if (t === "boolean") return v;
  if (Array.isArray(v)) {
    if (v.length > 1024) return undefined;
    const out = [];
    for (const it of v) {
      const c = cleanJSON(it, depth + 1);
      if (c === undefined) return undefined;
      out.push(c);
    }
    return out;
  }
  if (t === "object") {
    const out = {};
    for (const k of Object.keys(v)) {
      if (BAD_KEYS.has(k) || k.length > 64) return undefined;
      const c = cleanJSON(v[k], depth + 1);
      if (c === undefined) return undefined;
      out[k] = c;
    }
    return out;
  }
  return undefined; // functions, symbols, bigints, undefined
}

// sanitizeAppEvent admits an event a frame wants on the wire: its own types
// only, clean JSON, no transport-injected fields, notice reduced to plain
// clamped strings (never action chips), and a total size cap. Returns the
// cleaned event or null.
export function sanitizeAppEvent(appName, ownedTypes, event) {
  const e = cleanJSON(event);
  if (!e || typeof e !== "object" || Array.isArray(e)) return null;
  if (typeof e.type !== "string" || !e.type.startsWith(appName + ".")) return null;
  if (ownedTypes && !ownedTypes.includes(e.type)) return null;
  delete e.name; // the transport injects these; a frame must not choose them
  delete e.ts;
  delete e.uid;
  if (e.notice !== undefined) {
    const n = e.notice;
    if (!n || typeof n !== "object" || Array.isArray(n)) return null;
    e.notice = {
      title: String(n.title || "").slice(0, 120),
      body: String(n.body || "").slice(0, 400),
    };
  }
  try {
    if (JSON.stringify(e).length > MAX_EVENT_JSON) return null;
  } catch {
    return null;
  }
  return e;
}

// sanitizePanelSpec admits a command panel request from a frame (the
// declarative ctx.panel form — see sandbox-frame.js's header): clamped title,
// whitelisted position/animate, and `data` (the JSON handed to the app's
// panel hook) cleaned and size-capped. Returns the cleaned spec or null.
export function sanitizePanelSpec(spec) {
  if (!spec || typeof spec !== "object" || Array.isArray(spec)) return null;
  // Field-wise, not cleanJSON on the whole object: an app that leaves
  // position/animate unset ships them as `undefined` properties, which
  // cleanJSON (rightly) rejects wholesale — only `data` is arbitrary JSON.
  const data = spec.data === undefined || spec.data === null ? null : cleanJSON(spec.data);
  if (data === undefined) return null;
  const out = { title: String(spec.title || "").slice(0, 80), data };
  if (spec.position === "top") out.position = "top";
  if (spec.animate === false) out.animate = false;
  try {
    if (JSON.stringify(data).length > 64 * 1024) return null;
  } catch {
    return null;
  }
  return out;
}

// ---- the proxy app ---------------------------------------------------------

// One shared stylesheet for every sandbox mount (injected once).
function injectSandboxStyles() {
  if (typeof document === "undefined" || document.getElementById("sandbox-style")) return;
  const st = document.createElement("style");
  st.id = "sandbox-style";
  st.textContent = `
.sandbox-pane { display: flex; flex-direction: column; height: 100%; }
/* Sandboxed apps own their full surface edge-to-edge — drop the app-pane's
   16px inset (apps.js), which is meant for built-in apps rendering DOM
   directly into the pane. The app adds its own padding inside the frame.
   (render() puts .sandbox-pane on the pane element itself.) */
.thread-view.app-mode .app-pane.sandbox-pane { padding: 0; gap: 0; }
.sandbox-note { padding: 8px 12px; font-size: 13px; color: var(--muted); border-bottom: 1px solid var(--border); }
.sandbox-note.err { color: var(--danger); }
.sandbox-frame { flex: 1 1 auto; width: 100%; border: 0; display: block; }
`;
  document.head.appendChild(st);
}

// Live mounts: iframe element → mount record. One global listener routes each
// frame's "ready" (sent on load AND on reload — a parked pane's iframe reloads
// when it re-enters the DOM) to its record and (re-)initialises the bridge.
const mounts = new Map();

// resolveDark turns a computed `color-scheme` value into a concrete dark/light
// decision for the frame. The app writes "light", "dark", or "light dark" (the
// last means "follow the OS" — colorScheme() in ui.js), so a plain
// .includes("dark") reads "light dark" as dark and forces every app dark even in
// light mode. Explicit wins; the ambiguous "light dark"/unset case follows the OS.
export function resolveDark(colorScheme, osPrefersDark) {
  const s = (colorScheme || "").trim();
  const hasDark = /\bdark\b/.test(s);
  const hasLight = /\blight\b/.test(s);
  if (hasDark && !hasLight) return true;
  if (hasLight && !hasDark) return false;
  return !!osPrefersDark;
}

function themeSnapshot() {
  const cs = getComputedStyle(document.documentElement);
  const vars = {};
  for (const k of THEME_VARS) {
    const v = cs.getPropertyValue(k);
    if (v) vars[k] = v.trim();
  }
  return {
    vars,
    font: getComputedStyle(document.body).font || "",
    dark: resolveDark(cs.colorScheme, matchMedia("(prefers-color-scheme: dark)").matches),
  };
}

// pushTheme forwards the CURRENT theme to every live sandbox frame, so member
// apps re-tint the moment the member switches theme/appearance — the shell calls
// it from its own applyTheme. (Without this a frame keeps its init-time theme
// until it's re-mounted, e.g. by revisiting the thread.)
export function pushTheme() {
  const msg = { type: "theme", ...themeSnapshot() };
  for (const rec of mounts.values()) {
    if (rec.port) {
      try {
        rec.port.postMessage(msg);
      } catch {}
    }
  }
}

function seedFrom(state) {
  const s = state || {};
  return { v: s.v === undefined ? null : s.v, vUpTo: s.vUpTo || 0, pend: s.pend || [], chat: s.chat || [] };
}

// initMount is driven by the iframe's `load` event (see registerMemberApp),
// NOT by a postMessage from the frame. That distinction is load-bearing: a
// `load` event fires only on a genuine document (re)load and cannot be forged
// by the code running inside the frame, whereas a `postMessage` "ready" can —
// so a hostile app could otherwise spam a fake ready to make the host swap to
// a fresh port the live frame never adopts, freezing event delivery. By the
// time the parent's `load` fires, the frame's module script has already run
// and installed its init listener, so posting the port here always lands.
function initMount(rec) {
  const chan = new MessageChannel();
  rec.port = chan.port1;
  rec.sent = new Set();
  rec.emits = []; // rate-limit timestamps
  rec.port.onmessage = (ev) => onFrameMessage(rec, ev);
  const state = rec.ctx.getState();
  const seed = seedFrom(state);
  for (const it of seed.pend) if (it && it.meta && it.meta.id != null) rec.sent.add(it.meta.id);
  const init = {
    type: "lchat-sandbox-init",
    source: rec.app.memberApp.source,
    manifest: rec.app.memberApp.manifest,
    threadId: rec.ctx.threadId,
    me: { uid: rec.ctx.me, name: rec.ctx.meName },
    theme: themeSnapshot(),
    seed,
  };
  // A panel frame boots straight into the app's panel hook (sandbox-frame.js).
  if (rec.panelFrame) init.panel = { data: rec.panelData === undefined ? null : rec.panelData };
  rec.iframe.contentWindow.postMessage(
    init,
    // The frame's origin is opaque, so "*" is the only addressable target;
    // the transferred port scopes the channel to exactly this frame.
    "*",
    [chan.port2],
  );
}

function note(rec, text, isErr) {
  let n = rec.el.querySelector(".sandbox-note");
  if (!text) {
    if (n) n.remove();
    return;
  }
  if (!n) {
    n = document.createElement("div");
    n.className = "sandbox-note";
    rec.el.prepend(n);
  }
  n.classList.toggle("err", !!isErr);
  n.textContent = text;
}

function onFrameMessage(rec, ev) {
  const m = ev.data;
  if (!m || typeof m !== "object") return;
  const app = rec.app;
  const ctx = rec.ctx;
  switch (m.type) {
    case "state": {
      if (rec.panelFrame) return; // the app-thread's own frame owns state
      const upTo = m.upTo;
      if (typeof upTo !== "number" || !Number.isFinite(upTo) || upTo < 0) return;
      const state = cleanJSON(m.state);
      if (state === undefined) return;
      const chat = app.memberApp.manifest.chat ? sanitizeChat(m.chat) : undefined;
      try {
        // Guard the WHOLE persisted object (state + projected chat), not just
        // state: the snapshot carries both, and together they must fit the
        // server's thread_state cap.
        if (JSON.stringify(state).length + (chat ? JSON.stringify(chat).length : 0) > MAX_STATE_JSON) {
          note(rec, "This app's state grew too large to save — recent changes may not persist.", true);
          return;
        }
      } catch {
        return;
      }
      installMemberAppState(ctx.threadId, app.name, state, upTo, chat);
      if (chat && chat.length) foldCompanionChat(ctx.threadId, app, chat);
      break;
    }
    case "command-reply": {
      const w = rec.cmdWaiters && rec.cmdWaiters.get(m.seq);
      if (w) {
        rec.cmdWaiters.delete(m.seq);
        w(m.spec && typeof m.spec === "object" ? m.spec : null);
      }
      break;
    }
    case "emit":
    case "ephemeral": {
      if (!allowSend(rec)) return;
      const e = sanitizeAppEvent(app.name, app.memberApp.manifest.types, m.event);
      if (!e) return;
      if (m.type === "emit") ctx.emit(e);
      else ctx.emitEphemeral(e);
      break;
    }
    case "schedule": {
      const seq = m.seq;
      if (!allowSend(rec)) {
        reply(rec, seq, null);
        return;
      }
      const e = sanitizeAppEvent(app.name, app.memberApp.manifest.types, m.event);
      const when = m.when;
      const sane =
        e && typeof when === "number" && Number.isFinite(when) &&
        when > Date.now() - 120_000 && when < Date.now() + 2 * 366 * 24 * 3600 * 1000;
      if (!sane) {
        reply(rec, seq, null);
        return;
      }
      ctx.schedule(e, when).then((sid) => reply(rec, seq, sid || null));
      break;
    }
    case "unschedule": {
      const sid = typeof m.sid === "string" && m.sid.length <= 64 ? m.sid : "";
      if (!sid || !allowSend(rec)) {
        reply(rec, m.seq, false);
        return;
      }
      Promise.resolve(ctx.unschedule(sid)).then((ok) => reply(rec, m.seq, !!ok));
      break;
    }
    case "panel-open": {
      // A COMMAND asking for a panel (declarative ctx.panel). Gated to a
      // still-live command invocation — the host ctx (with its panel opener,
      // bound to where the member typed) is looked up by the command's seq,
      // so a frame can't pop panels outside a command it was just asked to
      // run ("a response, not an ambush", for member apps too).
      const hostCtx = rec.cmdCtx && rec.cmdCtx.get(m.cmdSeq);
      const spec = hostCtx && typeof hostCtx.panel === "function" ? sanitizePanelSpec(m.spec) : null;
      if (!spec) {
        reply(rec, m.seq, false);
        return;
      }
      const opened = hostCtx.panel({
        title: spec.title,
        position: spec.position,
        animate: spec.animate,
        render: (el, handle) => mountPanelFrame(app, hostCtx.threadId, spec.data, el, handle),
        onClose: () => teardownPanelMount(app.name),
      });
      reply(rec, m.seq, !!opened);
      break;
    }
    case "panel-size": {
      // The panel frame fitting its content: clamp and size the iframe; the
      // host panel's own body scrolls beyond the cap.
      if (!rec.panelFrame) return;
      const h = typeof m.h === "number" && Number.isFinite(m.h) ? Math.min(600, Math.max(24, m.h)) : 0;
      if (h) rec.iframe.style.height = h + "px";
      break;
    }
    case "panel-close": {
      if (rec.panelFrame && rec.panelHandle) rec.panelHandle.close();
      break;
    }
    case "panel-insert": {
      // A panel acting on the composer it sits above (clamped; the same
      // doorway a trusted panel's insertText uses). Should follow a user tap.
      if (rec.panelFrame && rec.panelHandle && typeof m.text === "string") {
        rec.panelHandle.insertText(m.text.slice(0, 2000));
      }
      break;
    }
    case "error":
      note(rec, `App error: ${String(m.message || "unknown").slice(0, 200)}`, true);
      break;
  }
}

// ---- command panels for member apps ----------------------------------------

// One live panel frame per app (opening another replaces it, like the host
// panel itself). The frame is just another mount: its emits/schedules ride the
// same sanitized, rate-limited bridge; only `state` reports are ignored.
const panelMounts = new Map(); // app name → mount record

function mountPanelFrame(app, threadId, data, el, handle) {
  teardownPanelMount(app.name);
  injectSandboxStyles();
  const iframe = document.createElement("iframe");
  iframe.className = "sandbox-frame sandbox-panel-frame";
  iframe.setAttribute("sandbox", "allow-scripts");
  iframe.setAttribute("allow", "");
  iframe.referrerPolicy = "no-referrer";
  iframe.src = "/app-sandbox";
  iframe.style.cssText = "width:100%;border:0;display:block;height:96px";
  const rec = {
    iframe,
    el,
    app,
    ctx: memberCtx(threadId, app),
    port: null,
    sent: new Set(),
    emits: [],
    panelFrame: true,
    panelHandle: handle,
    panelData: data,
  };
  mounts.set(iframe, rec);
  panelMounts.set(app.name, rec);
  iframe.addEventListener("load", () => {
    rec.port = null;
    initMount(rec);
  });
  el.appendChild(iframe);
}

function teardownPanelMount(name) {
  const rec = panelMounts.get(name);
  if (!rec) return;
  panelMounts.delete(name);
  // Small grace so a click's in-flight emit still crosses before removal.
  setTimeout(() => {
    mounts.delete(rec.iframe);
    if (rec.iframe.parentNode) rec.iframe.remove();
  }, 2000);
}

function reply(rec, seq, value) {
  if (rec.port && typeof seq === "number") rec.port.postMessage({ type: "rpc-reply", seq, value });
}

// allowSend is the shared rate limit on everything a frame may push to the
// wire (emit / ephemeral / schedule / unschedule) — a runaway or hostile app
// can't flood the server with the member's credentials.
function allowSend(rec) {
  const now = Date.now();
  rec.emits = rec.emits.filter((t) => now - t < EMIT_WINDOW_MS);
  if (rec.emits.length >= EMIT_BURST) {
    note(rec, "This app is sending too fast — some of its updates were dropped.", true);
    return false;
  }
  rec.emits.push(now);
  return true;
}

// ---- companion chat ---------------------------------------------------------

// sanitizeChat cleans a frame's reported companion chat lines to plain data:
// each { mid, ts, text, action } with clamped strings. Untrusted, so bounded.
export function sanitizeChat(lines) {
  if (!Array.isArray(lines)) return [];
  const out = [];
  for (const l of lines.slice(-CHAT_CAP)) {
    if (!l || typeof l !== "object") continue;
    const mid = l.mid;
    const text = typeof l.text === "string" ? l.text : "";
    if (mid == null || !text) continue;
    out.push({
      mid,
      ts: Number.isFinite(l.ts) ? l.ts : 0,
      text: text.slice(0, 400),
      action: !!l.action,
    });
  }
  return out;
}
const CHAT_CAP = 200;

// foldCompanionChat folds the frame's projected lines into the thread's Chat
// view — the SAME path a trusted companion uses (foldAppEventBubble), a
// chat.msg attributed to the app, deduped by message id. Then refresh the
// surfaces so the Chat pane repaints.
//
// The dedupe id is NAMESPACED (`c:<mid>`), not the raw frame-reported mid: a
// hostile app (which controls its own frame's port) could otherwise report a
// mid equal to a not-yet-folded real message id in its own thread and, via the
// chat app's first-writer-wins dedupe, suppress the installer's own later note.
// Prefixing keeps projected ids in their own space, so they can never collide
// with a real chat.msg id — folding stays idempotent, ordering is by ts.
function foldCompanionChat(threadId, app, lines) {
  for (const l of lines) {
    foldHostEvent(
      threadId,
      "chat",
      { type: "chat.msg", name: app.title || app.name, text: l.text, uid: "app:" + app.name, ts: l.ts || Date.now(), action: l.action },
      { id: "c:" + l.mid, ts: l.ts },
    );
  }
  if (surfaceRefresh) {
    try {
      surfaceRefresh(threadId);
    } catch {}
  }
}

// ---- logic frames + commands ------------------------------------------------

// A member app's command handler is untrusted, so it runs in a frame. When the
// app's thread is open its live frame handles it; otherwise a transient hidden
// frame is mounted (seeded from the snapshot) just to execute the command, then
// torn down. Hidden frames live in one offscreen container.
function hiddenContainer() {
  let el = document.getElementById("sandbox-hidden");
  if (!el) {
    el = document.createElement("div");
    el.id = "sandbox-hidden";
    el.setAttribute("aria-hidden", "true");
    el.style.cssText = "position:absolute;width:0;height:0;overflow:hidden;border:0;left:-9999px;top:0";
    document.body.appendChild(el);
  }
  return el;
}

// ensureLogicFrame returns a live frame (with a ready port) bound to
// (app, threadId): a mounted visible/companion frame if one exists, else a
// freshly-mounted transient hidden frame seeded from the snapshot.
async function ensureLogicFrame(app, threadId) {
  for (const rec of mounts.values()) {
    if (rec.app === app && rec.ctx && rec.ctx.threadId === threadId && rec.port) return rec;
  }
  // Load the app-thread's snapshot so the frame's getState is accurate for a
  // state-reading command (a bare emit doesn't need it, but correctness first).
  if (memberSeeder) {
    try {
      await memberSeeder(threadId);
    } catch {}
  }
  return mountHiddenFrame(app, threadId);
}

function mountHiddenFrame(app, threadId) {
  const iframe = document.createElement("iframe");
  iframe.className = "sandbox-frame";
  iframe.setAttribute("sandbox", "allow-scripts");
  iframe.setAttribute("allow", "");
  iframe.referrerPolicy = "no-referrer";
  iframe.src = "/app-sandbox";
  const rec = {
    iframe,
    el: hiddenContainer(),
    app,
    ctx: memberCtx(threadId, app),
    port: null,
    sent: new Set(),
    emits: [],
    transient: true,
  };
  mounts.set(iframe, rec);
  return new Promise((resolve) => {
    rec.onReady = () => resolve(rec);
    iframe.addEventListener("load", () => {
      rec.port = null;
      initMount(rec);
      if (rec.onReady) {
        const r = rec.onReady;
        rec.onReady = null;
        r();
      }
    });
    hiddenContainer().appendChild(iframe);
    // Never hang a command on a frame that fails to load.
    setTimeout(() => {
      if (rec.onReady) {
        rec.onReady = null;
        resolve(rec);
      }
    }, 6000);
  });
}

function teardownTransient(rec) {
  if (!rec || !rec.transient || rec.tornDown) return;
  rec.tornDown = true;
  // Small grace so a late state report / reply still lands before removal.
  setTimeout(() => {
    mounts.delete(rec.iframe);
    if (rec.iframe.parentNode) rec.iframe.remove();
  }, 4000);
}

// runMemberCommand executes one slash command in a frame and shows its reply
// where the user typed. Invoked by the proxy's command wrapper; `hostCtx` is
// the apps.js ctx bound to the app's thread (with ctx.reply set by runCommand).
async function runMemberCommand(app, hostCtx, cmdName, args) {
  const rec = await ensureLogicFrame(app, hostCtx.threadId);
  if (!rec) return;
  // finally: a transient frame that never got a port (a load-event timeout)
  // must still be torn down, or it leaks a stranded hidden iframe.
  try {
    if (!rec.port) return;
    const spec = await sendCommand(rec, cmdName, args, hostCtx);
    if (spec && hostCtx.reply) hostCtx.reply(sanitizeReply(spec, app, hostCtx));
  } finally {
    teardownTransient(rec);
  }
}

let cmdSeq = 0;
function sendCommand(rec, cmd, args, hostCtx) {
  if (!rec.cmdWaiters) rec.cmdWaiters = new Map();
  if (!rec.cmdCtx) rec.cmdCtx = new Map();
  const seq = ++cmdSeq;
  // The host ctx stays addressable past the command's reply: a handler may
  // reply first and open its panel after an await. The window is bounded.
  rec.cmdCtx.set(seq, hostCtx);
  setTimeout(() => rec.cmdCtx.delete(seq), 20000);
  return new Promise((resolve) => {
    rec.cmdWaiters.set(seq, resolve);
    rec.port.postMessage({ type: "command", seq, cmd, args: String(args || "") });
    setTimeout(() => {
      if (rec.cmdWaiters.delete(seq)) resolve(null);
    }, 15000);
  });
}

// sanitizeReply reduces a frame's command reply to a private confirmation:
// clamped text/short, and a host-owned "Open <app>" chip so the member can
// jump to the app after a quick capture (the ONLY action — the app can't ship
// arbitrary clickable code into the host).
function sanitizeReply(spec, app, hostCtx) {
  const text = String(spec.text || "").slice(0, 500);
  if (!text) return { text: "" };
  const out = { text, short: spec.short != null ? String(spec.short).slice(0, 200) : undefined };
  if (hostCtx && typeof hostCtx.open === "function") {
    out.actions = [{ label: `Open ${app.title || app.name}`, run: hostCtx.open }];
  }
  return out;
}

// The queue fold every proxy type shares: append, bounded. Dropping the
// oldest breaks v-continuity, so mark the state `lost` — the app still works
// forward, and the flag is visible for debugging. (The frame drains the
// queue whenever the app is open, so hitting the cap means hundreds of events
// arrived while this app was never once opened.)
function queueEvent(s, e, meta) {
  const pend = [...(s.pend || []), { e, meta: { id: meta && meta.id, ts: meta && meta.ts } }];
  if (pend.length > MAX_PEND) {
    return { v: s.v, vUpTo: s.vUpTo || 0, pend: pend.slice(pend.length - MAX_PEND), lost: true };
  }
  return { v: s.v, vUpTo: s.vUpTo || 0, pend, lost: s.lost };
}

// registerMemberApp validates and registers one decrypted member app as a
// sandbox proxy. Returns { ok: true } or { ok: false, reason }.
const registeredIds = new Set();
export function registerMemberApp({ id, manifest, source, author }) {
  const err = validateManifest(manifest);
  if (err) return { ok: false, reason: err };
  if (typeof source !== "string" || !source.trim() || source.length > 512 * 1024) {
    return { ok: false, reason: "bad source" };
  }
  if (registeredIds.has(id)) return { ok: false, reason: "already registered" };
  if (appByName(manifest.name)) return { ok: false, reason: `an app named "${manifest.name}" already exists` };
  for (const t of manifest.types) {
    if (isAppType(t)) return { ok: false, reason: `event type "${t}" is already owned by another app` };
  }
  // The command twin of the type check above, and it is LOAD-TIME security,
  // not deploy UX: member apps register after the built-ins, so without it a
  // crafted blob claiming "/todo" (or "/help") would overwrite commandOwner
  // on every member's client and route their typed arguments into the
  // hijacker-readable log — worse still for a places:["space"] app, whose
  // log every member's hijacked commands would share.
  for (const c of manifest.commands || []) {
    const taken = commandTakenBy(c.name);
    if (taken) return { ok: false, reason: `command ${c.name} is already taken (${taken === "host" ? "built-in" : `by ${taken}`})` };
  }

  const events = {};
  for (const t of manifest.types) events[t] = queueEvent;

  // Command METADATA → proxy handlers. The handler forwards to the app-thread's
  // frame (runMemberCommand); the untrusted logic never runs in the page.
  const commands = {};
  for (const c of manifest.commands || []) {
    commands[c.name] = {
      desc: c.desc || "",
      args: c.args || "",
      run: (args, ctx) => runMemberCommand(app, ctx, c.name, args),
    };
  }

  const app = defineApp({
    name: manifest.name,
    title: manifest.title,
    glyph: manifest.glyph,
    symbol: manifest.symbol,
    blurb: author ? `Built by ${author}` : "A member-built app",
    incremental: true, // the iframe must survive re-renders; we pump instead
    initialState: () => ({ v: null, vUpTo: 0, pend: [], chat: [] }),
    events,
    commands,
    // A companion app opts in with manifest.chat: give the proxy a chatMessage
    // so appWantsChatView() sees it as a companion (Chat + Interface views).
    // It returns null — the real projection runs in the frame and folds into
    // the Chat view via foldCompanionChat, so foldAppEventBubble adds nothing.
    ...(manifest.chat ? { chatMessage: () => null } : {}),
    // defaultCommand: plain text in the Chat view runs this command (validated
    // above to be one of `commands`). defaultCommandFor(threadId) reads it, so a
    // member app gets the same "type to add" behaviour trusted apps have.
    ...(manifest.defaultCommand && commands[manifest.defaultCommand] ? { defaultCommand: manifest.defaultCommand } : {}),
    // The app's PLACES (the one-field declaration, docs/space-apps.md): a
    // places-first manifest passes straight through — ANY non-empty subset,
    // "you" included only if declared (a space-only member app is legal).
    // The legacy groupCapable/spaceCapable booleans — stored member apps are
    // user content, never migrated — normalize into it, with "you" fixed for
    // that generation only (it was personal by definition). Either way this
    // is the author's explicit trust decision (declared in the source's
    // defineApp, never derived from code shape); the chat/space fold
    // machinery (groupapps.*, spaceapps.*) keys off the result.
    places: manifest.places || ["you", ...(manifest.groupCapable ? ["chat"] : []), ...(manifest.spaceCapable ? ["space"] : [])],
    // listed: false — the implicitly-placed shape (validated above): the app
    // stays out of the catalogues; a space-only unlisted app routes to the
    // space's one copy on first command, no add gesture (the /gif model).
    ...(manifest.listed === false ? { listed: false } : {}),
    ...(typeof manifest.placeNote === "string" && manifest.placeNote ? { placeNote: manifest.placeNote } : {}),
    // quiet: the author opted this app into never forcing its personal thread
    // into view on mere activity (manifest.quiet — same meaning and same
    // enforcement path as a built-in app's `quiet`, see apps.js + issue #227).
    ...(manifest.quiet ? { quiet: true } : {}),
    // memberApp marks the proxy (apps.js gates installMemberAppState on it)
    // and carries what the frame needs at init.
    memberApp: { id, source, manifest, author: author || "" },
    render(state, el, ctx) {
      injectSandboxStyles();
      el.classList.add("sandbox-pane");
      let iframe = el.querySelector("iframe.sandbox-frame");
      const fresh = !iframe;
      if (fresh) {
        iframe = document.createElement("iframe");
        iframe.className = "sandbox-frame";
        iframe.setAttribute("sandbox", "allow-scripts");
        iframe.setAttribute("allow", "");
        iframe.referrerPolicy = "no-referrer";
        iframe.src = "/app-sandbox";
      }
      let rec = mounts.get(iframe);
      if (!rec) {
        rec = { iframe, el, app, ctx, port: null, sent: new Set(), emits: [] };
        mounts.set(iframe, rec);
        // Drop records whose iframe left the DOM for good (thread switched,
        // pane rebuilt) so mounts can't grow unboundedly.
        for (const [f, r] of [...mounts]) {
          if (f !== iframe && !f.isConnected && r.el !== el) mounts.delete(f);
        }
      }
      if (fresh) {
        // Init on the (unforgeable) load event — fires on the first load AND
        // whenever the pane is re-inserted (which reloads the iframe with a
        // fresh document + a fresh port). Reset the port between loads so a
        // stale one is never used before re-init.
        iframe.addEventListener("load", () => {
          rec.port = null;
          initMount(rec);
        });
        el.appendChild(iframe);
      }
      rec.ctx = ctx; // renders hand us a fresh ctx; keep the newest
      rec.el = el;
      if (state && state.lost) {
        note(rec, "Some older activity couldn't be kept — this app may be missing items.", false);
      }
      // Pump: forward queued events the live frame hasn't seen. (No port yet
      // means the frame is still loading; init will carry them in the seed.)
      if (rec.port) {
        const batch = (state && state.pend ? state.pend : []).filter(
          (it) => it && it.meta && it.meta.id != null && !rec.sent.has(it.meta.id),
        );
        if (batch.length) {
          for (const it of batch) rec.sent.add(it.meta.id);
          rec.port.postMessage({ type: "events", batch });
        }
      }
    },
    ephemeral(event, ctx) {
      // Relay-only traffic of this app's types, forwarded into a live frame.
      for (const rec of mounts.values()) {
        if (rec.app === app && rec.port && rec.ctx.threadId === ctx.threadId) {
          rec.port.postMessage({ type: "ephemeral-in", event });
        }
      }
    },
  });
  registeredIds.add(id);
  return { ok: true, app };
}

// ---- boot-time loading ------------------------------------------------------

let loadInflight = null;

// loadMemberApps fetches, decrypts, and registers every deployed member app.
// Needs the instance key (member-app blobs are sealed under it); when the key
// hasn't arrived yet the call resolves and the shell retries from
// onInstanceKeyReady. authorName maps a user id to a display name for the
// "Built by …" byline (best-effort; may return "").
export async function loadMemberApps({ token, instanceKey, authorName }) {
  if (!instanceKey || loadInflight) return loadInflight;
  loadInflight = (async () => {
    try {
      const r = await fetch(`/api/member-apps?token=${encodeURIComponent(token)}`);
      if (!r.ok) return;
      const { apps } = await r.json();
      // Decrypt every blob concurrently (they're independent), then register
      // in listing order so registration stays deterministic.
      const opened = await Promise.all(
        (apps || []).map(async (entry) => {
          if (!entry || typeof entry.id !== "string" || registeredIds.has(entry.id)) return null;
          try {
            return { entry, doc: await decrypt(instanceKey, entry.blob) };
          } catch (e) {
            console.warn(`member app ${entry.id} failed to load:`, e);
            return null;
          }
        }),
      );
      for (const item of opened) {
        if (!item) continue;
        const { entry, doc } = item;
        const res = registerMemberApp({
          id: entry.id,
          manifest: doc && doc.manifest,
          source: doc && doc.source,
          author: (authorName && authorName(entry.author_id)) || "",
        });
        if (!res.ok) console.warn(`member app ${entry.id} skipped: ${res.reason}`);
      }
    } catch (e) {
      console.error("member apps skipped:", e);
    } finally {
      loadInflight = null;
    }
  })();
  return loadInflight;
}

// ---- App Studio: member-facing list / deploy / retire -----------------------
// These power web/static/apps/appstudio.js — a member pasting their own app
// code and deploying it directly, no bot. Privileged (they touch the token +
// instance key), so App Studio is a TRUSTED compiled-in app that imports these;
// sandboxed member apps never can.

// manifestIsLegacy: does a STORED manifest still speak the legacy placement
// vocabulary — no `places` array, so loading falls back to the old
// scope/groupCapable/spaceCapable fields? Loading such an app keeps working
// (the one compat funnel — docs/member-apps.md § Legacy formats), but App
// Studio flags it and offers a one-tap upgrade: redeploying the SAME source
// re-mints a current manifest (manifestOf emits places-first), a new version
// with the old kept in History. Pure, exported for tests.
export function manifestIsLegacy(m) {
  return !!m && !Array.isArray(m.places);
}

// recentLocalDeploy lets shell.js skip a full page reload on the apps_changed
// broadcast this client just caused — it registers the new app live instead.
let lastLocalDeployAt = 0;
export function recentLocalDeploy() {
  return Date.now() - lastLocalDeployAt < 5000;
}

function mintAppId() {
  const b = crypto.getRandomValues(new Uint8Array(6));
  return "app-" + [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
}

// extractManifest runs pasted source in a throwaway sandbox frame purely to
// read back its manifest (the real defineApp, evaluated in the cage) — never in
// the page. Returns { manifest } or { error }.
export function extractManifest(source) {
  if (typeof source !== "string" || !source.trim()) return Promise.resolve({ error: "paste some app code first" });
  if (source.length > 512 * 1024) return Promise.resolve({ error: "that code is too large" });
  return new Promise((resolve) => {
    const iframe = document.createElement("iframe");
    iframe.setAttribute("sandbox", "allow-scripts");
    iframe.setAttribute("allow", "");
    iframe.referrerPolicy = "no-referrer";
    iframe.src = "/app-sandbox";
    iframe.style.cssText = "position:absolute;width:0;height:0;border:0;left:-9999px;top:0";
    let done = false;
    const finish = (v) => {
      if (done) return;
      done = true;
      iframe.remove();
      resolve(v);
    };
    iframe.addEventListener("load", () => {
      const chan = new MessageChannel();
      chan.port1.onmessage = (ev) => {
        const m = ev.data;
        if (m && m.type === "extracted") finish(m.error ? { error: m.error } : { manifest: m.manifest });
      };
      iframe.contentWindow.postMessage({ type: "lchat-sandbox-init", extract: true, source }, "*", [chan.port2]);
    });
    hiddenContainer().appendChild(iframe);
    setTimeout(() => finish({ error: "the app didn't load in time" }), 6000);
  });
}

// listDeployedApps returns every deployed member app (decrypted), each flagged
// `mine` when the current member owns it — whether they deployed it themselves or
// a bot built it for them (owner_id), so their Claude-built apps are theirs to
// edit/remove too. For App Studio's list.
export async function listDeployedApps() {
  const admin = memberAdmin && memberAdmin();
  if (!admin || !admin.instanceKey) return { error: "your space key hasn't loaded yet — try again in a moment" };
  let apps;
  try {
    const r = await fetch(`/api/member-apps?token=${encodeURIComponent(admin.token)}`);
    if (!r.ok) return { error: `couldn't list apps (${r.status})` };
    ({ apps } = await r.json());
  } catch (e) {
    return { error: "couldn't reach the server" };
  }
  const out = [];
  for (const entry of apps || []) {
    if (!entry || typeof entry.id !== "string") continue;
    let doc = null;
    try {
      doc = await decrypt(admin.instanceKey, entry.blob);
    } catch {
      // A blob we can't open (shouldn't happen — one instance key) still lists
      // by id so an admin could retire it.
    }
    out.push({
      id: entry.id,
      manifest: (doc && doc.manifest) || null,
      source: (doc && doc.source) || "",
      mine: entry.owner_id === admin.uid || entry.author_id === admin.uid,
      // AI-generated: a bot deployed it for its owner (deployer ≠ owner). A
      // hand-deployed app has author === owner. (Only meaningful once owner_id is
      // recorded, so legacy owner-less apps read as not-bot.)
      byBot: !!(entry.owner_id && entry.author_id && entry.author_id !== entry.owner_id),
      version: entry.version,
      updatedAt: entry.updated_at,
    });
  }
  return { apps: out };
}

// listAppVersions returns an app's version history (decrypted), newest first,
// for App Studio's History view. Each entry carries the source so "Restore" can
// re-deploy it (see deployMemberApp) — which records it as a new version.
export async function listAppVersions(id) {
  const admin = memberAdmin && memberAdmin();
  if (!admin || !admin.instanceKey) return { error: "your space key hasn't loaded yet — try again in a moment" };
  let data;
  try {
    const r = await fetch(`/api/member-apps/${encodeURIComponent(id)}/versions?token=${encodeURIComponent(admin.token)}`);
    if (!r.ok) return { error: `couldn't load history (${r.status})` };
    data = await r.json();
  } catch {
    return { error: "couldn't reach the server" };
  }
  const out = [];
  for (const v of data.versions || []) {
    let doc = null;
    try {
      doc = await decrypt(admin.instanceKey, v.blob);
    } catch {}
    out.push({
      version: v.version,
      current: v.version === data.current,
      source: (doc && doc.source) || "",
      byMe: v.author_id === admin.uid,
      at: v.created_at,
      based_on: v.based_on || 0, // the version this one was reverted from (0 = none)
    });
  }
  return { current: data.current, versions: out };
}

// deployMemberApp validates + deploys pasted source directly (App Studio's
// Deploy). Pass { id } to UPDATE an app you already own (same thread + state);
// omit it to create a new one. Pass { basedOn: N } on a revert to mark the new
// version as "based on version N". Returns { ok, id, updated } or { error }.
export async function deployMemberApp(source, opts = {}) {
  const admin = memberAdmin && memberAdmin();
  if (!admin || !admin.instanceKey) return { error: "your space key hasn't loaded yet — try again in a moment" };
  const ext = await extractManifest(source);
  if (ext.error) return { error: ext.error };
  const manifest = ext.manifest;
  const verr = validateManifest(manifest);
  if (verr) return { error: verr };

  const updating = !!opts.id;
  if (!updating) {
    // A NEW app can't collide with an already-registered name/event type.
    if (appByName(manifest.name)) return { error: `an app named “${manifest.name}” already exists — rename yours` };
    for (const t of manifest.types) {
      if (isAppType(t)) return { error: `event type “${t}” is already used by another app` };
    }
  }
  // Command names can't collide either — with a built-in verb, the host set
  // (/help, /me, …), or another app's. An UPDATE may of course keep the
  // commands this app itself already owns. registerMemberApp enforces the
  // same rule at load time on every client (that one is the security gate —
  // a blob can be crafted straight to the API); this check is the friendly
  // deploy-time error.
  for (const c of manifest.commands || []) {
    const taken = commandTakenBy(c.name);
    if (taken && taken !== manifest.name) return { error: `command ${c.name} is already taken (${taken === "host" ? "built-in" : `by ${taken}`}) — pick another name` };
  }
  const id = opts.id || mintAppId();
  const doc = { source, manifest: { ...manifest, owner: admin.uid, by: admin.name || "" } };
  let blob;
  try {
    blob = await encrypt(admin.instanceKey, doc);
  } catch {
    return { error: "couldn't encrypt the app" };
  }
  let res;
  try {
    const put = { token: admin.token, blob };
    if (updating && opts.basedOn > 0) put.based_on = opts.basedOn;
    res = await fetch(`/api/member-apps/${encodeURIComponent(id)}`, {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(put),
    });
  } catch {
    return { error: "couldn't reach the server" };
  }
  if (!res.ok) {
    // The server says why in httpError's {error} body — the feature gates
    // ("making your own apps is turned off for this space"), the app caps,
    // author-only updates. Show its words rather than guessing from the
    // status (a guessed "app limit" on a gated 403 misleads).
    const msg = await res.json().then((j) => (j && j.error) || "").catch(() => "");
    return { error: msg || `deploy was rejected (${res.status})` };
  }
  // A brand-new app registers live so it's usable without a reload (and we
  // suppress this client's own apps_changed reload). An UPDATE changes code the
  // running proxy already loaded, so it needs a fresh load — let the
  // apps_changed broadcast reload every client, this one included.
  lastLocalDeployAt = updating ? 0 : Date.now();
  if (!updating && !registeredIds.has(id)) {
    registerMemberApp({ id, manifest: doc.manifest, source, author: admin.name || "" });
  }
  return { ok: true, id, updated: updating };
}

// openMemberApp launches a member app's personal thread (App Studio's "Open"),
// via the host opener shell.js injects.
export function openMemberApp(name) {
  const admin = memberAdmin && memberAdmin();
  if (admin && admin.openApp) return admin.openApp(name);
}

// The rest of the place-aware "Open" seam (appOpenPlan in ui.js): the group
// chats an app could be added to, the add-and-land opener for one of them,
// the space-wide opener, and whether this page is a native embed (where only
// the personal open can hand off to the native shell today). All thin
// forwards to the host context — the studio never touches shell state itself.
export function memberAppGroups() {
  const admin = memberAdmin && memberAdmin();
  return admin && admin.groups ? admin.groups() : [];
}
export function openMemberAppInGroup(name, threadId) {
  const admin = memberAdmin && memberAdmin();
  return admin && admin.openAppInGroup ? admin.openAppInGroup(name, threadId) : false;
}
export function openMemberAppForSpace(name) {
  const admin = memberAdmin && memberAdmin();
  return admin && admin.openAppForSpace ? admin.openAppForSpace(name) : false;
}
export function memberHostEmbedded() {
  const admin = memberAdmin && memberAdmin();
  return !!(admin && admin.embedded);
}

// retireMemberApp deletes a member app (author-only, enforced server-side).
export async function retireMemberApp(id) {
  const admin = memberAdmin && memberAdmin();
  if (!admin) return { error: "not ready" };
  try {
    const r = await fetch(`/api/member-apps/${encodeURIComponent(id)}?token=${encodeURIComponent(admin.token)}`, { method: "DELETE" });
    if (!r.ok) return { error: r.status === 403 ? "only the author can remove this app" : `couldn't remove it (${r.status})` };
  } catch {
    return { error: "couldn't reach the server" };
  }
  return { ok: true };
}