@tawaship/pixi-animate-runtime 0.0.0-stage → 0.1.0

package/dist-skills/animate-data-converter-guide/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: animate-data-converter-guide
+description: Use this skill whenever the user asks to extract, inspect, or debug the data that @tawaship/animate-data-converter extracts from Adobe Animate HTML5 Canvas (CreateJS) publish output — the engine-independent symbol and timeline definitions (IDefinition). Trigger on any mention of 'animate-data-converter', 'extractPublishedFile', 'extractPublished', 'expand', 'compact', 'IDefinition', 'converterVersion', definition JSON files, or unsupported-feature 'issues' reported for Animate content. To play content on PixiJS, use the pixi-animate-runtime-guide skill instead (its generator runs this converter for you); with Pixim.js, the pixim-animate-runtime-guide skill.
+---
+
+# @tawaship/animate-data-converter development skill
+
+Supported versions: **`^0.1.0`** (written against `0.1.0`).
+
+First determine the installed version (`node_modules/@tawaship/animate-data-converter/package.json`). If it is outside the supported range, **treat the type definitions in node_modules as authoritative** and follow them wherever they disagree with this skill.
+
+The content is assumed to be published by **Adobe Animate 24.0.15** for HTML5 Canvas, the only version checked: this package depends on the form of the published JavaScript. If the user's content comes from another version of Animate and something does not work, mention this before looking for other causes.
+
+## Overview
+
+`@tawaship/animate-data-converter` reads the JavaScript that Adobe Animate publishes for HTML5 Canvas and extracts every symbol and its timeline as plain data (JSON-compatible), one definition per symbol, shared by every instance. A player for a specific engine builds on this data, so content can be played without CreateJS or the published code at play time.
+
+- It runs in **Node.js 18 or later only**, at development time. Never suggest running it in the browser
+- It reads only the published JavaScript. Images and sounds are not read, and CreateJS 1.0.0 comes with the package
+- Most users do not call it directly: `@tawaship/pixi-animate-runtime`'s generator (`npx --no-install @tawaship/pixi-animate-runtime`) runs it. Use the converter directly only to keep definitions as files, to inspect them, or to build a player of your own
+
+## Type definition files
+
+**Before writing code that uses this package, check the corresponding type definition file.** Read them from the package installed in the project (`node_modules/@tawaship/animate-data-converter/types/`); that is the single source of truth.
+
+| What | Type definition file |
+|---|---|
+| Entry point (everything exported) | `types/index.d.ts` |
+| The definition (`IDefinition` and the types it is made of) | `types/types.d.ts` |
+| `extractPublishedFile`, `extractPublished` | `types/load.d.ts` |
+| `expand`, `compact`, `SLOT_DEFAULTS` | `types/compact.d.ts` |
+| `extract` | `types/extract.d.ts` |
+| The CreateJS surface `extract` reads | `types/createjs.d.ts` |
+
+## Basic usage
+
+### Command line
+
+```sh
+npx --no-install @tawaship/animate-data-converter game.js --out game.json --pretty
+```
+
+- `-o, --out <file>`: where to write (standard output without it). `-p, --pretty`: indented JSON. `-e, --expanded`: the expanded form instead of the compact one. `-f, --force`: write even with unsupported features. `-h, --help`: the usage
+- Exit code `1` when the content uses unsupported features (each one is listed, nothing is written unless `--force` is given), `2` when the file cannot be read or is not Animate HTML5 Canvas output
+
+### API
+
+```js
+const { extractPublishedFile } = require('@tawaship/animate-data-converter');
+
+extractPublishedFile('game.js').then(definition => {
+  definition.issues.forEach(issue => console.warn(issue.symbol, issue.message));
+});
+```
+
+The published code runs in a sandbox (QuickJS, a JavaScript engine compiled to WebAssembly, given nothing of the host), so extraction is asynchronous. Still tell the user to convert only content they trust (see the README).
+
+| Function | Use it for |
+|---|---|
+| `extractPublishedFile(path)` | Extracting from a file (returns a promise) |
+| `extractPublished({ published })` | Extracting from source text already in hand (returns a promise) |
+| `extract(createjs, source)` | Extracting from content already running in an environment you set up |
+| `expand(definition)` / `compact(expanded)` | Converting between the compact form (what extraction gives) and the expanded form (every value as it is) |
+
+When calling `extract()` on an environment of your own, images created while symbols are constructed must report that they have loaded as soon as an `onload` handler is assigned; otherwise bitmap fills from sprite sheets are missing from the definition. Prefer `extractPublished()`, which runs the published code in its sandbox (QuickJS) and does this.
+
+## What the definition holds
+
+The definition is extracted in its **compact form** (`form: 'compact'`): every value kept, written once (drawings in the content's `graphics` with `commandKinds`, slots as `slotTemplates` plus initial values, each tween's distinct `values` with the index of every position's values in `frames`). `expand()` gives the **expanded form** (`form: 'expanded'`), every value where it applies; read `IExpandedDefinition` for that. The README's "Reading a definition" explains both. pixi-animate-runtime's generator takes the compact form only.
+
+
+- `symbols`: every symbol of the published `lib`, under its library name (non-ASCII names kept as they are). Published content has no root of its own; any symbol can be played as a root (the published HTML picks one)
+- For a movie clip: labels, length, the display objects it owns with their initial state, masks, buttons, color effects, caching, and its tweens with **the exact value of every controlled property at every frame** (not approximated)
+- Frame scripts as their **source text**, unchanged. They are not run or rewritten
+- `manifest`, `spriteSheets`, `properties` (size, frame rate, background color), `issues`
+- `converterVersion`: the converter version that extracted it. A reader of kept definition files can tell from it whether it knows their form
+
+## Important notes
+
+### Unsupported content is reported, not guessed
+
+When `issues` is not empty, the content uses something outside the supported range (the Animate camera / "Advanced Layers", filters other than color effects, event listeners added by symbol code, hand-written looping/reversed tweens, non-plain frame script functions, display objects other than MovieClip/Shape/Sprite/Bitmap/Text). Report the listed issues to the user and suggest changing the Animate document (for the camera: delete the camera layer and publish again). Do not suggest `--force` as a fix: it only writes the data anyway.
+
+### Publish again → extract again
+
+The definition is a snapshot of one publish. After the content is published again from Animate, extract (or generate) again.

package/dist-skills/pixi-animate-runtime-guide/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: pixi-animate-runtime-guide
+description: Use this skill whenever the user asks to create, edit, or debug content using @tawaship/pixi-animate-runtime — a player that plays Adobe Animate HTML5 Canvas (CreateJS) content on pixi.js from runtime content files generated at development time, without CreateJS. Trigger on any mention of 'pixi-animate-runtime', 'runtime content', 'Animate コンテンツ', 'Adobe Animate' or 'createjs' in a project that has @tawaship/pixi-animate-runtime installed, or on concepts like loadContentAsync, AnimateContainer, AnimateController, content.create, PIXI.animateRuntime, or the 'npx pixi-animate-runtime' command. If the project uses @tawaship/pixi-animate-container instead (CreateJS at run time, loadAssetAsync), use the pixi-animate-container-guide skill. If the user is working with Pixim.js, use the pixim-animate-runtime-guide skill (it builds on this one).
+---
+
+# @tawaship/pixi-animate-runtime development skill
+
+Supported versions: **`^0.1.0`** (written against `0.1.0`).
+
+First determine the installed version (`node_modules/@tawaship/pixi-animate-runtime/package.json`). If it is outside the supported range, **treat the type definitions in node_modules as authoritative** and follow them wherever they disagree with this skill.
+
+The content is assumed to be published by **Adobe Animate 24.0.15** for HTML5 Canvas, the only version checked: this package depends on the form of the published JavaScript. If the user's content comes from another version of Animate and something does not work, mention this before looking for other causes.
+
+## Dependencies
+
+Read these skills first if they are available, then apply this one:
+
+- A PixiJS v5.3 skill (such as pixijs-guide): the player runs on pixi.js 5.3 (`^5.3.2`)
+
+## Overview
+
+"Animate content" is what Adobe Animate publishes in HTML5 Canvas mode: a JavaScript file (plus images) that runs on CreateJS. This package plays it on pixi.js in two steps:
+
+1. **At development time (Node.js 18+)**, the generator turns the published JavaScript into a **runtime content file** (one per published file). This runs CreateJS once and records every symbol
+2. **In the browser**, the player loads runtime content files and plays them. **CreateJS and the published JavaScript are not loaded**
+
+Consequences to keep in mind:
+
+- **After the content is published again from Animate, the runtime content must be generated again.** The player never reads the published `.js`. When a change made in Animate does not show, check this first
+- Never write `<script>` tags for CreateJS or the published `.js` in a project using this package
+
+## Type definition files
+
+**Before writing code that uses a class, method, or property of this package, check the corresponding type definition file** in the installed package (`node_modules/@tawaship/pixi-animate-runtime/`). That is the single source of truth.
+
+| What | Type definition file |
+|---|---|
+| Everything the player exports | `types/player/index.d.ts` |
+| `loadContentAsync`, `IContentTarget` (the load options) | `types/player/loader.d.ts` |
+| `IContent` (`create`, `lib`, `properties`, `id`), `tick` | `types/player/content.d.ts` |
+| `AnimateContainer`, `AnimateController` | `types/player/animate-container.d.ts` |
+| `MovieClip` (`play`, `stop`, `gotoAndPlay`, `labels`, ...) | `types/player/movieclip.d.ts` |
+| `DisplayObject`, `Container` (the CreateJS-compatible base classes, `pixi`) | `types/player/display.d.ts` |
+| `Shape`, `Sprite`, `Bitmap`, `Text`, `ButtonHelper`, `ColorFilter` | `types/player/objects.d.ts` |
+| The generator (Node): `planGeneration`, `writeGeneration`, `generateFromPublishedFile`, `generate` | `types/generator/generator/index.d.ts` (the plan types in `types/generator/generator/plan.d.ts`) |
+
+## Basic usage
+
+### 1. Generate the runtime content (development time)
+
+```sh
+npx --no-install @tawaship/pixi-animate-runtime assets/animates
+```
+
+Give it the directory Animate published into. It writes `assets/animates/generated/<same name>.js` for every published `.js`, and copies the images each content uses next to it (`generated/images/...`). Copy the `generated/` directory into the application's assets.
+
+- `-o, --out-dir <dir>` writes there instead of `generated/`. `-r, --recursive` also converts the published files in the directories below (not `node_modules` or hidden ones), written below `-o` at the same relative paths, or next to each published file in `generated/`. `-h, --help` shows the usage. A published `.js` file instead of a directory converts only that file
+- It first lists what it would write as a table (where from and where to, then for each published file its composition id shortened to 8 characters, the number of images, and new / replace / not written with the reason). For the whole composition id, read `lib.properties.id` in the published file or the comment at the top of the runtime content file. It writes only after the user answers `y`. `-y, --yes` asks nothing and writes; run from a script, an npm script in CI or anything that is not a terminal, **`-y` is needed** (without it, nothing is written and the command exits with `1`)
+- Nothing is deleted. Leftover files in the output directory are only listed
+- Always write the command as `npx --no-install @tawaship/pixi-animate-runtime` (in npm scripts, `pixi-animate-runtime` alone). A bare `npx pixi-animate-runtime` in a project where the package is not installed downloads and runs an unscoped package of that name from the npm registry, without asking in CI or scripts. `yes=false` in the project's `.npmrc` keeps `npx` from downloading anything
+- From a Node script, `planGeneration(options)` (the same options as the command: `input`, `outDir`, `recursive`, `force`) makes everything and writes nothing, and `writeGeneration(plan)` writes it, so the script can show its own list or questions in between (or remove contents from the plan to write only some)
+- A content using unsupported features (each one listed) is not written, and the command exits with `1`. Report the listed features to the user; do not reach for `--force`
+- On Windows, `tools/pixi-animate-runtime.bat` in the installed package does the same (copy it into the project, drop the published directory on it)
+- The command prints each content's **composition id**, needed below
+
+### 2. Load and play (browser)
+
+```html
+<script src="pixi.js"></script>
+<script src="pixi-animate-runtime.js"></script>
+<script src="assets/animates/generated/game.js"></script><!-- runtime content file -->
+```
+
+```javascript
+const { loadContentAsync, AnimateContainer } = PIXI.animateRuntime;
+
+loadContentAsync({ id: 'COMPOSITION_ID', basepath: 'assets/animates/generated/' })
+  .then((content) => {
+    const container = new AnimateContainer();
+    app.stage.addChild(container);
+    app.ticker.add(container.handleTick, container); // required: nothing plays without it
+
+    container.addCreatejs(content.create('game')); // the symbol the published HTML used as its root
+  });
+```
+
+- Runtime content files must be loaded (script tags, or script elements added at run time) **before** `loadContentAsync` is called. They register under their composition id
+- `id`: the composition id (`lib.properties.id`; printed by the command, and written at the top of the runtime content file). When nothing is registered under it, the error lists what is
+- `basepath`: the directory the runtime content file was written to, ending with `/`; images are loaded relative to it
+- `options.crossOrigin: false` loads images without CORS. `options.handleManifest(manifest)` can change image `src` before loading
+- An array of targets gives an array of contents
+- With a bundler: `import { loadContentAsync, AnimateContainer } from '@tawaship/pixi-animate-runtime'`. Runtime content files are still loaded as scripts
+
+### 3. Creating instances
+
+- `content.create('symbolName')` creates an instance set up the way the published HTML sets up its root. Use it for every instance the application places
+- `new content.lib.symbolName()` is what frame scripts do; it skips that setup
+- `content.properties` holds the published `lib.properties` (`width`, `height`, `fps`, `color`, ...)
+- Symbol names are the library names in Animate (non-ASCII names kept as they are)
+
+### 4. AnimateContainer
+
+- `addCreatejs(instance)` / `addCreatejsAt(instance, index)` put an instance on the container; a movie clip plays from its first frame. `removeCreatejs(instance)` takes it off and it stops
+- Content plays at its published frame rate whatever the display's refresh rate
+- `speed`: playback speed (`1` = published frame rate, `0` stops)
+- `overSpeed` (default `true`): when the display runs slower than the content, one tick may play several frames. `false` plays at most one frame per tick
+- `smooth` (default `true`): frames follow a steady clock, so small variations of the frame time do not make the playing uneven (no frame on one tick, two on the next); it still keeps to the real time. Leave it on unless the user asks for the pixi-animate-container behavior (`false`)
+- To play on a container of another PixiJS framework, use `new AnimateController(container)`; it has the same `addCreatejs`, `handleTick`, `speed`, `overSpeed`, `smooth`
+
+## Objects and their PixiJS nodes
+
+Every instance is a CreateJS-compatible object (what frame scripts see as `this`), shown by a PixiJS node in its `pixi` property. Common values are stored once: `instance.x = 100` and `instance.pixi.x = 100` are the same write, and `instance.pixi` is always current.
+
+Members whose meaning differs keep the CreateJS meaning on the instance and the PixiJS meaning on the node:
+
+| Member | On the instance | On `instance.pixi` |
+|---|---|---|
+| `rotation` | Degrees | Radians (`angle` is degrees) |
+| `skewX` / `skewY` | Degrees, CreateJS skew | `skew` in radians |
+| `mask`, `filters`, `parent`, `children` | CreateJS-compatible objects | PixiJS objects |
+
+- **Do not draw into a shape's `pixi` node** (`clear()`, `lineTo()`, ...): shapes showing the same drawing share one geometry, so the change shows everywhere
+- Named instances placed in Animate (`this.button`, ...) exist at run time but are not in the types (`MovieClip` has no index signature)
+- `addEventListener` / `dispatchEvent` follow CreateJS, so the usual pattern of dispatching an event from a frame script and listening in the application works
+- Frame scripts run as published. They see `this`, `cjs` / `createjs` (the player's compatible classes, not real CreateJS) and `lib`. `exportRoot` and `stage` are undefined; `playSound()` plays nothing
+
+## Current limits (tell the user instead of working around silently)
+
+- Buttons do not react to the pointer and CreateJS mouse events (`click`, `mousedown`, `rollover`, ...) are never called. For input, listen to PixiJS events on `instance.pixi` (`pointertap`, ... with `interactive = true`)
+- Sound is not played
+- The Animate camera ("Advanced Layers") is not supported: delete the camera layer and publish again
+- Dynamic text: lines break as in the published content; vertical position can differ slightly by font
+
+## Coming from pixi-animate-container
+
+| pixi-animate-container | pixi-animate-runtime |
+|---|---|
+| Script tags for CreateJS and the published `.js` | Script tag for the runtime content file only |
+| `PIXI.animate` | `PIXI.animateRuntime` |
+| `loadAssetAsync(targets)` → `lib` | `loadContentAsync(targets)` → content (`content.lib`) |
+| `new lib.game()` | `content.create('game')` |
+| `PIXI.animate.Container` | `AnimateContainer` |
+| `createjsSpeed` / `createjsOverSpeed` | `speed` / `overSpeed` |
+| `CreatejsMovieClip` etc. | `MovieClip` etc. |
+
+Not available: `listenFrameEvents`, `useSound`, CreateJS mouse events.

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@tawaship/pixi-animate-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Plays Adobe Animate HTML5 Canvas content on PixiJS from definitions extracted by @tawaship/animate-data-converter.",
+  "main": "dist/pixi-animate-runtime.cjs.js",
+  "module": "dist/pixi-animate-runtime.esm.js",
+  "browser": "dist/pixi-animate-runtime.js",
+  "types": "types/player/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/player/index.d.ts",
+      "import": "./dist/pixi-animate-runtime.esm.js",
+      "require": "./dist/pixi-animate-runtime.cjs.js"
+    },
+    "./generator": {
+      "types": "./types/generator/generator/index.d.ts",
+      "require": "./dist/generator.cjs.js"
+    }
+  },
+  "bin": {
+    "pixi-animate-runtime": "bin/pixi-animate-runtime.js"
+  },
+  "files": [
+    "dist",
+    "types",
+    "bin",
+    "tools",
+    "dist-skills"
+  ],
+  "scripts": {
+    "rollup": "rollup -c --bundleConfigAsCjs",
+    "d": "tsc -p tsconfig.player.json --emitDeclarationOnly --declaration --outDir ./types/player && tsc -p tsconfig.generator.json --emitDeclarationOnly --declaration --outDir ./types/generator",
+    "build": "npm run rollup -- --environment PROD && npm run d && echo done.",
+    "docs": "typedoc",
+    "prepublishOnly": "node scripts/check-publish.js"
+  },
+  "keywords": [
+    "pixi.js",
+    "adobe-animate",
+    "createjs"
+  ],
+  "author": "tawaship",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tawaship/pixi-animate-runtime.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tawaship/pixi-animate-runtime/issues"
+  },
+  "homepage": "https://tawaship.github.io/pixi-animate-runtime/",
+  "peerDependencies": {
+    "pixi.js": "^5.3.2"
+  },
+  "dependencies": {
+    "@tawaship/animate-data-converter": "^0.1.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-buble": "^1.0.3",
+    "@rollup/plugin-typescript": "^12.3.1",
+    "@types/node": "^20.19.43",
+    "del": "^8.0.1",
+    "pixi.js": "5.3.9",
+    "rollup": "^4.65.0",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.20",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/tools/pixi-animate-runtime.bat

@@ -0,0 +1,8 @@
+@echo off
+rem Generates runtime content for pixi-animate-runtime.
+rem Drop a directory of Animate published content (or a published .js file) on this file,
+rem or double-click it to be asked for the directory.
+rem Put this file in your project (where pixi-animate-runtime is installed).
+cd /d "%~dp0"
+call npx --no-install @tawaship/pixi-animate-runtime %*
+pause

package/types/generator/generator/cli.d.ts

@@ -0,0 +1,17 @@
+export interface ICliIO {
+    stdout(text: string): void;
+    stderr(text: string): void;
+    /** Asks a question and gives the answer; absent when nobody can answer (not a terminal) */
+    ask?(question: string): Promise<string>;
+    /** The directory relative paths are taken from */
+    cwd?: string;
+}
+/**
+ * The command line tool: {@link planGeneration}, the plan listed (and, in a
+ * terminal, confirmed; without one, written only with -y), then
+ * {@link writeGeneration}. Returns the exit code: 0 when every content was
+ * written, 1 when some could not be (unsupported features without --force,
+ * images the content uses that are missing) or nothing was written for want of
+ * a "y", 2 for usage and loading errors.
+ */
+export declare function runCli(args: string[], io: ICliIO): Promise<number>;

package/types/generator/generator/converter-version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The animate-data-converter versions this generator reads definitions of:
+ * the range this package depends on, and the version it was built with
+ * (written in from package.json when the package is built).
+ */
+export declare const CONVERTER_RANGE: string;
+export declare const CONVERTER_KNOWN: string;

package/types/generator/generator/generate.d.ts

@@ -0,0 +1,33 @@
+import type { IDefinition, IIssue } from '@tawaship/animate-data-converter';
+import type { IRuntimeData } from '../player/data';
+export interface IGenerated {
+    /** The composition id the runtime content is registered under */
+    id: string;
+    /** The content's data (what the runtime content returns as `data`) */
+    data: IRuntimeData;
+    /** Frame script sources, by the index the data refers to them with */
+    scripts: string[];
+    /** Writer function sources, by the index the data refers to them with */
+    writers: string[];
+    /** Member writer function sources, by the index the data refers to them with */
+    memberWriters: string[];
+    /** The runtime content (JavaScript source) */
+    source: string;
+    /** Unsupported features the converter found */
+    issues: IIssue[];
+    /** Things to look at that did not stop the generation (a definition from a newer converter) */
+    warnings: string[];
+}
+/** The composition id of a content (lib.properties.id): the id its runtime content is registered and loaded under */
+export declare function compositionId(definition: IDefinition): string;
+/**
+ * Generates the runtime content of a content from its extracted definition.
+ * It is registered under the content's composition id; `sourceName` (the
+ * published file it came from) is written into it to tell contents apart in
+ * messages.
+ */
+export declare function generate(definition: IDefinition, sourceName?: string): IGenerated;
+/**
+ * Extracts a published file and generates its runtime content.
+ */
+export declare function generateFromPublishedFile(publishedPath: string): Promise<IGenerated>;

package/types/generator/generator/index.d.ts

@@ -0,0 +1,6 @@
+export { compositionId, generate, generateFromPublishedFile } from './generate';
+export type { IGenerated } from './generate';
+export { planGeneration, writeGeneration } from './plan';
+export type { IPlanOptions, IGenerationPlan, IPlannedContent, IPlannedImage, IWriteResult } from './plan';
+export { runCli } from './cli';
+export type { ICliIO } from './cli';

package/types/generator/generator/plan.d.ts

@@ -0,0 +1,87 @@
+import type { IIssue } from '@tawaship/animate-data-converter';
+export interface IPlanOptions {
+    /** A directory of published content (every published JavaScript file directly in it), or one published file */
+    input: string;
+    /**
+     * Where to write: each content below it, at the path of its published file
+     * from the input directory. Absent or null: generated/ next to each published file
+     */
+    outDir?: string | null;
+    /** Also look in the directories below the input directory (not node_modules, nor directories whose name starts with ".") */
+    recursive?: boolean;
+    /** Write runtime content even when the content uses unsupported features */
+    force?: boolean;
+    /** The directory relative paths are taken from (default: the current directory) */
+    cwd?: string;
+}
+export interface IPlannedImage {
+    /** The image file next to the published file */
+    from: string;
+    /** Where it is copied */
+    to: string;
+}
+export interface IPlannedContent {
+    /** The published file */
+    published: string;
+    /** Its path from the input directory ("/" separated) */
+    name: string;
+    /** The composition id it registers under; null when the published file could not be read */
+    id: string | null;
+    /** Where its runtime content is written */
+    out: string;
+    /** Whether a file is already there (writing replaces it) */
+    exists: boolean;
+    /** The images it uses, copied next to its runtime content at the same relative paths */
+    images: IPlannedImage[];
+    /** The runtime content (JavaScript source) that is written; null when it is not written */
+    source: string | null;
+    /** Unsupported features the content uses (written anyway only with force) */
+    issues: IIssue[];
+    /** Things to look at that did not stop the generation */
+    warnings: string[];
+    /** Why it is not written; null when it is */
+    problem: string | null;
+}
+export interface IGenerationPlan {
+    /** The directory the names are taken from: the input directory, or the directory of the input file */
+    root: string;
+    /** The output directory; null when each content goes into generated/ next to its published file */
+    outDir: string | null;
+    /** Every published file found, in order */
+    contents: IPlannedContent[];
+    /** Files already in the output directories; the ones the plan does not write are left as they are */
+    existing: string[];
+}
+export interface IWriteResult {
+    /** The files written (runtime content and images) */
+    written: string[];
+    /** The files already in the output directories that were not written (nothing is deleted) */
+    left: string[];
+}
+/** A path from a directory, "/" separated */
+export declare function relativePath(from: string, file: string): string;
+/**
+ * The published files an input names, and the directory their names are
+ * taken from. Only reads the files (nothing is run). Throws when the input
+ * does not exist or has no published file.
+ */
+export declare function findPublished(input: string, recursive?: boolean, cwd?: string): {
+    root: string;
+    files: string[];
+};
+/**
+ * Finds the published files, makes their runtime content and works out where
+ * everything would be written, without writing anything. Each published file
+ * is run in a sandbox of its own, one after another. What cannot be written
+ * (a file that cannot be read, unsupported features without force, missing
+ * images) is in the plan with its problem. Throws when the input does not
+ * exist, has no published file, or the output would be a published directory.
+ * {@link writeGeneration} writes the plan.
+ */
+export declare function planGeneration(options: IPlanOptions): Promise<IGenerationPlan>;
+/**
+ * Writes a plan made by {@link planGeneration}: the runtime content it made
+ * (as it was when the plan was made) and copies of the images. The contents
+ * with a problem are not written. Nothing is deleted.
+ */
+export declare function writeGeneration(plan: IGenerationPlan): IWriteResult;

package/types/generator/player/data.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The data of runtime content (what the generator writes and the player reads): the definition
+ * extracted by @tawaship/animate-data-converter, with every frame script
+ * taken out of the data and referenced by its index in the runtime content's
+ * script list (the scripts themselves are code in the runtime content), and with
+ * the writes of each tween and of each instance's initial values compiled
+ * into writer functions (code in the runtime content as well, referenced by index).
+ * Drawings are gathered into one table for the whole content, identical
+ * ones merged, and a symbol refers to them by index.
+ */
+import type { IMovieClipSymbolDef, ISpriteSymbolDef, IBitmapSymbolDef, ITweenDef, IPropMapDef, ISlotDef, IManifestEntryDef, ISpriteSheetDef, IGraphicsCommandDef, IStateEntryDef, TDataValue, TFrameValue } from '@tawaship/animate-data-converter';
+import { TEase } from './ease';
+/** A kind of drawing command: its type and the names of its props, in order */
+export type TRuntimeCommandKind = [string, string[]];
+/** A drawing command as written in runtime content: the index of its kind, then its props' values in the kind's order */
+export type TRuntimeCommand = TDataValue[];
+/** A drawing as written in runtime content */
+export interface IRuntimeGraphicsData {
+    commands: TRuntimeCommand[];
+}
+/** A drawing's commands as the player draws them, from their written form */
+export declare function commandsOf(kinds: TRuntimeCommandKind[], graphics: IRuntimeGraphicsData): IGraphicsCommandDef[];
+export type { ISlotDef, ITweenDef, IStateEntryDef, IGraphicsDef, IGraphicsCommandDef, ISpriteDef, IBitmapDef, IFilterDef, ICacheDef, IButtonDef, IFilterCacheEntryDef, IRectDef, IDataMap, IPropMapDef, IManifestEntryDef, ISpriteSheetDef, ILabelDef, IMemberDef, TTargetDef, TFrameValue, TDataValue, ISpriteSymbolDef, IBitmapSymbolDef } from '@tawaship/animate-data-converter';
+/**
+ * The pixi-animate-runtime versions whose runtime content this player plays
+ * (npm's range notation). Raised when the player stops playing runtime
+ * content older versions made.
+ */
+export declare const RUNTIME_CONTENT_RANGE = "0.x";
+export interface IRuntimeActionDef {
+    /** Timeline position the action sits on */
+    position: number;
+    /** Index into the runtime content's script list */
+    script: number;
+    params: TFrameValue[] | null;
+}
+export interface IRuntimeTweenDef extends Omit<ITweenDef, 'actions' | 'frames'> {
+    actions: IRuntimeActionDef[];
+    /** The tween's distinct frame values (each the values of its props, in order) */
+    values: TFrameValue[][];
+    /** For every position, the index of its values in values (a position holding the same values as another shares them) */
+    frames: number[];
+    /**
+     * Index into the runtime content's writer list: the function that writes a frame's
+     * values (values[frames[position]]) to the target, one property after another by
+     * name (null when the tween writes no property)
+     */
+    writer: number | null;
+}
+/**
+ * A slot as the player uses it. Its initial values are in code only (the
+ * writer), not in the data.
+ */
+/**
+ * A frame value as written in runtime content: a display list (`state`) may
+ * give an entry that places a slot as it is (no props) as the slot's index
+ */
+export type TRuntimeFrameValue = TFrameValue | Array<IStateEntryDef | number>;
+/**
+ * A position, or a stretch of positions, of a tween as written in runtime
+ * content: the index of the position's values, or an interpolated stretch
+ * [from, to, length, ease] whose positions run from values[from] toward
+ * values[to] (the position after the stretch) as CreateJS interpolates a
+ * step with that ease (see interpolated)
+ */
+export type TRuntimeFrameRef = number | [number, number, number, string];
+/** A tween as written in runtime content (tweenOf makes its values for every position) */
+export interface IRuntimeTweenData extends Omit<IRuntimeTweenDef, 'values' | 'frames'> {
+    values: TRuntimeFrameValue[][];
+    frames: TRuntimeFrameRef[];
+}
+/**
+ * The values at a position of a step, as CreateJS's Tween computes them: the
+ * ratio of the position in the step, eased, then each value from its start
+ * toward its end (a value that is not a number, or does not change, keeps its
+ * start until the eased ratio reaches 1).
+ */
+export declare function interpolated(from: TFrameValue[], to: TFrameValue[], position: number, length: number, ease: TEase | null): TFrameValue[];
+/**
+ * A tween with the values of every position: its display lists (the values of
+ * its `state` prop) as entries, and its interpolated stretches computed (each
+ * position of a stretch gets values of its own)
+ */
+export declare function tweenOf(data: IRuntimeTweenData): IRuntimeTweenDef;
+export interface IRuntimeSlotDef extends Omit<ISlotDef, 'init'> {
+    /** Index into the runtime content's writer list: the function that writes the slot's initial values (initValues) */
+    initWriter: number | null;
+    /** The slot's initial values, in the order its writer writes them */
+    initValues: TFrameValue[] | null;
+}
+/** The values a slot's fields have when runtime content leaves them out */
+export declare const SLOT_DEFAULTS: Omit<IRuntimeSlotDef, 'kind'>;
+/**
+ * A slot template as written in runtime content: its kind, and the fields not
+ * at their defaults (SLOT_DEFAULTS); its initial values are the slot's own
+ */
+export type TRuntimeSlotData = Pick<IRuntimeSlotDef, 'kind'> & Partial<Omit<IRuntimeSlotDef, 'kind' | 'initValues'>>;
+/**
+ * A slot as written in a symbol: the index of its template in the content's
+ * slotTemplates, with its initial values when it has some
+ */
+export type TRuntimeSlotRef = number | [number, TFrameValue[]];
+/** A slot from its template (the fields left out at their defaults) and its initial values */
+export declare function slotOf(templates: TRuntimeSlotData[], ref: TRuntimeSlotRef): IRuntimeSlotDef;
+export interface IRuntimeMovieClipDef extends Omit<IMovieClipSymbolDef, 'tweens' | 'slots' | 'graphics' | 'members'> {
+    /** The slots as written (templates and initial values; slotOf makes them whole) */
+    slots: TRuntimeSlotRef[];
+    /** The tweens as written (display lists with slot indexes; tweenOf turns them back into entries) */
+    tweens: IRuntimeTweenData[];
+    /**
+     * Index into the runtime content's member writer list: the function that
+     * gives an instance its named children (`this.instance = ...`), or null
+     * when it has none
+     */
+    memberWriter: number | null;
+    /**
+     * The symbol's drawings as indexes into the content's drawing table
+     * (graphics[n] is the drawing the symbol's slots and tween values call n)
+     */
+    graphics: number[];
+}
+export type TRuntimeSymbolDef = IRuntimeMovieClipDef | ISpriteSymbolDef | IBitmapSymbolDef;
+export interface IRuntimeData {
+    /** The version of pixi-animate-runtime that generated the runtime content */
+    runtimeVersion: string;
+    /** Primitive entries of the published lib.properties (width, height, fps, color, ...) */
+    properties: IPropMapDef;
+    /** Images of the published manifest (sounds are left out) */
+    images: IManifestEntryDef[];
+    /** The published lib.ssMetadata */
+    spriteSheets: ISpriteSheetDef[];
+    /** Every drawing of the content, identical ones merged (shared by every symbol that shows them); commandsOf reads them */
+    graphics: IRuntimeGraphicsData[];
+    /** The kinds of the drawings' commands (a type and the names of its props) */
+    commandKinds: TRuntimeCommandKind[];
+    /** The slots of every symbol but their initial values, identical ones merged */
+    slotTemplates: TRuntimeSlotData[];
+    symbols: {
+        [id: string]: TRuntimeSymbolDef;
+    };
+}

package/types/generator/player/ease.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The eases of CreateJS (createjs.Ease), computed as CreateJS computes them,
+ * by name. Runtime content names the ease of an interpolated stretch of a
+ * tween; the player computes the stretch's values with it once, when a symbol's
+ * class is made. `get:<amount>` is Ease.get(amount) (Animate's classic ease).
+ */
+export type TEase = (t: number) => number;
+/** The ease runtime content names (null for a name the player does not know) */
+export declare function easeOf(id: string): TEase | null;
+/** The eases the generator tries for a stretch of a tween, by name: the named ones, then Ease.get(-1 .. 1) in hundredths */
+export declare function easeIds(): string[];