Smoke test required

...

← All documentation

Documentation

Product Spec

**Status:** active · last reviewed 2026-05-03

source: docs/grand-plan/PRODUCT_SPEC.md

The detailed what and how of the Studio (primary), the Dashboard (secondary), and the platform layer they live on. Reads after MANIFESTO.md. Pairs with ARCHITECTURE.md, ART_DIRECTION.md, GTM_PLAN.md, and the new INTERACTIVE_ASSETS.md.

Status: locked 2026-04-27 (afternoon), revised 2026-04-28 (evening) with the canvas-as-first-class-unit + procedural-fill + collective-showcase scope expansion, re-locked 2026-04-30 evening per VISION_REVISION_2026-04-30.md: terminology aligned to Ensemble / Studio / Canvas / Showcase, tier limits set to 1+1 (free) / 1+9 (pro), sprite-walk + character creator pulled in from v1.5 to v1.0. Earlier versions in git. Bar: Apple-quality, no compromise. Every spec line is a contract.

2026-04-30 vision lock in one paragraph. Four words carry the product. Ensemble is the overworld — the public place a visitor lands in. Studio is the editor app where creators author. Canvas is a creator’s place inside their Studio: anything they can imagine within the sprite-game world, wrapping games, websites, embeds, visual elements placed via toolbar or Claude. Showcase is the ONE canvas a creator chooses to publish to Ensemble — the doorway visitors walk through from the overworld. Every creator gets exactly one Studio. Free tier = 1 Showcase + 1 extra (2 canvases total). Pro tier = 1 Showcase + 9 extras (10 canvases total). v1.0 ships sprite-walk inside the canvas: visitors steer a sprite, walk up to components, press X (or click) to interact. The multi-tenant overworld — walking between Studios — remains v1.5 per V1_5_WALKABLE_WORLD.md. Procedurally-filled first canvas keeps the world lived-in starting at user #1.

Terminology lock (binding). Every doc, every UI string, every variable name where copy bleeds in:

Term Definition Cardinality
Ensemble The overworld map. The PLACE itself. The world a visitor lands in. One
Studio The editor app where creators author canvases. 1 per creator
Canvas A creator’s place inside their Studio. Anything they can imagine within the sprite-game world. 2 (free) / 10 (pro) per creator
Showcase The ONE canvas a creator chooses to publish to Ensemble. Visitors see it from the overworld and walk into it. 1 per creator

Anti-glossary: “Room” is no longer used as the public place — it’s Canvas now. “Workshop” is no longer used as the creator’s surface — that’s the Studio. “Workshop drawer” remains as the name of the inspiration drawer inside the Studio (UI element, not surface name).


1. Two-surface architecture

Ensemble has two top-level destinations. Their priorities have flipped from the morning spec.

Surface Role Status Voice Default state
Ensemble Public collective showcase. The work everyone created together. v1.0 = static grid of canvases; v1.5 = walkable navigable world (per STAGED_PLATFORM.md). First impression Lived-in, alive. Never empty (procedural fill ensures this). Grid/world populated with canvases from across the community.
Studio Creator work area. Where canvases are authored + curated. The editor app. Lead pitch for sign-up Playful, warm, character-led. Pixel sprites in vector environments. CRT overlay. Procedurally-filled first Canvas (seeded from signup q’s + GitHub) with the Workshop drawer open for editing and a walkable sprite already on the floor.
Dashboard Secondary surface for power users running multi-agent operations. Discoverable, not the marketing pitch Dark, dense, opinionated. JetBrains Mono details. Widget grid + control deck (existing, preserved).

Both surfaces share: - The bronze-on-ink palette + 17 alternative themes. - The 6 funky backgrounds. - The same data model. - One-key handshake (the /pair flow).

Both surfaces do not share: - Voice. Studio is approachable; Dashboard is for operators. - Priority. Studio is the homepage; Dashboard is found via Settings or a footer link.

Top nav (4-slot Apple-quality, locked 2026-04-27 evening with the staged-platform pivot + view-toggle unification vision):

[logo] Ensemble · Dashboard · Settings · Docs
  • Ensemble (default landing — /index.html) — the public collective showcase: “the work everyone created together.” v1.0 (Chunk 5 public flip): a beautiful static grid of published Canvases (per §3.6.6) with light filtering (newest / featured / random), pagination, and click-any-canvas-to-fly-in. A “Make your own” / “See the Studio” CTA lives in the page header for visitors who want to author. The old manifesto / elevator-pitch copy lives below the grid as a secondary section, not as the page’s purpose. v1.5+: the two surfaces unify behind a zoom toggle — zoom out for the multiplayer Ensemble city (overview), zoom in for your controllable Studio sprite (walking your sprite inside a single canvas, first-person).
  • Dashboard (/dashboard.html) — your operations surface. Inside lives the agent-management depth: project tiles, control deck, command palette, kill switch. Linear / Notion / Figma pattern: top nav has destinations, depth lives inside the page.
  • Settings (/settings.html) — preferences, pairing, themes, billing, account, Studio publish settings.
  • Docs (/docs.html) — help, API reference, runbooks.

/studio.html retains its URL for shareable links (e.g. ensemble.so/studio/<handle>) and is reachable via the “See the Studio” CTA on the Ensemble page. Top-nav highlight: when a visitor is on Studio, the “Ensemble” slot is active (Studio nests inside Ensemble conceptually). v1.5 unifies them visually behind the zoom toggle.

Inside Dashboard: projects (current projects.html content), controls (live agent control surface — kill switch, autopilot fire, mode toggles), commands (command palette / shortcut reference). Three sub-surfaces accessible via tabs or sidebar.

Why 4 slots: Apple’s typical desktop-app top-nav ceiling is 4-6 destinations. The user articulated the floor as Ensemble + Dashboard + Settings; Docs stays because new-user “how does this work” lookup is too important to bury in the footer. The view-toggle unification of Ensemble + Studio resolves the question of whether they're separate destinations: they're the same canvas at different zoom levels, just with separate URLs for shareability.

Renamed from prior spec: the old “Operator” nav slot becomes “Dashboard”; the old “Map” tab becomes the public Ensemble surface (with the navigable pixel-world view shipping in v1.5 as the zoom-out mode).


2. The Dashboard (preserved, demoted in nav)

The dashboard work shipped through Phases 1–2.5 stays exactly as it is. Same widget grid, same control deck, same kill switch. Functionally unchanged. What changes:

  • It’s no longer at /index.html. It lives at /dashboard.html (per §1’s nav).
  • The Ensemble collective showcase takes the /index.html slot; Studio lives at /studio.html.
  • “Dashboard” appears in the nav as a secondary destination rather than as primary navigation.
  • The /pair page works for both surfaces — one token, both surfaces unlocked.

For users who currently live in the dashboard: they bookmark /dashboard.html once and continue as before. Zero functional regression.


3. The Studio — primary front door

The Studio is the editor app where creators author canvases. Every creator has exactly one Studio; inside it live their canvases (1 Showcase + 1 extra on free; + 9 extras on Pro). This is the rewritten section, replacing the morning spec’s orchestra-as-default model and the 04-28 “Room/Canvas” split.

3.1 Core concepts (refined 2026-04-30)

Concept What it is
Studio The editor app where the creator authors canvases. One per creator. Private. Holds the toolbar, Claude chat drawer, Workshop drawer, props panel, code editor.
Canvas A creator’s place. The editable + viewable unit. Holds components, theme, sprite walk-floor, sound layer. Default seeded by procedural fill from signup q’s + GitHub (if connected); never empty. Dimensions: 1920×1080 nominal stage; viewport-fit rendering. Free tier = 2 canvases (1 Showcase + 1 extra); Pro tier = 10 canvases (1 Showcase + 9 extras).
Showcase The ONE canvas a creator chooses to publish to Ensemble. Exactly one Showcase per creator at any time; setting a new Showcase auto-clears the prior. The doorway visitors walk through from the overworld.
Sprite-walk (v1.0) The visitor steers a customizable sprite through the canvas. 8-direction walk physics, camera-follow, collision against components flagged solid, interaction prompts when within radius of components flagged interactable. See SPRITE_WORLD.md.
Character creator (v1.0) First-run UI where the new user customizes their sprite (body / hair / outfit palette). Per-user sprite descriptor persisted; reusable across visits.
Component flags Per-component metadata governing sprite-walk behavior: walkable_through (sprite passes over, e.g. a rug), solid (sprite collides, e.g. a wall), interactable (sprite gets prompt within radius). Stored on each component in the canvas schema.
Procedural fill The first-canvas-from-zero pipeline. Inputs: signup answers + GitHub repos/topics (if connected) + sensible defaults. Output: a populated Canvas the user can keep, edit, or wipe. Sprite-aware: components are placed with walk-paths in mind. Full spec in PROCEDURAL_FILL.md; real implementation lands in Chunk 5.
Workshop drawer A left-side drawer of inspiration content inside the Studio: example components, asset packs, sample wirings, premade scenes. Always discoverable; closeable; never forced. UI element, not a surface — the Studio is the surface.
Component Anything inside a Canvas. Live, static, interactive (with first-class click-to-launch), embeds, custom-code. Each carries the three component flags above. See INTERACTIVE_ASSETS.md for click-to-launch detail.
Sprite A pixel-art character or object. Lives in the asset library. The visitor’s own sprite (from the character creator) is distinct from component sprites authored into the canvas.
Slot (Optional) A position in the Canvas mapped to a chat. Opt-in — the user chooses if they want this connection rather than getting it forced.
Door A component class. Click (or sprite-proximity + interact) → travel to another canvas (v1.0: across your own canvases; v1.5: across Studios via the multi-tenant overworld).
Living canvas A mode where Claude composes the scene from your work data. Daily / mood / weekly views. (Distinct from procedural fill: Living Canvases require real activity; procedural fill seeds day-zero.)
Bot sprite A component-sprite with a defined personality + your-work context. Visitors chat with it via Claude.
Edit mode Owner-only. Reveals palette, code editor, Claude chat drawer, Workshop drawer, props panel, animation timeline. Sprite-walk pauses; the sprite parks at the door so the owner can author without the camera following.
View mode Default for everyone (incl. owner). Renders the Canvas with its sprite-walk + interactions live.

3.1a Tier limits — canvas count (locked 2026-04-30)

Tier Showcase (public) Extra canvases (drafts/private) Total
Free 1 1 2
Pro 1 9 10
Team (post-launch) 1 per member unlimited unlimited

Enforcement points:

  • POST /canvas (create) — tier check + count check; reject with HTTP 402 (Payment Required) + upgrade-prompt if at limit.
  • Studio UI — disable “New canvas” button when at limit; show “Upgrade for more” inline.
  • Showcase setter — exactly one canvas per creator can hold the Showcase flag. Setting a new one auto-clears the prior in a single transaction.

The 1+9 Pro number is locked pending Kevin’s final call (open question §6.1 in VISION_REVISION_2026-04-30.md). All code, copy, and tests treat 1+9 as canonical until that decision lands.

3.2 Default state — procedurally-filled first Canvas + Workshop drawer + walking sprite

Revised 2026-04-30 evening: the first-time experience is populated, walkable, and yours. After the character-creator step (3.2a below), the new user lands in their Studio with a single Canvas (the future Showcase) already filled by the procedural-fill pipeline (see PROCEDURAL_FILL.md). Inputs: signup answers + GitHub repos/topics (if connected) + sensible defaults. Output: a Canvas with 4–8 components reflecting their stated interests + work — anchored just enough to feel personal, sparse enough to invite editing. Their custom sprite stands by the entrance ready to walk. The Workshop drawer is open by default beside the populated stage, so the first action can be “walk around what’s here,” “edit what’s here,” or “wipe and start fresh” — each one click away.

3.2a First-run flow (sprite-walk era, locked 2026-04-30)

  1. Sign in. GitHub OAuth or email magic-link.
  2. Character creator. Pick body / hair / outfit. Tight palette (8 body × 6 hair × 8 outfit = 384 combos for v1.0; art direction pending Kevin’s call per VISION_REVISION_2026-04-30.md §6.3 + §6.4). Save → sprite descriptor persisted on the user record.
  3. Procedural fill runs. Background job seeds the first Canvas with 4–8 components.
  4. Studio opens. Sprite stands at the door. Camera centers on sprite. Workshop drawer open. A 2-second hint reads “WASD or arrow keys to walk · X or click to interact” then fades.
  5. Walk + interact. The user explores the populated canvas with their sprite. Click-to-launch / link / embed / read all fire on sprite-proximity + X (or click).
  6. Edit when ready. “Edit” button top-right pauses the sprite, opens the props panel, makes everything author-editable.

The ASCII layout below shows the Workshop drawer + stage relationship; in the procedurally-filled state, the stage is populated and the sprite is on the floor:

┌─────────────────────────────────────────────────────────┐
│  ╔═════════════════════════════╗                        │
│  ║ WORKSHOP                ✕  ║   ← Drawer, default open
│  ║                              ║                        │
│  ║  Get started               ║                        │
│  ║  ─────────                 ║                        │
│  ║  ▣ Drag a sprite           ║   [empty stage,         │
│  ║  ▣ Add an arcade cabinet   ║    subtle grid,         │
│  ║  ▣ Connect to a friend's   ║    cursor visible]      │
│  ║    canvas                  ║                        │
│  ║                              ║                        │
│  ║  Examples                   ║                        │
│  ║  ─────────                 ║                        │
│  ║  ⚏ Music ensemble (orch.)  ║                        │
│  ║  ⚏ Game arcade             ║                        │
│  ║  ⚏ Personal library        ║                        │
│  ║  ⚏ Gallery                  ║                        │
│  ║  ⚏ Workshop (literal)      ║                        │
│  ║                              ║                        │
│  ║  Asset packs                ║                        │
│  ║  ─────────                 ║                        │
│  ║  ▦ Music instruments       ║                        │
│  ║  ▦ Arcade machines          ║                        │
│  ║  ▦ Books + bookshelves      ║                        │
│  ║  ▦ Plants + props           ║                        │
│  ║  ▦ Doors + portals          ║                        │
│  ╚═════════════════════════════╝                        │
└─────────────────────────────────────────────────────────┘

The user is invited to compose, customize, or wipe. The procedural fill is opinionated but disposable — never sticky, never assumed-correct. The Orchestra ensemble remains as one example in the Workshop drawer — a useful starting point for users whose mental model fits — but it’s not forced.

Wipe-and-restart contract: the user can always click “Start blank” in the Workshop drawer to return to a true empty stage. Procedural fill is a gift, not a prescription.

3.3 The Workshop drawer

A UI element inside the Studio. Not a surface name. The drawer is where users find inspiration. Three sections:

a) Get started — short, high-priority interactive cards that walk the user through their first action. “Drag this arcade cabinet onto your stage” → drag-to-stage interaction. “Click any door to connect to a friend’s Studio” → spawn a door, lay out tutorial. Coachmarks tied to actions, not modal popups.

b) Examples — premade scenes the user can load (and edit, fork, or remix). Five at v1: - Music ensemble — the former Orchestra preset. Conductor + musicians. - Game arcade — three arcade cabinets, each clickable to launch a real game. - Personal library — bookshelves with click-to-read essays + a typewriter for blog posts. - Gallery — a long wall with framed images, each clickable to open a fullscreen view + caption. - Workshop (the literal one) — a maker’s bench with tools, a chalkboard, project sketches.

c) Asset packs — categorized sprite libraries the user can browse + drag from. Initial packs at v1: - Music instruments (~20 sprites). - Arcade machines (~15 sprites — different cabinet styles, joysticks, etc.). - Books + bookshelves (~15 sprites). - Plants + props (~25 sprites — stage curtains, lamps, plants, decor). - Doors + portals (~10 sprites — different door styles, archways, portals).

Total v1 sprite count: ~85–100. A clear step down from the morning spec’s “80 core + 200 extended” but the right scope for v1 — quality over quantity.

3.4 Component catalog

Five categories. The third (Interactive) is now the most important and the deepest. Every component, regardless of category, carries the three sprite-walk flags introduced in §3.1: walkable_through (default for floor decals + ambient props), solid (default for walls + tall furniture), interactable (default for any component with a click-to-* binding).

a) Live components

Bound to data from chat state. Slot, state badge, activity dot, recent commit ticker, now-playing card, smoke gate.

b) Static components

Text block, image, SVG shape, music staff, stage prop.

c) Interactive — the breakthrough (full spec in INTERACTIVE_ASSETS.md)

Component Behavior
Click-to-link Click → open a URL in a new tab. The simple linktree-style interaction.
Click-to-launch Click → load a sandboxed iframe to a real running thing (game, app, demo). The breakthrough interaction.
Click-to-embed Click → reveal an inline player (Bandcamp, YouTube, SoundCloud, Vimeo from allowlist).
Click-to-read Click → open a long-form panel with markdown content (essays, project briefs).
Click-to-bot Click a bot sprite → open a chat with that sprite’s Claude personality.
Click-to-door Click a door sprite (or sprite-proximity + X) → travel to another canvas (v1.0: within your own Studio; v1.5: across Studios).
Hover reveal Hover → swap to alt content (e.g., book → pull title and synopsis).

d) Embeds

Project card, Showcase peek, Canvas embed (other users’ canvases, live), external iframe (allowlist).

e) Custom (code)

HTML block (sandboxed iframe), Style override (scoped CSS), Behavior script (sandboxed JS).

3.5 User customization

Beyond components: 1. Replace any sprite with custom (Claude-generated, uploaded, or community-catalog). 2. Edit the environment art (curtains, walls, lighting). 3. Custom CSS scoped to the Canvas. 4. Custom JS in sandboxed iframes. 5. Save Canvas as personal preset. 6. Remix any built-in or other-user’s public preset.

Two-axis theme system (locked 2026-04-29 evening)

Theme = (primary color × mode), plus an optional secondary color for highlights/CTAs. Primary color is one of 21 themes (the existing spectrum from crimson through mono plus paper); mode is light / dark / auto (auto respects prefers-color-scheme). The 2D combinatoric grid is 21 × 3 = 63 user-facing combinations, but the engine only stores 21 palette dictionaries — the light/dark variants are generated via the strategy in CHUNK_PREFS_API_CONTRACT.md §5 (hand-tuned hero variants for paper / ash / slate / mono, algorithmic luminance-flip with WCAG AA fallback for the other 17).

Logo: 2 master SVGs (/icons/icon-light.svg, /icons/icon-dark.svg) with v10w “Threaded Trinity” geometry. Colors come from CSS custom properties (--mark-primary-{light,mid,dark}, --mark-bg-{center,edge}) at render time — the page sets them from the active theme + mode and the mark inherits. The 21 baked-in /icons/icon-<theme>.svg outputs ship for one release cycle for backwards-compat; new surfaces should reference the masters.

3.6 The four breakthrough features (v1)

3.6.1 Composable connected canvases

Door components link to other canvases. v1.0: doors connect within a creator’s own Studio (across their 2 / 10 canvases). v1.5: doors connect across Studios — the multi-tenant overworld lets visitors walk between creators per V1_5_WALKABLE_WORLD.md. Sprite walks up to a door, presses X (or clicks); 600ms fade transition; sprite materializes at the destination’s interior anchor point. Doors carry context: who you came from, where you’ve been (last 5 hops), how to go back.

Spec: INTERACTIVE_ASSETS.md §2. Architecture: ARCHITECTURE.md §6.

3.6.2 Live presence

Visitors appear as ghost-sprites in real time when they’re walking your Canvas — their custom sprite, semi-transparent, drifting through the space. They can leave notes pinned to your components. You see them when you’re both there. WebSocket via Cloudflare Durable Objects. Live presence is v1.5; v1.0 ships single-visitor sprite-walk only.

Spec: INTERACTIVE_ASSETS.md §3. Architecture: ARCHITECTURE.md §6.5.

3.6.3 Generative living canvases

A mode where Claude composes the Canvas from your data. “Show what I worked on this week” → fresh scene from commits + state changes. Daily, mood, weekly variants. Cached and refreshable. The user retains full control: generated scenes are editable, savable, comparable. Generated layouts respect sprite-walk: Claude is given the walk-floor + collision constraints in the system prompt.

Spec: INTERACTIVE_ASSETS.md §4. Architecture: ARCHITECTURE.md §5 (Claude API).

3.6.4 Programmable creator-bots

Sprite + personality + work context. Visitors click to chat. Claude impersonates the sprite based on the personality + the creator’s RAG’d portfolio data. Owner reviews + curates conversations. Rate-limited per visitor.

Spec: INTERACTIVE_ASSETS.md §5. Architecture: ARCHITECTURE.md §5.

3.6.5 Procedural empty-state fill (added 2026-04-28; sprite-aware 2026-04-30)

The fifth breakthrough — the one that makes the Ensemble world feel alive on day zero of every signup. When a brand-new user lands in their first Studio, their first Canvas is already populated by a Claude-driven pipeline that reads:

  • Signup questionnaire answers — what kind of work they make, what they’re excited about, who their references are.
  • GitHub repos + topics (if they connected GitHub during signup) — language mix, stars, README snippets, recent activity.
  • Sensible defaults — a baseline scene that looks intentional even when the user gave nothing.

The output is a Canvas with 4–8 components: a representative scene-sprite, a couple of placeholder click-to-link tiles (“My GitHub,” “About me”), one of the example presets (Music ensemble / Game arcade / Personal library / Gallery / Workshop) chosen by the questionnaire signal, and an obvious “Walk + interact” prompt overlay that fades after first interaction. Sprite-aware (locked 2026-04-30): procedural fill now lays out components with walk-paths in mind — solid components don’t block the entrance, interactable components face the door, the user’s own sprite is placed on a walkable cell. The first canvas is playable the moment the Studio opens, not just viewable.

Why this is a breakthrough, not just a nicety: it inverts the cold-start problem that kills creator platforms. Most platforms ask the user to imagine what their space could become; Ensemble shows them on signup, then invites editing. Empty-platform anxiety → never starts. Pre-filled space → “oh, I want to change this one thing” → user is now editing within 30 seconds.

Disposable by design: the user can wipe the procedural fill with a single click (“Start blank” in the Workshop drawer). Never sticky, never assumed-correct. This is the difference between gift and prescription.

Quality bar: the procedural fill must look intentional, not generic. If the output reads “Hi I’m Kevin, I like coding, here’s a placeholder” the empty-state strategy backfires and the world feels more dead, not less. Bar is HIGH and demands its own design pass.

Spec: PROCEDURAL_FILL.md (drafted in Chunk 4 background workstreams). Implementation lands in Chunk 5 alongside public flip. Chunk 2’s data model commits to canvas-as-primitive so this can plug in without refactor.

3.6.6 The Ensemble landing — collective showcase (added 2026-04-28)

The /index.html Ensemble surface is reframed as the collective showcase — when a visitor arrives they see “the work everyone created together,” not a manifesto-with-CTA.

v1.0 (Chunk 5 public flip): a beautiful static grid of canvases. Pagination, light filtering (newest / featured / random), click any canvas to fly into it. The grid is server-rendered for SEO and visitor speed; canvas detail loads lazily.

v1.5 (per STAGED_PLATFORM.md + binding spec V1_5_WALKABLE_WORLD.md): the navigable walkable world. Zoom-out renders all canvases as a 2D-spatial map; the visitor walks their sprite between Studios. Their own canvas (if logged in) is highlighted; doors connect canvases; live presence dots show who’s currently visiting.

LOD mechanism (locked 2026-04-29): v1.5 uses a two-layer rooftop + interior model. Each canvas surfaces a small decorated rooftop tile on the overworld (cheap to render at scale; identity-bearing at distance), and the full Phase 2.1 canvas as the interior you walk into through a door. The rooftop is stored as an optional roof_design field on the Canvas schema (v2, forward-compat with v1 canvases — undecorated canvases render a default theme-colored block). Procedural town-layout binds rooftops into walkable plazas by theme cluster. Full architecture in V1_5_WALKABLE_WORLD.md, with companion specs ROOFTOP_LAYER.md and TOWN_LAYOUT.md. Implementation deferred to post-v1.0; the schema patch lands now (Slot S2A) for forward-compat.

Procedural-fill makes this work. Without procedural fill, the v1.0 grid is full of empty canvases from inactive users — embarrassing. With procedural fill, every signup contributes at least something recognizable. The world looks lived-in starting at user-1.

Free-tier mechanic (locked 2026-04-30): free users get 2 canvas slots (1 Showcase + 1 extra); Pro users get 10 (1 Showcase + 9 extras). The Showcase is the ONE canvas published to Ensemble; setting a different canvas as Showcase auto-clears the prior in a single transaction. The publishing decision is owner-only and happens in the Studio, not on the public surface. See §3.1a.

3.6.7 BYOK — Bring Your Own Anthropic Key (every tier)

Every tier supports linking a user’s own Anthropic API key. Free users get a starting platform allotment (5 calls/day, 30/month) AND can link their key for unlimited use without upgrading. Pro users get the larger platform allotment (500/month) AND BYOK on top. Team users will get team-shared keys (Phase F+).

BYOK is a sustainability mechanic: it transfers Claude API cost from platform to user. Users who already have an Anthropic Max plan ($250/month, unlimited usage) can use Ensemble without spending platform credits at all. The platform allotment becomes a sampling experience — “try Claude for free; bring your own key to keep going.”

The Anthropic ToS pass-through is surfaced at link time: users acknowledge they’re bound by Anthropic’s Acceptable Use Policy when using their own key.

See BYOK_GUIDE.md for the user flow and BYOK_ARCHITECTURE.md for the engineering shape.

3.7 Edit mode UX

Toggle: an Edit button top-right (owner-only, gated by paired browser). On click:

  1. Layout shifts. Sprite-walk pauses; the visitor sprite parks at the door.
  2. Workshop drawer stays/opens on the left.
  3. Component palette (right side, 240px wide).
  4. Claude chat drawer (bottom-right, 360px × 420px).
  5. Props panel (right side, replaces palette when component selected). Includes the three sprite-walk flags (walkable_through / solid / interactable) per §3.1.
  6. Drag handles + delete buttons on every component.
  7. Code editor (modal overlay, full-screen) for custom CSS/JS.
  8. Walk-floor overlay (toggle): a 16px grid + collision shading visualizing where the sprite can walk.

Editing actions, persistence, and undo/redo as in the morning spec, unchanged.

3.8 Claude chat in edit mode

A persistent drawer. Generates sprites, components, layouts, and code. New behaviors per the reorient:

  • “Make me a personality for this sprite” → generates a creator-bot personality the visitor can chat with.
  • “Compose a Canvas from my GitHub” → fetches user’s repo data, generates a scene that represents the project structure.
  • “Today’s mood: stormy” → generates a fresh Canvas scene with stormy aesthetic and recomposed elements.
  • “Connect this door to my other canvas” → walks user through the link target + transition style. (v1.5 extends this to other Studios per V1_5_WALKABLE_WORLD.md.)

Multi-turn conversation per Canvas. Each generated change has Apply/Discard. Nothing applies without an explicit click.

3.9 View mode UX

What visitors see: - No edit chrome. - Their custom sprite walking the canvas (8-direction, camera-follow). - All interactions live via sprite-proximity + X (or click): hovers, doors, bots, click-to-launch. - Live-presence layer (other-visitor ghost-sprites; v1.5). - “About this Canvas” tooltip in corner. - Owner sees Edit button as primary affordance. - Visitors see “Made with Ensemble” badge linking to /.

3.10 Sharing, publishing, embedding

Mode Reach Where Status
Private Owner only localStorage pre-Chunk 5; cloud from Chunk 5+ Always available
Unlisted Anyone with URL Pre-Chunk 5: GitHub Pages static. Chunk 5+: cloud. Always available
Public Indexed in Ensemble showcase, profile Chunk 5+ only After multi-tenancy
Embeddable iframe in another site Public + unlisted Studios / Canvases Chunk 5+

The Canvas iframe-embed: copy a snippet that pins to a specific version. Drop it into Substack, Notion, Bluesky bio. Apple-quality animated portfolio in someone else’s surface.

3.11 Sound design

Off by default. Opt-in via Settings → Studio → Sound. Per-asset-pack ambient + action sounds. Honors prefers-reduced-motion. Same as morning spec.


4. Showcase pages (top-level nav)

Per-project public-facing pages that aren’t a status dashboard but a story. Promoted to top-level nav since they’re a primary public surface.

Layout, og:image generation, RSS feeds: same as morning spec.


5. Map — folded into Ensemble (per locked decision)

Map is no longer a top-level nav slot — it’s been folded into the Ensemble surface per §1’s 4-slot nav (Ensemble · Dashboard · Settings · Docs). The Canvas-map content lives inside the Ensemble destination:

  • v1.0 (Chunk 5): the collective showcase grid surfaces relationships implicitly via featured filters and click-to-fly-in.
  • v1.5: the navigable walkable world is the spatial Map — connected canvases via doors render as the literal city map; cross-Ensemble navigation happens by walking between Studios.

The Map becomes the index of the connected creator-network at scale, expressed as the navigable Ensemble world rather than a separate tab.


6. Feed (Chunk 6+)

Cross-Ensemble timeline. Same as morning spec.


7. Phases — refreshed

The phase plan grows because we added four breakthrough features to v1. Total time-to-launch grew from ~100h to ~160h of focused work, but the resulting product is meaningfully more compelling.

Phase Scope Hours Status
A.0 Studio foundation (engine, CSS, asset model, procedurally-filled first canvas default, basic component catalog) ~20 In progress
A.1 Workshop drawer + asset packs + 5 example presets + first interactive components ~16 After A.0
PROC FILL stub Procedural-fill stub interface (Chunk 2) — sufficient surface area for canvas-as-primitive data commit ~4 After A.1
PROC FILL spec PROCEDURAL_FILL.md drafted (Chunk 4 background workstreams) ~6 After A.3
PROC FILL impl Real procedural-fill implementation (Chunk 5, alongside public flip) ~16 After D
A.2 Click-to-launch components (allowlist + sandbox + arcade-cabinet pattern) ~14 After A.1
A.3 Claude chat drawer in edit mode + sprite generation + component generation ~14 After A.2
B Map tab (Canvas map + door-aware nodes) ~6 After A.3
C Showcase pages (public per-project surfaces) + iframe embedding ~12 After B
D Multi-tenancy + auth (cloud backend) ~30–50 After C
D.1 Composable connected canvases (door routing across Studios — v1.5 multi-tenant overworld) ~16 After D
D.2 Live presence (ghost cursors via Durable Objects) ~16 After D.1
D.3 Generative living canvases (Claude API patterns) ~12 After D.2
D.4 Programmable creator-bots (RAG + personality system) ~14 After D.3
E Feed + cross-Ensemble discovery ~16 After D.4
F Sprite community catalog + asset marketplace v1 ~24 After E

Total: ~210h — about 12–18 months of focused part-time work or ~6 months full-time. The reorient added ~50h to the plan but the resulting product is platform-shaped, not tool-shaped.


8. v1 ship list (everything Phase A must deliver)

Functionality (revised 2026-04-30 — sprite-walk + character creator pulled in from v1.5): - [ ] Character creator (first-run UI; persisted sprite descriptor; ~384-combo palette per §3.2a). - [ ] Sprite-walk engine (8-direction, camera-follow, collision against solid components, sprite-proximity prompts on interactable). - [ ] Per-component flags (walkable_through / solid / interactable) wired into the canvas schema and props panel. - [ ] Interaction prompt UX (visible “Press X” overlay when sprite enters an interactable component’s radius; honors keyboard + click + touch). - [ ] Default Studio is procedurally-filled first Canvas + Workshop drawer + standing sprite (per §3.2 / §3.2a / §3.6.5). - [ ] Procedural-fill stub interface in place (Chunk 2 data-model commit; real impl in Chunk 5 per §3.6.5). Output is sprite-aware: walk-paths preserved, entrance unblocked. - [ ] Workshop drawer renders 3 sections (Get started, Examples, Asset packs). - [ ] 5 example presets loadable from Workshop (music ensemble, game arcade, library, gallery, workshop). - [ ] ~85–100 sprites across 5 asset packs (component sprites — distinct from the user’s own avatar sprite from the character creator). - [ ] Component catalog covers all classes including click-to-launch + click-to-bot + click-to-door, with sprite-proximity firing the same handlers as click. Cross-Studio door routing is v1.5 per V1_5_WALKABLE_WORLD.md; v1.0 doors connect within a creator’s own canvases. - [ ] Tier gates (per §3.1a): POST /canvas enforces 1+1 free / 1+9 pro; Studio UI disables “New canvas” at limit; Showcase setter enforces exactly-one. - [ ] Edit-mode toggles cleanly. Sprite-walk pauses; sprite parks at door. - [ ] Drag/resize/delete on every component class. - [ ] Claude chat drawer with sprite + component + personality generation. - [ ] Auto-save every 5s. - [ ] Undo/redo (50 ops). - [ ] Sandboxed custom CSS/JS. - [ ] All 21 themes apply. - [ ] Sound layer (opt-in) — ambient + footstep SFX hooks (footstep default per Kevin’s call, VISION_REVISION_2026-04-30.md §6.6).

Performance, accessibility, polish: as in morning spec.


9. Cross-cutting concerns

Themes, accessibility, performance budget, privacy, versioning

As in morning spec. Unchanged by the reorient.


10. What this spec is not


Locked 2026-04-27 (afternoon revision). Replaces the morning version. Studio is the primary front door; orchestra is one example among many; click-to-launch + 4 breakthrough features are the v1 differentiators.