litecanvas 0.86.0 → 0.88.0

package/src/index.js

@@ -2,6 +2,7 @@
 import { setupZzFX } from './zzfx.js'
 import { defaultPalette } from './palette.js'
 import { assert } from './dev.js'
+import { version } from '../version.js'
 
 /**
  * The litecanvas constructor
@@ -22,6 +23,8 @@ export default function litecanvas(settings = {}) {
             elem.addEventListener(evt, callback, false)
             _browserEventListeners.push(() => elem.removeEventListener(evt, callback, false))
         },
+        /** @type {(c: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => void} */
+        beginPath = (c) => c.beginPath(),
         isNumber = Number.isFinite,
         zzfx = setupZzFX(root),
         /** @type {LitecanvasOptions} */
@@ -62,7 +65,7 @@ export default function litecanvas(settings = {}) {
         _deltaTime = 1 / 60,
         /** @type {number} */
         _accumulated = 0,
-        /** @type {number|null} */
+        /** @type {number?} */
         _rafid,
         /** @type {string} */
         _fontFamily = 'sans-serif',
@@ -131,9 +134,9 @@ export default function litecanvas(settings = {}) {
          * @tutorial https://gamedev.net/tutorials/programming/general-and-gameplay-programming/a-brief-introduction-to-lerp-r4954/
          */
         lerp: (start, end, t) => {
-            DEV: assert(isNumber(start), 'lerp: 1st param must be a number')
-            DEV: assert(isNumber(end), 'lerp: 2nd param must be a number')
-            DEV: assert(isNumber(t), 'lerp: 3rd param must be a number')
+            DEV: assert(isNumber(start), '[litecanvas] lerp() 1st param must be a number')
+            DEV: assert(isNumber(end), '[litecanvas] lerp() 2nd param must be a number')
+            DEV: assert(isNumber(t), '[litecanvas] lerp() 3rd param must be a number')
 
             return t * (end - start) + start
         },
@@ -172,10 +175,10 @@ export default function litecanvas(settings = {}) {
          * @returns {number} rounded number.
          */
         round: (n, precision = 0) => {
-            DEV: assert(isNumber(n), 'round: 1st param must be a number')
+            DEV: assert(isNumber(n), '[litecanvas] round() 1st param must be a number')
             DEV: assert(
                 null == precision || (isNumber(precision) && precision >= 0),
-                'round: 2nd param must be a positive number or zero'
+                '[litecanvas] round() 2nd param must be a positive number or zero'
             )
             if (!precision) {
                 return math.round(n)
@@ -193,10 +196,13 @@ export default function litecanvas(settings = {}) {
          * @returns {number}
          */
         clamp: (value, min, max) => {
-            DEV: assert(isNumber(value), 'clamp: 1st param must be a number')
-            DEV: assert(isNumber(min), 'clamp: 2nd param must be a number')
-            DEV: assert(isNumber(max), 'clamp: 3rd param must be a number')
-            DEV: assert(max > min, 'clamp: the 2nd param must be less than the 3rd param')
+            DEV: assert(isNumber(value), '[litecanvas] clamp() 1st param must be a number')
+            DEV: assert(isNumber(min), '[litecanvas] clamp() 2nd param must be a number')
+            DEV: assert(isNumber(max), '[litecanvas] clamp() 3rd param must be a number')
+            DEV: assert(
+                max > min,
+                '[litecanvas] clamp() the 2nd param must be less than the 3rd param'
+            )
 
             if (value < min) return min
             if (value > max) return max
@@ -212,10 +218,13 @@ export default function litecanvas(settings = {}) {
          * @returns {number}
          */
         wrap: (value, min, max) => {
-            DEV: assert(isNumber(value), 'wrap: 1st param must be a number')
-            DEV: assert(isNumber(min), 'wrap: 2nd param must be a number')
-            DEV: assert(isNumber(max), 'wrap: 3rd param must be a number')
-            DEV: assert(max > min, 'wrap: the 2nd param must be less than the 3rd param')
+            DEV: assert(isNumber(value), '[litecanvas] wrap() 1st param must be a number')
+            DEV: assert(isNumber(min), '[litecanvas] wrap() 2nd param must be a number')
+            DEV: assert(isNumber(max), '[litecanvas] wrap() 3rd param must be a number')
+            DEV: assert(
+                max > min,
+                '[litecanvas] wrap() the 2nd param must be less than the 3rd param'
+            )
 
             return value - (max - min) * math.floor((value - min) / (max - min))
         },
@@ -232,12 +241,15 @@ export default function litecanvas(settings = {}) {
          * @returns {number} the remapped number
          */
         map(value, start1, stop1, start2, stop2, withinBounds) {
-            DEV: assert(isNumber(value), 'map: 1st param must be a number')
-            DEV: assert(isNumber(start1), 'map: 2nd param must be a number')
-            DEV: assert(isNumber(stop1), 'map: 3rd param must be a number')
-            DEV: assert(isNumber(start2), 'map: 4th param must be a number')
-            DEV: assert(isNumber(stop2), 'map: 5th param must be a number')
-            DEV: assert(stop1 !== start1, 'map: the 2nd param must be different than the 3rd param')
+            DEV: assert(isNumber(value), '[litecanvas] map() 1st param must be a number')
+            DEV: assert(isNumber(start1), '[litecanvas] map() 2nd param must be a number')
+            DEV: assert(isNumber(stop1), '[litecanvas] map() 3rd param must be a number')
+            DEV: assert(isNumber(start2), '[litecanvas] map() 4th param must be a number')
+            DEV: assert(isNumber(stop2), '[litecanvas] map() 5th param must be a number')
+            DEV: assert(
+                stop1 !== start1,
+                '[litecanvas] map() the 2nd param must be different than the 3rd param'
+            )
 
             // prettier-ignore
             const result = ((value - start1) / (stop1 - start1)) * (stop2 - start2) + start2
@@ -255,10 +267,13 @@ export default function litecanvas(settings = {}) {
          * @returns {number} the normalized number.
          */
         norm: (value, start, stop) => {
-            DEV: assert(isNumber(value), 'norm: 1st param must be a number')
-            DEV: assert(isNumber(start), 'norm: 2nd param must be a number')
-            DEV: assert(isNumber(stop), 'norm: 3rd param must be a number')
-            DEV: assert(start !== stop, 'norm: the 2nd param must be different than the 3rd param')
+            DEV: assert(isNumber(value), '[litecanvas] norm() 1st param must be a number')
+            DEV: assert(isNumber(start), '[litecanvas] norm() 2nd param must be a number')
+            DEV: assert(isNumber(stop), '[litecanvas] norm() 3rd param must be a number')
+            DEV: assert(
+                start !== stop,
+                '[litecanvas] norm() the 2nd param must be different than the 3rd param'
+            )
 
             return instance.map(value, start, stop, 0, 1)
         },
@@ -272,12 +287,12 @@ export default function litecanvas(settings = {}) {
          * @param {(n: number) => number} [fn] - the periodic function (which default to `Math.sin`)
          */
         wave: (from, to, t, fn = Math.sin) => {
-            DEV: assert(isNumber(from), 'wave: 1st param must be a number')
-            DEV: assert(isNumber(to), 'wave: 2nd param must be a number')
-            DEV: assert(isNumber(t), 'wave: 3rd param must be a number')
+            DEV: assert(isNumber(from), '[litecanvas] wave() 1st param must be a number')
+            DEV: assert(isNumber(to), '[litecanvas] wave() 2nd param must be a number')
+            DEV: assert(isNumber(t), '[litecanvas] wave() 3rd param must be a number')
             DEV: assert(
                 'function' === typeof fn,
-                'wave: 4rd param must be a function (n: number) => number'
+                '[litecanvas] wave() 4rd param must be a function (n: number) => number'
             )
             return from + ((fn(t) + 1) / 2) * (to - from)
         },
@@ -292,9 +307,12 @@ export default function litecanvas(settings = {}) {
          * @returns {number} the random number
          */
         rand: (min = 0.0, max = 1.0) => {
-            DEV: assert(isNumber(min), 'rand: 1st param must be a number')
-            DEV: assert(isNumber(max), 'rand: 2nd param must be a number')
-            DEV: assert(max > min, 'rand: the 1st param must be less than the 2nd param')
+            DEV: assert(isNumber(min), '[litecanvas] rand() 1st param must be a number')
+            DEV: assert(isNumber(max), '[litecanvas] rand() 2nd param must be a number')
+            DEV: assert(
+                max > min,
+                '[litecanvas] rand() the 1st param must be less than the 2nd param'
+            )
 
             const a = 1664525
             const c = 1013904223
@@ -313,9 +331,12 @@ export default function litecanvas(settings = {}) {
          * @returns {number} the random number
          */
         randi: (min = 0, max = 1) => {
-            DEV: assert(isNumber(min), 'randi: 1st param must be a number')
-            DEV: assert(isNumber(max), 'randi: 2nd param must be a number')
-            DEV: assert(max > min, 'randi: the 1st param must be less than the 2nd param')
+            DEV: assert(isNumber(min), '[litecanvas] randi() 1st param must be a number')
+            DEV: assert(isNumber(max), '[litecanvas] randi() 2nd param must be a number')
+            DEV: assert(
+                max > min,
+                '[litecanvas] randi() the 1st param must be less than the 2nd param'
+            )
 
             return math.floor(instance.rand(min, max + 1))
         },
@@ -330,7 +351,7 @@ export default function litecanvas(settings = {}) {
         rseed(value) {
             DEV: assert(
                 null == value || (isNumber(value) && value >= 0),
-                'rseed: 1st param must be a positive number or zero'
+                '[litecanvas] rseed() 1st param must be a positive number or zero'
             )
 
             _rngSeed = ~~value
@@ -345,7 +366,7 @@ export default function litecanvas(settings = {}) {
         cls(color) {
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'cls: 1st param must be a positive number or zero or undefined'
+                '[litecanvas] cls() 1st param must be a positive number or zero or undefined'
             )
 
             if (null == color) {
@@ -368,23 +389,26 @@ export default function litecanvas(settings = {}) {
          * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/roundRect
          */
         rect(x, y, width, height, color, radii) {
-            DEV: assert(isNumber(x), 'rect: 1st param must be a number')
-            DEV: assert(isNumber(y), 'rect: 2nd param must be a number')
-            DEV: assert(isNumber(width) && width > 0, 'rect: 3rd param must be a positive number')
+            DEV: assert(isNumber(x), '[litecanvas] rect() 1st param must be a number')
+            DEV: assert(isNumber(y), '[litecanvas] rect() 2nd param must be a number')
+            DEV: assert(
+                isNumber(width) && width > 0,
+                '[litecanvas] rect() 3rd param must be a positive number'
+            )
             DEV: assert(
                 isNumber(height) && height >= 0,
-                'rect: 4th param must be a positive number or zero'
+                '[litecanvas] rect() 4th param must be a positive number or zero'
             )
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'rect: 5th param must be a positive number or zero'
+                '[litecanvas] rect() 5th param must be a positive number or zero'
             )
             DEV: assert(
                 null == radii || isNumber(radii) || (Array.isArray(radii) && radii.length >= 1),
-                'rect: 6th param must be a number or array of numbers'
+                '[litecanvas] rect() 6th param must be a number or array of numbers'
             )
 
-            _ctx.beginPath()
+            beginPath(_ctx)
             _ctx[radii ? 'roundRect' : 'rect'](
                 ~~x - _outline_fix,
                 ~~y - _outline_fix,
@@ -406,26 +430,26 @@ export default function litecanvas(settings = {}) {
          * @param {number|number[]} [radii] A number or list specifying the radii used to draw a rounded-borders rectangle
          */
         rectfill(x, y, width, height, color, radii) {
-            DEV: assert(isNumber(x), 'rectfill: 1st param must be a number')
-            DEV: assert(isNumber(y), 'rectfill: 2nd param must be a number')
+            DEV: assert(isNumber(x), '[litecanvas] rectfill() 1st param must be a number')
+            DEV: assert(isNumber(y), '[litecanvas] rectfill() 2nd param must be a number')
             DEV: assert(
                 isNumber(width) && width >= 0,
-                'rectfill: 3rd param must be a positive number or zero'
+                '[litecanvas] rectfill() 3rd param must be a positive number or zero'
             )
             DEV: assert(
                 isNumber(height) && height >= 0,
-                'rectfill: 4th param must be a positive number or zero'
+                '[litecanvas] rectfill() 4th param must be a positive number or zero'
             )
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'rectfill: 5th param must be a positive number or zero'
+                '[litecanvas] rectfill() 5th param must be a positive number or zero'
             )
             DEV: assert(
                 null == radii || isNumber(radii) || (Array.isArray(radii) && radii.length >= 1),
-                'rectfill: 6th param must be a number or array of at least 2 numbers'
+                '[litecanvas] rectfill() 6th param must be a number or array of at least 2 numbers'
             )
 
-            _ctx.beginPath()
+            beginPath(_ctx)
             _ctx[radii ? 'roundRect' : 'rect'](~~x, ~~y, ~~width, ~~height, radii)
             instance.fill(color)
         },
@@ -439,18 +463,18 @@ export default function litecanvas(settings = {}) {
          * @param {number} [color=0] the color index
          */
         circ(x, y, radius, color) {
-            DEV: assert(isNumber(x), 'circ: 1st param must be a number')
-            DEV: assert(isNumber(y), 'circ: 2nd param must be a number')
+            DEV: assert(isNumber(x), '[litecanvas] circ() 1st param must be a number')
+            DEV: assert(isNumber(y), '[litecanvas] circ() 2nd param must be a number')
             DEV: assert(
                 isNumber(radius) && radius >= 0,
-                'circ: 3rd param must be a positive number or zero'
+                '[litecanvas] circ() 3rd param must be a positive number or zero'
             )
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'circ: 4th param must be a positive number or zero'
+                '[litecanvas] circ() 4th param must be a positive number or zero'
             )
 
-            _ctx.beginPath()
+            beginPath(_ctx)
             _ctx.arc(~~x, ~~y, ~~radius, 0, TWO_PI)
             instance.stroke(color)
         },
@@ -464,18 +488,18 @@ export default function litecanvas(settings = {}) {
          * @param {number} [color=0] the color index
          */
         circfill(x, y, radius, color) {
-            DEV: assert(isNumber(x), 'circfill: 1st param must be a number')
-            DEV: assert(isNumber(y), 'circfill: 2nd param must be a number')
+            DEV: assert(isNumber(x), '[litecanvas] circfill() 1st param must be a number')
+            DEV: assert(isNumber(y), '[litecanvas] circfill() 2nd param must be a number')
             DEV: assert(
                 isNumber(radius) && radius >= 0,
-                'circfill: 3rd param must be a positive number or zero'
+                '[litecanvas] circfill() 3rd param must be a positive number or zero'
             )
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'circfill: 4th param must be a positive number or zero'
+                '[litecanvas] circfill() 4th param must be a positive number or zero'
             )
 
-            _ctx.beginPath()
+            beginPath(_ctx)
             _ctx.arc(~~x, ~~y, ~~radius, 0, TWO_PI)
             instance.fill(color)
         },
@@ -490,22 +514,22 @@ export default function litecanvas(settings = {}) {
          * @param {number} [color=0] the color index
          */
         oval(x, y, radiusX, radiusY, color) {
-            DEV: assert(isNumber(x), 'oval: 1st param must be a number')
-            DEV: assert(isNumber(y), 'oval: 2nd param must be a number')
+            DEV: assert(isNumber(x), '[litecanvas] oval() 1st param must be a number')
+            DEV: assert(isNumber(y), '[litecanvas] oval() 2nd param must be a number')
             DEV: assert(
                 isNumber(radiusX) && radiusX >= 0,
-                'oval: 3rd param must be a positive number or zero'
+                '[litecanvas] oval() 3rd param must be a positive number or zero'
             )
             DEV: assert(
                 isNumber(radiusY) && radiusY >= 0,
-                'oval: 4th param must be a positive number or zero'
+                '[litecanvas] oval() 4th param must be a positive number or zero'
             )
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'oval: 5th param must be a positive number or zero'
+                '[litecanvas] oval() 5th param must be a positive number or zero'
             )
 
-            _ctx.beginPath()
+            beginPath(_ctx)
             _ctx.ellipse(~~x, ~~y, ~~radiusX, ~~radiusY, 0, 0, TWO_PI)
             instance.stroke(color)
         },
@@ -520,22 +544,22 @@ export default function litecanvas(settings = {}) {
          * @param {number} [color=0] the color index
          */
         ovalfill(x, y, radiusX, radiusY, color) {
-            DEV: assert(isNumber(x), 'ovalfill: 1st param must be a number')
-            DEV: assert(isNumber(y), 'ovalfill: 2nd param must be a number')
+            DEV: assert(isNumber(x), '[litecanvas] ovalfill() 1st param must be a number')
+            DEV: assert(isNumber(y), '[litecanvas] ovalfill() 2nd param must be a number')
             DEV: assert(
                 isNumber(radiusX) && radiusX >= 0,
-                'ovalfill: 3rd param must be a positive number or zero'
+                '[litecanvas] ovalfill() 3rd param must be a positive number or zero'
             )
             DEV: assert(
                 isNumber(radiusY) && radiusY >= 0,
-                'ovalfill: 4th param must be a positive number or zero'
+                '[litecanvas] ovalfill() 4th param must be a positive number or zero'
             )
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'ovalfill: 5th param must be a positive number or zero'
+                '[litecanvas] ovalfill() 5th param must be a positive number or zero'
             )
 
-            _ctx.beginPath()
+            beginPath(_ctx)
             _ctx.ellipse(~~x, ~~y, ~~radiusX, ~~radiusY, 0, 0, TWO_PI)
             instance.fill(color)
         },
@@ -550,16 +574,22 @@ export default function litecanvas(settings = {}) {
          * @param {number} [color=0] the color index
          */
         line(x1, y1, x2, y2, color) {
-            DEV: assert(isNumber(x1), 'line: 1st param must be a number')
-            DEV: assert(isNumber(y1), 'line: 2nd param must be a number')
-            DEV: assert(isNumber(x2), 'line: 3rd param must be a positive number or zero')
-            DEV: assert(isNumber(y2), 'line: 4th param must be a positive number or zero')
+            DEV: assert(isNumber(x1), '[litecanvas] line() 1st param must be a number')
+            DEV: assert(isNumber(y1), '[litecanvas] line() 2nd param must be a number')
+            DEV: assert(
+                isNumber(x2),
+                '[litecanvas] line() 3rd param must be a positive number or zero'
+            )
+            DEV: assert(
+                isNumber(y2),
+                '[litecanvas] line() 4th param must be a positive number or zero'
+            )
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'line: 5th param must be a positive number or zero'
+                '[litecanvas] line() 5th param must be a positive number or zero'
             )
 
-            _ctx.beginPath()
+            beginPath(_ctx)
 
             let xfix = _outline_fix !== 0 && ~~x1 === ~~x2 ? 0.5 : 0
             let yfix = _outline_fix !== 0 && ~~y1 === ~~y2 ? 0.5 : 0
@@ -579,7 +609,7 @@ export default function litecanvas(settings = {}) {
         linewidth(value) {
             DEV: assert(
                 isNumber(value) && ~~value > 0,
-                'linewidth: 1st param must be a positive number'
+                '[litecanvas] linewidth() 1st param must be a positive number'
             )
 
             _ctx.lineWidth = ~~value
@@ -597,9 +627,9 @@ export default function litecanvas(settings = {}) {
         linedash(segments, offset = 0) {
             DEV: assert(
                 Array.isArray(segments) && segments.length > 0,
-                'linedash: 1st param must be an array of numbers'
+                '[litecanvas] linedash() 1st param must be an array of numbers'
             )
-            DEV: assert(isNumber(offset), 'linedash: 2nd param must be a number')
+            DEV: assert(isNumber(offset), '[litecanvas] linedash() 2nd param must be a number')
 
             _ctx.setLineDash(segments)
             _ctx.lineDashOffset = offset
@@ -616,13 +646,16 @@ export default function litecanvas(settings = {}) {
          * @param {string} [fontStyle] can be "normal" (default), "italic" and/or "bold".
          */
         text(x, y, message, color = 3, fontStyle = 'normal') {
-            DEV: assert(isNumber(x), 'text: 1st param must be a number')
-            DEV: assert(isNumber(y), 'text: 2nd param must be a number')
+            DEV: assert(isNumber(x), '[litecanvas] text() 1st param must be a number')
+            DEV: assert(isNumber(y), '[litecanvas] text() 2nd param must be a number')
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'text: 4th param must be a positive number or zero'
+                '[litecanvas] text() 4th param must be a positive number or zero'
+            )
+            DEV: assert(
+                'string' === typeof fontStyle,
+                '[litecanvas] text() 5th param must be a string'
             )
-            DEV: assert('string' === typeof fontStyle, 'text: 5th param must be a string')
 
             _ctx.font = `${fontStyle} ${_fontSize}px ${_fontFamily}`
             _ctx.fillStyle = _colors[~~color % _colors.length]
@@ -635,7 +668,10 @@ export default function litecanvas(settings = {}) {
          * @param {string} family
          */
         textfont(family) {
-            DEV: assert('string' === typeof family, 'textfont: 1st param must be a string')
+            DEV: assert(
+                'string' === typeof family,
+                '[litecanvas] textfont() 1st param must be a string'
+            )
 
             _fontFamily = family
         },
@@ -646,7 +682,7 @@ export default function litecanvas(settings = {}) {
          * @param {number} size
          */
         textsize(size) {
-            DEV: assert(isNumber(size), 'textsize: 1st param must be a number')
+            DEV: assert(isNumber(size), '[litecanvas] textsize() 1st param must be a number')
 
             _fontSize = size
         },
@@ -662,14 +698,14 @@ export default function litecanvas(settings = {}) {
         textalign(align, baseline) {
             DEV: assert(
                 null == align || ['left', 'right', 'center', 'start', 'end'].includes(align),
-                'textalign: 1st param must be null or one of the following strings: center, left, right, start or end.'
+                '[litecanvas] textalign() 1st param must be null or one of the following strings: center, left, right, start or end.'
             )
             DEV: assert(
                 null == baseline ||
                     ['top', 'bottom', 'middle', 'hanging', 'alphabetic', 'ideographic'].includes(
                         baseline
                     ),
-                'textalign: 2nd param must be null or one of the following strings: middle, top, bottom, hanging, alphabetic or ideographic.'
+                '[litecanvas] textalign() 2nd param must be null or one of the following strings: middle, top, bottom, hanging, alphabetic or ideographic.'
             )
 
             if (align) _ctx.textAlign = align
@@ -685,8 +721,8 @@ export default function litecanvas(settings = {}) {
          * @param {OffscreenCanvas|HTMLImageElement|HTMLCanvasElement} source
          */
         image(x, y, source) {
-            DEV: assert(isNumber(x), 'image: 1st param must be a number')
-            DEV: assert(isNumber(y), 'image: 2nd param must be a number')
+            DEV: assert(isNumber(x), '[litecanvas] image() 1st param must be a number')
+            DEV: assert(isNumber(y), '[litecanvas] image() 2nd param must be a number')
 
             _ctx.drawImage(source, ~~x, ~~y)
         },
@@ -704,22 +740,25 @@ export default function litecanvas(settings = {}) {
          * @see https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas
          */
         paint(width, height, drawing, options = {}) {
-            DEV: assert(isNumber(width) && width >= 1, 'paint: 1st param must be a positive number')
+            DEV: assert(
+                isNumber(width) && width >= 1,
+                '[litecanvas] paint() 1st param must be a positive number'
+            )
             DEV: assert(
                 isNumber(height) && height >= 1,
-                'paint: 2nd param must be a positive number'
+                '[litecanvas] paint() 2nd param must be a positive number'
             )
             DEV: assert(
                 'function' === typeof drawing || Array.isArray(drawing),
-                'paint: 3rd param must be a function or array'
+                '[litecanvas] paint() 3rd param must be a function or array'
             )
             DEV: assert(
                 (options && null == options.scale) || isNumber(options.scale),
-                'paint: 4th param (options.scale) must be a number'
+                '[litecanvas] paint() 4th param (options.scale) must be a number'
             )
             DEV: assert(
                 (options && null == options.canvas) || options.canvas instanceof OffscreenCanvas,
-                'paint: 4th param (options.canvas) must be an OffscreenCanvas'
+                '[litecanvas] paint() 4th param (options.canvas) must be an OffscreenCanvas'
             )
 
             const /** @type {OffscreenCanvas} */
@@ -796,8 +835,8 @@ export default function litecanvas(settings = {}) {
          * @param {number} y
          */
         translate: (x, y) => {
-            DEV: assert(isNumber(x), 'translate: 1st param must be a number')
-            DEV: assert(isNumber(y), 'translate: 2nd param must be a number')
+            DEV: assert(isNumber(x), '[litecanvas] translate() 1st param must be a number')
+            DEV: assert(isNumber(y), '[litecanvas] translate() 2nd param must be a number')
 
             return _ctx.translate(~~x, ~~y)
         },
@@ -809,8 +848,8 @@ export default function litecanvas(settings = {}) {
          * @param {number} [y]
          */
         scale: (x, y) => {
-            DEV: assert(isNumber(x), 'scale: 1st param must be a number')
-            DEV: assert(null == y || isNumber(y), 'scale: 2nd param must be a number')
+            DEV: assert(isNumber(x), '[litecanvas] scale() 1st param must be a number')
+            DEV: assert(null == y || isNumber(y), '[litecanvas] scale() 2nd param must be a number')
 
             return _ctx.scale(x, y || x)
         },
@@ -821,7 +860,7 @@ export default function litecanvas(settings = {}) {
          * @param {number} radians
          */
         rotate: (radians) => {
-            DEV: assert(isNumber(radians), 'rotate: 1st param must be a number')
+            DEV: assert(isNumber(radians), '[litecanvas] rotate() 1st param must be a number')
 
             return _ctx.rotate(radians)
         },
@@ -833,89 +872,56 @@ export default function litecanvas(settings = {}) {
          * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalAlpha
          */
         alpha(value) {
-            DEV: assert(isNumber(value), 'alpha: 1st param must be a number')
+            DEV: assert(isNumber(value), '[litecanvas] alpha() 1st param must be a number')
 
             _ctx.globalAlpha = instance.clamp(value, 0, 1)
         },
 
         /**
-         * Returns a newly instantiated Path2D object, optionally with another
-         * path as an argument (creates a copy), or optionally with a string
-         * consisting of SVG path data.
-         *
-         * @param {Path2D|string} [arg]
-         * @returns Path2D
-         * @see https://developer.mozilla.org/en-US/docs/Web/API/Path2D/Path2D
-         */
-        path: (arg) => {
-            DEV: assert(
-                null == arg || 'string' === typeof arg || arg instanceof Path2D,
-                'path: 1st param must be a string or a Path2D instance'
-            )
-
-            return new Path2D(arg)
-        },
-
-        /**
-         * Fills the current or given path with a given color.
+         * Fills the current path with a given color.
          *
          * @param {number} [color=0]
-         * @param {Path2D} [path]
          */
-        fill(color, path) {
+        fill(color) {
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'fill: 1st param must be a positive number or zero'
-            )
-            DEV: assert(
-                null == path || path instanceof Path2D,
-                'fill: 2nd param must be a Path2D instance'
+                '[litecanvas] fill() 1st param must be a positive number or zero'
             )
 
             _ctx.fillStyle = _colors[~~color % _colors.length]
-            if (path) {
-                _ctx.fill(path)
-            } else {
-                _ctx.fill()
-            }
+            _ctx.fill()
         },
 
         /**
-         * Outlines the current or given path with a given color.
+         * Outlines the current path with a given color.
          *
          * @param {number} [color=0]
-         * @param {Path2D} [path]
          */
-        stroke(color, path) {
+        stroke(color) {
             DEV: assert(
                 null == color || (isNumber(color) && color >= 0),
-                'stroke: 1st param must be a positive number or zero'
-            )
-            DEV: assert(
-                null == path || path instanceof Path2D,
-                'stroke: 2nd param must be a Path2D instance'
+                '[litecanvas] stroke() 1st param must be a positive number or zero'
             )
 
             _ctx.strokeStyle = _colors[~~color % _colors.length]
-            if (path) {
-                _ctx.stroke(path)
-            } else {
-                _ctx.stroke()
-            }
+            _ctx.stroke()
         },
 
         /**
-         * Turn given path into a clipping region.
+         * Turns a path (in the callback) into the current clipping region.
          *
-         * Note: always call `push()` before and `pop()` after.
-         *
-         * @param {Path2D} path
+         * @param {clipCallback} callback
          * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/clip
          */
-        clip(path) {
-            DEV: assert(path instanceof Path2D, 'clip: 1st param must be a Path2D instance')
+        clip(callback) {
+            DEV: assert(
+                'function' === typeof callback,
+                '[litecanvas] clip() 1st param must be a function'
+            )
 
-            _ctx.clip(path)
+            beginPath(_ctx)
+            callback(_ctx)
+            _ctx.clip()
         },
 
         /** SOUND API */
@@ -933,10 +939,10 @@ export default function litecanvas(settings = {}) {
         sfx(zzfxParams, pitchSlide = 0, volumeFactor = 1) {
             DEV: assert(
                 null == zzfxParams || Array.isArray(zzfxParams),
-                'sfx: 1st param must be an array'
+                '[litecanvas] sfx() 1st param must be an array'
             )
-            DEV: assert(isNumber(pitchSlide), 'sfx: 2nd param must be a number')
-            DEV: assert(isNumber(volumeFactor), 'sfx: 3rd param must be a number')
+            DEV: assert(isNumber(pitchSlide), '[litecanvas] sfx() 2nd param must be a number')
+            DEV: assert(isNumber(volumeFactor), '[litecanvas] sfx() 3rd param must be a number')
 
             if (
                 // @ts-ignore
@@ -967,7 +973,7 @@ export default function litecanvas(settings = {}) {
          * @param {number} value
          */
         volume(value) {
-            DEV: assert(isNumber(value), 'volume: 1st param must be a number')
+            DEV: assert(isNumber(value), '[litecanvas] volume() 1st param must be a number')
 
             // @ts-ignore
             root.zzfxV = value
@@ -980,14 +986,21 @@ export default function litecanvas(settings = {}) {
          * @returns {HTMLCanvasElement}
          */
         canvas: () => _canvas,
+
         /**
          * Prepares a plugin to be loaded
          *
          * @param {pluginCallback} callback
          */
         use(callback, config = {}) {
-            DEV: assert('function' === typeof callback, 'use: 1st param must be a function')
-            DEV: assert('object' === typeof config, 'use: 2nd param must be an object')
+            DEV: assert(
+                'function' === typeof callback,
+                '[litecanvas] use() 1st param must be a function'
+            )
+            DEV: assert(
+                'object' === typeof config,
+                '[litecanvas] use() 2nd param must be an object'
+            )
 
             if (_initialized) {
                 // load the plugin now
@@ -1006,8 +1019,14 @@ export default function litecanvas(settings = {}) {
          * @returns {Function} a function to remove the listener
          */
         listen(eventName, callback) {
-            DEV: assert('string' === typeof eventName, 'listen: 1st param must be a string')
-            DEV: assert('function' === typeof callback, 'listen: 2nd param must be a function')
+            DEV: assert(
+                'string' === typeof eventName,
+                '[litecanvas] listen() 1st param must be a string'
+            )
+            DEV: assert(
+                'function' === typeof callback,
+                '[litecanvas] listen() 2nd param must be a function'
+            )
 
             eventName = eventName.toLowerCase()
 
@@ -1028,7 +1047,10 @@ export default function litecanvas(settings = {}) {
          * @param {*} [arg4] any data to be passed over the listeners
          */
         emit(eventName, arg1, arg2, arg3, arg4) {
-            DEV: assert('string' === typeof eventName, 'emit: 1st param must be a string')
+            DEV: assert(
+                'string' === typeof eventName,
+                '[litecanvas] emit() 1st param must be a string'
+            )
             if (_initialized) {
                 eventName = eventName.toLowerCase()
 
@@ -1046,7 +1068,7 @@ export default function litecanvas(settings = {}) {
         pal(colors = defaultPalette) {
             DEV: assert(
                 Array.isArray(colors) && colors.length > 0,
-                'pal: 1st param must be a array of strings'
+                '[litecanvas] pal() 1st param must be a array of strings'
             )
             _colors = colors
         },
@@ -1058,7 +1080,7 @@ export default function litecanvas(settings = {}) {
          * @param {*} value
          */
         def(key, value) {
-            DEV: assert('string' === typeof key, 'def: 1st param must be a string')
+            DEV: assert('string' === typeof key, '[litecanvas] def() 1st param must be a string')
             DEV: if (null == value) {
                 console.warn(`def: key "${key}" was defined as ${value} but now is null`)
             }
@@ -1079,7 +1101,7 @@ export default function litecanvas(settings = {}) {
         timescale(value) {
             DEV: assert(
                 isNumber(value) && value >= 0,
-                'timescale: 1st param must be a positive number or zero'
+                '[litecanvas] timescale() 1st param must be a positive number or zero'
             )
 
             _timeScale = value
@@ -1093,7 +1115,7 @@ export default function litecanvas(settings = {}) {
         framerate(value) {
             DEV: assert(
                 isNumber(value) && value >= 1,
-                'framerate: 1st param must be a positive number'
+                '[litecanvas] framerate() 1st param must be a positive number'
             )
 
             _deltaTime = 1 / ~~value
@@ -1106,7 +1128,7 @@ export default function litecanvas(settings = {}) {
          * @returns {any}
          */
         stat(n) {
-            DEV: assert(isNumber(n) && n >= 0, 'stat: 1st param must be a number')
+            DEV: assert(isNumber(n) && n >= 0, '[litecanvas] stat() 1st param must be a number')
 
             const list = [
                 // 0
@@ -1114,7 +1136,7 @@ export default function litecanvas(settings = {}) {
                 // 1
                 _initialized,
                 // 2
-                _rafid,
+                _deltaTime,
                 // 3
                 _scale,
                 // 4
@@ -1149,9 +1171,7 @@ export default function litecanvas(settings = {}) {
          */
         quit() {
             // stop the game loop (update & draw)
-            cancelAnimationFrame(_rafid)
-
-            _rafid = 0
+            instance.pause()
 
             // emit "quit" event to manual clean ups
             instance.emit('quit')
@@ -1176,6 +1196,32 @@ export default function litecanvas(settings = {}) {
             // unset that flag
             _initialized = false
         },
+
+        /**
+         * Pauses the engine loop (update & draw).
+         */
+        pause() {
+            cancelAnimationFrame(_rafid)
+            _rafid = 0
+        },
+
+        /**
+         * Resumes (if paused) the engine loop.
+         */
+        resume() {
+            if (!_rafid && _initialized) {
+                _rafid = raf(drawFrame)
+            }
+        },
+
+        /**
+         * Returns `true` if the engine loop is paused.
+         *
+         * @returns {boolean}
+         */
+        paused() {
+            return !_rafid
+        },
     }
 
     // prettier-ignore
@@ -1188,6 +1234,9 @@ export default function litecanvas(settings = {}) {
         // setup default event listeners
         const source = settings.loop ? settings.loop : root
         for (const event of _coreEvents.split(',')) {
+            DEV: if (root === source && source[event]) {
+                console.info(`[litecanvas] using window.${event}()`)
+            }
             if (source[event]) instance.listen(event, source[event])
         }
 
@@ -1423,7 +1472,7 @@ export default function litecanvas(settings = {}) {
                 (key) => {
                     DEV: assert(
                         null == key || 'string' === typeof key,
-                        'iskeydown: 1st param must be a string or undefined'
+                        '[litecanvas] iskeydown() 1st param must be a string or undefined'
                     )
                     return keyCheck(_keysDown, key)
                 }
@@ -1441,64 +1490,65 @@ export default function litecanvas(settings = {}) {
                 (key) => {
                     DEV: assert(
                         null == key || 'string' === typeof key,
-                        'iskeypressed: 1st param must be a string or undefined'
+                        '[litecanvas] iskeypressed() 1st param must be a string or undefined'
                     )
                     return keyCheck(_keysPress, key)
                 }
             )
         }
 
+        // start the engine
         _initialized = true
-
-        // start the game loop
         instance.emit('init', instance)
 
+        // set the default text align and baseline
+        instance.textalign('start', 'top')
+
         _lastFrameTime = performance.now()
-        _rafid = raf(drawFrame)
+        instance.resume()
     }
 
     /**
      * @param {DOMHighResTimeStamp} now
      */
     function drawFrame(now) {
+        if (!settings.animate) {
+            return instance.emit('draw')
+        }
+
         let updated = 0
+        let frameTime = (now - _lastFrameTime) / 1000
 
-        if (settings.animate) {
-            // prevents too long frames
-            _accumulated += math.min(0.1, (now - _lastFrameTime) / 1000)
-            _lastFrameTime = now
+        _lastFrameTime = now
 
+        if (frameTime < 0.1) {
+            _accumulated += frameTime
             while (_accumulated >= _deltaTime) {
                 updated++
                 instance.emit('update', _deltaTime * _timeScale, updated)
                 instance.def('T', instance.T + _deltaTime * _timeScale)
                 _accumulated -= _deltaTime
             }
-
-            // request the next frame
-            // check if the last ID exists, because
-            // quit() delete it (sets to zero)
-            if (_rafid) {
-                _rafid = raf(drawFrame)
-            }
-        } else {
-            // when the canvas is not animated
-            // we force one frame when redraws are triggered
-            updated = 1
         }
 
         if (updated) {
-            // always set default values for
-            // _ctx.textAlign and _ctx.textBaseline before draw
-            instance.textalign('start', 'top')
             instance.emit('draw')
         }
+
+        // request the next frame
+        // only when the engine loop are not paused (_rafid >= 1)
+        if (_rafid) {
+            _rafid = raf(drawFrame)
+        }
     }
 
     function setupCanvas() {
         if ('string' === typeof settings.canvas) {
             _canvas = document.querySelector(settings.canvas)
-            DEV: assert(null != _canvas, 'Litecanvas\' option "canvas" is an invalid CSS selector')
+            DEV: assert(
+                null != _canvas,
+                '[litecanvas] litecanvas() option "canvas" is an invalid CSS selector'
+            )
         } else {
             _canvas = settings.canvas
         }
@@ -1507,7 +1557,7 @@ export default function litecanvas(settings = {}) {
 
         DEV: assert(
             'CANVAS' === _canvas.tagName,
-            'Litecanvas\' option "canvas" should be a canvas element or string (CSS selector)'
+            '[litecanvas] litecanvas() option "canvas" should be a canvas element or string (CSS selector)'
         )
 
         _ctx = _canvas.getContext('2d')
@@ -1527,15 +1577,15 @@ export default function litecanvas(settings = {}) {
     function resizeCanvas() {
         DEV: assert(
             null == settings.width || (isNumber(settings.width) && settings.width > 0),
-            'Litecanvas\' option "width" should be a positive number when defined'
+            '[litecanvas] litecanvas() option "width" should be a positive number when defined'
         )
         DEV: assert(
             null == settings.height || (isNumber(settings.height) && settings.height > 0),
-            'Litecanvas\' option "height" should be a positive number when defined'
+            '[litecanvas] litecanvas() option "height" should be a positive number when defined'
         )
         DEV: assert(
             null == settings.height || (settings.width > 0 && settings.height > 0),
-            'Litecanvas\' option "width" is required when the option "height" is defined'
+            '[litecanvas] litecanvas() option "width" is required when the option "height" is defined'
         )
 
         const width = settings.width || root.innerWidth,
@@ -1601,7 +1651,7 @@ export default function litecanvas(settings = {}) {
 
         DEV: assert(
             null == pluginData || 'object' === typeof pluginData,
-            'Litecanvas plugins should return an object or nothing'
+            '[litecanvas] litecanvas() plugins should return an object or nothing'
         )
 
         for (const key in pluginData) {
@@ -1612,13 +1662,16 @@ export default function litecanvas(settings = {}) {
     if (settings.global) {
         // @ts-ignore
         if (root.ENGINE) {
-            throw new Error('two global litecanvas detected')
+            throw new Error('only one global litecanvas is allowed')
         }
         Object.assign(root, instance)
         // @ts-ignore
         root.ENGINE = instance
     }
 
+    DEV: console.info(`[litecanvas] version ${version} started`)
+    DEV: console.debug(`[litecanvas] litecanvas() options =`, settings)
+
     setupCanvas()
 
     if ('loading' === document.readyState) {