paper 0.12.20 → 0.14.0

package/dist/paper.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Paper.js v0.12.20 - The Swiss Army Knife of Vector Graphics Scripting.
+ * Paper.js v0.14.0 - The Swiss Army Knife of Vector Graphics Scripting.
  * http://paperjs.org/
  *
  * Copyright (c) 2011 - 2020, Jürg Lehni & Jonathan Puckey
@@ -9,7 +9,7 @@
  *
  * All rights reserved.
  *
- * Date: Sun Oct 18 17:04:58 2026 +0200
+ * Date: Tue Oct 20 01:20:31 2026 +0200
  *
  * This is an auto-generated type definition.
  */
@@ -38,6 +38,79 @@ declare namespace paper {
         | { from: PointLike, to: PointLike }
     )
 
+    
+    class ChangeFlag  {
+        /** 
+         * Anything affecting the appearance of an item, including GEOMETRY,
+         * STROKE, STYLE and ATTRIBUTE (except for the invisible ones: locked, name)
+         */
+        static APPEARANCE: number
+
+        /** 
+         * A change in the item's children
+         */
+        static CHILDREN: number
+
+        /** 
+         * A change of the item's place in the scene graph (removed, inserted,
+         * moved)
+         */
+        static INSERTION: number
+
+        /** 
+         * Item geometry (path, bounds)
+         */
+        static GEOMETRY: number
+
+        /** 
+         * The item's matrix has changed
+         */
+        static MATRIX: number
+
+        /** 
+         * Only segment(s) have changed, and affected curves have already been
+         * notified. This is to implement an optimization in _changed() calls
+         */
+        static SEGMENTS: number
+
+        /** 
+         * Stroke geometry (excluding color)
+         */
+        static STROKE: number
+
+        /** 
+         * Fill style or stroke color / dash
+         */
+        static STYLE: number
+
+        /** 
+         * Item attributes: visible, blendMode, locked, name, opacity, clipMask ...
+         */
+        static ATTRIBUTE: number
+
+        /** 
+         * Text content
+         */
+        static CONTENT: number
+
+        /** 
+         * Raster pixels
+         */
+        static PIXELS: number
+
+        /** 
+         * Clipping in one of the child items
+         */
+        static CLIPPING: number
+
+        /** 
+         * The view has been transformed
+         */
+        static VIEW: number
+
+
+    }
+
     /** 
      * All properties and functions that expect color values in the form
      * of instances of Color objects, also accept named colors and hex values as
@@ -262,7 +335,7 @@ declare namespace paper {
         static random(): Color
 
         /** 
-         * Returns the addition of the supplied value to both coordinates of
+         * Returns the addition of the supplied value to all components of
          * the color as a new color.
          * The object itself is not modified!
          * 
@@ -285,7 +358,7 @@ declare namespace paper {
         add(color: Color): Color
 
         /** 
-         * Returns the subtraction of the supplied value to both coordinates of
+         * Returns the subtraction of the supplied value to all components of
          * the color as a new color.
          * The object itself is not modified!
          * 
@@ -308,7 +381,7 @@ declare namespace paper {
         subtract(color: Color): Color
 
         /** 
-         * Returns the multiplication of the supplied value to both coordinates
+         * Returns the multiplication of the supplied value to all components
          * of the color as a new color.
          * The object itself is not modified!
          * 
@@ -331,7 +404,7 @@ declare namespace paper {
         multiply(color: Color): Color
 
         /** 
-         * Returns the division of the supplied value to both coordinates of
+         * Returns the division of the supplied value to all components of
          * the color as a new color.
          * The object itself is not modified!
          * 
@@ -551,7 +624,7 @@ declare namespace paper {
         /** 
          * The bounding rectangle of the curve including handles.
          */
-        handleBounds: Rectangle
+        readonly handleBounds: Rectangle
 
 
         /** 
@@ -761,7 +834,8 @@ declare namespace paper {
         isVertical(): boolean
 
         /** 
-         * Calculates the curve location at the specified offset on the curve.
+         * Calculates the curve location at the specified offset on the curve, or
+         * `null` if the offset exceeds the length of the curve.
          * 
          * @param offset - the offset on the curve
          * 
@@ -771,7 +845,7 @@ declare namespace paper {
 
         /** 
          * Calculates the curve location at the specified curve-time parameter on
-         * the curve.
+         * the curve, or `null` if the parameter lies outside of `0..1`.
          * 
          * @param time - the curve-time parameter on the curve
          * 
@@ -791,7 +865,8 @@ declare namespace paper {
          * @param start - the curve-time in relation to which the offset is
          *     determined
          * 
-         * @return the curve-time parameter at the specified location
+         * @return the curve-time parameter at the specified location, or
+         *     `null` if the offset exceeds the length of the curve
          */
         getTimeAt(offset: number, start?: number): number
 
@@ -824,7 +899,7 @@ declare namespace paper {
          * 
          * @return the curve location of the specified point
          */
-        getLocationOf(point: PointLike): CurveLocation
+        getLocationOf(point: PointLike): CurveLocation | null
 
         /** 
          * Returns the length of the path from its beginning up to up to the
@@ -834,7 +909,7 @@ declare namespace paper {
          * 
          * @return the length of the path up to the specified point
          */
-        getOffsetOf(point: PointLike): number
+        getOffsetOf(point: PointLike): number | null
 
         /** 
          * Returns the curve-time parameter of the specified point if it lies on the
@@ -846,7 +921,7 @@ declare namespace paper {
          * 
          * @return the curve-time parameter of the specified point
          */
-        getTimeOf(point: PointLike): number
+        getTimeOf(point: PointLike): number | null
 
         /** 
          * Returns the nearest location on the curve to the specified point.
@@ -1272,6 +1347,16 @@ declare namespace paper {
          */
         clipped: boolean
 
+        /** 
+         * Specifies whether the group is isolated, drawn through a temporary
+         * canvas, so that the blend modes of its children only apply within it,
+         * like CSS's `isolation: isolate`. Without it, a compositing mode such as
+         * `'destination-out'` affects everything drawn below the group, also in
+         * other layers. Groups with an {@link Item#opacity} below 1 or a
+         * {@link Item#blendMode} are isolated anyway.
+         */
+        isolated: boolean
+
 
         /** 
          * Creates a new Group item and places it at the top of the active layer.
@@ -1306,6 +1391,14 @@ declare namespace paper {
         /** 
          * If the HitResult has a {@link HitResult#type} of `'bounds'`, this
          * property describes which corner of the bounding rectangle was hit.
+         * 
+         * The names refer to the item's own bounding rectangle, transformed by its
+         * {@link Item#matrix}, which is the rectangle that the item's selection
+         * draws. On mirrored or rotated items, a handle can therefore appear
+         * elsewhere on screen than its name says, while its opposite handle and
+         * the rectangle's axes stay the ones to transform the item by. To choose
+         * a cursor, use the direction from the rectangle's center to
+         * {@link HitResult#point}, both in project coordinates.
          */
         name: string
 
@@ -1340,6 +1433,17 @@ declare namespace paper {
         point: Point
 
 
+    }
+
+    /** 
+     * A HostItem represents a node of a host document that has no
+     * counterpart in Paper.js. Its bounds come from the host, it draws nothing,
+     * and only its matrix and attributes can be changed. Hosts can extend it to
+     * expose their own node kinds, storing their properties in `_values`, and
+     * declare `_hasChildren: true` for kinds that contain other items.
+     */
+    class HostItem extends Item {
+
     }
 
     /** 
@@ -1351,6 +1455,14 @@ declare namespace paper {
      * that they inherit from Item.
      */
     class Item  {
+        /** 
+         * The key of the host's node that the item represents, in a project
+         * backed by a host document, see {@link Project#source}. It can only be
+         * set once, on an item created by a script, to register the key that
+         * the host gave its new node.
+         */
+        key: number
+
         /** 
          * The unique id of the item.
          */
@@ -1369,6 +1481,10 @@ declare namespace paper {
 
         /** 
          * The path style of the item.
+         * 
+         * Styles set on a {@link Group} or {@link Layer} are applied to the
+         * children that it contains at that moment. Items added to it later do not
+         * receive them.
          */
         style: Style
 
@@ -1397,6 +1513,14 @@ declare namespace paper {
          */
         opacity: number
 
+        /** 
+         * Specifies whether the item functions as a guide. When set to `true`, the
+         * item is drawn as usual, but left out of hit-tests and mouse
+         * interactions. Hit-tests only find guides when `options.guides` is set,
+         * and then only them, see {@link #hitTest}.
+         */
+        guide: boolean
+
         /** 
          * Specifies whether the item is selected. This will also return `true` for
          * {@link Group} items if they are partially selected, e.g. groups
@@ -1525,6 +1649,11 @@ declare namespace paper {
          */
         readonly view: View
 
+        /** 
+         * The scope that this item belongs to, through its project.
+         */
+        readonly scope: PaperScope
+
         /** 
          * The layer that this item is contained within.
          */
@@ -1539,6 +1668,11 @@ declare namespace paper {
          * The children items contained within this item. Items that define a
          * {@link #name} can also be accessed by name.
          * 
+         * Only {@link Group}, {@link Layer} and {@link CompoundPath} items can have
+         * children. On all other items, such as {@link Path}, {@link Shape},
+         * {@link Raster}, {@link SymbolItem} and {@link PointText}, `children` is
+         * `undefined`.
+         * 
          * <b>Please note:</b> The children array should not be modified directly
          * using array functions. To remove single items from the children list, use
          * {@link Item#remove}, to remove all items from the children list, use
@@ -1604,7 +1738,9 @@ declare namespace paper {
         /** 
          * Specifies whether the stroke is to be drawn taking the current affine
          * transformation into account (the default behavior), or whether it should
-         * appear as a non-scaling stroke.
+         * appear as a non-scaling stroke. On text, non-scaling strokes are exact for
+         * uniform scaling only, as the glyphs are always stroked through the
+         * transformation.
          */
         strokeScaling: boolean
 
@@ -1854,11 +1990,13 @@ declare namespace paper {
          * Group} or {@link Layer}) at the location of the specified point,
          * returning the first found hit.
          * 
-         * The options object allows you to control the specifics of the hit-
-         * test and may contain a combination of the following values:
+         * The options object allows you to control the specifics of the hit-test.
+         * Without options, `fill`, `stroke` and `segments` are hit-tested. As soon
+         * as an options object is passed, only the hit-tests that it sets to `true`
+         * are performed. It may contain a combination of the following values:
          * 
          * @option [options.tolerance={@link PaperScope#settings}.hitTolerance]
-         *     {Number} the tolerance of the hit-test
+         *     {Number} the tolerance of the hit-test, in project coordinates
          * @option options.class {Function} only hit-test against a specific item
          *     class, or any of its sub-classes, by providing the constructor
          *     function against which an `instanceof` check is performed:
@@ -1867,11 +2005,11 @@ declare namespace paper {
          * @option options.match {Function} a match function to be called for each
          *     found hit result: Return `true` to return the result, `false` to keep
          *     searching
-         * @option [options.fill=true] {Boolean} hit-test the fill of items
-         * @option [options.stroke=true] {Boolean} hit-test the stroke of path
-         *     items, taking into account the setting of stroke color and width
-         * @option [options.segments=true] {Boolean} hit-test for {@link
-         *     Segment#point} of {@link Path} items
+         * @option options.fill {Boolean} hit-test the fill of items
+         * @option options.stroke {Boolean} hit-test the stroke of path items,
+         *     taking into account the setting of stroke color and width
+         * @option options.segments {Boolean} hit-test for {@link Segment#point} of
+         *     {@link Path} items
          * @option options.curves {Boolean} hit-test the curves of path items,
          *     without taking the stroke color or width into account
          * @option options.handles {Boolean} hit-test for the handles ({@link
@@ -1884,7 +2022,7 @@ declare namespace paper {
          *     the bounding rectangle of items ({@link Item#bounds})
          * @option options.bounds {Boolean} hit-test the corners and side-centers of
          *     the bounding rectangle of items ({@link Item#bounds})
-         * @option options.guides {Boolean} hit-test items that have {@link
+         * @option options.guides {Boolean} only hit-test items that have {@link
          *     Item#guide} set to `true`
          * @option options.selected {Boolean} only hit selected items
          * 
@@ -1984,7 +2122,9 @@ declare namespace paper {
          * 
          * @param options - the criteria to match against
          * 
-         * @return the list of matching descendant items
+         * @return the list of matching descendant items, in their
+         *     stacking order from bottom to top, with each item listed before its
+         *     own descendants
          */
         getItems(options: object | Function): Item[]
 
@@ -2054,6 +2194,12 @@ declare namespace paper {
          * @option [options.embedImages=true] {Boolean} whether raster images should
          *     be embedded as base64 data inlined in the xlink:href attribute, or
          *     kept as a link to their external URL.
+         * @option [options.reuseImages=false] {Boolean} whether raster images with
+         *     the same content should only be exported once into the `<defs>`
+         *     element, and placed through `<use>` elements referencing it
+         * @option [options.idPrefix=''] {String} a prefix for the ids generated
+         *     for definitions such as gradients, clip paths and symbols, to keep
+         *     them unique when several exported SVGs are placed in one document
          * @option [options.reduceAttributes=true] {Boolean} wether to only include
          *     style attributes in the SVG output that differ from their parents,
          *     or to always include them (much faster but leading to redundancies).
@@ -2070,8 +2216,15 @@ declare namespace paper {
          * the this item's children list. Note that the item is not cleared first.
          * You can call {@link Item#removeChildren} to do so.
          * 
+         * `<symbol>` elements are imported as {@link SymbolDefinition} items, and
+         * the `<use>` elements that place them as {@link SymbolItem} items. The
+         * styles that `<use>` elements inherit don't reach the symbols' content.
+         * 
          * @option [options.expandShapes=false] {Boolean} whether imported shape
          *     items should be expanded to path items
+         * @option [options.crossOrigin] {String} the {@link Raster#crossOrigin}
+         *     value of the rasters created for `<image>` elements, to load their
+         *     images with CORS
          * @option options.onLoad {Function} the callback function to call once the
          *     SVG content is loaded from the given URL receiving two arguments: the
          *     converted `item` and the original `svg` data as a string. Only
@@ -2212,9 +2365,12 @@ declare namespace paper {
          * the child-item is moved outside and the parent is erased. Otherwise, the
          * item itself is returned unmodified.
          * 
+         * @param options - the options passed on to {@link
+         *     Path#reduce(options)}
+         * 
          * @return the reduced item
          */
-        reduce(options: any): Item
+        reduce(options?: object): Item
 
         /** 
          * Removes the item and all its children from the project. The item is not
@@ -2269,9 +2425,10 @@ declare namespace paper {
         isEmpty(recursively?: boolean): boolean
 
         /** 
-         * Checks whether the item has a fill.
+         * Checks whether the item has a visible fill, a fill color with an alpha
+         * above 0. Hit-tests also hit transparent fills, see {@link #hitTest}.
          * 
-         * @return true if the item has a fill
+         * @return true if the item has a visible fill
          */
         hasFill(): boolean
 
@@ -2306,7 +2463,8 @@ declare namespace paper {
 
         /** 
          * Checks if this item is above the specified item in the stacking order
-         * of the project.
+         * of the project. If one item is a descendant of the other, neither is
+         * above the other and `false` is returned.
          * 
          * @param item - the item to check against
          * 
@@ -2316,7 +2474,8 @@ declare namespace paper {
 
         /** 
          * Checks if the item is below the specified item in the stacking order of
-         * the project.
+         * the project. If one item is a descendant of the other, neither is below
+         * the other and `false` is returned.
          * 
          * @param item - the item to check against
          * 
@@ -2502,10 +2661,16 @@ declare namespace paper {
         localToParent(point: PointLike): Point
 
         /** 
-         * Transform the item so that its {@link #bounds} fit within the specified
-         * rectangle, without changing its aspect ratio.
+         * Transform the item so that its {@link #bounds} are centered in the
+         * specified rectangle and fitted to it as described by `fit`.
+         * 
+         * @param fit - how to fit the item, as in CSS's
+         * `object-fit`: `'contain'` fits all of it within the rectangle, `'cover'`
+         * makes it cover the whole rectangle, and `'fill'` stretches it to the
+         * rectangle, changing its aspect ratio. The deprecated `true` and `false`
+         * stand for `'cover'` and `'contain'`.
          */
-        fitBounds(rectangle: RectangleLike, fill?: boolean): void
+        fitBounds(rectangle: RectangleLike, fit?: string | boolean): void
 
         /** 
          * Attaches an event handler to the item.
@@ -2623,7 +2788,9 @@ declare namespace paper {
          * of the easing: {@values 'linear' 'easeInQuad' 'easeOutQuad'
          * 'easeInOutQuad' 'easeInCubic' 'easeOutCubic' 'easeInOutCubic'
          * 'easeInQuart' 'easeOutQuart' 'easeInOutQuart' 'easeInQuint'
-         * 'easeOutQuint' 'easeInOutQuint'}
+         * 'easeOutQuint' 'easeInOutQuint' 'easeInSine' 'easeOutSine'
+         * 'easeInOutSine' 'easeInExpo' 'easeOutExpo' 'easeInOutExpo'
+         * 'easeInCirc' 'easeOutCirc' 'easeInOutCirc'}
          * @option [options.start=true] {Boolean} whether to start tweening automatically
          * 
          * @param from - the state at the start of the tweening
@@ -3258,6 +3425,12 @@ declare namespace paper {
          *     when drawing selections
          * @option [settings.hitTolerance=0] {Number} the default tolerance for hit-
          *     tests, when no value is specified
+         * @option [settings.scaleStrokes=false] {Boolean} controls whether applying
+         *     a matrix to the content of paths and compound paths also scales their
+         *     {@link Style#strokeWidth}, by the geometric mean of the scale factors
+         *     for non-uniform scaling. Items that keep their matrix, with
+         *     {@link Item#applyMatrix} set to `false`, scale their strokes when
+         *     drawing anyway, unless {@link Style#strokeScaling} is `false`
          */
         settings: any
 
@@ -3286,6 +3459,7 @@ declare namespace paper {
          */
         tools: Tool[]
 
+        ChangeFlag: typeof ChangeFlag
         Color: typeof Color
         CompoundPath: typeof CompoundPath
         Curve: typeof Curve
@@ -3295,6 +3469,7 @@ declare namespace paper {
         GradientStop: typeof GradientStop
         Group: typeof Group
         HitResult: typeof HitResult
+        HostItem: typeof HostItem
         Item: typeof Item
         Key: typeof Key
         KeyEvent: typeof KeyEvent
@@ -3368,12 +3543,34 @@ declare namespace paper {
          */
         setup(element: HTMLCanvasElement | string | SizeLike): void
 
+        /** 
+         * Creates a canvas of the given size, or reuses one that was released
+         * internally.
+         * 
+         * @param width - the width of the canvas
+         * @param height - the height of the canvas
+         * 
+         * @return the canvas
+         */
+        createCanvas(width: number, height: number): HTMLCanvasElement
+
         /** 
          * Activates this PaperScope, so all newly created items will be placed
          * in its active project.
          */
         activate(): void
 
+        /** 
+         * Removes all projects, views and tools of this scope, along with their
+         * installed event handlers.
+         */
+        clear(): void
+
+        /** 
+         * Clears this scope and removes it from the list of scopes.
+         */
+        remove(): void
+
         /** 
          * Retrieves a PaperScope object with the given scope id.
          */
@@ -3411,6 +3608,9 @@ declare namespace paper {
          *     generation
          * @option options.source {String} the source to be used for the source-
          *     mapping, in case the code that's passed in has already been mingled.
+         * @option options.handlers {String[]} the names of further global
+         *     handlers to export next to `onFrame`, `onResize` and the tool's
+         *     handlers, for hosts that call them themselves
          * 
          * @param code - the PaperScript code
          * @param scope - the scope for which the code is executed
@@ -3508,7 +3708,10 @@ declare namespace paper {
 
         /** 
          * Creates a new path item from SVG path-data and places it at the top of
-         * the active layer.
+         * the active layer. A path holds a single sub-path: further `M` commands
+         * are ignored, and the commands that follow them continue the same path.
+         * Use {@link CompoundPath} or {@link PathItem.create} to create
+         * items with multiple sub-paths.
          * 
          * @param pathData - the SVG path-data that describes the geometry
          * of this path
@@ -3591,12 +3794,15 @@ declare namespace paper {
 
         /** 
          * Removes the segments from the specified `from` index to the `to` index
-         * from the path's {@link #segments} array.
+         * from the path's {@link #segments} array. On closed paths, `from` can be
+         * bigger than `to`, to remove the segments from `from` to the end and then
+         * from the beginning up to `to`, wrapping around the closing curve.
          * 
          * @param from - the beginning index, inclusive
          * @param to - the ending index, exclusive
          * 
-         * @return an array containing the removed segments
+         * @return an array containing the removed segments, in the
+         *     order in which they appeared along the path
          */
         removeSegments(from: number, to?: number): Segment[]
 
@@ -3640,7 +3846,7 @@ declare namespace paper {
          * 
          * @return the newly created path after splitting, if any
          */
-        splitAt(location: number | CurveLocation): Path
+        splitAt(location: number | CurveLocation): Path | null
 
         /** 
          * Joins the path with the other specified path, which will be removed in
@@ -3659,12 +3865,19 @@ declare namespace paper {
         join(path: Path, tolerance?: number): void
 
         /** 
-         * Reduces the path by removing curves that have a length of 0,
-         * and unnecessary segments between two collinear flat curves.
+         * Reduces the path by removing straight curves that have a length of 0.
+         * With `options.simplify`, it also removes straight curves that are almost
+         * 0 in length, and unnecessary segments between two collinear straight
+         * curves.
+         * 
+         * @option [options.simplify=false] {Boolean} also remove almost zero-length
+         *     curves and segments between collinear straight curves
+         * 
+         * @param options - the reduce options
          * 
          * @return the reduced path
          */
-        reduce(options: any): Path
+        reduce(options?: object): Path
 
         /** 
          * Attempts to create a new shape item with same geometry as this path item,
@@ -3689,7 +3902,7 @@ declare namespace paper {
          * 
          * @return the curve location of the specified point
          */
-        getLocationOf(point: PointLike): CurveLocation
+        getLocationOf(point: PointLike): CurveLocation | null
 
         /** 
          * Returns the length of the path from its beginning up to up to the
@@ -3699,10 +3912,11 @@ declare namespace paper {
          * 
          * @return the length of the path up to the specified point
          */
-        getOffsetOf(point: PointLike): number
+        getOffsetOf(point: PointLike): number | null
 
         /** 
-         * Returns the curve location of the specified offset on the path.
+         * Returns the curve location of the specified offset on the path, or
+         * `null` if the offset exceeds the length of the path.
          * 
          * @param offset - the offset on the path, where `0` is at
          * the beginning of the path and {@link Path#length} at the end
@@ -3911,7 +4125,10 @@ declare namespace paper {
 
         class RegularPolygon extends Path {
             /** 
-             * Creates a regular polygon shaped path item.
+             * Creates a regular polygon shaped path item. As in Illustrator, it
+             * stands on a flat bottom edge, and its segments run counterclockwise
+             * from its top vertex, or with an even number of sides, from the right
+             * end of its top edge.
              * 
              * @param center - the center point of the polygon
              * @param sides - the number of sides of the polygon
@@ -4141,7 +4358,7 @@ declare namespace paper {
          * @return the locations of all intersection between the
          *     paths
          */
-        getIntersections(path: PathItem, include?: Function): CurveLocation[]
+        getIntersections(path?: PathItem, include?: Function): CurveLocation[]
 
         /** 
          * Returns all crossings between two {@link PathItem} items as an array of
@@ -4779,6 +4996,15 @@ declare namespace paper {
          */
         modulo(point: PointLike): Point
 
+        /** 
+         * Returns a new point with both coordinates negated.
+         * PaperScript uses it for the unary minus operator.
+         * The object itself is not modified!
+         * 
+         * @return the negation of the point as a new point
+         */
+        negate(): Point
+
         /** 
          * Checks whether the point is inside the boundaries of the rectangle.
          * 
@@ -4894,6 +5120,18 @@ declare namespace paper {
          */
         abs(): Point
 
+        /** 
+         * Returns a new point with the {@link #x} and {@link #y} values clamped to
+         * the range between the given minimum and maximum points. The object
+         * itself is not modified!
+         * 
+         * @param min - the point with the smallest values
+         * @param max - the point with the largest values
+         * 
+         * @return the clamped point as a new point
+         */
+        clamp(min: PointLike, max: PointLike): Point
+
         /** 
          * Returns a new point object with the smallest {@link #x} and
          * {@link #y} of the supplied points.
@@ -4969,6 +5207,39 @@ declare namespace paper {
      * {@link PaperScope#projects} variable.
      */
     class Project  {
+        /** 
+         * The host document that the project's items come from. Setting it
+         * creates the project's layers from the source's records. All items
+         * are created as shells that load their content and children from the
+         * source on first access.
+         * 
+         * The source provides:
+         * - `getChildren(key)`, which returns the records of the children of
+         *   the node with the given key, or of the top level for `null`, as
+         *   columns: `keys`, `types` (indices into `typeNames`), `typeNames`,
+         *   `flags` (selected: 1, visible: 2, locked: 4, strokeScaling: 8,
+         *   clipMask: 64, guide: 128, empty: 256), `boxes` (bounds,
+         *   strokeBounds and roughBounds in the item's coordinates, 12 numbers
+         *   per item), and the sparse objects `names` and `matrices`.
+         * - `getItem(key)`, which returns the node's own content in the form
+         *   of {@link Item#importJSON}, without children.
+         * - `getAncestorKeys(key)`, which returns the keys from the top level
+         *   down to the node's parent.
+         */
+        source: any
+
+        /** 
+         * Specifies whether the project logs the changes of its items, to be
+         * retrieved through {@link #takeChanges}. This allows hosts that keep
+         * their own document to update only what has changed.
+         */
+        trackChanges: boolean
+
+        /** 
+         * The scope that this project belongs to.
+         */
+        readonly scope: PaperScope
+
         /** 
          * The reference to the project's view.
          */
@@ -5022,6 +5293,39 @@ declare namespace paper {
          */
         constructor(element: HTMLCanvasElement | string | SizeLike)
 
+        /** 
+         * Returns the item of the host's node with the given key, loading only
+         * the children of its ancestors.
+         * 
+         * @param key - the key of the host's node
+         * 
+         * @return the item, or `null` if the source has no such node
+         */
+        getItemByKey(key: number): Item
+
+        /** 
+         * Updates the items of changed host nodes, given in the column format
+         * of the source's `getChildren()`, with two more flags: 16 when the
+         * node's own content changed, so the item loads it again on next
+         * access, and 32 when its list of children changed, so it loads them
+         * again right away if it had loaded them, keeping the items of nodes
+         * that remain. Nodes without items are skipped.
+         * 
+         * @param columns - the records of the changed nodes
+         */
+        invalidate(columns: object): void
+
+        /** 
+         * Returns the changes logged since tracking was activated or since the
+         * last call, and clears the log. Each item is listed once, with the
+         * {@link ChangeFlag} values of all its changes combined. Removed items are
+         * listed with the `ChangeFlag.INSERTION` flag.
+         * 
+         * @return the changes as `{ item, flags }` objects, or `null`
+         *     if {link #trackChanges} is off
+         */
+        takeChanges(): object[]
+
         /** 
          * Activates this project, so all newly created items will be placed
          * in it.
@@ -5079,11 +5383,13 @@ declare namespace paper {
          * Performs a hit-test on the items contained within the project at the
          * location of the specified point.
          * 
-         * The options object allows you to control the specifics of the hit-test
-         * and may contain a combination of the following values:
+         * The options object allows you to control the specifics of the hit-test.
+         * Without options, `fill`, `stroke` and `segments` are hit-tested. As soon
+         * as an options object is passed, only the hit-tests that it sets to `true`
+         * are performed. It may contain a combination of the following values:
          * 
          * @option [options.tolerance={@link PaperScope#settings}.hitTolerance]
-         *     {Number} the tolerance of the hit-test
+         *     {Number} the tolerance of the hit-test, in project coordinates
          * @option options.class {Function} only hit-test against a specific item
          *     class, or any of its sub-classes, by providing the constructor
          *     function against which an `instanceof` check is performed:
@@ -5092,11 +5398,11 @@ declare namespace paper {
          * @option options.match {Function} a match function to be called for each
          *     found hit result: Return `true` to return the result, `false` to keep
          *     searching
-         * @option [options.fill=true] {Boolean} hit-test the fill of items
-         * @option [options.stroke=true] {Boolean} hit-test the stroke of path
-         *     items, taking into account the setting of stroke color and width
-         * @option [options.segments=true] {Boolean} hit-test for {@link
-         *     Segment#point} of {@link Path} items
+         * @option options.fill {Boolean} hit-test the fill of items
+         * @option options.stroke {Boolean} hit-test the stroke of path items,
+         *     taking into account the setting of stroke color and width
+         * @option options.segments {Boolean} hit-test for {@link Segment#point} of
+         *     {@link Path} items
          * @option options.curves {Boolean} hit-test the curves of path items,
          *     without taking the stroke color or width into account
          * @option options.handles {Boolean} hit-test for the handles ({@link
@@ -5109,7 +5415,7 @@ declare namespace paper {
          *     the bounding rectangle of items ({@link Item#bounds})
          * @option options.bounds {Boolean} hit-test the corners and side-centers of
          *     the bounding rectangle of items ({@link Item#bounds})
-         * @option options.guides {Boolean} hit-test items that have {@link
+         * @option options.guides {Boolean} only hit-test items that have {@link
          *     Item#guide} set to `true`
          * @option options.selected {Boolean} only hit selected items
          * 
@@ -5170,7 +5476,9 @@ declare namespace paper {
          * 
          * @param options - the criteria to match against
          * 
-         * @return the list of matching items contained in the project
+         * @return the list of matching items contained in the project, in
+         *     their stacking order from bottom to top, with each item listed
+         *     before its own descendants
          */
         getItems(options: object | Function): Item[]
 
@@ -5239,6 +5547,12 @@ declare namespace paper {
          * @option [options.embedImages=true] {Boolean} whether raster images should
          *     be embedded as base64 data inlined in the xlink:href attribute, or
          *     kept as a link to their external URL.
+         * @option [options.reuseImages=false] {Boolean} whether raster images with
+         *     the same content should only be exported once into the `<defs>`
+         *     element, and placed through `<use>` elements referencing it
+         * @option [options.idPrefix=''] {String} a prefix for the ids generated
+         *     for definitions such as gradients, clip paths and symbols, to keep
+         *     them unique when several exported SVGs are placed in one document
          * @option [options.reduceAttributes=true] {Boolean} wether to only include
          *     style attributes in the SVG output that differ from their parents,
          *     or to always include them (much faster but leading to redundancies).
@@ -5256,8 +5570,15 @@ declare namespace paper {
          * Note that the project is not cleared first. You can call
          * {@link Project#clear} to do so.
          * 
+         * `<symbol>` elements are imported as {@link SymbolDefinition} items, and
+         * the `<use>` elements that place them as {@link SymbolItem} items. The
+         * styles that `<use>` elements inherit don't reach the symbols' content.
+         * 
          * @option [options.expandShapes=false] {Boolean} whether imported shape
          *     items should be expanded to path items
+         * @option [options.crossOrigin] {String} the {@link Raster#crossOrigin}
+         *     value of the rasters created for `<image>` elements, to load their
+         *     images with CORS
          * @option options.onLoad {Function} the callback function to call once the
          *     SVG content is loaded from the given URL receiving two arguments: the
          *     converted `item` and the original `svg` data as a string. Only
@@ -5353,15 +5674,16 @@ declare namespace paper {
         context: CanvasRenderingContext2D
 
         /** 
-         * The source of the raster, which can be set using a DOM Image, a Canvas,
-         * a data url, a string describing the URL to load the image from, or the
-         * ID of a DOM element to get the image from (either a DOM Image or a
-         * Canvas). Reading this property will return the url of the source image or
-         * a data-url.
+         * The source of the raster, which can be set using a string describing the
+         * URL to load the image from, or a data url. Reading this property will
+         * return the url of the source image or a data-url.
+         * To set the raster to a DOM Image or a Canvas, use {@link #image} or
+         * {@link #canvas} instead. The ID of a DOM Image or Canvas element is only
+         * accepted by the constructor.
          * Note that for consistency, a {@link #onLoad} event will be triggered on
          * the raster even if the image has already finished loading before.
          */
-        source: HTMLImageElement | HTMLCanvasElement | string
+        source: string
 
         /** 
          * The crossOrigin value to be used when loading the image resource, in
@@ -5459,8 +5781,21 @@ declare namespace paper {
 
         /** 
          * Returns a Base 64 encoded `data:` URL representation of the raster.
+         * If the raster shows an image that was loaded from a `data:` URL, that
+         * URL is returned unchanged. Otherwise, the arguments are passed on to
+         * `HTMLCanvasElement#toDataURL()` of the raster's {@link #canvas}.
+         * In web-workers, where the canvas is an `OffscreenCanvas`, this is not
+         * supported, and neither are {@link #source} and exporting the raster to
+         * JSON, which rely on it. Use the canvas' asynchronous `convertToBlob()`
+         * there instead.
+         * 
+         * @param type - the image format to encode
+         * @param quality - the image quality between `0` and `1`, for
+         *     formats that use lossy compression, such as `'image/jpeg'`
+         * 
+         * @return the `data:` URL of the raster
          */
-        toDataURL(): string
+        toDataURL(type?: string, quality?: number): string
 
         /** 
          * Draws an image on the raster.
@@ -5526,8 +5861,16 @@ declare namespace paper {
         
         createImageData(size: SizeLike): ImageData
 
-        
-        getImageData(rect: RectangleLike): ImageData
+        /** 
+         * Returns the image data of the pixels within the specified rectangle, or
+         * of the whole raster if no rectangle or an empty one is passed.
+         * 
+         * @param rect - the area of the raster to get the image data
+         *     of, in pixel coordinates
+         * 
+         * @return the image data of the specified area
+         */
+        getImageData(rect?: RectangleLike): ImageData
 
         
         putImageData(data: ImageData, point: PointLike): void
@@ -5564,7 +5907,8 @@ declare namespace paper {
         height: number
 
         /** 
-         * The top-left point of the rectangle
+         * The top-left point of the rectangle. Setting it moves the whole
+         * rectangle, unlike {@link #topLeft}.
          */
         point: Point
 
@@ -5598,47 +5942,59 @@ declare namespace paper {
         bottom: number
 
         /** 
-         * The center point of the rectangle.
+         * The center point of the rectangle. Setting it moves the whole rectangle.
          */
         center: Point
 
         /** 
-         * The top-left point of the rectangle.
+         * The top-left point of the rectangle. Note that this doesn't move the
+         * whole rectangle; the bottom-right corner stays where it was.
          */
         topLeft: Point
 
         /** 
-         * The top-right point of the rectangle.
+         * The top-right point of the rectangle. Note that this doesn't move the
+         * whole rectangle; the bottom-left corner stays where it was.
          */
         topRight: Point
 
         /** 
-         * The bottom-left point of the rectangle.
+         * The bottom-left point of the rectangle. Note that this doesn't move the
+         * whole rectangle; the top-right corner stays where it was.
          */
         bottomLeft: Point
 
         /** 
-         * The bottom-right point of the rectangle.
+         * The bottom-right point of the rectangle. Note that this doesn't move the
+         * whole rectangle; the top-left corner stays where it was.
          */
         bottomRight: Point
 
         /** 
-         * The left-center point of the rectangle.
+         * The left-center point of the rectangle. Setting it moves the left hand
+         * side while the right hand side stays where it was, and moves the whole
+         * rectangle vertically.
          */
         leftCenter: Point
 
         /** 
-         * The top-center point of the rectangle.
+         * The top-center point of the rectangle. Setting it moves the top while
+         * the bottom stays where it was, and moves the whole rectangle
+         * horizontally.
          */
         topCenter: Point
 
         /** 
-         * The right-center point of the rectangle.
+         * The right-center point of the rectangle. Setting it moves the right
+         * hand side while the left hand side stays where it was, and moves the
+         * whole rectangle vertically.
          */
         rightCenter: Point
 
         /** 
-         * The bottom-center point of the rectangle.
+         * The bottom-center point of the rectangle. Setting it moves the bottom
+         * while the top stays where it was, and moves the whole rectangle
+         * horizontally.
          */
         bottomCenter: Point
 
@@ -5652,6 +6008,11 @@ declare namespace paper {
          * 
          * Paper.js draws the bounds of items with selected bounds on top of
          * your project. This is very useful when debugging.
+         * 
+         * This property is only available on the rectangle returned by
+         * {@link Item#bounds}, and the selection always shows these bounds.
+         * Rectangles returned by other getters such as {@link
+         * Item#strokeBounds} don't have it.
          */
         selected: boolean
 
@@ -6353,6 +6714,15 @@ declare namespace paper {
          */
         modulo(size: SizeLike): Size
 
+        /** 
+         * Returns a new size with both dimensions negated.
+         * PaperScript uses it for the unary minus operator.
+         * The object itself is not modified!
+         * 
+         * @return the negation of the size as a new size
+         */
+        negate(): Size
+
         /** 
          * Checks if this size has both the width and height set to 0.
          * 
@@ -6428,6 +6798,9 @@ declare namespace paper {
      * All properties of Style are also reflected directly in {@link Item},
      * i.e.: {@link Item#fillColor}.
      * 
+     * Styles set on a {@link Group} or {@link Layer} are applied to the children
+     * that it contains at that moment. Items added to it later do not receive them.
+     * 
      * To set multiple style properties in one go, you can pass an object to
      * {@link Item#style}. This is a convenient way to define a style once and
      * apply it to a series of items:
@@ -6463,7 +6836,9 @@ declare namespace paper {
         /** 
          * Specifies whether the stroke is to be drawn taking the current affine
          * transformation into account (the default behavior), or whether it should
-         * appear as a non-scaling stroke.
+         * appear as a non-scaling stroke. On text, non-scaling strokes are exact for
+         * uniform scaling only, as the glyphs are always stroked through the
+         * transformation.
          */
         strokeScaling: boolean
 
@@ -6539,6 +6914,13 @@ declare namespace paper {
          */
         leading: number | string
 
+        /** 
+         * The tracking of text content: the space added after each character, in
+         * thousandths of an em, as in Adobe Illustrator and InDesign. A tracking of
+         * 100 adds a tenth of the font size.
+         */
+        tracking: number
+
         /** 
          * The justification of text paragraphs.
          */
@@ -6604,7 +6986,9 @@ declare namespace paper {
 
     /** 
      * A symbol item represents an instance of a symbol which has been
-     * placed in a Paper.js project.
+     * placed in a Paper.js project. All instances share the symbol's definition,
+     * which they draw as it is: styles set on a symbol item don't reach the items
+     * of the definition, unlike `<use>` elements in SVG.
      */
     class SymbolItem extends Item {
         /** 
@@ -6658,6 +7042,13 @@ declare namespace paper {
          */
         leading: number | string
 
+        /** 
+         * The tracking of text content: the space added after each character, in
+         * thousandths of an em, as in Adobe Illustrator and InDesign. A tracking of
+         * 100 adds a tenth of the font size.
+         */
+        tracking: number
+
         /** 
          * The justification of text paragraphs.
          */
@@ -6678,6 +7069,11 @@ declare namespace paper {
      * {@link #onKeyUp}).
      */
     class Tool  {
+        /** 
+         * The scope that this tool belongs to.
+         */
+        readonly scope: PaperScope
+
         /** 
          * The minimum distance the mouse has to drag before firing the onMouseDrag
          * event, since the last onMouseDrag event.
@@ -6690,6 +7086,15 @@ declare namespace paper {
          */
         maxDistance: number
 
+        /** 
+         * The interval in milliseconds at which the onMouseDrag event fires again
+         * while the mouse button is held, also when the mouse doesn't move. The
+         * repeated events are at the last point, with a zero
+         * {@link ToolEvent#delta}. `null`, the default, or anything up to 0 turns
+         * it off.
+         */
+        eventInterval: number
+
         
         fixedDistance: number
 
@@ -6711,6 +7116,9 @@ declare namespace paper {
          * The function to be called the mouse moves within the project view. The
          * function receives a {@link ToolEvent} object which contains information
          * about the tool event.
+         * 
+         * While the mouse button is held down, the tool calls {@link #onMouseDrag}
+         * instead, if it defines one, and `onMouseMove` only otherwise.
          */
         onMouseMove: Function | null
 
@@ -6743,6 +7151,19 @@ declare namespace paper {
          */
         onKeyUp: Function | null
 
+        /** 
+         * The function to be called when the tool is activated through
+         * {@link #activate}. The function receives the previously active tool,
+         * which is the tool itself when it was already active.
+         */
+        onActivate: Function | null
+
+        /** 
+         * The function to be called when another tool is activated through
+         * {@link #activate}, while this one is active.
+         */
+        onDeactivate: Function | null
+
 
         /** 
          * Activates this tool, meaning {@link PaperScope#tool} will
@@ -6838,6 +7259,11 @@ declare namespace paper {
          */
         type: string
 
+        /** 
+         * The tool that fired the event.
+         */
+        tool: Tool
+
         /** 
          * The position of the mouse in project coordinates when the event was
          * fired.
@@ -6953,6 +7379,15 @@ declare namespace paper {
      * view, find the currently visible bounds in project coordinates, or the
      * center, both useful for constructing artwork that should appear centered on
      * screen.
+     * 
+     * If the canvas element has a `resize` or `data-paper-resize` attribute, the
+     * view adjusts its size to the size of the element whenever the window is
+     * resized. The element itself needs to be sized through CSS, e.g. with
+     * `html, body { height: 100%; }` and `canvas[resize] { width: 100%; height:
+     * 100%; }` for a canvas that fills the window. Without such CSS, the view does
+     * not follow the window, and on HiDPI screens it grows with each resize.
+     * Without the attribute, the view sets the element's CSS width and height to
+     * its own size, see {@link #viewSize}.
      */
     class View  {
         /** 
@@ -6969,6 +7404,16 @@ declare namespace paper {
          */
         readonly element: HTMLCanvasElement
 
+        /** 
+         * The project that this view displays.
+         */
+        readonly project: Project
+
+        /** 
+         * The scope that this view belongs to.
+         */
+        readonly scope: PaperScope
+
         /** 
          * The ratio between physical pixels and device-independent pixels (DIPs)
          * of the underlying canvas / device.
@@ -7007,6 +7452,7 @@ declare namespace paper {
 
         /** 
          * The view's zoom factor by which the project coordinates are magnified.
+         * Setting it to a value that isn't a positive number has no effect.
          * 
          * @see #scaling
          */
@@ -7147,6 +7593,28 @@ declare namespace paper {
          */
         onMouseLeave: Function | null
 
+        /** 
+         * The function to be called when the user presses a key on the keyboard.
+         * The function receives a {@link KeyEvent} object which contains
+         * information about the keyboard event.
+         * 
+         * If the function returns `false`, the keyboard event will be prevented
+         * from bubbling up. This can be used for example to stop the window from
+         * scrolling, when you need the user to interact with arrow keys.
+         */
+        onKeyDown: Function | null
+
+        /** 
+         * The function to be called when the user releases a key on the keyboard.
+         * The function receives a {@link KeyEvent} object which contains
+         * information about the keyboard event.
+         * 
+         * If the function returns `false`, the keyboard event will be prevented
+         * from bubbling up. This can be used for example to stop the window from
+         * scrolling, when you need the user to interact with arrow keys.
+         */
+        onKeyUp: Function | null
+
 
         /** 
          * Removes this view from the project and frees the associated element.
@@ -7155,12 +7623,16 @@ declare namespace paper {
 
         /** 
          * Updates the view if there are changes. Note that when using built-in
-         * event hanlders for interaction, animation and load events, this method is
+         * event handlers for interaction, animation and load events, this method is
          * invoked for you automatically at the end.
          * 
+         * @param force - whether to redraw the view even if nothing
+         * has changed, e.g. after a web font used by text items has finished
+         * loading
+         * 
          * @return true if the view was updated
          */
-        update(): boolean
+        update(force?: boolean): boolean
 
         /** 
          * Requests an update of the view if there are changes through the browser's
@@ -7281,6 +7753,19 @@ declare namespace paper {
          */
         transform(matrix: Matrix): void
 
+        /** 
+         * Transform the view so that the specified rectangle is centered in it
+         * and fitted to it as described by `fit`, keeping the view's rotation and
+         * mirroring.
+         * 
+         * @param rectangle - the rectangle to fit, in project
+         * coordinates
+         * @param fit - how to fit the rectangle, as in CSS's
+         * `object-fit`: `'contain'` shows all of it, and `'cover'` fills the
+         * whole view with it, cropping the parts that don't fit
+         */
+        fitBounds(rectangle: RectangleLike, fit?: string): void
+
         /** 
          * Converts the passed point from project coordinate space to view
          * coordinate space, which is measured in browser pixels in relation to the
@@ -7383,6 +7868,49 @@ declare namespace paper {
          */
         responds(type: string): boolean
 
+        /** 
+         * Handles a mouse event that the host provides, for hosts without a
+         * DOM, such as workers, or with their own event source. It runs the
+         * same handling as the DOM's mouse events: the active tool's handlers,
+         * with {@link Tool#minDistance} and the like, then those of the items
+         * under the point and of the view, including the events that Paper.js
+         * derives itself: `'mousedrag'`, `'click'`, `'doubleclick'`,
+         * `'mouseenter'` and `'mouseleave'`.
+         * 
+         * @option [options.modifiers] {Object} the state of the modifier keys,
+         *     see {@link Key#modifiers}
+         * @option [options.button=0] {Number} the mouse button
+         * @option [options.timeStamp=Date.now()] {Number} the time stamp
+         * 
+         * @param type - the type of the event: {@values 'mousedown',
+         *     'mousemove', 'mouseup'}
+         * @param point - the location of the mouse in project coordinates
+         * @param options - the details of the event
+         * 
+         * @return true if a handler prevented the event's default
+         */
+        dispatchMouseEvent(type: string, point: PointLike, options?: object): boolean
+
+        /** 
+         * Handles a key event that the host provides, for hosts without a DOM,
+         * such as workers, or with their own event source. It updates
+         * {@link Key#modifiers} and {@link Key#isDown}, and calls the
+         * view's and the active tool's handlers, as the DOM's key events do.
+         * 
+         * @option [options.character] {String} the character that the key
+         *     produces. By default, keydown takes the key itself if it is a
+         *     single character, and keyup the character of its keydown
+         * @option [options.modifiers] {Object} the state of the modifier keys,
+         *     see {@link Key#modifiers}
+         * @option [options.timeStamp=Date.now()] {Number} the time stamp
+         * 
+         * @param type - the type of the event: {@values 'keydown',
+         *     'keyup'}
+         * @param key - the key, as in {@link KeyEvent#key}
+         * @param options - the details of the event
+         */
+        dispatchKeyEvent(type: string, key: string, options?: object): void
+
     }
 }