@amigo-labs/pincel-wasm 1.6.0 → 1.7.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@amigo-labs/pincel-wasm",
   "type": "module",
   "description": "WebAssembly bindings for the Pincel core (wasm-bindgen / wasm-pack target)",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",

package/pincel_wasm.d.ts

@@ -222,9 +222,10 @@ export class Document {
      * stable across runs and monotonic. Returns the assigned id.
      *
      * Routes through the [`AddTileset`] command so the operation joins
-     * the undo / redo bus. Tile-image content starts empty (Aseprite
-     * convention: tile id `0` is the implicit empty tile); per-tile
-     * edits land alongside the Tileset Editor in M8.7.
+     * the undo / redo bus. The tileset starts with one stored, fully
+     * transparent tile `0` (Aseprite's empty tile), so the first
+     * [`Document::add_tile`] returns id `1` and no user tile is written
+     * as the empty tile (docs/specs/tilemaps.md, Decisions 2026-10-29).
      *
      * Errors when `tile_w` or `tile_h` is zero, when the existing id
      * space is exhausted (an existing tileset already uses `u32::MAX`),
@@ -291,6 +292,22 @@ export class Document {
      * The emitted `dirty-rect` event covers the bbox in sprite space.
      */
     applyEllipse(x0: number, y0: number, x1: number, y1: number, color: number, fill: boolean): void;
+    /**
+     * Fill the selection — or, without one, the active layer's cel on the
+     * current frame — with a dithered ramp from `foreground` at the drag
+     * start to `background` at the drag end, as one undo entry.
+     *
+     * - `line`: `[x0, y0, x1, y1]`, the drag's start and end sprite pixels.
+     * - `kind`: `linear` or `radial`.
+     * - `dither`: the Bayer matrix size `2`, `4` or `8`, or `0` for two
+     *   hard bands split halfway.
+     * - `foreground` / `background`: `0xRRGGBBAA`.
+     *
+     * Returns `false` — and changes nothing — for a zero-length drag.
+     * Errors (and changes nothing) on a locked layer, a document without a
+     * paintable image layer, and an indexed or grayscale sprite.
+     */
+    applyGradient(line: Int32Array, kind: string, dither: number, foreground: number, background: number): boolean;
     /**
      * Rasterize a 1-pixel-wide Bresenham line between sprite-space
      * `(x0, y0)` and `(x1, y1)` with the given non-premultiplied RGBA
@@ -395,6 +412,23 @@ export class Document {
      * lands when more tools ship.
      */
     applyTool(tool_id: string, x: number, y: number, color: number): void;
+    /**
+     * Start a Pencil gesture with the Shading ink: every pixel the stroke
+     * touches whose color before the stroke is exactly entry `i` of `ramp`
+     * becomes entry `i + step`, clamped to the ramp; other colors stay.
+     * Each pixel changes at most once per gesture. Continue it with
+     * [`Self::stroke_to`] and close it with `endStroke` like any stroke.
+     *
+     * - `ramp`: the colors in palette order (`0xRRGGBBAA`), at least one.
+     * - `step`: `1` (left button, toward the end) or `-1` (right button,
+     *   toward the start).
+     * - `size`, `shape`, `pixel_perfect`: as in [`Self::begin_stroke`].
+     *
+     * Errors (and starts nothing) for an empty ramp, another step, an
+     * unknown shape, a locked target layer, or a document without a
+     * paintable image layer.
+     */
+    beginShadingStroke(ramp: Uint32Array, step: number, size: number, shape: string, pixel_perfect: boolean): void;
     /**
      * Start a Pencil / Eraser gesture on the active layer / current frame.
      * Nothing is painted until the first [`Self::stroke_to`].
@@ -446,6 +480,14 @@ export class Document {
      * event's `(x, y, width, height)` directly.
      */
     composeDirty(frame: number, zoom: number, dx: number, dy: number, dw: number, dh: number): ComposeFrame;
+    /**
+     * [`Document::compose`] with the onion skin chosen per call: `onion =
+     * true` applies the configured onion skin (the same bytes as
+     * `compose`), `onion = false` leaves it out whatever
+     * [`Document::set_onion_skin`] says — for an animation preview that
+     * must never show ghosts (docs/specs/animation-preview.md).
+     */
+    composeFrame(frame: number, zoom: number, onion: boolean): ComposeFrame;
     /**
      * Shrink the selection by `radius` pixels (may clear it).
      */
@@ -529,7 +571,7 @@ export class Document {
      * a fresh `Uint8Array` copy. Errors surface the `pincel-core`
      * message: an unknown format or tag, a scale outside 1–10, an output
      * edge above 16384 px, a frameless sequence, or a sprite the renderer
-     * refuses (an indexed sprite).
+     * refuses (a corrupt cel or a broken linked cel).
      */
     exportAnimation(format: string, tag: string | null | undefined, scale: number, loops: number): Uint8Array;
     /**
@@ -549,12 +591,29 @@ export class Document {
      * `meta.image` names `image_name` (default `"sheet.png"`). Errors
      * surface the underlying `pincel-core` message: zero columns, an
      * unknown tag, a frameless sprite, or anything the renderer refuses.
+     *
+     * `scale` (optional, default 1) upscales the sheet by an integer
+     * factor 1–10 with nearest-neighbour; the manifest and the `--data`
+     * JSON describe the scaled sheet (`meta.scale` stays `"1"`, as
+     * Aseprite's `--scale`). A scale outside 1–10 or a sheet edge above
+     * 16384 px is an error naming the limit (docs/specs/scaled-export.md).
      */
-    exportAtlas(columns: number, tag?: string | null, image_name?: string | null): AtlasExport;
+    exportAtlas(columns: number, tag?: string | null, image_name?: string | null, scale?: number | null): AtlasExport;
     /**
      * The palette as a GIMP `.gpl` file called `name` (alpha dropped).
+     *
+     * Deprecated: use [`Document::export_palette`] (`exportPalette`) with
+     * format `gpl`. Kept for the public npm API (spec §17.5).
      */
     exportGpl(name: string): string;
+    /**
+     * The palette as a file: `format` is `gpl` (a GIMP palette called
+     * `name`), `hex` (Lospec), `pal` (JASC) or `png` (a one-row strip of
+     * `cell` × `cell` px swatches). `name` is used only by `gpl`, `cell`
+     * only by `png`. Errors for an unknown format, or a PNG strip of an
+     * empty palette or with `cell` 0.
+     */
+    exportPalette(format: string, name: string, cell: number): Uint8Array;
     /**
      * Encode one frame as an RGBA8 PNG.
      *
@@ -567,8 +626,13 @@ export class Document {
      * `pincel-core` message: an out-of-range frame, or a sprite the
      * renderer refuses (non-RGBA color mode, non-`Normal` blend mode,
      * group layer, linked cel).
+     *
+     * `scale` (optional, default 1) upscales the PNG by an integer factor
+     * 1–10 with nearest-neighbour (docs/specs/scaled-export.md); scale 1
+     * and no scale give the same bytes. A scale outside 1–10 or an output
+     * edge above 16384 px is an error naming the limit.
      */
-    exportPng(frame: number): Uint8Array;
+    exportPng(frame: number, scale?: number | null): Uint8Array;
     /**
      * Flatten every visible layer into one image layer (hidden layers are
      * dropped) and return the new layer's id, which also becomes the
@@ -589,8 +653,21 @@ export class Document {
     /**
      * Replace the palette with a GIMP `.gpl` file's colours and return
      * how many it holds. One undo entry. Refused for indexed documents.
+     *
+     * Deprecated: use [`Document::import_palette`] (`importPalette`),
+     * which reads `.gpl` and the other palette formats. Kept for the
+     * public npm API (spec §17.5).
      */
     importGpl(text: string): number;
+    /**
+     * Replace the palette with a palette file's colours and return how
+     * many it holds. The format — GIMP `.gpl`, Lospec `.hex`, JASC `.pal`
+     * or a PNG palette image — is detected from the content, not the file
+     * name (spec §3.7). One undo entry. Refused for indexed documents, for
+     * files without colours and above 256 colours; the palette is then
+     * unchanged.
+     */
+    importPalette(bytes: Uint8Array): number;
     /**
      * Decode PNG bytes and add them as a new image layer named `name` on
      * top of the stack, at the current frame, anchored at the canvas
@@ -938,6 +1015,13 @@ export class Document {
      * merge into one undo entry until [`Document::end_stroke`] seals it.
      */
     setFrameDuration(frame: number, duration_ms: number): void;
+    /**
+     * Set the grid's offset (`x`, `y`) and cell size (`width` ×
+     * `height`) as one undo entry; saved in the `.aseprite` header.
+     * Errors, leaving the grid unchanged, for a cell size outside
+     * 1–65535 or an offset outside −32768–32767.
+     */
+    setGrid(x: number, y: number, width: number, height: number): void;
     /**
      * Set the named layer's blend mode by name (see [`blend_mode_names`]),
      * routed through the undo bus. Emits `dirty-canvas`. Errors on an
@@ -1014,6 +1098,28 @@ export class Document {
      * rejects the write.
      */
     setSliceKey(slice_id: number, frame: number, x: number, y: number, width: number, height: number, center_x?: number | null, center_y?: number | null, center_width?: number | null, center_height?: number | null, pivot_x?: number | null, pivot_y?: number | null): void;
+    /**
+     * Mirror the gesture in progress (symmetry): every pixel it paints is
+     * also painted at its mirror images. `axis_x2` / `axis_y2` are the
+     * vertical / horizontal axis in half pixels from the left / top canvas
+     * edge (column `x` mirrors to `axis_x2 − 1 − x`); absent turns that
+     * axis off. Mirror images off the canvas are skipped unless the
+     * gesture wraps. Call it after `beginStroke` / `beginShadingStroke`
+     * and before the first [`Self::stroke_to`].
+     *
+     * Errors when no gesture is armed or it has already painted.
+     */
+    setStrokeMirror(axis_x2?: number | null, axis_y2?: number | null): void;
+    /**
+     * Let the gesture in progress wrap across the canvas edges (tiled
+     * mode): along a wrapped axis, points beyond the canvas are taken
+     * modulo the canvas size instead of skipped, and the line between two
+     * points continues at the opposite edge. Call it after `beginStroke` /
+     * `beginShadingStroke` and before the first [`Self::stroke_to`].
+     *
+     * Errors when no gesture is armed or it has already painted.
+     */
+    setStrokeWrap(x: boolean, y: boolean): void;
     /**
      * Set the playback direction of the tag at `index` by snake_case
      * name. One undo entry.
@@ -1067,14 +1173,14 @@ export class Document {
      */
     sliceKeyCenterWidth(slice_id: number, key_index: number): number;
     /**
-     * Sprite-space `x` of the key's 9-patch center, or `0` when the
-     * key has no center. Errors when `slice_id` or `key_index` is
-     * out of range.
+     * `x` of the key's 9-patch center, relative to the key's bounds
+     * origin, or `0` when the key has no center. Errors when
+     * `slice_id` or `key_index` is out of range.
      */
     sliceKeyCenterX(slice_id: number, key_index: number): number;
     /**
-     * Sprite-space `y` of the key's 9-patch center, or `0` when the
-     * key has no center.
+     * `y` of the key's 9-patch center, relative to the key's bounds
+     * origin, or `0` when the key has no center.
      */
     sliceKeyCenterY(slice_id: number, key_index: number): number;
     /**
@@ -1103,13 +1209,13 @@ export class Document {
      */
     sliceKeyHeight(slice_id: number, key_index: number): number;
     /**
-     * Sprite-space `x` of the key's pivot, or `0` when the key has
-     * no pivot.
+     * `x` of the key's pivot, relative to the key's bounds origin
+     * (may be negative), or `0` when the key has no pivot.
      */
     sliceKeyPivotX(slice_id: number, key_index: number): number;
     /**
-     * Sprite-space `y` of the key's pivot, or `0` when the key has
-     * no pivot.
+     * `y` of the key's pivot, relative to the key's bounds origin
+     * (may be negative), or `0` when the key has no pivot.
      */
     sliceKeyPivotY(slice_id: number, key_index: number): number;
     /**
@@ -1258,6 +1364,26 @@ export class Document {
      * Number of frames in the document.
      */
     readonly frameCount: number;
+    /**
+     * Grid cell height in sprite pixels (16 for a sprite without a
+     * stored grid; 0 when a file stored a zero-sized grid).
+     */
+    readonly gridHeight: number;
+    /**
+     * Grid cell width in sprite pixels (16 for a sprite without a stored
+     * grid; 0 when a file stored a zero-sized grid).
+     */
+    readonly gridWidth: number;
+    /**
+     * Grid x offset in sprite pixels (0 for a sprite without a stored
+     * grid).
+     */
+    readonly gridX: number;
+    /**
+     * Grid y offset in sprite pixels (0 for a sprite without a stored
+     * grid).
+     */
+    readonly gridY: number;
     /**
      * `true` when a non-empty marquee selection is active. See
      * [`pincel_core::Sprite::has_selection`].
@@ -1437,6 +1563,13 @@ export function blendModeNames(): string[];
  */
 export function effectNames(): string[];
 
+/**
+ * Number of [`Document`]s alive in this module (created and not yet
+ * freed). A diagnostic: tests check that closing a tab frees its document
+ * (docs/specs/document-tabs.md AC-16).
+ */
+export function openDocumentCount(): number;
+
 /**
  * A single composited frame returned to JS.
  *
@@ -1488,17 +1621,20 @@ export interface InitOutput {
     readonly document_clearSelection: (a: number) => void;
     readonly document_compose: (a: number, b: number, c: number) => [number, number, number];
     readonly document_composeDirty: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
+    readonly document_composeFrame: (a: number, b: number, c: number, d: number) => [number, number, number];
     readonly document_currentFrame: (a: number) => number;
     readonly document_deleteSelection: (a: number) => [number, number, number];
     readonly document_drainEvents: (a: number) => [number, number];
     readonly document_endStroke: (a: number) => void;
-    readonly document_exportAtlas: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly document_exportAtlas: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
     readonly document_exportGpl: (a: number, b: number, c: number) => [number, number];
-    readonly document_exportPng: (a: number, b: number) => [number, number, number, number];
+    readonly document_exportPalette: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
+    readonly document_exportPng: (a: number, b: number, c: number) => [number, number, number, number];
     readonly document_frameCount: (a: number) => number;
     readonly document_hasSelection: (a: number) => number;
     readonly document_height: (a: number) => number;
     readonly document_importGpl: (a: number, b: number, c: number) => [number, number, number];
+    readonly document_importPalette: (a: number, b: number, c: number) => [number, number, number];
     readonly document_layerCount: (a: number) => number;
     readonly document_layerIdAt: (a: number, b: number) => [number, number, number];
     readonly document_layerKind: (a: number, b: number) => [number, number];
@@ -1565,35 +1701,12 @@ export interface InitOutput {
     readonly document_undoDepth: (a: number) => number;
     readonly document_width: (a: number) => number;
     readonly palettePresetNames: () => [number, number];
-    readonly document_cropToSelection: (a: number) => [number, number, number];
-    readonly document_resizeCanvas: (a: number, b: number, c: number, d: number, e: number) => [number, number];
-    readonly document_scaleImage: (a: number, b: number, c: number, d: number, e: number) => [number, number];
-    readonly document_transformCanvas: (a: number, b: number, c: number) => [number, number];
-    readonly document_transformLayer: (a: number, b: number, c: number) => [number, number];
-    readonly blendModeNames: () => [number, number];
-    readonly document_addGroup: (a: number, b: number, c: number) => [number, number, number];
-    readonly document_applyEffect: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
-    readonly document_duplicateLayer: (a: number, b: number) => [number, number, number];
-    readonly document_flattenImage: (a: number) => [number, number, number];
-    readonly document_layerBlendMode: (a: number, b: number) => [number, number];
-    readonly document_layerDepth: (a: number, b: number) => number;
-    readonly document_layerEditable: (a: number, b: number) => number;
-    readonly document_layerLocked: (a: number, b: number) => number;
-    readonly document_layerParent: (a: number, b: number) => number;
-    readonly document_layerThumbnail: (a: number, b: number, c: number, d: number) => [number, number, number];
-    readonly document_mergeDown: (a: number, b: number) => [number, number];
-    readonly document_moveLayerTo: (a: number, b: number, c: number, d: number, e: number) => [number, number];
-    readonly document_previewEffect: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
-    readonly document_reorderLayer: (a: number, b: number, c: number) => [number, number];
-    readonly document_setLayerBlendMode: (a: number, b: number, c: number, d: number) => [number, number];
-    readonly document_setLayerEditable: (a: number, b: number, c: number) => [number, number];
-    readonly document_setLayerOpacity: (a: number, b: number, c: number) => [number, number];
-    readonly effectNames: () => [number, number];
+    readonly openDocumentCount: () => number;
     readonly document_contractSelection: (a: number, b: number) => void;
-    readonly document_drawText: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number) => [number, number, number];
     readonly document_expandSelection: (a: number, b: number) => void;
+    readonly document_importPngAsLayer: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
     readonly document_invertSelection: (a: number) => void;
-    readonly document_previewText: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number) => [number, number, number];
+    readonly document_openPng: (a: number, b: number) => [number, number, number];
     readonly document_selectAll: (a: number) => void;
     readonly document_selectEllipse: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
     readonly document_selectPolygon: (a: number, b: number, c: number, d: number, e: number) => [number, number];
@@ -1601,61 +1714,94 @@ export interface InitOutput {
     readonly document_selectWand: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number];
     readonly document_selectionIsRect: (a: number) => number;
     readonly document_selectionMask: (a: number) => [number, number];
-    readonly registerFont: (a: number, b: number) => number;
     readonly __wbg_vectorizer_free: (a: number, b: number) => void;
     readonly __wbg_vectorizeresult_free: (a: number, b: number) => void;
-    readonly document_vectorizer: (a: number, b: number) => [number, number, number];
-    readonly vectorizer_trace: (a: number, b: number, c: number, d: number) => [number, number, number];
-    readonly vectorizeresult_layers: (a: number) => number;
-    readonly vectorizeresult_outlines: (a: number) => number;
-    readonly vectorizeresult_svg: (a: number) => [number, number];
-    readonly vectorizeresult_threshold: (a: number) => number;
-    readonly __wbg_copiedimage_free: (a: number, b: number) => void;
-    readonly copiedimage_height: (a: number) => number;
-    readonly copiedimage_png: (a: number) => [number, number];
-    readonly copiedimage_width: (a: number) => number;
-    readonly copiedimage_x: (a: number) => number;
-    readonly copiedimage_y: (a: number) => number;
-    readonly document_copySelection: (a: number, b: number) => [number, number, number];
-    readonly document_cutSelection: (a: number) => [number, number, number];
-    readonly document_imageKey: (a: number, b: number) => [number, number, number, number];
-    readonly document_importPngAsLayer: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
-    readonly document_openPng: (a: number, b: number) => [number, number, number];
-    readonly document_pasteLayer: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
-    readonly __wbg_animationinfo_free: (a: number, b: number) => void;
-    readonly __wbg_event_free: (a: number, b: number) => void;
-    readonly animationinfo_defaultLoops: (a: number) => number;
-    readonly animationinfo_frameCount: (a: number) => number;
-    readonly animationinfo_gifApproximated: (a: number) => number;
-    readonly animationinfo_semiTransparent: (a: number) => number;
     readonly document_addTag: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
-    readonly document_animationInfo: (a: number, b: number, c: number) => [number, number, number];
+    readonly document_applyEffect: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly document_applyGradient: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number];
     readonly document_applyShape: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number) => [number, number];
-    readonly document_beginStroke: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
-    readonly document_exportAnimation: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number, number];
     readonly document_frameDuration: (a: number, b: number) => [number, number, number];
+    readonly document_gridHeight: (a: number) => number;
+    readonly document_gridWidth: (a: number) => number;
+    readonly document_gridX: (a: number) => number;
+    readonly document_gridY: (a: number) => number;
     readonly document_onionSkinEnabled: (a: number) => number;
+    readonly document_previewEffect: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
     readonly document_removeFrame: (a: number, b: number) => [number, number];
     readonly document_removeTag: (a: number, b: number) => [number, number];
     readonly document_setFrameDuration: (a: number, b: number, c: number) => [number, number];
+    readonly document_setGrid: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly document_setOnionSkin: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly document_setTagDirection: (a: number, b: number, c: number, d: number) => [number, number];
     readonly document_setTagName: (a: number, b: number, c: number, d: number) => [number, number];
     readonly document_setTagRange: (a: number, b: number, c: number, d: number) => [number, number];
-    readonly document_strokeTo: (a: number, b: number, c: number, d: number) => [number, number];
     readonly document_tagColor: (a: number, b: number) => [number, number, number];
     readonly document_tagCount: (a: number) => number;
     readonly document_tagDirection: (a: number, b: number) => [number, number, number, number];
     readonly document_tagFrom: (a: number, b: number) => [number, number, number];
     readonly document_tagName: (a: number, b: number) => [number, number, number, number];
     readonly document_tagTo: (a: number, b: number) => [number, number, number];
+    readonly document_vectorizer: (a: number, b: number) => [number, number, number];
+    readonly effectNames: () => [number, number];
+    readonly vectorizer_trace: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly vectorizeresult_layers: (a: number) => number;
+    readonly vectorizeresult_outlines: (a: number) => number;
+    readonly vectorizeresult_svg: (a: number) => [number, number];
+    readonly vectorizeresult_threshold: (a: number) => number;
+    readonly __wbg_animationinfo_free: (a: number, b: number) => void;
+    readonly animationinfo_defaultLoops: (a: number) => number;
+    readonly animationinfo_frameCount: (a: number) => number;
+    readonly animationinfo_gifApproximated: (a: number) => number;
+    readonly animationinfo_semiTransparent: (a: number) => number;
+    readonly document_animationInfo: (a: number, b: number, c: number) => [number, number, number];
+    readonly document_exportAnimation: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number, number];
+    readonly __wbg_event_free: (a: number, b: number) => void;
     readonly event_frame: (a: number) => number;
     readonly event_height: (a: number) => number;
     readonly event_kind: (a: number) => [number, number];
+    readonly event_layer: (a: number) => number;
     readonly event_width: (a: number) => number;
     readonly event_x: (a: number) => number;
     readonly event_y: (a: number) => number;
-    readonly event_layer: (a: number) => number;
+    readonly blendModeNames: () => [number, number];
+    readonly document_addGroup: (a: number, b: number, c: number) => [number, number, number];
+    readonly document_drawText: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number) => [number, number, number];
+    readonly document_duplicateLayer: (a: number, b: number) => [number, number, number];
+    readonly document_flattenImage: (a: number) => [number, number, number];
+    readonly document_layerBlendMode: (a: number, b: number) => [number, number];
+    readonly document_layerDepth: (a: number, b: number) => number;
+    readonly document_layerEditable: (a: number, b: number) => number;
+    readonly document_layerLocked: (a: number, b: number) => number;
+    readonly document_layerParent: (a: number, b: number) => number;
+    readonly document_layerThumbnail: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly document_mergeDown: (a: number, b: number) => [number, number];
+    readonly document_moveLayerTo: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly document_previewText: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number) => [number, number, number];
+    readonly document_reorderLayer: (a: number, b: number, c: number) => [number, number];
+    readonly document_setLayerBlendMode: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly document_setLayerEditable: (a: number, b: number, c: number) => [number, number];
+    readonly document_setLayerOpacity: (a: number, b: number, c: number) => [number, number];
+    readonly registerFont: (a: number, b: number) => number;
+    readonly document_beginShadingStroke: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
+    readonly document_beginStroke: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
+    readonly document_setStrokeMirror: (a: number, b: number, c: number) => [number, number];
+    readonly document_setStrokeWrap: (a: number, b: number, c: number) => [number, number];
+    readonly document_strokeTo: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly __wbg_copiedimage_free: (a: number, b: number) => void;
+    readonly copiedimage_height: (a: number) => number;
+    readonly copiedimage_png: (a: number) => [number, number];
+    readonly copiedimage_width: (a: number) => number;
+    readonly copiedimage_x: (a: number) => number;
+    readonly copiedimage_y: (a: number) => number;
+    readonly document_copySelection: (a: number, b: number) => [number, number, number];
+    readonly document_cropToSelection: (a: number) => [number, number, number];
+    readonly document_cutSelection: (a: number) => [number, number, number];
+    readonly document_imageKey: (a: number, b: number) => [number, number, number, number];
+    readonly document_pasteLayer: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly document_resizeCanvas: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly document_scaleImage: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly document_transformCanvas: (a: number, b: number, c: number) => [number, number];
+    readonly document_transformLayer: (a: number, b: number, c: number) => [number, number];
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_free: (a: number, b: number, c: number) => void;
     readonly __externref_drop_slice: (a: number, b: number) => void;

package/pincel_wasm.js

@@ -464,9 +464,10 @@ export class Document {
      * stable across runs and monotonic. Returns the assigned id.
      *
      * Routes through the [`AddTileset`] command so the operation joins
-     * the undo / redo bus. Tile-image content starts empty (Aseprite
-     * convention: tile id `0` is the implicit empty tile); per-tile
-     * edits land alongside the Tileset Editor in M8.7.
+     * the undo / redo bus. The tileset starts with one stored, fully
+     * transparent tile `0` (Aseprite's empty tile), so the first
+     * [`Document::add_tile`] returns id `1` and no user tile is written
+     * as the empty tile (docs/specs/tilemaps.md, Decisions 2026-10-29).
      *
      * Errors when `tile_w` or `tile_h` is zero, when the existing id
      * space is exhausted (an existing tileset already uses `u32::MAX`),
@@ -587,6 +588,38 @@ export class Document {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * Fill the selection — or, without one, the active layer's cel on the
+     * current frame — with a dithered ramp from `foreground` at the drag
+     * start to `background` at the drag end, as one undo entry.
+     *
+     * - `line`: `[x0, y0, x1, y1]`, the drag's start and end sprite pixels.
+     * - `kind`: `linear` or `radial`.
+     * - `dither`: the Bayer matrix size `2`, `4` or `8`, or `0` for two
+     *   hard bands split halfway.
+     * - `foreground` / `background`: `0xRRGGBBAA`.
+     *
+     * Returns `false` — and changes nothing — for a zero-length drag.
+     * Errors (and changes nothing) on a locked layer, a document without a
+     * paintable image layer, and an indexed or grayscale sprite.
+     * @param {Int32Array} line
+     * @param {string} kind
+     * @param {number} dither
+     * @param {number} foreground
+     * @param {number} background
+     * @returns {boolean}
+     */
+    applyGradient(line, kind, dither, foreground, background) {
+        const ptr0 = passArray32ToWasm0(line, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(kind, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.document_applyGradient(this.__wbg_ptr, ptr0, len0, ptr1, len1, dither, foreground, background);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
     /**
      * Rasterize a 1-pixel-wide Bresenham line between sprite-space
      * `(x0, y0)` and `(x1, y1)` with the given non-premultiplied RGBA
@@ -749,6 +782,37 @@ export class Document {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * Start a Pencil gesture with the Shading ink: every pixel the stroke
+     * touches whose color before the stroke is exactly entry `i` of `ramp`
+     * becomes entry `i + step`, clamped to the ramp; other colors stay.
+     * Each pixel changes at most once per gesture. Continue it with
+     * [`Self::stroke_to`] and close it with `endStroke` like any stroke.
+     *
+     * - `ramp`: the colors in palette order (`0xRRGGBBAA`), at least one.
+     * - `step`: `1` (left button, toward the end) or `-1` (right button,
+     *   toward the start).
+     * - `size`, `shape`, `pixel_perfect`: as in [`Self::begin_stroke`].
+     *
+     * Errors (and starts nothing) for an empty ramp, another step, an
+     * unknown shape, a locked target layer, or a document without a
+     * paintable image layer.
+     * @param {Uint32Array} ramp
+     * @param {number} step
+     * @param {number} size
+     * @param {string} shape
+     * @param {boolean} pixel_perfect
+     */
+    beginShadingStroke(ramp, step, size, shape, pixel_perfect) {
+        const ptr0 = passArray32ToWasm0(ramp, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(shape, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.document_beginShadingStroke(this.__wbg_ptr, ptr0, len0, step, size, ptr1, len1, pixel_perfect);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * Start a Pencil / Eraser gesture on the active layer / current frame.
      * Nothing is painted until the first [`Self::stroke_to`].
@@ -838,6 +902,24 @@ export class Document {
         }
         return ComposeFrame.__wrap(ret[0]);
     }
+    /**
+     * [`Document::compose`] with the onion skin chosen per call: `onion =
+     * true` applies the configured onion skin (the same bytes as
+     * `compose`), `onion = false` leaves it out whatever
+     * [`Document::set_onion_skin`] says — for an animation preview that
+     * must never show ghosts (docs/specs/animation-preview.md).
+     * @param {number} frame
+     * @param {number} zoom
+     * @param {boolean} onion
+     * @returns {ComposeFrame}
+     */
+    composeFrame(frame, zoom, onion) {
+        const ret = wasm.document_composeFrame(this.__wbg_ptr, frame, zoom, onion);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ComposeFrame.__wrap(ret[0]);
+    }
     /**
      * Shrink the selection by `radius` pixels (may clear it).
      * @param {number} radius
@@ -1002,7 +1084,7 @@ export class Document {
      * a fresh `Uint8Array` copy. Errors surface the `pincel-core`
      * message: an unknown format or tag, a scale outside 1–10, an output
      * edge above 16384 px, a frameless sequence, or a sprite the renderer
-     * refuses (an indexed sprite).
+     * refuses (a corrupt cel or a broken linked cel).
      * @param {string} format
      * @param {string | null | undefined} tag
      * @param {number} scale
@@ -1039,17 +1121,24 @@ export class Document {
      * `meta.image` names `image_name` (default `"sheet.png"`). Errors
      * surface the underlying `pincel-core` message: zero columns, an
      * unknown tag, a frameless sprite, or anything the renderer refuses.
+     *
+     * `scale` (optional, default 1) upscales the sheet by an integer
+     * factor 1–10 with nearest-neighbour; the manifest and the `--data`
+     * JSON describe the scaled sheet (`meta.scale` stays `"1"`, as
+     * Aseprite's `--scale`). A scale outside 1–10 or a sheet edge above
+     * 16384 px is an error naming the limit (docs/specs/scaled-export.md).
      * @param {number} columns
      * @param {string | null} [tag]
      * @param {string | null} [image_name]
+     * @param {number | null} [scale]
      * @returns {AtlasExport}
      */
-    exportAtlas(columns, tag, image_name) {
+    exportAtlas(columns, tag, image_name, scale) {
         var ptr0 = isLikeNone(tag) ? 0 : passStringToWasm0(tag, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         var len0 = WASM_VECTOR_LEN;
         var ptr1 = isLikeNone(image_name) ? 0 : passStringToWasm0(image_name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         var len1 = WASM_VECTOR_LEN;
-        const ret = wasm.document_exportAtlas(this.__wbg_ptr, columns, ptr0, len0, ptr1, len1);
+        const ret = wasm.document_exportAtlas(this.__wbg_ptr, columns, ptr0, len0, ptr1, len1, isLikeNone(scale) ? Number.MAX_SAFE_INTEGER : (scale) >>> 0);
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
@@ -1057,6 +1146,9 @@ export class Document {
     }
     /**
      * The palette as a GIMP `.gpl` file called `name` (alpha dropped).
+     *
+     * Deprecated: use [`Document::export_palette`] (`exportPalette`) with
+     * format `gpl`. Kept for the public npm API (spec §17.5).
      * @param {string} name
      * @returns {string}
      */
@@ -1074,6 +1166,30 @@ export class Document {
             wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
         }
     }
+    /**
+     * The palette as a file: `format` is `gpl` (a GIMP palette called
+     * `name`), `hex` (Lospec), `pal` (JASC) or `png` (a one-row strip of
+     * `cell` × `cell` px swatches). `name` is used only by `gpl`, `cell`
+     * only by `png`. Errors for an unknown format, or a PNG strip of an
+     * empty palette or with `cell` 0.
+     * @param {string} format
+     * @param {string} name
+     * @param {number} cell
+     * @returns {Uint8Array}
+     */
+    exportPalette(format, name, cell) {
+        const ptr0 = passStringToWasm0(format, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.document_exportPalette(this.__wbg_ptr, ptr0, len0, ptr1, len1, cell);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v3 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v3;
+    }
     /**
      * Encode one frame as an RGBA8 PNG.
      *
@@ -1086,11 +1202,17 @@ export class Document {
      * `pincel-core` message: an out-of-range frame, or a sprite the
      * renderer refuses (non-RGBA color mode, non-`Normal` blend mode,
      * group layer, linked cel).
+     *
+     * `scale` (optional, default 1) upscales the PNG by an integer factor
+     * 1–10 with nearest-neighbour (docs/specs/scaled-export.md); scale 1
+     * and no scale give the same bytes. A scale outside 1–10 or an output
+     * edge above 16384 px is an error naming the limit.
      * @param {number} frame
+     * @param {number | null} [scale]
      * @returns {Uint8Array}
      */
-    exportPng(frame) {
-        const ret = wasm.document_exportPng(this.__wbg_ptr, frame);
+    exportPng(frame, scale) {
+        const ret = wasm.document_exportPng(this.__wbg_ptr, frame, isLikeNone(scale) ? Number.MAX_SAFE_INTEGER : (scale) >>> 0);
         if (ret[3]) {
             throw takeFromExternrefTable0(ret[2]);
         }
@@ -1132,6 +1254,42 @@ export class Document {
         }
         return ret[0];
     }
+    /**
+     * Grid cell height in sprite pixels (16 for a sprite without a
+     * stored grid; 0 when a file stored a zero-sized grid).
+     * @returns {number}
+     */
+    get gridHeight() {
+        const ret = wasm.document_gridHeight(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Grid cell width in sprite pixels (16 for a sprite without a stored
+     * grid; 0 when a file stored a zero-sized grid).
+     * @returns {number}
+     */
+    get gridWidth() {
+        const ret = wasm.document_gridWidth(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Grid x offset in sprite pixels (0 for a sprite without a stored
+     * grid).
+     * @returns {number}
+     */
+    get gridX() {
+        const ret = wasm.document_gridX(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Grid y offset in sprite pixels (0 for a sprite without a stored
+     * grid).
+     * @returns {number}
+     */
+    get gridY() {
+        const ret = wasm.document_gridY(this.__wbg_ptr);
+        return ret;
+    }
     /**
      * `true` when a non-empty marquee selection is active. See
      * [`pincel_core::Sprite::has_selection`].
@@ -1179,6 +1337,10 @@ export class Document {
     /**
      * Replace the palette with a GIMP `.gpl` file's colours and return
      * how many it holds. One undo entry. Refused for indexed documents.
+     *
+     * Deprecated: use [`Document::import_palette`] (`importPalette`),
+     * which reads `.gpl` and the other palette formats. Kept for the
+     * public npm API (spec §17.5).
      * @param {string} text
      * @returns {number}
      */
@@ -1191,6 +1353,25 @@ export class Document {
         }
         return ret[0] >>> 0;
     }
+    /**
+     * Replace the palette with a palette file's colours and return how
+     * many it holds. The format — GIMP `.gpl`, Lospec `.hex`, JASC `.pal`
+     * or a PNG palette image — is detected from the content, not the file
+     * name (spec §3.7). One undo entry. Refused for indexed documents, for
+     * files without colours and above 256 colours; the palette is then
+     * unchanged.
+     * @param {Uint8Array} bytes
+     * @returns {number}
+     */
+    importPalette(bytes) {
+        const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.document_importPalette(this.__wbg_ptr, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] >>> 0;
+    }
     /**
      * Decode PNG bytes and add them as a new image layer named `name` on
      * top of the stack, at the current frame, anchored at the canvas
@@ -2046,6 +2227,22 @@ export class Document {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * Set the grid's offset (`x`, `y`) and cell size (`width` ×
+     * `height`) as one undo entry; saved in the `.aseprite` header.
+     * Errors, leaving the grid unchanged, for a cell size outside
+     * 1–65535 or an offset outside −32768–32767.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} width
+     * @param {number} height
+     */
+    setGrid(x, y, width, height) {
+        const ret = wasm.document_setGrid(this.__wbg_ptr, x, y, width, height);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * Set the named layer's blend mode by name (see [`blend_mode_names`]),
      * routed through the undo bus. Emits `dirty-canvas`. Errors on an
@@ -2197,6 +2394,42 @@ export class Document {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * Mirror the gesture in progress (symmetry): every pixel it paints is
+     * also painted at its mirror images. `axis_x2` / `axis_y2` are the
+     * vertical / horizontal axis in half pixels from the left / top canvas
+     * edge (column `x` mirrors to `axis_x2 − 1 − x`); absent turns that
+     * axis off. Mirror images off the canvas are skipped unless the
+     * gesture wraps. Call it after `beginStroke` / `beginShadingStroke`
+     * and before the first [`Self::stroke_to`].
+     *
+     * Errors when no gesture is armed or it has already painted.
+     * @param {number | null} [axis_x2]
+     * @param {number | null} [axis_y2]
+     */
+    setStrokeMirror(axis_x2, axis_y2) {
+        const ret = wasm.document_setStrokeMirror(this.__wbg_ptr, isLikeNone(axis_x2) ? Number.MAX_SAFE_INTEGER : (axis_x2) >> 0, isLikeNone(axis_y2) ? Number.MAX_SAFE_INTEGER : (axis_y2) >> 0);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
+    /**
+     * Let the gesture in progress wrap across the canvas edges (tiled
+     * mode): along a wrapped axis, points beyond the canvas are taken
+     * modulo the canvas size instead of skipped, and the line between two
+     * points continues at the opposite edge. Call it after `beginStroke` /
+     * `beginShadingStroke` and before the first [`Self::stroke_to`].
+     *
+     * Errors when no gesture is armed or it has already painted.
+     * @param {boolean} x
+     * @param {boolean} y
+     */
+    setStrokeWrap(x, y) {
+        const ret = wasm.document_setStrokeWrap(this.__wbg_ptr, x, y);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * Set the playback direction of the tag at `index` by snake_case
      * name. One undo entry.
@@ -2325,9 +2558,9 @@ export class Document {
         return ret[0] >>> 0;
     }
     /**
-     * Sprite-space `x` of the key's 9-patch center, or `0` when the
-     * key has no center. Errors when `slice_id` or `key_index` is
-     * out of range.
+     * `x` of the key's 9-patch center, relative to the key's bounds
+     * origin, or `0` when the key has no center. Errors when
+     * `slice_id` or `key_index` is out of range.
      * @param {number} slice_id
      * @param {number} key_index
      * @returns {number}
@@ -2340,8 +2573,8 @@ export class Document {
         return ret[0];
     }
     /**
-     * Sprite-space `y` of the key's 9-patch center, or `0` when the
-     * key has no center.
+     * `y` of the key's 9-patch center, relative to the key's bounds
+     * origin, or `0` when the key has no center.
      * @param {number} slice_id
      * @param {number} key_index
      * @returns {number}
@@ -2420,8 +2653,8 @@ export class Document {
         return ret[0] >>> 0;
     }
     /**
-     * Sprite-space `x` of the key's pivot, or `0` when the key has
-     * no pivot.
+     * `x` of the key's pivot, relative to the key's bounds origin
+     * (may be negative), or `0` when the key has no pivot.
      * @param {number} slice_id
      * @param {number} key_index
      * @returns {number}
@@ -2434,8 +2667,8 @@ export class Document {
         return ret[0];
     }
     /**
-     * Sprite-space `y` of the key's pivot, or `0` when the key has
-     * no pivot.
+     * `y` of the key's pivot, relative to the key's bounds origin
+     * (may be negative), or `0` when the key has no pivot.
      * @param {number} slice_id
      * @param {number} key_index
      * @returns {number}
@@ -3033,6 +3266,17 @@ export function effectNames() {
     return v1;
 }
 
+/**
+ * Number of [`Document`]s alive in this module (created and not yet
+ * freed). A diagnostic: tests check that closing a tab frees its document
+ * (docs/specs/document-tabs.md AC-16).
+ * @returns {number}
+ */
+export function openDocumentCount() {
+    const ret = wasm.openDocumentCount();
+    return ret >>> 0;
+}
+
 /**
  * A single composited frame returned to JS.
  *