Issue: #349 Depends on: #347. Implements ADR-0019 §2, §3, §6, §7.
#347 defines how the API pulls a shared file: share.prepare, then a
poster stream and the render's stream over the runner socket. This slice is
the machine's side. The daemon announces share, answers share.prepare
with the scenario's description, the render's chapters and a poster it makes
with FFmpeg, and serves the poster through the relay. The renderer starts
writing chapters into result.json so there is something to answer with.
On top of that, demoflow share <runId> creates a share from the terminal,
and the MCP server gains share_demo, refused unless the project's committed
config says share.allowMcp: true.
packages/core/src/run-result.ts: optionalchaptersonRenderOutputSchema.packages/core/src/project-config.ts: the optionalshareblock;packages/core/schemas/project-config.schema.jsonregenerated withbun run --filter @demoflow/core schema(scripts/generate-schemas.ts[Confirmed]).packages/renderer/src/renderer.ts(and the plan code that knows the placed scene cards): writechaptersper render.apps/cli/src/runner/connection.ts:features: ['share']inlaunches.sync; routeshare.prepare.apps/cli/src/runner/share/(new):prepare.ts(description, chapters, poster),poster.ts(FFmpeg).apps/cli/src/runner/relay/index.ts: serveasset: 'poster'.apps/cli/src/commands/share.ts(new) andapps/cli/src/main.ts: thesharecommand.apps/cli/src/mcp/server.ts(andtasks.ts/project.tsas needed):share_demo.apps/cli/test/**: tests, Vitest under Node.apps/cli/README.md: the command, the tool andshare.allowMcp.
- The API (#347, #348) and the website (#350–#352).
- Website docs pages (#352).
- Re-uploading after a re-render (#356).
-
Chapters are written at render time.
RenderOutputSchemagainschapters: z.array(z.strictObject({ title: NonEmptyString ≤ 200, atMs: int ≥ 0 })).max(100).optional(). The renderer fills it for every render from the scene cards the plan placed — the scenario'sscenemarkers and the page's scenes (ADR-0014) alike — with each card's start in output time. A run rendered before this slice has nochapters; its share has none. [Unknown: which plan value carries the placed cards torecordRender;packages/renderer/src/plan/cards.tsplaces them (PlacedCard, kindscene[Confirmed]).]- Why in
result.json: the output time of a scene depends on cards, cuts and idle trimming; the renderer is the only place that knows it, and recomputing a plan at share time would use today's config, not the render's.
- Why in
-
share.prepareon the daemon.{ requestId, runId, format }, withrunIdthe server's id, looked up withfindReportedRun(apps/cli/src/runs-report/reported-runs.ts[Confirmed]) exactly as the relay does. Then:- no entry, no
result.jsonthat parses, or no render offormatwhose file exists →share.error { code: 'not-found' | 'no-render' }; description: the scenario's, read from<entry.root>/<scenarioId>the waydemoflow renderreads it (spec 255, Decision 3 [Confirmed:apps/cli/src/commands/render.ts]); absent when the file is gone or does not load;chapters: the render'schapters, or[];- the poster (Decision 3); its size is
posterSize. - Answer
share.prepared { requestId, description?, chapters, posterSize }. Only these fields; never a path. FFmpeg failing →share.error { code: 'io' }.
- no entry, no
-
Poster. One JPEG frame of the render at
min(1500, ⌊durationMs / 2⌋)ms, scaled to at most 1280 px wide keeping the aspect,-q:v 4, written to<runDir>/share/poster-<format>.jpgand reused while it is newer than the render's file. FFmpeg is the renderer's (resolveFfmpeg/runFfmpeg, exported from@demoflow/renderer[Confirmed]). A poster over 1 MB isio. GIF renders get a poster too. -
asset: 'poster'onvideo.open. The relay serves<runDir>/share/poster-<format>.jpgfor it, with the same checks as a render (the run is reported, the format is aRENDER_FORMATSmember) and the same chunking and credit. An unknownassetvalue isnot-found. -
Capability.
launches.synccarriesfeatures: ['share'](#347, Decision 6). -
demoflow share.demoflow share <runId> [--format <format>] [--expires <7|30|90>] [--password] [--json]plus a hidden
--project <dir>, likerender.<runId>is the local run id, resolved to a run directory asdemoflow renderdoes (spec 255, Decisions 1–2 [Confirmed]); the server id comes from the reported-runs index by run directory (readReportedRunsByDir[Confirmed]).--formatdefaults to the run's first render;--expiresto 30.--passwordasks for it without echo on a terminal; without a terminal it readsDEMOFLOW_SHARE_PASSWORD. A password is never a flag value (shell history).- It calls
POST /runner/shareswith the stored device token, then pollsGET /runner/shares/:idevery second for up to 10 minutes, printing progress on stderr, and prints the link (and the file link when there is no password).--jsonprints theShareView. - Refusals are
CommandErrors, exit 2:not-logged-in(no credentials: "run demoflow login"),run-not-found,run-not-reported(the run was made signed out or with reporting off),format-not-rendered,runner-offline("start the runner: demoflow runner start"),runner-outdated("restart the runner"),file-too-large,quota-exceeded(with used and limit).share-existsis not an error: it prints the existing link and says so. An upload that endsfailedexits 1 with itsfailure.
-
share_demo(MCP). Input{ runId, format?, expiresInDays? }, no password. It does whatdemoflow sharedoes and returns{ shareId, url, fileUrl, expiresAt }. Refused withshare-not-allowedunless thedemoflow.config.jsonof the run's project root hasshare.allowMcp: true. The root is the reported run'sroot[Confirmed:ReportedRun.root]; a run without one is refused the same way. [Source: owner, Q12; ADR-0019 §6] -
Config.
share: z.strictObject({ allowMcp: z.boolean().default(false) }).optional()onProjectConfigSchema, with a description that says the MCP server may then publish videos outside the machine without asking.
- A fresh run's
result.jsonhaschapterson each render, one per scene card, in output milliseconds; a run with no scenes haschapters: []; an oldresult.jsonwithout the field still parses. - The daemon's first frame carries
features: ['share']. - Given a reported run with an
mp4render,share.prepareanswersshare.preparedwith the scenario's description, the render's chapters and the poster's size; the poster is a JPEG ≤ 1280 px wide. -
share.preparefor an unreported run, a missing render file or an unrendered format answersshare.errorwithnot-found/no-render, and never reads outside the runs directory. -
video.openwithasset: 'poster'streams exactly the poster file. -
demoflow share <runId>against a fake API prints the link once the share isready; each refusal of Decision 6 exits 2 with its code;--passwordnever appears in the process arguments of the request. -
share_demoanswersshare-not-allowedwithoutshare.allowMcp: trueand creates the share with it. -
project-config.schema.jsonis regenerated andshare.allowMcpvalidates in an editor. - Tests pass under Node with Vitest on Linux, macOS and Windows
(
execution-plane.yml).
| Slot | Owns | Touches | Depends on | Lead | Model |
|---|---|---|---|---|---|
| i349-core | chapters and the config block | packages/core/src/run-result.ts, packages/core/src/project-config.ts, packages/core/schemas/project-config.schema.json, packages/core/test/, packages/renderer/src/renderer.ts, packages/renderer/src/plan/, packages/renderer/test/** | — | yes | opus |
| i349-cli | daemon, relay, command, MCP | apps/cli/src/runner/connection.ts, apps/cli/src/runner/share/, apps/cli/src/runner/relay/index.ts, apps/cli/src/commands/share.ts, apps/cli/src/main.ts, apps/cli/src/mcp/, apps/cli/test/**, apps/cli/README.md | i349-core | no | sonnet |
| Resource | Owner | Everyone else |
|---|---|---|
| packages/core/src/project-config.ts, packages/core/schemas/project-config.schema.json | i349-core | #361 (schedule) and #365 (render.endHoldMs) also add keys: one at a time, regenerate the schema each time |
| packages/core/src/run-result.ts | i349-core | #353/#354 or #360 may touch it; cut after this merges |
| packages/renderer/src/renderer.ts, packages/renderer/src/plan/** | i349-core | #353, #354, #365 edit the plan; serialize |
| apps/cli/src/runner/connection.ts | i349-cli | #355 and #361 route new messages; serialize |
| apps/cli/src/main.ts | i349-cli | #360 adds --check; serialize |
| apps/cli/src/mcp/server.ts | i349-cli | do not open it |
- Chapters wrong after idle trimming (medium). A scene placed in a trimmed span. Mitigation: take the time after the time map, from the same placed card the compositor draws; a test with a trimmed pause.
- FFmpeg seek on GIF (low). Mitigation: decode from the start for GIF
(
-ssafter-i); a test per container. - An agent shares a video with customer data (medium). Mitigation: the config flag is off by default and lives in a reviewed commit (ADR-0019 §6).
- A password for
share_demo— default: none; an agent should not hold one. - Auto-starting the daemon when
demoflow sharefinds it offline — default: no; print the command.