Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 131 additions & 0 deletions birdsbirdbirds/README.md
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.
91 changes: 91 additions & 0 deletions birdsbirdbirds/bird-watcher.mjs
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)
Comment thread
theycallmeswift marked this conversation as resolved.
Resolved
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')
}
41 changes: 41 additions & 0 deletions birdsbirdbirds/challenge.json
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"]
}
}
Loading
Loading