A motion design studio on your own machine: Claude makes the video step by step, you approve every stage. Bring your own Claude Code or API key.
// The gates: the rules every project follows, enforced here (not by asking the model nicely).
//
// - Only you cross a gate. A session can submit a reviewed step; only your Approve finishes it.
// - Internal steps finish with `mfx step done`, and only with their error checks reported.
// - Every submission reports every error check its step runs, on exactly what it's sending.
// - Every note you pinned on a version is answered, one by one, in the next version.
// - Submitted files are copied out of the working folder: what you reviewed can't change afterwards.
import { existsSync, mkdirSync, copyFileSync, realpathSync, statSync, readFileSync, appendFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
import { randomBytes } from 'node:crypto';
import { join, extname } from 'node:path';
import { paths, readJson, writeJson, withLock, isInside, UserError } from './studio.mjs';
import { checksForStep, WORK_KINDS } from './pipelines.mjs';
import { sceneGaps, gapsText } from './scenes.mjs';
import { projectPaths, projectPipeline, loadProject, update, event, safeName, now } from './projects.mjs';
import { firstWaits, scenesSubmitted } from './svc/lessons.mjs';
import { framesHeld } from './svc/framestate.mjs';
import { stillsHeld } from './svc/stills.mjs';
import { musicHeld } from './svc/musicneed.mjs';
import { fillV3Briefs } from './svc/v3briefs.mjs';
const DONE = ['approved', 'done', 'skipped'];
const KINDS = {
image: ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.svg', '.avif'],
video: ['.mp4', '.webm', '.mov', '.m4v'],
audio: ['.wav', '.mp3', '.m4a', '.ogg', '.flac', '.aac'],
pdf: ['.pdf'],
text: ['.md', '.txt'],
};
export function kindOf(file) {
const ext = extname(file).toLowerCase();
for (const [k, list] of Object.entries(KINDS)) if (list.includes(ext)) return k;
return 'file';
}
export class GateError extends UserError {}
const refuse = (msg) => { throw new GateError(msg); };
// Each step's state. Stored: working, in_review, changes, approved, done. Otherwise derived: ready or blocked.
export function stepView(project, pipeline) {
const stored = project.steps || {};
const byKey = Object.fromEntries(pipeline.steps.map((s) => [s.key, s]));
// A skipped step counts as finished only once the steps it follows are: skipping never lets later work jump ahead.
const finished = (k) => DONE.includes(stored[k]?.state) && (stored[k].state !== 'skipped' || (byKey[k]?.after || []).every(finished));
// Nothing is made before its gate (owner, 2026-10-18: "Nothing should be rendered until there's confirmation that
// everything looks good at the gates"): a step starts only when every step before it is approved, all the way back.
// The AI never runs ahead while the owner reviews.
const approvedChain = (k) => finished(k) && (byKey[k]?.after || []).every(approvedChain);
return pipeline.steps.map((s) => {
const rec = stored[s.key] || {};
// The style frames wait for the look the owner asks for (mfx.look_brief), whatever else is
// approved.
const lookWaits = s.canvas === 'frame' && s.key === 'style-frames' && !project.mfx?.look_brief;
// The animatic waits for the motion the owner picks (mfx.motion_brief: a motion pack and rule packs, or "the AI decides").
const motionWaits = s.canvas === 'shot' && s.key === 'animatic' && !project.mfx?.motion_brief;
// The transitions wait for the owner's transition pick (mfx.transition_brief: a transition pack, or the library).
const cutsWait = s.canvas === 'transition' && s.key === 'transitions' && !project.mfx?.transition_brief;
const state = rec.state || (s.after.every(approvedChain) && !lookWaits && !motionWaits && !cutsWait ? 'ready' : 'blocked');
return { ...s, state, version: rec.version || 0, last_feedback: rec.last_feedback || null, ...(rec.skip_reason ? { skip_reason: rec.skip_reason } : {}) };
});
}
// Recompute the project's state from its steps. Paused, cancelled and draft projects stay as they are.
export function settle(project, pipeline) {
if (!['queued', 'waiting', 'delivered'].includes(project.state)) return project.state;
const steps = stepView(project, pipeline);
const before = project.state;
// Edit requests from the canvas start a session at once, whatever else waits for the owner.
// So does a request for three music themes (doc 33: they arrive in the chat).
if (project.canvas_edits > 0 || project.mfx?.samples_wanted) project.state = 'queued';
else if (steps.every((s) => DONE.includes(s.state))) project.state = 'delivered';
else if (project.questions.some((q) => !q.answered_at)) project.state = 'waiting';
else if (steps.some((s) => ['ready', 'working', 'changes'].includes(s.state))) project.state = 'queued';
else project.state = 'waiting';
if (project.state === 'queued' && before !== 'queued') project.queued_at = now();
if (project.state === 'delivered' && before !== 'delivered') project.delivered_at = now();
if (project.state !== 'queued') project.status = null;
return project.state;
}
function studioChecks(root) {
const f = paths(root).checks;
return existsSync(f) ? readJson(f).active || [] : [];
}
export function stepChecks(root, id, stepKey) {
return checksForStep(projectPipeline(root, id), stepKey, studioChecks(root));
}
function findStep(pipeline, key) {
return pipeline.steps.find((s) => s.key === key) || refuse(`no step "${key}" in this pipeline (steps: ${pipeline.steps.map((s) => s.key).join(', ')})`);
}
function validateChecks(root, id, stepKey, reported) {
const need = stepChecks(root, id, stepKey);
const list = Array.isArray(reported) ? reported : [];
const byId = new Map(list.map((c) => [c?.id, c]));
for (const c of list) {
if (!need.some((n) => n.id === c?.id)) refuse(`error_checks: "${c?.id}" isn't a check for ${stepKey} (run: mfx checks ${stepKey})`);
if (!['pass', 'fixed', 'n/a'].includes(c.result)) refuse(`error_checks: "${c.id}" result must be pass, fixed or n/a`);
if (c.result !== 'pass' && !String(c.note || '').trim()) refuse(`error_checks: "${c.id}" is ${c.result}, so it needs a note`);
}
const missing = need.filter((n) => !byId.has(n.id));
if (missing.length) refuse(`error_checks: missing ${missing.map((m) => m.id).join(', ')} (every check for ${stepKey} must be reported: mfx checks ${stepKey})`);
return list.map((c) => ({ id: c.id, result: c.result, note: String(c.note || '').slice(0, 1000) }));
}
// ---------------------------------------------------------------------------------------------------------------
// What the session does (through mfx)
export function submit(root, id, stepKey, sub) {
const pp = projectPaths(root, id);
const pipeline = projectPipeline(root, id);
const step = findStep(pipeline, stepKey);
if (step.review === 'internal') refuse(`${stepKey} is internal: finish it with mfx step done ${stepKey} --checks <file>`);
if (!sub || typeof sub !== 'object') refuse('submission must be a JSON object');
// the shots: one per beat, always
if (step.canvas === 'shot' && !(pipeline.stage_set === 'v3' && firstWaits(root, id))) {
const gaps = sceneGaps(pp.work);
if (gaps.length) refuse(gapsText(gaps));
}
// The step's state first (checked again under the lock below): the most useful refusal comes first.
const early = stepView(loadProject(root, id), pipeline).find((s) => s.key === stepKey);
if (early.state === 'blocked') refuse(`${stepKey} can't start yet: it runs after ${step.after.join(', ')}`);
const note = String(sub.note || '').trim();
if (!note) refuse('submission needs a "note": what this is and what to look at');
const questions = (sub.questions || []).map((q, i) => {
if (!q?.text) refuse(`questions[${i}] needs text`);
const qid = String(q.id || `q${i + 1}`).replace(/[^A-Za-z0-9_-]/g, '').slice(0, 40) || `q${i + 1}`;
const choices = Array.isArray(q.choices) ? q.choices.map(String).slice(0, 12) : null;
const def = q.default === undefined || q.default === null ? null : String(q.default);
if (choices && def !== null && !choices.includes(def)) refuse(`questions[${i}]: the default must be one of its choices`);
return { id: qid, text: String(q.text).slice(0, 2000), choices, default: def };
});
if (new Set(questions.map((q) => q.id)).size !== questions.length) refuse('question ids must be unique');
const work = realpathSync(pp.work);
const items = (sub.items || []).map((it, i) => {
const label = String(it?.label || `Item ${i + 1}`).slice(0, 200);
const section = it?.section ? String(it.section).slice(0, 200) : null;
if (typeof it?.text === 'string') return { label, section, kind: 'text', text: it.text.slice(0, 200_000) };
if (typeof it?.path !== 'string') refuse(`items[${i}] needs a "path" (a file in this project folder) or "text"`);
const abs = join(work, it.path);
if (!existsSync(abs)) refuse(`items[${i}]: ${it.path} doesn't exist`);
const real = realpathSync(abs);
if (!isInside(work, real)) refuse(`items[${i}]: ${it.path} is outside the project folder`);
const st = statSync(real);
if (!st.isFile()) refuse(`items[${i}]: ${it.path} isn't a file`);
const kind = kindOf(real);
if (kind === 'text' && st.size <= 200_000) return { label, section, kind: 'text', text: readFileSync(real, 'utf8'), source: it.path };
return { label, section, kind, real, size: st.size, source: it.path };
});
const has = (k) => items.some((x) => x.kind === k);
const need = {
questions: () => questions.length || refuse('a questions step needs at least one question'),
document: () => has('text') || has('pdf') || refuse('a document step needs the document in items (text, .md, .txt or .pdf)'),
frames: () => has('image') || has('video') || refuse('a frames step needs the frames (images) in items'),
video: () => has('video') || refuse('a video step needs the video in items'),
audio: () => has('audio') || refuse('an audio step needs the audio in items'),
};
need[step.review]();
const error_checks = validateChecks(root, id, stepKey, sub.error_checks);
// The files are copied before the lock is taken (a big video can take longer than any writer should wait), into a
// staging folder that becomes reviews/<step>/v<N> with one rename under the lock.
const staging = join(pp.reviews, stepKey, `.incoming-${process.pid}-${randomBytes(4).toString('hex')}`);
const names = items.map((it, i) => (it.real ? `${String(i + 1).padStart(2, '0')}-${safeName(it.source)}` : null));
let res;
try {
mkdirSync(join(staging, 'files'), { recursive: true });
items.forEach((it, i) => { if (it.real) copyFileSync(it.real, join(staging, 'files', names[i])); });
res = update(root, id, (p) => {
const view = stepView(p, pipeline).find((s) => s.key === stepKey);
if (view.state === 'blocked') refuse(`${stepKey} can't start yet: it runs after ${step.after.join(', ')}`);
if (view.state === 'in_review') refuse(`${stepKey} v${view.version} is already waiting for review`);
if (DONE.includes(view.state)) refuse(`${stepKey} is already approved`);
// Every note from the last round gets an answer in this version.
const fb = view.last_feedback;
let pin_changes = [];
if (fb && fb.verdict === 'changes' && fb.notes > 0) {
const given = Array.isArray(sub.pin_changes) ? sub.pin_changes : [];
for (let n = 1; n <= fb.notes; n++) {
const c = given.find((x) => Number(x?.note) === n);
if (!c) refuse(`pin_changes: note ${n} from ${stepKey} v${fb.version} has no answer (one entry per note: {"note": ${n}, "change": "...", "status": "done|partly|not_done"})`);
if (!String(c.change || '').trim()) refuse(`pin_changes: note ${n} needs "change": what you changed, in plain words`);
if (!['done', 'partly', 'not_done'].includes(c.status)) refuse(`pin_changes: note ${n} status must be done, partly or not_done`);
pin_changes.push({ note: n, change: String(c.change).slice(0, 1000), status: c.status });
}
}
const version = view.version + 1;
const dir = join(pp.reviews, stepKey, `v${version}`);
// a submit that died before its record was written left this folder (the record never counted it): kept aside
if (existsSync(dir)) renameSync(dir, `${dir}.orphan-${Date.now()}`);
const stored = items.map((it, i) => {
if (!it.real) return { label: it.label, section: it.section, kind: it.kind, text: it.text, source: it.source || null };
return { label: it.label, section: it.section, kind: it.kind, file: `reviews/${stepKey}/v${version}/files/${names[i]}`, size: it.size, source: it.source };
});
const record = { step: stepKey, version, note: note.slice(0, 5000), questions, items: stored, error_checks, pin_changes, submitted_at: now() };
writeJson(join(staging, 'submission.json'), record);
renameSync(staging, dir);
p.steps[stepKey] = { ...(p.steps[stepKey] || {}), state: 'in_review', version, submitted_at: record.submitted_at };
p.status = null;
settle(p, pipeline);
event(root, id, { event: 'SUBMITTED', step: stepKey, version, details: note.slice(0, 300) });
return { step: stepKey, version, items: stored.length, project_state: p.state };
});
} finally {
rmSync(staging, { recursive: true, force: true }); // only still there when the submit was refused or failed
}
// Motion: the scene just submitted waits for the owner's OK (whoever built it)
if (stepKey === 'animatic') { try { scenesSubmitted(root, id); } catch { /* no scenes plan */ } }
return res;
}
export function stepStart(root, id, stepKey) {
const pipeline = projectPipeline(root, id);
findStep(pipeline, stepKey);
return update(root, id, (p) => {
const view = stepView(p, pipeline).find((s) => s.key === stepKey);
if (view.state === 'blocked') refuse(`${stepKey} can't start yet: it runs after ${view.after.join(', ')}`);
if (!['ready', 'changes', 'working'].includes(view.state)) refuse(`${stepKey} is ${view.state}`);
p.steps[stepKey] = { ...(p.steps[stepKey] || {}), state: 'working', version: view.version };
event(root, id, { event: 'STEP_STARTED', step: stepKey });
return { step: stepKey, state: 'working' };
});
}
export function stepDone(root, id, stepKey, reportedChecks) {
const pipeline = projectPipeline(root, id);
const step = findStep(pipeline, stepKey);
if (step.review !== 'internal') refuse(`${stepKey} is reviewed by you: only your approval finishes it (mfx submit ${stepKey} <file>)`);
const error_checks = validateChecks(root, id, stepKey, reportedChecks);
return update(root, id, (p) => {
const view = stepView(p, pipeline).find((s) => s.key === stepKey);
if (view.state === 'blocked') refuse(`${stepKey} can't finish yet: it runs after ${step.after.join(', ')}`);
if (view.state === 'done') refuse(`${stepKey} is already done`);
p.steps[stepKey] = { ...(p.steps[stepKey] || {}), state: 'done', version: view.version, done_at: now(), error_checks };
settle(p, pipeline);
event(root, id, { event: 'STEP_DONE', step: stepKey, details: error_checks.map((c) => `${c.id}:${c.result}`).join(' ') });
return { step: stepKey, state: 'done', project_state: p.state };
});
}
export function ask(root, id, stepKey, text, { default: def = null, choices = null } = {}) {
const pipeline = projectPipeline(root, id);
findStep(pipeline, stepKey);
if (!String(text || '').trim()) refuse('the question is empty');
if (choices && def !== null && !choices.includes(def)) refuse('the default must be one of the choices');
return update(root, id, (p) => {
const q = { id: `q${p.questions.length + 1}`, step: stepKey, text: String(text).slice(0, 2000), default: def, choices, asked_at: now(), answer: null, answered_at: null };
p.questions.push(q);
settle(p, pipeline);
event(root, id, { event: 'ASKED', step: stepKey, details: q.text.slice(0, 300) });
return { question: q.id, project_state: p.state };
});
}
export function status(root, id, key, mode = 'working') {
const pipeline = projectPipeline(root, id);
const text = pipeline.status_lines[key];
if (!text) refuse(`no status line "${key}" (this pipeline's: ${Object.keys(pipeline.status_lines).join(', ') || 'none'})`);
if (!['working', 'rendering'].includes(mode)) refuse('mode must be working or rendering');
return update(root, id, (p) => { p.status = { key, text, mode, at: now() }; return p.status; });
}
export function handoff(root, id, text) {
if (!String(text || '').trim()) refuse('the handoff is empty');
const pp = projectPaths(root, id);
appendFileSync(join(pp.work, 'JOURNAL.md'), `\n## ${now().slice(0, 16).replace('T', ' ')}\n\n${String(text).trim()}\n`);
event(root, id, { event: 'HANDOFF', details: String(text).slice(0, 600) });
return { ok: true };
}
export function log(root, id, name, details) {
if (!/^[A-Z][A-Z0-9_]{1,39}$/.test(name || '')) refuse('event names are UPPER_CASE, e.g. RESEARCH_DONE');
event(root, id, { event: name, details });
return { ok: true };
}
// The session can't go on without you (a decision only you can make, a broken tool, a missing key).
export function needsYou(root, id, text) {
if (!String(text || '').trim()) refuse('say what you need');
return update(root, id, (p) => {
// A late call (a session stopped by Cancel can still get one out) never brings a finished or cancelled
// project back as paused: those states only change by the owner's own action.
if (['cancelled', 'delivered', 'draft'].includes(p.state)) return { project_state: p.state, ignored: true };
p.state = 'paused';
p.needs_you = { text: String(text).slice(0, 2000), at: now() };
event(root, id, { event: 'NEEDS_YOU', details: p.needs_you.text });
return { project_state: p.state };
});
}
export function proposeCheck(root, id, { title, how, example, work, same_as }) {
const f = paths(root).checks;
return withLock(`${f}.lock`, () => {
const all = existsSync(f) ? readJson(f) : { active: [], proposed: [] };
if (same_as) {
const hit = [...all.active, ...all.proposed].find((c) => c.id === same_as) || refuse(`no check "${same_as}"`);
hit.seen = (hit.seen || 1) + 1;
writeJson(f, all);
event(root, id, { event: 'CHECK_SEEN_AGAIN', details: same_as });
return { id: same_as };
}
if (!title || !how) refuse('a check needs --title and --how');
const applies_to = String(work || '').split(',').map((w) => w.trim()).filter(Boolean);
for (const w of applies_to) if (!WORK_KINDS.includes(w)) refuse(`--work: ${w} isn't one of ${WORK_KINDS.join(', ')}`);
const cid = `${String(title).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 36)}-${Date.now().toString(36).slice(-4)}`;
all.proposed.push({ id: cid, title: String(title).slice(0, 200), how: String(how).slice(0, 2000), example: String(example || '').slice(0, 1000), applies_to, project: id, proposed_at: now() });
writeJson(f, all);
event(root, id, { event: 'CHECK_PROPOSED', details: title });
return { id: cid };
});
}
// ---------------------------------------------------------------------------------------------------------------
// What you do (web UI or `mortiflix review`)
export function respond(root, id, stepKey, version, { verdict, overall = '', notes = [], answers = {} }) {
const pp = projectPaths(root, id);
const pipeline = projectPipeline(root, id);
const target = findStep(pipeline, stepKey);
if (!['approve', 'changes', 'edit'].includes(verdict)) refuse('verdict must be approve, changes or edit');
// "Edit the video": instead of taking the final, the owner opens it in Mortiflix Studio (the delivering step only).
// v3 style frames one by one (rounds of 3): the Look is approved when every frame is OK (frames.ok), not before.
if (verdict === 'approve' && pipeline.stage_set === 'v3' && stepKey === 'style-frames' && framesHeld(root, id)) refuse('the style frames are checked one by one: press OK on each frame (frames.ok); the Look is approved when every frame is OK');
// v3 stills a group (scene) at a time: the step is approved when every still is OK (stills.ok), not before.
if (verdict === 'approve' && pipeline.stage_set === 'v3' && stepKey === 'stills' && stillsHeld(root, id)) refuse('the stills are checked a scene at a time: press OK on each still (stills.ok); the step is approved when every still is OK');
// v3 voice and music: the step is not approved until the music it makes is made and OK'd (Director 1, 2026-11-02:
// approved with no cue planned; owner 2026-11-03: "music is needed to be generated BEFORE we continue").
if (verdict === 'approve' && pipeline.stage_set === 'v3' && stepKey === 'voice') { const held = musicHeld(root, id); if (held) refuse(`the voice step makes the music too: ${held}`); }
if (verdict === 'edit' && !target.delivers) refuse('only the final can be edited in Mortiflix Studio');
// v3 scene by scene: approving a scene is motion.scene.approve, which builds the next scene. Asking for changes is fine.
if (verdict === 'approve' && pipeline.stage_set === 'v3' && stepKey === 'animatic' && firstWaits(root, id)) refuse('scenes are checked one by one: press OK on each scene (motion.scene.approve); the animatic is approved when every scene is OK');
if (verdict === 'edit' && !String(overall).trim()) overall = 'Edit the video: make the Mortiflix Studio project.';
const dir = join(pp.reviews, stepKey, `v${version}`);
if (!existsSync(join(dir, 'submission.json'))) refuse(`no ${stepKey} v${version}`);
const sub = readJson(join(dir, 'submission.json'));
const cleanNotes = (Array.isArray(notes) ? notes : []).map((n, i) => {
const text = String(n?.text || '').trim();
if (!text) refuse(`note ${i + 1} is empty`);
const item = n.item === undefined || n.item === null ? null : Number(n.item);
if (item !== null && !(Number.isInteger(item) && item >= 0 && item < sub.items.length)) refuse(`note ${i + 1} points at an item that doesn't exist`);
const frac = (v) => (v === undefined || v === null || v === '' ? null : Math.min(1, Math.max(0, Number(v))));
const out = { n: i + 1, item, item_label: item === null ? null : sub.items[item].label, text: text.slice(0, 2000) };
const x = frac(n.x), y = frac(n.y);
if (x !== null && y !== null && !Number.isNaN(x) && !Number.isNaN(y)) Object.assign(out, { x: round(x), y: round(y) });
if (n.time_sec !== undefined && n.time_sec !== null && n.time_sec !== '' && Number(n.time_sec) >= 0) out.time_sec = round(Number(n.time_sec), 2);
if (Number.isInteger(n.paragraph) && n.paragraph >= 0) out.paragraph = n.paragraph;
return out;
});
if (verdict === 'changes' && !cleanNotes.length && !String(overall).trim()) refuse('say what to change (a note or an overall comment)');
const resolved = sub.questions.map((q) => {
const a = answers?.[q.id];
const given = a === undefined || a === null || String(a).trim() === '' ? null : String(a).slice(0, 4000);
if (given === null && q.default === null) refuse(`"${q.text}" needs an answer`);
// A free answer beside the choices is allowed: people say "neither, make it teal".
return { id: q.id, text: q.text, answer: given ?? q.default, used_default: given === null };
});
const out = update(root, id, (p) => {
const view = stepView(p, pipeline).find((s) => s.key === stepKey);
if (view.state !== 'in_review' || view.version !== version) refuse(`${stepKey} v${version} isn't waiting for review (it's ${view.state}, v${view.version})`);
const feedback = {
step: stepKey,
version,
verdict,
overall: String(overall || '').slice(0, 4000),
notes: cleanNotes,
answers: resolved,
decided_at: now(),
how_to_read_annotations: 'Each note may point at an item (0-based index, item_label). x and y are fractions of the picture width and height from its top-left. time_sec is seconds into a video or audio item. paragraph is the 0-based paragraph of a text item. Answer every note in the next version\'s pin_changes.',
};
writeJson(join(dir, 'feedback.json'), feedback);
mkdirSync(join(pp.work, 'feedback'), { recursive: true });
writeJson(join(pp.work, 'feedback', `${stepKey}-v${version}.json`), feedback);
p.steps[stepKey] = {
...(p.steps[stepKey] || {}),
// Editing: the final is open in Mortiflix Studio. Nothing runs until the owner asks for a version or the big render.
state: verdict === 'approve' ? 'approved' : verdict === 'edit' ? 'editing' : 'changes',
...(verdict === 'edit' ? { edit: true } : { edit: undefined }),
version,
decided_at: feedback.decided_at,
last_feedback: { version, verdict, notes: cleanNotes.length },
};
const step = pipeline.steps.find((s) => s.key === stepKey);
if (verdict === 'approve' && step.delivers) {
p.deliverables = sub.items.filter((it) => it.file).map((it) => ({ label: it.label, kind: it.kind, file: it.file, size: it.size }));
}
settle(p, pipeline);
event(root, id, { event: verdict === 'approve' ? 'APPROVED' : verdict === 'edit' ? 'EDIT_VIDEO' : 'CHANGES_REQUESTED', actor: 'you', step: stepKey, version, details: cleanNotes.length ? `${cleanNotes.length} note(s)` : feedback.overall.slice(0, 200) });
return { step: stepKey, version, verdict, project_state: p.state };
});
// v3: a Look or Motion that waits only for a pick the app never asks for starts with "the AI decides" (svc/v3briefs.mjs)
if (verdict === 'approve') { try { fillV3Briefs(root, id); } catch (e) { console.error(`v3 briefs ${id}: ${e.message}`); } }
return out;
}
// The owner changes their mind after approving: the step goes back for changes, with their note, and steps after it
// that had started (but weren't approved) wait for the new version. The approval stays in the log.
export function reopen(root, id, stepKey, { overall = '', notes = [] } = {}) {
const pp = projectPaths(root, id);
const pipeline = projectPipeline(root, id);
const step = findStep(pipeline, stepKey);
if (step.review === 'internal') refuse(`${stepKey} isn't reviewed by you: reopen the reviewed step before it`);
if (!String(overall).trim() && !notes.length) refuse('say what to change');
return update(root, id, (p) => {
const rec = p.steps?.[stepKey];
if (!rec || !['approved', 'done'].includes(rec.state)) refuse(`${stepKey} isn't approved (it's ${rec?.state || 'not started'})`);
const version = rec.version;
const dir = join(pp.reviews, stepKey, `v${version}`);
const before = existsSync(join(dir, 'feedback.json')) ? readJson(join(dir, 'feedback.json')) : null;
const feedback = {
step: stepKey, version, verdict: 'changes', reopened: true, approved_at: before?.decided_at || rec.decided_at || null,
overall: String(overall).slice(0, 4000),
notes: notes.map((n, i) => ({ n: i + 1, item: n.item ?? null, text: String(n.text || '').slice(0, 2000) })),
answers: before?.answers || [],
decided_at: now(),
how_to_read_annotations: 'The owner approved this version, then asked for these changes. Answer every note in the next version\'s pin_changes.',
};
writeJson(join(dir, 'feedback.json'), feedback);
mkdirSync(join(pp.work, 'feedback'), { recursive: true });
writeJson(join(pp.work, 'feedback', `${stepKey}-v${version}.json`), feedback);
p.steps[stepKey] = { ...rec, state: 'changes', decided_at: feedback.decided_at, last_feedback: { version, verdict: 'changes', notes: feedback.notes.length } };
// Later steps that depend on it and had started without being approved go back to waiting.
const after = new Set([stepKey]);
let grew = true;
while (grew) { grew = false; for (const s of pipeline.steps) if (!after.has(s.key) && s.after.some((a) => after.has(a))) { after.add(s.key); grew = true; } }
for (const k of after) if (k !== stepKey && p.steps[k] && !['approved', 'done', 'skipped'].includes(p.steps[k].state)) delete p.steps[k];
if (p.state === 'delivered') p.state = 'queued';
settle(p, pipeline);
event(root, id, { event: 'REOPENED', actor: 'you', step: stepKey, version, details: String(overall).slice(0, 200) });
return { step: stepKey, version, project_state: p.state };
});
}
export function answerQuestion(root, id, qid, value) {
const pp = projectPaths(root, id);
const pipeline = projectPipeline(root, id);
return update(root, id, (p) => {
const q = p.questions.find((x) => x.id === qid) || refuse(`no question ${qid}`);
if (q.answered_at) refuse('already answered');
const given = value === undefined || value === null || String(value).trim() === '' ? null : String(value).slice(0, 4000);
if (given === null && q.default === null) refuse('this question needs an answer');
q.answer = given ?? q.default;
q.used_default = given === null;
q.answered_at = now();
mkdirSync(join(pp.work, 'feedback'), { recursive: true });
writeJson(join(pp.work, 'feedback', 'questions.json'), p.questions);
settle(p, pipeline);
event(root, id, { event: 'ANSWERED', actor: 'you', step: q.step, details: `${q.text.slice(0, 120)} → ${q.answer}` });
return { question: qid, project_state: p.state };
});
}
// Stop (cancel) is not final (owner 2026-11-03): a stopped project resumes like a paused one, from where it stopped.
// Its steps, files and paid results stay as they were; only the session was ended (runner.stopProject).
export function resume(root, id) {
const pipeline = projectPipeline(root, id);
return update(root, id, (p) => {
if (!['paused', 'cancelled'].includes(p.state)) refuse(`not paused or stopped (${p.state})`);
p.state = 'queued';
p.needs_you = null;
p.no_progress = 0;
p.last_failure = null;
settle(p, pipeline);
event(root, id, { event: 'RESUMED', actor: 'you' });
});
}
// "Let the AI take over" (T1): the one way a full session runs after a quick path gave up. The next run may use one.
export function takeover(root, id) {
const pipeline = projectPipeline(root, id);
return update(root, id, (p) => {
if (p.state !== 'paused') refuse(`not paused (${p.state})`);
p.mfx = { ...(p.mfx || {}), takeover: true };
p.state = 'queued';
p.needs_you = null;
p.no_progress = 0;
p.last_failure = null;
settle(p, pipeline);
event(root, id, { event: 'RESUMED', actor: 'you', details: 'Let the AI take over: a full session may run' });
});
}
export function pause(root, id, why = 'Paused by you') {
return update(root, id, (p) => {
if (['delivered', 'cancelled', 'draft'].includes(p.state)) refuse(`can't pause a ${p.state} project`);
p.state = 'paused';
p.needs_you = { text: why, at: now(), by_you: true };
event(root, id, { event: 'PAUSED', actor: 'you' });
});
}
export function cancel(root, id) {
return update(root, id, (p) => {
// a draft never started (Resume would skip project.start's checks); delivered and stopped have nothing to stop
if (['delivered', 'cancelled', 'draft'].includes(p.state)) refuse(`can't stop a ${p.state} project`);
p.state = 'cancelled';
event(root, id, { event: 'CANCELLED', actor: 'you' });
});
}
export function decideCheck(root, checkId, approve) {
const f = paths(root).checks;
return withLock(`${f}.lock`, () => {
const all = readJson(f);
const i = all.proposed.findIndex((c) => c.id === checkId);
if (i < 0) refuse(`no proposed check ${checkId}`);
const [c] = all.proposed.splice(i, 1);
if (approve) all.active.push({ ...c, approved_at: now() });
writeJson(f, all);
return c;
});
}
// ---------------------------------------------------------------------------------------------------------------
// Reading back
export function submissions(root, id) {
const pp = projectPaths(root, id);
const out = [];
if (!existsSync(pp.reviews)) return out;
for (const step of readdirSync(pp.reviews)) {
for (const v of readdirSync(join(pp.reviews, step))) {
if (!/^v\d+$/.test(v)) continue; // a submit being staged (.incoming-*) or one that never counted (v<N>.orphan-*)
const f = join(pp.reviews, step, v, 'submission.json');
if (!existsSync(f)) continue;
const sub = readJson(f);
const fb = join(pp.reviews, step, v, 'feedback.json');
out.push({ ...sub, feedback: existsSync(fb) ? readJson(fb) : null });
}
}
return out.sort((a, b) => a.submitted_at.localeCompare(b.submitted_at));
}
export function feedbackFor(root, id, stepKey) {
return submissions(root, id).filter((s) => s.feedback && (!stepKey || s.step === stepKey)).map((s) => s.feedback);
}
const round = (v, d = 4) => Math.round(v * 10 ** d) / 10 ** d;
// The final, rendered out of Mortiflix Studio after the owner's edits: it becomes the delivery. The file is copied into the
// project's record (reviews/<final>/edited-N.mp4), so it can't change after the fact.
export function deliverEdited(root, id, file) {
const pp = projectPaths(root, id);
const pipeline = projectPipeline(root, id);
const step = pipeline.steps.find((s) => s.delivers) || refuse('this pipeline has no delivering step');
if (loadProject(root, id).steps?.[step.key]?.state !== 'editing') refuse(`${step.name} isn't being edited in Mortiflix Studio`);
// The video is copied before the lock (it can be large), then renamed into place under it.
const dir = join(pp.reviews, step.key);
mkdirSync(dir, { recursive: true });
const staging = join(dir, `.incoming-${process.pid}-${randomBytes(4).toString('hex')}.mp4`);
try {
copyFileSync(file, staging);
return update(root, id, (p) => {
if (p.steps[step.key]?.state !== 'editing') refuse(`${step.name} isn't being edited in Mortiflix Studio`);
let n = 1;
while (existsSync(join(dir, `edited-${n}.mp4`))) n++;
renameSync(staging, join(dir, `edited-${n}.mp4`));
const rel = `reviews/${step.key}/edited-${n}.mp4`;
p.steps[step.key] = { ...p.steps[step.key], state: 'approved', edit: undefined, delivered_from: 'edit', decided_at: now() };
p.deliverables = [{ label: `${step.name} (edited in Mortiflix Studio)`, kind: 'video', file: rel, size: statSync(file).size }];
settle(p, pipeline);
event(root, id, { event: 'DELIVERED_FROM_EDIT', actor: 'you', step: step.key, details: rel });
return { delivered: rel, project_state: p.state };
});
} finally {
rmSync(staging, { force: true }); // only still there when the delivery was refused or failed
}
}