@songsid/agend 2.2.0 → 2.2.5

package/dist/web-identity-color.js

@@ -0,0 +1,209 @@
+/**
+ * #1958: an instance's identity colour — the cue people scan the sidebar by — and where it shows (its placements: the
+ * name, a bar at the row's left edge, the avatar's ring). docs/design/1958-identity-color.md has the decisions.
+ *
+ * The colour, in a fixed order:
+ *   1. person  — a person's pick from the web dashboard (this module's store), shared host-wide like the profile and
+ *                the identity card;
+ *   2. agent   — the agent's own (#1629 theme.identity.color, else its theme accent), only where the viewer shows
+ *                agents' themes;
+ *   3. role    — the own bot's colour from its highest coloured Discord role (never a shared bot's);
+ *   4. auto    — one of a few soft colours, chosen by a stable hash of the name (two instances may share one).
+ * The placements, likewise: a person's choice for this instance > the agent's (theme.identity.show, while themes are
+ * shown) > the host's default (web prefs `color.show`, else name, bar and ring — #2056). The host may turn colours off altogether
+ * (`color.off`): nothing is drawn, and every pick is kept for when they come back.
+ *
+ * A colour is kept and sent as `preset:<id>`, `auto:<id>` (both drawn with their light or dark value, readable on the
+ * page's background) or `#rrggbb` (a custom colour, drawn as it is; name text uses a readable shade of it).
+ * Its own table (instance_identity), never new columns on instance_profile or instance_card: "Clear card" leaves the
+ * colour alone, and an older AgEnD reading profiles.db sees what it knew.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalColor, contrastRatio, THEME_DEFAULTS } from "./web-theme.js";
+import { canonicalIdentityColor, canonicalPlacements, DEFAULT_PLACEMENTS } from "./web-identity-palette.js";
+export { AUTO_PALETTE, autoIdentityColor, canonicalIdentityColor, canonicalPlacements, DEFAULT_PLACEMENTS, IDENTITY_PALETTE, identityColorValue, PLACEMENTS } from "./web-identity-palette.js";
+/** The sidebar's own background (src/ui/shared/tokens.css --bg-sidebar), where names are drawn as well as the page's. */
+export const SIDEBAR_BG = { light: "#f9f9f9", dark: "#171717" };
+/**
+ * The shade of `hex` that name text uses on a page in `mode`: the colour itself if it reads at 4.5:1 against the
+ * page's and the sidebar's backgrounds, else the nearest step toward black (light page) or white (dark page) that does.
+ */
+export function readableShade(hex, mode) {
+    const backgrounds = [THEME_DEFAULTS[mode].bg, SIDEBAR_BG[mode]];
+    const base = canonicalColor(hex);
+    if (!base)
+        return THEME_DEFAULTS[mode].text;
+    const toward = mode === "light" ? 0 : 255;
+    const channels = [1, 3, 5].map(i => parseInt(base.slice(i, i + 2), 16));
+    for (let step = 0; step <= 20; step++) {
+        const mix = channels.map(c => Math.round(c + (toward - c) * (step / 20)));
+        const shade = `#${mix.map(c => c.toString(16).padStart(2, "0")).join("")}`;
+        if (backgrounds.every(bg => contrastRatio(shade, bg) >= 4.5))
+            return shade;
+    }
+    return THEME_DEFAULTS[mode].text;
+}
+/**
+ * The colour in force and where it comes from. `showThemes`: whether the viewer shows agents' themes (fx.show, not
+ * safe mode) — when not, the agent's tier is skipped, as the rest of the agent's theme is.
+ */
+export function resolveIdentityColor(t, opts) {
+    if (t.person)
+        return { color: t.person, source: "person" };
+    const agent = opts.showThemes ? canonicalIdentityColor(t.agent) : null;
+    if (agent)
+        return { color: agent, source: "agent" };
+    const role = canonicalColor(t.role);
+    if (role)
+        return { color: role, source: "role" };
+    return { color: t.auto, source: "auto" };
+}
+/** Where the colour shows: a person's choice, else the agent's (themes shown), else the host's default, else all three (DEFAULT_PLACEMENTS). */
+export function resolvePlacements(t, opts) {
+    const person = canonicalPlacements(t.person);
+    if (person)
+        return { show: person, source: "person" };
+    const agent = opts.showThemes ? canonicalPlacements(t.agent) : null;
+    if (agent)
+        return { show: agent, source: "agent" };
+    return { show: canonicalPlacements(opts.hostDefault) ?? [...DEFAULT_PLACEMENTS], source: "host" };
+}
+/** The first cut's table (instance_color, colour only, on feat/2.3-web-mod before 2.3 ships). */
+const LEGACY = "instance_color";
+/** Done once per database, recorded in it: the first cut's picks were carried over (Prism #2003 P2-1). */
+const MIGRATED = "instance_color_carried";
+const hasTable = (db, name) => !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name);
+const migrated = (db) => hasTable(db, "instance_identity_meta") && !!db.prepare("SELECT 1 FROM instance_identity_meta WHERE key = ?").get(MIGRATED);
+const ready = new WeakSet();
+/**
+ * The table, made once per connection. The first cut's picks carry over once per database — recorded in
+ * instance_identity_meta, so a pick reset since never comes back on a later connection — and never over a newer choice;
+ * the old table is left as it is. Prism #2003 P2-2: a connection counts as ready only when this ran outside a
+ * transaction (a rollback would take the tables away, never the mark), and the route sets it up before its transaction.
+ */
+function table(db) {
+    if (!ready.has(db)) {
+        db.transaction(() => {
+            db.exec(`CREATE TABLE IF NOT EXISTS instance_identity (
+        instance_name TEXT PRIMARY KEY,
+        color TEXT,
+        show TEXT,
+        updated_at INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS instance_identity_meta (key TEXT PRIMARY KEY, value TEXT);`);
+            if (!migrated(db)) {
+                if (hasTable(db, LEGACY))
+                    db.exec(`INSERT OR IGNORE INTO instance_identity (instance_name, color, show, updated_at) SELECT instance_name, color, NULL, updated_at FROM ${LEGACY}`);
+                db.prepare("INSERT OR IGNORE INTO instance_identity_meta (key, value) VALUES (?, '1')").run(MIGRATED);
+            }
+        })();
+        if (!db.inTransaction)
+            ready.add(db);
+    }
+    return db;
+}
+const parseShow = (raw) => {
+    if (raw === null)
+        return null;
+    try {
+        return canonicalPlacements(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+};
+/** The people's choices, one row per instance. */
+export class IdentityColorStore {
+    openDb;
+    now;
+    constructor(openDb, now = () => Date.now()) {
+        this.openDb = openDb;
+        this.now = now;
+    }
+    get(name) {
+        const row = table(this.openDb()).prepare("SELECT color, show FROM instance_identity WHERE instance_name = ?").get(name);
+        return { color: row?.color ? canonicalIdentityColor(row.color) : null, show: parseShow(row?.show ?? null) };
+    }
+    /** Every choice, for a status read: only when profiles.db exists and has the table — a read creates nothing. */
+    static all(dataDir, openDb) {
+        if (!existsSync(join(dataDir, "profiles.db")))
+            return new Map();
+        try {
+            const db = openDb();
+            const out = new Map();
+            if (hasTable(db, "instance_identity")) {
+                for (const r of db.prepare("SELECT instance_name, color, show FROM instance_identity").all()) {
+                    // A value this version cannot read is no choice, not an error.
+                    const p = { color: r.color ? canonicalIdentityColor(r.color) : null, show: parseShow(r.show) };
+                    if (p.color || p.show)
+                        out.set(r.instance_name, p);
+                }
+            }
+            if (!migrated(db) && hasTable(db, LEGACY)) {
+                // Not carried over yet (nothing has written since): the first cut's picks read as they are, under a newer one.
+                for (const r of db.prepare(`SELECT instance_name, color FROM ${LEGACY}`).all()) {
+                    const c = canonicalIdentityColor(r.color);
+                    if (c && !out.has(r.instance_name))
+                        out.set(r.instance_name, { color: c, show: null });
+                }
+            }
+            return out;
+        }
+        catch {
+            return new Map();
+        }
+    }
+    /**
+     * A person's choice, field by field: only the fields given change; `null` (or "" for the colour) clears one — the next
+     * tier shows again. Both checked before anything is written. A row with nothing left is removed.
+     */
+    set(name, patch) {
+        const next = this.check(patch);
+        if (!next.ok)
+            return next;
+        try {
+            const db = table(this.openDb());
+            const prev = this.get(name);
+            const color = next.color === undefined ? prev.color : next.color;
+            const show = next.show === undefined ? prev.show : next.show;
+            if (color === null && show === null)
+                db.prepare("DELETE FROM instance_identity WHERE instance_name = ?").run(name);
+            else
+                db.prepare(`INSERT INTO instance_identity (instance_name, color, show, updated_at) VALUES (@n, @c, @s, @t)
+        ON CONFLICT(instance_name) DO UPDATE SET color = excluded.color, show = excluded.show, updated_at = excluded.updated_at`)
+                    .run({ n: name, c: color, s: show === null ? null : JSON.stringify(show), t: this.now() });
+        }
+        catch (err) {
+            return { ok: false, status: 503, error: "color_write_failed", detail: err.message };
+        }
+        return { ok: true };
+    }
+    /** The patch, checked: `undefined` for a field not given, `null` to clear it. Writes nothing. */
+    check(patch) {
+        const out = { ok: true };
+        if (patch.color !== undefined) {
+            const v = patch.color;
+            if (v === null || (typeof v === "string" && !v.trim()))
+                out.color = null;
+            else {
+                const c = canonicalIdentityColor(v);
+                if (!c)
+                    return { ok: false, status: 400, error: "color", detail: "a preset id or a hex colour #rrggbb" };
+                out.color = c;
+            }
+        }
+        if (patch.show !== undefined) {
+            if (patch.show === null)
+                out.show = null;
+            else {
+                const s = canonicalPlacements(patch.show);
+                if (!s)
+                    return { ok: false, status: 400, error: "color_show", detail: "a list of where the colour shows: name, bar, ring (each once; [] for nowhere)" };
+                out.show = s;
+            }
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=web-identity-color.js.map

package/dist/web-identity-color.js.map

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

package/dist/web-identity-palette.d.ts

@@ -0,0 +1,113 @@
+/**
+ * #1958: the identity colour's palettes and placements — no imports, so the theme's schema (web-theme.ts) and the
+ * colour's resolution (web-identity-color.ts) both read them without a cycle.
+ *
+ * - The presets a person (or an agent) picks from: 12 clear colours.
+ * - The automatic colours (the user's decision 4): a handful of soft, low-saturation colours like the default avatar
+ *   colours of Telegram and Discord, chosen by a stable hash of the name. Two instances may share one.
+ * Every value reads at 4.5:1 or better on the page's and the sidebar's background, in its mode (a test pins it).
+ */
+/** The presets: each one's value on the light and on the dark page. */
+export declare const IDENTITY_PALETTE: readonly [{
+    readonly id: "red";
+    readonly light: "#cf222e";
+    readonly dark: "#ff7b72";
+}, {
+    readonly id: "orange";
+    readonly light: "#bc4c00";
+    readonly dark: "#ffa657";
+}, {
+    readonly id: "amber";
+    readonly light: "#8a5d00";
+    readonly dark: "#e3b341";
+}, {
+    readonly id: "lime";
+    readonly light: "#4d7c0f";
+    readonly dark: "#a3e635";
+}, {
+    readonly id: "green";
+    readonly light: "#1a7f37";
+    readonly dark: "#56d364";
+}, {
+    readonly id: "teal";
+    readonly light: "#0f766e";
+    readonly dark: "#2dd4bf";
+}, {
+    readonly id: "cyan";
+    readonly light: "#0e7490";
+    readonly dark: "#22d3ee";
+}, {
+    readonly id: "blue";
+    readonly light: "#0a62c2";
+    readonly dark: "#7ab7ff";
+}, {
+    readonly id: "indigo";
+    readonly light: "#4f46e5";
+    readonly dark: "#a5b4fc";
+}, {
+    readonly id: "violet";
+    readonly light: "#8250df";
+    readonly dark: "#d2a8ff";
+}, {
+    readonly id: "pink";
+    readonly light: "#bf3989";
+    readonly dark: "#f778ba";
+}, {
+    readonly id: "slate";
+    readonly light: "#57606a";
+    readonly dark: "#b1bac4";
+}];
+/** The automatic colours: soft, and few on purpose (duplicates are fine). */
+export declare const AUTO_PALETTE: readonly [{
+    readonly id: "sand";
+    readonly light: "#8a6d3b";
+    readonly dark: "#d4b98a";
+}, {
+    readonly id: "clay";
+    readonly light: "#9c5a4a";
+    readonly dark: "#d9a294";
+}, {
+    readonly id: "rose";
+    readonly light: "#9b4f6a";
+    readonly dark: "#d99ab0";
+}, {
+    readonly id: "plum";
+    readonly light: "#7a5a8c";
+    readonly dark: "#c3a6d6";
+}, {
+    readonly id: "dusk";
+    readonly light: "#5a628f";
+    readonly dark: "#a9b0db";
+}, {
+    readonly id: "sea";
+    readonly light: "#3f7286";
+    readonly dark: "#92c2d4";
+}, {
+    readonly id: "moss";
+    readonly light: "#5b7340";
+    readonly dark: "#a9c48d";
+}, {
+    readonly id: "slate";
+    readonly light: "#5f6b78";
+    readonly dark: "#aeb8c4";
+}];
+export type PresetId = (typeof IDENTITY_PALETTE)[number]["id"];
+export type AutoId = (typeof AUTO_PALETTE)[number]["id"];
+/** What is stored and sent: a preset, an automatic colour (never stored), or a custom colour. */
+export type IdentityColor = `preset:${PresetId}` | `auto:${AutoId}` | `#${string}`;
+/**
+ * A colour as a person or an agent gives it — a preset's id ("blue", or "preset:blue") or a hex colour ("#abc",
+ * "#aabbcc", any case) — in the form it is kept; null for anything else (an automatic colour is never picked).
+ */
+export declare function canonicalIdentityColor(v: unknown): IdentityColor | null;
+/** The colour drawn for `c` on a page in `mode`: a preset's or an automatic colour's value for that mode, a custom one as it is. */
+export declare function identityColorValue(c: IdentityColor, mode: "light" | "dark"): string;
+/** The automatic colour: one of AUTO_PALETTE, chosen by the name (32-bit FNV-1a over its UTF-8 bytes), the same on every load. */
+export declare function autoIdentityColor(name: string): IdentityColor;
+/** Where the colour shows (the user's decision 2): the name, a bar at the row's left edge, the avatar's ring. */
+export declare const PLACEMENTS: readonly ["name", "bar", "ring"];
+export type Placement = (typeof PLACEMENTS)[number];
+/** The host's default where nobody chose: all three (#2056, the user 2026-10-17; it was ring and bar, #1958 decision 1). */
+export declare const DEFAULT_PLACEMENTS: readonly Placement[];
+/** A set of places, in PLACEMENTS order, no repeats; [] is "nowhere". null for anything else. */
+export declare function canonicalPlacements(v: unknown): Placement[] | null;

package/dist/web-identity-palette.js

@@ -0,0 +1,84 @@
+/**
+ * #1958: the identity colour's palettes and placements — no imports, so the theme's schema (web-theme.ts) and the
+ * colour's resolution (web-identity-color.ts) both read them without a cycle.
+ *
+ * - The presets a person (or an agent) picks from: 12 clear colours.
+ * - The automatic colours (the user's decision 4): a handful of soft, low-saturation colours like the default avatar
+ *   colours of Telegram and Discord, chosen by a stable hash of the name. Two instances may share one.
+ * Every value reads at 4.5:1 or better on the page's and the sidebar's background, in its mode (a test pins it).
+ */
+/** The presets: each one's value on the light and on the dark page. */
+export const IDENTITY_PALETTE = [
+    { id: "red", light: "#cf222e", dark: "#ff7b72" },
+    { id: "orange", light: "#bc4c00", dark: "#ffa657" },
+    { id: "amber", light: "#8a5d00", dark: "#e3b341" },
+    { id: "lime", light: "#4d7c0f", dark: "#a3e635" },
+    { id: "green", light: "#1a7f37", dark: "#56d364" },
+    { id: "teal", light: "#0f766e", dark: "#2dd4bf" },
+    { id: "cyan", light: "#0e7490", dark: "#22d3ee" },
+    { id: "blue", light: "#0a62c2", dark: "#7ab7ff" },
+    { id: "indigo", light: "#4f46e5", dark: "#a5b4fc" },
+    { id: "violet", light: "#8250df", dark: "#d2a8ff" },
+    { id: "pink", light: "#bf3989", dark: "#f778ba" },
+    { id: "slate", light: "#57606a", dark: "#b1bac4" },
+];
+/** The automatic colours: soft, and few on purpose (duplicates are fine). */
+export const AUTO_PALETTE = [
+    { id: "sand", light: "#8a6d3b", dark: "#d4b98a" },
+    { id: "clay", light: "#9c5a4a", dark: "#d9a294" },
+    { id: "rose", light: "#9b4f6a", dark: "#d99ab0" },
+    { id: "plum", light: "#7a5a8c", dark: "#c3a6d6" },
+    { id: "dusk", light: "#5a628f", dark: "#a9b0db" },
+    { id: "sea", light: "#3f7286", dark: "#92c2d4" },
+    { id: "moss", light: "#5b7340", dark: "#a9c48d" },
+    { id: "slate", light: "#5f6b78", dark: "#aeb8c4" },
+];
+const PRESETS = new Map(IDENTITY_PALETTE.map(p => [p.id, p]));
+const AUTOS = new Map(AUTO_PALETTE.map(p => [p.id, p]));
+/** "#rgb" | "#rrggbb", any case → "#rrggbb" lowercase (web-theme.ts canonicalColor's rule); anything else → null. */
+function hexColor(v) {
+    const m = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(v);
+    if (!m)
+        return null;
+    const h = m[1].toLowerCase();
+    return h.length === 3 ? `#${h[0]}${h[0]}${h[1]}${h[1]}${h[2]}${h[2]}` : `#${h}`;
+}
+/**
+ * A colour as a person or an agent gives it — a preset's id ("blue", or "preset:blue") or a hex colour ("#abc",
+ * "#aabbcc", any case) — in the form it is kept; null for anything else (an automatic colour is never picked).
+ */
+export function canonicalIdentityColor(v) {
+    if (typeof v !== "string")
+        return null;
+    const id = v.startsWith("preset:") ? v.slice("preset:".length) : v;
+    if (PRESETS.has(id))
+        return `preset:${id}`;
+    return hexColor(v);
+}
+/** The colour drawn for `c` on a page in `mode`: a preset's or an automatic colour's value for that mode, a custom one as it is. */
+export function identityColorValue(c, mode) {
+    const p = c.startsWith("preset:") ? PRESETS.get(c.slice(7)) : c.startsWith("auto:") ? AUTOS.get(c.slice(5)) : undefined;
+    return p ? p[mode] : c;
+}
+/** The automatic colour: one of AUTO_PALETTE, chosen by the name (32-bit FNV-1a over its UTF-8 bytes), the same on every load. */
+export function autoIdentityColor(name) {
+    let h = 0x811c9dc5;
+    for (const unit of new TextEncoder().encode(name)) {
+        h ^= unit;
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return `auto:${AUTO_PALETTE[h % AUTO_PALETTE.length].id}`;
+}
+/** Where the colour shows (the user's decision 2): the name, a bar at the row's left edge, the avatar's ring. */
+export const PLACEMENTS = ["name", "bar", "ring"];
+/** The host's default where nobody chose: all three (#2056, the user 2026-10-17; it was ring and bar, #1958 decision 1). */
+export const DEFAULT_PLACEMENTS = ["name", "bar", "ring"];
+/** A set of places, in PLACEMENTS order, no repeats; [] is "nowhere". null for anything else. */
+export function canonicalPlacements(v) {
+    if (!Array.isArray(v) || v.length > PLACEMENTS.length || !v.every(p => PLACEMENTS.includes(p)))
+        return null;
+    if (new Set(v).size !== v.length)
+        return null;
+    return PLACEMENTS.filter(p => v.includes(p));
+}
+//# sourceMappingURL=web-identity-palette.js.map

package/dist/web-identity-palette.js.map

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

package/dist/web-image-meta.d.ts

@@ -0,0 +1,38 @@
+/**
+ * #1629 r4 §1: what an uploaded picture or font is, how large it is, and the same file without its metadata — all
+ * from the bytes, never decoding an image. Used by owner-CSS assets (r4 §3) and the identity card (r4 §1).
+ *
+ * Metadata is removed by byte surgery:
+ * - JPEG: the APP1–APP15 and COM segments go (EXIF, GPS, XMP, ICC, comments) wherever they are — before the first
+ *   scan or between the scans of a progressive file; APP0 (JFIF) and the image stay. Every scan's entropy-coded data
+ *   is walked to its end, and the file must end with EOI (what follows it is dropped).
+ * - PNG: the tEXt, zTXt, iTXt, eXIf and tIME chunks go.
+ * - WebP: the EXIF and "XMP " chunks go, and VP8X's EXIF/XMP flags are cleared to match. A file shorter than its
+ *   RIFF header says is refused; bytes after the RIFF end are dropped.
+ * A file this module cannot walk to its end is refused, never passed through.
+ */
+export type MediaKind = "png" | "jpeg" | "webp" | "gif" | "woff2";
+export declare const MEDIA_MIME: Record<MediaKind, string>;
+export declare const MEDIA_EXT: Record<MediaKind, string>;
+/** The kind by magic bytes, or null. */
+export declare function sniffMedia(b: Uint8Array): MediaKind | null;
+/** Width and height from the headers, or null when the file does not say (or is not an image). */
+export declare function imageSize(b: Uint8Array, kind: MediaKind): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * A JPEG's EXIF orientation (1–8), or 1 when it has none or it cannot be read. Read from the first APP1 "Exif" segment
+ * before the first scan: IFD0's tag 0x0112, in either byte order.
+ */
+export declare function jpegOrientation(b: Uint8Array): number;
+/**
+ * #2184: the size a browser draws a picture at, from its first bytes — width and height
+ * from the headers, swapped when a JPEG's EXIF orientation turns it (5–8; browsers apply it). Null when unknown.
+ */
+export declare function displaySize(b: Uint8Array): {
+    width: number;
+    height: number;
+} | null;
+/** The file without its metadata (see the module comment), or null when it cannot be walked safely. */
+export declare function stripMetadata(b: Uint8Array, kind: MediaKind): Uint8Array | null;