@pixel-studio/core 0.0.0-stage → 0.2.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +200 -2
  3. package/bin/pixel.mjs +313 -0
  4. package/docs/DESIGN.md +118 -0
  5. package/docs/README.md +19 -0
  6. package/docs/SPEC.md +467 -0
  7. package/docs/api.md +1891 -0
  8. package/docs/architecture.md +854 -0
  9. package/docs/cli.md +578 -0
  10. package/docs/figures.md +476 -0
  11. package/docs/getting-started.md +85 -0
  12. package/docs/playground.md +134 -0
  13. package/docs/runtime.md +664 -0
  14. package/docs/stage.md +398 -0
  15. package/examples/fox.json +85 -0
  16. package/examples/goose-base.json +94 -0
  17. package/examples/goose-greylag.json +192 -0
  18. package/examples/goose-kiddie.json +68 -0
  19. package/examples/goose-phreak.json +69 -0
  20. package/examples/goose-root.json +136 -0
  21. package/examples/goose-sudo.json +78 -0
  22. package/examples/moss.json +1715 -0
  23. package/examples/pip.json +74 -0
  24. package/examples/plugins/extras.mjs +53 -0
  25. package/examples/plugins/starfish.json +21 -0
  26. package/examples/robot.json +81 -0
  27. package/examples/slime.json +46 -0
  28. package/figures/blob.json +19 -0
  29. package/figures/chibi.json +43 -0
  30. package/figures/dog.json +60 -0
  31. package/figures/goose-front.json +56 -0
  32. package/figures/goose.json +70 -0
  33. package/figures/human.json +66 -0
  34. package/package.json +56 -4
  35. package/references/CREDITS.md +56 -0
  36. package/references/README.md +92 -0
  37. package/references/dog.json +167 -0
  38. package/references/goose-greylag.json +23 -0
  39. package/references/goose.json +95 -0
  40. package/references/human.json +281 -0
  41. package/references/measurements/bird-adjutant-pl774.json +597 -0
  42. package/references/measurements/bird-cockatoo-pl758.json +746 -0
  43. package/references/measurements/bird-ostrich-pl772.json +503 -0
  44. package/references/measurements/bird-pigeon-pl755.json +424 -0
  45. package/references/measurements/bird-pigeon-pl756.json +433 -0
  46. package/references/measurements/bird-pigeon-pl757.json +460 -0
  47. package/references/measurements/bird-vulture-pl765.json +800 -0
  48. package/references/measurements/bird-vulture-pl768.json +329 -0
  49. package/references/measurements/dog-pl706.json +196 -0
  50. package/references/measurements/dog-pl707.json +234 -0
  51. package/references/measurements/dog-pl708.json +262 -0
  52. package/references/measurements/dog-pl709.json +347 -0
  53. package/references/measurements/dog-pl710.json +325 -0
  54. package/references/measurements/human-pl001.json +1079 -0
  55. package/references/measurements/human-pl006.json +365 -0
  56. package/references/measurements/human-pl013.json +283 -0
  57. package/references/measurements/human-pl060.json +977 -0
  58. package/references/measurements/human-pl062.json +1183 -0
  59. package/references/measurements/human-pl064.json +1133 -0
  60. package/references/measurements/human-pl088.json +887 -0
  61. package/references/measurements/human-pl109.json +1037 -0
  62. package/references/measurements/human-pl111.json +365 -0
  63. package/references/measurements/human-pl152.json +681 -0
  64. package/references/measurements/human-pl159.json +700 -0
  65. package/references/measurements/human-pl161.json +660 -0
  66. package/references/measurements/human-pl162.json +695 -0
  67. package/references/measurements/human-pl236.json +595 -0
  68. package/references/measurements/human-pl249.json +556 -0
  69. package/references/sources.json +794 -0
  70. package/src/core/animate.js +172 -0
  71. package/src/core/ascii.js +22 -0
  72. package/src/core/bundle.js +152 -0
  73. package/src/core/color.js +112 -0
  74. package/src/core/export.js +58 -0
  75. package/src/core/extend.js +161 -0
  76. package/src/core/figure.js +340 -0
  77. package/src/core/image.js +61 -0
  78. package/src/core/index.js +19 -0
  79. package/src/core/internal.js +10 -0
  80. package/src/core/lint.js +56 -0
  81. package/src/core/mix.js +41 -0
  82. package/src/core/motion.js +521 -0
  83. package/src/core/plugins.js +96 -0
  84. package/src/core/png.js +113 -0
  85. package/src/core/render.js +346 -0
  86. package/src/core/rig.js +169 -0
  87. package/src/core/shapes.js +119 -0
  88. package/src/core/spec.js +457 -0
  89. package/src/core/textures.js +60 -0
  90. package/src/node/png.js +9 -0
  91. package/src/runtime.js +3 -0
  92. package/src/stage.js +2 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pavel Pascari
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,201 @@
1
- # Temporary Holding Version
1
+ # Pixel Studio
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Agents describe characters; the engine draws them as pixel art at every level of detail; websites play them with one tag.**
4
+
5
+ ```
6
+ agent ──JSON rig──▶ engine (SDF raster + pixel-art shader) ──▶ bundle (16/32/64 px sheets) ──▶ <pixel-sprite>
7
+ ▲ │
8
+ └──────────── preview PNG / ASCII / validation errors ◀──┘
9
+ ```
10
+
11
+ Plain ES modules, no build step. Node ≥ 20 for the CLI; any current browser for the runtime. MIT licensed.
12
+ Two packages, always released with the same version:
13
+
14
+ - **`@pixel-studio/core`** (this one): the engine, the `pixel` CLI, the figure library, examples and docs. Its only
15
+ dependency is the runtime.
16
+ - **[`@pixel-studio/runtime`](https://www.npmjs.com/package/@pixel-studio/runtime)**: `<pixel-sprite>` and
17
+ `<pixel-stage>`, the web components that play finished sprites. No dependencies; a site that only shows sprites
18
+ installs just this.
19
+
20
+ Docs and live demos: **[pixel-studio.sh](https://pixel-studio.sh)**.
21
+
22
+ > **Status: alpha.** The engine, CLI and web components work and are tested, and every page of pixel-studio.sh runs
23
+ > on them. The spec and bundle formats may still change before 1.0; each change is listed in the
24
+ > [changelog](../../CHANGELOG.md).
25
+
26
+ ## Five minutes to a goose on your page
27
+
28
+ ```bash
29
+ npm i @pixel-studio/core # brings @pixel-studio/runtime, nothing else
30
+ ```
31
+
32
+ Make a character by changing an example (`my-goose.json`):
33
+
34
+ ```json
35
+ { "extends": "./node_modules/@pixel-studio/core/examples/goose-base.json",
36
+ "name": "Marigold",
37
+ "materials": { "feather": { "color": "#e8b04a" }, "beak": { "color": "#d94b32" } } }
38
+ ```
39
+
40
+ ```bash
41
+ npx pixel validate my-goose.json # errors with JSON paths and did-you-mean
42
+ npx pixel preview my-goose.json --out my-goose.png # every animation at 16, 32 and 64 px
43
+ npx pixel bundle my-goose.json --out my-goose.bundle.json
44
+ ```
45
+
46
+ ```html
47
+ <script type="module" src="node_modules/@pixel-studio/runtime/src/pixel-sprite.js"></script>
48
+ <pixel-sprite src="my-goose.bundle.json" anim="idle" size="128" hover-anim="waddle" click-anim="honk"></pixel-sprite>
49
+ ```
50
+
51
+ The full walk-through is [docs/getting-started.md](docs/getting-started.md).
52
+
53
+ Characters can also live on the page itself: walk along cards, jump between them, climb their sides, sit on edges
54
+ and hide behind things ([docs/stage.md](docs/stage.md)):
55
+
56
+ ```html
57
+ <script type="module" src="pixel-stage.js"></script>
58
+ <article class="card" data-pixel-surface data-pixel-climbable>…</article>
59
+ <pixel-stage><pixel-actor src="goose.bundle.json" size="64"></pixel-actor></pixel-stage>
60
+ ```
61
+
62
+ ## The CLI: the agent's hands and eyes
63
+
64
+ ```bash
65
+ npx pixel validate examples/fox.json
66
+ npx pixel preview examples/fox.json --out fox.png # every animation × 16/32/64 px
67
+ npx pixel ascii examples/fox.json --res 24 --anim walk # text view for agents without vision
68
+ npx pixel where examples/goose-root.json --anim honk # world positions of pivots, per frame
69
+ npx pixel resolve examples/goose-sudo.json # a variant merged with its base
70
+ npx pixel bundle examples/fox.json --out fox.bundle.json
71
+ npx pixel export examples/fox.json --res 32 --out game/ # PNG + Aseprite JSON (Phaser, PixiJS)
72
+ npx pixel figures # the skeleton library
73
+ npx pixel brief # the agent brief (system prompt)
74
+ ```
75
+
76
+ (In a clone of the repository, run `node bin/pixel.mjs` from `packages/pixel-studio/` instead of `npx pixel`, and
77
+ the example paths work as written. Working on Pixel Studio itself: see
78
+ [CONTRIBUTING.md](../../CONTRIBUTING.md).)
79
+
80
+ ## Documentation
81
+
82
+ Start with [docs/getting-started.md](docs/getting-started.md), or read everything on
83
+ [pixel-studio.sh](https://pixel-studio.sh/docs/). The reference docs, also in this package's `docs/`:
84
+
85
+ | doc | covers |
86
+ |---|---|
87
+ | [docs/getting-started.md](docs/getting-started.md) | Install, write a character, preview, bundle, put it on a page. |
88
+ | [docs/SPEC.md](docs/SPEC.md) | The character spec. It doubles as the agent brief. |
89
+ | [docs/figures.md](docs/figures.md) | Figures, motion models, follow-through, writing a new figure. |
90
+ | [docs/runtime.md](docs/runtime.md) | `<pixel-sprite>`, the bundle format, events, attachment points, state machines, skins, moving sprites on a page. |
91
+ | [docs/stage.md](docs/stage.md) | `<pixel-stage>`: characters that walk, jump, climb, sit and hide on a real page. |
92
+ | [docs/cli.md](docs/cli.md) | Every CLI command and flag. |
93
+ | [docs/api.md](docs/api.md) | The JavaScript API. |
94
+ | [docs/playground.md](docs/playground.md) | The playground page: a character set up entirely by its URL, for people and browser agents. |
95
+ | [docs/architecture.md](docs/architecture.md) | How the engine works inside, and how to extend it. |
96
+ | [docs/DESIGN.md](docs/DESIGN.md) | Why it is designed this way. |
97
+
98
+ ## What's in this package
99
+
100
+ | Path | What |
101
+ |---|---|
102
+ | `src/core/` | The isomorphic engine: spec validation (JSON paths + did-you-mean), figures and motion models, rig maths and IK, variants, SDF shapes, the rasterizer and pixel-art shader (hue-shifted ramps, lighting, textures, dither, outlines, inner lines, contact shadows), sheets, bundles, export, ASCII, plug-ins. |
103
+ | `src/node/png.js` | The Node PNG encoder the CLI uses. |
104
+ | `src/runtime.js`, `src/stage.js` | `@pixel-studio/core/runtime` and `@pixel-studio/core/stage`: re-export [`@pixel-studio/runtime`](https://www.npmjs.com/package/@pixel-studio/runtime), the web components. |
105
+ | `bin/pixel.mjs` | The CLI. `--plugin` loads plug-ins (shapes, textures, motion models; see `examples/plugins/`). |
106
+ | `figures/` | The **figure library**: `goose` (and `goose-front` for its front and back views), `human`, `dog`, `chibi` (front-facing), `blob` (soft body). |
107
+ | `examples/` | Characters: `goose-base` and its variants `goose-root`, `-sudo`, `-phreak`, `-kiddie`, `-greylag`; `pip`; `fox`, `slime`, `robot` (written by a separate agent that only had `SPEC.md` and the CLI); `moss`. |
108
+ | `references/` | Where motion data comes from: every source cited, every measured value and frame logged ([references/README.md](references/README.md), credits in [references/CREDITS.md](references/CREDITS.md)). |
109
+ | `docs/` | The reference docs above. |
110
+
111
+ The studio (live JSON editor, onion skin, all detail levels at once, an **Agent** tab), the figure viewer, the
112
+ playground and the demo pages live in the [repository](https://github.com/pavelpascari/pixel-studio) and run on
113
+ [pixel-studio.sh](https://pixel-studio.sh/gallery/).
114
+
115
+ ## Levels of detail and texture
116
+
117
+ The same spec renders at any resolution. The detail tier changes how it is drawn:
118
+
119
+ | tier | default at | tones | texture | dither | outline | extras |
120
+ |---|---|---|---|---|---|---|
121
+ | 1 icon | ≤ 20 px | 2 | off | off | dark | brighter ambient, only `minDetail: 1` shapes |
122
+ | 2 sprite | 21–40 px | 3 | 60% | off | selective | contact shadows |
123
+ | 3 portrait | > 40 px | 5 | 100% | on | selective | inner lines between overlapping parts |
124
+
125
+ Textures: `noise fur scales stripes checker cloth bricks spots metal`. They are evaluated in each part's local space, so they stick to moving limbs. Materials can also carry `shine`, `flat`, and `outline: false`. Every knob can be overridden per spec (`style`) or live in the studio.
126
+
127
+ ## The agent loop, tested
128
+
129
+ To check the premise, I gave a fresh agent only `docs/SPEC.md` and the CLI and asked for three characters. It produced `fox`, `slime` and `robot` through about three preview-and-revise rounds each. Its friction report drove these engine fixes:
130
+
131
+ - Eyes and other detail parts cast contact shadows that looked like tears. Fixed: flat and `outline:false` materials no longer cast them.
132
+ - Seams appeared where same-material shapes overlapped. Fixed: they are now lit as one surface (union SDF).
133
+ - Typos like `minDetal` were ignored silently. Fixed: unknown keys produce warnings with did-you-mean.
134
+ - `sx`/`sy` waves centred on 0. Fixed: they now oscillate around 1.
135
+ - The icon tier was too dark. Fixed: it gets an ambient boost.
136
+ - The brief was missing several things: a style-key table, pivot = scale origin, pixel-grid alignment for tiny features, and no small head rotations.
137
+
138
+ Still open: tiny features are at the mercy of the pixel grid (at 16 px the fox's four legs merge), and there is no
139
+ alpha or glow.
140
+
141
+ ## Authoring helpers (added while building the goose flock)
142
+
143
+ Each one came from a specific problem building the geese:
144
+
145
+ | problem | feature |
146
+ |---|---|
147
+ | Four geese were four copied 700-line files that drifted apart | **`extends` variants**: a base rig plus about 45 lines of differences per goose (patch/add/remove parts, merge materials and animations, `materialMap`) |
148
+ | Getting the beak onto the keyboard meant guessing three joint angles per frame | **`reach` constraints**: name the chain, the tip point and an animatable target (optionally the head's `aim`); the engine solves the angles each frame |
149
+ | A honk pushed the head off-canvas and I only noticed in previews | **Bounds warnings**: "`head` goes 8.2 units past the right edge in frames 2–7" from `validate`, the CLI and the studio status bar |
150
+ | Unreachable targets fail silently | **Reach warnings**: by how much, which frames, and what to relax |
151
+ | Hard to tell where a joint actually is mid-animation | `pixel where` on the CLI and the **rig** toggle in the studio (pivots, bones, reach targets turning red when missed) |
152
+
153
+ ## Figures and motion models
154
+
155
+ Skeletons are dots and lines with realistic motion models. A character picks a figure (`"figure": "goose"`), dresses its bones with shapes, and gets its motions:
156
+
157
+ - **gait** (walk, run, trot, sneak). Feet are planted with IK and swing on real paths. The hips rise and fall with the legs, a four-legged figure's back pitches, and the head keeps its gaze steady. Each gait exports a `speed`, so a page that moves the sprite at that speed gets no foot sliding. The flock uses this.
158
+ - **idle**: breathing and weight shifting over planted feet.
159
+ - **pose**: your keyframes drive the body and the feet stay planted.
160
+ - **hop**: a gravity arc with volume-preserving squash and stretch, a lean into the jump, and a ground shadow that shrinks in the air.
161
+ - **Front view** (`chibi`): walking toward the viewer, the hips shift over the standing foot and lifted legs foreshorten.
162
+ - **Follow-through**: `"follow"` springs make tails, ears, hoods and straps lag, overshoot and settle.
163
+ - **For life on a page**: `jump` (crouch, launch, tuck, land), `climb` (feet holding a wall, with a `speedY`), `fall`,
164
+ `sit` on an edge, and `duck`/`peek` presets. Motions report events (`footstep`, `launch`, `land`), and figures define
165
+ attachment points (`beak`, `head`, hands) and the foot line, all baked into bundles.
166
+
167
+ Author tracks layer on top of the motion. **Every example is dressed on a figure:** the geese on `goose`, Ember on `dog`
168
+ (fitted: shorter neck, bushy tail), Pip and Bolt on `chibi` (Bolt fitted to its boxier proportions, with a springy antenna),
169
+ and Gloop on `blob`. phreak's sneak is the `sneak` preset plus a floppy disk, and honks, headbangs and waves are `pose` motions.
170
+
171
+ ```bash
172
+ npx pixel figures # list the library
173
+ npx pixel preview dog # a bare figure: its skeleton, every motion
174
+ ```
175
+
176
+ ## Agent tab (Claude in the browser)
177
+
178
+ In the studio, in the [repository](https://github.com/pavelpascari/pixel-studio) (`npm run studio`).
179
+
180
+ Describe a character, then **Generate**: Claude writes the spec, the studio validates it, and any validation errors go back to Claude for a fix. **Look & refine** renders a contact sheet (16/32/64 × every animation), sends the image back, and asks Claude to critique it like a pixel artist and return a revised spec.
181
+
182
+ - Your API key is stored only in `localStorage`. Requests go directly from the browser to the API (`dangerouslyAllowBrowser`), which is fine for a local prototype but not for a hosted app. A hosted version needs a small server-side proxy.
183
+ - The default model is `claude-opus-5-5`, with adaptive thinking at effort `medium`. The server-side fallback beta is on (`fallbacks: "default"`), so a safety-classifier refusal is routed to a fallback model instead of failing. To turn it off, remove `betas`/`fallbacks` in `studio/agent.js`.
184
+ - The SDK loads from esm.sh on first use, so the rest of the studio works offline.
185
+ - **This path has not been run end-to-end yet; it needs your key.** The extraction and validation-repair logic is exercised; the live API call isn't.
186
+
187
+ ## Known limitations and out of scope
188
+
189
+ - The spec and bundle formats are not frozen until 1.0.
190
+ - Parts are rigid: no mesh deformation, no pixel-level touch-up layers, no palette constraints across characters.
191
+ - No GIF/APNG export; PNG sheets, Aseprite JSON and bundles only.
192
+ - The studio's Agent tab is a local prototype (see above).
193
+
194
+ See [docs/DESIGN.md](docs/DESIGN.md) and the research notes in the repository's [docs/research/](../../docs/research/).
195
+
196
+ ## Contributing and license
197
+
198
+ See [CONTRIBUTING.md](../../CONTRIBUTING.md). Pixel Studio is released under the [MIT License](LICENSE).
199
+ Motion data comes only from public-domain and openly licensed sources (Muybridge's plates, published measurements);
200
+ each is credited in [references/CREDITS.md](references/CREDITS.md).
201
+ The studio's optional Agent tab loads the Anthropic SDK (MIT) from esm.sh at runtime; nothing third-party is bundled.
package/bin/pixel.mjs ADDED
@@ -0,0 +1,313 @@
1
+ #!/usr/bin/env node
2
+ // Pixel Studio CLI — the agent's hands and eyes.
3
+ //
4
+ // pixel validate <spec.json> check a spec, print errors with JSON paths
5
+ // pixel preview <spec.json> [--out p.png] [--res 16,32,64] [--cell 128] [--anim a,b]
6
+ // contact sheet: every animation (or those named) × every LOD tier
7
+ // pixel ascii <spec.json> [--res 24] [--anim idle] [--frame 0|all]
8
+ // a frame as text (for agents without vision)
9
+ // pixel render <spec.json> [--res 32] [--out dir] [--lod 1|2|3] [--tones n] [--texture 0..1] ...
10
+ // sprite sheet PNG + JSON metadata
11
+ // pixel export <spec.json> [--res 32] [--out dir] [--format aseprite]
12
+ // sheet PNG + Aseprite JSON (Phaser, PixiJS)
13
+ // pixel bundle <spec.json> [--res 16,32,64] [--views front,back|none] [--external] [--out file.bundle.json]
14
+ // self-contained web bundle for <pixel-sprite> (all skins);
15
+ // --external writes the sheets as PNG files beside it
16
+ // pixel resolve <variant.json> [--out full.json] print a variant ("extends") merged with its base
17
+ // pixel where <spec.json> [--anim a] [--frame f] [--part id --point x,y]
18
+ // world positions of part pivots (or of a point on a part)
19
+ // pixel figures list the figure library (skeletons + motions)
20
+ // pixel preview goose any command takes a bare figure name instead of a spec
21
+ //
22
+ // --skin <name> (preview, ascii, render, export, where): use one of the spec's skins
23
+ // style flags (preview, ascii, render, export, bundle): --lod 1|2|3 --tones n --texture 0..1 --dither true|false
24
+ // --outline dark|selective|none --light deg --flip
25
+ // pixel brief print the agent brief (spec format docs)
26
+ // pixel help this text
27
+ //
28
+ // --plugin ./a.mjs,./b.mjs (any command): register plug-in shapes, textures and motion models first
29
+ // errors print as one line and exit 1; PIXEL_DEBUG=1 adds the stack trace
30
+ import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
31
+ import { basename, dirname, join, resolve } from 'node:path';
32
+ import { fileURLToPath, pathToFileURL } from 'node:url';
33
+ import {
34
+ validate, compile, renderSheet, renderAnimation, renderFrame, resolveStyle,
35
+ contactSheet, frameToAscii, buildBundle, exportSheet, usePlugin, registeredPlugins, DETAIL_NAMES, resolveSpec, checkBounds, MAX_RES,
36
+ } from '../src/core/index.js';
37
+ import { samplePose, worldMatrices } from '../src/core/internal.js';
38
+ import { encodePNG } from '../src/node/png.js';
39
+
40
+ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
41
+
42
+ const BOOLEAN_FLAGS = new Set(['flip', 'external']); // never take the next argument as their value
43
+
44
+ function parseArgs(argv) {
45
+ const args = { _: [] };
46
+ for (let i = 0; i < argv.length; i++) {
47
+ const a = argv[i];
48
+ if (a.startsWith('--')) {
49
+ const eq = a.indexOf('='), k = eq < 0 ? a.slice(2) : a.slice(2, eq), v = eq < 0 ? undefined : a.slice(eq + 1);
50
+ args[k] = v ?? (!BOOLEAN_FLAGS.has(k) && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true);
51
+ } else args._.push(a);
52
+ }
53
+ return args;
54
+ }
55
+
56
+ function readJSON(path) {
57
+ let text;
58
+ try { text = readFileSync(path, 'utf8'); } catch (e) { fail(`cannot read ${path}: ${e.message}`); }
59
+ try { return JSON.parse(text); } catch (e) { fail(`${path} is not valid JSON: ${e.message}`); }
60
+ }
61
+
62
+ /** Load a spec, resolve its "extends" chain (paths relative to the file that names them) and its "figure". */
63
+ async function loadSpec(path) {
64
+ if (!path) fail('missing <spec.json>');
65
+ // A bare figure name ("goose") previews that figure's skeleton.
66
+ const spec = !path.endsWith('.json') && figureNames().includes(path) ? { figure: path } : readJSON(path);
67
+ const absOf = new Map();
68
+ try {
69
+ return await resolveSpec(spec, {
70
+ loadRef: (ref, from) => {
71
+ const abs = resolve(dirname(from ? absOf.get(from) : resolve(path)), ref);
72
+ absOf.set(ref, abs);
73
+ return JSON.parse(readFileSync(abs, 'utf8'));
74
+ },
75
+ loadFigure: (name) => JSON.parse(readFileSync(join(ROOT, 'figures', `${name}.json`), 'utf8')),
76
+ warn: (p, m) => console.error(`warning ${p}: ${m}`),
77
+ });
78
+ } catch (e) { fail(`${path}: ${e.message}`); }
79
+ }
80
+ const figureNames = () => readdirSync(join(ROOT, 'figures')).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5));
81
+
82
+ function printBounds(c, log = console.error) {
83
+ const w = checkBounds(c);
84
+ for (const x of w) log(`warning ${x.path}: ${x.message}`);
85
+ return w;
86
+ }
87
+
88
+ function fail(msg) { console.error(`error: ${msg}`); process.exit(1); }
89
+
90
+ function compileOrExit(spec) {
91
+ const { errors, warnings } = validate(spec);
92
+ for (const w of warnings) console.error(`warning ${w.path}: ${w.message}`);
93
+ if (errors.length) {
94
+ for (const e of errors) console.error(`error ${e.path}: ${e.message}`);
95
+ process.exit(1);
96
+ }
97
+ let c = compile(spec);
98
+ if (args.skin && cmd !== 'bundle') {
99
+ // Preview, render or inspect one skin (bundle always bakes all of them).
100
+ if (!c.skins?.[args.skin]) { console.error(`error unknown skin "${args.skin}" (skins: ${Object.keys(c.skins ?? {}).join(', ') || 'none'})`); process.exit(1); }
101
+ c = c.skins[args.skin];
102
+ }
103
+ printBounds(c);
104
+ return c;
105
+ }
106
+
107
+ /** A numeric flag, or a clear error naming what was typed. */
108
+ const numFlag = (a, k) => {
109
+ if (a[k] == null) return undefined;
110
+ const n = Number(a[k]);
111
+ if (a[k] === true || !Number.isFinite(n)) fail(`--${k} must be a number (got "${a[k] === true ? '' : a[k]}")`);
112
+ return n;
113
+ };
114
+ const overridesFrom = (a) => ({
115
+ lod: a.lod ? numFlag(a, 'lod') : undefined,
116
+ tones: numFlag(a, 'tones'),
117
+ texture: numFlag(a, 'texture'),
118
+ dither: a.dither != null ? a.dither !== 'false' : undefined,
119
+ outline: a.outline === true ? fail('--outline needs a value: dark, selective or none') : a.outline,
120
+ light: numFlag(a, 'light'),
121
+ flip: a.flip && a.flip !== 'false' ? true : undefined,
122
+ });
123
+
124
+ const resList = (v, d) => {
125
+ const list = String(v ?? d).split(',').map(Number);
126
+ if (!list.length || list.some((n) => !Number.isInteger(n) || n <= 0 || n > MAX_RES)) fail(`--res must be whole numbers 1..${MAX_RES}, e.g. 16,32,64 (got "${v}")`);
127
+ return list;
128
+ };
129
+ const oneRes = (v, d) => {
130
+ if (v != null && String(v).includes(',')) fail(`--res takes one resolution here (got "${v}"); use bundle or preview for several`);
131
+ return resList(v, d)[0];
132
+ };
133
+ /** --frame n, wrapped into 0..frames-1 (so -1 is the last frame). */
134
+ const frameIndex = (v, frames) => { const n = Math.trunc(Number(v) || 0); return ((n % frames) + frames) % frames; };
135
+ function animOrExit(c, name) {
136
+ const key = name ?? Object.keys(c.animations)[0];
137
+ if (!c.animations[key]) fail(`no animation "${name}" (have: ${Object.keys(c.animations).join(', ')})`);
138
+ return key;
139
+ }
140
+ const stem = (p) => basename(p).replace(/\.json$/, '');
141
+ const pngDataURL = (w, h, rgba) => 'data:image/png;base64,' + encodePNG(w, h, rgba).toString('base64');
142
+
143
+ // Anything that throws becomes one line on stderr and exit code 1 (PIXEL_DEBUG=1 shows the stack).
144
+ // A closed pipe (`pixel ascii … | head`) is not an error, and the handler must never run twice: writing the
145
+ // message to a closed stderr would throw again.
146
+ let crashing = false;
147
+ const crash = (e) => {
148
+ if (e?.code === 'EPIPE') process.exit(0);
149
+ if (crashing) process.exit(1);
150
+ crashing = true;
151
+ try { console.error(`error: ${e?.message ?? e}`); if (process.env.PIXEL_DEBUG) console.error(e?.stack); } finally { process.exit(1); }
152
+ };
153
+ process.on('uncaughtException', crash);
154
+ process.on('unhandledRejection', crash);
155
+
156
+ const [cmd, ...rest] = process.argv.slice(2);
157
+ const args = parseArgs(rest);
158
+ // Plug-ins (--plugin ./a.mjs,./b.mjs): register shapes, textures and motion models before anything runs.
159
+ if (args.plugin) {
160
+ for (const p of String(args.plugin).split(',')) {
161
+ try { await usePlugin(await import(pathToFileURL(resolve(p.trim())).href)); }
162
+ catch (e) { fail(`--plugin ${p}: ${e.message}`); }
163
+ }
164
+ }
165
+
166
+ switch (cmd) {
167
+ case 'figures': {
168
+ for (const n of figureNames()) {
169
+ const f = JSON.parse(readFileSync(join(ROOT, 'figures', `${n}.json`), 'utf8'));
170
+ console.log(`${n.padEnd(8)} ${f.bones.length} bones motions: ${Object.entries(f.motions ?? {}).map(([k, m]) => `${k}(${m.model ?? 'gait'})`).join(' ')}`);
171
+ if (f.description) console.log(` ${f.description}`);
172
+ console.log(` bones: ${f.bones.map((b) => b.id).join(' ')}`);
173
+ }
174
+ break;
175
+ }
176
+ case 'validate': {
177
+ const spec = await loadSpec(args._[0]);
178
+ const { errors, warnings } = validate(spec);
179
+ for (const w of warnings) console.log(`warning ${w.path}: ${w.message}`);
180
+ for (const e of errors) console.log(`error ${e.path}: ${e.message}`);
181
+ if (errors.length) process.exit(1);
182
+ const c = compile(spec);
183
+ printBounds(c, console.log);
184
+ const anims = Object.values(c.animations).map((a) => `${a.name}(${a.frames}f@${a.fps}fps)`).join(' ');
185
+ console.log(`ok: "${c.name}" ${c.parts.length} parts, ${Object.keys(c.materials).length} materials, animations: ${anims}`);
186
+ break;
187
+ }
188
+ case 'preview': {
189
+ const c = compileOrExit(await loadSpec(args._[0]));
190
+ const ov = overridesFrom(args);
191
+ const previewAnims = args.anim ? String(args.anim).split(',').map((n) => animOrExit(c, n.trim())) : Object.keys(c.animations);
192
+ const blocks = resList(args.res, '16,32,64').map((res) => ({
193
+ res,
194
+ rows: previewAnims.map((n) => ({ name: n, frames: renderAnimation(c, n, res, ov).frames })),
195
+ }));
196
+ const img = contactSheet(blocks, { cellH: Number(args.cell) || 128 });
197
+ const out = args.out || `${stem(args._[0])}.preview.png`;
198
+ mkdirSync(dirname(resolve(out)), { recursive: true });
199
+ writeFileSync(out, encodePNG(img.w, img.h, img.rgba));
200
+ console.log(`wrote ${out} (${img.w}x${img.h})`);
201
+ console.log(`blocks top→bottom: ${blocks.map((b) => `${b.res}px [${DETAIL_NAMES[resolveStyle(c, b.res, ov).lod]}]`).join(', ')}`);
202
+ console.log(`rows per block: ${previewAnims.join(', ')}`);
203
+ break;
204
+ }
205
+ case 'ascii': {
206
+ const c = compileOrExit(await loadSpec(args._[0]));
207
+ const res = oneRes(args.res, 24);
208
+ const anim = animOrExit(c, args.anim);
209
+ const frames = args.frame === 'all'
210
+ ? [...Array(c.animations[anim].frames).keys()]
211
+ : [frameIndex(args.frame, c.animations[anim].frames)];
212
+ const style = resolveStyle(c, res, overridesFrom(args));
213
+ for (const f of frames) {
214
+ const fr = renderFrame(c, { res, anim, frame: f, style });
215
+ const { text, legend } = frameToAscii(fr);
216
+ console.log(`${anim} frame ${f} @${res}px legend: ${Object.entries(legend).map(([k, v]) => `${v}=${k}`).join(' ')} #=outline .=empty`);
217
+ console.log(text + '\n');
218
+ }
219
+ break;
220
+ }
221
+ case 'render': {
222
+ const c = compileOrExit(await loadSpec(args._[0]));
223
+ const res = oneRes(args.res, 32);
224
+ const sheet = renderSheet(c, res, overridesFrom(args));
225
+ const dir = args.out || '.';
226
+ mkdirSync(dir, { recursive: true });
227
+ const base = `${stem(args._[0])}.${res}`;
228
+ writeFileSync(join(dir, `${base}.png`), encodePNG(sheet.width, sheet.height, sheet.rgba));
229
+ writeFileSync(join(dir, `${base}.json`), JSON.stringify({ name: c.name, image: `${base}.png`, ...sheet.meta }, null, 2));
230
+ console.log(`wrote ${join(dir, base)}.png (${sheet.width}x${sheet.height}) + .json`);
231
+ break;
232
+ }
233
+ case 'export': {
234
+ // Aseprite-format JSON (Phaser) with a PixiJS animations map, plus the PNG sheet.
235
+ const c = compileOrExit(await loadSpec(args._[0]));
236
+ const res = oneRes(args.res, 32);
237
+ if ((args.format ?? 'aseprite') !== 'aseprite') { console.error('error --format: only "aseprite" (also read by Phaser and PixiJS)'); process.exit(1); }
238
+ const dir = args.out || '.';
239
+ mkdirSync(dir, { recursive: true });
240
+ const base = `${stem(args._[0])}${args.skin ? `.${args.skin}` : ''}.${res}`;
241
+ const ex = exportSheet(c, res, { image: `${base}.png`, overrides: overridesFrom(args) });
242
+ writeFileSync(join(dir, `${base}.png`), encodePNG(ex.width, ex.height, ex.rgba));
243
+ writeFileSync(join(dir, `${base}.json`), JSON.stringify(ex.json, null, 2));
244
+ console.log(`wrote ${join(dir, base)}.png (${ex.width}x${ex.height}) + .json (${Object.keys(ex.json.frames).length} frames, ${ex.json.meta.frameTags.length} tags, ${ex.json.meta.slices.length} slices)`);
245
+ break;
246
+ }
247
+ case 'bundle': {
248
+ const c = compileOrExit(await loadSpec(args._[0]));
249
+ // --views front | front,back | none: which extra views (front, back, …) to ship; default all.
250
+ const views = args.views == null ? undefined : String(args.views) === 'none' ? [] : String(args.views).split(',').map((s) => s.trim()).filter(Boolean);
251
+ const bundle = await buildBundle(c, { resolutions: resList(args.res, '16,32,64'), overrides: overridesFrom(args), encode: pngDataURL, views });
252
+ const out = args.out || `${stem(args._[0])}.bundle.json`;
253
+ mkdirSync(dirname(resolve(out)), { recursive: true });
254
+ // --external: sheets as PNG files next to the bundle, so a page downloads only the one it shows.
255
+ if (args.external) {
256
+ const name = basename(out).replace(/\.bundle\.json$|\.json$/, '');
257
+ for (const v of bundle.variants) for (const key of ['image', 'overlay']) {
258
+ if (typeof v[key] !== 'string' || !v[key].startsWith('data:image/png;base64,')) continue;
259
+ // Skin names come from the spec: keep them to a safe slug so the file stays beside the bundle.
260
+ const slug = (x) => String(x).replace(/[^A-Za-z0-9_-]+/g, '_');
261
+ const file = `${slug(name)}.${Number(v.res)}${v.skin ? `.${slug(v.skin)}` : ''}${key === 'overlay' ? '.overlay' : ''}.png`;
262
+ const dir = dirname(resolve(out)), target = resolve(dir, file);
263
+ if (basename(file) !== file || dirname(target) !== dir) fail(`--external: refusing to write ${file} outside ${dir}`);
264
+ writeFileSync(target, Buffer.from(v[key].slice(22), 'base64'));
265
+ v[key] = file;
266
+ }
267
+ }
268
+ const json = JSON.stringify(bundle);
269
+ writeFileSync(out, json);
270
+ console.log(`wrote ${out} (${(json.length / 1024).toFixed(1)} KB, variants: ${bundle.variants.map((v) => v.skin ? `${v.res} (${v.skin})` : v.res).join(', ')})`);
271
+ break;
272
+ }
273
+ case 'resolve': {
274
+ const json = JSON.stringify(await loadSpec(args._[0]), null, 2);
275
+ if (args.out) { writeFileSync(args.out, json + '\n'); console.log(`wrote ${args.out}`); } else console.log(json);
276
+ break;
277
+ }
278
+ case 'where': {
279
+ const c = compileOrExit(await loadSpec(args._[0]));
280
+ const anim = c.animations[animOrExit(c, args.anim)];
281
+ const frame = frameIndex(args.frame, anim.frames);
282
+ const pose = samplePose(c, anim, frame);
283
+ const { world, visible } = worldMatrices(c.parts, pose);
284
+ const at = (m, [x, y]) => [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]].map((v) => +v.toFixed(1));
285
+ console.log(`${anim.name} frame ${frame} (canvas ${c.size.join('x')} units)`);
286
+ if (args.part) {
287
+ const p = c.parts.find((q) => q.id === args.part);
288
+ if (!p) fail(`no part "${args.part}"`);
289
+ const pt = args.point ? String(args.point).split(',').map(Number) : p.pivot;
290
+ console.log(`${p.id} [${pt}] (rest) → [${at(world.get(p.id), pt)}] rot ${pose.get(p.id).rot.toFixed(1)}°`);
291
+ } else {
292
+ for (const p of c.parts) {
293
+ const t = pose.get(p.id);
294
+ console.log(`${p.id.padEnd(12)} pivot [${p.pivot}] → [${at(world.get(p.id), p.pivot)}] rot ${t.rot.toFixed(1)}°${visible.get(p.id) ? '' : ' (hidden)'}`);
295
+ }
296
+ }
297
+ break;
298
+ }
299
+ case 'brief': {
300
+ process.stdout.write(readFileSync(join(ROOT, 'docs/SPEC.md'), 'utf8'));
301
+ const extra = registeredPlugins();
302
+ if (extra.length) process.stdout.write(`\n## Plug-ins loaded for this project\n\n${extra.map((p) => `- ${p.kind} \`${p.name}\`${p.describe ? `: ${p.describe}` : ''}`).join('\n')}\n`);
303
+ break;
304
+ }
305
+ case 'help': case '--help': case '-h': case undefined:
306
+ default:
307
+ {
308
+ const lines = readFileSync(fileURLToPath(import.meta.url), 'utf8').split('\n').slice(1); // skip the #! line
309
+ const header = lines.slice(0, lines.findIndex((l) => !l.startsWith('//')));
310
+ console.log(header.map((l) => l.slice(3)).join('\n'));
311
+ }
312
+ process.exit(!cmd || ['help', '--help', '-h'].includes(cmd) ? 0 : 1);
313
+ }
package/docs/DESIGN.md ADDED
@@ -0,0 +1,118 @@
1
+ # Pixel Studio — PoC design (working backwards)
2
+
3
+ ## 1. Start from the end: what does a website need?
4
+
5
+ A character animation that lives on a web page has to be:
6
+
7
+ | Need on the page | Consequence for the system |
8
+ |---|---|
9
+ | Crisp at any CSS size, no blur | Integer-scaled pixels, `image-rendering: pixelated`, canvas sized to the sprite's native resolution |
10
+ | Tiny and fast (hero, buttons, 404 pages, docs) | Bake to a sprite sheet (PNG) + a few hundred bytes of metadata; one small runtime file (`pixel-sprite.js`, about 15 KB gzipped); no framework |
11
+ | Drop-in embed | One custom element: `<pixel-sprite src="fox.bundle.json" anim="idle">` |
12
+ | Interactive | Named animations + `hover-anim` / `click-anim`, a `play()` API, `pixel-end` events |
13
+ | Responsive | Several resolutions per character (like `srcset`): the runtime picks the one that fits the rendered size |
14
+ | Polite | Honours `prefers-reduced-motion`, pauses off-screen |
15
+
16
+ So the **output artifact** is a *bundle*: `{ animations, variants: [{res, image(PNG)}, ...] }`.
17
+
18
+ ## 2. One step back: what produces a bundle?
19
+
20
+ A renderer that takes a **character description** and a **render setting** (resolution, detail level,
21
+ texture, outline, light) and emits frames. The key question is: *what is the character description?*
22
+
23
+ ### Why not "agents paint pixels"?
24
+
25
+ LLM agents are bad at long 2D pixel grids: coordinates drift, symmetry breaks, a 64×64 frame is 4096
26
+ cells, and every animation frame has to be repainted consistently. Hand-painted grids also don't give
27
+ you levels of detail for free: a 16px and a 64px version are two separate drawings.
28
+
29
+ ### What agents *are* good at
30
+
31
+ Structured, semantic, compositional descriptions: "a head is an ellipse here, the arm is a capsule from
32
+ the shoulder to the hand, it swings ±25° over the walk cycle". That is a scene graph, and it is
33
+ resolution-independent.
34
+
35
+ ### Decision: agents author a semantic rig, the engine rasterizes it into pixel art
36
+
37
+ ```
38
+ Agent ──writes──▶ Character spec (JSON)
39
+ materials · parts (shapes, pivots, z, parent) · animations (tracks per part)
40
+ │
41
+ ▼
42
+ Rasterizer (per frame, per resolution)
43
+ SDF shapes → coverage at pixel centres → material/part/normal per pixel
44
+ │
45
+ ▼
46
+ Pixel-art shader (the "detail & texture" knobs)
47
+ tone ramps with hue shifting · lighting quantized to ramp ·
48
+ procedural textures in part space · ordered dither · outlines/selout ·
49
+ inner lines
50
+ │
51
+ ▼
52
+ Frames → sprite sheet → bundle ──▶ <pixel-sprite> on a website
53
+ ```
54
+
55
+ Because geometry is rasterized fresh for every frame and every resolution:
56
+
57
+ - **LOD is free**: the same spec renders at 16, 32, 64 px. Shapes can opt in/out per detail tier
58
+ (`minDetail`) so a 16px icon drops eyebrows and buttons instead of turning them into noise.
59
+ - **Animation is cheap to author**: tracks move/rotate/scale parts; rotation doesn't smear pixels
60
+ (we never rotate a bitmap).
61
+ - **Texture moves with the body**: procedural textures are evaluated in each part's local space, so
62
+ fur/scales/cloth stick to the limb instead of swimming.
63
+
64
+ ## 3. What "levels of detail and texture" means concretely
65
+
66
+ Three detail tiers, each a preset of shader knobs (all overridable):
67
+
68
+ | Tier | Typical res | Tones per material | Texture | Dither | Outline | Inner lines | Shapes |
69
+ |---|---|---|---|---|---|---|---|
70
+ | 1 · icon | ≤ 20 px | 2 | off | off | dark | off | `minDetail ≤ 1 ≤ maxDetail` |
71
+ | 2 · sprite | 21–40 px | 3 | 60% | off | selective | off | `minDetail ≤ 2 ≤ maxDetail` |
72
+ | 3 · portrait | > 40 px | 5 | 100% | on | selective | on | `minDetail ≤ 3 ≤ maxDetail` |
73
+
74
+ Texture vocabulary (per material): `noise, fur, scales, stripes, checker, cloth, bricks, spots, metal`.
75
+ Materials also carry `shine` (specular), `flat` (no shading — eyes, emissive bits) and `outline: false`.
76
+
77
+ Pixel-art craft baked in, so agents don't need to know it:
78
+ - **hue-shifted ramps** (shadows drift cool, highlights drift warm) instead of plain darken/lighten
79
+ - **selective outline** (outline tinted by the neighbouring material) instead of pure black
80
+ - **thin-feature preservation**: a shape thinner than a pixel still gets 1 px instead of vanishing
81
+ - **pixel-snapped motion**: part offsets snap to whole pixels at each resolution
82
+ - **far-side shading**: `part.shade: -0.3` for the far arm/leg (figures set it automatically) (classic depth cue)
83
+
84
+ ## 4. The agent loop (the "studio for agents" part)
85
+
86
+ An agent needs to *see* what it drew. The PoC gives three loops:
87
+
88
+ 1. **CLI (any coding agent, e.g. Claude Code)** — `node bin/pixel.mjs validate|preview|ascii|render|export|bundle|resolve|where|figures|brief`
89
+ (see [cli.md](cli.md)).
90
+ `preview` writes a contact sheet PNG (all animations × LOD tiers) the agent can look at;
91
+ `ascii` prints a frame as text for agents without vision. Validation errors carry JSON paths.
92
+ 2. **Studio UI (human + agent)** — live JSON editor, animated preview, LOD strip, sprite sheet,
93
+ shader knobs, export.
94
+ 3. **In-studio Claude loop** — describe a character → Claude writes the spec → the studio renders a
95
+ contact sheet → sends the image back to Claude to critique and revise. (Needs your API key.)
96
+
97
+ `docs/SPEC.md` is the single source of truth for the format and doubles as the agent system prompt.
98
+
99
+ ## 5. Non-goals for the PoC
100
+
101
+ - Frame-by-frame hand editing / pixel painting tools (a later "touch-up layer" could store per-frame
102
+ pixel overrides on top of the rig).
103
+ - Mesh deformation, tweened easing curves editor. (Skeletal IK and palette-swap skins were on this list; IK now exists
104
+ as `reach` constraints and the figure motion models, see [figures.md](figures.md), and skins as patches of
105
+ materials and parts stored as recolours in the bundle, see [SPEC.md](SPEC.md#skins).)
106
+ - Server, accounts, storage. Everything is static files + Node with zero dependencies.
107
+
108
+ ## 6. Open questions for after the PoC
109
+
110
+ - ~~Is the rig expressive enough for non-humanoids (wings, tails, tentacles) — add chains/bones?~~ Resolved: figures
111
+ are bone chains with `wings`, `tail` and four-legged roles, `follow` springs for trailing parts, and plug-in motion
112
+ models ([figures.md](figures.md)).
113
+ - Should agents get a **touch-up pass** (pixel overrides per LOD tier) for faces, where geometry
114
+ rasterization is weakest at 16px?
115
+ - Palette constraints per site (brand palettes, limited global palette across characters)?
116
+ - ~~Export targets beyond the web component~~ Partly resolved: `pixel export` writes a sheet PNG with Aseprite JSON
117
+ (Phaser, PixiJS) and `pixel render` a plain sheet with metadata. GIF/APNG, a CSS `steps()` sprite and Lottie-like JSON
118
+ remain open.