@songsid/agend 2.2.0 → 2.3.0-beta.2

package/dist/topic-link.js

@@ -0,0 +1,269 @@
+/**
+ * #1990: links to another topic. One place builds "a link to instance X's place (or a world's General) on surface S"
+ * from what the adapters already know — Discord guild/channel ids, the Telegram supergroup id, its public @username
+ * when it has one, and topic ids — and messages name such a place through a token that each surface renders in its own
+ * form, or as plain text when the reader could not open the target.
+ *
+ *   Discord   `<#channel>` (clickable in place); in a DM, `https://discord.com/channels/<guild>/<channel>`
+ *   Telegram  `https://t.me/<username>/<topic>` (public group) or `https://t.me/c/<id without -100>/<topic>`, carried by
+ *             a `text_link` entity on plain text — no parse mode, so nothing in the text needs escaping
+ *   plain     the label alone (a suffix token disappears)
+ *
+ * The forms are the documented ones; no real client was driven (#1990: the user checks them on the 2.3 beta).
+ */
+/** A world's place, for links: its platform, its group and (Telegram) the group's public @username once read. */
+export function worldPlaceOf(world) {
+    const username = world.groupId ? world.adapter?.groupUsername?.(world.groupId) : undefined;
+    return { type: world.type, ...(world.groupId ? { groupId: world.groupId } : {}), ...(username ? { username } : {}) };
+}
+export const SNOWFLAKE = /^\d{5,25}$/;
+/** A Telegram @username as the platform allows it: 4–32 of [A-Za-z0-9_], starting with a letter. */
+const TELEGRAM_USERNAME = /^[A-Za-z][A-Za-z0-9_]{3,31}$/;
+/** t.me/c/ links take a supergroup's id without its -100 prefix; anything else has no such link. */
+export function telegramInternalId(chatId) {
+    const m = /^-100(\d+)$/.exec(chatId);
+    return m ? m[1] : undefined;
+}
+/** The t.me path prefix of a group: `<username>` for a public one, `c/<id>` for a private supergroup. */
+function telegramGroupPath(place, chatId = place.groupId ?? "") {
+    if (place.username && TELEGRAM_USERNAME.test(place.username) && chatId === place.groupId)
+        return place.username;
+    const internal = telegramInternalId(chatId);
+    return internal ? `c/${internal}` : undefined;
+}
+/** A link to a message (a prompt's own buttons), or undefined when none can be built for this platform/place. */
+export function messageLink(place, at) {
+    if (!at.messageId)
+        return undefined;
+    if (place.type === "discord") {
+        const channel = at.threadId ?? at.chatId;
+        if (!place.groupId || !SNOWFLAKE.test(place.groupId) || !SNOWFLAKE.test(channel) || !SNOWFLAKE.test(at.messageId))
+            return undefined;
+        return `https://discord.com/channels/${place.groupId}/${channel}/${at.messageId}`;
+    }
+    if (place.type === "telegram") {
+        const path = telegramGroupPath(place, at.chatId);
+        if (!path || !/^\d+$/.test(at.messageId))
+            return undefined;
+        const topic = at.threadId && at.threadId !== "1" && /^\d+$/.test(at.threadId) ? `${at.threadId}/` : "";
+        return `https://t.me/${path}/${topic}${at.messageId}`;
+    }
+    return undefined;
+}
+/**
+ * A browser URL to a topic or channel. Telegram's General topic (1) gets one only when `general` is set: an
+ * instance's link never points at General.
+ */
+export function topicUrl(place, topicId, opts = {}) {
+    if (!place || !topicId)
+        return undefined;
+    if (place.type === "discord") {
+        if (!place.groupId || !SNOWFLAKE.test(place.groupId) || !SNOWFLAKE.test(topicId))
+            return undefined;
+        return `https://discord.com/channels/${place.groupId}/${topicId}`;
+    }
+    if (place.type === "telegram") {
+        const path = telegramGroupPath(place);
+        if (!path || !/^\d+$/.test(topicId) || (topicId === "1" && !opts.general))
+            return undefined;
+        return `https://t.me/${path}/${topicId}`;
+    }
+    return undefined;
+}
+/** A way to the instance's own thread: Discord's channel mention (clickable in place), Telegram's topic link. */
+export function instanceLink(place, topicId) {
+    if (!topicId)
+        return undefined;
+    if (place.type === "discord")
+        return SNOWFLAKE.test(topicId) ? `<#${topicId}>` : undefined;
+    return topicUrl(place, topicId);
+}
+// Private-use code points: no normal text carries them, and a stray one is never taken for a token.
+const OPEN = "";
+const MID = "";
+const CLOSE = "";
+const TOKEN = /([^-]*)([^-]*)/g;
+const MARKERS = /[-]/g;
+function encodeTarget(target) {
+    return target.kind === "general" ? "g" : `i:${encodeURIComponent(target.name)}`;
+}
+function decodeTarget(payload) {
+    if (payload === "g")
+        return { kind: "general" };
+    if (!payload.startsWith("i:"))
+        return undefined;
+    try {
+        const name = decodeURIComponent(payload.slice(2));
+        return name ? { kind: "instance", name } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Name a place in a message: rendered as `label` linked to the target, or as `label` alone. */
+export function placeRef(target, label) {
+    return `${OPEN}${encodeTarget(target)}${MID}${label.replace(MARKERS, "")}${CLOSE}`;
+}
+/**
+ * A link appended to a message (" → General"): the message's own words stay as they are, and when the place cannot
+ * be linked the suffix disappears with its leading space.
+ */
+export function placeSuffix(target, label) {
+    return ` ${OPEN}s|${encodeTarget(target)}${MID}${label.replace(MARKERS, "")}${CLOSE}`;
+}
+export function hasPlaceRefs(text) {
+    return text.includes(OPEN);
+}
+/**
+ * Render every token for one surface. `resolve` says how this reader reaches a target (undefined: plain text). The
+ * text outside tokens is copied unchanged; `textLinks` is non-empty only on Telegram.
+ */
+export function renderPlaceRefs(text, surface, resolve) {
+    if (!hasPlaceRefs(text))
+        return { text, textLinks: [] };
+    const textLinks = [];
+    let out = "";
+    let last = 0;
+    for (const m of text.matchAll(TOKEN)) {
+        let before = text.slice(last, m.index);
+        last = m.index + m[0].length;
+        const suffix = m[1].startsWith("s|");
+        const target = decodeTarget(suffix ? m[1].slice(2) : m[1]);
+        const label = m[2];
+        const link = target && label && surface !== "plain" ? resolve(target) : undefined;
+        if (!link) {
+            // A suffix is all link: without one it goes, with the space placeSuffix put before it.
+            if (suffix)
+                before = before.endsWith(" ") ? before.slice(0, -1) : before;
+            out += before + (suffix ? "" : label);
+            continue;
+        }
+        out += before;
+        const arrow = suffix ? "→ " : "";
+        if (surface === "discord") {
+            // A mention is clickable in place; a URL (a DM) in angle brackets so Discord adds no embed.
+            const ref = "mention" in link ? link.mention : `<${link.url}>`;
+            out += suffix ? `${arrow}${ref}` : `${label} (${ref})`;
+        }
+        else if ("url" in link) {
+            out += arrow;
+            textLinks.push({ offset: out.length, length: label.length, url: link.url });
+            out += label;
+        }
+        else {
+            out += arrow + label;
+        }
+    }
+    out += text.slice(last);
+    return { text: out, textLinks };
+}
+/**
+ * #1990: an in-app route of the web app for an instance — its chat, or its terminal View — as the web client parses it
+ * (src/ui/shared/app-route.js chatPath / viewPath). Undefined for a name no route takes.
+ */
+export function webRoute(panel, name) {
+    if (!name || name.length > 128 || /[/\\\u0000-\u001f\u007f]/.test(name) || name === "." || name.includes(".."))
+        return undefined;
+    return panel === "chat" ? `/ui/chat/${encodeURIComponent(name)}` : `/view/${encodeURIComponent(name)}`;
+}
+const WEB_ROUTE = /^\/(?:ui\/chat|view)\/[^/?#\s]+$/;
+export const WEB_TEXT_LINKS_MAX = 16;
+/**
+ * #1990: links as the web keeps them — on a status line or a prompt, ranges of its text that open an instance's chat
+ * or View in the app. Whatever is not exactly that (out of the text, overlapping, not such a route) is dropped; an
+ * empty result is undefined.
+ */
+export function webTextLinks(raw, text) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    let end = 0;
+    for (const l of raw.slice(0, WEB_TEXT_LINKS_MAX)) {
+        if (!l || typeof l !== "object")
+            continue;
+        const { offset, length, url } = l;
+        if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || typeof url !== "string")
+            continue;
+        const o = offset, n = length;
+        if (o < end || n < 1 || o + n > text.length || !WEB_ROUTE.test(url))
+            continue;
+        try {
+            decodeURIComponent(url);
+        }
+        catch {
+            continue;
+        }
+        out.push({ offset: o, length: n, url });
+        end = o + n;
+    }
+    return out.length ? out : undefined;
+}
+/** Every token as its label, suffixes gone: what a surface that renders no links shows. */
+export function stripPlaceRefs(text) {
+    return renderPlaceRefs(text, "plain", () => undefined).text;
+}
+/** Text links that lie wholly inside [start, end), re-based to start; one that crosses the boundary is dropped. */
+export function textLinksWithin(links, start, end) {
+    return links.filter(l => l.offset >= start && l.offset + l.length <= end).map(l => ({ ...l, offset: l.offset - start }));
+}
+/**
+ * Whether a DM recipient may get links into a group: only a confirmed member (#1990 — never link to what the reader
+ * cannot open). One read per (group, user) per `ttlMs`, bounded by `deadlineMs`; a non-member, an error, a timeout or
+ * an adapter that cannot tell all mean "no" (plain text). Answers are cached, failures included, so a refusing
+ * platform is asked again only after the TTL; concurrent asks share one read.
+ */
+export class GroupMembership {
+    opts;
+    answers = new Map();
+    reads = new Map();
+    constructor(opts = { now: () => performance.now() }) {
+        this.opts = opts;
+    }
+    async isMember(source, groupId, userId) {
+        if (!source.isGroupMember || !groupId || !userId)
+            return false;
+        const key = `${groupId}\u0000${userId}`;
+        const ttl = this.opts.ttlMs ?? 10 * 60_000;
+        const cached = this.answers.get(key);
+        if (cached && this.opts.now() - cached.at < ttl)
+            return cached.member;
+        const pending = this.reads.get(key);
+        if (pending)
+            return pending;
+        const read = this.read(source, groupId, userId).then(member => {
+            this.answers.delete(key); // re-insert: the map's order is its age, for the bound below
+            this.answers.set(key, { member, at: this.opts.now() });
+            const max = this.opts.maxEntries ?? 1000;
+            while (this.answers.size > max)
+                this.answers.delete(this.answers.keys().next().value);
+            return member;
+        }).finally(() => this.reads.delete(key));
+        this.reads.set(key, read);
+        return read;
+    }
+    read(source, groupId, userId) {
+        const deadlineMs = this.opts.deadlineMs ?? 5_000;
+        return new Promise(resolve => {
+            const timer = setTimeout(() => resolve(false), deadlineMs);
+            timer.unref?.();
+            let asked;
+            try {
+                asked = source.isGroupMember(groupId, userId);
+            }
+            catch {
+                asked = Promise.resolve(false);
+            }
+            asked.then(member => { clearTimeout(timer); resolve(member === true); }, () => { clearTimeout(timer); resolve(false); });
+        });
+    }
+}
+/** #1990: refusals that send the person to General — their reply carries a link to it. */
+export const GENERAL_POINTING_REFUSALS = new Set(["cmd.use_in_general", "profile.general_only"]);
+/**
+ * Text from outside (an agent's message, a pane line, a dialog's description) as a place-token-free argument: a
+ * message that interpolates it must not let it name a place of its own.
+ */
+export function noPlaceMarkers(text) {
+    return text.replace(MARKERS, "");
+}
+//# sourceMappingURL=topic-link.js.map

package/dist/topic-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-link.js","sourceRoot":"","sources":["../src/topic-link.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -404,6 +404,19 @@ export interface WebConfig {
      * instead of it; web.preview: false turns previews off everywhere.
      */
     preview_on_public_link?: boolean;
+    /**
+     * #1629: agents' own web themes and effects. `agent_edit` (default true): false refuses every agent appearance write,
+     * fleet-wide; what is stored stays, and people can still reset and lock.
+     */
+    themes?: {
+        agent_edit?: boolean;
+    };
+    /**
+     * #1629 r4.1 Q3 (b): the identity card's upload limits and each agent's picture quota. Defaults: portrait
+     * 1024×1536 / 1536 KiB, banner 1600×600 / 768 KiB, quota 8 files / 4 MiB. A value outside its hard bound is clamped
+     * (and warned about); a change applies to new uploads only.
+     */
+    appearance?: import("./web-appearance-limits.js").AppearanceLimitsConfig;
 }
 /** `login:` section — remote /login behaviour. */
 export interface LoginConfig {

package/dist/ui/app-effects.js

@@ -0,0 +1,187 @@
+/** #1629: one session-only app effect owner. Importing this module starts nothing. */
+import { appStore } from "/assets/app-store.js";
+import { navStore } from "/assets/app-nav.js";
+import { onPrefsChanged, prefInForce } from "/assets/app-prefs.js";
+import { resolvedMode, themesStore } from "/assets/app-themes.js";
+import { ownerCssLifecycle, safeMode } from "/assets/owner-css.js";
+import { constrainedDevice } from "/assets/effect-policy.js";
+import { createAppEffectRuntime } from "/assets/effect-app-runtime.js";
+import { createEffectCursor } from "/assets/effect-cursor.js";
+import { createOwnerEffectRegions } from "/assets/effect-owner-regions.js";
+import { chatEffectIdentity } from "/assets/effect-chat-runtime.js";
+import { createEffectTrialController } from "./effect-trial-controller.js";
+import { effectTrialMessage } from "./effect-trial-offer.js";
+import { claimPanel, panelVersion, panelStore, openTrialPanel, closePanel } from "./preview-panel.js";
+const owners = new WeakMap();
+export function getAppEffects(host = window) { const value = owners.get(host); return value && !value.dead && value.api?.ok ? value : null; }
+
+/** Boot once with the page's Chat store, including when the first visible panel is Fleet. */
+export function startAppEffects({ store, window: host = window, factories = {} } = {}) {
+  const existing = owners.get(host);
+  if (existing) { if (!existing.dead) existing.bindStore(store); return getAppEffects(host); }
+  if (!chatEffectIdentity(host) || typeof host.AgendAuth?.onSessionEnd !== "function" || typeof host.AgendAuth?.sessionEnded !== "function") return null;
+  const doc = host.document, releases = [], ended = new Set(), updates = new Set(), trialUpdates = new Set(); let replyOff = null, replyStore = null, regions = null, cursor = null, cursorStamp = null, trialControl = null, trialIntent = null, trialHint = false, trialSerial = 0, trialStamp = null, chatBinding = null;
+  const safe = fn => { try { return fn(); } catch { return null; } };
+  const hold = off => { if (entry.dead) safe(() => off?.()); else releases.push(off); };
+  const entry = { dead: false, api: null,
+    cursorSnapshot: () => cursor?.snapshot() ?? { status: "unavailable", id: null },
+    gates: () => context(),
+    subscribe(fn) { if (typeof fn !== "function" || entry.dead) return () => {}; updates.add(fn); return () => updates.delete(fn); },
+    subscribeTrial(fn) { if (typeof fn !== "function" || entry.dead) return () => {}; trialUpdates.add(fn); return () => trialUpdates.delete(fn); },
+    onEnd(fn) { if (typeof fn !== "function") return () => {}; if (entry.dead) { safe(fn); return () => {}; } ended.add(fn); return () => ended.delete(fn); },
+    bindStore(value) {
+      if (entry.dead || value === replyStore) return;
+      safe(() => replyOff?.()); replyOff = null; replyStore = value;
+      trialControl?.stop(); chatBinding = null; entry.api?.detachChat();
+      if (typeof value?.onAgentReply === "function") {
+        const off = value.onAgentReply(event => { if (!entry.dead && replyStore === value) entry.api?.reply(event); });
+        if (entry.dead || replyStore !== value) safe(() => off?.()); else replyOff = off;
+      }
+    },
+    canTry(message) {
+      const offer = safe(() => effectTrialMessage(message)), nav = navStore.get();
+      return !entry.dead && !!chatBinding && safe(() => chatBinding.current()) === true && trialHint && trialControl?.ok === true && !!offer && message.instance === nav.route?.instance && nav.route?.panel === "chat"
+        && trialControl.snapshot().phase === "idle" && !trialControl.snapshot().busy && trialAllowed();
+    },
+    startTrial(message) {
+      if (!entry.canTry(message)) return Promise.resolve(false);
+      const nav = navStore.get(); trialIntent = { name: message.instance, seq: nav.seq, claim: claimPanel(), handle: null, chat: chatBinding };
+      return trialControl.start(message);
+    },
+    attachChat(options) {
+      const nav = navStore.get(), name = options?.name;
+      if (entry.dead || !entry.api?.ok || nav.route?.panel !== "chat" || nav.route.instance !== name || typeof options.current !== "function") return null;
+      const binding = { current: () => !entry.dead && host.document === doc && navStore.get().seq === nav.seq && navStore.get().route?.panel === "chat" && navStore.get().route?.instance === name && options.current() === true };
+      chatBinding = binding; trialControl?.stop();
+      if (entry.dead || chatBinding !== binding) return null;
+      const handle = entry.api.attachChat({ ...options, current: () => chatBinding === binding && binding.current() });
+      if (entry.dead || chatBinding !== binding) { safe(() => handle?.dispose()); return null; }
+      if (!handle) chatBinding = null;
+      return handle;
+    },
+    dispose() {
+      if (entry.dead) return; entry.dead = true;
+      safe(() => trialControl?.dispose()); safe(() => entry.api?.dispose()); safe(() => replyOff?.()); replyOff = null; replyStore = null;
+      for (const off of releases.splice(0)) safe(off);
+      updates.clear(); trialUpdates.clear(); const listeners = [...ended]; ended.clear(); for (const fn of listeners) safe(fn);
+    },
+  };
+  owners.set(host, entry); // Reentrant setup never constructs another owner.
+  let media, coarse, preview;
+  function context() {
+    let ready = false; try { ready = preview?.availability().ok === true; } catch { /* unavailable */ }
+    return { safe: safeMode(), publicLink: doc.body.dataset.publicLink === "1", reducedMotion: media?.matches !== false, saveData: host.navigator?.connection?.saveData === true,
+      hidden: doc.visibilityState !== "visible", enabled: typeof host.OffscreenCanvas === "function" && typeof host.Worker === "function" && typeof host.MutationObserver === "function" && typeof host.ResizeObserver === "function",
+      show: prefInForce("fx.show")?.value !== false, previewReady: ready,
+      optIn: prefInForce("preview.optIn")?.value === true && preview?.optedIn() === true && preview?.never() !== true,
+      constrained: constrainedDevice({ memory: host.navigator?.deviceMemory, cores: host.navigator?.hardwareConcurrency, coarse: coarse?.matches === true, width: host.innerWidth }),
+      modal: !!doc.querySelector("dialog[open],.menu-list,.pop,[role=alertdialog],.oc-keep,.shell.sb-open"), openInstance: null };
+  }
+  function trialCurrent(name) {
+    const intent = trialIntent, nav = navStore.get();
+    return !entry.dead && host.document === doc && !!intent && !!intent.chat && chatBinding === intent.chat && intent.chat.current() === true && intent.name === name && nav.seq === intent.seq && nav.route?.panel === "chat" && nav.route.instance === name
+      && (panelVersion() === intent.claim || intent.handle !== null && panelStore.get().open?.handle === intent.handle);
+  }
+  function trialAllowed() {
+    const c = context();
+    return !entry.dead && doc.visibilityState === "visible" && doc.hasFocus?.() === true && ownerCssLifecycle.get().state === "off"
+      && c.enabled && c.show && c.previewReady && c.optIn && !c.safe && !c.publicLink && !c.reducedMotion && !c.saveData && !c.hidden && !c.modal;
+  }
+  function mountTrial(handle) {
+    const intent = trialIntent; if (!intent || !trialCurrent(handle.instance) || !handle.current() || !Number.isSafeInteger(++trialSerial)) throw Error("trial_unavailable");
+    intent.handle = handle;
+    const binding = Object.freeze({ key: `trial:${trialSerial}:${handle.reply.trial}`, id: handle.reply.offer.id, run: handle.reply.trial, instance: handle.instance, generation: trialSerial });
+    let stage = null, source = null;
+    const cleanup = () => {
+      safe(() => source?.stop()); safe(() => stage?.dispose());
+      if (panelStore.get().open?.handle === handle) closePanel();
+    };
+    try {
+      openTrialPanel({ key: binding.key, instance: handle.instance, binding, handle, ownerCss: () => ownerCssLifecycle.get().state,
+        onStage(value) {
+          stage = value;
+          if (!handle.current()) { cleanup(); handle.stop(); return; }
+          source = entry.api.attachTrial({ reply: handle.reply, offer: handle.reply.offer.offer, startedAt: handle.startedAt, stage,
+            current: handle.current, onStop: handle.stop });
+          if (!source) { cleanup(); handle.stop(); }
+        },
+      });
+    } catch (error) { cleanup(); throw error; }
+    return cleanup;
+  }
+  function notifyTrial() {
+    if (entry.dead) return;
+    const nav = navStore.get(), next = JSON.stringify([trialHint, safe(() => chatBinding?.current()) === true, trialAllowed(), nav.route?.panel, nav.route?.instance, trialControl?.snapshot()]);
+    if (next === trialStamp) return; trialStamp = next;
+    for (const fn of [...trialUpdates]) safe(fn);
+  }
+  const notify = () => { if (!entry.dead) { trialControl?.sync(); notifyTrial(); for (const fn of [...updates]) safe(fn); } };
+  const cursorDragging = () => doc.body.classList?.contains("side-resizing") === true || !!doc.querySelector(".chat-split.resizing");
+  function syncCursor() {
+    if (entry.dead || !cursor) return;
+    const c = context();
+    cursor.update(entry.api?.cursorSelection?.() ?? null, c.enabled && c.show && c.previewReady && c.optIn && !c.safe && !c.publicLink && !c.reducedMotion && !c.saveData && !c.hidden && !c.modal && !cursorDragging());
+  }
+  try {
+    if (appStore.get().connection === "ended") { entry.dispose(); return null; }
+    preview = host.AgendPreview;
+    media = host.matchMedia?.("(prefers-reduced-motion: reduce)") ?? { matches: true };
+    coarse = host.matchMedia?.("(pointer: coarse)") ?? { matches: false };
+    entry.api = (factories.runtime ?? createAppEffectRuntime)({ window: host, current: () => !entry.dead && host.document === doc,
+      observe: () => ({ context: context(), ownerCss: ownerCssLifecycle.get().state, mode: resolvedMode() }), onDispose: () => entry.dispose(),
+      resolveOwnerTarget: (slot, manifest, proof) => !entry.dead ? regions?.resolve?.(slot, manifest.box, proof) ?? null : null,
+      onChange: () => { syncCursor(); notify(); } });
+    if (entry.dead || !entry.api.ok) { entry.dispose(); return null; }
+    trialControl = (factories.trialController ?? createEffectTrialController)({ window: host, current: trialCurrent, allowed: trialAllowed, onStart: mountTrial, onChange: notify });
+    hold(() => trialControl?.dispose());
+    if (typeof host.AgendAuth.trialSession === "function") Promise.resolve().then(() => host.AgendAuth.trialSession()).then(value => {
+      if (entry.dead) return; trialHint = value?.localAdmin === true && value.epoch === chatEffectIdentity(host)?.epoch; notify();
+    }).catch(() => {});
+    hold(panelStore.subscribe(() => { trialControl?.sync(); notifyTrial(); }));
+    const ownRegions = (factories.regions ?? createOwnerEffectRegions)({ window: host, current: () => !entry.dead && host.document === doc });
+    regions = ownRegions?.ok ? ownRegions : null; hold(() => ownRegions?.dispose?.());
+    if (entry.dead) return null;
+    const ownCursor = safe(() => (factories.cursor ?? createEffectCursor)({ window: host, current: () => !entry.dead && host.document === doc,
+      readImage: (selection, signal) => entry.api?.cursorImageSettled?.(selection, signal) ?? Promise.resolve(null),
+      onChange(value) { const next = JSON.stringify(value); if (next !== cursorStamp) { cursorStamp = next; notify(); } },
+    }));
+    cursor = ownCursor?.ok ? ownCursor : null; hold(() => ownCursor?.dispose?.());
+    if (entry.dead) return null;
+    const sync = () => { if (!entry.dead) { trialControl?.sync(); entry.api.sync(); syncCursor(); notifyTrial(); } };
+    let revision = appStore.get().themesRev, prefsRevision = appStore.get().prefsRev, navSeq = navStore.get().seq;
+    hold(navStore.subscribe(value => { if (entry.dead || value.seq === navSeq) return; navSeq = value.seq; trialControl?.stop(); chatBinding = null; entry.api.detachChat(); syncCursor(); }));
+    hold(appStore.subscribe(value => {
+      if (entry.dead) return;
+      if (value.connection === "ended") { entry.dispose(); return; }
+      const chatChanged = value.themesRev !== revision, ownerChanged = value.prefsRev !== prefsRevision;
+      revision = value.themesRev; prefsRevision = value.prefsRev;
+      if (chatChanged) entry.api.changedChat();
+      if (ownerChanged) entry.api.changedOwner();
+      if (!chatChanged && !ownerChanged) sync();
+    }));
+    hold(ownerCssLifecycle.subscribe(sync)); hold(themesStore.subscribe(sync)); hold(onPrefsChanged(sync));
+    if (typeof preview?.onChange === "function") hold(preview.onChange(sync));
+    if (typeof host.AgendTheme?.onChange === "function") hold(host.AgendTheme.onChange(sync));
+    for (const [target, type] of [[media, "change"], [coarse, "change"], [doc, "visibilitychange"], [host, "resize"], [host.navigator?.connection, "change"]]) {
+      if (target?.addEventListener) { target.addEventListener(type, sync); hold(() => target.removeEventListener(type, sync)); }
+    }
+    if (entry.dead) return null;
+    let modal = context().modal, dragging = cursorDragging(), queuedSurface = false;
+    // Panel commits can happen after navigation and contain no Chat lease. Reproject fixed owner targets
+    // once after stock DOM changes. Body-level effect roots/frames/rules do not schedule themselves.
+    const surfaceChanged = () => {
+      if (entry.dead || queuedSurface) return; queuedSurface = true;
+      Promise.resolve().then(() => { queuedSurface = false; sync(); });
+    };
+    const barriers = typeof host.MutationObserver === "function" ? new host.MutationObserver(records => {
+      if (entry.dead) return;
+      const value = context().modal, drag = cursorDragging(); if (value !== modal || drag !== dragging) { modal = value; dragging = drag; sync(); }
+      if (Array.isArray(records) && records.some(r => r.target?.closest?.("#app") || r.target === doc.getElementById?.("app"))) surfaceChanged();
+    }) : null;
+    hold(() => barriers?.disconnect());
+    if (entry.dead) return null;
+    barriers?.observe(doc.documentElement, { subtree: true, childList: true, attributes: true, attributeFilter: ["class", "open", "hidden", "role"] });
+    entry.bindStore(store); sync();
+    return getAppEffects(host);
+  } catch { entry.dispose(); return null; }
+}

package/dist/ui/chat-effect-posters.js

@@ -0,0 +1,42 @@
+/** #1629: static Chat fallback. It requires no preview origin, device consent, Worker or personal identity. */
+import { useLayoutEffect } from "/assets/app-html.js";
+import { appStore } from "/assets/app-store.js";
+import { onPrefsChanged, prefInForce } from "/assets/app-prefs.js";
+import { themesShown, themesStore } from "/assets/app-themes.js";
+import { ownerCssLifecycle } from "/assets/owner-css.js";
+import { chatEffectIdentity } from "/assets/effect-chat-runtime.js";
+import { createChatPosters } from "/assets/effect-posters.js";
+
+export function ChatEffectPosters({ name, lease, element }) {
+  useLayoutEffect(() => {
+    let live = true, api = null;
+    const releases = [], host = window;
+    const current = () => live && lease.current();
+    const cleanup = () => { if (!live) return; live = false; try { api?.dispose?.(); } catch { /* optional */ } for (const off of releases) { try { off?.(); } catch { /* release all */ } } };
+    lease.hold(cleanup);
+    try {
+      const preview = host.AgendPreview, motion = host.matchMedia?.("(prefers-reduced-motion: reduce)") ?? { matches: true };
+      const observe = () => {
+        let previewReady = false; try { previewReady = preview?.availability().ok === true; } catch { /* fallback */ }
+        // This is a surface fallback, not a replacement for an explicit Pause, queued effect or failed live read.
+        const playback = chatEffectIdentity(host) && typeof host.Worker === "function" && typeof host.OffscreenCanvas === "function" && previewReady &&
+          prefInForce("preview.optIn")?.value === true && preview?.optedIn() === true && preview?.never() !== true && !motion.matches && host.navigator?.connection?.saveData !== true;
+        return { shown: themesShown(), fallback: !playback, ownerCss: ownerCssLifecycle.get().state };
+      };
+      api = createChatPosters({ window: host, name, element: element.current, current, observe });
+      if (!api.ok) return cleanup;
+      const sync = () => { if (current()) api.sync(); };
+      let revision = appStore.get().themesRev;
+      releases.push(appStore.subscribe(s => {
+        if (!current()) return;
+        if (s.connection === "ended") { api.dispose(); return; }
+        if (s.themesRev !== revision) { revision = s.themesRev; api.changed(); } else sync();
+      }));
+      releases.push(ownerCssLifecycle.subscribe(sync)); releases.push(themesStore.subscribe(sync)); releases.push(onPrefsChanged(sync));
+      if (typeof preview?.onChange === "function") releases.push(preview.onChange(sync));
+      for (const target of [motion, host.navigator?.connection]) if (target?.addEventListener) { target.addEventListener("change", sync); releases.push(() => target.removeEventListener("change", sync)); }
+      sync(); return cleanup;
+    } catch { cleanup(); return cleanup; }
+  }, [name, lease]);
+  return null;
+}

package/dist/ui/chat-effects.js

@@ -0,0 +1,72 @@
+// #1629: Chat contributes a committed lease to the one app owner; no private pool or server polling.
+import { html, useLayoutEffect, useRef, useState } from "/assets/app-html.js";
+import { register, t } from "/assets/app-i18n.js";
+import { appStore, useStore } from "/assets/app-store.js";
+import { ownerCssLifecycle } from "/assets/owner-css.js";
+import { chatEffectState, chatEffectIdentity } from "/assets/effect-chat-runtime.js";
+import { Dialog } from "/assets/ui-dialog.js";
+import { navigate } from "/assets/app-nav.js";
+import { toast } from "/assets/ui-toast.js";
+import { getAppEffects } from "./app-effects.js";
+
+register("chatFx", {
+  en: { title: "Effects", loading: "Checking effects…", empty: "No effects in this chat.", failed: "Effects stopped because their resources could not be verified. Reload the page to try again.", reload: "Reload page", pause: "Pause", resume: "Resume", remove: "Remove from chat", removeFailed: "Could not remove this effect. Reload the page to check its state.", css: "Agent foreground effects are paused while your custom CSS is on or cannot be verified.", setting: "Open Web appearance settings", running: "Running", starting: "Starting", off: "Stopped", resumeFailed: "This effect cannot resume: the page or its safety history is not ready. Reload the page or choose another effect.", queued: "Waiting for a slot", unknown: "Playback is off or unavailable here.", budget: "Paused to protect page responsiveness. Resume keeps the three-pauses safety limit.", paused: "Paused", low: "Reduced quality" },
+  "zh-TW": { title: "效果", loading: "正在確認效果…", empty: "這個聊天沒有放置效果。", failed: "無法確認效果資源，已停止播放。重新載入頁面後再試。", reload: "重新載入頁面", pause: "暫停", resume: "恢復", remove: "從聊天移除", removeFailed: "無法移除效果。請重新載入頁面確認狀態。", css: "自訂 CSS 開啟或無法確認時，代理的前景效果會暫停。", setting: "開啟網頁外觀設定", running: "播放中", starting: "啟動中", off: "已停止", resumeFailed: "頁面或安全紀錄尚未就緒，無法恢復此效果。請重新載入頁面，或選擇其他效果。", queued: "等待空位", unknown: "這裡已關閉播放，或無法播放效果。", budget: "為維持頁面順暢，已暫停效果。恢復仍保留三次暫停的安全上限。", paused: "已暫停", low: "降低畫質" },
+});
+
+/** Local read/admin sessions keep controls; public, View, poll and header-only pages have no runtime identity. */
+export function chatEffectsMenuAvailable() { return chatEffectIdentity(window) !== null; }
+
+export function ChatEffects({ name, lease, element, store, open, onClose }) {
+  const cssLife = useStore(ownerCssLifecycle);
+  const runtime = useRef(null), [state, setState] = useState(null), [canWrite, setCanWrite] = useState(false), [busy, setBusy] = useState(false);
+  useLayoutEffect(() => {
+    let live = true, api = null;
+    const releases = [];
+    // Effects are optional: a failed setup must release its partial ownership without breaking Chat.
+    const cleanup = () => {
+      if (!live) return;
+      live = false;
+      try { api?.dispose?.(); } catch { /* continue releasing partial setup */ }
+      for (const off of releases) { try { if (typeof off === "function") off(); } catch { /* release the rest */ } }
+      if (runtime.current === api) runtime.current = null;
+    };
+    lease.hold(cleanup);
+    try {
+      setBusy(false); onClose(); setCanWrite(false); setState(null);
+      const host = window, owner = getAppEffects(host);
+      const current = () => live && lease.current();
+      if (!owner) { setState({ error: null, rows: [], effects: [], unavailable: true }); return cleanup; }
+      releases.push(owner.onEnd(() => { if (current()) setState({ error: "resource_unavailable", rows: [], effects: [], unavailable: true }); }));
+      const changed = value => {
+        if (!current()) return;
+        const g = owner.gates();
+        setState({ ...value, unavailable: !g.enabled || !g.show || !g.previewReady || !g.optIn || g.safe || g.publicLink || g.reducedMotion || g.saveData });
+      };
+      api = owner.attachChat({ name, element: element.current, current,
+        observe: () => ({ state: chatEffectState(appStore.get(), name) }), onChange: changed });
+      runtime.current = api;
+      if (!api?.ok) { setState({ error: null, rows: [], effects: [], unavailable: true }); return cleanup; }
+      host.AgendAuth?.canWrite?.().then(value => { if (current()) setCanWrite(value === true); }).catch(() => {});
+      api.sync();
+      return cleanup;
+    } catch {
+      cleanup();
+      if (lease.current()) setState({ error: "runtime_unavailable", rows: [], effects: [] });
+      return cleanup;
+    }
+  }, [name, lease]);
+  const rows = state?.rows ?? [], effects = state?.effects ?? [];
+  const css = cssLife.state !== "off" && effects.some(p => p.by !== "human" && p.manifest.layer === "front");
+  const remove = async id => { if (busy) return; setBusy(true); const api = runtime.current; const ok = await api?.remove?.(id); if (!lease.current() || runtime.current !== api) return; setBusy(false); if (!ok) toast(t("chatFx.removeFailed"), false); };
+  return html`${open ? html`<${Dialog} title=${t("chatFx.title")} onClose=${onClose} busy=${busy}>
+      ${state?.error ? html`<p>${t("chatFx.failed")}</p><button type="button" class="btn" onClick=${() => location.reload()}>${t("chatFx.reload")}</button>` : null}
+      ${css ? html`<p>${t("chatFx.css")}</p><button type="button" class="btn" onClick=${() => { onClose(); navigate("/settings/appearance"); }}>${t("chatFx.setting")}</button>` : null}
+      ${!effects.length && !state?.error ? html`<p>${t(state?.unavailable ? "chatFx.unknown" : state?.loading || !state ? "chatFx.loading" : "chatFx.empty")}</p>` : null}
+      ${effects.map(p => { const row = rows.find(r => r.id === p.id), phase = row?.phase; return html`<section key=${p.id}><h3>${p.manifest.title}</h3><p>${t(row?.reason === "paused" || row?.reason === "host_budget" ? "chatFx.paused" : phase === "running" ? "chatFx.running" : phase ? "chatFx.starting" : row?.verdict === "queued" ? "chatFx.queued" : "chatFx.off")}${row?.quality === "low" ? ` · ${t("chatFx.low")}` : ""}</p>
+        ${row?.reason === "host_budget" ? html`<p>${t("chatFx.budget")}</p>` : null}
+        <button type="button" class="btn" disabled=${busy} onClick=${() => runtime.current?.pause?.(p.id)}>${t("chatFx.pause")}</button>
+        <button type="button" class="btn" disabled=${busy} onClick=${() => { if (!runtime.current?.resume?.(p.id)) toast(t("chatFx.resumeFailed"), false); }}>${t("chatFx.resume")}</button>
+        ${canWrite ? html`<button type="button" class="btn" disabled=${busy} onClick=${() => remove(p.id)}>${t("chatFx.remove")}</button>` : null}</section>`; })}
+    </${Dialog}>` : null}`;
+}