@potoru/authoring

Make Potoru 2D animation from code: a typed authoring API, check / export / lint as functions, and the potoru command line. Projects are format v4 source folders (small YAML files that people and LLM agents edit directly); export writes the .poto package the player plays.

npm install @potoru/authoring

API

import { Project } from "@potoru/authoring";

const project = Project.create({ id: "sunrise", name: "Sunrise", format: 4 });
project.scene("hill", { stage: { width: 960, height: 540 }, duration: 3 }, (scene) => {
  scene.rect("sky", { at: [0, 0], size: [960, 540], fill: "#203a6b" });
  scene.ellipse("sun", { at: [430, 400], size: [100, 100], fill: "#ffcc33" });
  scene.state("main", { duration: 3 }, (t) => {
    t.tween("sun", "y", { from: 400, to: 120, duration: 3, easing: "easeOut" });
  });
});
await project.save("stories/sunrise");          // a v4 source folder ("sunrise.potoru": one zip file)

const again = await Project.load("stories/sunrise");   // folder, .potoru zip, or legacy JSON
const bytes = await again.toBytes();                    // Project.fromBytes(bytes) reads them

Part references take a handle, the key the part was made with, its full id, or a slash path of names. Every error is a PotoruError with a stable code, a diagnostic ({code, severity, message, file?, path?, fix?, didYouMean?}) and, for validation, every finding in diagnostics.

| Entry | What | |---|---| | @potoru/authoring | Project and the builders, gradients, presets, measureText, PotoruError | | @potoru/authoring/node | file helpers: imageFile, audioFile, fontFile, importSvgFile, openLibraryFolder, builtinFonts, loadEngines | | @potoru/authoring/tools | check, exportPackage, lint, simulate, size, render, presets, measure, runPotoru | | @potoru/authoring/experimental | rigging (drives, skins, meshes, spring bones, constraints), strokes, hops, the engines, the format toolkit: may change in a minor release | | @potoru/authoring/legacy | schema-3 JSON (openProject, serializeProject): deprecated |

Strokes, interaction (on: / machine:) and path guides use WebAssembly engines; in Node, call await loadEngines() from @potoru/authoring/node once before using them.

Tools as functions

import { check, exportPackage, render } from "@potoru/authoring/tools";

const result = await check("stories/sunrise");
for (const d of result.diagnostics) console.log(`${d.file}: ${d.severity} [${d.code}] ${d.message}`);
if (result.ok) {
  await exportPackage("stories/sunrise", "dist/sunrise.poto");
  await render("dist/sunrise.poto", { out: "dist/sunrise.png", times: [1.5], scale: 0.5 });
}

Each returns {ok, command, exitCode, diagnostics, outputs, stats, data, text} and never throws for a finding or a usage mistake. Paths in results are relative or base names.

Command line

npx potoru new stories/sunrise --id sunrise --scene hill --width 960 --height 540 --duration 3
npx potoru check stories/sunrise
npx potoru export stories/sunrise dist/sunrise.poto
npx potoru render dist/sunrise.poto --time 1.5 --scale 0.5 --out dist/sunrise.png
npx potoru size dist/sunrise.poto --json
npx potoru help

• --json on every command prints one JSON document (the same result as the functions).
• Exit codes: 0 ok (warnings allowed; --strict makes warnings fail), 1 findings or errors, 2 usage or missing input. Unknown options are refused with a "did you mean".
• lint, simulate, skin, mesh, strokes, bones, machine are experimental.
• Library folders: --lib-dir <folder> or POTORU_LIB_DIR.
• potoru video is not part of 0.1 (it needs Chrome or a native renderer); render draws PNG frames through @potoru/render without either.

Runtimes

Node 20 or newer, ES modules only. The root entry loads no Node built-ins, so bundlers can use the API in other runtimes; file helpers, tools and the CLI need Node. Versions move in lockstep with @potoru/web (which also compiles source folders in browsers: compile({ yaml })), @potoru/react and @potoru/render.

Licence

Apache-2.0 (LICENSE, NOTICE). The wasm engines contain third-party Rust crates and the package ships three fonts under the SIL Open Font License 1.1: see THIRD-PARTY-NOTICES.txt. Depends on @xmldom/xmldom (MIT) and @potoru/render. "Potoru" is a trademark of The Potoru Authors.