@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/cursor/skills/funpixel-publish/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: funpixel-publish
+description: Use when publishing (putting it live so friends can play it) or replacing a game on Funpixel or another host, checking a published game, or making its trailer, share video, store shots, title card, logo sting or a playable ad (AppLovin, Unity Ads, ironSource, Meta, TikTok). Covers the verify record, what ships, a leak scan, the post-publish smoke and the five-second ad with its call to action.
+---
+
+# Publish a game
+
+A launch is the game's first impression: a link that opens straight into play, a cover, and store
+shots, a trailer and ads cut from real moments. Publishing uploads a draft you own at a permanent
+address; sharing it on the Community shelf is a separate choice. The platform builds what you upload
+on its own machine, so a game that only works on yours arrives broken.
+
+## Tools
+
+- `publish_game` uploads with the same verify gate; `probe` plays the published URL and returns
+  the verdict; `screenshot` captures it at a phone viewport; `build` shows why an upload failed.
+- `store_shots`: store-size screenshots from the newest real capture run, never concept art.
+- `report_feedback` files what was missing, before you finish.
+- Local: `npx @funpixel/tools publish` (needs `FUNPIXEL_API_KEY`), `npx @funpixel/tools verify`,
+  `funtools doctor`, `funtools pack --dry-run` (what ships, which rule dropped each file, a leak
+  scan), `funtools smoke`, `funtools publish --target itch|pages|folder` for
+  another host, `funtools export <dest>` for a games repo, `funtools reel` / `funtools playable`.
+- Video: `funtools trailer` cuts one from play ([references/trailer.md](references/trailer.md));
+  `compose_video` (`funtools compose`) renders one you design in HTML, the game live in it
+  ([references/compose.md](references/compose.md)); `funtools motion` draws title cards and loops
+  ([references/motion.md](references/motion.md)).
+
+## Steps
+
+1. **The key.** Publishing needs a paid plan and an `fp_live_` key with the `games:publish` scope,
+   in the `FUNPIXEL_API_KEY` environment variable. A key in a file that ships is public the moment
+   the game is. `npx @funpixel/tools doctor` lists what the server build would trip on (the engine
+   in `dependencies`, an unpinned SDK, the viewport meta).
+2. **A fresh, passing verify.** `verify.json` fingerprints the files that ship, so the record has
+   to come from `npm run build && npx @funpixel/tools verify` after the last edit. Publish refuses
+   in three distinct ways:
+
+   | Refusal | Cause | Fix |
+   |---|---|---|
+   | no verify record | verify never ran in this folder | run verify |
+   | stale | a shipped file changed after verify | verify again; nothing else |
+   | failed | the last verify failed | fix what it reported, then verify |
+
+   Exit 2 (not observed) publishes unverified; say so in the hand-back.
+3. **What ships** is the folder minus `node_modules/`, `.git/`, `dist/`, `.vite/`, empty files and
+   the rules in `.harnessignore`. A rule without a leading `/` matches at any depth, so `assets/`
+   also strips `public/assets/` and the game ships with no art. The rules, and what an odd `files`
+   count in `verify.json` means: [references/what-ships.md](references/what-ships.md).
+4. **Scan the contents, not the names.** Keys, machine paths, private tooling, vendor names inside
+   GLBs, source maps and a live debug escape all hide in files with harmless names; the scan list
+   is in [references/what-ships.md](references/what-ships.md), and `funtools pack --dry-run` runs it.
+5. **Pass the server build.** It installs with lifecycle scripts off and runs a plain `vite
+   build` on its own `vite.config.ts`; your `dist/` is never used. What builds green there and
+   breaks live (a value only in `.env`, a CDN engine, `file:` links, a caret SDK), and how to
+   reproduce it: [references/server-build.md](references/server-build.md).
+6. **Publish.** `npx @funpixel/tools publish --name "Title"` prints `draft <game_id>` and, when
+   the draft has one, its address. The id in `funpixel.json` keeps every later publish on that
+   draft and address. `--game-id <id>` overrides the file.
+7. **Smoke the published URL the way players load it.** `npx @funpixel/tools verify <play_url>`,
+   or `probe` on it, and a `screenshot` at 390x844. Exit 0 and a drawn frame: done. Blank or
+   hanging: read the requests that got HTML where a decoder or asset belongs, the console and
+   `build`; fix, verify, publish again.
+8. **Another host** (itch.io, Cloudflare Pages, a folder) takes the built `dist/`, never the
+   source. You prepare; the person performs: show the host, address, file count and size and wait
+   for their yes, since it goes public under their name; their host token stays with them. Method and limits:
+   [references/other-hosts.md](references/other-hosts.md).
+9. **Trailer, store shots and ads come from real play.** A concept image, the target frame or a
+   state the game cannot reach misleads stores and players. Mark each
+   payoff in code, `window.__FPX_MOMENT__?.('boss_down', 1)` (weight 0 to 1): the capture tour
+   shoots at the mark and the share video cuts on it. `store_shots` for the stores, `funtools reel`
+   for a local vertical cut. Look before handing it over; arc, captions, icon:
+   [references/store-shots.md](references/store-shots.md). **Compose a video** to design the cut
+   (trailer, 9:16 post, end card): `funtools compose new trailer`, edit, render, read its contact sheet.
+   `ad_variations` cuts many for store tests or network A/B; the person picks which to publish.
+10. **A playable ad** is the game's best verb cut out as one HTML file inside somebody else's app,
+   where a player gives it five seconds: the board mid-situation with a hand on the one thing to
+   press, a move that cannot fail, the reward, then the call to action on the beat after it (never on
+   the first tap). Every asset inlined, nothing fetched at runtime, under the tightest network's
+   ceiling, both orientations; `npx @funpixel/tools playable --network <network>` weighs it and plays
+   it offline. Steps, the cut order and the networks' table: [references/playable-ad.md](references/playable-ad.md),
+   [references/networks.md](references/networks.md).
+11. **Feedback.** `report_feedback` tells Funpixel what was missing and what you worked around
+   (skill `funpixel-feedback`): it is how a missing tool gets built.
+
+## Worked example
+
+Publishing a Pixi runner:
+1. `npx @funpixel/tools doctor`: all ok.
+2. `npm run build && npx @funpixel/tools verify`: exit 0, `verify.json` says 61 files.
+3. 61 is low for 140 art files: `.harnessignore`'s `assets/` also strips `public/assets/`. It
+   becomes `/assets/`: 203 files.
+4. The scan finds a home-folder path in `src/debug.ts` and a `?debug=1` branch that enables god
+   mode. Both go; verify again, exit 0.
+5. `npx @funpixel/tools publish --name "Tunnel Fox"` prints
+   `draft 3f9c2a7e4b1d4c8e9a0b6d5e7f8a9b0c https://…/`.
+6. `npx @funpixel/tools verify` on that URL: exit 1, the canvas never drew;
+   `/basis/basis_transcoder.wasm` answered with HTML (a dev plugin served it from `node_modules`).
+   The decoders move to `public/basis/`; verify, publish again (same address); the smoke passes.
+
+## Common mistakes
+
+- Treating publish as sharing: the draft is off the Community shelf until you share it.
+- Editing a shipped file after verify "just a comment": the record is stale and publish refuses.
+- Deleting or editing `game_id` in `funpixel.json`: the next publish makes a second draft at a new
+  address.
+- Sending `src/` to itch.io or Pages, or publishing there without the person's yes.
+- Store shots or a trailer from concept art or an idle board: stores reject it, players skip it.
+- A playable ad that loads assets by path, or asks for the install on the first tap: a blank frame,
+  or a network's refusal.

package/plugins/cursor/skills/funpixel-publish/references/compose.md

@@ -0,0 +1,113 @@
+# Compose a video: HTML in, MP4 out, the game live in it
+
+`funtools trailer` cuts a trailer for you from a filmed take. `funtools compose` is for the cut you
+design: a 15 s trailer, a 9:16 post, the end card of a playable ad. You write it as a HyperFrames
+composition (HTML with timed clips on tracks, GSAP for titles, `<audio>` for sound), the game sits in
+it as a live clip, and the kit renders it frame by frame to an MP4 that comes out the same every time.
+HyperFrames (HeyGen's renderer, Apache-2.0) does the rendering; the kit stages the game and checks the
+result.
+
+## Make one
+
+1. **Build and capture.** `npm run build`, then `npx @funpixel/tools capture --all`: the starters use
+   the build, the captures (real frames for strips and hooks), the key art (`design/key-art.png`) and
+   the game's own music and effects from `public/assets/`.
+2. **Start from a starter.** `npx @funpixel/tools compose new trailer` writes
+   `design/compose/trailer.html` (15 s, 16:9). `post` is 10 s at 9:16 and `endcard` is 6 s at 9:16.
+   `--aspect 16:9|9:16|1:1` re-frames one, `--seconds` re-times it, and `--name` keeps several.
+3. **Fill it in.** The words are composition variables on `<html data-composition-variables>`: title,
+   tagline, caption1, caption2 and cta. Change their `default`s. Move a clip by its `data-start` and
+   `data-duration`, change its look in the `<style>`, and its motion in the timeline script at the bottom.
+4. **Render.** `npx @funpixel/tools compose render design/compose/trailer.html` (or the
+   `compose_video` tool). It checks the contract, probes each game clip, runs HyperFrames' lint, renders
+   `.funtools/compose/trailer.mp4`, and writes `trailer.sheet.jpg` (twelve frames, 4 x 3) and
+   `trailer.json` (the record).
+5. **Look at the sheet** before you hand the video over. The checks catch a wrong length, a blank
+   frame, and a game clip that is one still picture. They do not catch a caption over the hero or a
+   title that is hard to read on key art: you catch those by looking.
+
+## Many ad cuts from one brief
+
+For a store listing test or an A/B across ad networks, write `design/compose/ads.json` and run
+`npx @funpixel/tools compose variations` (the `ad_variations` tool):
+
+```json
+{ "hooks": [{ "line": "Bugs don't pop. They sneeze.", "moment": "chain" }, { "line": "One puff, fifteen sneezes", "moment": "chain-desktop" }],
+  "ctas": ["Play now", "Play free"], "lengths": [6, 15, 30], "aspects": ["9:16", "1:1", "16:9"],
+  "end_card": { "title": "Achoo!", "tagline": "Sneeze them all" }, "max": 12 }
+```
+
+- A hook's `moment` is a capture by name (`chain-desktop`, from `capture --all`) or a view (`chain`,
+  live). Left out, the cut opens on the game's payoff moment.
+- It makes at most `max` cuts. Every hook, call to action, length and aspect is in one before any
+  pair repeats. `--dry-run` prints which cuts and what each opens on.
+- Each cut is its own composition, `design/compose/ads/<id>.html`: the post (12 s or shorter) or the
+  trailer, its opening first, the hook as caption 1. `compose render` re-renders one you edit.
+- Out: `.funtools/compose/ads/<id>/` (the MP4, its contact sheet, its record), `index.json` and
+  `sheet.png`, one labelled frame per cut. A failed cut is still there, marked.
+- The end card's words should be the playable's own. A difference is a warning, not a failure.
+- Show the person `sheet.png`. They pick which cuts to publish.
+
+## The game clip
+
+```html
+<iframe id="game" class="clip game" style="left:0;top:0;width:100vw;height:100vh"
+        data-start="2" data-duration="7.2" data-track-index="1" data-no-timeline
+        data-fpx-game="game/index.html" data-fpx-view="playing" data-fpx-inputs='auto'></iframe>
+```
+
+| Attribute | What it does |
+|---|---|
+| `data-fpx-game="game/index.html"` | The build. compose stages `dist/` there, with the held clock first in its `<head>`. |
+| `data-fpx-view` | The `__FPX_VIEWS__` view entered when the clip starts (a fresh round from the seed). Left out, the clip shows what the game boots to. |
+| `data-fpx-inputs` | `auto` presses the game's own play verbs about four times a second, the way `reel` plays it. A list scripts it instead: `[{"at": 1.2, "verb": "jump"}, {"at": 2, "key": "ArrowLeft", "hold": 0.4}, {"at": 3, "tap": [0.5, 0.8]}]`, with seconds into the clip. `[]` presses nothing, which suits a moment view that stages its own payoff. |
+| `data-fpx-lead` | Game seconds run after the view is entered, before the clip's first frame (default 0.5). |
+| the box | The iframe's CSS size is the game's viewport, so a 1920x1080 box gets the desktop layout. A landscape game in a 9:16 post sits in a 16:9 band; the starters do this for you. |
+
+Two clips of one game are two games, each driven on its own. That is how the trailer cuts from play
+to a payoff moment.
+
+**Why the game can be seeked.** A render never plays the composition. It asks for frame 90, then
+frame 91, in any order, on as many workers as it likes. The kit runs the game on the held clock
+`capture` uses (`requestAnimationFrame`, timers, `performance.now`, `Date.now`, CSS and Web
+Animations, and a seeded `Math.random` all stand still until moved). The composition's clock moves it
+to the game frame for each video frame, and the scripted inputs fire on their own frames. Asking for
+an earlier frame reloads the game and plays it forward again. No game time passes while the game is
+loading, so how fast this machine loads it changes nothing. The same composition gives the same game
+frames.
+
+**When it cannot be seeked.** compose probes each clip first. A game whose loop runs on something
+the clock does not hold (`AudioContext` time, a Worker, `new Date()`) runs no frames on it. Such a
+clip is filmed in real time, then played back as a sequence of frames. compose says so, and its frames
+are fixed files, so the render still repeats. The take itself does not repeat, so fix the loop if you
+can: run it on `requestAnimationFrame` with time from `performance.now()`.
+
+## What else goes in
+
+- Paths are written from the game folder (`design/key-art.png`,
+  `.funtools/capture/chain-desktop.png`, `public/assets/music/bed.mp3`) and are staged as written.
+  A path outside the folder (`../`) is refused.
+- Sound is `<audio data-start data-duration data-volume data-fade-in data-fade-out src>`. The game
+  playing inside its clip makes no sound in the render, so place its bed, and its effects on the
+  moments you show. Keep each slot no longer than its file.
+- Use real frames only. A strip of captures, the live game, the key art: yes. The target frame
+  (`design/target.png`) is a mock-up, and a card made from it passes one off as play.
+- Words go inside the clear area of the format, where a platform's own buttons never cover them. The
+  starters' `.safe` box is it.
+
+## Common mistakes
+
+- A wall clock or unseeded randomness in the composition's own script (`Date.now()`,
+  `Math.random()`): every render differs. Put the motion on the timeline.
+- `repeat: -1` on a tween: the timeline has no end. Give it a count that fits the clip.
+- A game clip without an `id`, or one pointing anywhere but `game/…`.
+- Rendering before `npm run build`: the clip embeds the last build, not your source.
+- Shipping a video nobody looked at: read `*.sheet.jpg`.
+
+## Tools it needs
+
+Node 22 or newer, `ffmpeg` and `ffprobe`, and Playwright's headless Chromium (the browser verify
+uses, so a trailer renders the game as verify sees it). A missing one is named on one line with the
+command that installs it. The first render fetches the pinned HyperFrames with `npx`. To preview a
+staged composition with HyperFrames' own studio, run `npx hyperframes@0.8.145 preview
+.funtools/compose/<name>`.

package/plugins/cursor/skills/funpixel-publish/references/motion.md

@@ -0,0 +1,120 @@
+# Motion: title cards, stings and loops drawn frame by frame
+
+A trailer shot is filmed from real play ([trailer.md](trailer.md)). Everything around it is drawn:
+the title card, the logo sting, the end card, a lower third, a social loop, a single's visualiser,
+a podcast's audiogram, a film's titles. `funtools motion` is the bench for those. You write the
+scene as a web page that draws frame f; the kit renders it one frame at a time on a held clock, so
+two renders are the same pixels, checks the frames, then encodes the video.
+
+## The scene contract
+
+A scene is an `.html` page (or a folder holding `index.html`) using CSS animation, a canvas, SVG
+or GSAP. It may declare itself before anything else runs:
+
+```html
+<script>
+  window.__MOTION__ = { seconds: 4, fps: 30, size: '1080x1920', loop: true };
+</script>
+```
+
+| Key | Meaning | Default |
+|---|---|---|
+| `seconds` (or `frames`) | the length; `frames` wins when both are given | 5 s |
+| `fps` | frames a second, 1 to 60 | 30 |
+| `size` (or `aspect`) | the frame in CSS pixels, `'WxH'`, even sides; or `'9:16'`, `'16:9'`, `'1:1'`, `'4:5'` | 1080x1920 |
+| `loop` | the last frame runs back into the first, and the seam is checked | false |
+| `safe` | your own safe zone, shares of each side `{ top, right, bottom, left }` | the format's |
+
+Flags on the command beat the contract. The page is opened at exactly `size`, at device scale 1, so
+`vw`, `vh` and `vmin` units carry one scene to every aspect.
+
+Two ways to move:
+
+- **Let the held clock move it.** CSS animations, Web Animations, `requestAnimationFrame`,
+  `setTimeout`/`setInterval`, `performance.now()` and `Date.now()` all stand still until the kit
+  steps them, one frame of `1000 / fps` ms at a time, and `Math.random` is seeded. A CSS-only scene
+  needs nothing else.
+- **Draw any frame on demand.** Give `window.__MOTION_SEEK__ = (frame) => { … }` (0-based; it may
+  return a promise) and the kit calls it for every frame after stepping the clock. Make it pure:
+  frame 40 looks the same whichever frame came before. A GSAP timeline is
+  `tl.pause(); window.__MOTION_SEEK__ = (f) => tl.seek(f / fps)`.
+
+Frame 0 is time 0 of every animation the page started on load (one boot frame is stepped first so
+each animation is born on the held clock). With the clock alone, `performance.now()` at frame f is
+`(f + 1) × 1000 / fps`.
+
+Not held, so never draw from them: video and GIF frames, audio time, Web Workers, `new Date()`,
+`requestIdleCallback`. A font or image the page fetches is waited for before the clock moves; one
+from a CDN makes the render depend on the network, so keep fonts and images beside the scene.
+
+## Commands
+
+```sh
+npx @funpixel/tools motion new title-card --aspect 9:16
+npx @funpixel/tools motion render title-card --prove
+npx @funpixel/tools motion render title-card --aspect 16:9 --out out/title-wide --webm
+npx @funpixel/tools motion render sting.html --fps 60 --seconds 2 --audio sting.wav
+npx @funpixel/tools motion check .funtools/motion/title-card
+```
+
+- `new <name>` writes `<name>/index.html`: a title, a subtitle and a CSS loop that passes every
+  check. Start there and make it yours.
+- `render` serves the scene (its folder as plain files, or its project's own Vite when the project
+  has a `package.json` with Vite installed, so a scene may import the game's drawing code), shoots
+  `frames/000001.png…`, encodes `motion.mp4` (H.264, yuv420p, faststart; plays in QuickTime, on
+  iOS and in every browser), `motion.webm` with `--webm`, and muxes `--audio`, padded or cut to the
+  picture's length. Output goes to `.funtools/motion/<scene>/` unless `--out`; it never ships.
+- `check` judges a render folder again from its files, or renders a scene and judges it without
+  encoding.
+- Rendering is software GL, as the hosted probe runs, at roughly a third of a second a frame at
+  1080x1920: a 4 s loop at 30 fps takes about 40 s, and `--prove` doubles it.
+
+Exit 0 every check that applies passed, 1 one failed, 2 nothing could be judged (no browser), 3 an
+error (a flag, a page that did not load, an encode that failed). `motion.json` holds the plan, every
+frame's hash, the render's hash and each check; `layout.json` holds the layout samples.
+
+## The checks
+
+Each check is pass, fail or not observed; not observed is never a pass.
+
+| Check | What it measures | Fails when |
+|---|---|---|
+| repeatable | with `--prove`, a second render, every frame's bytes compared | any frame differs; the first that differs is named |
+| safe zone | `layout.js` (the file `audit-screens` uses) at the first frame, every 0.5 s and the last: text and controls against the safe zone, and text cut by the frame's edge or by what it sits in | a line of text or a control is outside the zone or cut |
+| overlaps | the same samples: every element with its own text paired with every other, in flow or not | two pieces of text paint over each other |
+| loop seam | a loop only: the frame after the last (rendered, not kept) against the first | it differs by more than 0.4% and by more than twice the median change between neighbouring frames |
+| blank frames | every frame at least 0.5 s from both ends | 99.5% of it sits within 10 levels of one colour |
+
+The safe zones are the trailer's clear areas (one table): 9:16 keeps 13% top, 15% right, 22%
+bottom and 6% left clear (the feed's header, its rail of buttons, the caption block); 4:5 and 1:1
+keep 6% at the sides and top and 10% at the bottom; 16:9 keeps 7% top, 5% at the sides and 12%
+bottom. A shape bleeding off the frame is design, not a cut; only text and controls count.
+
+Text drawn on a canvas is invisible to the layout checks: they say not observed. Put words in the
+page as text over the canvas when they matter.
+
+In a game folder with `design/status.json`, each render adds a `motion:<scene>` part to the zero
+board (`funtools zero`): each stretch of blank frames to errors, safe zone and overlaps to
+overlaps, the seam to seams.
+
+## Making a loop that closes
+
+- Give every looping animation a period that divides the length: a 4 s scene takes 4 s, 2 s or 1 s
+  periods. Set the length once (in `__MOTION__`) and derive the CSS from it, as the starter does
+  with a `--loop` custom property.
+- Its first and last keyframes match: `0%, 100% { … }`, or a full turn, `rotate(360deg)`.
+- An entrance that plays once (`animation-fill-mode: both`) cannot loop. Either end the scene on
+  the exit, or set `loop: false`.
+- A text entrance that slides in from beyond the frame is cut while it crosses the edge; at the
+  0.5 s samples that is a finding. Enter by fade, scale or a mask inside the frame, or finish the
+  move before the first sample after 0 s.
+
+## Common mistakes
+
+- Animating from `Date()` or a video element: the render no longer repeats; `--prove` names the
+  first frame that differs.
+- A black hold in the middle of a sting: read as an empty frame. Fades through black belong in the
+  first or last half second.
+- Titles laid out in pixels for one size: render at 16:9 and they spill. Use `vmin` and keep words
+  in the middle of the frame.
+- A web font from a CDN: the first render waits on the network and a later one may draw a fallback.

package/plugins/cursor/skills/funpixel-publish/references/networks.md

@@ -0,0 +1,75 @@
+# The networks, and what each one refuses
+
+Read from each network's own specification on 2026-09-26 (sources at the end). Networks change
+these pages; when a submission is refused for a reason not listed here, the network's page wins
+and this table is out of date.
+
+## Ceilings, packages and the call to action
+
+| Network | Package | Ceiling | Call to action | What it refuses |
+|---|---|---|---|---|
+| AppLovin | one HTML file, every asset base64 | 5 MB | `mraid.open(url)`; MRAID 2.0, used only after it reports ready | external network calls; sound before the first touch; a store redirect on the first tap; a timer that starts before the first touch; either orientation broken |
+| Unity Ads | one `index.html`, inlined and minified | under 5 MB | `mraid.open(url)`; MRAID 3.0, injected by the webview; start play on `viewableChange` | network requests (anonymous interaction analytics aside); blocking the close button; an automatic store redirect; either orientation broken |
+| ironSource | one HTML file, every asset base64, MRAID | 5 MB; build to 4 MB for the ironSource Exchange | `mraid.open(url)` | assets outside the file; plain `http://` links |
+| Mintegral | one HTML file (or a zip holding it) | 5 MB, measured unzipped | `window.install && window.install()`, plus the game-end call its test guide names | external URLs in the source |
+| Google Ads (App campaigns) | a zip with `index.html` and at most 512 files, relative paths | 5 MB | `ExitApi.exit()`, with Google's `exitapi.js` script in the head | any external reference except Google Fonts and Google-hosted jQuery, GreenSock and CreateJS; sound before a touch; a missing `<meta name="ad.orientation">` |
+| Meta | one HTML file (or a zip with `index.html` at the top) | 2 MB for the single file, 5 MB for a zip | `FbPlayableAd.onCTAClick()` | `mraid.js`; any HTTP request; a JavaScript redirect; a layout that is not responsive |
+| TikTok Ad Network | a zip with `index.html` and `config.json` (`playable_orientation`: 0 either, 1 portrait, 2 landscape) at the top | under 5 MB, compressed | `window.openAppStore()`, from TikTok's playable SDK script at the end of the body | `mraid.js`; any HTTP request; a JavaScript redirect |
+
+Treat a megabyte as 1,000,000 bytes and leave 10% spare: networks do not agree on the unit, and a
+file that fits by a few kilobytes fails the first time a sprite changes.
+
+A creative that fits Meta's single file (2 MB, no MRAID, no network) fits every other network's
+ceiling too; only the call-to-action function and the package change.
+
+## One wrapper for every network
+
+```ts
+declare const mraid: any, FbPlayableAd: any, ExitApi: any;
+const STORE_URL = 'https://apps.apple.com/app/id0000000000';   // or the Play Store listing
+
+export function cta(): void {
+  const w = window as any;
+  if (typeof FbPlayableAd !== 'undefined') return FbPlayableAd.onCTAClick();
+  if (typeof ExitApi !== 'undefined') return ExitApi.exit();
+  if (typeof w.openAppStore === 'function') return w.openAppStore();
+  if (typeof w.install === 'function') return w.install();
+  if (typeof mraid !== 'undefined') return mraid.open(STORE_URL);
+  window.open(STORE_URL, '_blank');                             // local preview only
+}
+
+/** Start play once the container is ready: MRAID networks load the ad before it is shown. */
+export function whenReady(start: () => void): void {
+  if (typeof mraid === 'undefined') return start();
+  const go = () => (mraid.isViewable?.() ?? true) ? start() : mraid.addEventListener('viewableChange', (v: boolean) => v && start());
+  if (mraid.getState() === 'loading') mraid.addEventListener('ready', go); else go();
+}
+```
+
+A per-network build replaces the whole wrapper with the one line it needs, when a reviewer
+objects to the others being present.
+
+## Checking before submitting
+
+- The file size against the ceiling above, with the spare.
+- The URL search from the skill (step 7) finds nothing but the network's own sanctioned script.
+- Offline in a phone frame, both orientations: it draws on the first frame, the hand points, the
+  move works, the call to action fires once after the reward.
+- The network's own preview: AppLovin's playable preview (p.applov.in/playablePreview), Meta's
+  playable preview tool in Ads Manager, Google's HTML5 validator on upload, Mintegral's playable
+  test guide.
+
+## Sources
+
+- AppLovin, creative specs and guidelines:
+  https://support.applovin.com/en/growth/promoting-your-apps/welcome-to-applovin/creative-specs-and-guidelines
+- Unity Ads, playable asset specifications:
+  https://docs.unity.com/en-us/grow/acquire/creatives/playable/specifications
+- ironSource, interactive ad requirements (5 MB) and the ironSource Exchange MRAID guidelines
+  (4 MB): https://docs.unity.com/en-us/grow/is-ads/user-acquisition/creatives/interactive-requirements
+  and https://docs.unity.com/en-us/grow/programmatic/ironsource-exchange/mraid-specifications-guidelines
+- Mintegral, creative asset specifications: https://helpcenter.mintegral.com/en/docs/asset-specs
+  (the install and game-end calls are named in its playable test guide, linked from there)
+- Google Ads, HTML5 and playable ads for App campaigns: https://support.google.com/google-ads/answer/9981650
+- Meta, specifications for playable ads: https://www.facebook.com/business/help/412951382532338
+- TikTok Ad Network playable ads: https://ads.tiktok.com/help/article/how-to-create-tiktok-pangle-playable-ads

package/plugins/cursor/skills/funpixel-publish/references/other-hosts.md

@@ -0,0 +1,65 @@
+# Publishing somewhere else: itch.io, Cloudflare Pages, a folder
+
+Funpixel builds from your source. Every other host takes a finished build, so the rules turn
+around: what leaves your machine is the built `dist/` folder and nothing else, and the person, not
+the agent, sends it. `funtools publish --target itch|pages|folder` is planned; until it lands, this
+is the method by hand.
+
+## The model prepares; the person performs
+
+An agent can build, verify, count and check. It does not choose where a game goes, it does not
+sign in for anyone, and it does not press publish on its own.
+
+1. **Ask where it goes.** itch.io (which account and game page), Cloudflare Pages (which
+   project), or a folder (which path). Never pick a host or guess a name for the person.
+2. **Build and verify fresh.** `npm run build && npx @funpixel/tools verify` must pass on the
+   build you are about to send; an edit after the verify means verify again.
+3. **Check it is a build.** The folder you send has `index.html` at its top and holds no
+   `package.json`, `src/`, `.git/`, `.env`, `node_modules/` or `verify.json`. A folder named `src`
+   is never a build. Run the leak scan from the skill (step 4) over it.
+4. **Ask, every time.** Show the host, the address it will have, the number of files and their
+   total size, and say that what is published stays published. The person answers yes or no; a
+   "no" publishes nothing. With nobody watching (a scheduled task, a background run), do not
+   publish: approval that cannot be asked is refused, not assumed.
+5. **Hand over the command** or run it once approved. Logins are the person's: they run
+   `npx wrangler@4 login` or `butler login` themselves. A token never goes on a command line or into
+   a file in the game.
+6. **Record it.** `funtools publish` appends one line per publish to `.funtools/publish.jsonl`
+   (host, address, the `verify.json` fingerprint, the time); that folder never ships and never
+   makes a verify stale. Publishing by hand, append the same line there yourself.
+7. **Smoke the live address** with `npx @funpixel/tools verify <url>`, as for a Funpixel publish.
+
+## itch.io
+
+- The person makes the game page once at itch.io/game/new, with Kind of project set to HTML.
+- Push the build with butler: `butler push dist <user>/<game>:html5`. Check that butler is signed
+  in before running it (`BUTLER_API_KEY` is set, or the person has run `butler login`): butler with
+  no credentials opens a browser to sign in, which nobody asked for.
+- After the first push, the person ticks "This file will be played in the browser" on the upload
+  and sets the embed size.
+- Limits, from itch.io's HTML5 guide: at most 1,000 files, 500 MB extracted, 200 MB for any one
+  file, 240 characters for a path. Paths are case-sensitive on the server.
+
+## Cloudflare Pages
+
+- Create the project once: `npx wrangler@4 pages project create <name> --production-branch main`.
+  "Already exists" is fine if it is the person's own project.
+- Deploy the build: `npx wrangler@4 pages deploy dist --project-name <name> --branch main`.
+- Read the live address from wrangler's output. A taken name gets a suffixed `*.pages.dev`
+  subdomain, so the guessed `<name>.pages.dev` can be a stranger's site: never report an address
+  you did not read back.
+- Limits, from Cloudflare's Pages limits: 20,000 files a site on the free plan, 25 MiB for any one
+  file.
+
+## A folder
+
+A copy on disk is the host that has destroyed the most work: one publisher deleted whatever path
+it was given, and was given a folder that held the project's sources.
+
+- Copy into a new, empty folder, or into one that holds a marker file your own earlier copy left
+  (write one, such as `.published-copy`, beside the files).
+- Refuse a destination that holds sources (`package.json`, `src/`, `.git/`), that holds the project
+  itself, or that is a shared root such as the home folder or the Desktop. A hand-made site (an
+  `index.html` with no marker) is not yours to replace.
+- Replacing an earlier copy moves it to the Trash; it never deletes.
+- A folder never leaves the machine, so step 4's question is skipped; it still gets the log line.

package/plugins/cursor/skills/funpixel-publish/references/playable-ad.md

@@ -0,0 +1,90 @@
+# Playable ads
+
+A playable is the game's best verb, cut out and served as one HTML file inside somebody else's
+app, where a player gives it five seconds. Networks reject or blank most first attempts for one of
+three reasons a normal build never tests: the file is over that network's ceiling, it fetches
+something at runtime and shows an empty frame, or it asks for the install before the player has
+had the good moment. This skill builds the playable from the real game and checks all three.
+
+## Tools
+
+- `npx @funpixel/tools optimize compress <image> --max-size <px> --write` compresses each picture
+  to the size it is drawn at; `optimize pack-atlas <sprites…> --write` packs more than three sprites
+  into one sheet (local and free; not MCP tools yet). Bytes are the budget here.
+- `screenshot` captures the published game's peak moment, as the reference for the end card.
+- Local: `npx @funpixel/tools playable --network <network>` builds the one file into
+  `dist-playable/index.html` (from `playable.html` when there is one), weighs it against that
+  network's ceiling, fails on anything it would fetch at runtime, then plays it offline on a phone
+  with the network's call to action stubbed: it must not fire by itself or on the first tap, and
+  must fire on the end card after the score rises (expose the score in `__FPX_STATE__`, or that
+  part is "not observed"). `verify <url> --viewport both` on the served file adds render health.
+
+## Steps
+
+1. **The networks first.** The ceiling and the call-to-action function differ by network, and
+   art made for 5 MB will not fit 2 MB, so the tightest network the campaign runs on sets the budget: [networks.md](networks.md) has the table, with sources.
+2. **Cut one move from the real game.** The single most satisfying verb, isolated and made
+   generous: not a level, not a tutorial, not three mechanics. A separate entry
+   (`playable.html` and `src/playable.ts`) imports the game's own systems, with a fixed seed and the
+   one scenario set up; it is not the whole game behind a flag.
+3. **The five seconds.**
+   - First frame: the board mid-situation, with a hand or arrow on the one thing to press. No logo,
+     loading screen or title.
+   - Seconds two to four: the move. Big hit areas, and a near miss counts: the move cannot be
+     failed. A wrong tap still answers (a nudge, a shake).
+   - The reward lands loud, and the call to action arrives on the beat after it (networks refuse
+     a store redirect on the first touch, and players install after the good moment).
+   - A common rhythm: three seconds without a touch brings the hand back; a player who never
+     moves gets the call to action at about eight seconds.
+   - Timers start at the first touch, and sound stays muted until then.
+4. **The call to action.** Large, in the bottom third, and the only live control once it shows.
+   The label names the game, not the button ("Keep playing", not "Install now"). It calls the network's own function through one
+   `cta()` wrapper (the table in the reference); on MRAID networks, wait until MRAID is ready
+   before calling anything on it. The end card keeps the board visible behind the name and button.
+5. **One file, no network.** Every image, sound, font and data file is imported so the bundler
+   inlines it as a data URI; nothing is loaded by path at runtime (`Assets.load('/assets/hero.png')`
+   fetches, and on the network that fetch is a blank frame). No CDN, web font URL, analytics or
+   `fetch`. Build with a separate config (`vite.playable.config.ts`: inline every asset, no module
+   preload, one chunk, then the script and styles inlined into the HTML) into `dist-playable/`,
+   which goes in `.harnessignore` so it never ships to Funpixel. Google's exit script and TikTok's
+   SDK are the two sanctioned external scripts, and only for their own network.
+6. **Both orientations.** Lay out from the live size on every resize; a playable cannot ask the
+   player to rotate.
+7. **Weigh it.** `npx @funpixel/tools playable --network <network>` weighs the file against the
+   ceiling (a warning inside the last 10%) and names every leftover URL, each a runtime fetch that
+   would blank it.
+   Over budget, cut in this order: music, the number of sprites (reuse with tint and scale),
+   resolution (draw at the displayed size), photographic backdrops (a gradient and two shapes in
+   code), web fonts. The pointer hand, the feedback on the core verb and the call to action are
+   the ad itself, so they are the last things to cut.
+8. **Play it offline on a phone frame.** `funtools playable` does the portrait half: offline at
+   390x844 with touch on, the network's function stubbed, the call to action fired once, after the
+   reward. Look at 844x390 yourself. Then run it through the network's own preview tool before
+   submitting.
+
+## Worked example
+
+A colour-sort game, for AppLovin and Meta:
+1. Meta's single-file ceiling (2 MB) is the budget; AppLovin's 5 MB then fits too.
+2. The move: pour one bottle into its match. `src/playable.ts` loads level 3 with the seed fixed so
+   the matching pour is one tap away; a hand pulses over the source bottle on the first frame.
+3. The first build is 3.4 MB: a 1.1 MB music loop, a 900 KB photographic backdrop, twelve
+   separate bottle sprites. Music goes, the backdrop becomes a gradient drawn in code, and the
+   bottles become one tinted sprite through `optimize pack-atlas` and `optimize compress`: 1.46 MB.
+4. The grep finds `url(/fonts/title.woff2)` in the CSS: the display font was loaded by path. It is
+   imported instead, and subset to the six letters of the title: 18 KB.
+5. `cta()` calls `FbPlayableAd.onCTAClick()` in the Meta build and `mraid.open(storeUrl)` in the
+   AppLovin build. Offline at 390x844, the stub fires once, a beat after the pour's burst.
+
+## Common mistakes
+
+- A logo or title screen first: the player is gone before the board appears.
+- An animation to watch instead of a board to touch.
+- The call to action on the first tap, or before the reward: networks reject a store redirect on
+  the first touch.
+- Assets loaded by path: fine in the browser, a blank frame on the network.
+- Building to 5 MB when the campaign includes Meta's 2 MB single file.
+- Sound playing before the first touch.
+- `dist-playable/` shipped to Funpixel because `.harnessignore` did not name it.
+
+Where this comes from: ours, from the ad networks' own published rules (networks.md).