@pixerate/editor 0.246.0 → 0.249.0

package/dist/vector/index.js

@@ -26,7 +26,7 @@ import {
   traceField,
   traceVectorImage,
   vectorTraceContours
-} from "../chunk-DQWPMGH2.js";
+} from "../chunk-DOIU7VJG.js";
 import {
   applyHomography,
   homographyFromPoints,
@@ -53,7 +53,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-A23PSOBB.js";
+} from "../chunk-O75V4ZS3.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -526,8 +526,9 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-N6WUB3Y5.js";
-import "../chunk-VDAWA546.js";
+} from "../chunk-PZP2SZIZ.js";
+import "../chunk-J7T5QZ45.js";
+import "../chunk-5RH3VXAK.js";
 import {
   createProvenance
 } from "../chunk-M6DNZNVY.js";
@@ -562,14 +563,16 @@ import {
 import "../chunk-V2ZCJRDM.js";
 import {
   GRAIN_PATTERNS
-} from "../chunk-2PBZBRP5.js";
+} from "../chunk-D5KGAO4Z.js";
+import "../chunk-4D6KP5BV.js";
 import "../chunk-ODBT55Q7.js";
+import "../chunk-IRSTHLQQ.js";
 import {
   bytesToBase64,
   decodePng,
   isPng,
   parseDataUrl
-} from "../chunk-42TWUPNJ.js";
+} from "../chunk-OTTT5N3K.js";
 import "../chunk-HVVR5PZW.js";
 import {
   deflate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.246.0",
+  "version": "0.249.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",
@@ -334,6 +334,16 @@
         "default": "./dist/effects/index.cjs"
       }
     },
+    "./stickers": {
+      "import": {
+        "types": "./dist/stickers/index.d.ts",
+        "default": "./dist/stickers/index.js"
+      },
+      "require": {
+        "types": "./dist/stickers/index.d.cts",
+        "default": "./dist/stickers/index.cjs"
+      }
+    },
     "./diagram": {
       "import": {
         "types": "./dist/diagram/index.d.ts",

package/skills/README.md

@@ -29,6 +29,7 @@ model and its general practice.
 | [`pixerate-effect-authoring`](pixerate-effect-authoring/SKILL.md) | Authoring shaders and procedural effects: inspecting parameters and source code, setting values and presets, keyframing animation tracks, playback timing, and previewing. |
 | [`pixerate-color`](pixerate-color/SKILL.md) | Colour inspection, WCAG accessibility and contrast optimization, CVD simulation, palette audits, harmonies, and OKLab/OKLCH blends. |
 | [`pixerate-typography`](pixerate-typography/SKILL.md) | Fonts and fallback stacks, font loading, modular type scales and hierarchies, fluid sizes, readability and type-aware contrast audits, text segmentation, the font picker. |
+| [`pixerate-stickers`](pixerate-stickers/SKILL.md) | Sticker libraries: finding stickers by ref (`provider:id`), categories, tags, tintable art and licences, for the editors that spray or place them. |
 
 ## Workflow skills
 

package/skills/pixerate-paint-editor/SKILL.md

@@ -165,41 +165,28 @@ Wet oil blends where the brush meets it; impasto adds relief lit by `set_lightin
 
 ## Gradient paint
 
-Paint that changes colour as the stroke goes: give a gradient where a colour would go.
-
-1. **`set_paint`** with `{ type: "gradient", stops, map }` makes it the paint for every following
-   stroke (`set_color` goes back to one colour); `paint_stroke` `paint` overrides it for one stroke;
-   a brush can carry its own (`set_brush` `paint`, presets `gradient-round`, `pressure-ombre`,
-   `rainbow-marker`, `gradient-wash`).
-2. **Choose the mapping by what the stroke should do**: `distance` (default, 300 px then
-   `mirror` back) for "drag it out" colour; `pressure` for light-to-heavy shading in one stroke;
-   `direction` for strokes coloured by their heading; `across-tip` for a brush loaded with several
-   colours side by side; `random` (`every` dabs) for speckled or confetti colour; `time` and
-   `velocity` need timed points (`t`). Set `length` to about the stroke length you will paint.
-3. **Stops**: 2..16, sorted by `offset`; `"paint"` / `"secondary"` follow the two editor colours;
-   `opacity` multiplies flow (fade a stroke out); `midpoint` shifts where two colours meet;
-   `softness` 0 makes hard bands. `space` `pigment` (default) mixes like paint (blue to yellow
-   through green), `oklab` keeps rainbows bright.
-4. **It works with every colour engine**: dab, Mixer Brush (each dab reloads its reservoir),
-   watercolour and gouache (each deposit carries its pigment into the wet layer, which then flows
-   and mixes), oil and impasto (the colour varies along the relief), particles, bristles and
-   stickers. Erasers, blenders and smudges ignore it; the eyedropper picks one colour.
-5. Strokes record the gradient (with concrete colours), so replays, time-lapses, high-res
-   re-renders and drying are exact. `get_brush` `strokePaint` says what the next stroke paints.
+Paint that changes colour as the stroke goes (`set_paint` with a gradient, a brush's own `paint`,
+or `paint_stroke` `paint`): read [references/gradient-paint.md](references/gradient-paint.md).
+
+## Layer effects
+
+Live layer styles on a paint layer, drawn from its pixels so they follow later painting: outer and
+inner glow, shadows, stroke, bevel, satin and overlays, as in the image editor
+(`add_layer_effect` and the rows below). Read [references/layer-effects.md](references/layer-effects.md).
 
 ## Procedural brushes, bristles, stickers and stencils
 
-- **Particle brushes** (category `procedural`): `hair-strands` (strings of masses dragged behind
-  the pen: hair, fur, grass), `spring-ink` (springs that overshoot: lively ink lines),
-  `orbit-curls` (particles circling the pen: curls and spirals), `flow-fur` and `sparkle-dust`
-  (particles thrown into a swirling flow), `bead-trail` (beads along a springy path). Tune with
-  `particle` (kind, render dot / line / sequence, count, stiffness, damping, speed, gravity).
+- **Particle brushes** (category `procedural`; ribbons, flames and bokeh are in `light`):
+  `hair-strands`, `spring-ink`, `orbit-curls`, `flow-fur`, `sparkle-dust`, `bead-trail`. Tune
+  with `particle`: kind (string, spring, orbit, flow, elastic, fuzzy), render (dot, line,
+  sequence, ribbon), waves and textured dots; read [references/particle-brushes.md](references/particle-brushes.md).
   Draw slowly and with varying direction: the particles react to movement.
 - **Bristle brushes** (category `bristle`): `bristle-round`, `bristle-flat`, `dry-brush`. Every
   bristle draws its own line: press harder to splay the tuft, tilt to flatten it; soft bristles
   bend into curves at turns; a low `bristle.load` runs dry into broken streaks.
-- **Sticker spray** (category `sticker`): stamps (`star`, `leaf`, `confetti`, `flower`, `heart`,
-  `splat`, `sparkle`, `ring`, `dot`) sprayed onto an **empty layer**, each staying an object:
+- **Sticker spray** (category `sticker`): stickers by ref (`editor:star`, `editor:leaf`… or any
+  from the host's library: `find_stickers`; tintable ones take the paint colour) sprayed onto an
+  **empty layer**, each staying an object:
   `add_stickers` (exact places), `sticker_at`, `list_stickers`, `update_sticker`, `arrange_stickers`,
   `remove_stickers`. A sticker layer takes no other paint; sprays are refused under an enabled
   mask stencil (hide it with `update_stencil` `enabled` false, then remove unwanted stickers).
@@ -283,9 +270,14 @@ is a canvas coordinate: read [references/canvas-hosted.md](references/canvas-hos
 
 | Tool | Use |
 | --- | --- |
-| `list_layers` | Read the layers top first: id, name, type (`pixel` / `group`), visible, opacity, blend, clipped, locks, `active`, painted `bounds` (null when empty), parent and depth. |
+| `list_layers` | Read the layers top first: id, name, type (`pixel` / `group`), visible, opacity, blend, clipped, locks, `active`, painted `bounds` (null when empty), parent, depth and `effects` (how many layer effects). |
 | `add_layer` | Add an empty pixel layer (or `type: "group"`, or `type: "strokes"` for a stroke layer whose strokes stay editable) above the active layer, above `aboveId`, or at the top of group `parentId`; it becomes active. Returns the layer. Put each pass of a painting on its own layer. |
 | `update_layer` | Change `name`, `visible`, `opacity` (0..1), `blend`, `clipped` (clip to the layer below) or `locks` (`pixels`, `transparency`: paint only where there is paint, `position`, `all`). Returns the layer. |
+| `list_layer_effects` | Read a layer's effects: the master switch, Scale Effects, margin, and each effect with its id, kind and settings, plus the pattern ids. Call before changing one. |
+| `add_layer_effect` | Add a live effect (`outer-glow`, `inner-glow`, `drop-shadow`, `stroke`, …) with Photoshop's defaults changed by `settings`. One undo step. Returns its `effectId` and the layer's effects. |
+| `update_layer_effect` | Change settings of one effect (by `effectId`) after painting: glow colour, size, opacity, blend. One undo step. Returns the layer's effects. |
+| `remove_layer_effect` | Remove one effect (`update_layer_effect` `enabled: false` hides it instead). One undo step. |
+| `set_layer_effects_enabled` | Turn all of a layer's effects on or off and set Scale Effects. One undo step. |
 | `list_blend_modes` | Read every blend mode: id, label, group (`standard`, `pigment`, `painterly`), what the pigment and painterly modes do, and the `psd` mode export writes instead. Read before choosing a painterly mode. Changes nothing. |
 | `set_active_layer` | Make a layer the default target of strokes, fills and clears. Editor state. |
 | `remove_layer` | Delete a layer (a group with its children). Prefer hiding it when the user may want it back. |
@@ -381,10 +373,12 @@ is a canvas coordinate: read [references/canvas-hosted.md](references/canvas-hos
 
 | Tool | Use |
 | --- | --- |
-| `list_stickers` | Read a layer's stickers bottom first: id, stamp, x, y, size, rotation, color, opacity. |
-| `add_stickers` | Place stickers exactly (`stamp`, `x`, `y`, optional `size`, `rotation`, `color`, `opacity`, `seed`) on a sticker layer or an empty layer. Use it for deliberate placement, a sticker brush for a scatter. One undo step. Returns the new stickers with ids. |
+| `list_stickers` | Read a layer's stickers bottom first: id, `ref` (and `stamp` for the editor's own), x, y, size, rotation, color, opacity. |
+| `add_stickers` | Place stickers exactly (`ref` from `find_stickers`, `x`, `y`, optional `size`, `rotation`, `color`, `opacity`, `seed`) on a sticker layer or an empty layer; a provider's art loads first. Use it for deliberate placement, a sticker brush for a scatter. One undo step. Returns the new stickers with ids. |
 | `sticker_at` | Read the top-most sticker under a point (`x`, `y`), or null. Use it to pick one sticker among many similar ones before `update_sticker`, `arrange_stickers` or `remove_stickers`. |
-| `update_sticker` | Change one sticker by `id`: `stamp`, `x`, `y`, `size`, `rotation`, `color`, `opacity`. One undo step. Returns it. |
+| `update_sticker` | Change one sticker by `id`: `ref`, `x`, `y`, `size`, `rotation`, `color`, `opacity`. One undo step. Returns it. |
+| `find_stickers` | Search the sticker library (the editor's stamps unless the host plugged in its own) by words, category, tags and commercial licence, a page at a time. Returns refs (`provider:id`) for sticker brushes (`set_brush` `sticker.stamps`) and `add_stickers`, with tintable and licence. |
+| `describe_sticker` | One sticker by `ref`: licence and attribution, colours, outline. Unknown refs are refused with the closest ones. |
 | `arrange_stickers` | Move stickers (`ids`) to the `front` or `back` of their layer. One undo step. |
 | `remove_stickers` | Delete stickers by `ids`, or all on the layer. One undo step. |
 

package/skills/pixerate-paint-editor/references/gradient-paint.md

@@ -0,0 +1,23 @@
+# Gradient paint
+
+Paint that changes colour as the stroke goes: give a gradient where a colour would go.
+
+1. **`set_paint`** with `{ type: "gradient", stops, map }` makes it the paint for every following
+   stroke (`set_color` goes back to one colour); `paint_stroke` `paint` overrides it for one stroke;
+   a brush can carry its own (`set_brush` `paint`, presets `gradient-round`, `pressure-ombre`,
+   `rainbow-marker`, `gradient-wash`).
+2. **Choose the mapping by what the stroke should do**: `distance` (default, 300 px then
+   `mirror` back) for "drag it out" colour; `pressure` for light-to-heavy shading in one stroke;
+   `direction` for strokes coloured by their heading; `across-tip` for a brush loaded with several
+   colours side by side; `random` (`every` dabs) for speckled or confetti colour; `time` and
+   `velocity` need timed points (`t`). Set `length` to about the stroke length you will paint.
+3. **Stops**: 2..16, sorted by `offset`; `"paint"` / `"secondary"` follow the two editor colours;
+   `opacity` multiplies flow (fade a stroke out); `midpoint` shifts where two colours meet;
+   `softness` 0 makes hard bands. `space` `pigment` (default) mixes like paint (blue to yellow
+   through green), `oklab` keeps rainbows bright.
+4. **It works with every colour engine**: dab, Mixer Brush (each dab reloads its reservoir),
+   watercolour and gouache (each deposit carries its pigment into the wet layer, which then flows
+   and mixes), oil and impasto (the colour varies along the relief), particles, bristles and
+   stickers. Erasers, blenders and smudges ignore it; the eyedropper picks one colour.
+5. Strokes record the gradient (with concrete colours), so replays, time-lapses, high-res
+   re-renders and drying are exact. `get_brush` `strokePaint` says what the next stroke paints.

package/skills/pixerate-paint-editor/references/layer-effects.md

@@ -0,0 +1,28 @@
+# Layer effects (layer styles)
+
+The paint editor's layers take the same live effects as the image editor's: outer glow, inner
+glow, drop shadow, inner shadow, stroke, bevel & emboss, satin, and colour, gradient and pattern
+overlays, with the same settings, defaults and limits. They are stored on the layer, drawn from its
+pixels each time the painting is composited (so they follow every later stroke, smudge and
+erase), saved with the document, undone one step per change, and written to PSD as layer styles.
+
+- **Tools.** `add_layer_effect` (kind plus `settings`; returns the `effectId`),
+  `update_layer_effect` (only the settings you give), `remove_layer_effect`,
+  `set_layer_effects_enabled` (all on or off, and Scale Effects), `list_layer_effects` (read
+  them). They take pixel, stroke, sticker and group layers; a fully locked layer refuses them.
+- **Glow you can still change.** Paint a light shape on its own layer, then `add_layer_effect`
+  `outer-glow` with `settings: { fill: { type: "color", color: "#22d3ee" }, size: 30, spread: 0.1,
+  blend: "linear-dodge", opacity: 0.9 }`. Change its colour or size later with
+  `update_layer_effect`, without repainting. `inner-glow` lights the inside of the shape from its
+  edge (`source: "edge"`) or centre.
+- **Glow style vs light spill.** Light paint (`light.amount`, the Light brushes) spills each
+  stroke's own colour by its own strength. A glow style is one colour, one size, around everything
+  on the layer: use it for a uniform halo (a neon sign's tube, a sticker's outline, a title), or as
+  well as spill for a stronger, adjustable bloom. For the light-painting look on dark paper,
+  `linear-dodge` (or the default `screen`) glows add light; `normal` paints a solid halo.
+- **Shadows and bevels** follow the default global light (120°, 30° altitude) unless you give
+  `angle` with `useGlobalLight: false`; the paint editor has no global light of its own (its
+  `set_lighting` lights impasto relief, not effects).
+- **Wet paint** shows its effects as it is now; they redraw as it flows and dries.
+- **PSD.** `export_psd` writes each layer's effects as its layer style (Photoshop reads them as
+  editable effects); the merged image matches the editor.

package/skills/pixerate-paint-editor/references/light-paint.md

@@ -3,8 +3,9 @@
 Light paint is paint that gives off light: neon, light painting, glow-in-the-dark, glowing glassy
 tubes, glowing watercolour. Any dab, particle, bristle, Mixer Brush, impasto or wet paint brush
 lays it with `light.amount` above 0 (`set_brush`); the Light category presets are ready-made
-(`glow-gel`, `neon-marker`, `light-airbrush`, `spark-trail`, `glow-wash`,
-`highlighter`).
+(`glow-gel`, `neon-marker`, `light-airbrush`, `spark-trail`, `light-ribbon`, `flame-ribbon`,
+`neon-strand`, `smoke-ribbon`, `bokeh-dots`, `twinkle-sparks`, `glow-wash`, `highlighter`; the
+particle ones are tuned in [particle-brushes.md](particle-brushes.md)).
 
 - **What it does.** Each layer keeps a light channel next to its colour. The light's colour is the
   paint's colour at that pixel, so recolouring paint recolours its light. It glows (the paint
@@ -28,6 +29,13 @@ lays it with `light.amount` above 0 (`set_brush`); the Light category presets ar
   layer that holds the text (a tip blend works within its layer), and turn that layer's spill off
   (`set_light_spill` `radius` 0): fluorescent ink does not light its surroundings, and spill would
   wash the text out.
+- **Light painting** (long-exposure trails, neon signs, fire): set dark paper (`set_paper`
+  `color`, e.g. `#0b1020`), then paint with the Light presets in bright, saturated colours;
+  white light reads as a hot core, so lay a coloured stroke first and a thinner, lighter one over
+  it. Ribbons (`light-ribbon`, `flame-ribbon`) read best in long sweeping strokes with times;
+  `neon-strand` in steady strokes; `bokeh-dots` and `twinkle-sparks` as accents last. Put each
+  colour family on its own layer so you can tune its spill (`set_light_spill`: larger radius for
+  haze, 0 for crisp). Check with `export_image` before adding more: light adds up fast.
 - **Spill vs a glow layer style.** Spill takes each stroke's colour and strength. For a one-colour
   halo around everything on a layer, use a blend or an effect layer instead.
 - **Glowing watercolour** (wet paint brushes with `light.amount`, e.g. `glow-wash`): the light is

package/skills/pixerate-paint-editor/references/particle-brushes.md

@@ -0,0 +1,66 @@
+# Particle brushes
+
+Particle brushes (`engine: 'particle'`) make marks with a small simulation driven by the pen. They
+are seeded and stepped by distance, so the same points and `seed` paint the same pixels and
+replays are exact. Their marks are ordinary coverage: opacity, blend modes, locks, stencils,
+symmetry, gradient paint, effect paint and light paint all work as for a dab brush. Change them
+with `set_brush` `particle` (missing fields keep their values); `get_brush` returns them all.
+
+## Kinds (`particle.kind`)
+
+| Kind | Motion | Good for |
+| --- | --- | --- |
+| `string` | Strands of masses dragged behind the pen | Hair, fur, grass, silk |
+| `spring` | Each particle on a spring to the pen, overshooting | Lively ink, twisting bands |
+| `orbit` | Particles circling the pen | Curls, spirographs |
+| `flow` | Thrown off the pen into a swirling flow until they fade (`life`) | Fur, sparks, flames, smoke |
+| `elastic` | Strands whose links have a rest length: they stretch when the pen is fast and snap back | Neon tubes, rubber bands |
+| `fuzzy` | Strings that always wind, each strand waving out of step | Fuzz, tangled light, yarn |
+
+`stiffness`, `damping` and `gravity` shape the motion (negative gravity rises: flames, smoke).
+`elastic` and `fuzzy` damp their strands enough to stay together at any setting; a `string` with
+low damping and high stiffness can still swing wildly, which is part of its look.
+
+## Renders (`particle.render`)
+
+- `dot`: a mark at every step; `line`: each particle's path as a line; `sequence`: beads spaced
+  by `interval` along each path.
+- `ribbon`: the band between neighbouring particles' paths is filled, at `ribbonFill` (0..1,
+  default 0.5) of the stroke opacity, and the paths are drawn as its edges at `size` (keep
+  `size` small, about 0.01, for fine edges; `ribbonFill` 0 leaves only the edges).
+  `ribbonPairs` `adjacent` (default) joins each particle to its neighbour around the pen;
+  `first-last` makes one band between the outermost two. `spread` sets how wide it is. The fill
+  has no seams and does not build up where bands meet; it builds up only with other strokes.
+  `spring` ribbons twist like silk, `string` ribbons trail, `flow` ribbons flicker like flames.
+
+## Waves
+
+Any kind and render can wave: each particle's drawn place moves sideways to the stroke on a sine.
+`waveAmplitude` is a fraction of the tip size (0 default: off), `waveLength` px of pen travel
+(4..2000, default 60), `waveSpeed` how fast the waves run by stroke time (0: they stand still on
+the path; 1: about four a second, so slow strokes wave more), `wavePhaseJitter` how far out of
+step the particles are (0: a wavy band; 1: tangled strands). Waves run by the points' `time`;
+points without times run at a nominal 0.5 px/ms, so give times when the speed matters.
+
+## Textured dots
+
+`dotTextures`: up to four sticker stamps (`list_stickers` stamp ids: dot, star, heart, leaf,
+flower, confetti, splat, sparkle, ring) drawn instead of round marks by the `dot` and `sequence`
+renders; a stamp listed twice is picked twice as often. `dotTextureOrder` `sequence` (default)
+uses them in turn, `random` picks one per dot (seeded). `dotRotation` `random` (default),
+`follow` (turned with each particle's motion) or `fixed` (the tip angle). Empty: round dots.
+
+## Light presets (category `light`)
+
+`light-ribbon` (silk of light on slow waves), `flame-ribbon` (rising flow ribbons), `neon-strand`
+(an elastic tube with a slow shimmer), `smoke-ribbon` (thin lit smoke), `bokeh-dots` (soft discs
+and rings), `twinkle-sparks` (sparkles and stars thrown into the flow), `spark-trail`. Each lays
+light paint; see [light-paint.md](light-paint.md) for spill and the light-painting method.
+
+## Best practice
+
+- Check a setting with `render_brush_thumbnail` before painting with it.
+- Change one thing at a time: kind for the motion, render for the look, then waves and textures.
+- Many `flow` particles with long `life` in a `ribbon` are slow (every pair of live particles is
+  a band each step): keep `count` × `life` low (count 3..6, life ≤ 0.4).
+- Stroke layers redraw particle strokes exactly, so ribbons and waves stay editable there.

package/skills/pixerate-stickers/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pixerate-stickers
+description: How to find, check and use stickers from the Pixerate sticker library through find_stickers and describe_sticker - the editor's own stamps (editor:star, editor:heart, ...) or any library a host plugged in (brand packs, uploads, third-party APIs), with refs (provider:id), categories, tags, tintable art and licences. Use when asked to add, spray, place, search for or credit stickers, or when find_stickers or describe_sticker are available.
+---
+
+# Stickers
+
+A sticker library is a `StickerProvider` the host plugs in (`@pixerate/editor/stickers`); with
+none, it is the editor's own stamps (`editorStickers()`: `editor:dot`, `editor:star`,
+`editor:heart`, `editor:leaf`, `editor:flower`, `editor:confetti`, `editor:splat`,
+`editor:sparkle`, `editor:ring`, all MIT and tintable). Every sticker is named by a **ref**,
+`provider:id`; the editors' sticker tools take refs.
+
+## Working method
+
+1. **Find.** `find_stickers` with a few words (`query`) and, when the result's `categories`
+   suggest one, a `category`. Pages are small: pass `next` as `after` for more, or narrow the
+   query. Filter with `commercial: true` for anything that will be sold or used in marketing.
+2. **Check.** `describe_sticker` when the choice matters: its licence (and the attribution line
+   it asks for), dominant colours, variants and outline.
+3. **Use.** Pass refs to the editor that places them: in the paint editor, a sticker brush
+   (`set_brush` `sticker.stamps`, then `paint_stroke`) sprays them and `add_stickers` places
+   them exactly. A provider's art loads before it is drawn.
+4. **Colour.** Tintable stickers (flat, single-colour art) take the paint colour or a sticker's
+   `color`; the rest keep their own colours.
+
+## Best practices
+
+- Keep refs exactly as `find_stickers` returns them; a bare editor stamp (`star`) also works
+  and means `editor:star`.
+- Credit stickers whose licence has an `attribution` wherever the work is published.
+- Prefer tintable stickers when they must match a palette.
+
+## Pitfalls
+
+- An unknown ref is refused with the closest refs: pick one of those or search again.
+- A category that the library doesn't have is refused with the list of its categories.
+- `limit` is 1..100; results beyond a page need `after`, not a larger limit.
+
+## Tool reference
+
+| Tool | Use |
+| --- | --- |
+| `find_stickers` | Search or list the library: `query`, `category`, `tags`, `commercial`, `limit`, `after`. Returns `items` (each `ref`, name, category, tags, width, height, formats, tintable, licence), `total`, `next`, `categories`. Changes nothing. |
+| `describe_sticker` | One sticker by `ref`: everything `find_stickers` returns plus `silhouette` (SVG path data), `colours` and `variants`. Unknown refs are refused with the closest ones. Changes nothing. |