@amigo-labs/pincel-wasm 1.4.0 → 1.5.0

package/README.md

@@ -24,7 +24,7 @@ await init();
 const doc = new Document(64, 64);          // or Document.openAseprite(bytes)
 doc.applyTool('pencil', x, y, 0xff0000ff); // tool id, position, RGBA
 const frame = doc.compose(0, 1);           // frame index, zoom
-// frame.pixels is a Uint8ClampedArray view into wasm memory (zero-copy)
+// frame.pixels is a fresh Uint8Array copy (RGBA8, row-major) on each read
 
 const bytes = doc.saveAseprite();
 ```
@@ -36,8 +36,8 @@ changes with `doc.drainEvents()`, and release the handle with
 ## Status
 
 Phase 1. The API surface is documented in `docs/specs/pincel.md` §17.5 of
-the [repository][Pincel] and kept small and stable; `STATUS.md` there
-tracks the current milestone.
+the [repository][Pincel] and kept small and stable; open work there is
+tracked as feature specs indexed in `docs/specs/README.md`.
 
 ## License
 

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.4.0",
+  "version": "1.5.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",

package/pincel_wasm.d.ts

@@ -1,6 +1,34 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * What the animation export dialog shows before exporting.
+ */
+export class AnimationInfo {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Default play count: the tag's repeat count when non-zero, else `0`
+     * (forever).
+     */
+    readonly defaultLoops: number;
+    /**
+     * Number of frames the export contains (pingpong counts the way back).
+     */
+    readonly frameCount: number;
+    /**
+     * A frame does not fit a 256-entry GIF colour table, so a GIF export
+     * approximates its colours.
+     */
+    readonly gifApproximated: boolean;
+    /**
+     * A frame has partially transparent pixels, which GIF reduces to
+     * on / off.
+     */
+    readonly semiTransparent: boolean;
+}
+
 /**
  * An exported texture atlas: the PNG bytes plus the manifest that says
  * where each frame landed.
@@ -62,6 +90,35 @@ export class ComposeFrame {
     readonly width: number;
 }
 
+/**
+ * What Copy / Cut produced: the PNG and the canvas position it came from.
+ */
+export class CopiedImage {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The copied pixels as RGBA8 PNG bytes.
+     */
+    png(): Uint8Array;
+    /**
+     * Height of the copied region in pixels.
+     */
+    readonly height: number;
+    /**
+     * Width of the copied region in pixels.
+     */
+    readonly width: number;
+    /**
+     * Sprite-space `x` of the copied region (its paste-in-place origin).
+     */
+    readonly x: number;
+    /**
+     * Sprite-space `y` of the copied region.
+     */
+    readonly y: number;
+}
+
 /**
  * Owned Pincel document — the [`Sprite`] plus its detached cel store —
  * exposed as a JS class.
@@ -174,6 +231,12 @@ export class Document {
      * or when the command bus rejects the insert.
      */
     addTileset(name: string, tile_w: number, tile_h: number): number;
+    /**
+     * Describe the animation `tag` selects (`undefined` / `null` = every
+     * frame) for the export dialog. Errors as
+     * [`Document::export_animation`] for the tag and the renderer.
+     */
+    animationInfo(tag?: string | null): AnimationInfo;
     /**
      * Flood-fill the contiguous region of pixels matching the seed pixel
      * at sprite-space `(x, y)` with the given non-premultiplied RGBA
@@ -332,6 +395,20 @@ export class Document {
      * lands when more tools ship.
      */
     applyTool(tool_id: string, x: number, y: number, color: number): void;
+    /**
+     * Start a Pencil / Eraser gesture on the active layer / current frame.
+     * Nothing is painted until the first [`Self::stroke_to`].
+     *
+     * - `tool`: `"pencil"` paints `color` (`0xRRGGBBAA`); `"eraser"`
+     *   clears to transparent and ignores `color`.
+     * - `size`: brush size, clamped to 1–8.
+     * - `shape`: `"square"` or `"round"`.
+     * - `pixel_perfect`: drop L-corner pixels; only at size 1.
+     *
+     * Errors (and starts nothing) for an unknown tool or shape, a locked
+     * target layer, or a document without a paintable image layer.
+     */
+    beginStroke(tool: string, color: number, size: number, shape: string, pixel_perfect: boolean): void;
     /**
      * Drop the active marquee selection. No-op when no selection is
      * active; always enqueues a `selection-changed` event with zeroed
@@ -373,11 +450,27 @@ export class Document {
      * Shrink the selection by `radius` pixels (may clear it).
      */
     contractSelection(radius: number): void;
+    /**
+     * Copy (spec §5.4): the active layer at the current frame — with
+     * `merged`, the composite of all visible layers — cropped to the
+     * selection's bounding box (clipped to the canvas; the whole canvas
+     * without a selection), pixels outside a shaped selection
+     * transparent. A group or tilemap layer copies its rendered pixels.
+     * The document is unchanged.
+     */
+    copySelection(merged: boolean): CopiedImage;
     /**
      * Crop the canvas to the marquee selection (intersected with the
      * canvas). Returns `Ok(false)` when there is no usable selection.
      */
     cropToSelection(): boolean;
+    /**
+     * Cut (spec §5.4): what [`Self::copy_selection`] returns for the
+     * active layer, then clears those pixels (the whole layer without a
+     * selection) in one undo step. Refused — document unchanged — for a
+     * group or tilemap layer and for a locked layer.
+     */
+    cutSelection(): CopiedImage;
     /**
      * Clear the pixels inside the active marquee selection to transparent
      * on the active paint layer / current frame, routed through the undo
@@ -425,6 +518,20 @@ export class Document {
      * Grow the selection by `radius` pixels. No-op without a selection.
      */
     expandSelection(radius: number): void;
+    /**
+     * Encode the animation as APNG or GIF bytes.
+     *
+     * Mirrors `pincel_core::export_animation`. `format` is `"apng"` or
+     * `"gif"`; `tag`, when given, exports that tag in its direction —
+     * pass `undefined` / `null` for every frame forward. `scale` is the
+     * integer nearest-neighbour factor `1..=10`; `loops` the total play
+     * count, `0` for forever (at most 65535). The returned `Box<[u8]>` is
+     * 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).
+     */
+    exportAnimation(format: string, tag: string | null | undefined, scale: number, loops: number): Uint8Array;
     /**
      * Pack frames into a grid atlas PNG and return it with its manifest.
      *
@@ -473,6 +580,12 @@ export class Document {
      * range.
      */
     frameDuration(frame: number): number;
+    /**
+     * Clipboard identity of encoded PNG `bytes`: size plus a hash of the
+     * decoded pixels, equal for two encodings of the same image. Tells
+     * Pincel's own copy apart on the system clipboard.
+     */
+    static imageKey(bytes: Uint8Array): string;
     /**
      * Replace the palette with a GIMP `.gpl` file's colours and return
      * how many it holds. One undo entry. Refused for indexed documents.
@@ -482,8 +595,8 @@ export class Document {
      * 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
      * origin and clipped to the canvas. Returns the new layer id (which
-     * also becomes the active paint target). One undo step restores the
-     * layer's blank cel, a second removes the layer.
+     * also becomes the active paint target). One undo step removes the
+     * layer and its pixels (the Paste command, spec §5.4).
      */
     importPngAsLayer(bytes: Uint8Array, name: string): number;
     /**
@@ -639,6 +752,15 @@ export class Document {
      * callers can distinguish "unnamed" from "no such entry".
      */
     paletteName(index: number): string;
+    /**
+     * Paste (spec §5.4): decode PNG `bytes` onto a new image layer above
+     * the active one, on the current frame, top-left at sprite `(x, y)`.
+     * With `expand` the canvas first grows (anchored top-left) to cover
+     * the image there; otherwise the image is cropped to the canvas. One
+     * undo step. Returns the new layer's id, which becomes active.
+     * Refused for an indexed sprite (writing indexed cels is Phase 2).
+     */
+    pasteLayer(bytes: Uint8Array, x: number, y: number, expand: boolean): number;
     /**
      * Sample the composited color at sprite coordinates `(x, y)` on the
      * given frame. Returns the packed non-premultiplied RGBA8 value as
@@ -871,7 +993,7 @@ export class Document {
      * rect matches the previous one — the UI's RAF coalescer collapses
      * the duplicate, and the symmetric "every write emits" contract
      * matches the other paint methods. Selection state is not part of
-     * the undo stack in the M7.8 slice (see spec §5.2 / STATUS.md).
+     * the undo stack in the M7.8 slice (see spec §5.2).
      */
     setSelection(x: number, y: number, width: number, height: number): void;
     /**
@@ -1012,6 +1134,19 @@ export class Document {
      * key — the codec rejects empty key vectors).
      */
     sliceName(slice_id: number): string;
+    /**
+     * Extend the gesture to sprite-space `(x, y)`: the first call stamps
+     * the brush there, every later call stamps it at each pixel of the
+     * straight line from the previous point. Pixels outside the canvas
+     * are skipped silently. The whole gesture is one undo entry; emits a
+     * `dirty-rect` for the painted segment.
+     *
+     * `pressure` is the optional pen pressure at `(x, y)`: absent means
+     * full pressure (mouse, touch, or the Size option off). It is clamped
+     * to 0–1, and each stamp has size `max(1, round(size × p))` with `p`
+     * interpolated linearly between consecutive points.
+     */
+    strokeTo(x: number, y: number, pressure?: number | null): void;
     /**
      * Display color of the tag at `index`, packed `0xRRGGBBAA`.
      */
@@ -1384,11 +1519,57 @@ export interface InitOutput {
     readonly document_undoDepth: (a: number) => number;
     readonly document_width: (a: number) => number;
     readonly palettePresetNames: () => [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_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 event_frame: (a: number) => number;
+    readonly event_height: (a: number) => number;
+    readonly event_kind: (a: number) => [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 __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_pasteLayer: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly blendModeNames: () => [number, number];
+    readonly document_addGroup: (a: number, b: number, c: number) => [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_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_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 document_strokeTo: (a: number, b: number, c: number, d: number) => [number, number];
     readonly document_addTag: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly document_cropToSelection: (a: number) => [number, number, number];
     readonly document_frameDuration: (a: number, b: number) => [number, number, number];
     readonly document_onionSkinEnabled: (a: number) => number;
     readonly document_removeFrame: (a: number, b: number) => [number, number];
     readonly document_removeTag: (a: number, b: 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_setFrameDuration: (a: number, b: number, c: 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];
@@ -1400,26 +1581,12 @@ export interface InitOutput {
     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 __wbg_event_free: (a: number, b: number) => void;
-    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 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 document_applyEffect: (a: number, b: number, c: number, d: number, e: 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_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_invertSelection: (a: number) => void;
-    readonly document_previewEffect: (a: number, b: number, c: number, d: number, e: number, f: number) => [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_selectAll: (a: number) => void;
     readonly document_selectEllipse: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
@@ -1428,26 +1595,13 @@ 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 effectNames: () => [number, number];
     readonly registerFont: (a: number, b: number) => number;
-    readonly blendModeNames: () => [number, number];
-    readonly document_addGroup: (a: number, b: number, c: number) => [number, number, number];
-    readonly document_duplicateLayer: (a: number, b: number) => [number, number, number];
-    readonly document_flattenImage: (a: number) => [number, number, number];
+    readonly document_applyEffect: (a: number, b: number, c: number, d: number, e: 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_previewEffect: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly effectNames: () => [number, number];
     readonly document_importPngAsLayer: (a: number, b: number, c: number, d: number, e: 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_openPng: (a: number, b: 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 __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

@@ -1,5 +1,63 @@
 /* @ts-self-types="./pincel_wasm.d.ts" */
 
+/**
+ * What the animation export dialog shows before exporting.
+ */
+export class AnimationInfo {
+    static __wrap(ptr) {
+        const obj = Object.create(AnimationInfo.prototype);
+        obj.__wbg_ptr = ptr;
+        AnimationInfoFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        AnimationInfoFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_animationinfo_free(ptr, 0);
+    }
+    /**
+     * Default play count: the tag's repeat count when non-zero, else `0`
+     * (forever).
+     * @returns {number}
+     */
+    get defaultLoops() {
+        const ret = wasm.animationinfo_defaultLoops(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Number of frames the export contains (pingpong counts the way back).
+     * @returns {number}
+     */
+    get frameCount() {
+        const ret = wasm.animationinfo_frameCount(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * A frame does not fit a 256-entry GIF colour table, so a GIF export
+     * approximates its colours.
+     * @returns {boolean}
+     */
+    get gifApproximated() {
+        const ret = wasm.animationinfo_gifApproximated(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * A frame has partially transparent pixels, which GIF reduces to
+     * on / off.
+     * @returns {boolean}
+     */
+    get semiTransparent() {
+        const ret = wasm.animationinfo_semiTransparent(this.__wbg_ptr);
+        return ret !== 0;
+    }
+}
+if (Symbol.dispose) AnimationInfo.prototype[Symbol.dispose] = AnimationInfo.prototype.free;
+
 /**
  * An exported texture atlas: the PNG bytes plus the manifest that says
  * where each frame landed.
@@ -141,6 +199,71 @@ export class ComposeFrame {
 }
 if (Symbol.dispose) ComposeFrame.prototype[Symbol.dispose] = ComposeFrame.prototype.free;
 
+/**
+ * What Copy / Cut produced: the PNG and the canvas position it came from.
+ */
+export class CopiedImage {
+    static __wrap(ptr) {
+        const obj = Object.create(CopiedImage.prototype);
+        obj.__wbg_ptr = ptr;
+        CopiedImageFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        CopiedImageFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_copiedimage_free(ptr, 0);
+    }
+    /**
+     * Height of the copied region in pixels.
+     * @returns {number}
+     */
+    get height() {
+        const ret = wasm.copiedimage_height(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * The copied pixels as RGBA8 PNG bytes.
+     * @returns {Uint8Array}
+     */
+    png() {
+        const ret = wasm.copiedimage_png(this.__wbg_ptr);
+        var v1 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v1;
+    }
+    /**
+     * Width of the copied region in pixels.
+     * @returns {number}
+     */
+    get width() {
+        const ret = wasm.copiedimage_width(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Sprite-space `x` of the copied region (its paste-in-place origin).
+     * @returns {number}
+     */
+    get x() {
+        const ret = wasm.copiedimage_x(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Sprite-space `y` of the copied region.
+     * @returns {number}
+     */
+    get y() {
+        const ret = wasm.copiedimage_y(this.__wbg_ptr);
+        return ret;
+    }
+}
+if (Symbol.dispose) CopiedImage.prototype[Symbol.dispose] = CopiedImage.prototype.free;
+
 /**
  * Owned Pincel document — the [`Sprite`] plus its detached cel store —
  * exposed as a JS class.
@@ -362,6 +485,22 @@ export class Document {
         }
         return ret[0] >>> 0;
     }
+    /**
+     * Describe the animation `tag` selects (`undefined` / `null` = every
+     * frame) for the export dialog. Errors as
+     * [`Document::export_animation`] for the tag and the renderer.
+     * @param {string | null} [tag]
+     * @returns {AnimationInfo}
+     */
+    animationInfo(tag) {
+        var ptr0 = isLikeNone(tag) ? 0 : passStringToWasm0(tag, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len0 = WASM_VECTOR_LEN;
+        const ret = wasm.document_animationInfo(this.__wbg_ptr, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return AnimationInfo.__wrap(ret[0]);
+    }
     /**
      * Flood-fill the contiguous region of pixels matching the seed pixel
      * at sprite-space `(x, y)` with the given non-premultiplied RGBA
@@ -610,6 +749,34 @@ export class Document {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * Start a Pencil / Eraser gesture on the active layer / current frame.
+     * Nothing is painted until the first [`Self::stroke_to`].
+     *
+     * - `tool`: `"pencil"` paints `color` (`0xRRGGBBAA`); `"eraser"`
+     *   clears to transparent and ignores `color`.
+     * - `size`: brush size, clamped to 1–8.
+     * - `shape`: `"square"` or `"round"`.
+     * - `pixel_perfect`: drop L-corner pixels; only at size 1.
+     *
+     * Errors (and starts nothing) for an unknown tool or shape, a locked
+     * target layer, or a document without a paintable image layer.
+     * @param {string} tool
+     * @param {number} color
+     * @param {number} size
+     * @param {string} shape
+     * @param {boolean} pixel_perfect
+     */
+    beginStroke(tool, color, size, shape, pixel_perfect) {
+        const ptr0 = passStringToWasm0(tool, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(shape, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.document_beginStroke(this.__wbg_ptr, ptr0, len0, color, size, ptr1, len1, pixel_perfect);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * Drop the active marquee selection. No-op when no selection is
      * active; always enqueues a `selection-changed` event with zeroed
@@ -678,6 +845,23 @@ export class Document {
     contractSelection(radius) {
         wasm.document_contractSelection(this.__wbg_ptr, radius);
     }
+    /**
+     * Copy (spec §5.4): the active layer at the current frame — with
+     * `merged`, the composite of all visible layers — cropped to the
+     * selection's bounding box (clipped to the canvas; the whole canvas
+     * without a selection), pixels outside a shaped selection
+     * transparent. A group or tilemap layer copies its rendered pixels.
+     * The document is unchanged.
+     * @param {boolean} merged
+     * @returns {CopiedImage}
+     */
+    copySelection(merged) {
+        const ret = wasm.document_copySelection(this.__wbg_ptr, merged);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return CopiedImage.__wrap(ret[0]);
+    }
     /**
      * Crop the canvas to the marquee selection (intersected with the
      * canvas). Returns `Ok(false)` when there is no usable selection.
@@ -699,6 +883,20 @@ export class Document {
         const ret = wasm.document_currentFrame(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * Cut (spec §5.4): what [`Self::copy_selection`] returns for the
+     * active layer, then clears those pixels (the whole layer without a
+     * selection) in one undo step. Refused — document unchanged — for a
+     * group or tilemap layer and for a locked layer.
+     * @returns {CopiedImage}
+     */
+    cutSelection() {
+        const ret = wasm.document_cutSelection(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return CopiedImage.__wrap(ret[0]);
+    }
     /**
      * Clear the pixels inside the active marquee selection to transparent
      * on the active paint layer / current frame, routed through the undo
@@ -793,6 +991,37 @@ export class Document {
     expandSelection(radius) {
         wasm.document_expandSelection(this.__wbg_ptr, radius);
     }
+    /**
+     * Encode the animation as APNG or GIF bytes.
+     *
+     * Mirrors `pincel_core::export_animation`. `format` is `"apng"` or
+     * `"gif"`; `tag`, when given, exports that tag in its direction —
+     * pass `undefined` / `null` for every frame forward. `scale` is the
+     * integer nearest-neighbour factor `1..=10`; `loops` the total play
+     * count, `0` for forever (at most 65535). The returned `Box<[u8]>` is
+     * 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).
+     * @param {string} format
+     * @param {string | null | undefined} tag
+     * @param {number} scale
+     * @param {number} loops
+     * @returns {Uint8Array}
+     */
+    exportAnimation(format, tag, scale, loops) {
+        const ptr0 = passStringToWasm0(format, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        var ptr1 = isLikeNone(tag) ? 0 : passStringToWasm0(tag, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len1 = WASM_VECTOR_LEN;
+        const ret = wasm.document_exportAnimation(this.__wbg_ptr, ptr0, len0, ptr1, len1, scale, loops);
+        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;
+    }
     /**
      * Pack frames into a grid atlas PNG and return it with its manifest.
      *
@@ -920,6 +1149,33 @@ export class Document {
         const ret = wasm.document_height(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * Clipboard identity of encoded PNG `bytes`: size plus a hash of the
+     * decoded pixels, equal for two encodings of the same image. Tells
+     * Pincel's own copy apart on the system clipboard.
+     * @param {Uint8Array} bytes
+     * @returns {string}
+     */
+    static imageKey(bytes) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.document_imageKey(ptr0, len0);
+            var ptr2 = ret[0];
+            var len2 = ret[1];
+            if (ret[3]) {
+                ptr2 = 0; len2 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        }
+    }
     /**
      * Replace the palette with a GIMP `.gpl` file's colours and return
      * how many it holds. One undo entry. Refused for indexed documents.
@@ -939,8 +1195,8 @@ export class Document {
      * 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
      * origin and clipped to the canvas. Returns the new layer id (which
-     * also becomes the active paint target). One undo step restores the
-     * layer's blank cel, a second removes the layer.
+     * also becomes the active paint target). One undo step removes the
+     * layer and its pixels (the Paste command, spec §5.4).
      * @param {Uint8Array} bytes
      * @param {string} name
      * @returns {number}
@@ -1325,6 +1581,28 @@ export class Document {
             wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
         }
     }
+    /**
+     * Paste (spec §5.4): decode PNG `bytes` onto a new image layer above
+     * the active one, on the current frame, top-left at sprite `(x, y)`.
+     * With `expand` the canvas first grows (anchored top-left) to cover
+     * the image there; otherwise the image is cropped to the canvas. One
+     * undo step. Returns the new layer's id, which becomes active.
+     * Refused for an indexed sprite (writing indexed cels is Phase 2).
+     * @param {Uint8Array} bytes
+     * @param {number} x
+     * @param {number} y
+     * @param {boolean} expand
+     * @returns {number}
+     */
+    pasteLayer(bytes, x, y, expand) {
+        const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.document_pasteLayer(this.__wbg_ptr, ptr0, len0, x, y, expand);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] >>> 0;
+    }
     /**
      * Sample the composited color at sprite coordinates `(x, y)` on the
      * given frame. Returns the packed non-premultiplied RGBA8 value as
@@ -1875,7 +2153,7 @@ export class Document {
      * rect matches the previous one — the UI's RAF coalescer collapses
      * the duplicate, and the symmetric "every write emits" contract
      * matches the other paint methods. Selection state is not part of
-     * the undo stack in the M7.8 slice (see spec §5.2 / STATUS.md).
+     * the undo stack in the M7.8 slice (see spec §5.2).
      * @param {number} x
      * @param {number} y
      * @param {number} width
@@ -2231,6 +2509,27 @@ export class Document {
             wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * Extend the gesture to sprite-space `(x, y)`: the first call stamps
+     * the brush there, every later call stamps it at each pixel of the
+     * straight line from the previous point. Pixels outside the canvas
+     * are skipped silently. The whole gesture is one undo entry; emits a
+     * `dirty-rect` for the painted segment.
+     *
+     * `pressure` is the optional pen pressure at `(x, y)`: absent means
+     * full pressure (mouse, touch, or the Size option off). It is clamped
+     * to 0–1, and each stamp has size `max(1, round(size × p))` with `p`
+     * interpolated linearly between consecutive points.
+     * @param {number} x
+     * @param {number} y
+     * @param {number | null} [pressure]
+     */
+    strokeTo(x, y, pressure) {
+        const ret = wasm.document_strokeTo(this.__wbg_ptr, x, y, isLikeNone(pressure) ? Number.MAX_SAFE_INTEGER : Math.fround(pressure));
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * Display color of the tag at `index`, packed `0xRRGGBBAA`.
      * @param {number} index
@@ -2680,12 +2979,18 @@ function __wbg_get_imports() {
     };
 }
 
+const AnimationInfoFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_animationinfo_free(ptr, 1));
 const AtlasExportFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_atlasexport_free(ptr, 1));
 const ComposeFrameFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_composeframe_free(ptr, 1));
+const CopiedImageFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_copiedimage_free(ptr, 1));
 const DocumentFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_document_free(ptr, 1));