All notable changes to this project are documented here. The format follows Keep a Changelog, and versions follow Semantic Versioning. Until 1.0, minor versions may change the spec format.
[Unreleased]
Section titled “[Unreleased]”[0.2.0-alpha.2] - 2026-11-21
Section titled “[0.2.0-alpha.2] - 2026-11-21”Renamed: pixel-studio is now @pixel-studio/core
Section titled “Renamed: pixel-studio is now @pixel-studio/core”- The engine package moves into the
@pixel-studioorganisation, next to@pixel-studio/runtime:npm i @pixel-studio/core. Imports change with it:@pixel-studio/core,@pixel-studio/core/internal,@pixel-studio/core/runtime,@pixel-studio/core/stage,@pixel-studio/core/node/png; the example paths becomenode_modules/@pixel-studio/core/examples/. Thepixelcommand is unchanged. pixel-studioon npm stays at 0.2.0-alpha.1 and is deprecated, pointing here.
[0.2.0-alpha.1] - 2026-11-21
Section titled “[0.2.0-alpha.1] - 2026-11-21”On npm, as two packages
Section titled “On npm, as two packages”pixel-studio(the engine, thepixelCLI, figures, examples, motion references and the reference docs) and@pixel-studio/runtime(<pixel-sprite>,<pixel-stage>and<pixel-actor>) are published on npm, always with the same version:npm i pixel-studio, ornpm i @pixel-studio/runtimefor a site that only plays sprites. The runtime has no dependencies and never imports the engine;pixel-studiodepends on exactly its version.pixel-studio/runtimeandpixel-studio/stagekeep working: they re-export the runtime package. In the runtime package the files aresrc/pixel-sprite.jsandsrc/pixel-stage.js(weresrc/runtime/inpixel-studio), and the imports are@pixel-studio/runtimeand@pixel-studio/runtime/stage.- The
pixel-studiopackage no longer ships the research notes (docs/research/); they stay in the repository.
- The hand-written guide pages (
site/) move into pixel-studio.sh as the Guide (/docs/guide/): the same nine topics, every live example running next to its code (now with the site’s highlighting, copy button and themes) and every editable character redrawn by the engine as you type.site/is gone;scripts/browser-check.mjschecks the guide’s pages instead.
Repository
Section titled “Repository”- Laid out as npm workspaces:
packages/pixel-studio/,packages/runtime/, with the studio, demos, guide pages and website around them.npm installlinks the two packages; there are still no third-party dependencies. - Generated files are no longer committed:
demo/assets/(built bynpm run build:demo, and by the website’s build) andpreviews/(which still held a contact sheet of a character that no longer exists). - CI on every push and pull request: both packages’ tests on Node 20 and 24, Markdown links, the packed packages installed and used from a fresh folder, and the website build. Releases are staged on npm from a signed tag and approved by a maintainer with 2FA (see CONTRIBUTING.md).
Removed
Section titled “Removed”demo/pp.html, the P/P studio site sketch: it is a personal site, not an engine demo, so it no longer ships here.
[0.2.0-alpha.0] - 2026-11-15
Section titled “[0.2.0-alpha.0] - 2026-11-15”The first alpha. Install from GitHub: npm i github:pavelpascari/pixel-studio#v0.2.0-alpha.0.
Old event names, the state attribute and actor.state still work in this alpha and go away after it.
Breaking: event names, load status, exports
Section titled “Breaking: event names, load status, exports”- One event naming scheme. Every event the runtime fires is now
pixel-<name>, and every one bubbles and is composed (it crosses shadow roots). The details are unchanged. The old names still fire, with their old options, for one alpha release and will be removed after 0.2.0-alpha.<pixel-sprite>:ready→pixel-ready,error→pixel-error,statechange→pixel-statechange,spriteend→pixel-end,spriteevent→pixel-event,spriteburst→pixel-burst,spritecalm→pixel-calm.<pixel-actor>:tap,burst,calm,enter,exit,land,arrive,drop,pickup,deliver,catchup→pixel-tap,pixel-burst, …;actorstate→pixel-activity.<pixel-stage>:sceneevent,scenestep,sceneend,scrollsettle,fastscroll→pixel-sceneevent, ….- An actor’s inner
<pixel-sprite>keeps its events inside the actor (and no longer counts clicks itself), so a listener on an actor hears each burst once, from the actor. - Scenes keep their short names (
"waitFor": "tap","trigger": {"event": "arrive"}); on actors and the stage they listen for thepixel-events. Because those bubble,"on": "stage"now hears every character’s events.
- “State” means the state machine.
<pixel-sprite>’s load status is thestatusattribute andel.status(loading,ready,error);statestays as an alias (both attributes are set) for one alpha.<pixel-actor>’s behaviour isactor.activity(eventpixel-activity);actor.statestays as an alias for one alpha. - A smaller, safer engine API.
pixel-studiono longer exports internal building blocks or live registries:createImage,blit,bakePoints,samplePose,samplePoseAt,sampleValue,frameTime,followOffsets,worldMatrices,solveReach,overflowForPose,resolveExtends,mergeVariant,expandFigure,paletteOfandbuildMixesmoved topixel-studio/internal(src/core/internal.js), which carries no compatibility promise.pngBytesstays public: it is how a browser makes theencodethatbuildBundleneeds.SHAPE_TYPES,TEXTURES,MOTION_MODELSandLEGGED_MODELSare replaced byshapeTypes(),textures(),motionModels()andleggedModels(), which return fresh frozen arrays (SHAPE_TYPES.push('blob')used to makevalidatecrash).TRACK_PROPS,DETAIL_PRESETSandDETAIL_NAMESare frozen.- Registering the same plug-in definition again under its name is a no-op (a dev server re-running a plug-in’s setup); a different definition under a taken name still throws.
Getting ready for the alpha
Section titled “Getting ready for the alpha”- Moss replaces Clawd. Clawd was drawn after another company’s mascot, which this project does not do. Moss is an
original character on the same 16-cell rig and with the same twelve animations: a moss-green shield beetle with a
domed, banded shell, a sand belly, amber-tipped antennae and round eyes (
examples/moss.json, generated byscripts/gen-moss.mjs). It takes Clawd’s place in the stage demo, the docs site, the playground and the docs. - Fixed: a
<pixel-stage>scene with"loop": truewhose steps all finished at once (every actor missing, or onlyemitsteps) froze the tab. Each pass of a loop now takes at least 100 ms,checkScenerejects a forever-loop with no step that takes time, and a long-running scene no longer piles up stop listeners. - Validation is stricter, so typos fail with a JSON path instead of rendering a blank or hanging:
- part
x,y,rot,shadeare numbers;sx/syare within ±16;showis a boolean or a number; - shape sizes are ≥ 0,
minDetail/maxDetailare 1, 2 or 3, and coordinates stay within 4 canvas sizes; sizeis at most 1000 units a side, and renders are at most 512 px (MAX_RES);- names that are built-in object keys (
toString,constructor, …) are rejected for materials, points, skins, state nodes and inputs, as they already were for parts and animations.
- part
- Style overrides (
resolveStyle, and the CLI’s--tones,--light,--outline, …) follow the same rules as a spec’sstyle, with a readable error. - CLI: errors print as one
error:line with exit code 1 (PIXEL_DEBUG=1adds the stack);pixel help,--helpand-hprint the usage and exit 0;--frame -1is the last frame;--out=a=b.pngkeeps its=; closing the pipe early (| head) is not an error. - Runtime:
checkBundletype-checks animations, loops, points, size, ground, states and frame sizes; it accepts later minor versions of the format (pixel-sprite/1.x); name lookups cannot hit built-in keys; a bundle URL that serves an HTML page gets an error that says so; sheets on another origin load withcrossOrigin="anonymous". - Docs: a new getting-started guide; the README leads with install and a five-minute path; every reference doc re-checked against the code (stale outputs re-run, fixed “known issues” removed, views documented in the agent brief, skins described as the deltas they are).
P/P site sketch: a goose that follows the scroll
Section titled “P/P site sketch: a goose that follows the scroll”demo/pp.html: a one-page studio site (field-guide direction: paper, ink, stamp red) where the greylag goose starts on the logo’s baseline, takes off on the first scroll and flies between “perches” (any element withdata-perch, standing on its top edge atdata-at, indata-pose) as you read down. Pointing at a product card sends it over; pressing the footer stamp makes it come and honk. Landings stamp footprints; only the last 7 stay. Decorative only: under reduced motion it stays home in a still pose, and the page reads the same with it hidden.- A sketch panel picks the goose (greylag, plain, sudo, kiddie, root, phreak) and its size (40–128 px; phones get 3/4),
kept in the URL (
?goose=sudo&size=96) so a setup can be shared;?ui=0hides the panel. Spacing around the logo and the product row grows with the goose. - Scenes (short scripts that take the goose over, then hand it back): it flies in from off-screen on arrival; in-page links scroll a little slower and the goose lags ~0.6 s behind, so it flies into the frame and lands (on the logo when going to the top); subscribing (sketch form) makes it honk, carry the letter off one edge and return from the other.
- Portals: a hole opens under the goose, it sinks in and rises out of another hole elsewhere, flaps, then does one thing (peck, sit, honk). After a quiet spell it portals to an annotation in view (at most every 45 s). Click it and it honks; four clicks in 3 s and it puffs up, rushes at the cursor, honks, dives, and comes out on the far side from the cursor.
- Ambient life: when scrolling stops, the goose paces a few steps (leaving prints), turns, pecks, or sits where it is.
- Talking: a field-note tag over the goose’s head (beside it where there is no room) says a line as things happen: a greeting by time of day on arrival, “Ooh, a letter.” when taking a subscription and “Signed for.” back at the form after delivering it, a word per poke (“Honk?”, “Honk.”, “Oi.”, then “RIGHT.”), “Watch it! Honk!” out of the angry portal, a remark when it pops up at an annotation. Left alone on the logo for 7 s it sits down and snores (“z… zzz”, dashed tag) until anything moves. Decorative and aria-hidden, like the goose; off under reduced motion.
Views: front, back and a three-quarter look
Section titled “Views: front, back and a three-quarter look”- Specs can have
views: the same character dressed on other figures ("front": {"figure": "goose-front", "parts": [...]}). View parts join asfront.*, shown only in that view’s animations (idle@front,waddle@back); turns are generated (turn@front,unturn@front), andlookputs the view’s head on the side body for a three-quarterlook@frontthat the turn passes through. Attachment points follow the view. Variants patch views like the main spec, and theirmaterialMapreaches every view. - New figure
goose-front(head-on, or from behind); front-view wings flap outward on both sides. examples/goose-base.json(and so the whole flock) has front and back views.- Stage:
actor.face('viewer' | 'away' | 'side')turns the character (a promise; scenes wait for it). It idles, talks and performs in that view and turns back to the side by itself before walking. Newgazebehaviour (on by default): now and then it looks at the reader. The demo’s goose turns to you when it has delivered the mail. - Workbench: side / ¾ look / front / back, with each view’s parts switchable and exported as
viewspatches. Hiding a part that is not a bone exports asremove. - The flock is dressed in every view: root’s shades, hood and drawstrings; sudo’s headphones, bandana and cheek strap; phreak’s ski mask, eye slit and pompom; kiddie’s proportions and cap. The workbench’s 17 features have front and back versions where they show.
- Fixed: a prop hidden by default (root’s server rack) appeared during turns.
A game: Fox Trail
Section titled “A game: Fox Trail”- New
demo/runner.html: an endless runner played by the fox (gallop measured from Muybridge’s hounds, a new in-placeleap, pixel-accurate collisions withhitTest, speed ramp throughrate, best distance kept locally). Linked from the demo site. docs/runtime.mdhas a “Games” section: what<pixel-sprite>offers a game loop, why<pixel-stage>scenes are for choreography rather than play, and three gaps worth closing (rectangle overlap, frame seek, reduced-motion opt-in).
New motions measured from photographs
Section titled “New motions measured from photographs”- All 26 relevant Muybridge plates (1887, public domain, full-resolution BPL scans) measured into
references/measurements/— dogs 706–710, human walks, runs, stairs, ladders, jumps, sitting and rising, and pigeon, cockatoo, vulture, ostrich and adjutant — with per-frame contacts, verified joint points, timing, and what could not be measured and why. All 28 plates are in the registry (ids zero-padded:muybridge-1887-pl001); the references check now also validates measurement files. - New figure motions:
dog.gallop(hound plates: 0.25 s, duty 0.22, hind–hind–fore–fore),human.sprint(full-speed runs: 0.5 s, duty 0.29),human.sitDownandhuman.standUp(one frame per plate frame of plates 236 and 249, hip height and trunk lean as measured),goose.fly(level flight at 5 Hz, Meir et al. 2019, with the full wingstroke the bird plates show). Each value — and each frame of the sit-down and stand-up — is logged inreferences/. - The fox gallops and every goose flies (
flyin goose-base and the greylag). The figure library and the motions page show them; the motions page has a “Measured from photographs” section with playgrounds.
Motion re-timed from real animals (every change cited in references/)
Section titled “Motion re-timed from real animals (every change cited in references/)”- Dog (fox and anything on
figures/dog.json), from Maes et al. 2008:walktakes real dog-sized steps (stride15 → 27, 0.8 s cycle) with each forefoot landing 16% of a cycle after its hindfoot (Table 2, was 25%);trotis a real trot instead of a walking-speed jog (0.5 s cycle,duty0.46,stride17 → 30; 8 frames at 16 fps). Speeds: walk 23 → 52, trot 57 → 130 units/s. - Goose (every goose), from Wang et al. 2025 and Han et al. 2023: the walk and sneak head-bob, holding the head
still for 38% of each step (
head.hold); walkingduty0.62 → 0.7;runandrushare grounded runs (duty0.42 → 0.58: waterfowl keep a foot down when they run), so they are slower (run 76 → 55, rush 100 → 72 units/s). The greylag’s own waddle gets the same duty and head-bob. - Human, from Fukuchi et al. 2018/2017: walk
stride26 → 36 (real step length), runduty0.38 → 0.35,stride26 → 30, 11 fps (0.73 s cycle). - Muybridge plate 706 measured (
references/measurements/dog-pl706.json): the mastiff is walking, not trotting (support switches between a same-side and a diagonal pair; 0.88 s cycle), which agrees with the newdog.walk; it is not used for the trot. - Wings are unchanged: 6–7 Hz matches a goose taking off (Meir et al. 2019, Marey 1890).
- Each value is logged with its source and exact location (table, equation, plate) in
references/dog.json,goose.json,human.jsonandgoose-greylag.json, andnpm testfails if a value drifts from its log.
Where our motion comes from
Section titled “Where our motion comes from”- New
references/: a registry of motion sources (sources.json: Muybridge plates with record IDs, frame layout and exposure intervals, papers with DOIs, videos), each cited in full with its rights statement word for word, and one log per figure saying which source each tuned parameter and each derived frame comes from. The format is inreferences/README.md. scripts/references.mjschecks the logs (part ofnpm test): unknown sources, licences outside the rule (public domain, CC0, CC BY with credit, or numbers only from copyrighted papers), values that drifted from the figure, and frames measured from a source whose images we may not use.node scripts/references.mjs creditswritesreferences/CREDITS.md, which ships with the package.- Research notes behind it:
docs/research/motion-references.md(public-domain photo plates, published gait and flight numbers, our presets against them),mit-libraries.md,motion-data-sources.md,mesh2motion.md.
Every page on a phone
Section titled “Every page on a phone”- The studio works on phones and tablets: one column with the character first, a wrapping toolbar, the spec editor in its own scroll area, and the animation chips in one row you swipe (goose-base has 40).
- Trailmark’s nav links drop to a swipeable row of pills instead of squeezing into one-word columns (the page was 12 px too wide on a phone).
- On touch screens every page (studio, workbench, figures, playground, docs, demos) makes buttons, selects, sliders, checkboxes and the parts list’s toggles big enough to tap, and fields use 16 px text so iOS doesn’t zoom in on focus. Desktop is unchanged.
A wild one joins the flock: greylag
Section titled “A wild one joins the flock: greylag”- New
examples/goose-greylag.json: a natural greylag goose (heavy grey-brown body, slim neck, buff-edged coverts, pink legs, orange-pink bill) on the goose figure with its own proportions. Contributed through the playground, then tuned to read at sprite sizes: a selective outline and rounder shading, the flank streaks and covert edge strokes dropped (a comb below ~100 px), a paler belly only underneath (it showed as a white goose when the wing lifted), a bigger honk, every flock move (run, rush, jump, fall, sit, duck, peek, climb, flap) and goose-base’s front and back views in greylag colours.rushleans less so the longer bill stays in the frame. - It walks the flock lawn and has a roster card (hover: peek); the playground, the studio and the goose workbench list it. The workbench’s features are drawn on goose-base’s body, so for a goose with its own proportions they are off (with a note saying why); picks come back on switching to a flock goose.
- The workbench’s skeleton overlay draws only the bones shown in the frame. It used to draw every view’s skeleton at once, so the side view had the front view’s spine and wings standing through the body.
Playground
Section titled “Playground”- New
studio/play.html: one character, animated, set up entirely by its URL:?c=goose-root&view=front&anim=waddle&skin=party&res=64plus#spec=with changes to materials, style and parts (URL-encoded JSON, or deflate-raw + base64url; a whole goose is about 2 KB). Panels for colours, textures and style write into the link; Copy link shares it. - For agents: docs/playground.md (URL options, payload rules, examples),
studio/play.schema.json(JSON Schema of the payload), andwindow.playground(ready,options(),set(),link(),frame()) in the page. llms.txtat the site root points agents to the playground, its guide and the spec.scripts/serve.mjsno longer serves dotfiles or dot-folders (.gitwas reachable through a tunnel) and answers/robots.txtwith “allow everything”.
Speech bubbles above the head
Section titled “Speech bubbles above the head”actor.say()puts its bubble just above the highest pixel over the head and beak (a hat or hood included), not at the beak, where it covered the head. The flock demo’s HONK! does the same.- New
el.topAt(x0, x1)on<pixel-sprite>: the highest opaque pixel in a strip of the frame showing now.
Smaller bundles
Section titled “Smaller bundles”- Sheets are written as indexed PNGs (palette, 1–8 bits per pixel) when they have at most 256 colours, which pixel
art nearly always does: 35–45% smaller. New
pngBytes(w, h, rgba, deflate)in the core works in any host; the studio uses it withCompressionStream, Node’sencodePNGwith zlib. - Skins are stored as a change to the default sheet (
recolor: colours swapped;overlay: the pixels still different) when that is smaller: root’s two skins went from 290 KB to 10 KB.<pixel-sprite>rebuilds the sheet on load (checked pixel-exact in Chromium, Firefox and WebKit).buildBundle(..., {deltas: false})turns it off. buildBundle(..., {views})/pixel bundle --views front|noneship only some views.pixel bundle --externalwrites the sheets as PNG files next to the bundle, so a page downloads only the size it shows.- Root’s bundle: 609 KB → 156 KB with every view, 80 KB side-only; 22 KB of JSON + one 18–71 KB sheet with
--external. All demo bundles together: 1.6 MB → 0.85 MB.
Goose workbench
Section titled “Goose workbench”studio/goose.html: the goose large (32–192 px, whole-pixel zoom, skeleton and pixel-grid overlays, actual-size previews at 16/32/64), any of the flock, every animation, frame stepping. Every part and every shape can be switched off; 17 realistic features (studio/goose-features.json: beak nail, nostril, bill line, eye ring and glint, Chinese knob, neck furrows, pale throat and belly, white stern, flank barring, far wing, wing coverts, dark flight feathers, layered tail, webbed toes, scaly shins) can be tried on. The look is kept in the URL and exported as a variant spec (checked to build). Works on phones.- Workbench “Rendering” panel: tones, outline, texture, roundness, fill light, dithering and inner lines over the
goose’s own style; a “clean” preset (no texture or dithering, 3 tones, no inner lines, softer light) for a calmer,
more natural look at large sizes. Exported as the spec’s
style.
Figure library page on phones; more goose moves in the library
Section titled “Figure library page on phones; more goose moves in the library”studio/figures.htmlworks on phones: the animation first (square, sharp at any pixel density), figures and motions as rows of chips to swipe, view options in a grid. Desktop layout unchanged.- Figure library motions can carry their own
tracks,eventsandholds(a spec’s tracks override them). The goose figure’s library gainsrush,flapandhonk, so every goose spec can use them; the flock’s bundles are unchanged.
Triggers, carrying, leaving the screen
Section titled “Triggers, carrying, leaving the screen”- Scenes can have a
trigger({"event", "on", "once", "preventDefault"}): a form submit, a click, an element scrolled into view (visible), a tap on a character.<script type="application/json" data-pixel-scene>scenes are armed when the page loads;stage.arm(scene)from code. Steps can name the triggering element"$trigger"(or"$trigger .x"). - Actors:
pickUp(el)(a styled copy rides at the beak or hand;carrying),drop('here' | 'back'),exit('left' | 'right' | 'auto')(off the screen’s edge, delivering what it carries;offstage), andenter(...)(walk in from a side or drop in from the top); the same as scene steps andrun()orders. Eventspickup,drop,deliver,exit,enter. - Leaving or entering by the page’s right edge never widens the page; a speech bubble stays inside it.
- The stage demo’s newsletter form: subscribe and the goose posts your letter.
- Movement steps take a
speed(actor.hurry(rate)): faster, running, feet planted. The geese haveflap(from the kiddie goose) and arushgait (running with wings beating and neck out, after footage of running geese), used when hurrying. In the newsletter scene the goose flaps the moment you subscribe and rushes the letter off. - Carried things hang from the beak tip (or hand) by their near corner, tipped a little and behind the character, so the beak stays in view.
Scenes
Section titled “Scenes”stage.playScene(scene): scripted moments as JSON (in a<script type="application/json">, as text or an object). StepsgoTo(selector, cast name or point;then,at),hideBehind,perform,say,face,shoo,wait,together(parallel),waitFor(an event on a character, element or the stage),emit;asyncon any step;loop. Returns{finished, stop()};scenestep,sceneeventandsceneendevents;<pixel-stage scene="#intro">autoplays. Scenes are checked first, with JSON paths in the errors (checkScene). Steps that cannot happen are skipped.- Actors:
run(action, ...args)returns a promise (true when done, false if impossible or interrupted);say()returns a promise;face(); adirectedmode (no wandering between orders, stays seated or hidden); atapevent. - The stage demo plays “The plan” (goose, Clawd and Pip); the docs site’s stage page plays a race.
- New example character
examples/clawd.json, a blocky orange critter after the Claude Code mascot: 12 animations (idle, a “thinking” shuffle, a sideways scuttle walk and run, hop, wave, jump, fall, climb, sit, duck, peek), all hand-keyed on a 16-cell grid so it stays crisp at every size. Generated byscripts/gen-clawd.mjs. On the stage demo, the docs home page and the motions gallery. - Stage:
actor.perform(name); a live character’ssizecan change (speed, jumps and hit area follow). The stage demo has a character-size slider (50–200%, remembered).
Rage clicks, playback rate, fast scrolls
Section titled “Rage clicks, playback rate, fast scrolls”<pixel-sprite>: bursts of quick clicks firespriteburst{count, rate} andspritecalm; a burst speeds up a playing click animation; arateattribute (0.25..4) andeffectiveRate; state machines getburst/calminteractions ($count,$rate) and node rates from inputs. The goose honks faster with each quick click and panics.<pixel-stage>: rage taps make a character panic (faster, fleeing) withburst/calmevents;fastscrollandscrollsettleevents andstage.scrollSpeed;keep-in-viewcharacters catch up after a scroll (run at 2.5×, or drop in from the top of the screen);actor.catchUp(). Movement scales with playback rate everywhere.
- Drag and throw characters with a mouse or pen (touch keeps tap-to-shoo, so scrolling is never hijacked).
data-pixel-surface="animated": moving surfaces are re-read every frame; characters ride them, and jumps onto them follow them in the air. The stage demo has a drifting cloud.
Plug-ins
Section titled “Plug-ins”registerShape,registerTexture,registerMotion(andusePlugin,registeredPlugins): new shapes, textures and motion models validate, render and animate like built-ins, andpixel brieflists them. CLI--plugin. Example:examples/plugins/extras.mjs(star shape, feathers texture, float motion) andstarfish.json.
Transition clips
Section titled “Transition clips”mixesin specs ("waddle>idle": {"frames": 3}) bake in-between frames that blend the end of one animation into the start of another.<pixel-sprite>plays them when a switch happens at a boundary (loop end or after a one-shot), so stops and starts no longer pop;play(name, {mix: false})skips them. The geese have them.
Docs site
Section titled “Docs site”site/: nine pages where every feature is a live example next to its code (copyable, highlighted), and spec playgrounds that render a character with the real engine as you edit it. Overview, sprites, events and points, state machines and skins, moving sprites, the stage, writing a character, figures and motions, bundles and game engines (with a live PixiJS example). Works on phones.npm run build:demoalso writes a poster PNG per character and an exported goose sheet for the PixiJS example.
Runtime (<pixel-sprite>)
Section titled “Runtime (<pixel-sprite>)”- Fixed: one sprite that threw stopped every sprite on the page. The shared frame loop now requests
the next frame first and isolates each sprite; a failing sprite goes to
state="error". - Fixed: elements upgraded after parsing loaded their bundle twice.
- Fixed: before load (and after a failure) a sprite was 300 × 150 px. The box is now reserved from
size. - Fixed: overlapping
srcchanges could race and show the wrong bundle or throw. Loads carry a token and commit atomically. - Fixed: a failed fetch was cached forever. Failures are evicted;
reload()retries. - Fixed:
alt=""was announced with the bundle’s name. It now marks the sprite decorative. - Fixed: under reduced motion, one-shots never fired
spriteend. They now hold a frame and end on time, and the setting is watched live. - Added: scaling in whole device pixels (even pixels at DPR 2.625, 1.5 and with zoom), re-run when the DPR changes.
- Added:
errorevent andstateattribute (loading/ready/error); light-DOM fallback content (a poster<img>). - Added: the shared
clockexport for page code,el.pxPerSecond(name),el.displaySize,el.currentAnim,el.frame,el.reload(),play(name, {restart})(re-playing the current animation no longer restarts it). - Added: bundle validation (
checkBundle), decoded sheets shared between sprites (ImageBitmap), one sharedIntersectionObserver,fpsobserved. - Changed: on touch screens
hover-animno longer flashes during a tap; a tap plays it once when there is noclick-anim. - Added:
test/browser/runtime.html, 24 in-browser checks to run on real devices (pass in Chromium, Firefox, WebKit and iOS Safari), andscripts/browser-check.mjs, which runs them and every docs-site page in Firefox and WebKit with Playwright (installed outside the project; no dependency). - Fixed: a one-shot started while off-screen never fired
spriteend; it now ends on time, as under reduced motion.
Bundles and specs
Section titled “Bundles and specs”- Bundles record the spec canvas
sizeand the foot lineground(units), so pages can convertspeedto px/s and stand a character exactly on an element. - Animation events: motion models emit
footstep(with the leg),takeoff/land(hop) andlaunch/land(jump); authors add"events": [{"frame", "name", "data"}]. The runtime fires them asspriteevent. - Attachment points:
pointsin specs and figures (beak,head, hands, …), baked per frame;el.point(name). - Frame holds:
"holds": {"3": 2}→ per-framedurationsin the bundle. - Skins: named patches (
skins) baked as extra variants;<pixel-sprite skin="party">. CLI--skin. - State machines:
states(inputs, nodes with one-shots and random fidgets, transitions with conditions andatnow / end / sync / an event name, click and hover interactions). Runtimeel.set,el.fire,el.stateNode,statechange; exportedStateMachineandparseCondition. - Validation for all of the above, with JSON paths and did-you-mean.
Figures and motion
Section titled “Figures and motion”- New motion models:
jump(legged, one-shot, timed bylaunch/land),climb(feet on a wall, exportsspeedYand thewallline),fall,sit(on an edge);duckandpeekpresets. New rig rolewings. - Presets for them in every figure where they make sense; examples gained
jump,fall,sit,duck,peekand (geese)climb. - Figures define attachment points and their foot line.
Page interactions: <pixel-stage> (new)
Section titled “Page interactions: <pixel-stage> (new)”- Characters live on a real page: walk along
data-pixel-surfaceelements, drop and jump between them, climbdata-pixel-climbablesides, sit on edges anddata-pixel-perches, duck and peek behinddata-pixel-hideelements, pass behinddata-pixel-occluders (clip-path cut-outs), avoiddata-pixel-avoid. - Cost-based route planning; layout read only when the page changes; tap or click a character to shoo it (only its opaque pixels, and that click does not reach the page); a pause button that is remembered; reduced motion.
actor.goTo(),hideBehind(),say(),shoo(),actorstate/land/arriveevents.- Demo:
demo/stage.html. Checked in desktop Chromium and iOS 18.1 Safari (simulator).
Export
Section titled “Export”pixel exportwrites a PNG sheet with Aseprite-format JSON (frames named by index, frame tags, slices for points, per-frame durations) plus a PixiJSanimationsmap. Loaded successfully by PixiJS 8.6 and Phaser 3.88.pixel preview --anim a,blimits the rows.
- The flock moves its geese on the runtime’s clock with
pxPerSecond, snaps to device pixels, and stops while off-screen.
[0.1.0] - 2026-11-08
Section titled “[0.1.0] - 2026-11-08”First public version.
Engine
Section titled “Engine”- JSON character spec: materials, parts with pivots and parents, SDF shapes (rect, ellipse, circle, capsule, polygon), animation tracks (keyframes, eased keys, waves). Validation with JSON paths and did-you-mean.
- Pixel-art renderer at any resolution with three detail tiers: hue-shifted colour ramps, lighting, textures in part space, dithering, selective outlines, inner lines, contact shadows.
- Sprite sheets, contact sheets, ASCII frames, and self-contained web bundles (
pixel-sprite/1). reachconstraints (IK), bounds and reach warnings,extendsvariants.
Figures and motion
Section titled “Figures and motion”- Figure library:
goose,human,dog(side view),chibi(front view),blob(soft body). - Motion models:
gait(planted feet, body bob and pitch, steady head, arm swing),idle,pose,hop(gravity arc, volume-preserving squash and stretch). Front-view walking. Exportedspeedfor slide-free movement on a page. - Follow-through springs for tails, ears, scarves and antennae.
pixelCLI (validate, preview, ascii, render, bundle, resolve, where, figures, brief).- Studio with live editing, rig overlay, detail-level strip and an Agent tab; figure viewer.
<pixel-sprite>web component: resolution variants, hover/click animations, reduced motion, off-screen pause.