@px-petals/roku.motion-web 1.0.0 → 1.1.0

package/script/play/play.objects.js

@@ -0,0 +1,295 @@
+/**
+ * The scripted objects of a bundle (`scriptObjects` in motion.json): nodes,
+ * drawables and path effects that run every frame, on the player's clock.
+ *
+ * One host per entry, run in the entry's `order`. A host steps (`advance`,
+ * then `update`) when it has never run, when its entry has a `clock`, or when
+ * a view-model path in its `reads` changed; any other frame it is skipped. A
+ * drawable's drawing fills the entry's `draws` slots and a path effect's
+ * result its `effect` slot, both through `outputs`, which the player merges
+ * into the slot table of every animation it draws.
+ *
+ * Rive's first advance after a view model is bound only binds: it runs no
+ * script. The first `step` here does the same; the next runs `init`,
+ * `advance` and `update` together (see `script/rive/rive.md`).
+ *
+ * Nothing is allocated in a step beyond what the hosts allocate: the draw
+ * lists, colours and the contour list of an effect are kept and reused.
+ */
+
+import { createValuesViewModel } from '../rive/context/lists/lists.values.js'
+import { assetSource, scoped } from './play.scope.js'
+
+/** @import { ScriptHost } from '../rive/host/host.js' */
+
+/** A path with no vertices, which draws nothing: what a slot holds when its drawable drew fewer paths */
+const EMPTY = { v: [], i: [], o: [], c: false }
+
+/**
+ * One entry of `scriptObjects`.
+ *
+ * @typedef {object} ObjectEntry
+ * @property {string}   id        the bytecode's name in `manifest.scripts`
+ * @property {string}   [name]
+ * @property {string}   kind      node, drawable or pathEffect
+ * @property {number}   [order]   the run order across the bundle
+ * @property {string}   [scope]   the view-model path its context is bound at
+ * @property {Record<string, any>} [inputs]
+ * @property {string[]} [reads]   view-model paths it reads, under `scope`
+ * @property {string[]} [writes]
+ * @property {boolean}  [clock]   runs every frame, not only when its reads change
+ * @property {{ sid: string, fill?: string, stroke?: string, width?: string }[]} [draws] a drawable's path slots, and the slots its paint goes to
+ * @property {{ sid: string, source?: string }} [effect] a path effect's output slot, and the slot holding the path it applies to
+ */
+
+/**
+ * What the player gives the objects.
+ *
+ * @typedef {object} ObjectsEnv
+ * @property {any}                         data     the bundle's view model (`manifest.data`)
+ * @property {() => Record<string, any>}   values   the live values
+ * @property {(path: string, value: any) => void} write  sets a value now, for the scripts after it to read, and holds it for `commit`
+ * @property {(path: string) => void}      fire     fires a trigger, held for `commit`
+ * @property {() => boolean}               commit   hands the player what was written and fired since the last call; whether that redrew the slots
+ * @property {() => void}                  publish  puts `outputs` into the slots now
+ * @property {(sid: string) => any}        probe    the value a slot's property has now: a path's geometry, for an effect
+ * @property {Record<string, string>}      [families]  the bundle's fonts, by name, as registered
+ * @property {Record<string, { width: number, height: number }>} [images] the images the bundle lists, by name
+ */
+
+/**
+ * @typedef {object} Objects
+ * @property {Record<string, any>} outputs  slot id → value, for the slots the objects fill
+ * @property {string[]}            sids     every slot id in `outputs`
+ * @property {boolean}             live     whether the next step would run a host: one has not run, has a clock, or has a read that changed
+ * @property {boolean}             clocked  whether some host runs every frame, which keeps a finished animation stepping
+ * @property {number}              count    hosts made
+ * @property {(seconds: number) => void} step    one frame
+ * @property {() => void}          destroy  releases the hosts
+ */
+
+/**
+ * @typedef {object} Item
+ * @property {ScriptHost}   host
+ * @property {ObjectEntry}  entry
+ * @property {string[]}     reads     the paths it reads, with its scope
+ * @property {any[]}        seen      what they held when it last ran
+ * @property {boolean}      isStarted
+ * @property {boolean}      isClocked
+ * @property {any[]}        into      the list its drawing is recorded into
+ * @property {number[][]}   colors    the colour slot values of its draws
+ * @property {any[]}        contours  the one-contour list an effect is given
+ * @property {any}          input     the geometry an effect applies to when its entry names no source
+ * @property {{}}           node
+ * @property {boolean}      isOver    whether it was told it drew too much
+ */
+
+/**
+ * @param   {ObjectEntry[]}              entries
+ * @param   {Record<string, Uint8Array>} bytes   each script's bytecode, by `id`
+ * @param   {ObjectsEnv}                 env
+ * @param   {(message: string) => void}  report
+ * @param   {Function}                   make    makes a script host
+ * @returns {Objects}
+ */
+export function createObjects(entries, bytes, env, report, make) {
+  /** @type {Record<string, any>} */
+  const outputs = {}
+  /** @type {string[]} */
+  const sids = []
+  const values = env.values
+  const base = createValuesViewModel({ data: env.data, values, write: env.write })
+  const hasViewModel = !!env.data
+  const fire = base.fire
+  base.fire = (path) => {
+    env.fire(path)
+    if (fire) fire(path)
+  }
+  const assets = assetSource(env.families || {}, env.images || {})
+  /** @type {Record<string, import('../rive/context/context.viewmodel.js').ViewModelAdapter>} */
+  const scopes = {}
+
+  /** @type {Item[]} */
+  const items = []
+  const ordered = entries.map((entry, n) => ({ entry, n })).filter((one) => bytes[one.entry.id]).sort((a, b) => (a.entry.order || 0) - (b.entry.order || 0) || a.n - b.n)
+
+  for (let n = 0; n < ordered.length; n++) {
+    const entry = ordered[n].entry
+    const scope = entry.scope || ''
+    const adapter = scopes[scope] || (scopes[scope] = scoped(base, scope))
+    const host = make({
+      bytes: bytes[entry.id],
+      inputs: entry.inputs,
+      // a bundle without a view model gives its scripts none, as Rive's context:viewModel() is nil there
+      viewModel: hasViewModel ? adapter : null,
+      rootViewModel: hasViewModel ? adapter : null,
+      assets,
+      log: () => {},
+      onError: (/** @type {Error} */ error) => report("script '" + entry.id + "': " + error.message),
+    })
+    const listed = entry.reads || []
+    const reads = []
+    for (let k = 0; k < listed.length; k++) reads.push(scope ? scope + '.' + listed[k] : listed[k])
+    const draws = entry.draws || []
+    const colors = []
+    for (let k = 0; k < draws.length; k++) {
+      sids.push(draws[k].sid)
+      outputs[draws[k].sid] = EMPTY
+      if (draws[k].fill) sids.push(/** @type {string} */ (draws[k].fill))
+      if (draws[k].stroke) sids.push(/** @type {string} */ (draws[k].stroke))
+      if (draws[k].width) sids.push(/** @type {string} */ (draws[k].width))
+      colors.push([ 0, 0, 0, 1 ])
+    }
+    if (entry.effect) sids.push(entry.effect.sid)
+    items.push({ host, entry, reads, seen: new Array(reads.length), isStarted: false, isClocked: !!entry.clock, into: [], colors, contours: [ null ], input: null, node: {}, isOver: false })
+  }
+
+  let isBound = false
+  let isDestroyed = false
+
+  /**
+   * Whether a host's reads differ from when it last ran.
+   *
+   * @param   {Item}    item
+   * @param   {boolean} isTaking whether to remember what they hold now
+   * @returns {boolean}
+   */
+  function changed(item, isTaking) {
+    const current = values()
+    let result = false
+    for (let n = 0; n < item.reads.length; n++) {
+      const value = current[item.reads[n]]
+      if (item.seen[n] === value) continue
+      if (!isTaking) return true
+      result = true
+      item.seen[n] = value
+    }
+    return result
+  }
+
+  /** @param {Item} item */
+  function isDue(item) {
+    return !item.isStarted || item.isClocked || changed(item, false)
+  }
+
+  /**
+   * A drawable's drawing, into its slots.
+   *
+   * @param {Item} item
+   */
+  function drawn(item) {
+    const draws = item.entry.draws || []
+    const list = item.host.draw(item.into)
+    let k = 0
+    let over = 0
+    for (let n = 0; n < list.length; n++) {
+      const record = list[n]
+      if (record.kind !== 'path') continue
+      const rgba = record.paint.rgba
+      const isStroke = record.paint.style === 'stroke'
+      for (let c = 0; c < record.path.length; c++) {
+        if (k >= draws.length) {
+          over++
+          continue
+        }
+        const draw = draws[k]
+        outputs[draw.sid] = record.path[c]
+        const paint = isStroke ? draw.stroke : draw.fill
+        if (paint) {
+          const color = item.colors[k]
+          color[0] = rgba[0]
+          color[1] = rgba[1]
+          color[2] = rgba[2]
+          color[3] = rgba[3] * record.opacity
+          outputs[paint] = color
+        }
+        if (isStroke && draw.width) outputs[draw.width] = record.paint.thickness
+        k++
+      }
+    }
+    for (; k < draws.length; k++) outputs[draws[k].sid] = EMPTY
+    if (over && !item.isOver) {
+      item.isOver = true
+      report("script '" + item.entry.id + "' drew " + (draws.length + over) + ' paths, more than its ' + draws.length + ' slots; the rest are dropped')
+    }
+  }
+
+  /**
+   * A path effect on the geometry of the path it applies to.
+   *
+   * @param {Item} item
+   */
+  function effected(item) {
+    const effect = /** @type {NonNullable<ObjectEntry['effect']>} */ (item.entry.effect)
+    // without a `source` the input is the slot's own value as the bundle baked it, taken before the first write
+    const live = effect.source ? env.probe(effect.source) : undefined
+    if (live) item.input = live
+    else if (!item.input && !effect.source) item.input = env.probe(effect.sid)
+    if (!item.input) return
+    item.contours[0] = item.input
+    const out = item.host.effect(item.contours, item.node)
+    if (out !== item.contours && out.length) outputs[effect.sid] = out[0]
+  }
+
+  /** @param {number} seconds */
+  function step(seconds) {
+    if (isDestroyed) return
+    if (!isBound) {
+      // Rive's first advance after binding runs no script
+      isBound = true
+      return
+    }
+
+    // listeners hear what the player changed since the hosts last ran
+    let isOutside = false
+    for (let n = 0; n < items.length && !isOutside; n++) isOutside = items[n].isStarted && changed(items[n], false)
+    if (isOutside) base.refresh()
+
+    let isProduced = false
+    for (let n = 0; n < items.length; n++) {
+      const item = items[n]
+      if (!isDue(item)) continue
+      changed(item, true)
+      if (!item.isStarted) {
+        item.isStarted = true
+        item.host.init()
+      }
+      const kind = item.entry.kind
+      if (kind === 'pathEffect') {
+        item.host.advance(seconds)
+        effected(item)
+        isProduced = true
+      } else {
+        item.host.frame(seconds)
+        if (kind === 'drawable') {
+          drawn(item)
+          isProduced = true
+        }
+      }
+    }
+    if (!env.commit() && isProduced) env.publish()
+  }
+
+  return {
+    outputs,
+    sids,
+    get live() {
+      for (let n = 0; n < items.length; n++) if (isDue(items[n])) return true
+      return false
+    },
+    get clocked() {
+      for (let n = 0; n < items.length; n++) if (items[n].isClocked) return true
+      return false
+    },
+    get count() {
+      return items.length
+    },
+    step,
+    destroy() {
+      isDestroyed = true
+      items.length = 0
+      sids.length = 0
+      for (const sid in outputs) delete outputs[sid]
+    },
+  }
+}

package/script/play/play.scope.js

@@ -0,0 +1,91 @@
+/**
+ * What a scripted object reaches: the player's values as a view model rooted
+ * at the object's `scope`, and the fonts and images the bundle carries.
+ */
+
+import { measuredFont } from '../rive/api/text/text.font.js'
+
+/** @import { ViewModelAdapter } from '../rive/context/context.viewmodel.js' */
+
+/**
+ * The adapter with every path under `scope`: a nested artboard bound at
+ * `gauge` reads `gauge.value` when its script asks for `value`.
+ *
+ * @param   {ViewModelAdapter} base
+ * @param   {string}           scope the path the object's view model sits at; "" for the host's own
+ * @returns {ViewModelAdapter}
+ */
+export function scoped(base, scope) {
+  if (!scope) return base
+  const at = (/** @type {string} */ path) => (path ? scope + '.' + path : scope)
+  /** @type {ViewModelAdapter} */
+  const adapter = {
+    get: (path) => base.get(at(path)),
+    set: (path, value) => base.set(at(path), value),
+    subscribe: (path, fn) => base.subscribe(at(path), fn),
+    kind: (path) => (base.kind ? base.kind(at(path)) : undefined),
+    fire: (path) => (base.fire ? base.fire(at(path)) : base.set(at(path), true)),
+  }
+  if (base.listSize) {
+    const size = base.listSize
+    adapter.listSize = (path) => size(at(path))
+  }
+  if (base.listGet) {
+    const get = base.listGet
+    adapter.listGet = (path, index) => get(at(path), index)
+  }
+  if (base.listInsert) {
+    const insert = base.listInsert
+    adapter.listInsert = (path, item, index) => insert(at(path), item, index)
+  }
+  if (base.listRemove) {
+    const remove = base.listRemove
+    adapter.listRemove = (path, index) => remove(at(path), index)
+  }
+  if (base.listSwap) {
+    const swap = base.listSwap
+    adapter.listSwap = (path, a, b) => swap(at(path), a, b)
+  }
+  if (base.listClear) {
+    const clear = base.listClear
+    adapter.listClear = (path) => clear(at(path))
+  }
+  if (base.instance) {
+    const instance = base.instance
+    adapter.instance = (path, name) => instance(at(path), name)
+  }
+  return adapter
+}
+
+/**
+ * The assets a script may ask for by name: the bundle's fonts, measured on a
+ * canvas in the family the player registered them under, and its images.
+ *
+ * @param   {Record<string, string>}                                   families font name → registered family
+ * @param   {Record<string, { width: number, height: number }>}        images   image name → size, for the images the bundle lists
+ * @returns {import('../rive/api/assets/assets.js').AssetSource}
+ */
+export function assetSource(families, images) {
+  /** @type {CanvasRenderingContext2D | null | undefined} */
+  let context
+  const measurer = () => {
+    if (context === undefined) {
+      const canvas = typeof document === 'undefined' ? null : document.createElement('canvas')
+      context = canvas ? canvas.getContext('2d') : null
+    }
+    return context
+  }
+  return {
+    image: (name) => images[name] || { width: 0, height: 0 },
+    font: (name) => {
+      if (!(name in families)) return undefined
+      return measuredFont(name, (character) => {
+        const ctx = measurer()
+        if (!ctx) return 0.5
+        // measured at 100 px so the advance is in em
+        ctx.font = '100px "' + families[name] + '"'
+        return ctx.measureText(character).width / 100
+      })
+    },
+  }
+}

package/script/rive/api/api.statics.js

@@ -0,0 +1,31 @@
+/**
+ * The static side of a host type as a Lua global: a table of functions
+ * (`Text.new`), which can also be called itself (`ImageSampler('clamp', ...)`)
+ * as Rive's constructors can.
+ */
+
+import { LuaTable, NativeFunction } from '../../luau/vm/vm.value.js'
+
+/**
+ * @param   {string} name
+ * @param   {Record<string, (args: any[]) => any>} fns  each takes the call's arguments
+ * @param   {string} [call]  the function a call of the table itself runs
+ * @returns {LuaTable}
+ */
+export function statics(name, fns, call) {
+  const t = new LuaTable()
+  for (const key in fns) {
+    const fn = fns[key]
+    t.set(key, new NativeFunction(name + '.' + key, function (vm, args) {
+      return fn(args)
+    }))
+  }
+  if (call) {
+    const meta = new LuaTable()
+    meta.set('__call', new NativeFunction(name + '.__call', function (vm, args) {
+      return fns[call](args.slice(1))
+    }))
+    t.meta = meta
+  }
+  return t
+}

package/script/rive/api/api.type.js

@@ -0,0 +1,188 @@
+/**
+ * Host types for Lua: a Lua table that carries a JS object and a metatable
+ * whose `__index` and `__newindex` read and write that object's fields and
+ * find its methods. Every Rive type a script can hold (Path, Paint, Mat2D,
+ * the view model and its properties, the context) is made this way, so a
+ * script indexes them as it would Rive's own userdata.
+ */
+
+import { EMPTY, LuaTable, NativeFunction, fail, typeName } from '../../luau/vm/vm.value.js'
+import { toNumber } from '../../luau/vm/vm.meta.js'
+import { decodeUtf8, encodeUtf8 } from '../../luau/luau.convert.js'
+
+/** A Lua table that stands for a host object */
+export class Wrapped extends LuaTable {
+  /** @param {any} host */
+  constructor(host) {
+    super()
+    this.host = host
+  }
+}
+
+/**
+ * @typedef {object} TypeSpec
+ * @property {Record<string, { get: (h: any, vm: any) => any, set?: (h: any, value: any, vm: any) => void }>} [fields]
+ * @property {Record<string, (h: any, args: any[], vm: any) => any>} [methods]  `args[0]` is the wrapper itself (the `self` of a method call)
+ * @property {(h: any, key: any, vm: any) => any} [index]     reads a key no field or method names
+ * @property {(h: any, key: any, value: any, vm: any) => void} [newindex]  writes a key no field names
+ * @property {Record<string, (vm: any, args: any[]) => any>} [meta]  metamethods such as `__mul`, `__eq`, `__tostring`
+ */
+
+/**
+ * @typedef {object} HostType
+ * @property {string}   name
+ * @property {LuaTable} meta
+ * @property {(host: any) => Wrapped} wrap
+ * @property {(v: any) => boolean} is
+ * @property {(v: any) => any} unwrap  the host object, or undefined when v is another kind of value
+ */
+
+/**
+ * @param   {string}   name
+ * @param   {TypeSpec} spec
+ * @returns {HostType}
+ */
+export function defineType(name, spec) {
+  const meta = new LuaTable()
+  /** @type {Record<string, NativeFunction>} */
+  const methods = Object.create(null)
+  const fields = spec.fields || Object.create(null)
+  const defs = spec.methods || Object.create(null)
+
+  for (const key in defs) methods[key] = method(name, key, defs[key])
+
+  meta.set('__index', new NativeFunction(name + '.__index', function (vm, args) {
+    const self = args[0]
+    const key = args[1]
+    const host = self.host
+    if (typeof key === 'string') {
+      const field = fields[key]
+      if (field !== undefined) return field.get(host, vm)
+      const m = methods[key]
+      if (m !== undefined) return m
+    }
+    return spec.index ? spec.index(host, key, vm) : undefined
+  }))
+
+  meta.set('__newindex', new NativeFunction(name + '.__newindex', function (vm, args) {
+    const host = args[0].host
+    const key = args[1]
+    const field = typeof key === 'string' ? fields[key] : undefined
+    if (field !== undefined && field.set) field.set(host, args[2], vm)
+    else if (field === undefined && spec.newindex) spec.newindex(host, key, args[2], vm)
+    else throw fail('cannot set ' + name + " field '" + String(key) + "'")
+    return EMPTY
+  }))
+
+  if (spec.meta) for (const event in spec.meta) meta.set(event, new NativeFunction(name + '.' + event, spec.meta[event]))
+  if (!(spec.meta && spec.meta.__tostring)) meta.set('__tostring', new NativeFunction(name + '.__tostring', function () { return name }))
+
+  /** @type {HostType} */
+  const type = {
+    name,
+    meta,
+    wrap(host) {
+      const t = new Wrapped(host)
+      t.meta = meta
+      return t
+    },
+    is(v) {
+      return v instanceof Wrapped && v.meta === meta
+    },
+    unwrap(v) {
+      return v instanceof Wrapped && v.meta === meta ? v.host : undefined
+    },
+  }
+  return type
+}
+
+/**
+ * @param   {string} typeNameText
+ * @param   {string} key
+ * @param   {(h: any, args: any[], vm: any) => any} fn
+ * @returns {NativeFunction}
+ */
+function method(typeNameText, key, fn) {
+  return new NativeFunction(typeNameText + '.' + key, function (vm, args) {
+    const self = args[0]
+    if (!(self instanceof Wrapped)) throw fail('missing self: call ' + typeNameText + '.' + key + ' with a colon')
+    return fn(self.host, args, vm)
+  })
+}
+
+// Arguments
+// ■■■■■■■■■
+
+/**
+ * @param   {any[]}  args
+ * @param   {number} i      0-based
+ * @returns {string}
+ */
+function got(args, i) {
+  return i >= args.length ? 'no value' : typeName(args[i])
+}
+
+/**
+ * @param   {number} i
+ * @param   {string} fname
+ * @param   {string} expected
+ * @param   {any[]}  args
+ */
+export function badArg(i, fname, expected, args) {
+  return fail('invalid argument #' + (i + 1) + " to '" + fname + "' (" + expected + ' expected, got ' + got(args, i) + ')')
+}
+
+/**
+ * @param   {any[]}  args
+ * @param   {number} i
+ * @param   {string} fname
+ * @returns {number}
+ */
+export function num(args, i, fname) {
+  const n = typeof args[i] === 'number' ? args[i] : toNumber(args[i])
+  if (n === undefined) throw badArg(i, fname, 'number', args)
+  return n
+}
+
+/**
+ * @param   {any[]}  args
+ * @param   {number} i
+ * @param   {string} fname
+ * @param   {number} def
+ * @returns {number}
+ */
+export function optNum(args, i, fname, def) {
+  return args[i] === undefined ? def : num(args, i, fname)
+}
+
+/**
+ * @param   {any[]}  args
+ * @param   {number} i
+ * @param   {string} fname
+ * @returns {string} a string argument as text
+ */
+export function text(args, i, fname) {
+  if (typeof args[i] !== 'string') throw badArg(i, fname, 'string', args)
+  return decodeUtf8(args[i])
+}
+
+/**
+ * @param   {any[]}  args
+ * @param   {number} i
+ * @param   {HostType} type
+ * @param   {string} fname
+ * @returns {any}    the host object of a wrapped value of this type
+ */
+export function wrapped(args, i, type, fname) {
+  const h = type.unwrap(args[i])
+  if (h === undefined) throw badArg(i, fname, type.name, args)
+  return h
+}
+
+/**
+ * @param   {string} s  JS text
+ * @returns {string}    as a Lua string
+ */
+export function lua(s) {
+  return encodeUtf8(s)
+}

package/script/rive/api/artboard/artboard.js

@@ -0,0 +1,89 @@
+/**
+ * `Artboard`: an artboard a script holds as an input (or makes with
+ * `instance()`) and draws. Motion plays the artboard itself, as the nested
+ * artboard it is placed as; the script only places it. `draw` records
+ *
+ * `{ kind: 'artboard', name, instance, time, transform, clips, opacity, color, viewModel }`
+ *
+ * where `instance` numbers the artboard's instances (an `instance()` is a new
+ * one), `time` is the seconds the script advanced it by, and `viewModel` the
+ * adapter an instance was bound to (or null). A visitor passed to `draw` is not
+ * called: there are no drawables to visit here.
+ */
+
+import { Vector } from '../../../luau/vm/vm.value.js'
+import { Wrapped, defineType, num, wrapped } from '../api.type.js'
+import { Renderer } from '../draw/draw.renderer.js'
+import { stamp } from '../media/media.draw.js'
+
+/**
+ * @typedef {object} ArtboardData
+ * @property {string} name
+ * @property {number} width
+ * @property {number} height
+ * @property {number} instance
+ * @property {number} time
+ * @property {boolean} frameOrigin
+ * @property {any} viewModel    a ViewModelAdapter, or null
+ * @property {{ next: number }} counter  shared by the instances of one artboard
+ */
+
+/**
+ * @param {any} r  a Recorder
+ * @param {ArtboardData} a
+ */
+function record(r, a) {
+  const out = /** @type {any} */ (stamp(r, 'artboard'))
+  out.name = a.name
+  out.instance = a.instance
+  out.time = a.time
+  out.viewModel = a.viewModel
+  r.drawings.push(out)
+}
+
+const none = () => 0
+
+export const Artboard = defineType('Artboard', {
+  fields: {
+    frameOrigin: { get: (a) => a.frameOrigin, set: (a, v) => { a.frameOrigin = v === true } },
+    width: { get: (a) => a.width },
+    height: { get: (a) => a.height },
+    data: { get: (a) => a.data },
+  },
+  methods: {
+    draw: (a, args) => record(wrapped(args, 1, Renderer, 'draw'), a),
+    drawModulated: (a, args) => record(wrapped(args, 1, Renderer, 'drawModulated'), a),
+    propertyKey: () => undefined,
+    advance: (a, args) => {
+      a.time += num(args, 1, 'advance')
+      return true
+    },
+    instance: (a, args) => {
+      const vm = args[1] instanceof Wrapped && args[1].host && args[1].host.scope ? args[1].host.scope.adapter : null
+      a.counter.next++
+      return Artboard.wrap({ name: a.name, width: a.width, height: a.height, instance: a.counter.next, time: 0, frameOrigin: a.frameOrigin, viewModel: vm, counter: a.counter, data: undefined })
+    },
+    animation: () => undefined,
+    node: () => undefined,
+    bounds: (a) => [ new Vector(0, 0, 0), new Vector(a.width, a.height, 0) ],
+    pointerDown: none,
+    pointerUp: none,
+    pointerMove: none,
+    pointerExit: none,
+    pointerScroll: none,
+    gamepadConnected: none,
+    gamepadEvent: none,
+    gamepadDisconnected: none,
+    addToPath: () => {},
+  },
+})
+
+/**
+ * @param   {string} name
+ * @param   {number} width
+ * @param   {number} height
+ * @returns {any}  an Artboard for a script
+ */
+export function artboardHandle(name, width, height) {
+  return Artboard.wrap({ name, width, height, instance: 0, time: 0, frameOrigin: false, viewModel: null, counter: { next: 0 }, data: undefined })
+}