@songsid/agend 2.3.0-beta.6 → 2.3.0-beta.7

package/dist/web-ambient.js

@@ -0,0 +1,154 @@
+/**
+ * #2117 (from #2115's proposal): an **ambient** effect is declarative, like a widget. The agent supplies a small closed
+ * spec (a preset, its glyphs and a few numbers); the page draws it with its own code (src/ui/chat-ambient.js): plain
+ * nodes animated by the Web Animations API, under the chat's content and never taking a click. No agent code runs, so
+ * an ambient needs no Worker, preview origin, HTML-preview consent or FPS baseline (Canvas Worker effects do).
+ *
+ * A chat holds at most one looping ambient (`fall`, `rise`, `twinkle`) and one click ambient (`burst-on-click`): falling
+ * petals and click stars together. One module validates and canonicalises the spec; the store keeps only what this
+ * returns, and the page checks the bounds again.
+ */
+import { canonicalColor, canonicalText } from "./web-theme.js";
+export const AMBIENT_PRESETS = ["fall", "rise", "twinkle", "burst-on-click"];
+/** Where a preset is kept: a chat has one of each. */
+export const AMBIENT_KINDS = ["loop", "click"];
+export const ambientKind = (preset) => preset === "burst-on-click" ? "click" : "loop";
+export const AMBIENT_GLYPHS_MAX = 4;
+export const AMBIENT_GLYPH_GRAPHEMES = 2;
+export const AMBIENT_COLORS_MAX = 5;
+export const AMBIENT_SPEC_MAX_BYTES = 1024;
+/** The page's caps (chat-ambient.js keeps the same numbers): 24 looping particles, 3 bursts of 16 at once. */
+export const AMBIENT_LOOP_MAX = 24;
+export const AMBIENT_BURST_MAX = 16;
+export const AMBIENT_BURSTS_LIVE = 3;
+/** Each preset's bounds and defaults. A count is particles (loops) or particles per click (burst). */
+export const AMBIENT_RULES = {
+    fall: { count: [1, AMBIENT_LOOP_MAX], countDefault: 12, duration: [4, 30], durationDefault: [9, 19] },
+    rise: { count: [1, AMBIENT_LOOP_MAX], countDefault: 12, duration: [4, 30], durationDefault: [9, 19] },
+    twinkle: { count: [1, AMBIENT_LOOP_MAX], countDefault: 12, duration: [1, 10], durationDefault: [2, 5] },
+    "burst-on-click": { count: [4, AMBIENT_BURST_MAX], countDefault: 10, duration: [0.3, 2], durationDefault: [0.5, 0.9] },
+};
+export const AMBIENT_SIZE = [10, 40];
+export const AMBIENT_SIZE_DEFAULT = [14, 22];
+export const AMBIENT_SWAY_MAX = 80;
+export const AMBIENT_SWAY_DEFAULT = 40;
+export const AMBIENT_SPREAD = [20, 120];
+export const AMBIENT_SPREAD_DEFAULT = [34, 90];
+export const AMBIENT_ROTATE_MAX = 720;
+export const AMBIENT_ROTATE_DEFAULT = 300;
+export const AMBIENT_OPACITY_DEFAULT = [0, 0.85, 0.15];
+const KEYS = ["preset", "glyphs", "colors", "count", "duration", "size", "sway", "spread", "rotate", "opacity", "layer"];
+const ASSET_ID = /^[0-9a-f]{32}$/;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+/** Two decimals are plenty for seconds, pixels and opacity, and keep the stored spec short. */
+const round = (n) => Math.round(n * 100) / 100;
+/**
+ * A spec, closed and canonical: unknown keys, a value out of its preset's bounds or a glyph that is not 1..2 visible
+ * graphemes (or one of this instance's `glyph` pictures, when `glyphAsset` is given) are refused.
+ */
+export function checkAmbient(raw, opts = {}) {
+    const errors = [];
+    const bad = (path, problem) => { errors.push({ path, problem }); };
+    if (!isObj(raw))
+        return { ok: false, errors: [{ path: "ambient", problem: "an object { preset, glyphs, … }" }] };
+    for (const k of Object.keys(raw))
+        if (!KEYS.includes(k))
+            bad(k.slice(0, 40), "unknown key");
+    const preset = raw.preset;
+    if (!AMBIENT_PRESETS.includes(preset))
+        return { ok: false, errors: [...errors, { path: "preset", problem: AMBIENT_PRESETS.join(" | ") }] };
+    const rules = AMBIENT_RULES[preset];
+    const glyphs = [];
+    if (!Array.isArray(raw.glyphs) || raw.glyphs.length < 1 || raw.glyphs.length > AMBIENT_GLYPHS_MAX)
+        bad("glyphs", `1..${AMBIENT_GLYPHS_MAX} glyphs`);
+    else
+        raw.glyphs.forEach((g, i) => {
+            if (typeof g === "string") {
+                const t = canonicalText(g, 1, AMBIENT_GLYPH_GRAPHEMES);
+                if (t === null)
+                    bad(`glyphs.${i}`, `1..${AMBIENT_GLYPH_GRAPHEMES} visible characters (an emoji, ✦, ❀)`);
+                else
+                    glyphs.push(t);
+            }
+            else if (isObj(g) && Object.keys(g).length === 1 && typeof g.asset === "string" && ASSET_ID.test(g.asset)) {
+                if (opts.glyphAsset && !opts.glyphAsset(g.asset))
+                    bad(`glyphs.${i}.asset`, "not one of this instance's glyph pictures (set_web_theme_asset slot glyph)");
+                else
+                    glyphs.push({ asset: g.asset });
+            }
+            else
+                bad(`glyphs.${i}`, "a short string, or { asset: <id> }");
+        });
+    const colors = [];
+    if (raw.colors !== undefined) {
+        if (!Array.isArray(raw.colors) || raw.colors.length > AMBIENT_COLORS_MAX)
+            bad("colors", `0..${AMBIENT_COLORS_MAX} colours`);
+        else
+            raw.colors.forEach((c, i) => { const v = canonicalColor(c); if (v === null)
+                bad(`colors.${i}`, "#rgb or #rrggbb");
+            else
+                colors.push(v); });
+    }
+    const int = (key, [lo, hi], dflt) => {
+        const v = raw[key];
+        if (v === undefined)
+            return dflt;
+        if (!Number.isSafeInteger(v) || v < lo || v > hi) {
+            bad(key, `a whole number ${lo}..${hi}${key === "count" ? ` for ${preset}` : ""}`);
+            return dflt;
+        }
+        return v;
+    };
+    const num = (key, [lo, hi], dflt) => {
+        const v = raw[key];
+        if (v === undefined)
+            return dflt;
+        if (!isNum(v) || v < lo || v > hi) {
+            bad(key, `a number ${lo}..${hi}`);
+            return dflt;
+        }
+        return round(v);
+    };
+    const range = (key, [lo, hi], dflt) => {
+        const v = raw[key];
+        if (v === undefined)
+            return [dflt[0], dflt[1]];
+        if (!Array.isArray(v) || v.length !== 2 || !v.every(isNum) || v[0] < lo || v[1] > hi || v[0] > v[1]) {
+            bad(key, `[min, max] within ${lo}..${hi}${key === "duration" ? ` seconds for ${preset}` : ""}`);
+            return [dflt[0], dflt[1]];
+        }
+        return [round(v[0]), round(v[1])];
+    };
+    const count = int("count", rules.count, rules.countDefault);
+    const duration = range("duration", rules.duration, rules.durationDefault);
+    const size = range("size", AMBIENT_SIZE, AMBIENT_SIZE_DEFAULT);
+    const sway = num("sway", [0, AMBIENT_SWAY_MAX], AMBIENT_SWAY_DEFAULT);
+    const spread = range("spread", AMBIENT_SPREAD, AMBIENT_SPREAD_DEFAULT);
+    const rotate = num("rotate", [0, AMBIENT_ROTATE_MAX], AMBIENT_ROTATE_DEFAULT);
+    let opacity = [...AMBIENT_OPACITY_DEFAULT];
+    if (raw.opacity !== undefined) {
+        const o = raw.opacity;
+        if (!Array.isArray(o) || o.length !== 3 || !o.every(x => isNum(x) && x >= 0 && x <= 1))
+            bad("opacity", "[start, peak, end], each 0..1");
+        else
+            opacity = [round(o[0]), round(o[1]), round(o[2])];
+    }
+    if (raw.layer !== undefined && raw.layer !== "behind")
+        bad("layer", "\"behind\" (an ambient never covers the chat)");
+    if (errors.length)
+        return { ok: false, errors };
+    const spec = { preset, glyphs, colors, count, duration, size, sway, spread, rotate, opacity, layer: "behind" };
+    if (Buffer.byteLength(JSON.stringify(spec), "utf8") > AMBIENT_SPEC_MAX_BYTES)
+        return { ok: false, errors: [{ path: "ambient", problem: `at most ${AMBIENT_SPEC_MAX_BYTES} bytes` }] };
+    return { ok: true, value: spec };
+}
+/** The glyph pictures a spec names. */
+export function ambientAssets(spec) {
+    return spec.glyphs.flatMap(g => typeof g === "string" ? [] : [g.asset]);
+}
+/** One line per problem, for a tool's refusal. */
+export function ambientProblems(errors) {
+    return errors.map(e => `${e.path}: ${e.problem}`).join("; ");
+}
+//# sourceMappingURL=web-ambient.js.map

package/dist/web-ambient.js.map

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

package/dist/web-api.d.ts

@@ -52,6 +52,7 @@ export interface WebApiContext {
         web?: {
             echo_to_channel?: boolean;
             usage_panel?: boolean;
+            usage_report_on_public_link?: boolean;
             upload_max_file_mb?: number;
             upload_max_total_mb?: number;
         };
@@ -130,6 +131,7 @@ export interface WebApiContext {
     /** Current owned pane reader shared with status; absent means context is unavailable. */
     getPaneContextSource?(name: string): PaneContextSource | null;
     /** #1306: which preview origin this /ui load may frame (Host and the TLS signal only); absent: previews off. */
+    readonly effectBoot?: string;
     previewForUi?(hostHeader: string | undefined, secure: boolean): PreviewAvailability & {
         boot: string | null;
     };
@@ -196,6 +198,11 @@ export interface WebApiContext {
     logSteps?(name: string, q: import("./log-service.js").LogQuery): Promise<unknown>;
     /** #1468: the prompt-cache expiry analysis for a window ("24h" | "7d" | "30d"); absent: not offered. */
     cacheReport?(window: string): Promise<unknown>;
+    /** #2122: the usage report (Fleet → Usage); absent: not offered. */
+    usageReport?(params: {
+        range: import("./usage-report.js").UsageRange;
+        group: import("./usage-report.js").UsageGroup;
+    }): Promise<unknown>;
     /** #1269: an instance's chat command from the web chat (web-commands.ts); absent: not offered. */
     webCommand?(input: {
         instance: string;
@@ -210,6 +217,29 @@ export interface WebApiContext {
         status: number;
         body: unknown;
     }>;
+    /** #1939 S2b: "Authorize this browser" — the Confirm card in the account's DM; and what the app shows for this browser. */
+    requestSessionAuthorization?(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+    }): Promise<{
+        ok: true;
+        expiresInMs: number;
+    } | {
+        ok: false;
+        refusal: string;
+        retryAfterMs?: number;
+    }>;
+    webSessionAuthorization?(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+    }): {
+        state: string;
+        until?: number;
+        expiresInMs?: number;
+        reason?: string;
+    };
     /** #1939 S1: the design's §3 for one request (`instance` once the body names it); absent: web carries no authority. */
     webAuthority?(input: {
         session: SessionRecord | null;
@@ -350,6 +380,8 @@ export type PublicPreviewForUi = PreviewAvailability & {
     detail?: string;
 };
 export interface AppShellContext {
+    /** #2118: independent trusted opaque effect document, never HTML-preview consent or listener state. */
+    readonly effectBoot?: string;
     previewForUi?(hostHeader: string | undefined, secure: boolean): (PreviewAvailability & {
         boot: string | null;
     }) | null;

package/dist/web-api.js

@@ -516,7 +516,12 @@ function handleEffects(req, res, url, ctx, path, method) {
     const reading = method === "GET";
     // Reports are bounded untrusted diagnostics, not an appearance or admission write (r2 §6).
     const profilePost = method === "POST" && /^\/ui\/effects\/profile\/[0-9a-f]{32}$/.test(path);
-    if (gatewayRequestContext(req)) {
+    const gateway = gatewayRequestContext(req), guest = guestRequestOf(req);
+    const instanceQuery = url.searchParams.get("instance"), keys = [...url.searchParams.keys()];
+    const chatRead = reading && (path === "/ui/effects/placements" || /^\/ui\/effects\/resource\/[0-9a-f]{32}$/.test(path))
+        && keys.length === 2 && keys.includes("instance") && keys.includes("ownerEpoch") && !!instanceQuery && instanceQuery.length <= 128;
+    // Public viewing grants current Chat reads, never ordinary library/owner/Trial access or writes.
+    if (gateway && (!chatRead || !gateway.isCurrent())) {
         json(res, reading ? 404 : 403, { error: "effects_not_over_public_link" });
         return true;
     }
@@ -528,7 +533,9 @@ function handleEffects(req, res, url, ctx, path, method) {
             return { status: 403, error: "effects_need_a_signed_in_person" };
         if (!reading && !profilePost && verdict.session.tier !== "admin")
             return { status: 403, error: "effects_read_only" };
-        return { person: webPersonKey(verdict.session.owner), canWrite: verdict.session.tier === "admin", epoch: verdict.session.handle };
+        if (verdict.session.tier === "guest" && (!chatRead || !guest || !guest.current() || !guest.scope().has(instanceQuery)))
+            return { status: 404, error: "not_found" };
+        return { person: webPersonKey(verdict.session.owner), canWrite: verdict.session.tier === "admin", epoch: verdict.session.handle, guest: verdict.session.tier === "guest" };
     };
     const first = who();
     if ("status" in first) {
@@ -571,9 +578,9 @@ function handleEffects(req, res, url, ctx, path, method) {
         else if (path === "/ui/effects/owner" && instance === undefined && slot === null)
             answer(service.ownerSelections(first.person));
         else if (path === "/ui/effects/placements" && instance !== undefined)
-            answer(service.placements(first.person, instance));
+            answer(service.placements(first.person, instance, !!gateway || first.guest));
         else if (idPath?.[1] === "resource")
-            answer(slot === null ? service.resource(first.person, idPath[2], instance) : service.ownerResource(first.person, idPath[2], slot));
+            answer(slot === null ? service.resource(first.person, idPath[2], instance, !!gateway || first.guest) : service.ownerResource(first.person, idPath[2], slot));
         else if (idPath?.[1] === "profile" && instance === undefined)
             answer(service.profile(first.person, idPath[2]));
         else
@@ -627,8 +634,13 @@ function handleEffects(req, res, url, ctx, path, method) {
             answer(service.remove(now.person, body));
         else if (path === "/ui/effects/share")
             answer(service.share(now.person, body));
-        else
-            answer(service.report(now.person, idPath[2], body, instance));
+        else {
+            if (body && typeof body === "object" && body.kind === "playback" && (url.searchParams.getAll("instance").length !== 1 || slot !== null)) {
+                json(res, 400, { error: "playback_report" });
+                return;
+            }
+            answer(service.report(now.person, idPath[2], body, instance, now.epoch));
+        }
     })().catch(() => { try {
         json(res, 500, { error: "effect_request_failed" });
     }
@@ -837,7 +849,7 @@ export function exportMod(ctx, person, body) {
         return { ok: false, status: 400, error: "title", detail: "1..60 characters on one line" };
     const parts = {};
     let omitted = 0;
-    const wantsInstance = inc.theme === true || inc.identity === true || (isObj(inc.widgets) && AGENT_WIDGET_SLOTS.some(s => inc.widgets[s] === true));
+    const wantsInstance = inc.theme === true || inc.identity === true || inc.ambient === true || (isObj(inc.widgets) && AGENT_WIDGET_SLOTS.some(s => inc.widgets[s] === true));
     let name = null;
     if (wantsInstance) {
         if (typeof body.instance !== "string" || !ctx.isKnownInstance?.(body.instance) || !ctx.themeStore)
@@ -864,6 +876,11 @@ export function exportMod(ctx, person, body) {
             if (isObj(inc.widgets) && inc.widgets[slot] === true && w)
                 (parts.widgets ??= {})[slot] = { spec: w.spec, data: w.data };
         }
+        // #2117: its ambients, whoever set them (a person exports what is on the chat).
+        if (inc.ambient === true) {
+            const specs = Object.fromEntries(Object.entries(rec.placements.ambient).flatMap(([k, a]) => a ? [[k, a.spec]] : []));
+            parts.ambient = { specs, picture: id => { const a = rec.assets.find(x => x.id === id); const b = store.asset(name, id); return a && b ? { bytes: b.bytes, kind: a.kind } : null; } };
+        }
     }
     if (isObj(inc.widgets) && inc.widgets.sidebar === true && ctx.webPrefs) {
         const v = ctx.webPrefs.read(OPERATOR).values["widget.sidebar"];
@@ -914,6 +931,19 @@ function webAuthorityOf(req, url, ctx, instance) {
     return ctx.webAuthority({ session: v.kind === "allow" && v.via === "session" ? v.session : null, gateway: !!gatewayRequestContext(req),
         peer: classifyWebPeer(req), ...(instance !== undefined ? { instance } : {}) });
 }
+/**
+ * #2122: what let this request in, asked now — its session (by handle, under the token it was signed in with) or the
+ * header token; null when nothing does any more (the gate also refuses a public link that is no longer the current
+ * one). Equal before and after an await: the same admission still holds. Never touches the session.
+ */
+function admissionOf(req, url, ctx) {
+    const gateway = gatewayRequestContext(req);
+    const v = evaluateWebRequest(req, url, ctx.webToken ?? null, ctx.webSessions, { touch: false });
+    if (v.kind !== "allow")
+        return null;
+    const via = v.via === "session" ? `session:${v.session.handle}:${v.session.tokenEpoch}` : "token";
+    return gateway ? `${via}@${gateway.exposureId}` : via;
+}
 /** #1827: the person, or the request is answered 401 here (it is no longer authorized) and null is returned. */
 function webPersonOr401(req, res, url, ctx) {
     const p = webPersonOf(req, url, ctx);
@@ -1282,9 +1312,10 @@ export function handleWebRequest(req, res, url, ctx) {
         return true;
     }
     // ── #1629: agents' themes — read by every page (the public link included: it views them), changed by a person ──
-    // GET /ui/themes: { rev, themes, locked, widgets } when the status frame's themes_rev moves (passive, web-auth.ts).
+    // GET /ui/themes: { rev, themes, locked, widgets, ambient (#2117) } when the status frame's themes_rev moves (passive, web-auth.ts).
     // GET /ui/img/theme/<instance>/<id>: a theme's picture (same headers as #1630's images; the id is the content hash).
-    // POST /ui/themes/<instance>/reset | lock | widget (r4-4: { slot } — take an agent's widget out): a person's, from an admin session — never the CLI token, never the public
+    // POST /ui/themes/<instance>/reset | lock | widget (r4-4: { slot } — take an agent's widget out) | ambient (#2117: { spec } sets one,
+    // { which? } alone clears that kind or both): a person's, from an admin session — never the CLI token, never the public
     // link (absent from its manifest, and refused here too).
     if (method === "GET" && path === "/ui/themes") {
         const store = ctx.themeStore;
@@ -1292,7 +1323,7 @@ export function handleWebRequest(req, res, url, ctx) {
             json(res, 404, { error: "Themes are not kept on this fleet" });
             return true;
         }
-        json(res, 200, { rev: store.rev(), themes: store.themes(), locked: store.lockedNames(), widgets: store.widgets() });
+        json(res, 200, { rev: store.rev(), themes: store.themes(), locked: store.lockedNames(), widgets: store.widgets(), ambient: store.ambients() });
         return true;
     }
     const themeImage = path.match(/^\/ui\/img\/theme\/([^/]+)\/([0-9a-f]{32})$/);
@@ -1318,7 +1349,7 @@ export function handleWebRequest(req, res, url, ctx) {
         res.end(image.bytes);
         return true;
     }
-    const themeWrite = path.match(/^\/ui\/themes\/([^/]+)\/(reset|lock|widget)$/);
+    const themeWrite = path.match(/^\/ui\/themes\/([^/]+)\/(reset|lock|widget|ambient)$/);
     if (method === "POST" && themeWrite) {
         const service = ctx.webAppearance;
         if (!service) {
@@ -1370,7 +1401,8 @@ export function handleWebRequest(req, res, url, ctx) {
             }
             const r = themeWrite[2] === "reset" ? service.humanReset(name)
                 : themeWrite[2] === "widget" ? service.humanRemoveWidget(name, body.slot)
-                    : typeof body.locked === "boolean" ? service.humanLock(name, body.locked) : { error: "locked: true or false", status: 400 };
+                    : themeWrite[2] === "ambient" ? service.humanSetAmbient(name, body.spec ?? null, body.which)
+                        : typeof body.locked === "boolean" ? service.humanLock(name, body.locked) : { error: "locked: true or false", status: 400 };
             if (typeof r.error === "string") {
                 json(res, typeof r.status === "number" ? r.status : 503, { error: r.error });
                 return;
@@ -1771,6 +1803,50 @@ export function handleWebRequest(req, res, url, ctx) {
     // #1269: an instance's chat command (/ctx, /compact, /clear, /model, …) — a session write (CSRF, checked by the
     // gate), run through the platforms' own handlers and command table. The public link is told it is one (/save is
     // refused there).
+    // ── #1939 S2b: this browser's authorization — what the app shows (GET), and "Authorize this browser" (POST: posts the
+    // Confirm card in the account's DM). Judged on this request (§3), never touching the session.
+    if (path === "/ui/authorization" && (method === "GET" || method === "POST")) {
+        const judge = () => {
+            const v = evaluateWebRequest(req, url, ctx.webToken ?? null, ctx.webSessions, { touch: false });
+            return { session: v.kind === "allow" && v.via === "session" ? v.session : null, gateway: !!gatewayRequestContext(req), peer: classifyWebPeer(req) };
+        };
+        res.setHeader("Cache-Control", "no-store");
+        if (method === "GET") {
+            if (!ctx.webSessionAuthorization) {
+                json(res, 404, { error: "not available" });
+                return true;
+            }
+            json(res, 200, ctx.webSessionAuthorization(judge()));
+            return true;
+        }
+        if (!ctx.requestSessionAuthorization) {
+            json(res, 404, { error: "not available" });
+            return true;
+        }
+        const ask = ctx.requestSessionAuthorization.bind(ctx);
+        (async () => {
+            try {
+                await parseBody(req);
+            }
+            catch {
+                json(res, 400, { error: "Invalid JSON" });
+                return;
+            }
+            if (!permitWebContinuation(req, res, ctx))
+                return;
+            const r = await ask(judge()); // asked again now the body is in
+            // A refusal is an answer the page shows (pending, three this hour, why not), not a failed request: 200 with
+            // ok: false — a 4xx would be logged as an error in the browser's console every time.
+            json(res, 200, r);
+        })().catch(err => {
+            ctx.logger.error({ err: err.message }, "Web authorization request failed");
+            try {
+                json(res, 500, { error: "Request failed" });
+            }
+            catch { /* already answered */ }
+        });
+        return true;
+    }
     if (method === "POST" && path === "/ui/command") {
         if (!ctx.webCommand) {
             json(res, 404, { error: "Not available" });
@@ -2252,6 +2328,42 @@ export function handleWebRequest(req, res, url, ctx) {
         }
         return true;
     }
+    // #2122: the usage report. Signed-in sessions by default (guests never: not in GUEST_ROUTES); hidden with the rest of
+    // usage by web.usage_panel: false; over the public link only when web.usage_report_on_public_link is true. Answered
+    // from the ledgers and rollups as they are; a catch-up runs behind. The page's CSV is built from this same answer.
+    if (method === "GET" && path === "/ui/usage-report") {
+        // Who may have it, asked on arrival and again before it is sent (the report is awaited: a switch turned off, a
+        // session signed out or a public link ended meanwhile gets nothing). The same boundary both times, no new gate.
+        const refusal = () => {
+            if (!ctx.usageReport || ctx.fleetConfig?.web?.usage_panel === false)
+                return [404, "Not available"];
+            if (gatewayRequestContext(req) && ctx.fleetConfig?.web?.usage_report_on_public_link !== true)
+                return [403, "usage_report_not_over_public_link"];
+            return null;
+        };
+        const first = refusal();
+        if (first) {
+            json(res, first[0], { error: first[1] });
+            return true;
+        }
+        const admitted = admissionOf(req, url, ctx);
+        if (!admitted) {
+            json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
+            return true;
+        }
+        void import("./usage-report.js").then(({ usageRange, usageGroup }) => ctx.usageReport({
+            range: usageRange(url.searchParams.get("range"), url.searchParams.get("from") ?? undefined, url.searchParams.get("to") ?? undefined),
+            group: usageGroup(url.searchParams.get("group")),
+        })).then((report) => {
+            const now = refusal();
+            if (now)
+                return json(res, now[0], { error: now[1] });
+            if (admissionOf(req, url, ctx) !== admitted)
+                return json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
+            json(res, 200, report);
+        }, (err) => { ctx.logger.error({ err }, "usage report failed"); json(res, 500, { error: "Usage report failed" }); });
+        return true;
+    }
     // #1468: the prompt-cache expiry analysis. Opening it is a person's navigation, like any Fleet tab (it counts as
     // use); the page never re-reads it on a timer. Answered from the ledgers as they are; a catch-up runs behind.
     if (method === "GET" && path === "/ui/cache") {
@@ -2873,23 +2985,33 @@ function shellHtmlTag(ctx, mode, viewer) {
  * the public link, the anonymous View reader, the CLI's header token or the sign-in and setup pages (other panels).
  */
 function shellOwnerCss(ctx, mode, viewer) {
-    return mode === "full" && viewer?.person !== null && viewer?.person !== undefined && ctx.ownerCss ? ctx.ownerCss.active(viewer.person) : null;
+    return mode === "full" && !viewer?.guest && viewer?.person !== null && viewer?.person !== undefined && ctx.ownerCss ? ctx.ownerCss.active(viewer.person) : null;
 }
 function guestBodyAttrs(ctx, owner, attr) {
     const badge = ctx.guestBadge?.(owner);
     return ` data-tier="guest"${badge ? ` data-guest-name="${attr(badge.name)}" data-guest-platform="${attr(badge.platform)}"` : ""}`;
 }
+/** A separate session fence for Chat playback: public/guest viewers acquire no owner-pref identity. */
+function shellEffect(req, ctx, mode) {
+    if (mode !== "full" || typeof ctx.effectBoot !== "string" || !/^[0-9a-f]{32}$/.test(ctx.effectBoot))
+        return null;
+    const v = evaluateWebRequest(req, new URL(req.url ?? "/", "http://localhost"), ctx.webToken ?? null, ctx.webSessions, { touch: false });
+    if (v.kind !== "allow" || v.via !== "session" || !v.session || !/^[a-f0-9]{16}$/.test(v.session.handle))
+        return null;
+    return { boot: ctx.effectBoot, epoch: v.session.handle, scope: gatewayRequestContext(req) || v.session.tier === "guest" ? "chat" : "owner" };
+}
 function shellBodyTag(req, ctx, mode, viewer) {
     const p = shellPreview(req, ctx, mode);
-    const ownerCss = shellOwnerCss(ctx, mode, viewer);
-    let ownerCssState = "unknown";
-    if (mode === "full" && viewer?.person != null && ctx.ownerCss) {
+    const ownerCss = shellOwnerCss(ctx, mode, viewer), effect = shellEffect(req, ctx, mode);
+    let ownerCssState = mode === "full" && (gatewayRequestContext(req) || viewer?.guest) ? "off" : "unknown";
+    if (mode === "full" && !viewer?.guest && viewer?.person != null && ctx.ownerCss) {
         ownerCssState = ctx.ownerCss.effectState(viewer.person);
         if (ownerCssState === "off" && ownerCss !== null || ownerCssState === "on" && ownerCss === null)
             ownerCssState = "unknown";
     }
     const attr = (v) => String(v ?? "").replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`);
     return `<body data-mode="${mode}"${mode === "full" && gatewayRequestContext(req) ? ' data-web-transport="poll"' : ""} data-dashboard-origin="${attr(p?.dashboardOrigin)}" data-preview-origin="${attr(p?.previewOrigin)}"`
+        + `${effect ? ` data-effect-boot="${effect.boot}" data-effect-epoch="${effect.epoch}" data-effect-scope="${effect.scope}"` : ""}`
         + ` data-preview-boot="${attr(p?.previewOrigin ? p.boot : "")}" data-preview-reason="${attr(p ? p.reason : "Previews are not available on this fleet.")}"`
         // #1554: no availability asked (the public link, or not the full app) still says why, in the page's language.
         + ` data-preview-reason-code="${attr(p ? p.code ?? "" : gatewayRequestContext(req) ? "publicLink" : "notOffered")}"`
@@ -2925,8 +3047,11 @@ export function serveAppShell(req, res, ctx, mode) {
         const mediaSrc = own ? `${own}/ui/file/` : "'none'";
         // A public-link page frames what its exposure's preview names (the quick-tunnel wildcard: its host is not known when
         // the page may load); every other page frames exactly the origin this load chose (#1723).
-        const frameSrc = p && "frameSrc" in p ? p.frameSrc : p?.previewOrigin
-            ? `${p.previewOrigin}/frame${mode === "full" && !gatewayRequestContext(req) ? ` ${p.previewOrigin}/effect` : ""}` : null;
+        const previewFrames = p && "frameSrc" in p ? p.frameSrc : p?.previewOrigin ? `${p.previewOrigin}/frame` : null;
+        // This fixed trusted document is independent of HTML preview. Its own response confines all Worker execution.
+        const effectOrigin = gatewayRequestContext(req)?.expectedOrigin ?? dashboardOriginFor(typeof req.headers.host === "string" ? req.headers.host : undefined, isSecureRequest(req));
+        const effectFrame = shellEffect(req, ctx, mode) && effectOrigin ? `${effectOrigin}/effect-bootstrap` : null;
+        const frameSrc = [previewFrames, effectFrame].filter(Boolean).join(" ");
         sendPanelHtml(res, html.replace('<html lang="en">', shellHtmlTag(ctx, mode, viewer)).replace("<body>", shellBodyTag(req, ctx, mode, viewer)), 200, {}, { ...(frameSrc ? { frameSrc } : {}), mediaSrc });
     }
     catch {