@oidoid/void 0.1.0-3 → 0.1.0-6

package/dist/tools/utils/argv.d.ts

@@ -0,0 +1,12 @@
+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` */
+export interface Opts {
+}
+export declare function Argv(argv: readonly string[]): Argv;

package/dist/tools/utils/argv.js

@@ -0,0 +1,19 @@
+export function Argv(argv) {
+    const args = [];
+    const posargs = [];
+    const opts = {};
+    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 };
+}
+//# sourceMappingURL=argv.js.map

package/dist/tools/utils/argv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv.js","sourceRoot":"","sources":["../../../tools/utils/argv.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,IAAI,CAAC,IAAuB;IAC1C,MAAM,IAAI,GAAG,EAAE,CAAA;IACf,MAAM,OAAO,GAAG,EAAE,CAAA;IAClB,MAAM,IAAI,GAAiC,EAAE,CAAA;IAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACrB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YAClC,MAAK;QACP,CAAC;QACD,IAAI,IAAI,CAAC,CAAC,CAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YAClD,IAAI,CAAC,CAAE,CAAC,GAAG,CAAC,IAAI,IAAI,CAAA;QACtB,CAAC;;YAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,CAAA;IAC5B,CAAC;IACD,OAAO,EAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAC,CAAA;AAC9B,CAAC"}

package/dist/tools/utils/exec.d.ts

@@ -0,0 +1,3 @@
+export declare function exec(exe: string, ...args: readonly [...string[], {
+    stdin?: string | undefined;
+}] | readonly string[]): Promise<string>;

package/dist/tools/utils/exec.js

@@ -0,0 +1,15 @@
+import { execFile } from 'node:child_process';
+import util from 'node:util';
+export async function exec(exe, ...args) {
+    const opts = (typeof args.at(-1) === 'object' ? args.at(-1) : undefined);
+    args = (opts ? args.slice(0, -1) : args);
+    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;
+}
+//# sourceMappingURL=exec.js.map

package/dist/tools/utils/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../../tools/utils/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,oBAAoB,CAAA;AAC3C,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,GAAW,EACX,GAAG,IAEkB;IAErB,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAE1D,CAAA;IACb,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAa,CAAA;IACpD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;IACvD,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,CAAC;QAC/C,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACrC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;IAC3B,CAAC;IACD,MAAM,EAAC,MAAM,EAAE,MAAM,EAAC,GAAG,MAAM,OAAO,CAAA;IACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IAC5B,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/tools/utils/file-util.d.ts

@@ -0,0 +1 @@
+export declare function globAll(glob: string): Promise<string[]>;

package/dist/tools/utils/file-util.js

@@ -0,0 +1,13 @@
+import fs from 'node:fs/promises';
+export async function globAll(glob) {
+    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;
+}
+//# sourceMappingURL=file-util.js.map

package/dist/tools/utils/file-util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-util.js","sourceRoot":"","sources":["../../../tools/utils/file-util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAEjC,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY;IACxC,MAAM,SAAS,GAAG,EAAE,CAAA;IACpB,IAAI,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,QAAQ,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACtE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,CAAC,UAAU,IAAI,eAAe,EAAE,EAAC,KAAK,EAAE,GAAG,EAAC,CAAC,CAAA;IAC1D,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/dist/tools/utils/html-parser.d.ts

@@ -0,0 +1 @@
+export declare function parseHTML(filename: string): Promise<Document>;

package/dist/tools/utils/html-parser.js

@@ -0,0 +1,10 @@
+import { JSDOM } from 'jsdom';
+export async function parseHTML(filename) {
+    try {
+        return (await JSDOM.fromFile(filename)).window.document;
+    }
+    catch (err) {
+        throw Error(`HTML ${filename} unparsable`, { cause: err });
+    }
+}
+//# sourceMappingURL=html-parser.js.map

package/dist/tools/utils/html-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-parser.js","sourceRoot":"","sources":["../../../tools/utils/html-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,EAAC,MAAM,OAAO,CAAA;AAE3B,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAgB;IAC9C,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAA;IACzD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,CAAC,QAAQ,QAAQ,aAAa,EAAE,EAAC,KAAK,EAAE,GAAG,EAAC,CAAC,CAAA;IAC1D,CAAC;AACH,CAAC"}

package/dist/tools/void.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+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 declare function build(args: readonly string[], env: {
+    readonly [name: string]: string | undefined;
+}): Promise<void>;

package/dist/tools/void.js

@@ -0,0 +1,30 @@
+#!/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 packageJSON from '../package.json' with { type: 'json' };
+import { parseConfigFile } from "../schema/config-file.js";
+import { bundle } from "./bundle/bundle.js";
+import { Config } from "./types/config.js";
+import { Argv } from "./utils/argv.js";
+import { exec } from "./utils/exec.js";
+import { parseHTML } from "./utils/html-parser.js";
+export async function build(args, env) {
+    const argv = Argv(args);
+    const configFile = await parseConfigFile(argv.opts['--config'] ?? 'void.json');
+    const config = Config(configFile, argv, env.npm_package_version);
+    const doc = await parseHTML(config.entry);
+    const srcFilenames = [
+        ...doc.querySelectorAll("script[type='module'][src$='.ts']")
+    ].map(el => path.resolve(path.dirname(config.entry), el.getAttribute('src')));
+    const voidVersion = {
+        hash: (await exec('git', 'rev-parse', '--short', 'HEAD')).trim(),
+        published: packageJSON.published,
+        // imported JSON doesn't treeshake. define as a constant.
+        version: packageJSON.version
+    };
+    await bundle(config, srcFilenames, voidVersion);
+}
+if (import.meta.main)
+    await build(process.argv, process.env);
+//# sourceMappingURL=void.js.map

package/dist/tools/void.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"void.js","sourceRoot":"","sources":["../../tools/void.ts"],"names":[],"mappings":";AACA,iEAAiE;AACjE,gEAAgE;AAEhE,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,WAAW,MAAM,iBAAiB,CAAC,OAAM,IAAI,EAAE,MAAM,EAAC,CAAA;AAC7D,OAAO,EAAC,eAAe,EAAC,MAAM,0BAA0B,CAAA;AAExD,OAAO,EAAC,MAAM,EAAC,MAAM,oBAAoB,CAAA;AACzC,OAAO,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAA;AACxC,OAAO,EAAC,IAAI,EAAC,MAAM,iBAAiB,CAAA;AACpC,OAAO,EAAC,IAAI,EAAC,MAAM,iBAAiB,CAAA;AACpC,OAAO,EAAC,SAAS,EAAC,MAAM,wBAAwB,CAAA;AAgBhD,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,IAAuB,EACvB,GAAkD;IAElD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;IACvB,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,WAAW,CAAC,CAAA;IAC9E,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,mBAAmB,CAAC,CAAA;IAEhE,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACzC,MAAM,YAAY,GAAG;QACnB,GAAG,GAAG,CAAC,gBAAgB,CACrB,mCAAmC,CACpC;KACF,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAE,CAAC,CAAC,CAAA;IAE9E,MAAM,WAAW,GAAgB;QAC/B,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE;QAChE,SAAS,EAAE,WAAW,CAAC,SAAS;QAChC,yDAAyD;QACzD,OAAO,EAAE,WAAW,CAAC,OAAO;KAC7B,CAAA;IAED,MAAM,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,WAAW,CAAC,CAAA;AACjD,CAAC;AAED,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI;IAAE,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAA"}

package/package.json

@@ -1,72 +1,66 @@
 {
   "author": "Stephen Niedzielski <stephen@oidoid.com> (https://oidoid.com)",
   "bin": {
-    "void": "tools/void.js"
+    "void": "tools/void.ts"
   },
   "bugs": "https://github.com/oidoid/void/issues",
-  "description": "Tiny 2D game engine.",
+  "dependencies": {
+    "@biomejs/biome": "2.2.6",
+    "esbuild": "0.25.11",
+    "html-minifier-next": "3.0.0",
+    "jsdom": "27.0.1",
+    "mem-font": "11.0.0-6"
+  },
+  "description": "basic 2D game library.",
   "devDependencies": {
-    "@ampproject/filesize": "4.3.0",
-    "@types/jsdom": "21.1.6",
-    "@types/node": "20.11.30",
-    "esbuild": "0.20.2",
-    "jsdom": "24.0.0",
-    "mem-font": "11.0.0-2",
-    "prettier": "3.2.5",
-    "typescript": "5.4.3",
-    "vitest": "1.4.0"
+    "@types/html-minifier-next": "2.1.0",
+    "@types/jsdom": "27.0.0",
+    "@types/node": "24.4.0",
+    "typescript": "5.9.3"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=24.0"
+  },
+  "exports": {
+    ".": "./dist/index.js"
   },
   "files": [
     "dist",
-    "!dist/**/tsconfig.tsbuildinfo"
+    "schema",
+    "tools",
+    "!tools/tsconfig*",
+    "!**/tsconfig.tsbuildinfo"
   ],
-  "filesize": {
-    "dist/void.js": {
-      "none": "16.7 KB",
-      "gzip": "6.3 KB"
-    }
-  },
   "homepage": "https://github.com/oidoid/void",
   "keywords": [
     "game engine",
     "webgl"
   ],
   "license": "AGPL-3.0-only",
-  "main": "dist/index.js",
   "name": "@oidoid/void",
-  "prettier": {
-    "arrowParens": "avoid",
-    "bracketSpacing": false,
-    "jsxSingleQuote": true,
-    "proseWrap": "always",
-    "semi": false,
-    "singleQuote": true,
-    "trailingComma": "none"
-  },
   "publishConfig": {
     "access": "public"
   },
+  "published": "20251020",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oidoid/void.git"
   },
   "scripts": {
-    "build": "tsc --build",
+    "build": "tsc --build && npm run build:favicon && npm run build:demo -- --minify --one-file",
+    "build:favicon": "for s in 1 2 3 4 12 32; do f=dist/public/favicon/favicon$(($s * 16)).png; aseprite src/demo/assets/favicon.aseprite --batch --color-mode=indexed --scale=$s --save-as=$f; zopflipng -y $f $f > /dev/null; done",
+    "build:demo": "tools/void.ts --config=src/demo/void.json",
     "clean": "rm -rf dist",
-    "format": "npm run formatter -- --write",
-    "formatter": "prettier --cache --log-level warn './**/*.{js,json,md,ts,yaml}'",
+    "format": "npm run formatter -- --fix",
+    "formatter": "biome check --error-on-warnings",
     "preversion": "[ -z \"$(git status -z)\" ]",
     "prepublishOnly": "! git symbolic-ref --quiet HEAD || git push --follow-tags origin \"$(git branch --show-current)\"",
-    "test": "npm run test:format && npm run test:unit && npm run build && npm run test:size",
-    "test:format": "npm run formatter -- --check",
-    "test:size": "npx esbuild --bundle --format=esm --metafile=dist/void.meta.json --minify --outfile=dist/void.js --sourcemap=linked --target=es2022 src/index.ts && filesize",
-    "test:unit": "vitest --config=tools/vitest.config.ts run",
-    "version": "npm test"
+    "start": "tsc --build --preserveWatchOutput --watch& npm run build:favicon && npm run build:demo -- --watch& wait",
+    "test": "npm run test:format && npm run test:unit && npm run build",
+    "test:format": "npm run formatter",
+    "test:unit": "sh -c 'node --experimental-test-coverage --test ${@:-$(find src schema tools -name \\*.test.ts -printf %p\\ )}' --",
+    "version": "npm pkg set published=$(date +%Y%m%d) && npm test"
   },
   "type": "module",
-  "types": "dist/index.d.ts",
-  "version": "0.1.0-3"
+  "version": "0.1.0-6"
 }

package/readme.md

@@ -1,6 +1,6 @@
 # void
 
-All of my free time goes into void.
+basic 2D game library.
 
 ## Installation
 

package/schema/config-file.test.ts

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict'
+import {test} from 'node:test'
+import {type ConfigFile, type ConfigFileSchema, parse} from './config-file.ts'
+
+test('defaults', () => {
+  const config: ConfigFileSchema = {}
+  assert.deepEqual<ConfigFile>(
+    parse('dirname/filename', JSON.stringify(config)),
+    {
+      $schema:
+        'https://raw.githubusercontent.com/oidoid/void/refs/heads/main/schema/config-file.v0.json',
+      entry: 'dirname/src/assets/index.html',
+      meta: 'dirname/dist/meta.json',
+      out: {dir: 'dirname/dist/public/', name: undefined},
+      preloadAtlas: undefined,
+
+      dirname: 'dirname',
+      filename: 'dirname/filename'
+    }
+  )
+})
+
+test('overrides', () => {
+  const config: Required<ConfigFileSchema> = {
+    $schema: '$schema',
+    entry: 'entry',
+    meta: 'meta',
+    out: {dir: 'outDir', name: 'name'},
+    preloadAtlas: {dir: 'dir/', image: 'image.png', json: 'json.json'}
+  }
+  assert.deepEqual<ConfigFile>(
+    parse('dirname/filename', JSON.stringify(config)),
+    {
+      $schema: '$schema',
+      entry: 'dirname/entry',
+      meta: 'dirname/meta',
+      out: {dir: 'dirname/outDir', name: 'name'},
+      preloadAtlas: {
+        dir: 'dirname/dir/',
+        image: 'dirname/image.png',
+        json: 'dirname/json.json'
+      },
+
+      dirname: 'dirname',
+      filename: 'dirname/filename'
+    }
+  )
+})
+
+test('overrides', () => {
+  assert.throws(
+    () => parse('dirname/filename', ''),
+    Error('config dirname/filename unparsable')
+  )
+})

package/schema/config-file.ts

@@ -0,0 +1,69 @@
+import {readFile} from 'node:fs/promises'
+import path from 'node:path'
+import schema from './config-file.v0.json' with {type: 'json'}
+
+export type AtlasConfig = {dir: string; image: string; json: string}
+
+export type ConfigFile = {
+  $schema: string
+  entry: string
+  meta: string | undefined
+  out: {dir: string; name: string | undefined}
+  preloadAtlas: AtlasConfig | undefined
+
+  /** config directory name. */
+  dirname: string
+  /** config filename. */
+  filename: string
+}
+
+export type ConfigFileSchema = {
+  $schema?: string | undefined
+  entry?: string | undefined
+  meta?: string | undefined
+  out?: {dir?: string | undefined; name?: string | undefined} | undefined
+  preloadAtlas?: AtlasConfig | undefined
+}
+
+export async function parseConfigFile(filename: string): Promise<ConfigFile> {
+  let str
+  try {
+    str = await readFile(filename, 'utf8')
+  } catch (err) {
+    throw Error(`config ${filename} unreadable`, {cause: err})
+  }
+
+  return parse(filename, str)
+}
+
+/** @internal */
+export function parse(filename: string, str: string): ConfigFile {
+  const dirname = path.dirname(filename)
+  let json: ConfigFileSchema
+  try {
+    json = JSON.parse(str)
+  } catch (err) {
+    throw Error(`config ${filename} unparsable`, {cause: err})
+  }
+
+  return {
+    $schema: json.$schema ?? schema.properties.$schema.default,
+    entry: path.join(dirname, json.entry ?? schema.properties.entry.default),
+    meta: path.join(dirname, json.meta ?? schema.properties.meta.default),
+    out: {
+      dir: path.join(
+        dirname,
+        json.out?.dir ?? schema.properties.out.properties.dir.default
+      ),
+      name: json.out?.name
+    },
+    preloadAtlas: json.preloadAtlas && {
+      dir: path.join(dirname, json.preloadAtlas.dir),
+      image: path.join(dirname, json.preloadAtlas.image),
+      json: path.join(dirname, json.preloadAtlas.json)
+    },
+
+    dirname,
+    filename
+  }
+}

package/schema/config-file.v0.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/oidoid/void/refs/heads/main/schema/config-file.v0.json",
+  "title": "void Config File Schema",
+  "type": "object",
+  "description": "a JSON representation of a void config file.",
+  "$defs": {
+    "Atlas": {
+      "type": "object",
+      "description": "sprite sheet config.",
+      "additionalProperties": false,
+      "required": ["dir", "image", "json"],
+      "properties": {
+        "dir": {
+          "type": "string",
+          "description": "Aseprite asset root directory. all `**.aseprite` files are input.",
+          "examples": ["src/assets/atlas/", "./"]
+        },
+        "image": {
+          "type": "string",
+          "description": "sprite sheet image output.",
+          "examples": ["dist/public/atlas.png", "atlas.png"]
+        },
+        "json": {
+          "type": "string",
+          "description": "sprite sheet JSON output.",
+          "examples": ["src/assets/atlas.json", "atlas.json"]
+        }
+      }
+    }
+  },
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "the configuration schema URI.",
+      "default": "https://raw.githubusercontent.com/oidoid/void/refs/heads/main/schema/config-file.v0.json"
+    },
+    "entry": {
+      "type": "string",
+      "default": "src/assets/index.html",
+      "description": "HTML entrypoint input. the file should include a script tag sourcing the TypeScript / JavaScript entrypoint."
+    },
+    "meta": {
+      "type": "string",
+      "default": "dist/meta.json",
+      "description": "esbuild bundle metadata file output."
+    },
+    "out": {
+      "type": "object",
+      "description": "output config.",
+      "additionalProperties": false,
+      "properties": {
+        "dir": {
+          "type": "string",
+          "description": "HTML and JavaScript output directory.",
+          "default": "dist/public/"
+        },
+        "name": {
+          "type": "string",
+          "description": "HTML output file stem when watch is disabled. defaults to entry.",
+          "examples": ["index", "super-patience"]
+        }
+      }
+    },
+    "preloadAtlas": {"$ref": "#/$defs/Atlas"}
+  }
+}

package/tools/atlas-pack/aseprite.ts

@@ -0,0 +1,60 @@
+import type {TagFormat} from '../../src/graphics/atlas.ts'
+import type {Box, WH} from '../../src/types/geo.ts'
+
+/** https://github.com/aseprite/aseprite/blob/master/docs/ase-file-specs.md */
+export type Aseprite = {meta: AsepriteMeta; frames: AsepriteFrameMap}
+
+export type AsepriteFrameMap = {[tag: AsepriteFrameTag]: AsepriteFrame}
+
+export type AsepriteMeta = {
+  /** `--list-tags`. */
+  frameTags: AsepriteTagSpan[]
+  size: WH
+  /** `--list-slices`. */
+  slices: AsepriteSlice[]
+}
+
+/** `--filename-format='{title}--{tag}--{frame}'`. */
+export type AsepriteFrameTag = `${TagFormat}--${bigint}`
+
+export type AsepriteFrame = {
+  /** positive animation length in milliseconds. */
+  duration: number
+  /** bounds including padding. */
+  frame: Box
+  /** WH without padding. */
+  sourceSize: WH
+}
+
+export type AsepriteTagSpan = {
+  direction: AsepriteDirection | string
+  name: TagFormat | string
+  from: number
+  /** inclusive ending index, possibly equal to from. */
+  to: number
+}
+
+export type AsepriteSlice = {
+  /** '#ff0000ff' is hitbox, '#00ff00ff' is hurtbox, '#0000ffff is both. */
+  color: string
+  name: TagFormat | string
+  keys: {bounds: Box}[]
+}
+
+export type AsepriteDirection =
+  (typeof AsepriteDirection)[keyof typeof AsepriteDirection]
+export const AsepriteDirection = {
+  /** animate from start to end; when looping, return to start. */
+  Forward: 'forward',
+  /** animate from end to start; when looping, return to end. */
+  Reverse: 'reverse',
+  /**
+   * animate from start to end - 1 or start, whichever is greater; when
+   * looping, change direction (initially, end to start + 1 or end, whichever
+   * is lesser. a traversal from start to end - 1 then end to start + 1 is
+   * considered a complete loop.
+   */
+  PingPong: 'pingpong',
+  /** like pingpong but start from end - 1 or start, whichever is greater. */
+  PingPongReverse: 'pingpong_reverse'
+} as const