diff --git a/apps/media/src/lib.rs b/apps/media/src/lib.rs index d26a053a..ea6c815a 100644 --- a/apps/media/src/lib.rs +++ b/apps/media/src/lib.rs @@ -3,7 +3,8 @@ //! //! raea media probe FILE duration, size, fps, codec, audio (JSON) //! raea media still FILE --at S [--width W] -o OUT.png|.jpg the frame showing at S (an image: itself), W px wide at most -//! raea media sheet FILE... [--n 12] [--width 240] -o OUT a contact sheet (n frames of one file, or each file's middle) +//! raea media sheet FILE... [--n 12] [--width 240] -o OUT a contact sheet (n frames of one file, or each file's middle), +//! and OUT.labels.json: each cell's time or file, for raea show //! raea media audio FILE [--rate 16000] [--mono] [--from S --to S] -o OUT.wav|- (- is f32le on stdout) //! raea media loudness FILE [--from S --to S] integrated LUFS, mean and peak dB, true peak //! raea media motion FILE [--from S --to S] [--fps 6] how much the picture changes (mean luma difference, YDIF) diff --git a/apps/media/src/picture.rs b/apps/media/src/picture.rs index 1e14dd17..d5d7659c 100644 --- a/apps/media/src/picture.rs +++ b/apps/media/src/picture.rs @@ -68,7 +68,51 @@ pub fn sheet(files: &[PathBuf], n: usize, w: u32, out: &Path) -> R { image::imageops::overlay(&mut sheet, &small, ((k as u32 % cols) * w) as i64, ((k as u32 / cols) * th) as i64); } save(&sheet, out)?; - Ok(json!({"wrote": out, "tiles": tiles.len(), "at": tiles.iter().map(|(t, _)| round3(*t)).collect::>(), "width": sheet.width(), "height": sheet.height()})) + // OUT.labels.json beside it (docs/callouts.feature CO2c): each cell says what it is, so raea show OUT.png labels them + let heights: Vec = tiles.iter().map(|(_, i)| (i.height() as f64 * w as f64 / i.width() as f64).round().max(1.0) as u32).collect(); + let texts: Vec = if files.len() == 1 { tiles.iter().map(|(t, _)| clock(*t)).collect() } else { files.iter().map(|f| f.file_name().unwrap_or_default().to_string_lossy().into_owned()).collect() }; + let labels = out.with_extension("labels.json"); + std::fs::write(&labels, serde_json::to_string_pretty(&json!({"labels": cell_labels(&texts, &heights, w, th, cols, rows)})).unwrap_or_default()).map_err(|e| format!("{}: {e}", labels.display()))?; + Ok(json!({"wrote": out, "labels": labels, "tiles": tiles.len(), "at": tiles.iter().map(|(t, _)| round3(*t)).collect::>(), "width": sheet.width(), "height": sheet.height()})) +} + +/// Each cell's label: its text and its box in the sheet's own 0-1 (a cell `w` wide, its picture `heights[k]` tall in a row +/// `th` tall), in the sheet's order, left to right then down. +fn cell_labels(texts: &[String], heights: &[u32], w: u32, th: u32, cols: u32, rows: u32) -> Vec { + let (sw, sh) = ((cols * w) as f64, (rows * th) as f64); + let r4 = |v: f64| (v * 1e4).round() / 1e4; + texts.iter().zip(heights).enumerate().map(|(k, (text, h))| { + let (x, y) = (((k as u32 % cols) * w) as f64, ((k as u32 / cols) * th) as f64); + json!({"text": text, "box": [r4(x / sw), r4(y / sh), r4((x + w as f64) / sw), r4((y + *h as f64) / sh)]}) + }).collect() +} + +/// A moment as a cell's tag: 0:03.2, 1:05.0 +fn clock(t: f64) -> String { + let d = (t.max(0.0) * 10.0).round() as u64; + format!("{}:{:04.1}", d / 600, (d % 600) as f64 / 10.0) +} + +#[cfg(test)] +mod sheet_tests { + use super::*; + + #[test] + fn a_sheets_cells_are_labelled_by_their_boxes() { + // five cells, four across: the second row's one cell, a shorter picture than its row + let texts: Vec = ["a", "b", "c", "d", "e"].map(String::from).to_vec(); + let l = cell_labels(&texts, &[135, 135, 135, 135, 90], 240, 135, 4, 2); + assert_eq!(l[0], json!({"text": "a", "box": [0.0, 0.0, 0.25, 0.5]})); + assert_eq!(l[3], json!({"text": "d", "box": [0.75, 0.0, 1.0, 0.5]})); + assert_eq!(l[4], json!({"text": "e", "box": [0.0, 0.5, 0.25, 0.8333]})); + } + + #[test] + fn a_moment_reads_as_a_clock() { + assert_eq!(clock(3.24), "0:03.2"); + assert_eq!(clock(59.96), "1:00.0"); + assert_eq!(clock(65.0), "1:05.0"); + } } // ---- sound diff --git a/docs/callouts.feature b/docs/callouts.feature new file mode 100644 index 00000000..c25f5f4f --- /dev/null +++ b/docs/callouts.feature @@ -0,0 +1,118 @@ +@spec +Feature: Callouts: an agent's labels on what it made, beside it, pointing in when looked at + Shane, 2026-11-18: "whenever it makes a image or video, it will like combine a bunch of frames and say the left is + this, the middle is this, the last is this ... label the frames within an image or within a video ... it can just + look like little tags if they were really short, but ... opening it up to have like a paragraph of information if + ... the agent wants to. So instead of just like putting it in the title of the image of left this, bottom this, right + this, whatever, now it can have ... these labels show up like in the UI, not overlapping any of the imagery. Like we + would want it in the like periphery, like in the canvas area ... not an edge, like we don't want to use the edge + components, but like some sort of little like armature thing that just comes over and animates when you hover, just + to be sure that we're pointing at the right thing ... we could even utilize that same aspect for specific call out + to the elements within scenes ... link these little armature comments to like the 3D scene elements that can be ... + hovered on." + + What there was (read 11-18): an agent that put several frames in one still (a contact sheet from `raea media sheet`, + a side by side, a before and after, a grid of props) said which was which in the item's title or in its message: + "left: v1, middle: v2, right: v3". The person's own notes have pins and marks on the picture (docs/fingerprint.feature + FP11a) and in a scene's space (docs/scene-feed.feature SF3), but those are comments, asking for something. Nothing let + the agent say what a part of its own picture is. + + The callout: + - A label is the agent's: a tag of a few words, and a paragraph more when there is more to say. It points at a + place in what was made: a box or a point on a picture, a still of a storyboard, a moment or a span of a film, a + part of a 3D scene or a point in its space. + - It is never drawn over the picture. The tags stand in the canvas around it, each on the side nearest the place it + names, in that place's order, apart from each other. + - Pointing is on hover: the tag's armature, a thin line with one bend, draws out from the tag to the place, and the + place's corners are marked. Moving away, it draws back. Nothing is drawn on the picture until then. + - It isn't a comment: it asks nothing and goes to no agent. It is part of the item, as its title is. + + Background: + Given the app's code is apps/app (raea-feed): src/model/labels.ts, src/detail/blocks/Callouts.tsx, the views that + draw them (src/detail/views Look.tsx, Watch.tsx, Scene.tsx), and how they come in (src/acp/post.ts, host/show.ts, + src/acp/protocol.ts feed_post) + And raea's own side: `raea show --label` (engine/cli/src/show.ts) and the sheet's labels (apps/media picture.rs) + + Rule: CO1. A label, and what it can point at + # Status 11-18: in 0.1.8. The feed draws them (raea-feed labels: a still, a film, a scene's parts live, the card's + # count); raea show takes --label, --detail and --labels; raea media sheet writes OUT.labels.json; the raea skill says + # when to label (CO5a). + + Scenario: CO1a. A tag and a paragraph + Given a label + Then its tag is its text, a few words (up to 60 characters; longer is cut, with the rest put first in its + paragraph) + And its detail, when it has one, is a paragraph (up to 1200 characters) the tag opens + + Scenario: CO1b. Where it points + Then a label names one place: a box (x0, y0, x1, y1) or a point (x, y) in the picture's own 0-1 coordinates + And with frame N, the storyboard's still N (from 0, as a still's pin is) instead of the first + And with t (and to), a film's moment (or span) in seconds: it is drawn while the playhead is within half a second + of the moment, or in the span + And with part, a 3D scene's part by its source key or its name; with space, a point in the scene's space; with + entry, which of a board's scenes + And a label that names no place it can be drawn at is kept off the stage and listed under the picture instead + + Rule: CO2. How labels come in + Scenario: CO2a. feed_post takes labels + When an agent posts with feed_post and labels: [{ text, detail?, box? | point? | part? | space?, frame?, t?, to? }] + Then the item has them, cleaned: up to 24, numbers held to 0-1, an empty tag dropped, a box's corners put in order + And a label it can't read is said back in the post's answer, not dropped quietly + + Scenario: CO2b. raea show takes labels + When an agent runs raea show FILE --label "PLACE TAG" [--detail "PARAGRAPH"] ... + Then PLACE is x0,y0,x1,y1 or x,y, then #N for the Nth file shown (from 1), @T or @T-TO for a film's seconds, or + part=KEY for a scene's part, joined without spaces (0,0,.5,1#2@3-5); the tag is the rest + And a --detail is the paragraph of the --label before it + And --labels FILE.json gives them as feed_post does + + Scenario: CO2c. A contact sheet comes labelled + When raea media sheet writes OUT.png + Then it writes OUT.labels.json beside it: each cell's box and its time ("0:03.2"), or its file's name for a sheet of + several files + And raea show OUT.png takes OUT.labels.json along when it is there, so the sheet's cells say what they are with + nothing more done; an agent that wants to say more edits the JSON's tags and paragraphs first + + Rule: CO3. Drawn beside the picture, never on it + Scenario: CO3a. In the canvas around the picture + Given a still, a film or a scene with labels, opened + Then each label's tag stands in the canvas beside the picture, on the left or right, whichever the place it names + is nearer, or below when neither side has room + And tags on a side are in the order of their places from the top, and never overlap each other or the picture + And as the picture is zoomed or panned, or the stage resized, they keep to its sides + + Scenario: CO3b. On a film, in time + Given a film's labels with moments or spans + Then a label stands while the playhead is in its time and fades out of it; one with no time stands throughout + + Rule: CO4. Pointing, on hover + Scenario: CO4a. The armature + When the pointer is on a tag (or on the place it names, for a box) + Then the tag's armature draws out from the tag to the nearest edge of its place (a box) or to its point: along + the side's margin, one bend at the picture's edge, then in + And the place's corners are marked while it's out + And moving off, it draws back + And with reduced motion it appears and goes without drawing + + Scenario: CO4b. The paragraph + When a tag with a paragraph is clicked + Then the paragraph opens under the tag, in the margin, and the armature stays out while it's open + And Esc or a click elsewhere closes it + + Scenario: CO4c. A scene's part + Given a label on a scene's part + When its tag is hovered + Then the armature goes to the part as the stage draws it now, and the part is outlined as when the pointer is on it + And it follows the camera and the scene's time as they move + + Rule: CO5. The agent's skill says when to label + Scenario: CO5a. Label, don't title + Then the raea skill says: when one picture holds several things (a sheet, a side by side, before and after, a grid + of props or characters), label each instead of naming them by position in the title or the message, with a + paragraph only where a tag isn't enough + And it shows raea show sheet.png --label "0,0,.5,1 v1, hook first" --label ".5,0,1,1 v2, product first" + --detail "Opens on the product..." + + Rule: CO6. On the feed's card + Scenario: CO6a. Labels on the feed's card + Then the card shows how many labels the item has, and not the tags themselves, until a card has room for them diff --git a/engine/cli/conformance/show.test.ts b/engine/cli/conformance/show.test.ts index 1b5680c0..26109a64 100644 --- a/engine/cli/conformance/show.test.ts +++ b/engine/cli/conformance/show.test.ts @@ -2,7 +2,7 @@ // R3), and where a note read from one stands (docs/direction.feature DR5, DR6): its asks, its badge and each ask's, // and a clip under an ask for the person to sign. The host (apps/app/host/tasks.ts) is faked: this is the command's side. import { describe, expect, test } from "bun:test"; -import { showVerb } from "../src/show.ts"; +import { labelsIn, showVerb } from "../src/show.ts"; /** showVerb with a host that keeps each op it was asked, and answers a task as the host does. */ function run(args: string[]) { @@ -54,3 +54,59 @@ describe("raea show --working, for a note", () => { refused(["--working", "cm-1", "--ask", "one", "--states", "to check,failing"], "one state for each --ask: 1 asks, 2 states"); }); }); + +// labels on what's shown (docs/callouts.feature CO2b): what the command sends the host, which reads each place +describe("raea show --label", () => { + const shown = (args: string[], listed?: unknown[]) => { + const ops: [string, Record][] = []; + const ask = (op: string, b: Record) => { + ops.push([op, b]); + if (op === "harness") return { name: "Claude Code", pid: 7 }; + return { kind: "item", id: "i-1", type: "look", title: "Three cuts", project: "shop", workspace: "Work", inbox: "/inbox.jsonl" }; + }; + showVerb(ask, args, "/work/shop", { CLAUDECODE: "1", CLAUDE_CODE_SESSION_ID: "abcdef123" }, listed); + return ops.find(([op]) => op === "show")?.[1]; + }; + + test("each --label is a place and its tag, a --detail the paragraph of the one before it", () => { + const b = shown(["out/three.png", "--label", "0,0,.5,1 v1, hook first", "--label", ".5,0,1,1#2@3-5 v2", "--detail", "Opens on the product.", "--title", "Three cuts"]); + expect(b?.files).toEqual(["/work/shop/out/three.png"]); + expect(b?.labels).toEqual([ + { place: "0,0,.5,1", text: "v1, hook first" }, + { place: ".5,0,1,1#2@3-5", text: "v2", detail: "Opens on the product." }, + ]); + expect(b?.title).toBe("Three cuts"); + }); + + test("a scene part's key keeps its colons", () => { + expect(shown(["room.tsx", "--label", "part=room.tsx:46:7 the crate"])?.labels).toEqual([{ place: "part=room.tsx:46:7", text: "the crate" }]); + }); + + test("no labels: none sent, so a sheet's own OUT.labels.json comes along", () => { + expect(shown(["out/sheet.png"])).not.toHaveProperty("labels"); + }); + + test("--labels sends the file's list as it is", () => { + const list = [{ text: "0:01.5", box: [0, 0, 0.25, 0.5] }]; + expect(shown(["out/sheet.png", "--labels", "mine.json"], list)?.labels).toEqual(list); + }); + + test("what isn't a label is refused, saying what one is", () => { + expect(() => shown(["a.png", "--label", "v1"])).toThrow(/--label "v1" is a place, then its tag/); + expect(() => shown(["a.png", "--detail", "why"])).toThrow(/--detail goes after the --label/); + expect(() => shown(["a.png", "--label", "0,0 a", "--detail", "x", "--detail", "y"])).toThrow(/one --detail for the label "a"/); + expect(() => shown(["--question", "Which?", "--choice", "A", "--choice", "B", "--label", "0,0 a"])).toThrow(/labels go on the files you show/); + expect(() => shown(["a.png", "--label", "0,0 a", "--labels", "l.json"], [])).toThrow(/--label or --labels, not both/); + }); +}); + +describe("labelsIn", () => { + test("a list, or { labels }", () => { + expect(labelsIn('[{"text":"a"}]', "l.json")).toEqual([{ text: "a" }]); + expect(labelsIn('{"labels":[{"text":"b"}]}', "l.json")).toEqual([{ text: "b" }]); + }); + test("anything else is refused, naming the file", () => { + expect(() => labelsIn("{", "l.json")).toThrow(/--labels l.json isn't JSON/); + expect(() => labelsIn('{"text":"a"}', "l.json")).toThrow(/--labels l.json is a list of labels/); + }); +}); diff --git a/engine/cli/src/cli.rs b/engine/cli/src/cli.rs index e2e4735f..85191cf0 100644 --- a/engine/cli/src/cli.rs +++ b/engine/cli/src/cli.rs @@ -134,7 +134,7 @@ pub fn run(args: &[String]) -> R { IN_HELP.set(was); // `raea library` (engine/cli/src/library.ts) and `raea show` (show.ts: in the raea app, not Preview, Shane 11-09), under render's usage let usage = format!("{usage}\n raea library [new NAME [--cloud] | add LIBRARY PATH | files LIBRARY | tag SHA TAGS | status | scan ...] | raea library search \"WORDS\" [--library LIBRARY] [--kind KIND] [--limit N] [--sound] (the person's libraries in the raea app: folders and drives indexed on this machine, searched by meaning; a folder an agent adds waits for the person's yes)"); - let usage = format!("{usage}\n raea show FILE... [--title T] [--ask LINE] [--project P] [--replaces ITEM] [--as NAME] [--role ROLE] [--inbox NAME] [--open] | raea show --question Q --choice A --choice B [STILL...] | raea show [--title T] --question Q [--preview FILE] --choice A [--preview FILE] --choice B ... [--question Q2] ... | raea show --on ITEM [--working ID] [--ask TEXT] [--status S] [--states S1,S2] [--sign N --clip FILE --render HASH] [--done ID] [--note LINE] [--sub NAME] (shown in the raea app as an item the person can use and answer, posted quietly with a notice, the window left where they are unless --open: stills (several, a storyboard), a video, a sound, a NAME.script.ts or .md, a .tsx (an interactive artifact; a project's composition opens in its editor), or questions, all of them one item, each question and choice with a --preview to play or read while answering (a still, a video, a sound, a script or .md; after a --choice that choice's, else the question's); what they send comes to ~/.raea/inbox/INBOX.jsonl; their edit comments are tasks: --working ID as you start one (each --ask with it one ask you read it as, for the person to correct; --status and --states where the note and each ask stand: to restate, to check, failing, to sign, passing, signed; --sign N --clip FILE --render HASH a clip under ask N for them to sign; a note closes when they retire it, never with --done), --done ID when it's settled, or with the version that settles it, FILE --replaces ITEM --done ID; never open media in Preview while the app is installed)"); + let usage = format!("{usage}\n raea show FILE... [--title T] [--ask LINE] [--project P] [--replaces ITEM] [--as NAME] [--role ROLE] [--inbox NAME] [--open] [--label LABEL] [--detail PARAGRAPH] [--labels FILE.json] | raea show --question Q --choice A --choice B [STILL...] | raea show [--title T] --question Q [--preview FILE] --choice A [--preview FILE] --choice B ... [--question Q2] ... | raea show --on ITEM [--working ID] [--ask TEXT] [--status S] [--states S1,S2] [--sign N --clip FILE --render HASH] [--done ID] [--note LINE] [--sub NAME] (shown in the raea app as an item the person can use and answer, posted quietly with a notice, the window left where they are unless --open: stills (several, a storyboard), a video, a sound, a NAME.script.ts or .md, a .tsx (an interactive artifact; a project's composition opens in its editor), or questions, all of them one item; --label \"PLACE TAG\" a label beside the picture, never on it, that points at PLACE (x0,y0,x1,y1 or x,y in its 0-1, then #N the Nth file, @T or @T-TO a film's seconds, or part=KEY a scene's part; the tag the rest), --detail the paragraph of the --label before it, --labels a JSON list of them as feed_post takes them, and a sheet raea media sheet made comes labelled; each question and choice with a --preview to play or read while answering (a still, a video, a sound, a script or .md; after a --choice that choice's, else the question's); what they send comes to ~/.raea/inbox/INBOX.jsonl; their edit comments are tasks: --working ID as you start one (each --ask with it one ask you read it as, for the person to correct; --status and --states where the note and each ask stand: to restate, to check, failing, to sign, passing, signed; --sign N --clip FILE --render HASH a clip under ask N for them to sign; a note closes when they retire it, never with --done), --done ID when it's settled, or with the version that settles it, FILE --replaces ITEM --done ID; never open media in Preview while the app is installed)"); // clothes for SOMA's body, sewn or laid on the skin (docs/character.feature CH45c): engine/cli/src/clothes.ts, wardrobe.ts and sewn.ts let usage = format!("{usage}\n raea clothes [make NAME [\"WHAT IT IS\"] [--plain] [--set PATH=VALUE,...] [--colour #RRGGBB] | settings | cover NAME --parts PART[:SHARE],... --colour #RRGGBB [--stand MM] [--over UNDER] [--hard [--sole MM] [--sole-colour #RRGGBB] [--panels #RRGGBB,...]] | wear OUT_DIR GARMENT... [--body DIR] [--head HEAD_DIR]] (clothes for SOMA's body from words: make sews a garment: a sewing pattern (GarmentCode, MIT) from the words, or the plain base with --plain, its settings changed by --set PATH=VALUE (settings lists them and what each may be), cut to SOMA's measurements, draped by raea's own cloth and baked, as assets/clothes/NAME.json and its .glb, in --colour or the palette's next; the first make sets up GarmentCode and its Python in raea's models folder; cover makes one by procedure in the same file, no picture: the skin of the parts named (hips, waist, torso, chest, neck, head, upperArm, foreArm, hand, thigh, shin, foot, toes; a limb's SHARE is how far along it from its top), in one colour, MM off the skin (6 unless said), --over a garment already made as the one under it; wear puts garments on a body, innermost first (each GARMENT a name or its .json): OUT_DIR/NAME.glb each, with OUT_DIR/body.glb the body without the skin wholly under cloth; --body DIR another SOMA body folder (a headless one for a head part); --head HEAD_DIR the head that joins it (head.json), whose skin the body's is graded to at the collar; alone, the project's garments. The first use fetches SOMA's body (NVlabs/SOMA-X, Apache-2.0) into raea's models folder and needs Blender: raea setup blender)"); // body motion made by Kimodo, on MLX on a Mac and on PyTorch elsewhere (docs/character.feature CH15c): diff --git a/engine/cli/src/index.ts b/engine/cli/src/index.ts index 1e7fdfed..2b83fcc1 100644 --- a/engine/cli/src/index.ts +++ b/engine/cli/src/index.ts @@ -24,7 +24,7 @@ const out = (stdout: string, exitCode = 0, stderr = "") => ({ stdout, stderr, ex // `raea library` (library.ts), kept apart from the imports above import { libraryVerb } from "./library"; // `raea show` (show.ts): what a session shows the person, in the raea app -import { showVerb } from "./show"; +import { labelsIn, showVerb } from "./show"; // `raea clothes` (clothes.ts): garments for SOMA's body from words import { clothesVerb } from "./clothes"; // `raea bug` (bug.ts): an agent's report of a bug in raea, to raea's server @@ -267,8 +267,18 @@ export function raeaHandler(host?: Host, engine?: Engine) { } case "library": return out(libraryVerb(ask, args.slice(1), (globalThis as { process?: { env: Record } }).process?.env ?? {})); - case "show": - return out(showVerb(ask, args.slice(1), c.cwd, (globalThis as { process?: { env: Record } }).process?.env ?? {})); + case "show": { + // --labels FILE.json: read here, where the shell's files are (show.ts labelsIn) + const at = args.lastIndexOf("--labels"); + const file = at > 0 ? args[at + 1] : undefined; + let listed: unknown[] | undefined; + try { + listed = file === undefined ? undefined : labelsIn(await c.fs.readFile(p(file), "utf8"), file); + } catch (e) { + return out("", 2, `raea show: ${(e as Error).message.startsWith("--labels") ? (e as Error).message : `--labels ${file}: ${(e as Error).message}`}\n`); + } + return out(showVerb(ask, args.slice(1), c.cwd, (globalThis as { process?: { env: Record } }).process?.env ?? {}, listed)); + } case "clothes": return out(clothesVerb(ask, args.slice(1))); case "bug": diff --git a/engine/cli/src/show.ts b/engine/cli/src/show.ts index 50b15d7d..35e02aac 100644 --- a/engine/cli/src/show.ts +++ b/engine/cli/src/show.ts @@ -26,6 +26,14 @@ raea show [--title T] --question Q1 [--preview FILE] --choice A [--preview FILE] lists them), a folder in the project, or a Copy reference from the app; a title only when it's the only one and this folder isn't in another project. Else the one this folder is in. Who's showing it: --as NAME [--role ROLE] [--inbox NAME], else your harness's. +raea show FILE... --label "PLACE TAG" [--detail "PARAGRAPH"] --label ... | --labels LABELS.json + Labels say what's where in what you show: each tag stands beside the picture, never on it, and points at its place + when the person's pointer is on it. PLACE is x0,y0,x1,y1 or x,y in the picture's own 0-1, then #N for the Nth file + shown (from 1), @T or @T-TO for a film's seconds, or part=KEY for a scene's part (its source key, or its name), + joined without spaces (0,0,.5,1#2@3-5); the tag is the rest, a few words. A --detail is the paragraph its --label + opens, where a tag isn't enough. --labels gives them as feed_post takes them. A sheet raea media sheet wrote comes + labelled by itself (its OUT.labels.json, beside it). When one picture holds several things (a sheet, a side by side, + a grid), label each instead of naming them by position in the title. raea show --on ITEM --working ID... [--ask TEXT]... [--status S [--states S1,S2...]] | --done ID... [--note LINE] [--sub NAME] raea show --on ITEM --working ID --sign N --clip FILE --render HASH raea show FILE... --replaces ITEM --done ID... @@ -37,7 +45,7 @@ raea show FILE... --replaces ITEM --done ID... closes when the person retires it, never with --done. raea notes post sends all of these from the notes. `; -const WITH_VALUE = new Set(["--title", "--ask", "--project", "--replaces", "--as", "--role", "--inbox", "--question", "--choice", "--preview", "--on", "--working", "--done", "--note", "--sub", "--status", "--states", "--sign", "--clip", "--render"]); +const WITH_VALUE = new Set(["--label", "--detail", "--labels", "--title", "--ask", "--project", "--replaces", "--as", "--role", "--inbox", "--question", "--choice", "--preview", "--on", "--working", "--done", "--note", "--sub", "--status", "--states", "--sign", "--clip", "--render"]); const FLAGS = new Set(["--open"]); /** The harness an agent runs in, named as the feed shows it, from the program that started this command (native.ts @@ -77,9 +85,20 @@ export function parseShow(args: string[], cwd: string) { // the questions in order: each --question starts one and its --choice's follow; a --preview after a --choice is that // choice's, after the --question (before any choice) the question's own const asked: { ask: string; choices: { label: string; preview?: string }[]; preview?: string }[] = []; + // the labels in order (docs/callouts.feature CO2b): each --label a place and its tag, a --detail its paragraph + const labels: { place: string; text: string; detail?: string }[] = []; for (let i = 0; i < args.length; i++) { const v = args[i + 1]; - if (args[i] === "--question" && v !== undefined) asked.push({ ask: v, choices: [] }); + if (args[i] === "--label" && v !== undefined) { + const m = /^\s*(\S+)\s+(\S[\s\S]*)$/.exec(v); + if (!m) throw new Error(`--label "${v}" is a place, then its tag: --label "0,0,.5,1 v1, hook first"\n${SHOW_USAGE}`); + labels.push({ place: m[1], text: m[2].trim() }); + } else if (args[i] === "--detail" && v !== undefined) { + const l = labels.at(-1); + if (!l) throw new Error(`--detail goes after the --label whose paragraph it is\n${SHOW_USAGE}`); + if (l.detail !== undefined) throw new Error(`one --detail for the label "${l.text}"\n${SHOW_USAGE}`); + l.detail = v; + } else if (args[i] === "--question" && v !== undefined) asked.push({ ask: v, choices: [] }); else if (args[i] === "--choice" && v !== undefined) asked.at(-1)?.choices.push({ label: v }); else if (args[i] === "--preview" && v !== undefined) { const q = asked.at(-1); @@ -92,11 +111,27 @@ export function parseShow(args: string[], cwd: string) { if (args.includes("--choice") && args.indexOf("--choice") < args.indexOf("--question")) throw new Error(`a --choice goes after its --question\n${SHOW_USAGE}`); // several questions, or any preview: one item with them all (host/show.ts questions); else the one question as before const questions = asked.length > 1 || asked.some((q) => q.preview || q.choices.some((c) => c.preview)) ? asked : undefined; + if ((labels.length || args.includes("--labels")) && (!files.length || questions || asked.length)) throw new Error(`labels go on the files you show: raea show FILE --label "PLACE TAG"\n${SHOW_USAGE}`); + if (labels.length && args.includes("--labels")) throw new Error(`--label or --labels, not both\n${SHOW_USAGE}`); if (questions && files.length) throw new Error(`with several questions or previews, each file is a --preview of the question or choice it shows\n${SHOW_USAGE}`); - return { files, choices, questions, open: args.includes("--open"), title: one("--title"), ask: one("--ask"), asks: many("--ask"), project: one("--project"), replaces: one("--replaces"), question: questions ? undefined : one("--question"), as: one("--as"), role: one("--role"), inbox: one("--inbox"), on: one("--on"), working: many("--working"), done: many("--done"), note: one("--note"), sub: one("--sub"), status: one("--status"), states: one("--states")?.split(",").map((s) => s.trim()).filter(Boolean), sign: one("--sign"), clip: one("--clip"), render: one("--render") }; + return { labels, labelsFile: one("--labels"), files, choices, questions, open: args.includes("--open"), title: one("--title"), ask: one("--ask"), asks: many("--ask"), project: one("--project"), replaces: one("--replaces"), question: questions ? undefined : one("--question"), as: one("--as"), role: one("--role"), inbox: one("--inbox"), on: one("--on"), working: many("--working"), done: many("--done"), note: one("--note"), sub: one("--sub"), status: one("--status"), states: one("--states")?.split(",").map((s) => s.trim()).filter(Boolean), sign: one("--sign"), clip: one("--clip"), render: one("--render") }; } -export function showVerb(ask: Ask, args: string[], cwd: string, env: Record): string { +/** A --labels file's labels, as feed_post takes them: a list, or { "labels": [...] } (raea media sheet's OUT.labels.json). */ +export function labelsIn(text: string, name: string): unknown[] { + let json: unknown; + try { + json = JSON.parse(text); + } catch (e) { + throw new Error(`--labels ${name} isn't JSON: ${(e as Error).message}`); + } + const list = Array.isArray(json) ? json : (json as { labels?: unknown } | null)?.labels; + if (!Array.isArray(list)) throw new Error(`--labels ${name} is a list of labels, or { "labels": [...] }, each { text, detail?, box? | point? | part?, frame?, t?, to? }`); + return list; +} + +/** `listed`: the --labels file's labels, read by the caller (labelsIn), which has the files. */ +export function showVerb(ask: Ask, args: string[], cwd: string, env: Record, listed?: unknown[]): string { if (!args.length || args[0] === "--help") return SHOW_USAGE; const a = parseShow(args, cwd); const parent = (): { name: string; pid: number } | undefined => { @@ -132,7 +167,9 @@ export function showVerb(ask: Ask, args: string[], cwd: string, env: Record