@oidoid/void 0.1.0-4 → 0.1.0-7

package/tools/atlas-pack/atlas-json-parser.ts

@@ -0,0 +1,159 @@
+import {
+  type Anim,
+  type AtlasJSON,
+  animCels,
+  animMillis,
+  celMillis,
+  type TagFormat
+} from '../../src/graphics/atlas.ts'
+import {type Box, boxEq, type XY} from '../../src/types/geo.ts'
+import {
+  type Aseprite,
+  AsepriteDirection,
+  type AsepriteFrame,
+  type AsepriteFrameMap,
+  type AsepriteFrameTag,
+  type AsepriteSlice,
+  type AsepriteTagSpan
+} from './aseprite.ts'
+
+export function parseAtlasJSON(ase: Readonly<Aseprite>): AtlasJSON {
+  const anim: {[tag: string]: Anim} = {}
+  const cels: number[] = []
+  for (const span of ase.meta.frameTags) {
+    const tag = parseTag(span.name)
+    if (anim[tag]) throw Error(`atlas tag "${tag}" duplicate`)
+    const id = Object.keys(anim).length
+    anim[tag] = parseAnim(id, span, ase.frames, ase.meta.slices)
+    for (const cel of parseAnimFrames(span, ase.frames).map(parseCel))
+      cels.push(cel.x, cel.y)
+  }
+  for (const slice of ase.meta.slices)
+    if (!anim[parseTag(slice.name)])
+      throw Error(`atlas hitbox "${slice.name}" has no animation`)
+  return {anim, celXY: cels}
+}
+
+/** @internal */
+export function parseAnim(
+  id: number,
+  span: Readonly<AsepriteTagSpan>,
+  map: Readonly<AsepriteFrameMap>,
+  slices: readonly Readonly<AsepriteSlice>[]
+): Anim {
+  const cels = parseAnimFrames(span, map)
+  if (!cels[0]) throw Error(`no atlas frame "${span.name}"`)
+  const {hitbox, hurtbox} = parseHitboxes(span, slices)
+  return {
+    cels: cels.length,
+    h: cels[0].sourceSize.h,
+    hitbox,
+    hurtbox,
+    id,
+    w: cels[0].sourceSize.w
+  }
+}
+
+/**
+ * every frame is guaranteed to be present for at least `celMillis`. cels are
+ * duplicated until cel duration is at least met. cels are unpacked until a full
+ * period is defined for the direction. no warns for overflowing past on second
+ * or uneven periods.
+ * @internal
+ */
+export function parseAnimFrames(
+  span: AsepriteTagSpan,
+  map: AsepriteFrameMap
+): AsepriteFrame[] {
+  const cels = []
+  let animDuration = 0
+  const len = span.to - span.from + 1
+  const peak = len - 1
+  const cycle = Math.max(1, 2 * peak)
+  const end =
+    span.direction === AsepriteDirection.Forward ||
+    span.direction === AsepriteDirection.Reverse
+      ? len
+      : cycle
+  const indexByDir: {[dir in AsepriteDirection]: (i: number) => number} = {
+    forward: i => span.from + (i % len),
+    pingpong: i => span.from + peak - Math.abs((i % cycle) - peak),
+    pingpong_reverse: i => span.to - (peak - Math.abs((i % cycle) - peak)),
+    reverse: i => span.to - (i % len)
+  }
+  const frameIndex = indexByDir[span.direction as AsepriteDirection]
+  for (
+    let i = 0;
+    i < end && cels.length < animCels && animDuration < animMillis;
+    i++
+  ) {
+    const frameTag = `${span.name}--${frameIndex(i)}` as AsepriteFrameTag
+    const frame = map[frameTag]
+    if (!frame) throw Error(`no atlas frame "${frameTag}"`)
+    for (
+      let celDuration = 0;
+      celDuration < frame.duration &&
+      cels.length < animCels &&
+      animDuration < animMillis;
+      celDuration += celMillis, animDuration += celMillis
+    ) {
+      cels.push(frame)
+
+      if (span.from === span.to) return cels // optimize for long single cel.
+    }
+  }
+  return cels
+}
+
+/** @internal */
+export function parseCel(frame: Readonly<AsepriteFrame>): XY {
+  return {
+    x: frame.frame.x + (frame.frame.w - frame.sourceSize.w) / 2,
+    y: frame.frame.y + (frame.frame.h - frame.sourceSize.h) / 2
+  }
+}
+
+/** @internal */
+export function parseHitboxes(
+  span: Readonly<AsepriteTagSpan>,
+  slices: readonly Readonly<AsepriteSlice>[]
+): {hitbox: Box | undefined; hurtbox: Box | undefined} {
+  let hitbox
+  let hurtbox
+  // https://github.com/aseprite/aseprite/issues/3524
+  for (const slice of slices) {
+    if (slice.name !== span.name) continue
+
+    if (!slice.keys[0]) continue
+
+    for (const k of slice.keys)
+      if (!boxEq(k.bounds, slice.keys[0].bounds))
+        throw Error(
+          `atlas tag "${span.name}" hitbox bounds varies across frames`
+        )
+
+    const red = slice.color === '#ff0000ff'
+    const green = slice.color === '#00ff00ff'
+    const blue = slice.color === '#0000ffff' // default Aseprite slice color.
+    if (!red && !green && !blue)
+      throw Error(
+        `atlas tag "${span.name}" hitbox color ${slice.color} unsupported`
+      )
+
+    if (hitbox && (red || blue))
+      throw Error(`atlas tag "${span.name}" has multiple hitboxes`)
+
+    if (hurtbox && (green || blue))
+      throw Error(`atlas tag "${span.name}" has multiple hurtboxes`)
+
+    if (red || blue) hitbox = slice.keys[0].bounds
+    if (green || blue) hurtbox = slice.keys[0].bounds
+  }
+  return {hitbox, hurtbox}
+}
+
+function parseTag(tag: string): TagFormat {
+  if (!tag.includes('--'))
+    throw Error(`atlas tag "${tag}" not in <filestem>--<animation> format`)
+  return tag as TagFormat
+}

package/tools/atlas-pack/atlas-pack.ts

@@ -0,0 +1,51 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type {AtlasConfig} from '../../schema/config-file.ts'
+import {exec} from '../utils/exec.ts'
+import {globAll} from '../utils/file-util.ts'
+import {parseAtlasJSON} from './atlas-json-parser.ts'
+
+// to-do: separate executable?
+export async function packAtlas(config: Readonly<AtlasConfig>): Promise<void> {
+  const filenames = await globAll(path.join(config.dir, '**.aseprite'))
+  if (!filenames.length) return
+
+  const webp = config.image.endsWith('.webp')
+  const sheet = webp ? config.image.replace('.webp', '.png') : config.image
+  const json = await exec(
+    'aseprite',
+    '--batch',
+    '--color-mode=indexed',
+    '--filename-format={title}--{tag}--{frame}',
+    '--list-slices',
+    '--list-tags',
+    '--merge-duplicates',
+    `--sheet=${sheet}`,
+    '--sheet-pack',
+    '--tagname-format={title}--{tag}',
+    ...filenames
+  )
+
+  if (webp)
+    await exec(
+      'cwebp',
+      '-exact',
+      '-lossless',
+      '-mt',
+      '-quiet',
+      '-z',
+      '9',
+      sheet,
+      '-o',
+      config.image
+    )
+
+  await fs.writeFile(
+    config.json,
+    JSON.stringify(parseAtlasJSON(JSON.parse(json)))
+  )
+
+  try {
+    await exec('biome', 'check', '--fix', config.json)
+  } catch {}
+}

package/tools/bundle/bundle.ts

@@ -0,0 +1,64 @@
+import fs from 'node:fs'
+import esbuild from 'esbuild'
+import type {AtlasConfig} from '../../schema/config-file.ts'
+import * as V from '../../src/index.ts'
+import type {VoidVersion} from '../../src/types/void-version.ts'
+import {packAtlas} from '../atlas-pack/atlas-pack.ts'
+import type {Config} from '../types/config.ts'
+import {HTMLPlugin} from './html-plugin.ts'
+
+export async function bundle(
+  config: Readonly<Config>,
+  srcFilenames: readonly string[],
+  voidVersion: Readonly<VoidVersion>
+): Promise<void> {
+  const opts: esbuild.BuildOptions = {
+    banner: config.watch
+      ? {
+          js: "new EventSource('/esbuild').addEventListener('change', () => location.reload());"
+        }
+      : {},
+    bundle: true,
+    define: {
+      // define on globalThis to avoid ReferenceError in unit tests.
+      'globalThis.voidVersion': JSON.stringify(voidVersion)
+    },
+    entryPoints: [...srcFilenames],
+    format: 'esm',
+    logLevel: 'info', // print the port and build demarcations.
+    metafile: true,
+    minify: config.minify,
+    outdir: config.out.dir,
+    plugins: [HTMLPlugin(config)],
+    sourcemap: 'linked',
+    target: 'es2024' // https://esbuild.github.io/content-types/#tsconfig-json
+  }
+
+  if (config.preloadAtlas) await packAtlas(config.preloadAtlas)
+  if (config.preloadAtlas && config.watch) {
+    fs.watch(config.preloadAtlas.dir, {recursive: true}, (ev, type) =>
+      onWatch(config.preloadAtlas!, ev, type)
+    )
+    const ctx = await esbuild.context(opts)
+    await Promise.all([
+      ctx.watch(),
+      ctx.serve({port: 1234, servedir: config.out.dir})
+    ])
+  } else {
+    const build = await esbuild.build(opts)
+    if (config.meta)
+      await fs.promises.writeFile(config.meta, JSON.stringify(build.metafile))
+  }
+}
+
+const onWatch = V.debounce(
+  async (
+    config: Readonly<AtlasConfig>,
+    ev: fs.WatchEventType,
+    file: string | null
+  ) => {
+    console.log(`asset ${file} ${ev}.`)
+    await packAtlas(config)
+  },
+  500 as V.Millis
+)

package/tools/bundle/html-plugin.ts

@@ -0,0 +1,135 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type esbuild from 'esbuild'
+import {minify} from 'html-minifier-next'
+import type {Config} from '../types/config.ts'
+import {exec} from '../utils/exec.ts'
+import {parseHTML} from '../utils/html-parser.ts'
+
+type Manifest = {
+  icons?:
+    | {
+        src?: string | undefined
+        size?: string | undefined
+        type?: string | undefined
+      }[]
+    | undefined
+  start_url?: string | undefined
+  version?: string | undefined
+}
+
+export function HTMLPlugin(config: Readonly<Config>): esbuild.Plugin {
+  return {
+    name: 'HTMLPlugin',
+    setup(build) {
+      build.onEnd(async _result => {
+        const doc = await parseHTML(config.entry)
+
+        const scripts = doc.querySelectorAll<HTMLScriptElement>(
+          "script[type='module'][src$='.ts']"
+        )
+        for (const script of scripts) {
+          // to-do: test.
+          const filename = path.basename(
+            script.getAttribute('src')!.replace(/\.ts$/, '.js')
+          )
+          if (config.oneFile) {
+            script.removeAttribute('src')
+            script.textContent = await fs.readFile(
+              path.join(config.out.dir, filename),
+              {encoding: 'utf8'}
+            )
+          } else script.src = filename
+        }
+
+        if (config.oneFile) {
+          const imgs = doc.querySelectorAll<HTMLImageElement>('img[src]')
+          for (const img of imgs) {
+            const filename = img.getAttribute('src')!
+            const b64 = await fs.readFile(path.join(config.out.dir, filename), {
+              encoding: 'base64'
+            })
+            const ext = filename.match(/\.([^.]+)$/)?.[1]
+            if (!ext) throw Error('no asset extension')
+            img.src = `data:image/${ext};base64,${b64}`
+          }
+        }
+
+        const manifestEl = doc.querySelector<HTMLLinkElement>(
+          'link[href][rel="manifest"]'
+        )
+        if (manifestEl) {
+          const manifestFilename = path.resolve(
+            path.dirname(config.entry),
+            manifestEl.getAttribute('href')!
+          )
+          const manifest: Manifest = JSON.parse(
+            await fs.readFile(manifestFilename, 'utf8')
+          )
+          if (config.version) manifest.version = config.version
+
+          for (const icon of manifest.icons ?? []) {
+            if (!icon.src || !icon.type) continue
+            const iconFilename = `${path.dirname(manifestFilename)}/${icon.src}`
+            const file = await fs.readFile(iconFilename)
+            if (config.oneFile)
+              icon.src = `data:${icon.type};base64,${file.toString('base64')}`
+            else icon.src = path.relative(config.out.dir, iconFilename)
+          }
+          if (config.watch) manifest.start_url = 'http://localhost:1234'
+
+          if (config.oneFile)
+            manifestEl.href = `data:application/json,${encodeURIComponent(
+              JSON.stringify(manifest)
+            )}`
+          else
+            await fs.writeFile(
+              path.join(config.out.dir, path.basename(manifestFilename)),
+              JSON.stringify(manifest)
+            )
+        }
+
+        if (config.oneFile) {
+          const icons = doc.querySelectorAll<HTMLLinkElement>(
+            'link[href][rel="icon"][type]'
+          )
+          for (const icon of icons) {
+            const filename = path.resolve(
+              config.out.dir,
+              icon.getAttribute('href')!
+            )
+            const file = await fs.readFile(filename)
+            icon.href = `data:${icon.type};base64,${file.toString('base64')}`
+          }
+        }
+
+        let html = `<!doctype html>\n${doc.documentElement.outerHTML}`
+
+        if (config.minify)
+          html = await minify(html, {
+            caseSensitive: true,
+            collapseBooleanAttributes: true,
+            html5: true,
+            minifyCSS: true,
+            removeAttributeQuotes: true,
+            removeComments: true,
+            removeEmptyAttributes: true
+          })
+        else
+          try {
+            html = await exec(
+              'biome',
+              'check',
+              '--fix',
+              `--stdin-file-path=${config.entry}`,
+              {stdin: html}
+            )
+          } catch {}
+
+        // to-do: test.
+        const outHTMLFilename = path.join(config.out.dir, config.out.filename)
+        await fs.writeFile(outHTMLFilename, html)
+      })
+    }
+  }
+}

package/tools/types/config.ts

@@ -0,0 +1,65 @@
+import path from 'node:path'
+import type {AtlasConfig, ConfigFile} from '../../schema/config-file.ts'
+import type {Argv} from '../utils/argv.ts'
+import type {PackageJSON} from './package-json.ts'
+
+export type Config = {
+  $schema: string
+  entry: string
+  meta: string | undefined
+  out: {dir: string; filename: string}
+  preloadAtlas: AtlasConfig | undefined
+
+  /** config directory name. */
+  dirname: string
+  /** config filename. */
+  filename: string
+
+  minify: boolean
+  oneFile: boolean
+  watch: boolean
+
+  /** package publish date. */
+  published: string | undefined
+  /** package version. */
+  version: string | undefined
+
+  /** Git short hash. */
+  hash: string
+}
+
+export function Config(
+  configFile: Readonly<ConfigFile>,
+  argv: Readonly<Argv>,
+  packageJSON: Readonly<PackageJSON>,
+  hash: string
+): Config {
+  let fileStem = path.basename(configFile.entry).replace(/\.[^.]+$/, '')
+  if (configFile.out.name && !argv.opts['--watch'])
+    fileStem = configFile.out.name
+  let fileSuffix = '.html'
+  if (!argv.opts['--watch']) {
+    const version = packageJSON.version ? `v${packageJSON.version}` : ''
+    const published =
+      packageJSON.version && packageJSON.published
+        ? `+${packageJSON.published}`
+        : ''
+    const hashStr = packageJSON.version && hash ? `.${hash}` : ''
+    fileSuffix = `-${version}${published}${hashStr}.html`
+  }
+  return {
+    $schema: configFile.$schema,
+    entry: configFile.entry,
+    meta: configFile.meta,
+    out: {dir: configFile.out.dir, filename: `${fileStem}${fileSuffix}`},
+    preloadAtlas: configFile.preloadAtlas,
+    dirname: configFile.dirname,
+    filename: configFile.filename,
+    minify: argv.opts['--minify'] ?? false,
+    oneFile: argv.opts['--one-file'] ?? false,
+    watch: argv.opts['--watch'] ?? false,
+    published: packageJSON.published,
+    version: packageJSON.version,
+    hash
+  }
+}

package/tools/types/package-json.ts

@@ -0,0 +1,4 @@
+export type PackageJSON = {
+  version?: string | undefined
+  published?: string | undefined
+}

package/tools/utils/argv.test.ts

@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict'
+import {test} from 'node:test'
+import {Argv} from './argv.ts'
+
+declare module './argv.ts' {
+  interface Opts {
+    '--config'?: string
+    '--minify'?: true
+    '--watch'?: true
+  }
+}
+
+test('parses empty.', () => {
+  assert.deepEqual<Argv>(Argv(['/usr/local/bin/node', 'tools/void.ts']), {
+    args: [],
+    opts: {},
+    posargs: []
+  })
+})
+
+test('parses nonempty.', () => {
+  assert.deepEqual<Argv>(
+    Argv([
+      '/usr/local/bin/node',
+      'tools/void.ts',
+      '--config=config',
+      '--minify',
+      '--watch',
+      'a.aseprite',
+      'b.aseprite',
+      '--',
+      'posarg0',
+      'posarg1'
+    ]),
+    {
+      args: ['a.aseprite', 'b.aseprite'],
+      opts: {'--config': 'config', '--minify': true, '--watch': true},
+      posargs: ['posarg0', 'posarg1']
+    }
+  )
+})

package/tools/utils/argv.ts

@@ -0,0 +1,29 @@
+export type Argv = {
+  /** all the arguments not starting with `--` before `--`. */
+  args: string[]
+  /** all options starting with `--` before `--` and their optional value. */
+  opts: Opts
+  /** everything after `--`. */
+  posargs: string[]
+}
+
+/** string-string|bool map. Eg, `'--config'?: string; '--minify'?: string | true` */
+// biome-ignore lint/suspicious/noEmptyInterface: declaration merging.
+export interface Opts {}
+
+export function Argv(argv: readonly string[]): Argv {
+  const args = []
+  const posargs = []
+  const opts: {[k: string]: string | true} = {}
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--') {
+      posargs.push(...argv.slice(i + 1))
+      break
+    }
+    if (argv[i]!.startsWith('--')) {
+      const [k, v] = argv[i]!.split(/=(.*)/).slice(0, 2)
+      opts[k!] = v ?? true
+    } else args.push(argv[i]!)
+  }
+  return {args, opts, posargs}
+}

package/tools/utils/exec.ts

@@ -0,0 +1,22 @@
+import {execFile} from 'node:child_process'
+import util from 'node:util'
+
+export async function exec(
+  exe: string,
+  ...args:
+    | readonly [...string[], {stdin?: string | undefined}]
+    | readonly string[]
+): Promise<string> {
+  const opts = (typeof args.at(-1) === 'object' ? args.at(-1) : undefined) as
+    | {stdin?: string | undefined}
+    | undefined
+  args = (opts ? args.slice(0, -1) : args) as string[]
+  const promise = util.promisify(execFile)(exe, args, {})
+  if (promise.child.stdin && opts?.stdin != null) {
+    promise.child.stdin.write(opts.stdin)
+    promise.child.stdin.end()
+  }
+  const {stdout, stderr} = await promise
+  process.stderr.write(stderr)
+  return stdout
+}

package/tools/utils/file-util.ts

@@ -0,0 +1,11 @@
+import fs from 'node:fs/promises'
+
+export async function globAll(glob: string): Promise<string[]> {
+  const filenames = []
+  try {
+    for await (const filename of fs.glob(glob)) filenames.push(filename)
+  } catch (err) {
+    throw Error(`glob \`${glob}\` unreadable`, {cause: err})
+  }
+  return filenames
+}

package/tools/utils/html-parser.ts

@@ -0,0 +1,9 @@
+import {JSDOM} from 'jsdom'
+
+export async function parseHTML(filename: string): Promise<Document> {
+  try {
+    return (await JSDOM.fromFile(filename)).window.document
+  } catch (err) {
+    throw Error(`HTML ${filename} unparsable`, {cause: err})
+  }
+}

package/tools/void.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// void.ts --config=<void.json> [--minify] [--one-file] [--watch]
+// compiles images into an atlas and bundles an HTML entrypoint.
+
+import path from 'node:path'
+import voidPackageJSON from '../package.json' with {type: 'json'}
+import {parseConfigFile} from '../schema/config-file.ts'
+import type {VoidVersion} from '../src/types/void-version.ts'
+import {bundle} from './bundle/bundle.ts'
+import {Config} from './types/config.ts'
+import type {PackageJSON} from './types/package-json.ts'
+import {Argv} from './utils/argv.ts'
+import {exec} from './utils/exec.ts'
+import {parseHTML} from './utils/html-parser.ts'
+
+declare module './utils/argv.ts' {
+  interface Opts {
+    '--config'?: string
+    '--minify'?: true
+    /** inline everything into a single HTML file output. */
+    '--one-file'?: true
+    /**
+     * run development server on http://localhost:1234 and reload on code
+     * change.
+     */
+    '--watch'?: true
+  }
+}
+
+export async function build(args: readonly string[]): Promise<void> {
+  const argv = Argv(args)
+  const configFile = await parseConfigFile(argv.opts['--config'] ?? 'void.json')
+  const hash = (await exec('git', 'rev-parse', '--short', 'HEAD')).trim()
+  const packageJSON: PackageJSON = JSON.parse(
+    (await exec('npm', 'pkg', 'get', 'version', 'published')) || '{}'
+  )
+  const config = Config(configFile, argv, packageJSON, hash)
+
+  const doc = await parseHTML(config.entry)
+  const srcFilenames = [
+    ...doc.querySelectorAll<HTMLScriptElement>(
+      "script[type='module'][src$='.ts']"
+    )
+  ].map(el => path.resolve(path.dirname(config.entry), el.getAttribute('src')!))
+
+  const voidVersion: VoidVersion = {
+    published: voidPackageJSON.published,
+    // imported JSON doesn't treeshake. define as a constant.
+    version: voidPackageJSON.version
+  }
+
+  await bundle(config, srcFilenames, voidVersion)
+}
+
+if (import.meta.main) await build(process.argv)

package/dist/atlas/anim.d.ts

@@ -1,30 +0,0 @@
-/**
- * @template {AnimTag} T
- * @typedef {object} Anim
- * @prop {readonly Readonly<import('../types/2d.js').XY>[]} cels
- * @prop {Readonly<import('../types/2d.js').Box>} hitbox
- * @prop {number} id A multiple of 16 (maxAnimCels).
- * @prop {number} w
- * @prop {number} h
- * @prop {T & AnimTag} tag
- */
-/**
- * `--tagname-format={title}--{tag}`.
- * @typedef {`${string}--${string}`} AnimTag
- */
-export const maxAnimCels: 16;
-export type Anim<T extends `${string}--${string}`> = {
-    cels: readonly Readonly<import('../types/2d.js').XY>[];
-    hitbox: Readonly<import('../types/2d.js').Box>;
-    /**
-     * A multiple of 16 (maxAnimCels).
-     */
-    id: number;
-    w: number;
-    h: number;
-    tag: T & AnimTag;
-};
-/**
- * `--tagname-format={title}--{tag}`.
- */
-export type AnimTag = `${string}--${string}`;