@songsid/agend 2.2.1 → 2.2.6

package/dist/web-theme-store.d.ts

@@ -0,0 +1,257 @@
+import { type MediaKind } from "./web-image-meta.js";
+import { type Theme } from "./web-theme.js";
+import { type AppearanceLimits } from "./web-appearance-limits.js";
+import { type AmbientKind, type AmbientSpec } from "./web-ambient.js";
+import { type AgentWidgetSlot, type WidgetData, type WidgetSpec } from "./web-widget.js";
+export type AppearanceActor = "agent" | "human";
+/** `params` (effects only): the effect's non-default params (CW1), checked against its manifest when placed. */
+export interface Placement {
+    id: string;
+    by: AppearanceActor;
+    at: number;
+    params?: Record<string, unknown>;
+}
+/** r4-4 (option A): a widget is a declarative spec and its data (web-widget.ts); `id` is the spec's content hash. */
+export interface WidgetPlacement extends Placement {
+    spec: WidgetSpec;
+    data: WidgetData;
+}
+/** #2117: an ambient is a declarative spec (web-ambient.ts); `id` is the spec's content hash. */
+export interface AmbientPlacement extends Placement {
+    spec: AmbientSpec;
+}
+export interface Placements {
+    effects: Placement[];
+    widgets: {
+        chat_header?: WidgetPlacement;
+        details?: WidgetPlacement;
+    };
+    /** One looping ambient and one click ambient. An older binary drops this key (an unknown placement), nothing else. */
+    ambient: {
+        loop?: AmbientPlacement;
+        click?: AmbientPlacement;
+    };
+}
+import { THEME_ASSET_SLOTS, type ThemeAssetSlot } from "./web-asset-parts.js";
+export { THEME_ASSET_SLOTS, type ThemeAssetSlot };
+export interface ThemeAsset {
+    id: string;
+    slot: ThemeAssetSlot;
+    kind: MediaKind;
+    bytes: number;
+}
+export interface ThemeRecord {
+    theme: Theme;
+    placements: Placements;
+    assets: ThemeAsset[];
+    /** Who made the last change (an agent's tool, or a person's reset or lock). */
+    by: AppearanceActor;
+    updated: number;
+    /** A person locked it: every agent write is refused until unlocked (r2 (a)). */
+    locked: boolean;
+}
+export type StoreWrite<T = Record<never, never>> = ({
+    ok: true;
+    rev: number;
+} & T) | {
+    ok: false;
+    status: 400 | 404 | 409 | 413 | 503;
+    error: string;
+    detail?: string;
+};
+/** The theme's own picture slots (first design §4). The card's (portrait, banner) are `web.appearance`'s (r4.1 Q3 (b)). */
+export declare const THEME_ASSET_LIMITS: Record<"background" | "avatar", {
+    maxBytes: number;
+    maxSide: number;
+}>;
+/** #2117: an ambient's glyph picture is small and fixed (not configurable): at most this many per instance. */
+export declare const GLYPH_ASSET_LIMIT: {
+    readonly maxBytes: number;
+    readonly maxSide: 128;
+    readonly files: 4;
+};
+/** Width, height and bytes a slot takes now. */
+export declare function slotLimit(slot: ThemeAssetSlot, limits: AppearanceLimits): {
+    maxWidth: number;
+    maxHeight: number;
+    maxBytes: number;
+};
+/**
+ * A picture for a slot, checked as an upload is (magic bytes, size and dimensions for its slot under `limits`) and with
+ * its metadata stripped; its id is the hash of what is kept. Pure: the upload path and a mod bundle's check share it.
+ */
+export declare function prepareThemeAsset(slot: unknown, bytes: Uint8Array, limits: AppearanceLimits): {
+    ok: true;
+    slot: ThemeAssetSlot;
+    kind: MediaKind;
+    kept: Uint8Array;
+    id: string;
+} | {
+    ok: false;
+    status: 400 | 413;
+    error: string;
+    detail?: string;
+};
+export declare class ThemeStore {
+    private readonly dataDir;
+    private readonly opts;
+    private state;
+    readonly path: string;
+    constructor(dataDir: string, opts?: {
+        now?: () => number;
+        limits?: () => AppearanceLimits;
+        /**
+         * Effect ids no longer placed on an instance after a write that held (B2's library: collectUnreferenced, a guarded
+         * collector that rechecks every reference before it deletes anything). Every write path reaches it: setPlacements,
+         * applyLook and its undo, reset, forget.
+         */
+        effectsDropped?: (ids: string[]) => void;
+    });
+    /** The limits in force now (`web.appearance`, clamped); checked at each upload, never against what is stored. */
+    limits(): AppearanceLimits;
+    private now;
+    private assetDir;
+    private load;
+    private save;
+    /** Change one record; on disk first, then in memory. */
+    private commit;
+    rev(): number;
+    readable(): boolean;
+    /** One instance's record (a copy), or a fresh default one. */
+    get(name: string): ThemeRecord;
+    /** Every instance's theme, for the page (GET /ui/themes): only themes that set something. */
+    themes(): Record<string, Theme>;
+    /** The instances a person locked (the page's chat menu says Unlock for them). */
+    lockedNames(): string[];
+    /**
+     * Replace an instance's theme (already checked, web-theme.ts). An asset the old theme named and the new one no
+     * longer does is deleted once the change is on disk (first design §4); one uploaded but not named yet stays.
+     */
+    setTheme(name: string, theme: Theme, by: AppearanceActor): StoreWrite<{
+        theme: Theme;
+    }>;
+    /**
+     * A picture for the theme or its card: magic bytes, size and dimensions for its slot (the limits in force now),
+     * metadata stripped, the instance's quota. An asset is its kept bytes and holds one slot: the same picture uploaded
+     * again for that slot is the same id; for another slot, 409 (a card names only its own slot's pictures).
+     */
+    addAsset(name: string, slot: unknown, bytes: Uint8Array): StoreWrite<{
+        id: string;
+    }>;
+    private unlinkAssets;
+    asset(name: string, id: string): {
+        bytes: Buffer;
+        mime: string;
+    } | null;
+    /**
+     * Reset. The agent's own (reset_web_theme): its theme only. A person's: the theme, its placements and assets — the
+     * lock stays (a reset is not an unlock).
+     */
+    reset(name: string, by: AppearanceActor): StoreWrite;
+    /** A person's lock (r2 (a)): agents' writes are refused while it is on. */
+    setLocked(name: string, locked: boolean): StoreWrite;
+    /**
+     * Where effects are placed (B2's apply/remove tools, a person's choices). Each entry is either an id — a placement
+     * kept as it is (its `by`, `at` and params; a new id is placed plainly) — or `{ id, params? }`, an explicit apply that
+     * always takes this call's `by` and `at` and its params (the effect's non-default overrides, already resolved), even
+     * for an id already placed: so an agent re-applying a person's placement never keeps `by: "human"`. `validate` is
+     * the caller's synchronous check of each (kind, scope, params), run before anything is written. Widgets have their
+     * own calls below.
+     */
+    setPlacements(name: string, patch: {
+        effects?: Array<string | {
+            id: string;
+            params?: Record<string, unknown>;
+        }>;
+    }, by: AppearanceActor, validate: (what: {
+        kind: "effect";
+        id: string;
+        params?: Record<string, unknown>;
+    }) => string | null): StoreWrite<{
+        placements: Placements;
+    }>;
+    /**
+     * r4-4: place a widget (a spec and its data, both already checked — web-widget.ts) in one of the instance's own
+     * slots, or replace it. `by` is who placed it; the same spec placed again keeps its first placement's `by` and `at`.
+     */
+    setWidget(name: string, slot: AgentWidgetSlot, spec: WidgetSpec, data: WidgetData, by: AppearanceActor): StoreWrite<{
+        widget: WidgetPlacement;
+    }>;
+    /** r4-4: a placed widget's new data (checked against its spec by the caller); who placed it stays. */
+    setWidgetData(name: string, slot: AgentWidgetSlot, data: WidgetData, by: AppearanceActor): StoreWrite<{
+        widget: WidgetPlacement;
+    }>;
+    /** r4-4: take widgets out of these slots (those placed nowhere are skipped); one write. */
+    removeWidgets(name: string, slots: readonly AgentWidgetSlot[], by: AppearanceActor): StoreWrite<{
+        removed: AgentWidgetSlot[];
+    }>;
+    /**
+     * #2117: place an ambient (already checked — web-ambient.ts — its glyph pictures this instance's own) where its preset
+     * goes (one looping, one click), or replace the one there. The same spec placed again keeps its first `by` and `at`.
+     * Glyph pictures the replaced ambient named and no ambient names now are deleted once the write is on disk.
+     */
+    setAmbient(name: string, spec: AmbientSpec, by: AppearanceActor): StoreWrite<{
+        ambient: AmbientPlacement;
+        kind: AmbientKind;
+    }>;
+    /** #2117: take ambients out (those placed nowhere are skipped); one write; their unused glyph pictures go. */
+    clearAmbient(name: string, kinds: readonly AmbientKind[], by: AppearanceActor): StoreWrite<{
+        removed: AmbientKind[];
+    }>;
+    /** The record's assets once `placements` replace its own: glyph pictures the old ambients named and the new ones don't go. */
+    private glyphsAfter;
+    /** Every instance's ambients, for the page (GET /ui/themes): `{ <name>: { loop?: { spec, by }, click?: { spec, by } } }`. */
+    ambients(): Record<string, Partial<Record<AmbientKind, {
+        spec: AmbientSpec;
+        by: AppearanceActor;
+    }>>>;
+    /**
+     * Every instance's placed effects (B2's reference source for the effect library: an effect placed on an instance is
+     * in use, holder "instance:<name>"). Empty when the file can't be read.
+     */
+    placedEffects(): Array<{
+        name: string;
+        ids: string[];
+    }>;
+    /** Every instance's placed widgets, for the page (GET /ui/themes): `{ <name>: { <slot>: { spec, data, by } } }`. */
+    widgets(): Record<string, Partial<Record<AgentWidgetSlot, {
+        spec: WidgetSpec;
+        data: WidgetData;
+        by: AppearanceActor;
+    }>>>;
+    /**
+     * r4-5: a mod's look applied to one instance by a person, in ONE record write: its pictures (checked and stripped
+     * already — web-mod-bundle.ts), the theme (replacing the look; the card's pictures stay), the identity's tagline and
+     * bio (the card's agent-side text, which a person's own card fields still win over), widgets, and effect placements.
+     * New picture files are written first; pictures the old look named and the new one does not are deleted only by
+     * `finalize()`, once the whole import has succeeded — so `undo()` always puts back a complete record.
+     */
+    applyLook(name: string, look: {
+        theme?: Theme;
+        identity?: {
+            tagline?: string;
+            bio?: string;
+        };
+        pictures: Array<{
+            slot: ThemeAssetSlot;
+            id: string;
+            kind: MediaKind;
+            kept: Uint8Array;
+        }>;
+        widgets?: Partial<Record<AgentWidgetSlot, {
+            spec: WidgetSpec;
+            data: WidgetData;
+        }>>;
+        effects?: Array<{
+            id: string;
+            params: Record<string, unknown>;
+        }>;
+        /** #2117: replaces the instance's ambients (a mod's look carries both kinds or none). */
+        ambient?: Partial<Record<AmbientKind, AmbientSpec>>;
+    }, by: AppearanceActor): StoreWrite<{
+        finalize: () => void;
+        undo: () => StoreWrite;
+    }>;
+    /** An instance was removed: its record and its pictures go. */
+    forget(name: string): void;
+}