@caperjs/core 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) Relish Interactive
+Copyright (c) 2026 Anthony Sapp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @caperjs/core
+
+> An opinionated HTML game framework built on [PixiJS v8](https://pixijs.com).
+
+`@caperjs/core` is the framework package of [Caper](https://github.com/anthonysapp/caper), a personal fork of [dill-pixel](https://github.com/relishinc/dill-pixel) by Relish Studios that narrows scope, modernizes the dependency stack, and ships fewer half-finished things.
+
+It sits on top of PixiJS — a renderer, not a game engine — and adds the parts you'd otherwise rebuild for every project: scenes, plugins, asset pipeline, build config, type-safe IDs, signals, and a project layout that scales from a 48-hour jam to something you ship.
+
+## Status
+
+This package is **not yet published to npm**. The recommended way to use it is to clone the [Caper monorepo](https://github.com/anthonysapp/caper), run the kitchen-sink, and either fork it as a starter or vendor `packages/core` into your own project. First publish lands in Phase 7.
+
+## Highlights
+
+- **Pixi v8 native**, pinned to the latest 8.x
+- **Auto-discovered scenes / plugins / popups / entities** via the bundled Vite plugin — drop a file in the right directory, the build picks it up
+- **Type-safe IDs** for scenes, plugins, popups, entities, locale keys (string-literal unions on every API that takes one)
+- **Per-bundle asset types** generated from your AssetPack manifest
+- **Plugin `requires: [...]`** declarations + topological sort at bootstrap
+- **Build-time validation** for asset bundles, plugin IDs, dependency cycles, duplicate IDs
+- **Exported Vite + AssetPack config** (`@caperjs/core/config/vite`, `@caperjs/core/config/assetpack`)
+- **`caper add` CLI** for scaffolding scenes, plugins, entities, popups
+- **Signals** via `typed-signals`
+- **Tested** — Vitest covers `Plugin`, `Store`, `Scene`, `SignalRegistry`
+
+## Minimal example
+
+```ts
+// src/scenes/MenuScene.ts
+import { defineScene, Scene } from '@caperjs/core';
+
+export const scene = defineScene({
+  id: 'menu',
+  assets: { preload: { bundles: ['ui'] } },
+});
+
+export default class MenuScene extends Scene {
+  initialize() {
+    this.add.text({
+      text: 'Caper',
+      anchor: 0.5,
+      style: { fontFamily: 'system-ui', fontSize: 64, fill: 0xffffff },
+    });
+  }
+}
+```
+
+The Vite plugin discovers this file on next reload. The id `'menu'` flows into the generated `AppScenes` union, so `app.scenes.load('menu')` is fully typed.
+
+## Documentation
+
+There's no docs site yet — the upstream `apps/docs/` was deleted in Phase 6 because it almost entirely described pre-fork state. A new docs surface will land when there's enough audience to justify it. Until then, the [`plan/`](https://github.com/anthonysapp/caper/tree/main/plan) directory + JSDoc on `Scene` and `IPlugin` are the documentation:
+
+- `plan/fork-plan.md` — long-form architectural rationale
+- `plan/tasks.md` — execution log of what's shipped and why
+- `CLAUDE.md` — repo conventions and common commands
+
+The kitchen-sink ([`apps/kitchen-sink/`](https://github.com/anthonysapp/caper/tree/main/apps/kitchen-sink)) is the canonical reference implementation — every plugin, every UI primitive, scenes, popups, entities, signals, storage all exercised end-to-end.
+
+## License
+
+MIT. Original dill-pixel framework architecture credit to Relish Studios.

package/cli/add.mjs

@@ -0,0 +1,197 @@
+import { bold, cyan, green, red, yellow } from 'kleur/colors';
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * `caper add <kind> <Name>` — scaffolds a single file under `src/<kind>s/`
+ * for a scene, plugin, entity, or popup, using the project's discovery
+ * conventions (default-exported class, optional `defineX({...})` wrapper
+ * with an `id`). The file is intentionally minimal — just enough that the
+ * Vite plugin's discovery picks it up immediately on next dev reload.
+ */
+
+const KINDS = ['scene', 'plugin', 'entity', 'popup'];
+
+// Convert a user-supplied name into a PascalCase class name and a
+// kebab-case id, regardless of input casing. "my cool scene" → MyCoolScene
+// + my-cool-scene; "MyCoolScene" → MyCoolScene + my-cool-scene.
+function normalizeName(raw) {
+  const cleaned = raw
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
+    .trim()
+    .split(/\s+/);
+  if (cleaned.length === 0 || !cleaned[0]) {
+    throw new Error(`Invalid name: ${JSON.stringify(raw)}`);
+  }
+  const className = cleaned
+    .map((word) => {
+      // Split on lowercase→uppercase boundary so "MyCoolScene" stays MyCoolScene
+      // rather than getting collapsed.
+      return word
+        .split(/(?=[A-Z])/)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join('');
+    })
+    .join('');
+  const id = className
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+  return { className, id };
+}
+
+const TEMPLATES = {
+  scene: ({ className, id }) => `import { defineScene, Scene } from '@caperjs/core';
+
+export const scene = defineScene({
+  id: '${id}',
+  active: true,
+  // assets: { preload: { bundles: ['default'] } },
+});
+
+export default class ${className} extends Scene {
+  initialize() {
+    // build the scene's display tree here
+  }
+
+  start() {
+    // start jobs / timelines here
+  }
+
+  resize() {
+    // re-layout on viewport changes
+  }
+
+  update() {
+    // per-frame loop
+  }
+
+  destroy() {
+    super.destroy();
+    // clean up listeners / timers
+  }
+}
+`,
+
+  plugin: ({ className, id }) => `import { definePlugin, IApplication, Logger, Plugin } from '@caperjs/core';
+
+export const plugin = definePlugin({
+  id: '${id}',
+  // requires: ['firebase'], // other plugin IDs that must initialize before this one
+});
+
+export type ${className}PluginOptions = {
+  // TODO: add plugin options here
+};
+
+const defaultOptions: ${className}PluginOptions = {};
+
+export default class ${className}Plugin extends Plugin<${className}PluginOptions> {
+  public readonly id = '${id}';
+
+  protected _options: ${className}PluginOptions = defaultOptions;
+
+  async initialize(options: Partial<${className}PluginOptions> = {}, _app: IApplication): Promise<void> {
+    this._options = { ...defaultOptions, ...options };
+    Logger.log('${className} plugin initialized');
+  }
+}
+`,
+
+  entity: ({ className, id }) => `import { Container, defineEntity } from '@caperjs/core';
+
+export const entity = defineEntity({
+  id: '${id}',
+});
+
+export default class ${className} extends Container {
+  constructor() {
+    super();
+    this.init();
+  }
+
+  init() {
+    // build the entity's display tree here
+  }
+}
+`,
+
+  popup: ({ className, id }) => `import { Container, definePopup, IPopup, Popup } from '@caperjs/core';
+
+export const popup = definePopup({
+  id: '${id}',
+});
+
+export default class ${className}Popup extends Popup implements IPopup {
+  window: Container;
+
+  initialize() {
+    this.window = this.view.add.container();
+    // build the popup contents on this.window
+  }
+
+  async show() {
+    // entry animation
+  }
+
+  async hide() {
+    // exit animation
+  }
+}
+`,
+};
+
+const DIRS = {
+  scene: 'src/scenes',
+  plugin: 'src/plugins',
+  entity: 'src/entities',
+  popup: 'src/popups',
+};
+
+const SUFFIXES = {
+  scene: '',
+  plugin: 'Plugin',
+  entity: '',
+  popup: 'Popup',
+};
+
+export async function add(args) {
+  const [kind, rawName, ...rest] = args;
+
+  if (!kind || !KINDS.includes(kind)) {
+    console.error(red(`caper add: missing or unknown kind. Expected one of: ${KINDS.join(', ')}`));
+    console.error(`Usage: caper add <${KINDS.join('|')}> <Name> [--dir path]`);
+    process.exit(1);
+  }
+  if (!rawName) {
+    console.error(red(`caper add ${kind}: missing name. Usage: caper add ${kind} <Name>`));
+    process.exit(1);
+  }
+
+  // Optional --dir override; defaults to the conventional discovery dir
+  let targetDir = DIRS[kind];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--dir' && rest[i + 1]) {
+      targetDir = rest[i + 1];
+      i++;
+    }
+  }
+
+  const { className, id } = normalizeName(rawName);
+  const fileName = `${className}${SUFFIXES[kind]}.ts`;
+  const fullDir = path.resolve(process.cwd(), targetDir);
+  const fullPath = path.join(fullDir, fileName);
+
+  if (fs.existsSync(fullPath)) {
+    console.error(red(`caper add ${kind}: ${path.relative(process.cwd(), fullPath)} already exists. Aborting.`));
+    process.exit(1);
+  }
+
+  fs.mkdirSync(fullDir, { recursive: true });
+  fs.writeFileSync(fullPath, TEMPLATES[kind]({ className, id }), 'utf-8');
+
+  console.log(green(bold(`✓ Created ${kind}`)) + ` ${cyan(path.relative(process.cwd(), fullPath))}`);
+  console.log(`  ${yellow('id:')}    ${id}`);
+  console.log(`  ${yellow('class:')} ${className}${SUFFIXES[kind]}`);
+  console.log(`\n  Discovery will pick this up on the next dev-server reload.`);
+}

package/cli/audio/cc.mjs

@@ -0,0 +1,128 @@
+import { parse } from 'csv-parse/sync';
+import { bgGreen, bold, green, white } from 'kleur/colors';
+import { exec } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { walkDir } from './utils.mjs';
+
+
+const durations = {};
+const captions = {};
+
+async function readDurations(dir) {
+  console.log('readDurations', dir);
+  const files = [];
+  const outputDir = path.join(dir, '');
+  if (!fs.existsSync(outputDir)) {
+    return Promise.reject(`Output directory not found at "${outputDir}". Please run \`caper audio compress\` first.`);
+  }
+  walkDir(outputDir, file => {
+    if (/\.(wav|mp3)$/i.test(file)) {
+      files.push(file);
+    }
+  });
+  await Promise.all(files.map(file => new Promise((resolve, reject) => {
+    exec(`ffprobe -v quiet -print_format compact=print_section=0:nokey=1:escape=csv -show_entries format=duration "${file}"`, (e, duration) => {
+      duration = parseInt((parseFloat(duration) * 1000).toFixed(0));
+      const name = path.basename(file).replace(/\.(wav|mp3)$/, '');
+      durations[name] = duration;
+      console.log(bold(bgGreen(white('[Get Duration]'))), green(name), white(duration));
+      resolve();
+    });
+  })));
+}
+
+async function readCaptions(dir) {
+  const captionsDir = path.join(dir, 'captions');
+
+  if (!fs.existsSync(captionsDir)) {
+    return Promise.reject(`Captions directory not found. Please create a captions directory at "${captionsDir}", and add your captions CSV files.`);
+  }
+
+  for (const csvFileName of fs.readdirSync(captionsDir)) {
+    if (path.extname(csvFileName) !== '.csv') {
+      continue;
+    }
+    const csvFile = path.join(captionsDir, csvFileName);
+    console.log(bold(bgGreen(white('[Read CSV]'))), green(csvFile));
+    const csv = parse(fs.readFileSync(csvFile, { encoding: 'utf-8' }), {
+      comment: '#',
+    });
+    const sectionColumn = csv[0].reduce((a, t, i) => t === 'Section' ? i : a, -1);
+    const fileColumn = csv[0].reduce((a, t, i) => t === 'FILENAME' || t === 'File Name' ? i : a, -1);
+    const textColumn = csv[0].reduce((a, t, i) => t === 'LINE' || t === 'VO Line' ? i : a, -1);
+    const startOffsetColumn = csv[0].indexOf('START_OFFSET');
+    const endOffsetColumn = csv[0].indexOf('END_OFFSET');
+
+    function processRow(file, row) {
+      const duration = durations[file];
+      const text = normalizeText(row[textColumn]);
+      if (file && text && duration && !captions[file]) {
+        const lines = text.split('--').map(it => normalizeText(it)).filter(it => !!it);
+        fixSpecialCases(file, lines);
+        if (lines.length > 0) {
+          let start = 0;
+          const length = lines.reduce((a, t) => a + t.length, 0);
+          captions[file] = [];
+          for (const line of lines) {
+            const end = start + line.length;
+            const startOffset = parseInt(row[startOffsetColumn] || 0);
+            const endOffset = parseInt(row[endOffsetColumn] || 0);
+            captions[file].push({
+              content: `<p>${line}</p>`,
+              start: Math.round(duration * start / length) + startOffset,
+              end: Math.round(duration * end / length) + endOffset,
+            });
+            start = end;
+          }
+        } else {
+          captions[file] = [{ content: `<p>${text}</p>`, start: 0, end: duration }];
+        }
+        console.log(bold(bgGreen(white(`[Generate CC]`))), green(file));
+        for (const cc of captions[file]) {
+          console.log('\t\t', cc.start, cc.end, cc.content);
+        }
+      }
+    }
+
+    for (let i = 1; i < csv.length; i++) {
+      const row = csv[i];
+      let file = (row[fileColumn] || '').replace(/\.(wav|mp3)$/, '');
+      processRow(file, row);
+    }
+  }
+}
+
+function normalizeText(text) {
+  text = text ?? '';
+  text = text.replace(/^\s+/, '');
+  text = text.replace(/\s+$/, '');
+  text = text.replace(/(\s*)–(\s*)/ig, '$1-$2');
+  text = text.replace(/’/ig, '\'');
+  text = text.replace(/“/ig, '"');
+  text = text.replace(/”/ig, '"');
+  text = text.replace(/…/ig, '...');
+  text = text.replace(/^--/ig, '');
+  text = text.replace(/--$/ig, '');
+  return text;
+}
+
+async function writeCaptions(outputDir) {
+  console.log(bold(bgGreen(white('[Writing Captions]'))), green(outputDir));
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  fs.writeFileSync(`${outputDir}/cc.json`, JSON.stringify(captions, null, 2), { encoding: 'utf-8' });
+}
+
+function fixSpecialCases(file, lines) {
+  switch (file) {
+    case 'anim-03-c':
+      lines.pop();
+      break;
+  }
+}
+
+export async function generateCaptions(dir, outputDir = dir) {
+  return readDurations(outputDir).then(() => readCaptions(dir)).then(() => writeCaptions(outputDir));
+}

package/cli/audio/index.mjs

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {execPromise, walkDir} from './utils.mjs';
+
+const SOURCE_DIR = 'source';
+const OUTPUT_DIR = 'output';
+
+/**
+ * @param {string} file
+ * @returns {Promise<Awaited<unknown>[]>}
+ */
+function compressFile(file) {
+	if (/\.(wav|m4a|mp3|ogg)$/i.test(file)) {
+		let outDir = path.dirname(file).replace(SOURCE_DIR, OUTPUT_DIR);
+		let outFile = path.join(outDir, path.basename(file)).replace(/\.\w+$/, '');
+
+		if (!fs.existsSync(outDir)) {
+			fs.mkdirSync(outDir);
+		}
+
+		const p1 = execPromise(`ffmpeg -i "${file}" -y -c:a libvorbis -q:a 1 -ac 1 "${outFile}.webm"`)
+		const p2 = execPromise(`ffmpeg -i "${file}" -y -c:a libmp3lame -b:a 128k -ac 1 "${outFile}.mp3"`)
+
+		return Promise.all([p1, p2]);
+	}
+}
+
+/**
+ * Compresses audio files in a directory.
+ * @param dir
+ * @returns {Promise<*[]>}
+ */
+export async function compress(dir) {
+	const sourceDir = path.join(dir, SOURCE_DIR);
+	if (!fs.existsSync(sourceDir)) {
+		return new Promise((resolve, reject) => {
+			reject(`No source directory found at ${sourceDir}`);
+		})
+	}
+	return walkDir(sourceDir, compressFile);
+}
+

package/cli/audio/utils.mjs

@@ -0,0 +1,56 @@
+import {exec} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Logs the output of an exec command.
+ * @param err
+ * @param stdout
+ * @param stderr
+ */
+export function logExec(err, stdout, stderr) {
+	console.log(stdout);
+	console.error(err);
+	console.error(stderr);
+}
+
+/**
+ * Executes a command and returns a promise.
+ * @param command
+ * @returns {Promise<unknown>}
+ */
+export function execPromise(command) {
+	return new Promise((resolve, reject) => {
+		exec(command, (err, stdout, stderr) => {
+			logExec(err, stdout, stderr);
+			if (err) {
+				reject(err);
+			}
+			resolve();
+		});
+	})
+}
+
+
+/**
+ * Walks a directory and executes a callback on each file.
+ * @param dir
+ * @param callback
+ * @param promises
+ * @returns {*[]}
+ */
+export function walkDir(dir, callback, promises = []) {
+	const files = fs.readdirSync(dir);
+	for (let i = 0; i < files.length; i++) {
+		const f = files[i];
+		let dirPath = path.join(dir, f);
+		let isDirectory = fs.statSync(dirPath).isDirectory();
+		if (isDirectory) {
+			walkDir(dirPath, callback, promises);
+		} else {
+			promises.push(callback(path.join(dir, f)));
+		}
+	}
+	return promises;
+}
+

package/cli/create-caper.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import {exec} from 'node:child_process';
+
+function create() {
+	exec(`caper create`);
+}
+
+create();