Arcade · AI video pivot · 10 July 2026

Give Studio architectural sovereignty

Avery is your AI Producer. Video Projects are the work.

module
seam
leakage
deep module
The language spine
Product
Studio
Customer-facing mission
Avery
Your AI Producer
Editable work
Video Project
Rendered artifact
Video Export
Implementation below the seam HyperFrames today · replaceable tomorrow
3,479
flow-builder source files
15,596
12-month file touches
48
prompt-video routes
68
video-store importers
0
wizard intake tests
Strong ports & adapters Mission/domain drift

Make Video Projects first-class

packages/shared/src/types/firebase/promptVideoGeneration.ts apps/flow-builder/src/store/promptVideoGenerations/promptVideoGenerations.server.ts apps/functions/src/hyperframes-export.ts apps/functions/src/wizard-video-thumbnail.ts apps/flow-builder/app/api/prompt-video-generations/** apps/flow-builder/src/promptVideoGeneration/**
Before · shared persistence becomes the interface
flowchart TB
  L[Legacy scene-model video] --> C[(promptVideoGenerations)]
  H[Video Project
HyperFrames HTML] --> C
  C --> S[2,419-line store
36 exported operations]
  S --> R[48 route handlers]
  S --> F[Export + thumbnail functions]
  S --> U[Share + editor UI]
  R -. storage paths .-> F
  U -. version fields .-> F
  classDef leak stroke:#dc2626,stroke-width:2px,color:#991b1b,fill:#fff7f7;
  class C,S,R,F,U leak;
After · storage is implementation
Studio
Share
Admin
Deep module
Video Project
source · version · edit · export · publish · thumbnail
Firestore adapter
Storage adapter
Render adapter
Problem

Studio gives customers Avery, their AI Producer; the work Avery creates is a Video Project. Persistence instead calls it “V3 Wizard video” with format: 'wizard' and shares its interface with the KTLO scene model.

Solution

Deepen one Video Project module and hide the current Firestore collection, Storage layout, callable renderer, and compatibility fields behind its seam. HyperFrames becomes an implementation, not the product model.

Wins
  • • locality: one project lifecycle
  • • leverage: one interface
  • • KTLO storage stays internal
  • • tests cross the real seam
Strong ports & adapters 0 intake tests

Give Avery a durable generation run

apps/flow-builder/src/server/wizard/wizardSessionPost.ts apps/flow-builder/src/server/wizard/wizardSessionHandler.ts apps/flow-builder/src/server/wizard/wizardOrchestrator.ts apps/flow-builder/src/server/wizard/tools/** apps/flow-builder/src/store/wizardSessions/** apps/intelligence/src/workflows/**
Before · caller owns orchestration order
sequenceDiagram
  participant UI as Studio
  participant RT as 687-line intake
  participant CR as Credits
  participant WS as WizardSession
  participant SR as Source stores
  participant OR as Avery agent loop
  participant VD as Video Project
  UI->>RT: start / turn / stop
  RT->>CR: reserve + finalize
  RT->>WS: create + status
  RT->>SR: Flow / image / video / Brand Kit
  RT->>OR: 17+ resolved facts
  OR->>VD: HTML + mirrored ids
  Note over RT,VD: failures cross several owners
After · one run owns the outcome
Studio brief
Deep module
Video Generation Run
authorize · snapshot sources · converse · generate · settle
Workflow adapter
Source adapters
Usage adapter
Video Project module
Problem

Avery’s work lives inside an 800-second request continuation that owns credits, raw source records, Workspace and Team ids, Brand Kit internals, status flags, cancellation, provider details, and compensation ordering.

Solution

Deepen the generation run so HTTP only starts, observes, or cancels it. Put Avery’s multi-minute implementation behind the existing remote-owned workflow seam, with immutable sources and explicit failure settlement.

Wins
  • • locality: one run outcome
  • • Flow stays behind adapters
  • • usage settlement becomes atomic
  • • interface becomes test surface
Strong mock Advances ADR 0009

Finish the AI Invocation Runtime

apps/flow-builder/src/api/ai/aiClient.ts apps/functions/src/common/ai/aiClient.ts apps/flow-builder/src/api/ai/modelTiers.ts apps/functions/src/common/ai/modelTiers.ts apps/intelligence/src/services/ai/model-registry.ts packages/shared/src/types/firebase/features.ts
Before · provider policy has three homes
flowchart TB
  FB[flow-builder
611-line client] --> O[OpenAI / Vertex]
  FN[functions
476-line port] --> O
  IN[intelligence
807-line registry] --> P[OpenRouter / Vertex / Reve]
  FB -. tier policy .-> FN
  FN -. already drifted .-> FB
  FB -. tracing + schema rules .-> IN
  classDef leak stroke:#dc2626,stroke-width:2px,color:#991b1b,fill:#fff7f7;
  class FB,FN,IN leak;
After · capability enters once
flow-builder
functions
intelligence
Deep module
AI Invocation Runtime
provider policy · capability tier · schema · provenance · cost · tracing
OpenAI adapter
Vertex adapter
OpenRouter adapter
Fake adapter
Problem

The unified AI implementation was copied from flow-builder into functions, has already drifted on invalid-tier behavior, and coexists with intelligence’s separate provider registry.

Solution

Deepen the ADR 0009 runtime in a dedicated narrow package. Provider guarantee, tier resolution, structured output, multimodal conversion, provenance, and tracing become implementation.

Wins
  • • provider guarantee stays local
  • • model upgrades gain leverage
  • • one compliance test surface
  • • deployment drift stops
Strong local-substitutable KTLO firewall

Replace FlowLikeEntity with a Content Catalog

apps/flow-builder/src/components/Flows/types.ts apps/flow-builder/src/hooks/useFlowEntities.tsx apps/flow-builder/src/hooks/useMoveFlow.tsx apps/flow-builder/src/auth/server/access.ts apps/flow-builder/app/api/{flows,video-generations,...} apps/flow-builder/src/store/{flows,promptVideoGenerations,...}
Before · every caller knows six shapes
flowchart TB
  H[Home / library] --> Q[useFlowEntities]
  Q --> F[(Flow)]
  Q --> C[(Collection)]
  Q --> V[(VisualProject)]
  Q --> L[(Legacy Video)]
  Q --> P[(Prompt Video)]
  Q --> W[(Video Project
format: wizard)]
  M[Move / delete / tag / access] -. field checks .-> F
  M -. five SDK dispatches .-> W
  classDef leak stroke:#dc2626,stroke-width:2px,color:#991b1b,fill:#fff7f7;
  class Q,M leak;
After · stable catalog, varied adapters
Library
Search
Organization
Deep module
Content Catalog
identity · kind · owner · location · lifecycle · preview
Flow adapter
KTLO adapters
Video Project adapter
Problem

A six-shape union is discriminated by incidental fields such as steps, fps, format, and source; listing, access, and organization repeat the same branching.

Solution

Deepen a Content Catalog around the facts every library caller needs, with one adapter per persisted content kind. Flow-specific authoring remains outside the seam.

Wins
  • • new kinds add one adapter
  • • locality: organization rules
  • • legacy shapes stop leaking
  • • one catalog test surface
Strong in-process

Deepen the HyperFrames document compiler

packages/shared/src/customVideo/** apps/flow-builder/src/server/wizard/tools/createVideo.ts apps/flow-builder/src/server/wizard/tools/createComposition.ts apps/flow-builder/src/server/wizard/tools/addSoundEffects.ts apps/flow-builder/src/customVideoEditor/** apps/functions/src/hyperframes-export.ts
Before · callers assemble the pipeline
repair fonts
repair scripts
set caption default
bake derived captions
inject logo guard
validate / write / render repair

create, edit, and export know different ordering rules

After · one compiler owns invariants
Agent write
Editor write
Render prep
Deep module
HyperFrames Compiler
parse · repair · derive · validate · compile
fontsscriptscaptionsmusic
Problem

The customVideo interface exports ten files of parsing and mutation functions; callers must know transform order, idempotency, render-only repairs, and caption regeneration.

Solution

Deepen one compiler that owns document invariants from generated HTML through editable source and render-ready output, preserving the accepted derived-caption decision.

Wins
  • • ordering becomes implementation
  • • locality: document invariants
  • • tests use real parser
  • • renderer and editor agree
Strong in-process Two real adapters

Give the editor a document seam

apps/flow-builder/src/customVideoEditor/editorContextsBridge.tsx apps/flow-builder/src/customVideoEditor/context.tsx apps/flow-builder/src/editor/context-provider.tsx apps/flow-builder/src/editor/state/** apps/flow-builder/src/editor/timeline/** apps/flow-builder/src/editor/inspector/**
Before · HyperFrames impersonates Prompt Video
flowchart TB
  H[HyperFrames HTML] --> B[1,259-line context bridge]
  B --> S[Synthetic PromptVideoGeneration]
  S --> P[38 React context providers]
  P --> T[Timeline + inspector + undo]
  B -. timing translation .-> T
  B -. identity remapping .-> T
  B -. disabled capabilities .-> T
  classDef leak stroke:#dc2626,stroke-width:2px,color:#991b1b,fill:#fff7f7;
  class B,S,P leak;
After · editor speaks document
Timeline
Inspector
Undo
Deep module
Editor Document
snapshot · capabilities · commands · source changes
Structured-video adapter
HyperFrames adapter
Problem

HyperFrames fabricates a structured Prompt Video and feeds 38 legacy editor contexts. Timing, identities, undo, and capability rules live in the bridge; trimming, reordering, clipboard, and caption editing are disabled.

Solution

Deepen an Editor Document module between the reusable editor UI and the source model. Structured Prompt Video and HyperFrames are two real adapters at the seam.

Wins
  • • full HyperFrames editing path
  • • locality: undo semantics
  • • capabilities stop leaking
  • • two adapters justify seam
Worth exploring in-process Quality leverage

Compile Brand Kit once for generation

apps/flow-builder/src/api/ai/generation/promptVideoBrandContext.ts apps/flow-builder/src/server/wizard/wizardBrandKit.ts apps/flow-builder/src/server/wizard/selectBrandKitStyleAnchors.ts apps/flow-builder/src/api/ai/generation/__tests__/brandKitPromptParity.characterization.test.ts apps/intelligence/src/workflows/brand-kit/** packages/shared/src/brand-kit/**
Before · brand meaning is recompiled
PromptBrandKit
buildBrandContext
Legacy generator
BrandKitDoc
buildBrandKitPromptSection
Avery
font markup
asset URLs
b-roll rules
After · one domain projection
Brand Kit
Deep module
Brand Context
identity · voice · palette · fonts · usable assets · deterministic policy
Avery
Generation
B-roll
Problem

Legacy generation and Avery compile different Brand Kit shapes and prompt text, while fonts, logo variants, media, and b-roll guidance add separate policy paths.

Solution

Deepen a Brand Context module that owns the deterministic projection from a Brand Kit into generation-ready facts; each generation mode consumes that projection without reinterpreting the kit.

Wins
  • • locality: brand fidelity
  • • one deterministic projection
  • • prompt drift becomes visible
  • • quality tests gain leverage
Strong ports & adapters Advances ADR 0015

Join lineage, signals, and evals into Generation Evidence

packages/shared/src/types/firebase/artifactGraph.ts packages/shared/src/server/artifact-graph/** apps/flow-builder/src/store/artifactGraph/** apps/flow-builder/src/server/wizard/signals/** apps/flow-builder/src/api/ai/prompt-video-eval/** apps/flow-builder/src/api/ai/broll-eval/**
Before · 13k lines, several partial joins
flowchart TB
  G[Generation] --> TS[Turn signals]
  G --> AG[Artifact graph writers]
  G --> BT[Braintrust spans]
  G --> PV[Prompt-video eval]
  G --> BR[B-roll eval]
  TS -. manual join .-> A[Admin pages]
  AG -. partial readers .-> A
  BT -. trace lookup .-> A
  PV -. own schema .-> A
  BR -. own schema .-> A
  classDef leak stroke:#dc2626,stroke-width:2px,color:#991b1b,fill:#fff7f7;
  class TS,AG,BT,PV,BR,A leak;
After · evidence follows the artifact
Generation Run
Render
Human rating
Deep module
Generation Evidence
artifacts · transforms · signals · rubric · judge · experiment join
Firestore adapter
Braintrust adapter
Media references
Problem

Artifact lineage, turn signals, Braintrust spans, prompt-video diagnosis, b-roll rubrics, and admin views each own part of the question “why was this output bad?”

Solution

Deepen the accepted eval-control-plane direction into one Generation Evidence module; Firestore, Braintrust, and media remain distinct adapters linked through typed artifacts and transforms.

Wins
  • • locality: quality evidence
  • • one lineage walk
  • • eval schemas stop multiplying
  • • product learning compounds
Strategy guardrails
Strangler, not rewrite

Existing Firestore collections, Storage paths, Workspace rules, and KTLO code remain implementation behind adapters until a migration earns its cost.

One import rule

New Video Project modules do not import FlowDoc, RawFlow, Step, membership mirrors, or collection names except inside named legacy adapters.

Dedicated module homes

Do not grow another barrel inside @arcadehq/shared. Deep modules get narrow export maps and explicit ownership.

Interface is the test surface

Add behavior tests at each new seam; remove shallow implementation tests after equivalent interface coverage exists.

Top recommendation
Make Video Projects first-class

It is the smallest seam that changes the company’s option set: Studio gains an architectural home, Avery’s mission stops being encoded as a legacy video subtype, and every migration remains incremental and optional.