Shotmap Agent build log

Shotmap Agent is a narrow, forkable pre-production agent for short-form generative video. Give it a rough 15, 30, or 45 second brief and it returns a timed shot sequence, a continuity ledger, independently reusable prompts, a ranked risk pass, and an assembly checklist.

• Try the live demo
• View the source
• Read the v0.1.0 release

Why this exists

Generative-video workflows are moving from isolated clips toward storyboard-driven sequences. The hard part is no longer producing one attractive prompt. It is preserving the same subject, prop, wardrobe, light, geography, and screen direction across several shots while still giving every shot a useful camera and motion instruction.

Shotmap Agent packages that continuity work into a single production artifact. It is deliberately not a chatbot. The interface is a compact workbench for channel, duration, aspect ratio, visual direction, continuity anchors, and hard constraints.

The agent loop

Every run follows five stages:

1. Audit the brief and make only material assumptions.
2. Extract a continuity ledger for subject, wardrobe, props, location, lighting, palette, geography, and screen direction.
3. Build a five-to-seven-shot sequence whose timings add up to the requested duration.
4. Synthesize per-shot prompts that repeat the anchors each generation needs.
5. Review continuity breaks, weak transitions, timing pressure, and ambiguous motion before returning the packet.

The response has a stable shape: Shot map, Continuity ledger, Prompt packet, Risk pass, and Production checklist. That makes the result easy to review, copy into image-to-video tools, or adapt in a fork.

BYOK by construction

The visitor chooses a supported provider model and supplies their own API key. The key lives only in browser sessionStorage, is read fresh for each request, and travels in the x-provider-key header to the same-origin /api/run route. The route constructs the provider client for that request, streams the result, and redacts the key from every error path.

Visitor key
  -> browser sessionStorage
  -> x-provider-key on same-origin /api/run
  -> selected provider client
  -> streamed production packet

There is no server-side fallback key, database write, cookie, query-string transport, analytics sink, or author-funded inference path. No author API key was used to build or test this release.

Model and SDK baseline

The scaffold keeps its verified multi-provider registry intact. OpenAI GPT-5.5 runs through the Responses API; the same frozen registry also offers Claude Sonnet 4.6 and Gemini 3.5 Flash. Current OpenAI guidance identifies GPT-5.6 as the flagship while continuing to document GPT-5.5 as a supported migration baseline, so this release preserved the starter contract rather than changing an out-of-lane model file.

The lockfile resolves AI SDK 6.0.208, @ai-sdk/openai 3.0.74, @ai-sdk/anthropic 3.0.85, @ai-sdk/google 3.0.83, Next.js 16.2.9, and React 19.2.7.

Interface decisions

The first viewport is the actual tool. Desktop keeps the production brief and generated packet side by side; mobile stacks the same workflow without hiding controls. Two realistic presets make the blank state useful, while the empty output timeline previews the six-beat planning rhythm without pretending a generation has already happened.

The visual system stays close to the starter: restrained dashboard typography, dashed production dividers, compact controls, and the existing model picker and key gate. The generic conversation UI was removed from the primary workflow, but the frozen streaming transport and stable BYOK test hooks remain unchanged.

Release evidence

The release commit is 46128bb. Local gates passed Biome, TypeScript, the Next.js production build, and the unchanged Playwright no-leak test. GitHub Actions passed for the same commit in CI run 29071357199.

The browser test proves that a sentinel key is stored only in sessionStorage, appears only in the same-origin x-provider-key request header, never reaches localStorage, cookies, URLs, request bodies, or the DOM, and still produces a rendered streamed response. The production deployment returned HTTP 200 before this build log and catalog row were published.

Fork it

Clone the repository, install with Bun, and run the workbench locally:

git clone https://github.com/dvnc-labs/shotmap-agent.git
cd shotmap-agent
bun install
bun dev

The most useful forks keep the BYOK route frozen and change the planning specialty: product cinematography, property tours, food sequences, event recaps, or narrative previz. The narrow loop is the point: one brief in, one production-ready packet out.