@pixerate/editor 0.262.0 → 0.263.0

package/dist/stickers/index.js

@@ -3,7 +3,7 @@ import {
   editorStickers,
   stampOutline,
   stampPixels
-} from "../chunk-F7CPSRLN.js";
+} from "../chunk-DOZ6F2K2.js";
 import {
   createInsertStickerTool,
   createStickerToolProvider,
@@ -11,23 +11,28 @@ import {
   describeStickerRef,
   insertSticker,
   stickerForAgent
-} from "../chunk-J5UQHWVL.js";
+} from "../chunk-6JL2D5SG.js";
 import {
   DEFAULT_STICKER_PAGE,
   EDITOR_STICKERS_ID,
   MAX_STICKER_PAGE,
   STAMP_KINDS,
+  STICKER_VARIANTS,
   StickersSlot,
   checkStickerSearchOptions,
+  checkStickerVariant,
   closestStickerRefs,
   editorStampOf,
   normalizeStickerRef,
   parseStickerRef,
   stampCoverage,
+  stickerCollections,
   stickerIdFor,
   stickerPage,
-  stickerRefOf
-} from "../chunk-APX63ILU.js";
+  stickerRefOf,
+  stickerVariantFor,
+  stickerVariantsOf
+} from "../chunk-ACFSFUQH.js";
 import {
   StickerError
 } from "../chunk-SZTI6EER.js";
@@ -39,11 +44,17 @@ import "../chunk-QGHEDC7B.js";
 
 // src/stickers/fake.ts
 var CATALOGUE = [
-  ...["sun", "moon", "cloud", "rain", "snow", "wind"].map((w, i) => ({ id: `weather-${w}`, name: w[0].toUpperCase() + w.slice(1), category: "weather", tags: ["weather", w], shape: "badge", colours: [["#f59e0b", "#64748b", "#94a3b8", "#2563eb", "#e0f2fe", "#14b8a6"][i], "#ffffff"], commercial: true })),
-  ...["apple", "pear", "cherry", "lemon", "grape"].map((f, i) => ({ id: `fruit-${f}`, name: f[0].toUpperCase() + f.slice(1), category: "food", tags: ["fruit", f], shape: "tile", colours: [["#dc2626", "#84cc16", "#be123c", "#facc15", "#7c3aed"][i], "#166534"], commercial: true })),
-  ...["new", "sale", "hot", "free"].map((b, i) => ({ id: `badge-${b}`, name: `${b[0].toUpperCase() + b.slice(1)} badge`, category: "badges", tags: ["badge", "label", b], shape: "badge", colours: [["#16a34a", "#dc2626", "#ea580c", "#0891b2"][i], "#ffffff"], commercial: true })),
+  ...["sun", "moon", "cloud", "rain", "snow", "wind"].map((w, i) => ({ id: `weather-${w}`, name: w[0].toUpperCase() + w.slice(1), category: "weather", tags: ["weather", w], shape: "badge", colours: [["#f59e0b", "#64748b", "#94a3b8", "#2563eb", "#e0f2fe", "#14b8a6"][i], "#ffffff"], commercial: true, collection: "outdoors", aiGenerated: true })),
+  ...["apple", "pear", "cherry", "lemon", "grape"].map((f, i) => ({ id: `fruit-${f}`, name: f[0].toUpperCase() + f.slice(1), category: "food", tags: ["fruit", f], shape: "tile", colours: [["#dc2626", "#84cc16", "#be123c", "#facc15", "#7c3aed"][i], "#166534"], commercial: true, collection: "kitchen" })),
+  ...["new", "sale", "hot", "free"].map((b, i) => ({ id: `badge-${b}`, name: `${b[0].toUpperCase() + b.slice(1)} badge`, category: "badges", tags: ["badge", "label", b], shape: "badge", colours: [["#16a34a", "#dc2626", "#ea580c", "#0891b2"][i], "#ffffff"], commercial: true, collection: "shop" })),
   { id: "art-sketch", name: "Sketch", category: "art", tags: ["drawing", "non-commercial"], shape: "tile", colours: ["#1f2937", "#fde68a"], commercial: false }
 ];
+var COLLECTIONS = {
+  outdoors: { name: "Outdoors", description: "Weather, AI-generated." },
+  kitchen: { name: "Kitchen", description: "Fruit tiles with dark variants." },
+  shop: { name: "Shop", description: "Tintable sale badges." }
+};
+var DARK_TOP = "#f8fafc";
 var W = 120;
 var H = 120;
 function summaryOf(s) {
@@ -57,16 +68,22 @@ function summaryOf(s) {
     height: H,
     formats: ["svg", "png"],
     licence: s.commercial ? { spdx: "CC0-1.0", name: "CC0 1.0", commercial: true } : { spdx: "CC-BY-NC-4.0", name: "CC BY-NC 4.0", attribution: "Fake Artist", commercial: false },
-    tintable: s.shape === "badge"
+    tintable: s.shape === "badge",
+    ...s.shape === "tile" ? { variants: ["light", "dark"] } : {},
+    ...s.collection ? { collection: s.collection } : {},
+    ...s.aiGenerated ? { aiGenerated: true } : {}
   };
 }
-function svgOf(s, fill) {
+var tileColours = (s, variant) => variant === "dark" ? [s.colours[0], DARK_TOP] : s.colours;
+function svgOf(s, fill, variant) {
   if (s.shape === "badge") {
     return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}"><path fill="${fill}" fill-rule="evenodd" d="M60 6A54 54 0 1 1 59.9 6ZM45 45H75V75H45Z"/></svg>`;
   }
-  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}"><rect x="10" y="10" width="100" height="100" fill="${s.colours[0]}"/><rect x="10" y="10" width="100" height="50" fill="${s.colours[1]}"/></svg>`;
+  const [bottom, top] = tileColours(s, variant);
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}"><rect x="10" y="10" width="100" height="100" fill="${bottom}"/><rect x="10" y="10" width="100" height="50" fill="${top}"/></svg>`;
 }
-function pixelsOf(s, size, fill) {
+function pixelsOf(s, size, fill, variant) {
+  const [bottom, top] = tileColours(s, variant);
   const out = new Uint8ClampedArray(size * size * 4);
   const hex = (c) => [parseInt(c.slice(1, 3), 16), parseInt(c.slice(3, 5), 16), parseInt(c.slice(5, 7), 16)];
   for (let y = 0; y < size; y++) {
@@ -78,7 +95,7 @@ function pixelsOf(s, size, fill) {
         const inDisc = Math.hypot(u - 60, v - 60) <= 54;
         const inNotch = u >= 45 && u <= 75 && v >= 45 && v <= 75;
         if (inDisc && !inNotch) rgb = hex(fill);
-      } else if (u >= 10 && u <= 110 && v >= 10 && v <= 110) rgb = hex(v < 60 ? s.colours[1] : s.colours[0]);
+      } else if (u >= 10 && u <= 110 && v >= 10 && v <= 110) rgb = hex(v < 60 ? top : bottom);
       if (!rgb) continue;
       const i = (y * size + x) * 4;
       out[i] = rgb[0];
@@ -104,19 +121,21 @@ function createFakeStickerProvider(options = {}) {
       if (!s) return void 0;
       return { ...summaryOf(s), silhouette: s.shape === "badge" ? "M60 6A54 54 0 1 1 59.9 6Z" : "M10 10H110V110H10Z", colours: s.shape === "badge" ? [s.colours[0]] : [...s.colours] };
     },
+    listCollections: () => stickerCollections(summaries, COLLECTIONS),
     categories: () => [...new Set(CATALOGUE.map((s) => s.category))].map((c) => ({ id: c, name: c, count: CATALOGUE.filter((s) => s.category === c).length })),
     async load(id, o = {}) {
       if (options.loadDelayMs) await new Promise((r) => setTimeout(r, options.loadDelayMs));
       const s = find(id);
       if (!s) throw new StickerError("unknown_sticker", `No fake sticker "${id}".`);
       if (options.failIds?.includes(id)) throw new StickerError("load_failed", `The fake sticker "${id}" failed to load (failIds).`);
+      const variant = checkStickerVariant(summaryOf(s), o.variant);
       const fill = s.shape === "badge" && o.colour ? o.colour.toLowerCase() : s.colours[0];
       if (o.format === "png") {
         const size = o.size ?? 128;
         if (!(Number.isInteger(size) && size >= 8 && size <= 512)) throw new StickerError("invalid_argument", `size must be 8..512 px, got ${size}.`);
-        return { kind: "image", url: pngDataUrl(size, size, pixelsOf(s, size, fill)), width: size, height: size };
+        return { kind: "image", url: pngDataUrl(size, size, pixelsOf(s, size, fill, variant)), width: size, height: size };
       }
-      return { kind: "svg", svg: svgOf(s, fill) };
+      return { kind: "svg", svg: svgOf(s, fill, variant) };
     }
   };
 }
@@ -133,10 +152,18 @@ function combineStickerProviders(providers, options = {}) {
     if (!p) throw new StickerError("unknown_provider", `No sticker provider "${provider}"; the providers are ${ids.join(", ") || "none"}.`);
     return { p, id };
   };
-  const prefix = (p, s) => ({ ...s, id: stickerRefOf(p, s.id) });
+  const collectionOf = (p, c) => p.namespaced ? c : `${p.id}:${c}`;
+  const prefix = (p, s) => ({ ...s, id: stickerRefOf(p, s.id), ...s.collection ? { collection: collectionOf(p, s.collection) } : {} });
+  const collectionOwner = (c) => {
+    const i = c.indexOf(":");
+    const p = i > 0 ? byId.get(c.slice(0, i)) : void 0;
+    if (!p) throw new StickerError("invalid_argument", `No collection "${c}"; collections here are "provider:collection" (listCollections lists them).`);
+    return { p, collection: p.namespaced ? c : c.slice(i + 1) };
+  };
   const page = async (query, o = {}) => {
-    const { after, limit = DEFAULT_STICKER_PAGE, ...filters } = o;
+    const { after, limit = DEFAULT_STICKER_PAGE, collection, ...filters } = o;
     checkStickerSearchOptions({ limit });
+    const only = collection !== void 0 ? collectionOwner(collection) : null;
     let i = 0;
     let inner;
     if (after !== void 0) {
@@ -145,7 +172,11 @@ function combineStickerProviders(providers, options = {}) {
       i = Number(m[1]);
       inner = m[2] || void 0;
     }
-    const get = (p, opts) => query === null ? p.list(opts) : p.search(query, opts);
+    const get = async (p, opts) => {
+      if (only && only.p !== p) return { items: [], total: 0 };
+      const withCollection = only ? { ...opts, collection: only.collection } : opts;
+      return query === null ? p.list(withCollection) : p.search(query, withCollection);
+    };
     let total = 0;
     for (const p of providers) total += (await get(p, { ...filters, limit: 1 })).total;
     const items = [];
@@ -185,7 +216,7 @@ function combineStickerProviders(providers, options = {}) {
         return void 0;
       }
       const d = await o.p.describe(o.id);
-      return d ? { ...d, id: stickerRefOf(o.p, d.id) } : void 0;
+      return d ? prefix(o.p, d) : void 0;
     },
     async load(ref, o) {
       const { p, id } = owner(ref);
@@ -200,6 +231,11 @@ function combineStickerProviders(providers, options = {}) {
         }
       }
       return [...counts.values()];
+    },
+    async listCollections() {
+      const out = [];
+      for (const p of providers) for (const c of await p.listCollections?.() ?? []) out.push({ ...c, id: collectionOf(p, c.id) });
+      return out;
     }
   };
 }
@@ -220,6 +256,14 @@ function checkSummary(s, provider, issues) {
   if (typeof s.licence?.commercial !== "boolean") at("licence.commercial is not a boolean");
   if (typeof s.tintable !== "boolean") at("tintable is not a boolean");
   if (s.thumbnail !== void 0 && !/^(data:|https:)/.test(s.thumbnail)) at("thumbnail must be a data: or https: URL");
+  if (s.aiGenerated !== void 0 && typeof s.aiGenerated !== "boolean") at("aiGenerated must be a boolean when present");
+  if (s.variants !== void 0) {
+    const v = s.variants;
+    if (!Array.isArray(v) || v.some((x) => x !== "light" && x !== "dark") || new Set(v).size !== v.length) at("variants must list light and / or dark, each once");
+    else if (!v.includes("light")) at("variants must include light (every sticker has its light art)");
+  }
+  if (s.collection !== void 0 && (typeof s.collection !== "string" || !s.collection)) at("collection must be a non-empty string when present");
+  if (s.collection !== void 0 && !provider.listCollections) at(`is in collection "${s.collection}" but the provider has no listCollections()`);
 }
 async function checkStickerProvider(provider, options = {}) {
   const issues = [];
@@ -278,6 +322,26 @@ async function checkStickerProvider(provider, options = {}) {
     if (d?.colours?.some((c) => !HEX.test(c))) top(`describe("${first.id}").colours must be #rrggbb`);
   }
   if (await provider.describe("__no_such_sticker__") !== void 0) top("describe of an unknown id returned a sticker");
+  if (provider.listCollections) {
+    try {
+      const collections = await provider.listCollections();
+      const known = /* @__PURE__ */ new Set();
+      for (const c of collections) {
+        if (typeof c?.id !== "string" || !c.id || typeof c.name !== "string" || !c.name || !(Number.isInteger(c.count) && c.count >= 0)) {
+          top(`listCollections() returned ${JSON.stringify(c)}; each needs id, name and a count`);
+          continue;
+        }
+        if (known.has(c.id)) top(`listCollections() lists "${c.id}" twice`);
+        known.add(c.id);
+        const page = await provider.list({ collection: c.id, limit: 100 });
+        if (page.total !== c.count) top(`collection "${c.id}" says count ${c.count} but list({ collection }) has ${page.total}`);
+        if (page.items.some((x) => x.collection !== c.id)) top(`list({ collection: "${c.id}" }) returned stickers of other collections`);
+      }
+      for (const x of all) if (x.collection !== void 0 && !known.has(x.collection)) issues.push({ stickerId: x.id, message: `collection "${x.collection}" is not in listCollections()` });
+    } catch (e) {
+      top(`listCollections() rejected: ${e.message}`);
+    }
+  }
   let rejected = false;
   try {
     await provider.load("__no_such_sticker__");
@@ -296,6 +360,24 @@ async function checkStickerProvider(provider, options = {}) {
       }
     }
   }
+  const dark = all.find((s) => s.variants?.includes("dark"));
+  if (dark) {
+    try {
+      await provider.load(dark.id, { format: dark.formats[0], variant: "dark", size: 32 });
+    } catch (e) {
+      issues.push({ stickerId: dark.id, message: `load({ variant: "dark" }) rejected for a sticker that lists it: ${e.message}` });
+    }
+  }
+  const lightOnly = all.find((s) => !s.variants?.includes("dark"));
+  if (lightOnly) {
+    let refused = false;
+    try {
+      await provider.load(lightOnly.id, { format: lightOnly.formats[0], variant: "dark", size: 32 });
+    } catch {
+      refused = true;
+    }
+    if (!refused) issues.push({ stickerId: lightOnly.id, message: 'load({ variant: "dark" }) did not reject for a sticker without a dark variant (checkStickerVariant does it)' });
+  }
   const tintable = all.find((s) => s.tintable);
   if (tintable) {
     try {
@@ -312,11 +394,13 @@ export {
   EDITOR_STICKERS_ID,
   MAX_STICKER_PAGE,
   STAMP_KINDS,
+  STICKER_VARIANTS,
   StickerBrowser,
   StickerError,
   StickersSlot,
   checkStickerProvider,
   checkStickerSearchOptions,
+  checkStickerVariant,
   closestStickerRefs,
   combineStickerProviders,
   createFakeStickerProvider,
@@ -332,8 +416,11 @@ export {
   stampCoverage,
   stampOutline,
   stampPixels,
+  stickerCollections,
   stickerForAgent,
   stickerIdFor,
   stickerPage,
-  stickerRefOf
+  stickerRefOf,
+  stickerVariantFor,
+  stickerVariantsOf
 };

package/dist/stickers/tools.d.cts

@@ -4,7 +4,7 @@
  * stickers. Refusals name the valid choices.
  */
 import type { AgentTool, AgentToolProvider } from '../tools/registry.cjs';
-import type { MaybePromise, StickerAsset, StickerDescription, StickerFormat, StickerProvider, StickerRef, StickerSummary } from './types.cjs';
+import { type MaybePromise, type StickerAsset, type StickerDescription, type StickerFormat, type StickerProvider, type StickerRef, type StickerSummary, type StickerVariant } from './types.cjs';
 /** Where and how big an inserted sticker goes, with its art. */
 export interface StickerPlacement {
     ref: StickerRef;
@@ -18,6 +18,8 @@ export interface StickerPlacement {
     height: number;
     /** #rrggbb it was tinted to, when tintable and asked for. */
     colour?: string;
+    /** The variant its art is (`dark` for a dark background, when the sticker has it). */
+    variant: StickerVariant;
 }
 /**
  * An editor that can take an inserted sticker (`insert_sticker`): the vector editor (editable
@@ -33,6 +35,8 @@ export interface StickerInsertHost {
         x: number;
         y: number;
     };
+    /** The background is dark (a dark canvas or theme): stickers with a dark variant use it unless the call names one. */
+    dark?(): boolean;
     /** Adds the sticker as one undo step; returns what it made (its id at least) for later tools. */
     insert(placement: StickerPlacement): MaybePromise<{
         id: string;
@@ -57,7 +61,8 @@ export declare function createStickerTools(options: StickerToolsOptions): AgentT
  * Puts one sticker into an editor through its host (the panels and `insert_sticker` both use it):
  * checks the ref, loads the art in the host's format, tinted when asked and tintable, and places
  * it centred at (`x`, `y`) (default the host's centre), `width` wide (default its natural width).
- * Returns what the host made, the ref, the size and the licence.
+ * The art is the `variant` asked for, else the dark one when the host's background is dark and
+ * the sticker has it. Returns what the host made, the ref, the size, the variant and the licence.
  */
 export declare function insertSticker(provider: StickerProvider, host: StickerInsertHost, options: {
     ref: StickerRef;
@@ -65,11 +70,13 @@ export declare function insertSticker(provider: StickerProvider, host: StickerIn
     y?: number;
     width?: number;
     color?: string;
+    variant?: StickerVariant;
 }): Promise<{
     id: string;
     ref: StickerRef;
     width: number;
     height: number;
+    variant: StickerVariant;
     licence: StickerDescription['licence'];
 } & Record<string, unknown>>;
 /** `insert_sticker`: one sticker by ref into an editor, at a place and size, as one undo step. */

package/dist/stickers/tools.d.ts

@@ -4,7 +4,7 @@
  * stickers. Refusals name the valid choices.
  */
 import type { AgentTool, AgentToolProvider } from '../tools/registry.js';
-import type { MaybePromise, StickerAsset, StickerDescription, StickerFormat, StickerProvider, StickerRef, StickerSummary } from './types.js';
+import { type MaybePromise, type StickerAsset, type StickerDescription, type StickerFormat, type StickerProvider, type StickerRef, type StickerSummary, type StickerVariant } from './types.js';
 /** Where and how big an inserted sticker goes, with its art. */
 export interface StickerPlacement {
     ref: StickerRef;
@@ -18,6 +18,8 @@ export interface StickerPlacement {
     height: number;
     /** #rrggbb it was tinted to, when tintable and asked for. */
     colour?: string;
+    /** The variant its art is (`dark` for a dark background, when the sticker has it). */
+    variant: StickerVariant;
 }
 /**
  * An editor that can take an inserted sticker (`insert_sticker`): the vector editor (editable
@@ -33,6 +35,8 @@ export interface StickerInsertHost {
         x: number;
         y: number;
     };
+    /** The background is dark (a dark canvas or theme): stickers with a dark variant use it unless the call names one. */
+    dark?(): boolean;
     /** Adds the sticker as one undo step; returns what it made (its id at least) for later tools. */
     insert(placement: StickerPlacement): MaybePromise<{
         id: string;
@@ -57,7 +61,8 @@ export declare function createStickerTools(options: StickerToolsOptions): AgentT
  * Puts one sticker into an editor through its host (the panels and `insert_sticker` both use it):
  * checks the ref, loads the art in the host's format, tinted when asked and tintable, and places
  * it centred at (`x`, `y`) (default the host's centre), `width` wide (default its natural width).
- * Returns what the host made, the ref, the size and the licence.
+ * The art is the `variant` asked for, else the dark one when the host's background is dark and
+ * the sticker has it. Returns what the host made, the ref, the size, the variant and the licence.
  */
 export declare function insertSticker(provider: StickerProvider, host: StickerInsertHost, options: {
     ref: StickerRef;
@@ -65,11 +70,13 @@ export declare function insertSticker(provider: StickerProvider, host: StickerIn
     y?: number;
     width?: number;
     color?: string;
+    variant?: StickerVariant;
 }): Promise<{
     id: string;
     ref: StickerRef;
     width: number;
     height: number;
+    variant: StickerVariant;
     licence: StickerDescription['licence'];
 } & Record<string, unknown>>;
 /** `insert_sticker`: one sticker by ref into an editor, at a place and size, as one undo step. */

package/dist/stickers/types.d.cts

@@ -20,6 +20,22 @@ export interface StickerLicence {
     commercial: boolean;
 }
 export type StickerFormat = 'svg' | 'png';
+/**
+ * A version of a sticker drawn for a light or a dark background: the same subject, pose and size.
+ * `light` is the default art every sticker has.
+ */
+export type StickerVariant = 'light' | 'dark';
+/** The variants there are, in order. */
+export declare const STICKER_VARIANTS: readonly StickerVariant[];
+/** A themed set of stickers within one provider (one per brand, say). */
+export interface StickerCollection {
+    /** Unique within the provider; what `StickerSummary.collection` and `StickerSearchOptions.collection` name. */
+    id: string;
+    name: string;
+    description?: string;
+    /** How many stickers it holds. */
+    count: number;
+}
 /** A sticker in a list or search result. */
 export interface StickerSummary {
     /** The provider's id (no `:` needed; `combineStickerProviders` prefixes its own). */
@@ -38,6 +54,15 @@ export interface StickerSummary {
     licence: StickerLicence;
     /** Flat, single-colour art: `load(id, { colour })` recolours it (the paint editor's spray colours it). */
     tintable: boolean;
+    /** The art was made by an AI model (absent: not said), so pickers and agents can label it. */
+    aiGenerated?: boolean;
+    /**
+     * The variants `load(id, { variant })` returns, always with `light` (absent: only `light`), so a
+     * picker or brush can pick the dark one for a dark background without calling `describe` first.
+     */
+    variants?: StickerVariant[];
+    /** The collection it belongs to (`listCollections`), when the provider groups its stickers. */
+    collection?: string;
 }
 /** Everything about one sticker. */
 export interface StickerDescription extends StickerSummary {
@@ -45,10 +70,6 @@ export interface StickerDescription extends StickerSummary {
     silhouette?: string;
     /** Dominant colours #rrggbb, for matching and recolouring. */
     colours?: string[];
-    variants?: {
-        id: string;
-        name: string;
-    }[];
 }
 /** A sticker's art. */
 export type StickerAsset = {
@@ -72,6 +93,8 @@ export interface StickerPage {
 }
 export interface StickerSearchOptions {
     category?: string;
+    /** Only stickers of this collection (`listCollections`). */
+    collection?: string;
     /** Every tag must match. */
     tags?: string[];
     /** Page size (providers cap it; 1..100, default 24). */
@@ -88,6 +111,8 @@ export interface StickerLoadOptions {
     size?: number;
     /** #rrggbb: recolour a tintable sticker. */
     colour?: string;
+    /** The art for a light (default) or dark background; one the sticker doesn't list is refused, naming the ones it has. */
+    variant?: StickerVariant;
 }
 export interface StickerProviderCapabilities {
     supportsSearch: boolean;
@@ -110,7 +135,7 @@ export interface StickerProvider {
     search(query: string, options?: StickerSearchOptions): MaybePromise<StickerPage>;
     /** A sticker by id, or `undefined`. */
     describe(id: string): MaybePromise<StickerDescription | undefined>;
-    /** The art; rejects with a `StickerError` (`unknown_sticker`, `unsupported_format`) when it can't. */
+    /** The art; rejects with a `StickerError` (`unknown_sticker`, `unsupported_format`, `unsupported_variant`) when it can't. */
     load(id: string, options?: StickerLoadOptions): MaybePromise<StickerAsset>;
     /** Categories with counts, when the provider knows them. */
     categories?(): MaybePromise<Array<{
@@ -118,6 +143,8 @@ export interface StickerProvider {
         name: string;
         count: number;
     }>>;
+    /** Its collections with counts, when it groups its stickers. Ids stay unique across collections, so `load(id)` needs none. */
+    listCollections?(): MaybePromise<StickerCollection[]>;
 }
 /** `provider:id`, the name of a sticker across providers. A bare editor stamp (`"star"`) means `editor:star`. */
 export type StickerRef = string;

package/dist/stickers/types.d.ts

@@ -20,6 +20,22 @@ export interface StickerLicence {
     commercial: boolean;
 }
 export type StickerFormat = 'svg' | 'png';
+/**
+ * A version of a sticker drawn for a light or a dark background: the same subject, pose and size.
+ * `light` is the default art every sticker has.
+ */
+export type StickerVariant = 'light' | 'dark';
+/** The variants there are, in order. */
+export declare const STICKER_VARIANTS: readonly StickerVariant[];
+/** A themed set of stickers within one provider (one per brand, say). */
+export interface StickerCollection {
+    /** Unique within the provider; what `StickerSummary.collection` and `StickerSearchOptions.collection` name. */
+    id: string;
+    name: string;
+    description?: string;
+    /** How many stickers it holds. */
+    count: number;
+}
 /** A sticker in a list or search result. */
 export interface StickerSummary {
     /** The provider's id (no `:` needed; `combineStickerProviders` prefixes its own). */
@@ -38,6 +54,15 @@ export interface StickerSummary {
     licence: StickerLicence;
     /** Flat, single-colour art: `load(id, { colour })` recolours it (the paint editor's spray colours it). */
     tintable: boolean;
+    /** The art was made by an AI model (absent: not said), so pickers and agents can label it. */
+    aiGenerated?: boolean;
+    /**
+     * The variants `load(id, { variant })` returns, always with `light` (absent: only `light`), so a
+     * picker or brush can pick the dark one for a dark background without calling `describe` first.
+     */
+    variants?: StickerVariant[];
+    /** The collection it belongs to (`listCollections`), when the provider groups its stickers. */
+    collection?: string;
 }
 /** Everything about one sticker. */
 export interface StickerDescription extends StickerSummary {
@@ -45,10 +70,6 @@ export interface StickerDescription extends StickerSummary {
     silhouette?: string;
     /** Dominant colours #rrggbb, for matching and recolouring. */
     colours?: string[];
-    variants?: {
-        id: string;
-        name: string;
-    }[];
 }
 /** A sticker's art. */
 export type StickerAsset = {
@@ -72,6 +93,8 @@ export interface StickerPage {
 }
 export interface StickerSearchOptions {
     category?: string;
+    /** Only stickers of this collection (`listCollections`). */
+    collection?: string;
     /** Every tag must match. */
     tags?: string[];
     /** Page size (providers cap it; 1..100, default 24). */
@@ -88,6 +111,8 @@ export interface StickerLoadOptions {
     size?: number;
     /** #rrggbb: recolour a tintable sticker. */
     colour?: string;
+    /** The art for a light (default) or dark background; one the sticker doesn't list is refused, naming the ones it has. */
+    variant?: StickerVariant;
 }
 export interface StickerProviderCapabilities {
     supportsSearch: boolean;
@@ -110,7 +135,7 @@ export interface StickerProvider {
     search(query: string, options?: StickerSearchOptions): MaybePromise<StickerPage>;
     /** A sticker by id, or `undefined`. */
     describe(id: string): MaybePromise<StickerDescription | undefined>;
-    /** The art; rejects with a `StickerError` (`unknown_sticker`, `unsupported_format`) when it can't. */
+    /** The art; rejects with a `StickerError` (`unknown_sticker`, `unsupported_format`, `unsupported_variant`) when it can't. */
     load(id: string, options?: StickerLoadOptions): MaybePromise<StickerAsset>;
     /** Categories with counts, when the provider knows them. */
     categories?(): MaybePromise<Array<{
@@ -118,6 +143,8 @@ export interface StickerProvider {
         name: string;
         count: number;
     }>>;
+    /** Its collections with counts, when it groups its stickers. Ids stay unique across collections, so `load(id)` needs none. */
+    listCollections?(): MaybePromise<StickerCollection[]>;
 }
 /** `provider:id`, the name of a sticker across providers. A bare editor stamp (`"star"`) means `editor:star`. */
 export type StickerRef = string;