Set the scene.
Collect the finished film.

One runner. Two ways in.

For an agent that needs a file on disk, run bounce locally and use HTTP. For an agent controlling this browser, call window.bounceAgent in the runner tab. The published site supports the browser API; the REST service is provided by npm start.

npm start
# Open http://127.0.0.1:4173/?agent=1
# Keep that runner tab visible while recording.

// In the /?agent=1 runner tab:
window.bounceAgent.capabilities()
window.bounceAgent.status()

Get a video onto disk.

Save the job JSON below as job.json. The included Node.js 20+ helper accepts your two local images, submits the job, waits for completion, saves the video, and releases the server’s copy only after the file is written.

node scripts/agent-record.mjs --job job.json \
  --image ./images/first.png --image ./images/second.jpg \
  --out ./renders

On Windows PowerShell, put this command on one line. Alternatively, include two image URLs or data URLs in job.json and omit both --image arguments.

A complete, portable job.

This example includes every configurable field. Replace the two example image URLs with your own direct PNG, JPEG or WebP URLs, or let the helper embed your local files. The first image is the level; the second is the image underneath it when nextImage is enabled.

Loading the current job contract…

Validate before you record.

const response = await fetch('http://127.0.0.1:4173/api/v1/validate', {
  method: 'POST', headers: {'Content-Type': 'application/json'},
  body: JSON.stringify(spec)
});
const validation = await response.json();
if (!response.ok) throw new Error(JSON.stringify(validation.error));
// {valid: true, spec: normalizedSpec}

Every setting, in one place.

Omitted optional fields use the defaults shown below. Unknown fields and out-of-range values are rejected, so mistakes are caught before a video starts. The reference is generated from the same contract the runner and server validate.

You choose the available powers.

Set powerups to an array of exact IDs. Agent jobs use this explicit selection instead of the normal progressive unlock plan. Include only the powers you want; [] disables all powerup spawns. The timed interval, ball growth limit and low-FPS multiplication guard still apply.

Speed and other personal abilities apply to the ball that collected them. Piercing still bounces off letter walls. Growth powers can be replaced when the configured population limit is reached.

Local REST API.

Base URL: http://127.0.0.1:4173/api/v1. Start npm start and keep one runner tab connected. Check GET /api/v1 for the current capabilities and worker.online before submitting.

For safe submit retries, send an Idempotency-Key header unique to that intended job. Keep the returned job ID. Poll that ID instead of blindly submitting again if a request times out.

Loading workflow…

The local service binds to loopback. It is for a trusted agent on this computer, and is not an authenticated public render service. Cross-origin browser requests may be refused; run HTTP requests from Node or another local process. Hosted static pages do not provide these REST endpoints.

A direct API in the runner.

These methods are available as window.bounceAgent on the playground. For automation, use /?agent=1 so it begins idle. run(spec) returns a job status immediately while preparation and recording proceed asynchronously.

const api = window.bounceAgent;
const validation = api.validate(spec);
if (!validation.valid) throw new Error(JSON.stringify(validation.error));
const started = api.run(spec); // prepares in the background
// Poll api.status() until state === 'complete'.
const video = api.getVideo(); // Blob + metadata + object URL
api.download(); // browser-controlled download
// After confirming your file was saved:
await api.release();
// Await your next explicit api.run(nextSpec).

WebMCP, where supported.

Browsers exposing document.modelContext or navigator.modelContext can offer these tools to an agent: bounce_get_capabilities, bounce_validate_job, bounce_start_job, bounce_job_status, bounce_pause_job, bounce_resume_job, bounce_stop_job, bounce_cancel_job, bounce_download_video and bounce_release_video. Support is optional; use the direct browser API or local REST when unavailable.

A job ends. The runner waits.

With recording.duration: "level", recording ends after the image clears and the phrase completes its hold and exit animation. A fixed number records for that many seconds; 0 records until stopped or the safety timeout is reached. No job automatically launches another job or advances into another recorded level.

Recover without losing a result.

• Validation errors identify the field to fix. Run validation before starting a long recording.
• If no worker is online, open the local runner. Keep only one local runner tab connected.
• HTTP 409 means a conflicting active job or lifecycle action. Poll the existing job rather than creating duplicates.
• A failed or cancelled job has no downloadable video. Read error, correct the problem and submit a new job.
• Downloads are retained in memory. Save before closing the runner, restarting the server or releasing a result. The server keeps at most three completed recordings within its video memory budget.
• Cancel a stuck job, wait for a terminal state, then release it. To stop early and keep a clip, use the browser stop() method.

{
  "error": {
    "code": "INVALID_JOB",
    "message": "A description of the problem",
    "path": "config.blockSize"
  }
}