rushes 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,165 @@
1
+ // §25: a visual is one post, a still or a carousel of pages, each page a picture in each aspect ratio it comes in. These are
2
+ // pure functions over the visuals file: they register a visual or a new version of one, and check a note against one. The
3
+ // pictures' sizes are read by the caller (the server reads the files), so nothing here touches the disk.
4
+ import { RushesError } from "./errors.js";
5
+ import { labelOfId, ratioId, ratioLabel } from "./formats.js";
6
+ import { slugify, uniqueId } from "./ids.js";
7
+ import { MAX_VISUAL_PAGES } from "./schema.js";
8
+ const fail = (code, message, detail = {}) => {
9
+ throw new RushesError(message, 400, code, detail);
10
+ };
11
+ const norm = (s) => s.trim().toLowerCase();
12
+ /** A page's pictures as images, each with the ratio its size gives it. Two pictures of one shape on one page are refused. */
13
+ function imagesOf(files, page) {
14
+ if (files.length === 0)
15
+ fail("bad_pages", `Page ${page} has no pictures.`, { page });
16
+ const images = [];
17
+ for (const f of files) {
18
+ const ratio = ratioId(ratioLabel(f.width, f.height));
19
+ const clash = images.find((i) => i.ratio === ratio);
20
+ if (clash)
21
+ fail("same_ratio", `Page ${page}: ${f.file} and ${clash.file} are both ${labelOfId(ratio)}. Give one picture per aspect ratio.`, { page, ratio, files: [clash.file, f.file] });
22
+ images.push({ ratio, file: f.file, width: f.width, height: f.height });
23
+ }
24
+ return images;
25
+ }
26
+ /** The aspect ratios a version comes in, in the order its pages list them. */
27
+ export function visualRatios(version) {
28
+ return version.pages[0]?.images.map((i) => i.ratio) ?? [];
29
+ }
30
+ /** Registers a new visual with its first version (v1). Changes nothing when it throws. */
31
+ export function registerVisual(file, input, now = new Date()) {
32
+ const name = input.name.trim();
33
+ if (name === "")
34
+ fail("bad_name", "A visual needs a name.");
35
+ const slug = slugify(name);
36
+ if (file.visuals.some((v) => norm(v.name) === norm(name) || v.id === slug)) {
37
+ fail("duplicate_name", `There is already a visual called "${name}". Register a new version of it, or give this one another name.`, { name });
38
+ }
39
+ if (input.pages.length === 0)
40
+ fail("bad_pages", "A visual needs at least one page.");
41
+ if (input.pages.length > MAX_VISUAL_PAGES)
42
+ fail("too_many_pages", `A visual holds at most ${MAX_VISUAL_PAGES} pages; this has ${input.pages.length}.`, { pages: input.pages.length });
43
+ const kind = input.kind ?? (input.pages.length > 1 ? "carousel" : "still");
44
+ if (kind === "still" && input.pages.length > 1)
45
+ fail("bad_pages", "A still has one page. Register several pages as a carousel.");
46
+ const pages = input.pages.map((p, i) => {
47
+ if (p.n !== undefined && p.n !== i + 1)
48
+ fail("bad_pages", `Pages are numbered 1, 2, 3 in order: the page at position ${i + 1} is numbered ${p.n}.`, { page: p.n });
49
+ return { n: i + 1, images: imagesOf(p.files, i + 1) };
50
+ });
51
+ const ratios = pages[0].images.map((i) => i.ratio).sort().join(",");
52
+ const odd = pages.find((p) => p.images.map((i) => i.ratio).sort().join(",") !== ratios);
53
+ if (odd)
54
+ fail("ratio_set", `Every page must come in the same aspect ratios: page 1 is ${pages[0].images.map((i) => labelOfId(i.ratio)).join(", ")}, page ${odd.n} is ${odd.images.map((i) => labelOfId(i.ratio)).join(", ")}.`, { page: odd.n });
55
+ const version = { id: "v1", addedAt: now.toISOString(), label: input.label ?? "", pages };
56
+ const visual = { id: uniqueId(slug, file.visuals.map((v) => v.id)), name, kind, addedAt: now.toISOString(), versions: [version] };
57
+ file.visuals.push(visual);
58
+ return { visual, version };
59
+ }
60
+ /** Finds a visual by its id, or by its name. */
61
+ export function findVisual(file, ref) {
62
+ return file.visuals.find((v) => v.id === ref) ?? file.visuals.find((v) => norm(v.name) === norm(ref));
63
+ }
64
+ /**
65
+ * Registers a new version of a visual. `pages` lists only what changed or is new; every other page, and every other
66
+ * ratio of a listed page, is inherited from the version before. Pages can be added at the end and never removed, and
67
+ * once inherited, every page must have a picture for every ratio. Changes nothing when it throws.
68
+ */
69
+ export function addVisualVersion(file, input, now = new Date()) {
70
+ const visual = findVisual(file, input.visual);
71
+ if (!visual)
72
+ return fail("no_such_visual", `No visual "${input.visual}". Register it with a name first.`, { visual: input.visual });
73
+ const prev = visual.versions[visual.versions.length - 1];
74
+ const listed = new Map();
75
+ for (const p of input.pages) {
76
+ if (p.n === undefined || !Number.isInteger(p.n) || p.n < 1)
77
+ fail("bad_pages", "Each page of a new version needs its page number, from 1.", { page: p.n });
78
+ if (listed.has(p.n))
79
+ fail("bad_pages", `Page ${p.n} is listed twice.`, { page: p.n });
80
+ listed.set(p.n, imagesOf(p.files, p.n));
81
+ }
82
+ if (listed.size === 0)
83
+ fail("bad_pages", "A new version needs at least one page.");
84
+ const total = Math.max(prev.pages.length, ...listed.keys());
85
+ for (let n = prev.pages.length + 1; n <= total; n++) {
86
+ if (!listed.has(n))
87
+ fail("bad_pages", `Page ${n} is missing: new pages are added at the end with no gap (the version before has ${prev.pages.length}).`, { page: n });
88
+ }
89
+ if (total > MAX_VISUAL_PAGES)
90
+ fail("too_many_pages", `A visual holds at most ${MAX_VISUAL_PAGES} pages; this would have ${total}.`, { pages: total });
91
+ if (visual.kind === "still" && total > 1)
92
+ fail("bad_pages", "A still has one page. Register several pages as a carousel.");
93
+ // The ratios: the version before's, then any new ones in the order they first appear.
94
+ const ratios = [...visualRatios(prev)];
95
+ for (const images of listed.values())
96
+ for (const i of images)
97
+ if (!ratios.includes(i.ratio))
98
+ ratios.push(i.ratio);
99
+ const pages = [];
100
+ for (let n = 1; n <= total; n++) {
101
+ const before = prev.pages[n - 1]?.images ?? [];
102
+ const sent = listed.get(n) ?? [];
103
+ const images = [];
104
+ for (const ratio of ratios) {
105
+ const image = sent.find((i) => i.ratio === ratio) ?? before.find((i) => i.ratio === ratio);
106
+ if (!image)
107
+ return fail("grid_incomplete", `Page ${n} has no ${labelOfId(ratio)} picture. Every page needs one for every aspect ratio.`, { page: n, ratio });
108
+ images.push(image);
109
+ }
110
+ pages.push({ n, images });
111
+ }
112
+ const version = { id: `v${visual.versions.length + 1}`, addedAt: now.toISOString(), label: input.label ?? "", pages };
113
+ visual.versions.push(version);
114
+ return { visual, version };
115
+ }
116
+ /**
117
+ * §25.4, checked when a note on a visual is written: the visual, its version and the page must be there, a ratio must be one
118
+ * of the version's, and a region or a point needs a ratio (a place on one shape is not the place on another).
119
+ */
120
+ export function checkVisualNote(next, file) {
121
+ if (next.stage !== "visuals")
122
+ return;
123
+ const on = next.on ?? "";
124
+ const slash = on.lastIndexOf("/");
125
+ const id = slash === -1 ? on : on.slice(0, slash);
126
+ const visual = file.visuals.find((v) => v.id === id);
127
+ if (!visual)
128
+ fail("no_such_visual", `No visual "${id}".`, { visual: id });
129
+ const version = visual.versions.find((v) => v.id === next.version);
130
+ if (!version)
131
+ fail("no_such_version", `${visual.name} has no version ${next.version ?? "(none)"}.`, { visual: id, version: next.version });
132
+ const n = slash === -1 ? NaN : Number(on.slice(slash + 1));
133
+ if (!Number.isInteger(n) || !version.pages.some((p) => p.n === n))
134
+ fail("no_such_page", `${visual.name} ${next.version} has no page ${slash === -1 ? "(none)" : on.slice(slash + 1)}.`, { visual: id, page: on.slice(slash + 1) });
135
+ if (next.format !== null && !visualRatios(version).includes(next.format))
136
+ fail("unknown_format", `${visual.name} ${next.version} has no ${labelOfId(next.format)} picture.`, { format: next.format });
137
+ if ((next.box || next.pin) && next.format === null)
138
+ fail("shape_needs_format", "A region or a point is drawn on one aspect ratio, so the note needs one.");
139
+ }
140
+ import { pinWords, regionWords } from "./visualWords.js";
141
+ export { pinWords, regionWords };
142
+ export function visualNoteView(note, file) {
143
+ if (note.stage !== "visuals" || note.on === null)
144
+ return null;
145
+ const slash = note.on.lastIndexOf("/");
146
+ const visual = file.visuals.find((v) => v.id === note.on.slice(0, slash));
147
+ const page = Number(note.on.slice(slash + 1));
148
+ if (!visual || slash === -1 || !Number.isInteger(page))
149
+ return null;
150
+ const version = visual.versions.find((v) => v.id === note.version);
151
+ const image = version?.pages.find((p) => p.n === page)?.images.find((i) => i.ratio === note.format);
152
+ const box = note.box ? { x: note.box.x, y: note.box.y, w: note.box.w, h: note.box.h } : null;
153
+ const pin = note.pin ? { x: note.pin.x, y: note.pin.y } : null;
154
+ return {
155
+ visual: { id: visual.id, name: visual.name },
156
+ version: note.version ?? "",
157
+ page,
158
+ ratio: note.format === null ? null : labelOfId(note.format),
159
+ shape: box ? "region" : pin ? "pin" : "image",
160
+ region: box,
161
+ pin,
162
+ words: box ? regionWords(box) : pin ? pinWords(pin) : null,
163
+ file: image?.file ?? null,
164
+ };
165
+ }
package/dist/mcp/tools.js CHANGED
@@ -6,7 +6,7 @@ import { BRING_IN_MAX } from "../server/found.js";
6
6
  import { LABEL_MAX, oneLineOf } from "../core/labels.js";
7
7
  import { LOG_AREAS } from "../core/logText.js";
8
8
  const project = z.string().optional().describe("Project folder. Defaults to the current working directory.");
9
- const stage = z.enum(["script", "picture", "voice", "music", "sfx", "mix"]);
9
+ const stage = z.enum(["script", "picture", "voice", "music", "sfx", "mix", "visuals"]);
10
10
  const fileKind = z.enum(["doc", "image", "caption", "export", "delivery", "edit"]);
11
11
  const assetKind = z.enum(["screenshot", "cut", "proxy", "take", "music", "sfx", "voice", "doc", "image", "caption", "export", "delivery", "edit"]);
12
12
  // §20.7: a file to bring in. The server checks everything else (inside the project, the kind, the limits).
@@ -185,6 +185,29 @@ export function createMcpServer(ctx) {
185
185
  return { ...r, note: OLDER_DROPPED };
186
186
  return r;
187
187
  }));
188
+ server.registerTool("rushes_add_visual", {
189
+ title: "Add a visual",
190
+ description: "Register a still, a standalone image or a carousel so the user can mark it up in the Visuals tab: one visual per post. A new visual (`name`) lists every page in order, each page with its pictures, one per aspect ratio (a png, jpg, webp or gif inside the project; Rushes reads each ratio from the picture's own size). A new version of a visual you already registered (`visual`: its id or name) lists only the pages that changed or are new, each with its page number `n`; every other page, and every ratio of a listed page you leave out, carries over from the version before. Pages can be added at the end and never removed; a new aspect ratio needs a picture on every page. After feedback, fix the marked pictures, register them as a new version, then rushes_reply to each note with fixVersion set to that version (you never mark a note done: the user does). Returns the visual, the version (v1, v2 ...), the page count and the ratios. A notes batch for Visuals (rushes_get_batch) names each note's visual, version, page, ratio and where on the picture it is, with the file to open. Refused, with the reason and nothing changed: a picture outside the project or that is a link, one that is not an image or cannot be read, two pictures of one ratio on a page, pages that disagree about their ratios, a name already used, and a page that is missing for a ratio.",
191
+ inputSchema: {
192
+ project,
193
+ name: z.string().trim().min(1).max(80).optional().describe("A new visual's name, e.g. \"Launch carousel\". Give this or `visual`, not both."),
194
+ visual: z.string().trim().min(1).max(80).optional().describe("The id or name of an existing visual, to register a new version of it."),
195
+ kind: z.enum(["still", "carousel"]).optional().describe("A new visual only. Defaults to a carousel when there is more than one page, else a still."),
196
+ label: z
197
+ .string()
198
+ .refine((s) => Array.from(oneLineOf(s)).length <= LABEL_MAX, `label is ${LABEL_MAX} characters at most`)
199
+ .meta({ maxLength: LABEL_MAX })
200
+ .optional()
201
+ .describe(`A short label saying what changed in this version, ${LABEL_MAX} characters at most.`),
202
+ pages: z
203
+ .array(z.object({
204
+ n: z.number().int().positive().optional().describe("The page number. Required for a new version; optional for a new visual (pages are 1, 2, 3 in order)."),
205
+ files: z.array(z.string().min(1).max(1024)).min(1).max(8).describe("The page's pictures, one per aspect ratio, paths relative to the project."),
206
+ }))
207
+ .min(1)
208
+ .max(100),
209
+ },
210
+ }, safe(async ({ project, ...b }) => (await ctx.client(project)).post("/api/visuals", b)));
188
211
  server.registerTool("rushes_add_format", {
189
212
  title: "Add a format",
190
213
  description: "Register another shape of a cut: the same edit rendered at another aspect ratio, e.g. the 9:16 or 1:1 of a 16:9 cut. Rushes measures the ratio with ffprobe. Defaults to the newest cut of the only or newest film. Returns the format's id and label (e.g. \"9x16\", \"9:16\"), and `warning` when its length is more than 0.1 s off the cut's. Refused, with the reason: a second render with a ratio the cut already has (a re-render is a new version), a file that isn't a video, a cut that already has 8 shapes (the most one cut can have, its own file included), and a machine without ffprobe. The cut's own file stays its main shape: register only the other shapes.",
@@ -5,10 +5,12 @@ import { RushesError, InvalidError, NotFoundError } from "../core/errors.js";
5
5
  import { addFile, addFormat, addVariant, addVersion, ensureProjectIdOnce, lockPicture, resolveCut, resolveVideo, setShots, shotAt } from "../core/project.js";
6
6
  import { addTake, editSection, setSections } from "../core/script.js";
7
7
  import { addNote, applyReply, applyUserEdit, checkNoteFormat, filterNotes } from "../core/notes.js";
8
- import { FORMAT_ID_RE, MAX_FORMATS, isPictureSize, versionFormats } from "../core/formats.js";
8
+ import { FORMAT_ID_RE, MAX_FORMATS, isPictureSize, labelOfId, versionFormats } from "../core/formats.js";
9
9
  import { createBatch, latestBatch } from "../core/batches.js";
10
10
  import { exportFileName, notesMarkdown } from "../core/exportNotes.js";
11
11
  import { tabStates } from "../core/tabs.js";
12
+ import { addVisualVersion, checkVisualNote, registerVisual, visualNoteView, visualRatios } from "../core/visuals.js";
13
+ import { readPicture } from "./visuals.js";
12
14
  import { fromManifestPath, toManifestPath } from "../core/paths.js";
13
15
  import { AUDIO_FORMATS, PROBE_TIMEOUT_MS, VIDEO_EXT, giveUpAfter, probe, probeVideo, videoGaveUp } from "../core/media.js";
14
16
  import { PROXY_PATH, ProxyJobs } from "./proxy.js";
@@ -22,16 +24,16 @@ import { GRAB_PATH, OUTSIDE_CUT_EXT, OUTSIDE_MEDIA_EXT, SCREENSHOT_PATH, content
22
24
  import { BRING_IN_MAX, FoundScanner, ffprobeDuration, foundAnnouncer } from "./found.js";
23
25
  import { candidatePaths, listAssets, fpsFor, screenshotName } from "./assets.js";
24
26
  import { osRevealer, osOpener, OPEN_SAFE_EXT } from "./reveal.js";
25
- import { LaneStageSchema, SectionStatusSchema, StageSchema, BoxSchema, FileKindSchema, MarkSchema, ProjectIdSchema, ShotSchema, LEVEL_MIN, LEVEL_MAX, LEVEL_STEP } from "../core/schema.js";
27
+ import { LaneStageSchema, SectionStatusSchema, StageSchema, BoxSchema, PinSchema, FileKindSchema, MarkSchema, ProjectIdSchema, ShotSchema, LEVEL_MIN, LEVEL_MAX, LEVEL_STEP } from "../core/schema.js";
26
28
  import { LABEL_MAX, oneLineOf } from "../core/labels.js";
27
29
  import { byOf, logBookFor } from "./logbook.js";
28
30
  import { BriefService } from "./brief.js";
29
31
  import { StoryboardService } from "./storyboard.js";
30
32
  import { buildState, planWarning } from "../core/plan.js";
31
- import { broughtInEvent, cutEvent, fileEvent, formatEvent, lineEvent, lockEvent, notesSentEvent, picksEvent, repliesEvent, scriptEvent, takeEvent, variantEvent, } from "../core/logEvents.js";
33
+ import { broughtInEvent, cutEvent, fileEvent, formatEvent, lineEvent, lockEvent, notesSentEvent, picksEvent, repliesEvent, scriptEvent, takeEvent, variantEvent, visualEvent, } from "../core/logEvents.js";
32
34
  import { LOG_AREAS, LOG_MAX, changeLogFileName, logText, recentChanges } from "../core/logText.js";
33
35
  import { defaultRunner, measureMix } from "./loudness.js";
34
- export const VERSION = "0.5.1";
36
+ export const VERSION = "0.6.0";
35
37
  async function body(c, schema) {
36
38
  let json;
37
39
  try {
@@ -50,6 +52,10 @@ const t = z.number().nonnegative();
50
52
  const formatId = z.string().max(16).regex(FORMAT_ID_RE);
51
53
  /** The longest path a format may be registered under (FoundItem and FoundPathsBody use the same). */
52
54
  const MAX_PATH = 1024;
55
+ /** §25.5: a note on a visual with where it is, in words, and the picture to open: what an agent reading the batch needs. */
56
+ function withVisualViews(notes, visuals) {
57
+ return notes.map((n) => (n.stage === "visuals" ? { ...n, visual: visualNoteView(n, visuals) } : n));
58
+ }
53
59
  const NewNoteBody = z.object({
54
60
  stage: StageSchema,
55
61
  video: z.string().nullish(),
@@ -61,13 +67,26 @@ const NewNoteBody = z.object({
61
67
  frame: z.number().int().nonnegative().nullish(),
62
68
  text: z.string(),
63
69
  box: BoxSchema.nullish(),
70
+ pin: PinSchema.nullish(),
64
71
  grab: z.string().nullish(),
65
72
  marks: z.array(MarkSchema).max(4).optional(),
66
73
  format: formatId.nullish(),
67
74
  });
75
+ // §25.5: a new visual (a name) or a new version of one (a visual), with the pages that are new or changed.
76
+ const VisualBody = z
77
+ .object({
78
+ name: z.string().trim().min(1).max(80).optional(),
79
+ visual: z.string().trim().min(1).max(80).optional(),
80
+ kind: z.enum(["still", "carousel"]).optional(),
81
+ label: z.string().trim().max(LABEL_MAX).optional(),
82
+ pages: z.array(z.object({ n: z.number().int().positive().optional(), files: z.array(z.string().min(1).max(1024)).min(1).max(MAX_FORMATS) })).min(1).max(100),
83
+ })
84
+ .refine((b) => (b.name !== undefined) !== (b.visual !== undefined), { message: "send name (a new visual) or visual (a new version of one), not both" })
85
+ .refine((b) => b.name !== undefined || b.kind === undefined, { message: "kind is for a new visual" });
68
86
  const UserEditBody = z.object({
69
87
  text: z.string().optional(),
70
88
  box: BoxSchema.nullable().optional(),
89
+ pin: PinSchema.nullable().optional(),
71
90
  grab: z.string().nullable().optional(),
72
91
  scope: z.enum(["point", "range", "whole"]).optional(),
73
92
  t: t.nullable().optional(),
@@ -426,6 +445,9 @@ export function createApp(store, opts = {}) {
426
445
  // falls through to candidatePaths, which does the readdir-backed discovery (§16.2's
427
446
  // auto-discovered docs/captions/exports) that a registered path never needs.
428
447
  let known = registeredMedia(project, script).has(path) || GRAB_PATH.test(path) || SCREENSHOT_PATH.test(path);
448
+ // §25.7: a registered visual's pictures. Read visuals.json only when the above missed, so a cut's seeks never touch it.
449
+ if (!known && registeredMedia(project, script, await store.read("visuals")).has(path))
450
+ known = true;
429
451
  // §24.12: a picture storyboard.md names (a safe, project-relative image path) is served too, registered or not.
430
452
  if (!known && (await storyboard.stills()).has(path))
431
453
  known = true;
@@ -591,11 +613,11 @@ export function createApp(store, opts = {}) {
591
613
  return c.json(result, 201);
592
614
  });
593
615
  app.post("/api/exports/notes", async (c) => {
594
- const [project, notesFile, script, picks] = await Promise.all([
595
- store.read("project"), store.read("notes"), store.read("script"), store.read("picks"),
616
+ const [project, notesFile, script, picks, visuals] = await Promise.all([
617
+ store.read("project"), store.read("notes"), store.read("script"), store.read("picks"), store.read("visuals"),
596
618
  ]);
597
619
  const now = new Date();
598
- const md = notesMarkdown(project, notesFile.notes, now, script, picks);
620
+ const md = notesMarkdown(project, notesFile.notes, now, script, picks, visuals);
599
621
  const name = exportFileName(project.name, now);
600
622
  const dir = join(store.root, "exports");
601
623
  await mkdir(dir, { recursive: true });
@@ -634,17 +656,17 @@ export function createApp(store, opts = {}) {
634
656
  app.get("/api/state", async (c) => {
635
657
  // §20.6: found is what the last scan left in memory; it never waits on a scan or a probe.
636
658
  // §22.8: the log's head is read-only, so a state request never writes (R6).
637
- const [project, script, notes, picks, batches, ffmpeg, foundSummary, logHead, briefView, storyboardView] = await Promise.all([
638
- store.read("project"), store.read("script"), store.read("notes"), store.read("picks"), store.read("batches"), jobs.available(), found.summary(), log.head(), brief.view(), storyboard.view(),
659
+ const [project, script, notes, picks, batches, ffmpeg, foundSummary, logHead, briefView, storyboardView, visuals] = await Promise.all([
660
+ store.read("project"), store.read("script"), store.read("notes"), store.read("picks"), store.read("batches"), jobs.available(), found.summary(), log.head(), brief.view(), storyboard.view(), store.read("visuals"),
639
661
  ]);
640
- const tabs = tabStates(project, script, notes);
662
+ const tabs = tabStates(project, script, notes, visuals);
641
663
  // §19.5: why each cut may play badly (or null). Never waits on a probe: an unprobed cut is
642
664
  // null until its background probe lands, which then announces a change (ruling B).
643
665
  const videos = await Promise.all(project.videos.map(async (v) => ({
644
666
  ...v,
645
667
  versions: await Promise.all(v.versions.map(async (ver) => ({ ...ver, proxyNeed: await jobs.needNow(fromManifestPath(store.root, ver.file)) }))),
646
668
  })));
647
- return c.json({ project: { ...project, videos }, script, notes, picks, batches, tabs, proxies: { ffmpeg, jobs: jobs.list() }, found: foundSummary, log: logHead, brief: briefView, storyboard: storyboardView, build: buildState({ brief: briefView, script: script.sections, storyboard: storyboardView }) });
669
+ return c.json({ project: { ...project, videos }, script, notes, picks, batches, tabs, visuals, proxies: { ffmpeg, jobs: jobs.list() }, found: foundSummary, log: logHead, brief: briefView, storyboard: storyboardView, build: buildState({ brief: briefView, script: script.sections, storyboard: storyboardView }) });
648
670
  });
649
671
  // ---- found: the project's other files (§20) ----
650
672
  app.get("/api/found", async (c) => {
@@ -730,10 +752,10 @@ export function createApp(store, opts = {}) {
730
752
  return c.json({ ok: true });
731
753
  });
732
754
  app.get("/api/tabs", async (c) => {
733
- const [project, script, notes] = await Promise.all([store.read("project"), store.read("script"), store.read("notes")]);
755
+ const [project, script, notes, visuals] = await Promise.all([store.read("project"), store.read("script"), store.read("notes"), store.read("visuals")]);
734
756
  const [b, sb] = await Promise.all([brief.view(), storyboard.view()]);
735
757
  return c.json({
736
- tabs: tabStates(project, script, notes),
758
+ tabs: tabStates(project, script, notes, visuals),
737
759
  brief: { exists: b.exists, status: b.status, changed: b.changed },
738
760
  storyboard: { exists: sb.exists, shots: sb.total, approved: sb.approved, changed: sb.changed },
739
761
  build: buildState({ brief: b, script: script.sections, storyboard: sb }),
@@ -764,14 +786,17 @@ export function createApp(store, opts = {}) {
764
786
  const q = NoteQuery.safeParse(c.req.query());
765
787
  if (!q.success)
766
788
  throw new InvalidError("Query is invalid", q.error.issues);
767
- const { notes } = await store.read("notes");
768
- return c.json({ notes: filterNotes(notes, { ...q.data, onlyThisFormat: q.data.onlyThisFormat === "true" }) });
789
+ const [{ notes }, visuals] = await Promise.all([store.read("notes"), store.read("visuals")]);
790
+ return c.json({ notes: withVisualViews(filterNotes(notes, { ...q.data, onlyThisFormat: q.data.onlyThisFormat === "true" }), visuals) });
769
791
  });
770
792
  app.post("/api/notes", async (c) => {
771
793
  const b = await body(c, NewNoteBody);
772
794
  // The client never sends shot; the server stamps it from the version's shots.
773
795
  let shot = null;
774
- if (b.stage === "picture" || b.format != null) {
796
+ // §25.4: a note on a visual is checked against the visual, its version, its page and its ratios.
797
+ if (b.stage === "visuals")
798
+ checkVisualNote({ stage: b.stage, on: b.on ?? null, version: b.version ?? null, format: b.format ?? null, box: b.box ?? null, pin: b.pin ?? null }, await store.read("visuals"));
799
+ else if (b.stage === "picture" || b.format != null) {
775
800
  const project = await store.read("project");
776
801
  // §21.3: a format must be one of this cut's, and on a cut with formats a box belongs to one.
777
802
  checkNoteFormat({ next: { stage: b.stage, video: b.video ?? null, version: b.version ?? null, format: b.format ?? null, box: b.box ?? null } }, project);
@@ -787,8 +812,9 @@ export function createApp(store, opts = {}) {
787
812
  app.patch("/api/notes/:id", async (c) => {
788
813
  const b = await body(c, UserEditBody);
789
814
  // §21.3 and R7: a change of format or box is checked against the note's cut as it is now.
790
- const project = b.format !== undefined || b.box !== undefined ? await store.read("project") : null;
791
- const check = project ? (next, prev) => checkNoteFormat({ next, prev, boxRedrawn: b.box !== undefined }, project) : undefined;
815
+ const project = b.format !== undefined || b.box !== undefined || b.pin !== undefined ? await store.read("project") : null;
816
+ const visuals = project ? await store.read("visuals") : null;
817
+ const check = project && visuals ? (next, prev) => (next.stage === "visuals" ? checkVisualNote(next, visuals) : checkNoteFormat({ next, prev, boxRedrawn: b.box !== undefined }, project)) : undefined;
792
818
  const { result } = await store.update("notes", (f) => applyUserEdit(f, { id: c.req.param("id"), ...b }, check));
793
819
  return c.json({ note: result });
794
820
  });
@@ -1189,17 +1215,28 @@ export function createApp(store, opts = {}) {
1189
1215
  return c.json({ batch: await run }, 201);
1190
1216
  });
1191
1217
  app.get("/api/batches/:id", async (c) => {
1192
- const [batches, notes, script] = await Promise.all([store.read("batches"), store.read("notes"), store.read("script")]);
1218
+ const [batches, notes, script, visuals] = await Promise.all([store.read("batches"), store.read("notes"), store.read("script"), store.read("visuals")]);
1193
1219
  const id = c.req.param("id");
1194
1220
  const batch = id === "latest" ? latestBatch(batches) : batches.batches.find((b) => b.id === id);
1195
1221
  if (!batch)
1196
1222
  throw new NotFoundError("batch", id);
1197
1223
  return c.json({
1198
1224
  batch,
1199
- notes: notes.notes.filter((n) => batch.noteIds.includes(n.id)),
1225
+ notes: withVisualViews(notes.notes.filter((n) => batch.noteIds.includes(n.id)), visuals),
1200
1226
  sections: script.sections.filter((s) => batch.sectionIds.includes(s.id)),
1201
1227
  });
1202
1228
  });
1229
+ // ---- visuals (§25) ----
1230
+ app.post("/api/visuals", async (c) => {
1231
+ const b = await body(c, VisualBody);
1232
+ // Every picture is read first, in the order given, so a refusal always names the first one and writes nothing.
1233
+ const pages = [];
1234
+ for (const p of b.pages)
1235
+ pages.push({ n: p.n, files: await Promise.all(p.files.map((f) => readPicture(store.root, f))) });
1236
+ const { result } = await store.update("visuals", (f) => b.name !== undefined ? registerVisual(f, { name: b.name, kind: b.kind, label: b.label, pages }) : addVisualVersion(f, { visual: b.visual, label: b.label, pages }));
1237
+ await log.add(() => visualEvent(result.visual, { id: result.version.id, note: "", file: "", label: result.version.label }), by(c));
1238
+ return c.json({ visual: { id: result.visual.id, name: result.visual.name, kind: result.visual.kind }, version: { id: result.version.id, label: result.version.label }, pages: result.version.pages.length, ratios: visualRatios(result.version).map(labelOfId) }, 201);
1239
+ });
1203
1240
  // ---- the Change Log (§22.7) ----
1204
1241
  app.get("/api/log", async (c) => {
1205
1242
  const q = LogQuery.safeParse(c.req.query());
@@ -66,7 +66,7 @@ export const GRAB_PATH = /^\.rushes\/grabs\/[a-z0-9][a-z0-9_-]*\.png$/;
66
66
  /** Screenshots: screenshots/<safe name>.png. Dots are allowed, for names like "00m12.05s". */
67
67
  export const SCREENSHOT_PATH = /^screenshots\/[a-z0-9][a-z0-9._-]*\.png$/;
68
68
  /** Every media path the project has registered. Only these (and grabs) may be served. */
69
- export function registeredMedia(project, script) {
69
+ export function registeredMedia(project, script, visuals) {
70
70
  const files = new Set();
71
71
  for (const v of project.videos) {
72
72
  for (const ver of v.versions) {
@@ -91,6 +91,12 @@ export function registeredMedia(project, script) {
91
91
  files.add(t.file);
92
92
  for (const f of project.files)
93
93
  files.add(f.file);
94
+ // §25.7: every picture of every version of every visual.
95
+ for (const v of visuals?.visuals ?? [])
96
+ for (const ver of v.versions)
97
+ for (const p of ver.pages)
98
+ for (const i of p.images)
99
+ files.add(i.file);
94
100
  return files;
95
101
  }
96
102
  /**
@@ -0,0 +1,20 @@
1
+ import { lstat } from "node:fs/promises";
2
+ import { join } from "node:path";
3
+ /**
4
+ * Whether `rel` (a project-relative path), or any folder on the way to it, is a link. The project's own files are never
5
+ * followed out of it: a still the storyboard names, a picture a visual is made of. A part that is missing is not a link.
6
+ */
7
+ export async function viaLink(root, rel) {
8
+ let at = root;
9
+ for (const seg of rel.split("/")) {
10
+ at = join(at, seg);
11
+ try {
12
+ if ((await lstat(at)).isSymbolicLink())
13
+ return true;
14
+ }
15
+ catch {
16
+ return false;
17
+ }
18
+ }
19
+ return false;
20
+ }
@@ -128,9 +128,10 @@ export class RecordFile {
128
128
  const tick = async () => {
129
129
  try {
130
130
  const st = await lstat(this.path).catch(() => null);
131
- const sig = st ? `${st.mtimeMs}:${st.size}:${st.ino}` : "";
131
+ // Only a regular file counts as "there was a file": changes inside a folder at this path are none of our business.
132
+ const sig = st ? `${st.isFile() ? "f" : "x"}:${st.mtimeMs}:${st.size}:${st.ino}` : "";
132
133
  if (sig !== last) {
133
- const hadFile = last !== null && last !== "";
134
+ const hadFile = last?.startsWith("f:") ?? false;
134
135
  last = sig;
135
136
  await this.sync();
136
137
  // A file that is deleted, or becomes a folder or a link, changes nothing in `.rushes/` by itself. Forget what was
@@ -1,8 +1,7 @@
1
- import { lstat } from "node:fs/promises";
2
- import { join } from "node:path";
3
1
  import { hashText } from "../core/brief.js";
4
2
  import { InvalidError, RushesError } from "../core/errors.js";
5
3
  import { STORYBOARD_FILE, cutShots, editShot, parseStoryboard } from "../core/storyboard.js";
4
+ import { viaLink } from "./links.js";
6
5
  import { RecordFile } from "./record.js";
7
6
  // §24.12: storyboard.md is the file of record for the shots. See RecordFile for how it is kept.
8
7
  export class StoryboardChangedError extends RushesError {
@@ -42,24 +41,9 @@ export class StoryboardService extends RecordFile {
42
41
  plannedLength: Math.round(shots.reduce((a, s) => a + (s.length ?? 0), 0) * 1000) / 1000,
43
42
  };
44
43
  }
45
- /** Whether a still, or any folder on the way to it, is a link. The project's own files are never followed out of it. */
46
- async linked(still) {
47
- let at = this.store.root;
48
- for (const seg of still.split("/")) {
49
- at = join(at, seg);
50
- try {
51
- if ((await lstat(at)).isSymbolicLink())
52
- return true;
53
- }
54
- catch {
55
- return false;
56
- }
57
- }
58
- return false;
59
- }
60
44
  /** The view with every still that goes through a link taken out: it is no still. */
61
45
  async safe(v) {
62
- const shots = await Promise.all(v.shots.map(async (s) => (s.still && (await this.linked(s.still)) ? { ...s, still: null } : s)));
46
+ const shots = await Promise.all(v.shots.map(async (s) => (s.still && (await viaLink(this.store.root, s.still)) ? { ...s, still: null } : s)));
63
47
  return { ...v, shots };
64
48
  }
65
49
  view() {
@@ -94,7 +78,7 @@ export class StoryboardService extends RecordFile {
94
78
  const named = text === null ? [] : parseStoryboard(text).shots.flatMap((s) => (s.still ? [s.still] : []));
95
79
  const safe = [];
96
80
  for (const still of named)
97
- if (!(await this.linked(still)))
81
+ if (!(await viaLink(this.store.root, still)))
98
82
  safe.push(still);
99
83
  return new Set(safe);
100
84
  });
@@ -0,0 +1,52 @@
1
+ import { open } from "node:fs/promises";
2
+ import { isAbsolute, normalize, relative, resolve, sep } from "node:path";
3
+ import { RushesError } from "../core/errors.js";
4
+ import { imageSize } from "../core/imageSize.js";
5
+ import { isPictureSize } from "../core/formats.js";
6
+ import { viaLink } from "./links.js";
7
+ // §25.5: the pictures a visual is made of are read here, and only here: a picture is a real file inside the project, of a
8
+ // type a browser shows inline, whose size can be read from its first bytes. Everything else is refused, naming the file.
9
+ const PICTURE_EXT = /\.(png|jpe?g|webp|gif)$/i;
10
+ /** A jpeg's frame header can sit behind large metadata, so more than a few kilobytes are read. */
11
+ const HEAD_BYTES = 262_144;
12
+ const refuse = (code, message, file) => {
13
+ throw new RushesError(message, 400, code, { file });
14
+ };
15
+ /** `file` as a project-relative path with forward slashes, or null when it is outside the project. */
16
+ function inProject(root, file) {
17
+ const abs = isAbsolute(file) ? normalize(file) : resolve(root, file);
18
+ const rel = relative(root, abs);
19
+ if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
20
+ return null;
21
+ return rel.split(sep).join("/");
22
+ }
23
+ export async function readPicture(root, file) {
24
+ const rel = inProject(root, file.trim());
25
+ if (rel === null || (await viaLink(root, rel)))
26
+ return refuse("not_in_project", `${file} is not a plain file inside the project folder. Visuals are made of pictures kept in the project (not links, and not elsewhere).`, file);
27
+ if (!PICTURE_EXT.test(rel))
28
+ return refuse("not_an_image", `${file} is not a png, jpg, webp or gif picture.`, file);
29
+ let head;
30
+ try {
31
+ const fh = await open(resolve(root, ...rel.split("/")), "r");
32
+ try {
33
+ if (!(await fh.stat()).isFile())
34
+ return refuse("not_an_image", `${file} is not a file.`, file);
35
+ const buf = Buffer.alloc(HEAD_BYTES);
36
+ const { bytesRead } = await fh.read(buf, 0, HEAD_BYTES, 0);
37
+ head = buf.subarray(0, bytesRead);
38
+ }
39
+ finally {
40
+ await fh.close();
41
+ }
42
+ }
43
+ catch (e) {
44
+ if (e instanceof RushesError)
45
+ throw e;
46
+ return refuse("unreadable", `${file} could not be read (${e.code ?? "error"}).`, file);
47
+ }
48
+ const size = imageSize(head);
49
+ if (!size || !isPictureSize(size.width, size.height))
50
+ return refuse("not_an_image", `${file} is not a picture Rushes can read the size of.`, file);
51
+ return { file: rel, width: size.width, height: size.height };
52
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rushes",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "A local review desk for video made with AI agents: timecoded notes, script edits and audio picks your agent can read and act on.",
5
5
  "keywords": [
6
6
  "video",
@@ -47,6 +47,10 @@ When the user asks to open or review a film they started in the chat, or the pro
47
47
 
48
48
  When a user starts briefing in the chat, offer to keep `brief.md` up to date as you go: run `rushes new` first, so the next session, or another tool, can pick it up.
49
49
 
50
+ ## Visuals
51
+
52
+ For stills, standalone images and carousels, register one visual per post with `rushes_add_visual`: a `name` and `pages`, each page with its pictures, one per aspect ratio, in every aspect ratio the post comes in (Rushes reads each ratio from the picture). The user marks a region, a point or the whole image in the Visuals tab and sends a batch; each note names its visual, version, page, ratio, where on the picture it is (`words`) and the `file` to open. A note with no ratio is for every ratio. Fix the pictures, register a new version with `rushes_add_visual` (`visual` and only the pages that changed, each with `n`), then `rushes_reply` to each note with `fixVersion` set to it. You never mark a note done. The full contract is in `AGENTS.md`.
53
+
50
54
  ## Reviewing and fixing
51
55
 
52
56
  1. Register what you made:
@@ -72,4 +76,4 @@ When asked to open or review work in Rushes, call `rushes_open`, then tell the u
72
76
 
73
77
  No project to show yet? Run `npx -y rushes demo <folder> --no-browser`, then `rushes_open` with `project: "<folder>"`. The demo builds a complete working example on the user's machine, with a cut, script, voice reads, music and notes already in place. Always pass `--no-browser`: without it the command stays running as the server and never returns.
74
78
 
75
- Rushes has twenty-two tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_format`, `rushes_add_variant`, `rushes_set_script`, `rushes_get_script`, `rushes_add_take`, `rushes_list_notes`, `rushes_list_assets`, `rushes_get_batch`, `rushes_reply`, `rushes_get_picks`, `rushes_set_shots`, `rushes_lock_picture`, `rushes_add_file`, `rushes_export_notes`, `rushes_log`, `rushes_get_log`, `rushes_scan`, `rushes_bring_in` and `rushes_doctor` (environment and project health check) — `rushes_add_take` stays only for compatibility and isn't used for voiceover. The full contract is in `AGENTS.md` at the package root.
79
+ Rushes has twenty-three tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_format`, `rushes_add_visual`, `rushes_add_variant`, `rushes_set_script`, `rushes_get_script`, `rushes_add_take`, `rushes_list_notes`, `rushes_list_assets`, `rushes_get_batch`, `rushes_reply`, `rushes_get_picks`, `rushes_set_shots`, `rushes_lock_picture`, `rushes_add_file`, `rushes_export_notes`, `rushes_log`, `rushes_get_log`, `rushes_scan`, `rushes_bring_in` and `rushes_doctor` (environment and project health check) — `rushes_add_take` stays only for compatibility and isn't used for voiceover. The full contract is in `AGENTS.md` at the package root.