@pixerate/editor 0.246.0 → 0.249.0

package/dist/stickers/index.js

@@ -0,0 +1,331 @@
+import {
+  StickerBrowser,
+  editorStickers,
+  stampOutline,
+  stampPixels
+} from "../chunk-EJLRBS5Q.js";
+import {
+  DEFAULT_STICKER_PAGE,
+  EDITOR_STICKERS_ID,
+  MAX_STICKER_PAGE,
+  STAMP_KINDS,
+  StickerError,
+  StickersSlot,
+  checkStickerSearchOptions,
+  closestStickerRefs,
+  createStickerToolProvider,
+  createStickerTools,
+  describeStickerRef,
+  editorStampOf,
+  normalizeStickerRef,
+  parseStickerRef,
+  stampCoverage,
+  stickerForAgent,
+  stickerIdFor,
+  stickerPage,
+  stickerRefOf
+} from "../chunk-5RH3VXAK.js";
+import "../chunk-4D6KP5BV.js";
+import {
+  pngDataUrl
+} from "../chunk-OTTT5N3K.js";
+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 })),
+  { id: "art-sketch", name: "Sketch", category: "art", tags: ["drawing", "non-commercial"], shape: "tile", colours: ["#1f2937", "#fde68a"], commercial: false }
+];
+var W = 120;
+var H = 120;
+function summaryOf(s) {
+  return {
+    id: s.id,
+    name: s.name,
+    category: s.category,
+    tags: s.tags,
+    description: s.shape === "badge" ? "A flat badge (tintable)." : "A two-colour tile.",
+    width: W,
+    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"
+  };
+}
+function svgOf(s, fill) {
+  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>`;
+}
+function pixelsOf(s, size, fill) {
+  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++) {
+    for (let x = 0; x < size; x++) {
+      const u = (x + 0.5) / size * W;
+      const v = (y + 0.5) / size * H;
+      let rgb = null;
+      if (s.shape === "badge") {
+        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]);
+      if (!rgb) continue;
+      const i = (y * size + x) * 4;
+      out[i] = rgb[0];
+      out[i + 1] = rgb[1];
+      out[i + 2] = rgb[2];
+      out[i + 3] = 255;
+    }
+  }
+  return out;
+}
+function createFakeStickerProvider(options = {}) {
+  const summaries = CATALOGUE.map(summaryOf);
+  const find = (id) => CATALOGUE.find((s) => s.id === id);
+  return {
+    id: options.id ?? "fake",
+    name: "Fake stickers",
+    version: "1",
+    capabilities: { supportsSearch: true, supportsSvg: true, supportsRaster: true, maxSize: 512 },
+    list: (o) => stickerPage(summaries, o),
+    search: (q, o) => stickerPage(summaries, o, q),
+    describe(id) {
+      const s = find(id);
+      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] };
+    },
+    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 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: "svg", svg: svgOf(s, fill) };
+    }
+  };
+}
+
+// src/stickers/combine.ts
+function combineStickerProviders(providers, options = {}) {
+  const ids = providers.map((p) => p.id);
+  const dup = ids.find((id, i) => ids.indexOf(id) !== i);
+  if (dup) throw new StickerError("invalid_argument", `Two sticker providers have the id "${dup}"; give each a unique id.`);
+  const byId = new Map(providers.map((p) => [p.id, p]));
+  const owner = (ref) => {
+    const { provider, id } = parseStickerRef(ref);
+    const p = byId.get(provider);
+    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 page = async (query, o = {}) => {
+    const { after, limit = DEFAULT_STICKER_PAGE, ...filters } = o;
+    checkStickerSearchOptions({ limit });
+    let i = 0;
+    let inner;
+    if (after !== void 0) {
+      const m = /^(\d+)\|(.*)$/.exec(after);
+      if (!m || Number(m[1]) >= providers.length) throw new StickerError("invalid_argument", `after "${after}" is not a cursor from this provider; pass the next value of the previous page.`);
+      i = Number(m[1]);
+      inner = m[2] || void 0;
+    }
+    const get = (p, opts) => query === null ? p.list(opts) : p.search(query, opts);
+    let total = 0;
+    for (const p of providers) total += (await get(p, { ...filters, limit: 1 })).total;
+    const items = [];
+    let next;
+    while (i < providers.length && items.length < limit) {
+      const p = providers[i];
+      const res = await get(p, { ...filters, limit: limit - items.length, ...inner ? { after: inner } : {} });
+      items.push(...res.items.map((s) => prefix(p, s)));
+      if (res.next && res.items.length) {
+        inner = res.next;
+        if (items.length >= limit) next = `${i}|${inner}`;
+        continue;
+      }
+      i++;
+      inner = void 0;
+    }
+    if (!next && items.length >= limit && i < providers.length) next = `${i}|`;
+    return { items, total, ...next ? { next } : {} };
+  };
+  return {
+    id: options.id ?? "stickers",
+    name: options.name ?? providers.map((p) => p.name).join(" + "),
+    namespaced: true,
+    capabilities: {
+      supportsSearch: providers.some((p) => p.capabilities.supportsSearch),
+      supportsSvg: providers.some((p) => p.capabilities.supportsSvg),
+      supportsRaster: providers.some((p) => p.capabilities.supportsRaster),
+      ...providers.every((p) => p.capabilities.maxSize) ? { maxSize: Math.max(...providers.map((p) => p.capabilities.maxSize)) } : {}
+    },
+    list: (o) => page(null, o),
+    search: (q, o) => page(q, o),
+    async describe(ref) {
+      let o;
+      try {
+        o = owner(ref);
+      } catch {
+        return void 0;
+      }
+      const d = await o.p.describe(o.id);
+      return d ? { ...d, id: stickerRefOf(o.p, d.id) } : void 0;
+    },
+    async load(ref, o) {
+      const { p, id } = owner(ref);
+      return p.load(id, o);
+    },
+    async categories() {
+      const counts = /* @__PURE__ */ new Map();
+      for (const p of providers) {
+        for (const c of await p.categories?.() ?? []) {
+          const had = counts.get(c.id);
+          counts.set(c.id, { id: c.id, name: had?.name ?? c.name, count: (had?.count ?? 0) + c.count });
+        }
+      }
+      return [...counts.values()];
+    }
+  };
+}
+
+// src/stickers/conformance.ts
+var HEX = /^#[0-9a-fA-F]{6}$/;
+function checkSummary(s, provider, issues) {
+  const at = (message) => issues.push({ stickerId: s.id, message });
+  if (typeof s.id !== "string" || !s.id) at("id is missing");
+  if (!provider.namespaced && s.id.includes(":")) at('id contains ":" (refs are provider:id; only a combined provider lists refs)');
+  if (typeof s.name !== "string" || !s.name) at("name is missing");
+  if (typeof s.category !== "string" || !s.category) at("category is missing");
+  if (!(s.width > 0 && s.height > 0)) at(`width and height must be positive, got ${s.width} \xD7 ${s.height}`);
+  if (!Array.isArray(s.formats) || !s.formats.length || s.formats.some((f) => f !== "svg" && f !== "png")) at("formats must list svg and / or png");
+  if (s.formats?.includes("svg") && !provider.capabilities.supportsSvg) at("lists svg but capabilities.supportsSvg is false");
+  if (s.formats?.includes("png") && !provider.capabilities.supportsRaster) at("lists png but capabilities.supportsRaster is false");
+  if (!s.licence || typeof s.licence.name !== "string" || !s.licence.name) at("licence.name is missing (every sticker says how it may be used)");
+  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");
+}
+async function checkStickerProvider(provider, options = {}) {
+  const issues = [];
+  const top = (message) => issues.push({ message });
+  if (typeof provider.id !== "string" || !provider.id) top("provider has no id");
+  else if (provider.id.includes(":")) top('provider id contains ":"');
+  if (typeof provider.name !== "string" || !provider.name) top("provider has no name");
+  const caps = provider.capabilities;
+  for (const k of ["supportsSearch", "supportsSvg", "supportsRaster"]) if (typeof caps?.[k] !== "boolean") top(`capabilities.${k} is not a boolean`);
+  if (caps?.maxSize !== void 0 && !(caps.maxSize > 0)) top("capabilities.maxSize must be positive");
+  const all = [];
+  const ids = /* @__PURE__ */ new Set();
+  let after;
+  let total = -1;
+  for (let n = 0; n < (options.maxPages ?? 50); n++) {
+    let page;
+    try {
+      page = await provider.list({ limit: 10, ...after ? { after } : {} });
+    } catch (e) {
+      top(`list() rejected: ${e.message}`);
+      break;
+    }
+    if (!Array.isArray(page?.items) || typeof page.total !== "number") {
+      top("list() did not return { items, total }");
+      break;
+    }
+    if (page.items.length > 10) top(`list({ limit: 10 }) returned ${page.items.length} stickers`);
+    if (total === -1) total = page.total;
+    for (const s of page.items) {
+      if (ids.has(s.id)) top(`duplicate id "${s.id}"`);
+      ids.add(s.id);
+      all.push(s);
+      checkSummary(s, provider, issues);
+    }
+    if (!page.next) break;
+    if (!page.items.length) {
+      top("list() returned an empty page with a next cursor");
+      break;
+    }
+    after = page.next;
+  }
+  if (total !== -1 && all.length !== total) top(`list() pages hold ${all.length} stickers but total says ${total}`);
+  try {
+    const found = await provider.search("", { limit: 1 });
+    if (found.total !== total) top(`search("") total ${found.total} differs from list() total ${total}`);
+  } catch (e) {
+    top(`search("") rejected: ${e.message}`);
+  }
+  const first = all[0];
+  if (first) {
+    const byCategory = await provider.list({ category: first.category, limit: 100 });
+    if (byCategory.items.some((s) => s.category !== first.category)) top(`list({ category: "${first.category}" }) returned stickers of other categories`);
+    const d = await provider.describe(first.id);
+    if (!d) top(`describe("${first.id}") returned nothing for a listed sticker`);
+    else if (d.id !== first.id) top(`describe("${first.id}") returned id "${d.id}"`);
+    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");
+  let rejected = false;
+  try {
+    await provider.load("__no_such_sticker__");
+  } catch {
+    rejected = true;
+  }
+  if (!rejected) top("load of an unknown id did not reject");
+  for (const s of all.slice(0, options.loads ?? 3)) {
+    for (const format of s.formats ?? []) {
+      try {
+        const asset = await provider.load(s.id, { format, size: 32 });
+        if (format === "svg" && (asset.kind !== "svg" || !/<svg[\s>]/.test(asset.svg))) issues.push({ stickerId: s.id, message: 'load({ format: "svg" }) did not return SVG' });
+        if (format === "png" && (asset.kind !== "image" || !/^(data:|https:)/.test(asset.url) || !(asset.width > 0 && asset.height > 0))) issues.push({ stickerId: s.id, message: 'load({ format: "png" }) did not return an image URL with its size' });
+      } catch (e) {
+        issues.push({ stickerId: s.id, message: `load({ format: "${format}" }) rejected: ${e.message}` });
+      }
+    }
+  }
+  const tintable = all.find((s) => s.tintable);
+  if (tintable) {
+    try {
+      const a = await provider.load(tintable.id, { format: tintable.formats[0], colour: "#123456", size: 32 });
+      if (a.kind === "svg" && !/#123456/i.test(a.svg)) issues.push({ stickerId: tintable.id, message: "a tintable sticker loaded with colour #123456 does not use it" });
+    } catch (e) {
+      issues.push({ stickerId: tintable.id, message: `load with a colour rejected: ${e.message}` });
+    }
+  }
+  return issues;
+}
+export {
+  DEFAULT_STICKER_PAGE,
+  EDITOR_STICKERS_ID,
+  MAX_STICKER_PAGE,
+  STAMP_KINDS,
+  StickerBrowser,
+  StickerError,
+  StickersSlot,
+  checkStickerProvider,
+  checkStickerSearchOptions,
+  closestStickerRefs,
+  combineStickerProviders,
+  createFakeStickerProvider,
+  createStickerToolProvider,
+  createStickerTools,
+  describeStickerRef,
+  editorStampOf,
+  editorStickers,
+  normalizeStickerRef,
+  parseStickerRef,
+  stampCoverage,
+  stampOutline,
+  stampPixels,
+  stickerForAgent,
+  stickerIdFor,
+  stickerPage,
+  stickerRefOf
+};

package/dist/stickers/stamps.d.cts

@@ -0,0 +1,13 @@
+/**
+ * The editor's own sticker stamps: procedural shapes (dot, star, heart, leaf, petal flower,
+ * confetti, splat, sparkle, ring) defined by a coverage function over the unit square, so no
+ * artwork is bundled. The paint editor's sticker spray draws them directly; `editorStickers()`
+ * offers them to every editor as the built-in sticker set (SVG outlines and PNGs).
+ */
+export type StampKind = 'dot' | 'star' | 'heart' | 'leaf' | 'flower' | 'confetti' | 'splat' | 'sparkle' | 'ring';
+export declare const STAMP_KINDS: readonly StampKind[];
+/**
+ * Coverage of a stamp at a point (u, v) of its unit square (−1..1, y down), 0..1, before shading.
+ * `t` is the sticker's seed for shapes with random parts (splat, confetti).
+ */
+export declare function stampCoverage(kind: StampKind, u: number, v: number, t: number): number;

package/dist/stickers/stamps.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The editor's own sticker stamps: procedural shapes (dot, star, heart, leaf, petal flower,
+ * confetti, splat, sparkle, ring) defined by a coverage function over the unit square, so no
+ * artwork is bundled. The paint editor's sticker spray draws them directly; `editorStickers()`
+ * offers them to every editor as the built-in sticker set (SVG outlines and PNGs).
+ */
+export type StampKind = 'dot' | 'star' | 'heart' | 'leaf' | 'flower' | 'confetti' | 'splat' | 'sparkle' | 'ring';
+export declare const STAMP_KINDS: readonly StampKind[];
+/**
+ * Coverage of a stamp at a point (u, v) of its unit square (−1..1, y down), 0..1, before shading.
+ * `t` is the sticker's seed for shapes with random parts (splat, confetti).
+ */
+export declare function stampCoverage(kind: StampKind, u: number, v: number, t: number): number;

package/dist/stickers/tools.d.cts

@@ -0,0 +1,25 @@
+/**
+ * Agent tools for a sticker library: `find_stickers` (search and page) and `describe_sticker`.
+ * Every sticker comes back as a `ref` (`provider:id`) for the editors' tools that place or spray
+ * stickers. Refusals name the valid choices.
+ */
+import type { AgentTool, AgentToolProvider } from '../tools/registry.cjs';
+import type { StickerDescription, StickerProvider, StickerRef, StickerSummary } from './types.cjs';
+/** A summary as the tools return it: `ref` instead of the provider's id. */
+export declare function stickerForAgent(provider: StickerProvider, s: StickerSummary): Record<string, unknown>;
+/**
+ * Looks up `ref` in `provider`, refusing an unknown or foreign ref with the closest ones it has.
+ * The editors use it to check refs before spraying or placing them.
+ */
+export declare function describeStickerRef(provider: StickerProvider, ref: StickerRef): Promise<StickerDescription>;
+export interface StickerToolsOptions {
+    /** The provider to use, read on every call (an editor's `StickersSlot`). */
+    provider: () => StickerProvider;
+}
+/** `find_stickers` and `describe_sticker` over the provider `options.provider()` returns. */
+export declare function createStickerTools(options: StickerToolsOptions): AgentTool[];
+/** The sticker library tools as a provider (id `stickers` by default). */
+export declare function createStickerToolProvider(options: StickerToolsOptions & {
+    id?: string;
+    namespace?: string;
+}): AgentToolProvider;

package/dist/stickers/tools.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Agent tools for a sticker library: `find_stickers` (search and page) and `describe_sticker`.
+ * Every sticker comes back as a `ref` (`provider:id`) for the editors' tools that place or spray
+ * stickers. Refusals name the valid choices.
+ */
+import type { AgentTool, AgentToolProvider } from '../tools/registry.js';
+import type { StickerDescription, StickerProvider, StickerRef, StickerSummary } from './types.js';
+/** A summary as the tools return it: `ref` instead of the provider's id. */
+export declare function stickerForAgent(provider: StickerProvider, s: StickerSummary): Record<string, unknown>;
+/**
+ * Looks up `ref` in `provider`, refusing an unknown or foreign ref with the closest ones it has.
+ * The editors use it to check refs before spraying or placing them.
+ */
+export declare function describeStickerRef(provider: StickerProvider, ref: StickerRef): Promise<StickerDescription>;
+export interface StickerToolsOptions {
+    /** The provider to use, read on every call (an editor's `StickersSlot`). */
+    provider: () => StickerProvider;
+}
+/** `find_stickers` and `describe_sticker` over the provider `options.provider()` returns. */
+export declare function createStickerTools(options: StickerToolsOptions): AgentTool[];
+/** The sticker library tools as a provider (id `stickers` by default). */
+export declare function createStickerToolProvider(options: StickerToolsOptions & {
+    id?: string;
+    namespace?: string;
+}): AgentToolProvider;

package/dist/stickers/types.d.cts

@@ -0,0 +1,123 @@
+/**
+ * The sticker provider contract: how an editor finds, describes and loads stickers from a library
+ * it knows nothing about (the editor's own stamps, a brand pack, user uploads, a third-party API).
+ * Libraries implement it structurally, like `EffectProvider` and `FontProvider`.
+ *
+ * Ids are the provider's own; a `StickerRef` (`provider:id`) names a sticker across providers
+ * (`combineStickerProviders` lists them that way).
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/** How a sticker's art may be used. Every sticker says. */
+export interface StickerLicence {
+    /** SPDX id when there is one (`MIT`, `CC-BY-4.0`). */
+    spdx?: string;
+    /** Human-readable name. */
+    name: string;
+    /** Credit line the licence asks for. */
+    attribution?: string;
+    url?: string;
+    /** May be used commercially. */
+    commercial: boolean;
+}
+export type StickerFormat = 'svg' | 'png';
+/** A sticker in a list or search result. */
+export interface StickerSummary {
+    /** The provider's id (no `:` needed; `combineStickerProviders` prefixes its own). */
+    id: string;
+    name: string;
+    category: string;
+    tags?: string[];
+    description?: string;
+    /** Natural size in px, for layout before the art is loaded. */
+    width: number;
+    height: number;
+    /** A small `data:` or `https:` image. */
+    thumbnail?: string;
+    /** The formats `load` can return. */
+    formats: StickerFormat[];
+    licence: StickerLicence;
+    /** Flat, single-colour art: `load(id, { colour })` recolours it (the paint editor's spray colours it). */
+    tintable: boolean;
+}
+/** Everything about one sticker. */
+export interface StickerDescription extends StickerSummary {
+    /** SVG path data of its outline, in its natural box (for die-cut treatments). */
+    silhouette?: string;
+    /** Dominant colours #rrggbb, for matching and recolouring. */
+    colours?: string[];
+    variants?: {
+        id: string;
+        name: string;
+    }[];
+}
+/** A sticker's art. */
+export type StickerAsset = {
+    kind: 'svg';
+    svg: string;
+    silhouette?: string;
+}
+/** `url`: a `data:` or `https:` image. */
+ | {
+    kind: 'image';
+    url: string;
+    width: number;
+    height: number;
+};
+/** One page of results. Pages stay small; follow `next` (pass it as `after`). */
+export interface StickerPage {
+    items: StickerSummary[];
+    /** How many match in all. */
+    total: number;
+    next?: string;
+}
+export interface StickerSearchOptions {
+    category?: string;
+    /** Every tag must match. */
+    tags?: string[];
+    /** Page size (providers cap it; 1..100, default 24). */
+    limit?: number;
+    /** `next` from the previous page. */
+    after?: string;
+    licence?: {
+        commercial?: boolean;
+    };
+}
+export interface StickerLoadOptions {
+    format?: StickerFormat;
+    /** Longest side in px for raster art. */
+    size?: number;
+    /** #rrggbb: recolour a tintable sticker. */
+    colour?: string;
+}
+export interface StickerProviderCapabilities {
+    supportsSearch: boolean;
+    supportsSvg: boolean;
+    supportsRaster: boolean;
+    /** The largest raster `size` it loads. */
+    maxSize?: number;
+}
+export interface StickerProvider {
+    /** Short and unique among the providers an editor uses: `editor`, `acme-brand`, `uploads`. */
+    readonly id: string;
+    readonly name: string;
+    readonly version?: string;
+    readonly capabilities: StickerProviderCapabilities;
+    /** Its ids are already refs (`provider:id`): a combination of providers (`combineStickerProviders`). */
+    readonly namespaced?: boolean;
+    /** The stickers, a page at a time; `category` and `tags` filter. */
+    list(options?: StickerSearchOptions): MaybePromise<StickerPage>;
+    /** Stickers matching words in their name, tags, category or description; `""` is `list`. */
+    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. */
+    load(id: string, options?: StickerLoadOptions): MaybePromise<StickerAsset>;
+    /** Categories with counts, when the provider knows them. */
+    categories?(): MaybePromise<Array<{
+        id: string;
+        name: string;
+        count: number;
+    }>>;
+}
+/** `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

@@ -0,0 +1,123 @@
+/**
+ * The sticker provider contract: how an editor finds, describes and loads stickers from a library
+ * it knows nothing about (the editor's own stamps, a brand pack, user uploads, a third-party API).
+ * Libraries implement it structurally, like `EffectProvider` and `FontProvider`.
+ *
+ * Ids are the provider's own; a `StickerRef` (`provider:id`) names a sticker across providers
+ * (`combineStickerProviders` lists them that way).
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/** How a sticker's art may be used. Every sticker says. */
+export interface StickerLicence {
+    /** SPDX id when there is one (`MIT`, `CC-BY-4.0`). */
+    spdx?: string;
+    /** Human-readable name. */
+    name: string;
+    /** Credit line the licence asks for. */
+    attribution?: string;
+    url?: string;
+    /** May be used commercially. */
+    commercial: boolean;
+}
+export type StickerFormat = 'svg' | 'png';
+/** A sticker in a list or search result. */
+export interface StickerSummary {
+    /** The provider's id (no `:` needed; `combineStickerProviders` prefixes its own). */
+    id: string;
+    name: string;
+    category: string;
+    tags?: string[];
+    description?: string;
+    /** Natural size in px, for layout before the art is loaded. */
+    width: number;
+    height: number;
+    /** A small `data:` or `https:` image. */
+    thumbnail?: string;
+    /** The formats `load` can return. */
+    formats: StickerFormat[];
+    licence: StickerLicence;
+    /** Flat, single-colour art: `load(id, { colour })` recolours it (the paint editor's spray colours it). */
+    tintable: boolean;
+}
+/** Everything about one sticker. */
+export interface StickerDescription extends StickerSummary {
+    /** SVG path data of its outline, in its natural box (for die-cut treatments). */
+    silhouette?: string;
+    /** Dominant colours #rrggbb, for matching and recolouring. */
+    colours?: string[];
+    variants?: {
+        id: string;
+        name: string;
+    }[];
+}
+/** A sticker's art. */
+export type StickerAsset = {
+    kind: 'svg';
+    svg: string;
+    silhouette?: string;
+}
+/** `url`: a `data:` or `https:` image. */
+ | {
+    kind: 'image';
+    url: string;
+    width: number;
+    height: number;
+};
+/** One page of results. Pages stay small; follow `next` (pass it as `after`). */
+export interface StickerPage {
+    items: StickerSummary[];
+    /** How many match in all. */
+    total: number;
+    next?: string;
+}
+export interface StickerSearchOptions {
+    category?: string;
+    /** Every tag must match. */
+    tags?: string[];
+    /** Page size (providers cap it; 1..100, default 24). */
+    limit?: number;
+    /** `next` from the previous page. */
+    after?: string;
+    licence?: {
+        commercial?: boolean;
+    };
+}
+export interface StickerLoadOptions {
+    format?: StickerFormat;
+    /** Longest side in px for raster art. */
+    size?: number;
+    /** #rrggbb: recolour a tintable sticker. */
+    colour?: string;
+}
+export interface StickerProviderCapabilities {
+    supportsSearch: boolean;
+    supportsSvg: boolean;
+    supportsRaster: boolean;
+    /** The largest raster `size` it loads. */
+    maxSize?: number;
+}
+export interface StickerProvider {
+    /** Short and unique among the providers an editor uses: `editor`, `acme-brand`, `uploads`. */
+    readonly id: string;
+    readonly name: string;
+    readonly version?: string;
+    readonly capabilities: StickerProviderCapabilities;
+    /** Its ids are already refs (`provider:id`): a combination of providers (`combineStickerProviders`). */
+    readonly namespaced?: boolean;
+    /** The stickers, a page at a time; `category` and `tags` filter. */
+    list(options?: StickerSearchOptions): MaybePromise<StickerPage>;
+    /** Stickers matching words in their name, tags, category or description; `""` is `list`. */
+    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. */
+    load(id: string, options?: StickerLoadOptions): MaybePromise<StickerAsset>;
+    /** Categories with counts, when the provider knows them. */
+    categories?(): MaybePromise<Array<{
+        id: string;
+        name: string;
+        count: number;
+    }>>;
+}
+/** `provider:id`, the name of a sticker across providers. A bare editor stamp (`"star"`) means `editor:star`. */
+export type StickerRef = string;