@songsid/agend 2.2.0-beta.1 → 2.2.0-beta.11

package/dist/web-mentions.d.ts

@@ -0,0 +1,44 @@
+/**
+ * #1682: the names the web chat shows for Discord mentions (`<@id>`, `<@&id>`, `<#id>`) — design: the comment on #1682.
+ *
+ * Asked by id, a few at a time (GET /ui/mentions?u=…&r=…&c=…: the ids a page found in what it rendered), answered
+ * without any Discord request: the fleet's own bots (their instance's label — fleet.yaml and the View profiles in
+ * profiles.db), the people seen on inbound messages (a bounded LRU), and what the Discord adapters already hold in
+ * their caches. A page never gets a directory: only the names of the ids it asked for.
+ */
+export type MentionKind = "u" | "r" | "c";
+export interface MentionQuery {
+    u: string[];
+    r: string[];
+    c: string[];
+}
+export type MentionNames = {
+    u: Record<string, string>;
+    r: Record<string, string>;
+    c: Record<string, string>;
+};
+/** At most this many ids in one request (all kinds together). */
+export declare const MAX_MENTION_IDS = 100;
+/** People remembered from inbound messages. */
+export declare const MAX_SEEN_USERS = 1000;
+/** `?u=1,2&r=3&c=4` → the ids, or why not: digits only (a Discord id), at most MAX_MENTION_IDS, no other parameter. */
+export declare function parseMentionQuery(params: URLSearchParams): {
+    ok: true;
+    query: MentionQuery;
+} | {
+    ok: false;
+    error: string;
+};
+/** The people seen on inbound messages: id → the name they wrote under, most recent last; the oldest go first. */
+export declare class SeenUsers {
+    private readonly max;
+    private readonly names;
+    constructor(max?: number);
+    record(id: string, name: string): void;
+    get(id: string): string | undefined;
+    get size(): number;
+}
+/** One source of names: what it knows for the asked ids (leaving out what it does not). */
+export type MentionSource = (query: MentionQuery) => Partial<MentionNames>;
+/** The names for a query from the sources, in order: the first that knows an id names it. Own keys only. */
+export declare function resolveMentions(query: MentionQuery, sources: MentionSource[]): MentionNames;

package/dist/web-mentions.js

@@ -0,0 +1,75 @@
+/** At most this many ids in one request (all kinds together). */
+export const MAX_MENTION_IDS = 100;
+/** People remembered from inbound messages. */
+export const MAX_SEEN_USERS = 1000;
+const SNOWFLAKE = /^\d{15,25}$/;
+/** `?u=1,2&r=3&c=4` → the ids, or why not: digits only (a Discord id), at most MAX_MENTION_IDS, no other parameter. */
+export function parseMentionQuery(params) {
+    const query = { u: [], r: [], c: [] };
+    let total = 0;
+    for (const key of params.keys())
+        if (key !== "u" && key !== "r" && key !== "c")
+            return { ok: false, error: `unknown parameter: ${key.slice(0, 16)}` };
+    for (const kind of ["u", "r", "c"]) {
+        for (const raw of params.getAll(kind)) {
+            for (const id of raw.split(",")) {
+                if (!id)
+                    continue;
+                if (!SNOWFLAKE.test(id))
+                    return { ok: false, error: "ids are Discord ids (digits)" };
+                if (!query[kind].includes(id)) {
+                    query[kind].push(id);
+                    total++;
+                }
+            }
+        }
+    }
+    if (total > MAX_MENTION_IDS)
+        return { ok: false, error: `at most ${MAX_MENTION_IDS} ids` };
+    return { ok: true, query };
+}
+/** The people seen on inbound messages: id → the name they wrote under, most recent last; the oldest go first. */
+export class SeenUsers {
+    max;
+    names = new Map();
+    constructor(max = MAX_SEEN_USERS) {
+        this.max = max;
+    }
+    record(id, name) {
+        if (!SNOWFLAKE.test(id) || typeof name !== "string" || !name.trim())
+            return;
+        this.names.delete(id);
+        this.names.set(id, name.trim().slice(0, 100));
+        while (this.names.size > this.max)
+            this.names.delete(this.names.keys().next().value);
+    }
+    get(id) { return this.names.get(id); }
+    get size() { return this.names.size; }
+}
+/** The names for a query from the sources, in order: the first that knows an id names it. Own keys only. */
+export function resolveMentions(query, sources) {
+    const out = { u: Object.create(null), r: Object.create(null), c: Object.create(null) };
+    for (const source of sources) {
+        let found;
+        try {
+            found = source(query);
+        }
+        catch {
+            continue;
+        }
+        for (const kind of ["u", "r", "c"]) {
+            const got = found[kind];
+            if (!got)
+                continue;
+            for (const id of query[kind]) {
+                if (Object.hasOwn(out[kind], id) || !Object.hasOwn(got, id))
+                    continue;
+                const name = got[id];
+                if (typeof name === "string" && name.trim())
+                    out[kind][id] = name.trim().slice(0, 100);
+            }
+        }
+    }
+    return { u: { ...out.u }, r: { ...out.r }, c: { ...out.c } };
+}
+//# sourceMappingURL=web-mentions.js.map

package/dist/web-mentions.js.map

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

package/dist/web-prefs.d.ts

@@ -0,0 +1,81 @@
+export declare const WEB_PREFS_FILE = "web-prefs.json";
+export declare const OPERATOR = "operator";
+/** #1664: at most this many favorites. */
+export declare const MAX_FAVORITES = 50;
+export declare const WEB_PREF_KEYS: readonly string[];
+export declare function isWebPrefKey(key: string): boolean;
+export interface WebPrefsView {
+    /** Every key that is set, and its value (a key not set has its default: the page's own). */
+    readonly values: Record<string, unknown>;
+    readonly rev: number;
+    /** The file could not be read: these are the defaults, and writes are refused until it is fixed. */
+    readonly unreadable?: true;
+}
+export type WebPrefsWrite = {
+    ok: true;
+    view: WebPrefsView;
+    changed: string[];
+} | {
+    ok: false;
+    status: 400 | 503;
+    error: string;
+};
+/**
+ * A request's `set`: own keys only, each known, each valid — or the first reason it is not. All or nothing.
+ * `exists`: whether an instance of that name is in the fleet now (#1664: a favorite must be one).
+ */
+export declare function parseWebPrefsPatch(set: unknown, exists?: (name: string) => boolean): {
+    ok: true;
+    patch: Map<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
+export declare class WebPrefsStore {
+    private readonly dir;
+    private readonly opts;
+    private state;
+    /**
+     * `exists` (#1664): whether an instance of that name is in the fleet now — a favorite that is not is never served,
+     * and is never accepted.
+     */
+    constructor(dir: string, opts?: {
+        now?: () => number;
+        write?: (path: string, data: string) => void;
+        exists?: (name: string) => boolean;
+    });
+    /** parseWebPrefsPatch against this fleet. */
+    parsePatch(set: unknown): ReturnType<typeof parseWebPrefsPatch>;
+    get path(): string;
+    private load;
+    read(identity?: string): WebPrefsView;
+    rev(): number;
+    /** #1664: an instance was removed — drop it from every favorites list (a write, and a new rev, only if one had it). */
+    forgetInstance(name: string): void;
+    private viewOf;
+    /**
+     * Set (or, with null, clear) the patch's keys. `onlyIfUnset`: a device's first upload of what it had locally — only
+     * the keys the host does not have yet are taken, so the first device to arrive wins and the host wins from then on.
+     */
+    write(identity: string, patch: Map<string, unknown>, opts?: {
+        onlyIfUnset?: boolean;
+    }): WebPrefsWrite;
+    /** #1827: a web person's profile as kept (checked again where it is used); null while the file cannot be read. */
+    profile(identity: string): WebProfile | null;
+    /** #1827: set (or, with null, clear) a person's own name — already validated by the caller (web-profile.ts). */
+    setProfileName(identity: string, name: string | null): {
+        ok: true;
+    } | {
+        ok: false;
+        status: 400 | 503;
+        error: string;
+    };
+    /** #1827: their account's display name at a sign-in (a change is a write and a new rev; the same, nothing). */
+    setPlatformName(identity: string, name: string): void;
+}
+export interface WebProfile {
+    /** The name they chose (as stored); absent: not set — their platform name is used. */
+    readonly name?: string;
+    /** Their account's display name at their last sign-in with a code. */
+    readonly platformName?: string;
+}

package/dist/web-prefs.js

@@ -0,0 +1,297 @@
+/**
+ * #1665: the web preferences that follow the person from device to device (theme, language, the sidebar's arrangement,
+ * the HTML-preview opt-in), kept on the host — design: the comment on #1665.
+ *
+ * - The tour and the first-run card stay per device (the user's call on #1665): they are not keys here.
+ * - One bucket per web identity. There is one today: every web session is the operator's (SessionRecord has no
+ *   owner), so the file is keyed by identity and holds "operator" only; a per-owner key can come later unmigrated.
+ * - A fixed registry of keys, each with its own validator. Anything else is refused — "__proto__" and "constructor"
+ *   are just unknown keys: every lookup is a Map, never an object's prototype chain.
+ * - The file (<home>/web-prefs.json, 0600) is replaced atomically. One that cannot be read or parsed is never
+ *   overwritten: reads give the defaults, writes are refused, until a person looks at it.
+ * - `rev` rises with every change; the status frame carries it, so another device re-reads at its next poll.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileSync } from "./atomic-write.js";
+export const WEB_PREFS_FILE = "web-prefs.json";
+export const OPERATOR = "operator";
+const bad = (invalid) => ({ invalid });
+const isInvalid = (v) => !!v && typeof v === "object" && Object.hasOwn(v, "invalid") && Object.keys(v).length === 1;
+const plain = (v) => !!v && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+const shortText = (v, max) => typeof v === "string" && v.length <= max;
+const name = (v) => typeof v === "string" && v.length >= 1 && v.length <= 128 && !/[\u0000-\u001f\u007f]/.test(v);
+/** Only the listed fields, each present: an extra field is a value this version does not understand. */
+function exactly(v, fields) {
+    const keys = Object.keys(v);
+    return keys.length === fields.length && fields.every((f) => Object.hasOwn(v, f));
+}
+function uniqueStrings(v, max, each, what) {
+    if (!Array.isArray(v) || v.length > max)
+        return bad(`${what}: a list of at most ${max}`);
+    if (!v.every(each))
+        return bad(`${what}: each a name of 1–128 characters`);
+    if (new Set(v).size !== v.length)
+        return bad(`${what}: no repeats`);
+    return v;
+}
+/** #1827: a web person's profile keys (internal: not settable through /ui/prefs, not in its view). */
+const PROFILE_NAME = "profile.name";
+const PROFILE_PLATFORM_NAME = "profile.platformName";
+const PROFILE_KEYS = new Set([PROFILE_NAME, PROFILE_PLATFORM_NAME]);
+/** #1664: at most this many favorites. */
+export const MAX_FAVORITES = 50;
+const FAVORITES = "nav.favorites";
+/** The status chips of the sidebar filter (src/ui/shared/instance-nav.js STATUS_FACETS). */
+const STATUS_FACETS = new Set(["working", "needs", "idle", "stopped", "crashed"]);
+/** Each key's validator: the value to store, or why it is refused. `null` (clear) never reaches one. */
+const REGISTRY = new Map([
+    ["theme", (v) => (v === "light" || v === "dark" || v === "system" ? v : bad("theme: light, dark or system"))],
+    ["lang", (v) => (v === "en" || v === "zh-TW" ? v : bad("lang: en or zh-TW"))],
+    // The sidebar's drag order: the rows instance-nav.js keeps (group rows have no group_name).
+    ["nav.order", (v) => {
+            if (!Array.isArray(v) || v.length > 1000)
+                return bad("nav.order: a list of at most 1000 rows");
+            for (const row of v) {
+                if (!plain(row) || !exactly(row, ["item_type", "item_name", "sort_index", "group_name"]))
+                    return bad("nav.order: rows of item_type, item_name, sort_index, group_name");
+                const groupRow = row.item_type === "group";
+                if (!groupRow && row.item_type !== "instance")
+                    return bad("nav.order: item_type group or instance");
+                if (!name(row.item_name))
+                    return bad("nav.order: item_name of 1–128 characters");
+                if (!Number.isSafeInteger(row.sort_index) || row.sort_index < 0)
+                    return bad("nav.order: sort_index a whole number from 0");
+                if (groupRow ? row.group_name !== null : !name(row.group_name))
+                    return bad("nav.order: group_name null for a group, the group's name for an instance");
+            }
+            return v;
+        }],
+    ["nav.collapsed", (v) => uniqueStrings(v, 200, name, "nav.collapsed")],
+    ["nav.filter", (v) => {
+            if (!plain(v) || !exactly(v, ["q", "status", "cli"]))
+                return bad("nav.filter: { q, status, cli }");
+            if (!shortText(v.q, 200))
+                return bad("nav.filter: q at most 200 characters");
+            const status = uniqueStrings(v.status, STATUS_FACETS.size, (s) => typeof s === "string" && STATUS_FACETS.has(s), "nav.filter.status");
+            if (isInvalid(status))
+                return status;
+            const cli = uniqueStrings(v.cli, 32, (s) => typeof s === "string" && /^[a-z0-9][a-z0-9_-]{0,31}$/.test(s), "nav.filter.cli");
+            if (isInvalid(cli))
+                return cli;
+            return { q: v.q, status, cli };
+        }],
+    // #1664: the starred instances, in the order they were starred (or moved). Whether each one exists is checked where
+    // the fleet is known (parseWebPrefsPatch's `exists`); a deleted one is dropped on read and when it is removed.
+    [FAVORITES, (v) => uniqueStrings(v, MAX_FAVORITES, name, FAVORITES)],
+    // HTML previews allowed. Who may write it at all is the route's business (a signed-in session, never the public link).
+    ["preview.optIn", (v) => (typeof v === "boolean" ? v : bad("preview.optIn: true or false"))],
+    // #1722: which name leads where the web shows an instance — its nickname (display name) or its real instance name.
+    ["names.primary", (v) => (v === "nickname" || v === "instance" ? v : bad("names.primary: nickname or instance"))],
+    // #1827: a web person's own profile — the name they chose, and their account's display name at their last sign-in.
+    // Kept here so it follows the person (their bucket), but never a /ui/prefs key: read and written only through
+    // profile() / setProfileName() / setPlatformName(), and checked in full where it is used (web-profile.ts). The file's
+    // own check is only its shape.
+    [PROFILE_NAME, (v) => (typeof v === "string" && v.length >= 1 && v.length <= 256 ? v : bad("profile.name"))],
+    [PROFILE_PLATFORM_NAME, (v) => (typeof v === "string" && v.length >= 1 && v.length <= 256 ? v : bad("profile.platformName"))],
+]);
+export const WEB_PREF_KEYS = [...REGISTRY.keys()].filter((k) => !PROFILE_KEYS.has(k));
+export function isWebPrefKey(key) { return REGISTRY.has(key) && !PROFILE_KEYS.has(key); }
+/**
+ * A request's `set`: own keys only, each known, each valid — or the first reason it is not. All or nothing.
+ * `exists`: whether an instance of that name is in the fleet now (#1664: a favorite must be one).
+ */
+export function parseWebPrefsPatch(set, exists) {
+    if (!plain(set))
+        return { ok: false, error: "set: an object of preference keys" };
+    const patch = new Map();
+    const keys = Object.keys(set);
+    if (!keys.length)
+        return { ok: false, error: "set: at least one preference" };
+    for (const key of keys) {
+        const validate = PROFILE_KEYS.has(key) ? undefined : REGISTRY.get(key);
+        if (!validate)
+            return { ok: false, error: `unknown_pref: ${key.slice(0, 64)}` };
+        const raw = set[key];
+        if (raw === null) {
+            patch.set(key, null);
+            continue;
+        }
+        const value = validate(raw);
+        if (isInvalid(value))
+            return { ok: false, error: value.invalid };
+        if (key === FAVORITES) {
+            const unknown = value.find((n) => !exists || !exists(n));
+            if (unknown !== undefined)
+                return { ok: false, error: `unknown_instance: ${unknown.slice(0, 64)}` };
+        }
+        patch.set(key, value);
+    }
+    return { ok: true, patch };
+}
+export class WebPrefsStore {
+    dir;
+    opts;
+    state = null;
+    /**
+     * `exists` (#1664): whether an instance of that name is in the fleet now — a favorite that is not is never served,
+     * and is never accepted.
+     */
+    constructor(dir, opts = {}) {
+        this.dir = dir;
+        this.opts = opts;
+    }
+    /** parseWebPrefsPatch against this fleet. */
+    parsePatch(set) { return parseWebPrefsPatch(set, this.opts.exists); }
+    get path() { return join(this.dir, WEB_PREFS_FILE); }
+    load() {
+        // A store that could not read its file tries again next time (a permission put back, a disk that recovered); one
+        // that did keeps what it read.
+        if (this.state && this.state !== "unreadable")
+            return this.state;
+        const empty = { buckets: new Map(), rev: 0 };
+        // Only a file that is definitely not there (ENOENT) is a new, empty store. Anything else — a read refused (EACCES),
+        // an I/O error, no place for the file at all, content of another shape — is "unreadable": the defaults are served
+        // and nothing is written, so the file is never replaced and a page or status frame never fails because of it.
+        try {
+            let raw;
+            try {
+                raw = readFileSync(this.path, "utf8");
+            }
+            catch (err) {
+                if (err?.code === "ENOENT")
+                    return (this.state = empty);
+                return (this.state = "unreadable");
+            }
+            const doc = JSON.parse(raw);
+            if (!plain(doc) || doc.version !== 1 || !plain(doc.identities) || !Number.isSafeInteger(doc.rev))
+                return (this.state = "unreadable");
+            const buckets = new Map();
+            for (const id of Object.keys(doc.identities)) {
+                const raw = doc.identities[id];
+                if (!plain(raw) || !plain(raw.values) || !plain(raw.updated))
+                    return (this.state = "unreadable");
+                const bucket = { values: new Map(), updated: new Map() };
+                // A key this version no longer knows, or a value it would refuse now, is left out (never served).
+                for (const key of Object.keys(raw.values)) {
+                    const validate = REGISTRY.get(key);
+                    if (!validate)
+                        continue;
+                    const value = validate(raw.values[key]);
+                    if (isInvalid(value))
+                        continue;
+                    bucket.values.set(key, value);
+                    const at = raw.updated[key];
+                    bucket.updated.set(key, typeof at === "number" && Number.isFinite(at) ? at : 0);
+                }
+                buckets.set(id, bucket);
+            }
+            return (this.state = { buckets, rev: doc.rev });
+        }
+        catch {
+            return (this.state = "unreadable");
+        }
+    }
+    read(identity = OPERATOR) {
+        const state = this.load();
+        if (state === "unreadable")
+            return { values: {}, rev: 0, unreadable: true };
+        return this.viewOf(state, identity);
+    }
+    rev() { const s = this.load(); return s === "unreadable" ? 0 : s.rev; }
+    /** #1664: an instance was removed — drop it from every favorites list (a write, and a new rev, only if one had it). */
+    forgetInstance(name) {
+        const state = this.load();
+        if (state === "unreadable")
+            return;
+        for (const [identity, bucket] of state.buckets) {
+            const list = bucket.values.get(FAVORITES);
+            if (list && list.includes(name))
+                this.write(identity, new Map([[FAVORITES, list.filter((n) => n !== name)]]));
+        }
+    }
+    viewOf(state, identity) {
+        const values = Object.create(null);
+        const bucket = state.buckets.get(identity);
+        if (bucket)
+            for (const [k, v] of bucket.values)
+                if (!PROFILE_KEYS.has(k))
+                    values[k] = v;
+        // #1664: a favorite whose instance was deleted is dropped (paused or stopped ones are still instances: kept).
+        if (Object.hasOwn(values, FAVORITES)) {
+            const exists = this.opts.exists;
+            values[FAVORITES] = values[FAVORITES].filter((n) => !!exists && exists(n));
+        }
+        return { values: { ...values }, rev: state.rev };
+    }
+    /**
+     * Set (or, with null, clear) the patch's keys. `onlyIfUnset`: a device's first upload of what it had locally — only
+     * the keys the host does not have yet are taken, so the first device to arrive wins and the host wins from then on.
+     */
+    write(identity, patch, opts = {}) {
+        const state = this.load();
+        if (state === "unreadable")
+            return { ok: false, status: 503, error: "prefs_unreadable" };
+        const prior = state.buckets.get(identity);
+        const next = { values: new Map(prior?.values), updated: new Map(prior?.updated) };
+        const at = (this.opts.now ?? Date.now)();
+        const changed = [];
+        for (const [key, value] of patch) {
+            if (opts.onlyIfUnset && next.values.has(key))
+                continue;
+            if (value === null) {
+                if (!next.values.has(key))
+                    continue;
+                next.values.delete(key);
+                next.updated.delete(key);
+            }
+            else {
+                if (next.values.has(key) && JSON.stringify(next.values.get(key)) === JSON.stringify(value))
+                    continue;
+                next.values.set(key, value);
+                next.updated.set(key, at);
+            }
+            changed.push(key);
+        }
+        if (!changed.length)
+            return { ok: true, view: this.viewOf(state, identity), changed };
+        const buckets = new Map(state.buckets);
+        buckets.set(identity, next);
+        const candidate = { buckets, rev: state.rev + 1 };
+        (this.opts.write ?? ((path, data) => atomicWriteFileSync(path, data, { mode: 0o600 })))(this.path, serialize(candidate));
+        // Only once it is on disk: a failed write leaves memory as the file is.
+        this.state = candidate;
+        return { ok: true, view: this.viewOf(candidate, identity), changed };
+    }
+    /** #1827: a web person's profile as kept (checked again where it is used); null while the file cannot be read. */
+    profile(identity) {
+        const state = this.load();
+        if (state === "unreadable")
+            return null;
+        const values = state.buckets.get(identity)?.values;
+        const name = values?.get(PROFILE_NAME);
+        const platformName = values?.get(PROFILE_PLATFORM_NAME);
+        return { ...(name !== undefined ? { name } : {}), ...(platformName !== undefined ? { platformName } : {}) };
+    }
+    /** #1827: set (or, with null, clear) a person's own name — already validated by the caller (web-profile.ts). */
+    setProfileName(identity, name) {
+        const w = this.write(identity, new Map([[PROFILE_NAME, name]]));
+        return w.ok ? { ok: true } : w;
+    }
+    /** #1827: their account's display name at a sign-in (a change is a write and a new rev; the same, nothing). */
+    setPlatformName(identity, name) {
+        const value = name.slice(0, 256);
+        if (value)
+            this.write(identity, new Map([[PROFILE_PLATFORM_NAME, value]]));
+    }
+}
+function serialize(state) {
+    const identities = {};
+    for (const [id, b] of state.buckets) {
+        identities[id] = { values: Object.fromEntries(b.values), updated: Object.fromEntries(b.updated) };
+    }
+    // Object.fromEntries with a "__proto__" entry defines an own property, but no such key ever gets in: ids are ours, keys
+    // are the registry's.
+    return JSON.stringify({ version: 1, rev: state.rev, identities }, null, 2) + "\n";
+}
+//# sourceMappingURL=web-prefs.js.map

package/dist/web-prefs.js.map

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

package/dist/web-preview.d.ts

@@ -40,7 +40,7 @@ export interface PreviewAvailability {
  * previewAvailability; `publicLink` and `notOffered` from the app shell, which asks it for neither the public link nor
  * a page that is not the full app. One list: the page's dictionary is checked against it.
  */
-export declare const PREVIEW_OFF_CODES: readonly ["fleetOff", "unchecked", "noPort", "notListed", "needOrigin", "needHttps", "sameOrigin", "publicLink", "notOffered"];
+export declare const PREVIEW_OFF_CODES: readonly ["fleetOff", "unchecked", "noPort", "notListed", "needOrigin", "needHttps", "sameOrigin", "publicLink", "publicLinkStarting", "publicLinkPreviewFailed", "notOffered"];
 export type PreviewOffCode = typeof PREVIEW_OFF_CODES[number];
 /** scheme://host[:port] from a Host header the host guard already accepted; a default port is dropped. */
 export declare function dashboardOriginFor(hostHeader: string | undefined, secure: boolean): string | null;
@@ -78,9 +78,22 @@ export interface PreviewListener {
  * it does not answer to → empty 403. No X-Frame-Options (it must be framable by the dashboard), no cookie or
  * header parsing beyond Host, nothing logged per request. Built once: the shim and its headers never change.
  */
+/**
+ * The /frame response for one set of dashboard origins (design §5.1): the shim and its exact headers. Shared by the
+ * local preview listener and the public link's own preview gateway (#1723), so both serve the very same frame.
+ */
+export declare function previewFrameResponse(bootId: string, origins: readonly string[]): {
+    body: Buffer;
+    headers: Record<string, string>;
+};
 export declare function createPreviewListener(opts: {
     settings: PreviewSettings;
     healthPort: number;
     config: HostGuardConfig | null | undefined;
     bootId?: string;
+    /**
+     * #1723: dashboard origins that may frame the preview for now — the open public link's, when a web.preview_origin is
+     * configured (it is used instead of a preview tunnel). Asked per request; never cached past the answer.
+     */
+    extraOrigins?(): readonly string[];
 }): PreviewListener;

package/dist/web-preview.js

@@ -67,7 +67,7 @@ export function previewOriginProblem(value, config) {
  * previewAvailability; `publicLink` and `notOffered` from the app shell, which asks it for neither the public link nor
  * a page that is not the full app. One list: the page's dictionary is checked against it.
  */
-export const PREVIEW_OFF_CODES = ["fleetOff", "unchecked", "noPort", "notListed", "needOrigin", "needHttps", "sameOrigin", "publicLink", "notOffered"];
+export const PREVIEW_OFF_CODES = ["fleetOff", "unchecked", "noPort", "notListed", "needOrigin", "needHttps", "sameOrigin", "publicLink", "publicLinkStarting", "publicLinkPreviewFailed", "notOffered"];
 const DEFAULT_PORT = { "http:": "80", "https:": "443" };
 /** scheme://host[:port] from a Host header the host guard already accepted; a default port is dropped. */
 export function dashboardOriginFor(hostHeader, secure) {
@@ -203,19 +203,40 @@ export function buildShim(bootId, origins) {
  * it does not answer to → empty 403. No X-Frame-Options (it must be framable by the dashboard), no cookie or
  * header parsing beyond Host, nothing logged per request. Built once: the shim and its headers never change.
  */
+/**
+ * The /frame response for one set of dashboard origins (design §5.1): the shim and its exact headers. Shared by the
+ * local preview listener and the public link's own preview gateway (#1723), so both serve the very same frame.
+ */
+export function previewFrameResponse(bootId, origins) {
+    const body = Buffer.from(buildShim(bootId, origins), "utf8");
+    return {
+        body,
+        headers: {
+            "Content-Type": "text/html; charset=utf-8",
+            "Content-Security-Policy": previewFrameCsp(origins),
+            "Permissions-Policy": PERMISSIONS_POLICY,
+            "Referrer-Policy": "no-referrer",
+            "Cross-Origin-Resource-Policy": "same-origin",
+            "X-Content-Type-Options": "nosniff",
+            "Cache-Control": "no-store",
+            "Content-Length": String(body.length),
+        },
+    };
+}
 export function createPreviewListener(opts) {
     const bootId = opts.bootId ?? randomBytes(16).toString("hex");
     const origins = dashboardOrigins(opts.settings, opts.healthPort, opts.config);
-    const body = Buffer.from(buildShim(bootId, origins), "utf8");
-    const headers = {
-        "Content-Type": "text/html; charset=utf-8",
-        "Content-Security-Policy": previewFrameCsp(origins),
-        "Permissions-Policy": PERMISSIONS_POLICY,
-        "Referrer-Policy": "no-referrer",
-        "Cross-Origin-Resource-Policy": "same-origin",
-        "X-Content-Type-Options": "nosniff",
-        "Cache-Control": "no-store",
-        "Content-Length": String(body.length),
+    const { body, headers } = previewFrameResponse(bootId, origins);
+    let widened = null;
+    const frameFor = () => {
+        const extra = (opts.extraOrigins?.() ?? []).filter(o => !origins.includes(o));
+        if (extra.length === 0)
+            return { body, headers };
+        const all = [...origins, ...extra];
+        const key = all.join(" ");
+        if (widened?.key !== key)
+            widened = { key, ...previewFrameResponse(bootId, all) };
+        return widened;
     };
     const hosts = new Set(LOOPBACK_HOST_NAMES);
     if (opts.settings.origin) {
@@ -234,8 +255,9 @@ export function createPreviewListener(opts) {
             return empty(res, 403);
         if (req.method !== "GET" || req.url !== "/frame")
             return empty(res, 404);
-        res.writeHead(200, headers);
-        res.end(body);
+        const frame = frameFor();
+        res.writeHead(200, frame.headers);
+        res.end(frame.body);
     });
     const settings = { ...opts.settings };
     // A listener on port 0 learns its real port when it binds: that is the one a /ui load must be offered.