openclacky 1.3.6 → 1.3.7

data/lib/clacky/web/core/ext.js

@@ -1,12 +1,17 @@
 // ── Clacky.ext — WebUI extension registry ─────────────────────────────────
 //
-// The single, controlled entry point through which user/AI-authored
-// extensions (loaded from ~/.clacky/webui_ext/) hook into the WebUI.
+// The single, controlled entry point through which extensions declared
+// in an ext.yml container hook into the WebUI.
 //
 // Three capabilities (the whole contract an extension author must learn):
 //   Clacky.ext.api.register(name, fn)        — register a data source
 //   Clacky.ext.subscribe(event, handler)     — listen to store events (read-only)
-//   Clacky.ext.ui.mount(slot, renderFn)      — inject UI into a named slot
+//   Clacky.ext.ui.mount(slot, spec, opts)    — inject UI into a named slot
+//
+//   `spec` is either a render function or { create?, render }. On per-session
+//   slots (session.aside/banner/composer), providing `create(ctx)` gives you
+//   one runtime per sessionId, isolated across sessions and disposed only
+//   when the session leaves the sidebar.
 //
 // Safety guarantees enforced here (the "constitution"):
 //   - Every extension callback is wrapped in try/catch. A throwing extension is
@@ -23,9 +28,9 @@
 window.Clacky = window.Clacky || {};
 
 Clacky.ext = (() => {
-  // Pure mode: detect ?pure=true once. When on, all registration is a no-op and
-  // the host must not load any webui_ext scripts (handled server-side / in the
-  // loader). This is the ultimate escape hatch back to a clean official UI.
+  // Pure mode: detect ?pure=true once. When on, all registration is a no-op
+  // and the host must not inject any extension scripts (handled server-side).
+  // This is the ultimate escape hatch back to a clean official UI.
   const PURE = (() => {
     try {
       return new URLSearchParams(window.location.search).get("pure") === "true";
@@ -37,6 +42,7 @@ Clacky.ext = (() => {
   const _dataSources = {};            // name => fn
   const _subscribers = {};            // event => [handler]
   const _slotRenderers = {};          // slot => [{ fn, extId, agents, panel, order, tab }]
+  const _workspaces = {};             // id => { id, title, render, extId }
   let   _currentExtId = null;         // set while an extension file is loading
 
   // Slots that render as a tabbed container instead of a vertical stack: each
@@ -46,6 +52,40 @@ Clacky.ext = (() => {
   // slot => active tab id (remembered across re-renders within a page load).
   const _activeTab = {};
 
+  // Slots that follow the current session's agent scope. A mount into any
+  // of these, made from inside a panel file, is confined to that panel's
+  // agents (via _currentPanel). Every other slot — sidebar, header, main
+  // workspace — is treated as global chrome: mounts there always show,
+  // regardless of which panel file happened to be loading. This is what
+  // separates "session UI" from "app chrome" and it is the ONLY place
+  // that distinction lives.
+  const SESSION_SCOPED_SLOTS = {
+    "session.banner": true,
+    "session.composer": true,
+    "session.aside": true,
+    "settings.tabs": true,
+    "settings.body": true,
+  };
+
+  // Named slots the host renders. Extensions mounting into any other name
+  // will silently do nothing — we warn once per bad name to catch typos
+  // like "sidebar-nav.top" or "session.aisde" during development.
+  const KNOWN_SLOTS = {
+    "header.left": true,
+    "header.right": true,
+    "sidebar.nav.top": true,
+    "sidebar.nav": true,
+    "sidebar.nav.bottom": true,
+    "sidebar.footer": true,
+    "main.workspace": true,
+    "session.banner": true,
+    "session.composer": true,
+    "session.aside": true,
+    "settings.tabs": true,
+    "settings.body": true,
+  };
+  const _warnedUnknownSlots = {};
+
   // Per-extension/panel agent scoping declared at load time:
   //   _extAgents[extId]  = ["coding", ...]   (from <script data-agent=...>, may be multiple)
   //   _panelAgents[panel] = ["coding", ...]  (agents whose profile.yml references the panel)
@@ -72,15 +112,88 @@ Clacky.ext = (() => {
     };
   }
 
-  // Bracket an extension's synchronous evaluation so registrations made during
-  // it are attributed to `extId`. The host emits _extBegin before the
+  // Warn once per unknown slot so a typo is loud but the log stays finite.
+  function _warnUnknownSlot(slot, label) {
+    if (KNOWN_SLOTS[slot] || _warnedUnknownSlots[slot]) return;
+    _warnedUnknownSlots[slot] = true;
+    const known = Object.keys(KNOWN_SLOTS).join(", ");
+    console.warn(
+      `[Clacky.ext] unknown slot ${JSON.stringify(slot)} in ${label}. ` +
+      `Nothing will render. Known slots: ${known}`
+    );
+  }
+
+  // Slots whose renderer represents "the current session's copy" of some UI
+  // (a tabbed panel body, a session banner, a session-composer button). Mounts
+  // to these slots may declare `create(ctx)` and get one runtime per session,
+  // isolated from every other session and torn down only when the session
+  // itself leaves the sidebar.
+  const PER_SESSION_SLOTS = {
+    "session.aside": true,
+    "session.banner": true,
+    "session.composer": true,
+  };
+
+  // sessionId => Map<mountKey, runtime>. Populated lazily on first render.
+  const _sessionRuntimes = new Map();
+  // sessionId => Map<mountKey, teardownFn|null>. Cleared before every rerender.
+  const _viewTeardowns = new Map();
+
+  // Deterministic key for a renderer within a session: same slot + extId + tab
+  // id always resolves to the same runtime for a given session.
+  function _mountKey(slot, entry) {
+    const tabId = entry.tab && entry.tab.id ? entry.tab.id : "_";
+    return `${slot}::${entry.extId || "?"}::${tabId}`;
+  }
+
+  // Normalize a mount registration. Accepts either a plain function (render
+  // only) or an object { create?, render }. Anything else is rejected with a
+  // console warning to catch typos early.
+  function _register(slot, spec, opts, extId, extra) {
+    let create = null;
+    let render;
+    if (typeof spec === "function") {
+      render = spec;
+    } else if (spec && typeof spec === "object" && typeof spec.render === "function") {
+      render = spec.render;
+      if (typeof spec.create === "function") create = spec.create;
+    } else {
+      console.warn(
+        `[Clacky.ext] ui.mount(${JSON.stringify(slot)}) needs a render function ` +
+        `or { create?, render } object. Got: ${typeof spec}`
+      );
+      return;
+    }
+
+    const isBuiltin = !!(extra && extra.builtin);
+    const explicit  = opts && Array.isArray(opts.agents) ? opts.agents : null;
+    const panel     = (!isBuiltin && SESSION_SCOPED_SLOTS[slot]) ? _currentPanel : null;
+    const scoped    = isBuiltin ? null : (explicit || _extAgents[extId] || null);
+    const order     = opts && Number.isFinite(opts.order) ? opts.order : 100;
+    const tab       = (opts && opts.tab) || null;
+    const workspace = (opts && typeof opts.workspace === "string") ? opts.workspace : null;
+
+    const label = `ui.mount(${slot})`;
+    (_slotRenderers[slot] ||= []).push({
+      render:  _guard(render, label, extId),
+      create:  create ? _guard(create, `${label}#create`, extId) : null,
+      extId,
+      agents:  scoped,
+      panel,
+      order,
+      tab,
+      workspace,
+    });
+  }
+
+
   // extension's <script src> and _extEnd right after. In pure mode these are
   // no-ops (and the host does not emit extension scripts at all).
   //
-  // `agents` scopes a single-agent extension (from agents/<name>/webui/): a list
-  // of agent profile names it should appear for. `panel` marks an official
-  // panel (from _panels/<id>/) whose agent scope is resolved separately via
-  // registerPanelAgents. Either may be omitted for a global extension.
+  // `agents` scopes a single-agent extension (from user agents/<name>/webui/):
+  // a list of agent profile names it should appear for. `panel` marks a panel
+  // whose agent scope is resolved separately via registerPanelAgents. Either
+  // may be omitted for a global extension.
   function _extBegin(extId, agents, panel) {
     if (PURE) return;
     _currentExtId = extId;
@@ -137,50 +250,153 @@ Clacky.ext = (() => {
   const ui = {
     // Register a renderer for a named slot. renderFn(ctx) -> Node | string | null.
     //
-    // opts.agents — restrict to these agent profile names (default: all agents).
-    //   For panels, scope is taken from the panel's registerPanelAgents map and
-    //   merged with any explicit opts.agents.
-    // opts.order — vertical sort weight when several renderers share one slot
-    //   (lower renders first). Default 100; ties keep registration order.
-    // opts.tab — { id, label, badge? } required for tabbed slots: marks this
-    //   renderer as one tab in the slot's tab bar.
-    mount(slot, renderFn, opts) {
-      if (PURE || typeof renderFn !== "function") return;
-      const explicit = opts && Array.isArray(opts.agents) ? opts.agents : null;
-      const panel    = (opts && opts.panel) || _currentPanel || null;
-      const scoped   = explicit || _extAgents[_currentExtId] || null;
-      const order    = opts && Number.isFinite(opts.order) ? opts.order : 100;
-      const tab      = (opts && opts.tab) || null;
-      (_slotRenderers[slot] ||= []).push({
-        fn: _guard(renderFn, `ui.mount(${slot})`, _currentExtId),
+    // Scope rules (automatic — you never spell them out):
+    //   • Mounts to session/settings slots inherit the current panel's agent
+    //     scope, so a `session.aside` tab written next to a designer panel
+    //     only shows when the user is on the designer agent.
+    //   • Mounts to every other slot (sidebar.*, header.*, main.workspace)
+    //     are global app chrome — they show regardless of panel/agent.
+    //
+    // opts.agents — restrict to these agent profile names, overriding the
+    //   defaults above. Rarely needed.
+    // Mount UI into a named slot. `spec` is either:
+    //   • a function (ctx) => Node|string|null       — plain render, no state
+    //   • an object { create?, render }              — render + optional
+    //     per-session runtime bound to `create`
+    //
+    // If the slot is per-session (session.aside etc.) AND `create` is present,
+    // the host allocates one runtime per sessionId — `create(ctx)` runs the
+    // first time this session shows the tab, `render(container, ctx, runtime)`
+    // runs every time the tab becomes visible with a fresh empty container,
+    // and `runtime.dispose()` runs when the session leaves the sidebar. State
+    // set up in `create` (media recorders, timers, subscriptions, buffers) is
+    // therefore isolated per session and survives tab teardown.
+    //
+    // For non-per-session slots or specs without `create`, the mount is a
+    // pure global renderer — one call per (re)render.
+    //
+    // opts.tab   — { id, label, badge? } required for tabbed slots.
+    // opts.order — vertical sort weight (lower first). Default 100.
+    // opts.workspace — id of a registerWorkspace() workspace this mount opens;
+    //   the host stamps it on the mount so the Router highlights this item
+    //   while that workspace is active. Use on sidebar.nav.* items.
+    // opts.agents — override the automatic agent scope.
+    mount(slot, spec, opts) {
+      if (PURE || spec == null) return;
+      _warnUnknownSlot(slot, `ui.mount(${_currentExtId || "?"})`);
+      _register(slot, spec, opts, _currentExtId);
+    },
+
+    // Host-owned mount: identical to `mount` but bypasses PURE so official
+    // built-in tabs keep working in safe mode, and defaults to no agent scope.
+    mountBuiltin(slot, spec, opts) {
+      if (spec == null) return;
+      _warnUnknownSlot(slot, "ui.mountBuiltin");
+      _register(slot, spec, opts, "host", { builtin: true });
+    },
+
+    // Register a full-page workspace under this extension. When opened it
+    // takes over the main content area (host hides its own panels first) and
+    // gets its own URL hash `#ext/<id>` so back/forward + reload work.
+    //
+    //   Clacky.ext.ui.registerWorkspace("my-console", {
+    //     title: "My Console",
+    //     render(container) { container.textContent = "hello"; },
+    //   });
+    //
+    // A workspace is opened with `Clacky.ext.ui.openWorkspace(id)` — typically
+    // wired to a `sidebar.nav` menu item mounted from the same extension.
+    // render(container, ctx) is called every time the workspace is shown; the
+    // container is cleared beforehand so the render function can be dumb.
+    registerWorkspace(id, def) {
+      if (PURE || !id || !def || typeof def.render !== "function") return;
+      _workspaces[id] = {
+        id,
+        title: def.title || id,
+        render: _guard(def.render, `ui.registerWorkspace(${id})`, _currentExtId),
         extId: _currentExtId,
-        agents: scoped,   // explicit/per-extension agent list, or null = global
-        panel,            // official-panel id, or null
-        order,
-        tab,              // { id, label, badge? } for tabbed slots, else null
-      });
+      };
     },
 
-    // Register a host-owned renderer (not attributed to any extension). Used for
-    // built-in tabs that must appear for every session regardless of agent
-    // scope (e.g. the Files tab). Bypasses PURE so the official UI keeps working
-    // in safe mode. agents=null => visible everywhere.
-    mountBuiltin(slot, renderFn, opts) {
-      if (typeof renderFn !== "function") return;
-      const order = opts && Number.isFinite(opts.order) ? opts.order : 100;
-      const tab   = (opts && opts.tab) || null;
-      (_slotRenderers[slot] ||= []).push({
-        fn: _guard(renderFn, `ui.mountBuiltin(${slot})`, "host"),
-        extId: "host",
-        agents: null,
-        panel: null,
-        order,
-        tab,
-      });
+    // Open a registered workspace. Emits a `clacky:ext:navigate` event that
+    // the host router listens for; ext.js has no compile-time dependency on
+    // the router. No-op if the id was never registered.
+    openWorkspace(id) {
+      if (PURE || !_workspaces[id]) return;
+      document.dispatchEvent(new CustomEvent("clacky:ext:navigate", {
+        detail: { view: "ext-workspace", params: { id } },
+      }));
     },
   };
 
-  // Decide whether a renderer is visible under the current agent profile.
+  // Return the per-session runtime for a mount, allocating it via `create` on
+  // first use. Global mounts (or per-session slots without `create`) return
+  // null — the render function is expected to work stateless.
+  function _getRuntime(slot, entry, ctx) {
+    if (!entry.create) return null;
+    if (!PER_SESSION_SLOTS[slot]) return null;
+    const sessionId = ctx && ctx.sessionId;
+    if (!sessionId) return null;
+
+    let bySession = _sessionRuntimes.get(sessionId);
+    if (!bySession) {
+      bySession = new Map();
+      _sessionRuntimes.set(sessionId, bySession);
+    }
+    const key = _mountKey(slot, entry);
+    let runtime = bySession.get(key);
+    if (!runtime) {
+      runtime = entry.create(ctx);
+      if (runtime === undefined) return null;  // create threw (guarded)
+      bySession.set(key, runtime || {});
+    }
+    return runtime;
+  }
+
+  // Run any view-level teardown collected on the previous render pass for the
+  // current session, so old event listeners / RAF loops don't leak when a tab
+  // is re-rendered or the session switches away.
+  function _runViewTeardowns(sessionId) {
+    if (!sessionId) return;
+    const map = _viewTeardowns.get(sessionId);
+    if (!map) return;
+    map.forEach((fn) => { if (typeof fn === "function") { try { fn(); } catch (_e) {} } });
+    map.clear();
+  }
+
+  function _rememberViewTeardown(sessionId, key, teardown) {
+    if (!sessionId || typeof teardown !== "function") return;
+    let map = _viewTeardowns.get(sessionId);
+    if (!map) { map = new Map(); _viewTeardowns.set(sessionId, map); }
+    map.set(key, teardown);
+  }
+
+  // Invoke a renderer's render function. Handles the (container, ctx, runtime)
+  // signature used everywhere; if the render returns a function it is stored
+  // as the view teardown, run before the next render or on session exit.
+  function _invokeRender(slot, entry, container, ctx) {
+    const runtime = _getRuntime(slot, entry, ctx);
+    let node, teardown, crashed = false;
+    try {
+      const out = entry.render(container, ctx, runtime);
+      if (out === undefined) {
+        crashed = false;  // container mutated in-place is fine
+      } else if (typeof out === "function") {
+        teardown = out;
+      } else {
+        node = out;
+      }
+    } catch (_e) {
+      crashed = true;
+    }
+    if (crashed) return { crashed: true };
+    if (ctx && ctx.sessionId && teardown) {
+      _rememberViewTeardown(ctx.sessionId, _mountKey(slot, entry), teardown);
+    }
+    return { node };
+  }
+
+
   // null agents AND null panel => global (always visible). Otherwise the
   // current profile must be in the renderer's agent list, or in the set of
   // agents that reference its panel.
@@ -215,34 +431,27 @@ Clacky.ext = (() => {
     const ordered = renderers.slice().sort((a, b) => a.order - b.order);
     ordered.forEach((entry) => {
       if (!_visibleFor(entry, profile)) return;
-      const { fn, extId } = entry;
-      let node;
-      let crashed = false;
-      try {
-        node = fn(renderCtx);
-        if (node === undefined) crashed = true; // guard swallowed a throw
-      } catch (_e) {
-        crashed = true; // defensive: should already be guarded
-      }
-
+      const wrap = document.createElement("div");
+      if (entry.extId) wrap.setAttribute("data-ext-id", entry.extId);
+      // Nav mounts that open a workspace declare it via opts.workspace; the
+      // host stamps it so the Router alone owns the active highlight.
+      if (entry.workspace) wrap.setAttribute("data-ext-workspace", entry.workspace);
+      const { node, crashed } = _invokeRender(slot, entry, wrap, renderCtx);
       if (crashed) {
-        const ph = document.createElement("div");
-        ph.setAttribute("data-ext-status", "crashed");
-        ph.setAttribute("data-ext-id", extId || "");
-        ph.className = "ext-slot-crashed";
-        ph.textContent = "Extension failed to render.";
-        container.appendChild(ph);
+        wrap.setAttribute("data-ext-status", "crashed");
+        wrap.className = "ext-slot-crashed";
+        wrap.textContent = "Extension failed to render.";
+        container.appendChild(wrap);
         return;
       }
-
-      if (node == null) return; // nothing to render is valid
-      if (typeof node === "string") {
-        const wrap = document.createElement("div");
-        wrap.setAttribute("data-ext-id", extId || "");
-        wrap.innerHTML = node;
+      if (node != null) {
+        if (typeof node === "string") wrap.innerHTML = node;
+        else wrap.appendChild(node);
+      }
+      // If render mutated `wrap` in-place (returned nothing) or produced a
+      // node, either way we only append when there's something to show.
+      if (wrap.childNodes.length > 0 || (node != null && typeof node === "string")) {
         container.appendChild(wrap);
-      } else {
-        container.appendChild(node);
       }
     });
   }
@@ -289,11 +498,7 @@ Clacky.ext = (() => {
         const localCtx = Object.assign({}, renderCtx, {
           setBadge: (n) => _setTabBadge(tabBtns[id], n),
         });
-        let node, crashed = false;
-        try {
-          node = entry.fn(localCtx);
-          if (node === undefined) crashed = true;
-        } catch (_e) { crashed = true; }
+        const { node, crashed } = _invokeRender(slot, entry, body, localCtx);
         if (crashed) {
           const ph = document.createElement("div");
           ph.className = "ext-slot-crashed";
@@ -355,11 +560,38 @@ Clacky.ext = (() => {
 
   // Update the current session context (host calls this on every session
   // switch) and re-render all slots so panels match the new agent profile.
+  // Runs the previous session's view-level teardowns first (event listeners /
+  // RAF loops attached to now-dead DOM), but leaves per-session runtimes
+  // alive — the meeting recorder for session A keeps running while you're
+  // looking at B, and its captions are still there when you switch back.
   function setContext(next) {
+    const prevSessionId = context.sessionId;
     Object.assign(context, next || {});
+    if (prevSessionId && prevSessionId !== context.sessionId) {
+      _runViewTeardowns(prevSessionId);
+    }
     refreshSlots();
   }
 
+  // Called by the host when a session leaves the sidebar for good (deleted,
+  // archived, or the page is unloading). Runs every runtime's `dispose()` for
+  // that session so timers, media recorders, and network handles are released.
+  function notifySessionRemoved(sessionId) {
+    if (!sessionId) return;
+    _runViewTeardowns(sessionId);
+    _viewTeardowns.delete(sessionId);
+    const bySession = _sessionRuntimes.get(sessionId);
+    if (!bySession) return;
+    bySession.forEach((runtime) => {
+      if (runtime && typeof runtime.dispose === "function") {
+        try { runtime.dispose(); } catch (err) {
+          console.error("[Clacky.ext] runtime.dispose failed:", err);
+        }
+      }
+    });
+    _sessionRuntimes.delete(sessionId);
+  }
+
   // Re-render every named slot present in the DOM against the current context.
   // Idempotent: each slot's container is cleared before re-rendering.
   function refreshSlots() {
@@ -373,6 +605,7 @@ Clacky.ext = (() => {
     get pure() { return PURE; },
     context,
     setContext,
+    notifySessionRemoved,
     refreshSlots,
     registerPanelAgents,
     api,
@@ -381,6 +614,10 @@ Clacky.ext = (() => {
     emit,
     renderSlot,
     slots,
+    // Host-only: look up a registered workspace by id. Returns
+    // { id, title, render, extId } or undefined. Used by the Router when
+    // handling the `ext-workspace` view — extensions never call this.
+    _getWorkspace(id) { return _workspaces[id]; },
     _extBegin,  // used by the loader; not part of the public extension API
     _extEnd,    // used by the loader; not part of the public extension API
   };

data/lib/clacky/web/features/backup/store.js

@@ -113,3 +113,4 @@ const BackupStore = (() => {
 })();
 
 const Backup = BackupStore;
+Clacky.Backup = Backup;

data/lib/clacky/web/features/backup/view.js

@@ -118,4 +118,3 @@ const BackupView = (() => {
 })();
 
 BackupView.init();
-window.Backup = Backup;

data/lib/clacky/web/features/brand/view.js

@@ -94,7 +94,7 @@ const BrandView = (() => {
   }
 
   function _goToLicenseInput() {
-    Router.navigate("settings");
+    window.Clacky.Router.navigate("settings");
     if (typeof Settings !== "undefined") Settings.open();
     setTimeout(() => {
       const generalTabBtn = document.querySelector('#settings-tabs .settings-tab[data-tab="general"]');
@@ -297,12 +297,20 @@ const BrandView = (() => {
     span.textContent = message;
     if (i18nKey) span.setAttribute("data-i18n", i18nKey);
 
-    const btn = document.createElement("button");
-    btn.innerHTML = "✕";
-    btn.onclick = () => bar.remove();
+    const renewBtn = document.createElement("button");
+    renewBtn.className   = "brand-warning-renew-btn";
+    renewBtn.textContent = I18n.t("brand.warning.renewBtn");
+    renewBtn.setAttribute("data-i18n", "brand.warning.renewBtn");
+    renewBtn.onclick = () => { bar.remove(); _goToLicenseInput(); };
+
+    const closeBtn = document.createElement("button");
+    closeBtn.className = "brand-warning-close-btn";
+    closeBtn.innerHTML = "✕";
+    closeBtn.onclick   = () => bar.remove();
 
     bar.appendChild(span);
-    bar.appendChild(btn);
+    bar.appendChild(renewBtn);
+    bar.appendChild(closeBtn);
     document.getElementById("main").prepend(bar);
   }