Repository navigation
feat: ship the BirdsBirdBirds challenge #12
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
9d04d01
feat: add the birdsbirdbirds manifest, icon, intro, skill, and README
claude 52e1810
chore: match the shared intro.md lint ignore wording
claude 3ac959c
feat: add the birdsbirdbirds checker for bird.json
claude 378f469
feat: add the birdsbirdbirds page server, hooks, and draw-and-fly page
claude 5e765be
fix: let the keyframes alone place the bird so it stays on screen
claude b5a363d
fix: harden birdsbirdbirds file reads, transform units, and labels
claude f1cbee8
fix: accept joiners and stacked marks in names, refuse swapped-in sym…
claude 981285f
fix: drop inline styles from the page CSP and reject more invisible c…
claude 6bfa46a
chore: merge main into claude/issue-7-birdsbirdbirds
claude 0886982
feat: open the bird page at start and advance draw-bird when the bird…
claude d1d91ee
fix: count only a complete bird.png as a save, so a half-written file…
claude e5bca49
chore: merge main into claude/issue-7-birdsbirdbirds
claude aecb0cc
fix: name the safety check in the save message and recheck bird.png o…
claude File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,131 @@ | ||
| # BirdsBirdBirds | ||
|
|
||
| Draw a bird in the browser, tell Pi how it should fly, and watch it cross the | ||
| sky. Pi writes the flight as a CSS keyframe animation in `bird.json`, and a | ||
| checker lets only safe animations through to the page. The bird can then be | ||
| published to the booth screens as a `birds-v1` gallery item. | ||
|
|
||
| ## Files | ||
|
|
||
| | File | Purpose | | ||
| | --- | --- | | ||
| | `challenge.json`, `plugin.json` | Manifest and Agent Plugin metadata | | ||
| | `intro.md`, `icon.txt` | Intro screen text and tile icon | | ||
| | `skills/start-challenge/SKILL.md` | The guide Pi follows | | ||
| | `extension.mjs` | Pi extension: tells Pi about each saved drawing (see below) | | ||
| | `bird-watcher.mjs` | Watches the workspace for a new `bird.png` | | ||
| | `check-bird.mjs` | Checks `bird.json`; `node check-bird.mjs [path]` | | ||
| | `server.mjs` | Local page server on `127.0.0.1:4322` | | ||
| | `workspace-file.mjs` | Reads `bird.json` and `bird.png` only as capped regular files | | ||
| | `setup`, `cleanup` | Start and stop the server (hooks in `hooks/`) | | ||
| | `page/` | The drawing canvas and the sky | | ||
|
|
||
| There is no `install` hook: the package, extension included, has no | ||
| dependencies beyond Node. | ||
|
|
||
| ## How steps advance | ||
|
|
||
| Pi opens the drawing page with `show_preview` as soon as the challenge | ||
| starts. The extension watches the workspace and sends Pi a hidden message | ||
| starting with `[birdsbirdbirds]` when the participant saves a new `bird.png`. | ||
| It starts a turn when Pi is idle and follows the current turn otherwise. The | ||
| skill then reads the drawing and reports `draw-bird`, so nobody has to tell | ||
| Pi they saved. A `bird.png` already in the workspace when Pi starts, and a | ||
| save with the same content, send nothing. Pi writes `bird.json` and runs the | ||
| checker itself, so `animate` needs no message. | ||
|
|
||
| The server listens on port 4322. Set `BIRDSBIRDBIRDS_PORT` to use another | ||
| port, though the skill and the challenge expect 4322. | ||
|
|
||
| ## Run without boothstrap | ||
|
|
||
| Needs Node 26 and a `GEMINI_API_KEY`. Follow the standalone steps in | ||
| boothstrap.sh's `docs/authoring-challenges.md` to install Pi and load the | ||
| package as an Agent Plugin, then: | ||
|
|
||
| ```sh | ||
| challenge=/absolute/path/to/birdsbirdbirds | ||
| mkdir /tmp/my-bird && cd /tmp/my-bird | ||
| "$challenge"/setup | ||
| ``` | ||
|
|
||
| Open `http://127.0.0.1:4322/`, then start Pi in the same folder: | ||
|
|
||
| ```sh | ||
| pi --model google/gemini-3.8-flash \ | ||
| --skill "$challenge"/skills/start-challenge/SKILL.md \ | ||
| --extension "$challenge"/extension.mjs \ | ||
| '/skill:start-challenge' | ||
| ``` | ||
|
|
||
| When done: | ||
|
|
||
| ```sh | ||
| "$challenge"/cleanup | ||
| ``` | ||
|
|
||
| `cleanup` stops the server and removes `.birdsbirdbirds/`; it leaves | ||
| `bird.png` and `bird.json` alone. Without boothstrap there is no | ||
| `report_step` or `publish_gallery_item`, so the skill names each finished | ||
| step and skips the gallery. | ||
|
|
||
| ## Gallery payload | ||
|
|
||
| An item is published with kind `bird` and renderer `birds-v1`. The image is | ||
| `files[0]`, a transparent PNG named `bird.png`. The payload is `bird.json`: | ||
|
|
||
| | Field | Type | Rules | | ||
| | --- | --- | --- | | ||
| | `bird_name` | string | At most 40 characters of visible text (see below) | | ||
| | `origin` | string | At most 60 characters of visible text (see below) | | ||
| | `animation.css_keyframes` | string | At most 4096 bytes; one `@keyframes` rule (see below) | | ||
| | `animation.animation_name` | string | Matches `fly_[A-Za-z0-9_-]{1,60}`; equals the keyframes name | | ||
| | `animation.duration` | string | Seconds, `2s` to `60s`, such as `14s` | | ||
| | `animation.timing_function` | string | `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`, or `cubic-bezier(x1, y1, x2, y2)` with plain numbers and x1, x2 from 0 to 1 | | ||
|
|
||
| `bird_name` and `origin` hold at least one visible letter, digit, symbol, or | ||
| punctuation mark, and at most 4 accent marks stacked on a letter. They hold | ||
| no control characters, no format characters (Unicode `Cf`, such as bidi | ||
| controls, zero-width spaces, soft hyphens, and tag characters U+E0000 to | ||
| U+E007F), no line or paragraph separators (U+2028, U+2029), and no blank | ||
| letters: the Hangul fillers (U+115F, U+1160, U+3164, U+FFA0) and the braille | ||
| blank (U+2800). The zero-width non-joiner and joiner (U+200C, U+200D) and the | ||
| emoji variation selector (U+FE0F) are allowed, since real names and emoji | ||
| need them. | ||
|
|
||
| The `fly_` prefix keeps a bird's keyframes from colliding with CSS keywords | ||
| or with the sky page's own `flap` keyframes. | ||
|
|
||
| The keyframes alone place the bird. In the sky page the bird's wrapper sits | ||
| at `top: 0; left: 0`, so `translate(x, y)` is measured from the top-left | ||
| corner of the sky with no extra offset. A gallery renderer should place the | ||
| bird the same way. | ||
|
|
||
| Payloads come from `check-bird.mjs`, but a display should still load | ||
| `css_keyframes` only as CSS text, as the sky page does with a constructed | ||
| `CSSStyleSheet` (`replaceSync`), and set names with `textContent`, never as | ||
| HTML. | ||
|
|
||
| ## What the checker allows | ||
|
|
||
| `animation.css_keyframes` must be exactly one `@keyframes <animation_name>` | ||
| rule holding frames. Each frame selects `from`, `to`, or a percentage from 0% | ||
| to 100%. | ||
|
|
||
| - Properties: `transform`, `opacity`, and `animation-timing-function`. | ||
| - `transform` values: `none`, or these functions with comma-separated | ||
| arguments, where only 0 may go without a unit: | ||
| - `translate`, `translateX`, `translateY`, `translate3d`: lengths in `vw`, | ||
| `vh`, `px`, `em`, `rem`, or `%`; the z length of `translate3d` can't be | ||
| `%`. | ||
| - `rotate`, `rotateZ`, `skew`, `skewX`, `skewY`: angles in `deg` or `turn`. | ||
| - `scale`, `scaleX`, `scaleY`: plain numbers with no unit. | ||
| - `opacity`: a number from 0 to 1. | ||
| - `animation-timing-function`: the same values as `timing_function`. | ||
| - Numbers are plain decimals such as `1000px`, never exponents like `1e3px`. | ||
| Units are lowercase. | ||
| - The keyframes name starts with `fly_`. | ||
| - Rejected: `url(`, `@import`, a second at-rule, backslash escapes, quotes, | ||
| `<`, comments, `!important`, unbalanced braces, text after the rule, and a | ||
| name without the `fly_` prefix. | ||
| - The whole `bird.json` is at most 8192 bytes. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| // Watches the workspace for the participant's Save on the drawing page, so | ||
| // Pi hears about a new bird.png without being told. | ||
| // | ||
| // fs.watch fires several events per write, and the page server saves | ||
| // bird.png through a temp file and a rename, so events are debounced and the | ||
| // callback fires only for content that differs from the last it fired for. | ||
| // A bird.png already there when watching starts counts as seen, so a | ||
| // restarted watcher stays quiet about it. | ||
|
|
||
| import { createHash } from 'node:crypto' | ||
| import { watch } from 'node:fs' | ||
| import path from 'node:path' | ||
|
|
||
| import { isCompletePng, MAX_PNG_BYTES } from './server.mjs' | ||
| import { readWorkspaceFile, RefusedFileError } from './workspace-file.mjs' | ||
|
|
||
| export const DEFAULT_DEBOUNCE_MS = 200 | ||
|
|
||
| const DRAWING_FILE = 'bird.png' | ||
|
|
||
| /** | ||
| * Watches `workspace` (absolute) until `stop()` is called, calling | ||
| * `onBirdSaved()` when bird.png appears or gets new content. Errors from | ||
| * reading or watching go to `onError(error)`; a missing, symlinked, piped, or | ||
| * oversized bird.png is not an error, just not a save. The watcher never | ||
| * keeps the process alive. Returns `{ stop }`. | ||
| */ | ||
| export function watchWorkspace({ workspace, onBirdSaved, onError, debounceMs = DEFAULT_DEBOUNCE_MS }) { | ||
| if (!path.isAbsolute(workspace)) throw new Error(`workspace must be an absolute path, got ${JSON.stringify(workspace)}`) | ||
|
|
||
| const drawingPath = path.join(workspace, DRAWING_FILE) | ||
| let lastHash = drawingHash(drawingPath) | ||
| let timer | ||
| let stopped = false | ||
|
|
||
| /** Reports bird.png when its content is new. */ | ||
| const checkDrawing = () => { | ||
| const hash = drawingHash(drawingPath) | ||
| if (hash === undefined || hash === lastHash) return | ||
|
|
||
| lastHash = hash | ||
| onBirdSaved() | ||
| } | ||
|
|
||
| /** Checks bird.png once its events have been quiet for `debounceMs`. */ | ||
| const scheduleCheck = () => { | ||
| clearTimeout(timer) | ||
| timer = setTimeout(() => { | ||
| if (stopped) return | ||
| try { | ||
| checkDrawing() | ||
| } catch (error) { | ||
| onError(error) | ||
| } | ||
| }, debounceMs) | ||
| timer.unref() | ||
| } | ||
|
|
||
| const watcher = watch(workspace, { persistent: false }, (_eventType, fileName) => { | ||
| // Some platforms leave out the name; then bird.png may have changed. | ||
| if (fileName === null || String(fileName) === DRAWING_FILE) scheduleCheck() | ||
| }) | ||
| watcher.on('error', onError) | ||
|
|
||
| return { | ||
| /** Stops watching and cancels a pending check; safe to call more than once. */ | ||
| stop() { | ||
| stopped = true | ||
| watcher.close() | ||
| clearTimeout(timer) | ||
| }, | ||
| } | ||
| } | ||
|
|
||
| /** | ||
| * Hex SHA-256 of bird.png, or undefined when it is missing, refused, or not a | ||
| * complete PNG yet (a write caught halfway must not count as a new drawing). | ||
| */ | ||
| function drawingHash(drawingPath) { | ||
| let bytes | ||
| try { | ||
| bytes = readWorkspaceFile(drawingPath, MAX_PNG_BYTES) | ||
| } catch (error) { | ||
| if (error.code === 'ENOENT' || error instanceof RefusedFileError) return undefined | ||
| throw error | ||
| } | ||
|
|
||
| if (!isCompletePng(bytes)) return undefined | ||
|
|
||
| return createHash('sha256').update(bytes).digest('hex') | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| { | ||
| "id": "birdsbirdbirds", | ||
| "title": "BirdsBirdBirds", | ||
| "tagline": "Draw a bird and watch it fly across the sky.", | ||
| "icon": "icon.txt", | ||
| "type": "terminal", | ||
| "agent": "pi", | ||
| "model": "google/gemini-3.8-flash", | ||
| "vault_services": ["gemini"], | ||
| "points": 150, | ||
| "estimated_minutes": 10, | ||
| "learning_objectives": [ | ||
| "describing a task so an agent can do it", | ||
| "checking an agent's work with a script" | ||
| ], | ||
| "featured_tech": ["Gemini", "Pi", "CSS animation"], | ||
| "intro": "intro.md", | ||
| "steps": [ | ||
| { | ||
| "id": "draw-bird", | ||
| "title": "Draw your bird", | ||
| "hint": "Draw a bird on the page and press Save.", | ||
| "done_when": "The file bird.png exists in the workspace." | ||
| }, | ||
| { | ||
| "id": "animate", | ||
| "title": "Give it a flight", | ||
| "hint": "Tell Pi how your bird should fly.", | ||
| "done_when": "bird.json exists in the workspace and passes check-bird.mjs." | ||
| }, | ||
| { | ||
| "id": "fly", | ||
| "title": "Watch it fly", | ||
| "hint": "Watch your bird cross the sky and tell Pi how it looks.", | ||
| "done_when": "The participant watched the bird fly and said so." | ||
| } | ||
| ], | ||
| "gallery": { | ||
| "kinds": ["bird"] | ||
| } | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.