toolroll 0.9.25 → 0.9.27

package/dist/browser-workspace.d.ts

@@ -2,6 +2,7 @@
  * produced by the existing trusted server renderers, never by a model-supplied
  * fragment. These projections do not authenticate, mutate or grant authority. */
 import type { TeamSnapshot } from './team-contract.js';
+import type { BrandIconId } from './brand-icons.js';
 import type { AssignmentSnapshot } from './assignment.js';
 export { browserCrewFromIndex, browserWorkActionHref } from './browser-crew.js';
 import type { Store } from './store.js';
@@ -281,11 +282,13 @@ export type BrowserSettingsView = {
     /** Settings → Updates: this version, the latest known one and its notes, how to update, the daily-check switch, and each worker's version. */
     updates?: BrowserUpdates | null;
 };
+/** A tile's `brand` is a chat app's logo (brand-mark.ts), drawn in place of its icon. */
 export type BrowserSettingsGroup = {
     title: string;
     tiles: {
         href: string;
         label: string;
+        brand?: BrandIconId;
         status?: {
             tone: 'ok' | 'warn' | 'off';
             words: string;
@@ -822,6 +825,18 @@ export type BrowserFlowStage = {
     onFail: string | null;
 };
 /** One card: a piece of work, where it is, what it waits on, what zones said. */
+/** After research, one of the report's items as the message numbered it, with its screenshot when it has one. */
+export type BrowserFlowSentItem = {
+    number: number;
+    title: string;
+    lines: string[];
+    source: string;
+    url: string;
+    image: {
+        src: string;
+        caption: string;
+    } | null;
+};
 export type BrowserFlowCard = {
     id: number;
     title: string;
@@ -912,6 +927,7 @@ export type BrowserFlowCard = {
             label: string;
             href: string;
         }[];
+        items?: BrowserFlowSentItem[];
         person: string;
         mine: boolean;
         options: {
@@ -928,6 +944,7 @@ export type BrowserFlowCard = {
             label: string;
             href: string;
         }[];
+        items?: BrowserFlowSentItem[];
         person: string;
         at: string;
     } | null;

package/dist/chat-delivery.js

@@ -840,18 +840,18 @@ export async function planChatNotifications(options) {
                     }
                     else if (notification.kind === "flow-decision") {
                         // The draft as written, and Approve / Edit / Send back on its last part; a card that moved on is not news.
-                        const parts = flowDecisionParts(store, notification);
+                        const parts = flowDecisionParts(store, notification, state.channel);
                         if (parts !== null) {
                             state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
                                 ts: "", thread: "", payload: "{}", created: now.toISOString() });
                             state.plan(id, parts, now);
                         }
                     }
-                    else if (personal && flowSendParts(store, notification) !== null) {
+                    else if (personal && flowSendParts(store, notification, state.channel) !== null) {
                         // A flow's "Send to me" (flow-send.ts): what was done, with its links as buttons.
                         state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
                             ts: "", thread: "", payload: "{}", created: now.toISOString() });
-                        state.plan(id, flowSendParts(store, notification), now);
+                        state.plan(id, flowSendParts(store, notification, state.channel), now);
                     }
                     else if (notification.kind === "flow-card" && questionParts(store, notification, binding) !== null) {
                         // A teammate's question (v93): its options and "Answer in words" on the notice, for the person it asks.

package/dist/chat-flow.d.ts

@@ -4,12 +4,13 @@ export type ChatFlowAction = "approve" | "edit" | "send-back";
 export declare const CHAT_FLOW_LABELS: Record<ChatFlowAction, string>;
 /** Words kept as written, line breaks and all; only control characters go. */
 export declare function chatFlowText(text: string): string;
+type ChatApp = "slack" | "discord" | "teams";
 /** A "Send to me" notice as chat parts: what was done, then its links; null when it isn't one. */
 export declare function flowSendParts(store: Store, notification: {
     dedupeKey: string;
     subject: string;
     body: string;
-}): ChatContent[] | null;
+}, app?: ChatApp): ChatContent[] | null;
 /**
  * A "flow-decision" notice as chat parts, or null when it isn't one (or the
  * card has already moved on, and there is nothing left to decide).
@@ -19,7 +20,7 @@ export declare function flowDecisionParts(store: Store, notification: {
     subject: string;
     body: string;
     link: string | null;
-}): ChatContent[] | null;
+}, app?: ChatApp): ChatContent[] | null;
 /** The live buttons on one part, in the order they were minted: a decision's, a choice's options in their order, or
  * "Use this as your note?" Yes / No. `key` is unique on the part (Slack names each button by it). */
 export declare function chatFlowButtons(state: ChatState, part: number, now: Date): Array<{
@@ -65,3 +66,4 @@ export declare function answerChatFlowPrompt(options: {
     text: string;
     originalLength?: number;
 }, repos: readonly string[], now: Date): boolean;
+export {};

package/dist/chat-flow.js

@@ -27,7 +27,9 @@
  */
 import { keptDraft } from "./flow-draft.js";
 import { decideFlowCard, flowCardHref, flowDefinitionOf } from "./flow-engine.js";
-import { chooseFlowCard, flowChoiceAt, flowSendPaths, FLOW_CHOOSE_KEY, FLOW_SEND_KEY, readFlowSend } from "./flow-send.js";
+import { chooseFlowCard, flowChoiceAt, flowSendPaths, flowSendTail, FLOW_CHOOSE_KEY, FLOW_SEND_KEY, readFlowSend } from "./flow-send.js";
+import { cleanFlowMessage, fitFlowMessage } from "./flow-items.js";
+import { renderReply } from "./reply-shape.js";
 import { deciderOf, replyTarget } from "./flows.js";
 import { MATE_MESSAGE_MAX_CHARS } from "./mate.js";
 import { verifyApproverStanding } from "./principal.js";
@@ -71,13 +73,27 @@ function decisionParts(text, visit, link) {
 function sendLinks(paths) {
     return { ...(paths[0] === undefined ? {} : { link: paths[0] }), ...(paths.length > 1 ? { also: paths.slice(1) } : {}) };
 }
+/** The most an item list's part carries here, as the app renders it — a Slack section (2,800), Discord's plain message
+ * content (2,000), a Teams message as long as Telegram's — less room for the line a tap adds under it. */
+const ITEMS_LIMIT = { slack: PART_CHARS - 300, discord: 2000 - 300, teams: 4096 - 300 };
+/** After research (flow-items.ts): the message with each item numbered under the summary, its words cleaned as every
+ * other flow message's are, in as few parts as the app's limit allows (one, unless head, links and tail alone overflow). */
+function itemsText(content, subject, app) {
+    if (app === undefined || content.items === undefined || content.items.length === 0)
+        return null;
+    const message = cleanFlowMessage({ head: subject, summary: content.summary, items: content.items, tail: flowSendTail(content) }, chatFlowText);
+    return fitFlowMessage(message, ITEMS_LIMIT[app], shaped => renderReply(shaped, app).length);
+}
 /** A "Send to me" notice as chat parts: what was done, then its links; null when it isn't one. */
-export function flowSendParts(store, notification) {
+export function flowSendParts(store, notification, app) {
     const visit = FLOW_SEND_KEY.exec(notification.dedupeKey);
     const kept = visit === null ? null : store.flowSend(Number(visit[1]), Number(visit[2]));
     const content = kept === null ? null : readFlowSend(kept.contentJson);
     if (content === null)
         return null;
+    const voiced = itemsText(content, notification.subject, app);
+    if (voiced !== null)
+        return voiced.map((text, index) => index < voiced.length - 1 ? { text, voice: true } : { text, voice: true, ...sendLinks(flowSendPaths(content)) });
     const all = pieces(chatFlowText(`${notification.subject}\n\n${notification.body}`));
     return all.map((piece, index) => index < all.length - 1 ? { text: piece } : { text: piece, ...sendLinks(flowSendPaths(content)) });
 }
@@ -85,7 +101,7 @@ export function flowSendParts(store, notification) {
  * A "flow-decision" notice as chat parts, or null when it isn't one (or the
  * card has already moved on, and there is nothing left to decide).
  */
-export function flowDecisionParts(store, notification) {
+export function flowDecisionParts(store, notification, app) {
     const choose = FLOW_CHOOSE_KEY.exec(notification.dedupeKey);
     if (choose !== null) {
         const visit = flowChoiceAt(store, Number(choose[1]), Number(choose[2]));
@@ -94,6 +110,10 @@ export function flowDecisionParts(store, notification) {
         if (visit === null || content === null)
             return null;
         const options = (content.options ?? []).filter(one => visit.stage.options?.[one.choice]?.label === one.label);
+        const voiced = itemsText(content, notification.subject, app);
+        if (voiced !== null)
+            return voiced.map((text, index) => index < voiced.length - 1 ? { text, voice: true }
+                : { text, voice: true, choose: { card: visit.card.id, entry: visit.card.entry, options }, ...sendLinks(flowSendPaths(content)) });
         const all = pieces(chatFlowText(`${notification.subject}\n\n${notification.body}`));
         return all.map((piece, index) => index < all.length - 1 ? { text: piece }
             : { text: piece, choose: { card: visit.card.id, entry: visit.card.entry, options }, ...sendLinks(flowSendPaths(content)) });
@@ -124,7 +144,9 @@ const retire = (state, card, entry, now) => {
 function repaint(state, part, event, line) {
     const row = state.prepare("SELECT payload FROM chat_part WHERE id=?").get(part);
     const before = row === undefined ? { text: "" } : JSON.parse(String(row["payload"]));
-    const content = { text: `${before.text}\n\n${line}`.slice(0, PART_CHARS + 400), edit: event.ts, ...(before.link === undefined ? {} : { link: before.link }), ...(before.channel === undefined ? {} : { channel: before.channel }) };
+    // An item list (flow-items.ts) stays whole and keeps its bold titles and labelled links; only plain text is capped.
+    const content = { text: before.voice === true ? `${before.text}\n\n${line}` : `${before.text}\n\n${line}`.slice(0, PART_CHARS + 400), edit: event.ts, ...(before.voice === true ? { voice: true } : {}),
+        ...(before.link === undefined ? {} : { link: before.link }), ...(before.channel === undefined ? {} : { channel: before.channel }) };
     state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?").run(JSON.stringify(content), part);
 }
 /**

package/dist/flow-cadence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Flow passes that don't wait for builds. The worker's pass used to move
+ * cards only between builds, so a card whose research finished sat still
+ * while another build ran (Oct 4: five minutes). Now the worker runs these
+ * passes on their own cadence beside its builds, and a finished build,
+ * research or check moves its card at once.
+ *
+ * Model-free and cheap: nothing here starts a build. Cards entering a build
+ * zone file their task, which waits for a free slot like any other.
+ */
+import { type FlowAdvance } from "./flow-engine.js";
+import { type TriggerIo, type TriggerPass } from "./flow-triggers.js";
+import { type ReplyWatch, type ReplyWatchIo } from "./flow-replies.js";
+import { type StepIo, type StepPass } from "./flow-steps.js";
+import type { Store } from "./store.js";
+/** How often the worker moves cards, checks triggers, reads replies and runs steps, builds or not. */
+export declare const FLOW_EVERY_MS = 15000;
+/** One pass of a kind for a project at a time in this process: a second one asked for while it runs is skipped
+ * (`idle`), and the next cadence takes up whatever it would have done. Cards are also claimed in the database,
+ * so passes in other processes can't act twice either. */
+export declare function alone<T>(kind: string, project: string, idle: T, run: () => Promise<T>): Promise<T>;
+export type FlowIo = {
+    triggers: TriggerIo;
+    replies: ReplyWatchIo;
+    steps: StepIo;
+    evidenceRoot?: string;
+};
+export type FlowHousekeeping = {
+    triggers: TriggerPass;
+    replies: ReplyWatch;
+    steps: StepPass;
+    flows: FlowAdvance;
+};
+/** One project's flow pass: triggers (which may start cards), replies (which move waiting cards), steps, then moves.
+ * `halted` (a stop or paused admission) skips everything that reaches outside; moves still run. */
+export declare function flowHousekeeping(store: Store, repo: string, clock: () => Date, io: FlowIo, halted: () => boolean): Promise<FlowHousekeeping>;
+/** Move one project's cards. Synchronous, so two can't overlap in a process; each move is checked against the
+ * card's visit in its own transaction, so a pass in another process can't move a card twice. */
+export declare function moveCards(store: Store, repo: string, now: Date, evidenceRoot: string | undefined): FlowAdvance;
+/** A build, research or check just finished: move the cards in this project, and in the project of any flow whose
+ * card that task belongs to (a build zone may build in another project), now rather than on the next pass. */
+export declare function moveCardsAfter(store: Store, repo: string, tasks: readonly string[], now: Date, evidenceRoot: string | undefined): FlowAdvance;

package/dist/flow-cadence.js

@@ -0,0 +1,78 @@
+/**
+ * Flow passes that don't wait for builds. The worker's pass used to move
+ * cards only between builds, so a card whose research finished sat still
+ * while another build ran (Oct 4: five minutes). Now the worker runs these
+ * passes on their own cadence beside its builds, and a finished build,
+ * research or check moves its card at once.
+ *
+ * Model-free and cheap: nothing here starts a build. Cards entering a build
+ * zone file their task, which waits for a free slot like any other.
+ */
+import { advanceFlows } from "./flow-engine.js";
+import { runFlowTriggers } from "./flow-triggers.js";
+import { watchFlowReplies } from "./flow-replies.js";
+import { runFlowSteps } from "./flow-steps.js";
+/** How often the worker moves cards, checks triggers, reads replies and runs steps, builds or not. */
+export const FLOW_EVERY_MS = 15_000;
+const running = new Set();
+/** One pass of a kind for a project at a time in this process: a second one asked for while it runs is skipped
+ * (`idle`), and the next cadence takes up whatever it would have done. Cards are also claimed in the database,
+ * so passes in other processes can't act twice either. */
+export async function alone(kind, project, idle, run) {
+    const key = `${kind}\u0000${project}`;
+    if (running.has(key))
+        return idle;
+    running.add(key);
+    try {
+        return await run();
+    }
+    finally {
+        running.delete(key);
+    }
+}
+/** One project's flow pass: triggers (which may start cards), replies (which move waiting cards), steps, then moves.
+ * `halted` (a stop or paused admission) skips everything that reaches outside; moves still run. */
+export async function flowHousekeeping(store, repo, clock, io, halted) {
+    const triggers = halted() ? { added: 0, checked: 0, problems: [] }
+        : await alone("triggers", repo, { added: 0, checked: 0, problems: [] }, () => runFlowTriggers(store, repo, clock(), io.triggers));
+    // One mailbox serves every project, so its reads are one at a time across them all.
+    const replies = halted() ? { read: 0, taken: 0, problem: null }
+        : await alone("replies", "*", { read: 0, taken: 0, problem: null }, () => watchFlowReplies(store, clock(), io.replies));
+    const steps = halted() ? { ran: 0, problems: [] }
+        : await alone("steps", repo, { ran: 0, problems: [] }, () => runFlowSteps(store, repo, clock(), io.steps));
+    // Last, so a step that just finished, or a card a trigger just added, moves now.
+    const flows = moveCards(store, repo, clock(), io.evidenceRoot);
+    return { triggers, replies, steps, flows };
+}
+/** Move one project's cards. Synchronous, so two can't overlap in a process; each move is checked against the
+ * card's visit in its own transaction, so a pass in another process can't move a card twice. */
+export function moveCards(store, repo, now, evidenceRoot) {
+    try {
+        return advanceFlows(store, repo, now, evidenceRoot === undefined ? {} : { evidenceRoot });
+    }
+    catch (error) {
+        return { moved: 0, filed: [], problems: [`flows: ${error instanceof Error ? error.message : "could not move cards"}`] };
+    }
+}
+/** A build, research or check just finished: move the cards in this project, and in the project of any flow whose
+ * card that task belongs to (a build zone may build in another project), now rather than on the next pass. */
+export function moveCardsAfter(store, repo, tasks, now, evidenceRoot) {
+    const projects = new Set([repo]);
+    for (const task of tasks) {
+        try {
+            const card = store.flowCardByTask(task) ?? store.flowCardByTask(store.taskFamilyOf(task, null, true)?.root.id ?? task);
+            const flow = card === null ? null : store.getFlow(card.flow);
+            if (flow !== null)
+                projects.add(flow.repo);
+        }
+        catch { /* not a task with a card */ }
+    }
+    const outcome = { moved: 0, filed: [], problems: [] };
+    for (const project of projects) {
+        const moved = moveCards(store, project, now, evidenceRoot);
+        outcome.moved += moved.moved;
+        outcome.filed.push(...moved.filed);
+        outcome.problems.push(...moved.problems);
+    }
+    return outcome;
+}

package/dist/flow-items.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A research report's items in a flow's message (flow-send.ts): after a report step, each item is listed under the
+ * summary, numbered — its title in bold, its why in plain lines, and its link named by its source ("Mobbin", or the
+ * site's name). Each screenshot of an item is captioned with the same number, its title and how it plugs in
+ * (result-shots.ts), so "2." in the album is item 2 in the text.
+ *
+ * The message is written in reply-shape.ts's canonical form (`**bold**`, `[label](url)`), which every channel renders
+ * in its own format. Its words go through the channel's own cleaner first. Fitted to a channel's limit, each why is
+ * shortened evenly first; then the summary, then the titles; past that it is split into parts. Links are never cut.
+ */
+export type FlowSendItem = {
+    title: string;
+    why: string;
+    url: string;
+    /** Where the link goes, by name: "Mobbin", "Linear", "Apple". */
+    source: string;
+    /** One line: how it plugs in (from the why, else the image's own caption). */
+    plug: string;
+    /** The item's screenshot (its evidence id in the report's run), when it has one. */
+    shot: number | null;
+};
+/** A link's source by name: a few known sites as they write themselves, else the site's own name from its address. */
+export declare function itemSource(url: string): string;
+/** A why as plain lines: its own lines, or "the pattern; why it fits us; how it plugs in" one to a line. */
+export declare function whyLines(why: string): string[];
+/** How an item plugs in, in one line: the why's last line when it has several, else the image's caption, else the why. */
+export declare function itemPlug(why: string, imageCaption: string | null): string;
+/** A screenshot's caption: its item's number, title and how it plugs in. */
+export declare function itemCaption(number: number, item: Pick<FlowSendItem, "title" | "plug">): string;
+export type FlowMessage = {
+    head: string;
+    summary: string;
+    items: readonly FlowSendItem[];
+    tail: readonly string[];
+};
+/** The message's own words through a channel's cleaner — head, summary, each title and why, and tail — before it is fitted. */
+export declare function cleanFlowMessage(message: FlowMessage, clean: (text: string) => string): FlowMessage;
+/**
+ * The message in canonical form, as parts within `limit` as `measure` counts each once the channel renders it: one
+ * whole part when it fits; else every why shortened to the same length; then the summary; then the titles. When the
+ * head, links and tail alone are over the limit, the whole message goes in several parts instead, split between
+ * blocks (else between lines). Every link stays.
+ */
+export declare function fitFlowMessage(message: FlowMessage, limit: number, measure: (shaped: string) => number): string[];
+/** Items read back from a kept content; anything malformed is left out. */
+export declare function readFlowItems(raw: unknown): FlowSendItem[];

package/dist/flow-items.js

@@ -0,0 +1,152 @@
+/**
+ * A research report's items in a flow's message (flow-send.ts): after a report step, each item is listed under the
+ * summary, numbered — its title in bold, its why in plain lines, and its link named by its source ("Mobbin", or the
+ * site's name). Each screenshot of an item is captioned with the same number, its title and how it plugs in
+ * (result-shots.ts), so "2." in the album is item 2 in the text.
+ *
+ * The message is written in reply-shape.ts's canonical form (`**bold**`, `[label](url)`), which every channel renders
+ * in its own format. Its words go through the channel's own cleaner first. Fitted to a channel's limit, each why is
+ * shortened evenly first; then the summary, then the titles; past that it is split into parts. Links are never cut.
+ */
+const PLUG_CHARS = 160;
+const NAMES = {
+    "mobbin.com": "Mobbin", "github.com": "GitHub", "figma.com": "Figma", "dribbble.com": "Dribbble", "behance.net": "Behance",
+    "youtube.com": "YouTube", "linkedin.com": "LinkedIn", "producthunt.com": "Product Hunt", "pageflows.com": "Page Flows",
+};
+const cutTo = (text, cap) => cap <= 0 ? "" : text.length <= cap ? text : `${text.slice(0, Math.max(0, cap - 1)).trimEnd()}…`;
+const oneLine = (text) => text.replace(/\s+/g, " ").trim();
+/** A link's source by name: a few known sites as they write themselves, else the site's own name from its address. */
+export function itemSource(url) {
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase().replace(/^www\./, "");
+    }
+    catch {
+        return "Link";
+    }
+    for (const [site, name] of Object.entries(NAMES))
+        if (host === site || host.endsWith(`.${site}`))
+            return name;
+    const labels = host.split(".");
+    if (labels.length < 2 || /^[0-9.]+$/.test(host) || host.includes(":"))
+        return host;
+    // "bbc.co.uk" is the BBC's; "developer.apple.com" is Apple's.
+    const short = labels.length >= 3 && labels[labels.length - 1].length === 2 && labels[labels.length - 2].length <= 3;
+    const name = labels[labels.length - (short ? 3 : 2)];
+    return name === "" ? host : `${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+}
+/** A why as plain lines: its own lines, or "the pattern; why it fits us; how it plugs in" one to a line. */
+export function whyLines(why) {
+    const lines = why.split(/\n+/).map(one => one.trim()).filter(one => one !== "");
+    if (lines.length !== 1)
+        return lines;
+    const parts = lines[0].split(/;\s+/).map(one => one.trim()).filter(one => one !== "");
+    return parts.length >= 2 && parts.length <= 4 ? parts.map(one => `${one.charAt(0).toUpperCase()}${one.slice(1)}`) : lines;
+}
+/** How an item plugs in, in one line: the why's last line when it has several, else the image's caption, else the why. */
+export function itemPlug(why, imageCaption) {
+    const lines = whyLines(why);
+    const words = lines.length >= 2 ? lines[lines.length - 1] : imageCaption !== null && imageCaption.trim() !== "" ? imageCaption : lines.join(" ");
+    return cutTo(oneLine(words), PLUG_CHARS);
+}
+/** A screenshot's caption: its item's number, title and how it plugs in. */
+export function itemCaption(number, item) {
+    return item.plug === "" ? `${number}. ${item.title}` : `${number}. ${item.title} · ${item.plug}`;
+}
+/** Plain words can't become bold or a link by accident. */
+const inert = (text) => text.replace(/\*\*/g, "*").replace(/\]\(/g, "] (");
+/** A link the canonical form keeps whole: the characters it stops at are written percent-encoded, as browsers read them. */
+const linkable = (url) => url.replace(/[()[\]<>"'`\s]/g, char => `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+/** The message's own words through a channel's cleaner — head, summary, each title and why, and tail — before it is fitted. */
+export function cleanFlowMessage(message, clean) {
+    return { head: clean(message.head), summary: clean(message.summary), items: message.items.map(item => ({ ...item, title: clean(item.title), why: clean(item.why) })),
+        tail: message.tail.map(clean) };
+}
+function blocks(message, whyCap, summaryCap, titleCap) {
+    const items = message.items.map((item, index) => {
+        const title = cutTo(oneLine(item.title).replace(/\*/g, ""), titleCap);
+        const why = cutTo(whyLines(item.why).join("\n"), whyCap);
+        return [`${index + 1}. ${title === "" ? "" : `**${title}**`}`.trimEnd(), ...(why === "" ? [] : [inert(why)]), `[${item.source.replace(/[[\]]/g, "")}](${linkable(item.url)})`].join("\n");
+    });
+    return [inert(message.head), inert(cutTo(message.summary, summaryCap)), ...items, ...message.tail.map(inert)].filter(one => one.trim() !== "");
+}
+const compose = (message, whyCap, summaryCap, titleCap) => blocks(message, whyCap, summaryCap, titleCap).join("\n\n");
+/** The largest n in [0, high] that fits, or -1. */
+function largest(high, fits) {
+    if (!fits(0))
+        return -1;
+    let low = 0;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (fits(mid))
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return low;
+}
+/** Whole pieces packed into as few parts as fit, joined by `glue`; a piece too long alone is broken by `smaller`. */
+function pack(pieces, glue, fits, smaller) {
+    const parts = [];
+    let open = "";
+    for (const piece of pieces.flatMap(one => fits(one) ? [one] : smaller(one))) {
+        const joined = open === "" ? piece : `${open}${glue}${piece}`;
+        if (open === "" || fits(joined))
+            open = joined;
+        else {
+            parts.push(open);
+            open = piece;
+        }
+    }
+    return open === "" ? parts : [...parts, open];
+}
+/** A line longer than a whole part, in the longest prefixes that fit (never splitting a surrogate pair). */
+function chop(line, fits) {
+    const out = [];
+    for (let rest = line; rest !== "";) {
+        let at = Math.max(1, largest(rest.length, n => fits(rest.slice(0, n))));
+        if (at < rest.length && /[\uD800-\uDBFF]/.test(rest[at - 1]))
+            at = at > 1 ? at - 1 : at + 1;
+        out.push(rest.slice(0, at));
+        rest = rest.slice(at);
+    }
+    return out;
+}
+/**
+ * The message in canonical form, as parts within `limit` as `measure` counts each once the channel renders it: one
+ * whole part when it fits; else every why shortened to the same length; then the summary; then the titles. When the
+ * head, links and tail alone are over the limit, the whole message goes in several parts instead, split between
+ * blocks (else between lines). Every link stays.
+ */
+export function fitFlowMessage(message, limit, measure) {
+    const fits = (text) => measure(text) <= limit;
+    const full = compose(message, Infinity, Infinity, Infinity);
+    if (fits(full))
+        return [full];
+    const longest = Math.max(0, ...message.items.map(one => whyLines(one.why).join("\n").length));
+    const why = largest(longest, n => fits(compose(message, n, Infinity, Infinity)));
+    if (why >= 0)
+        return [compose(message, why, Infinity, Infinity)];
+    const summary = largest(message.summary.length, n => fits(compose(message, 0, n, Infinity)));
+    if (summary >= 0)
+        return [compose(message, 0, summary, Infinity)];
+    const title = largest(Math.max(0, ...message.items.map(one => one.title.length)), n => fits(compose(message, 0, 0, n)));
+    if (title >= 0)
+        return [compose(message, 0, 0, title)];
+    return pack(blocks(message, Infinity, Infinity, Infinity), "\n\n", fits, block => pack(block.split("\n"), "\n", fits, line => chop(line, fits)));
+}
+/** Items read back from a kept content; anything malformed is left out. */
+export function readFlowItems(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((one) => {
+        if (typeof one !== "object" || one === null)
+            return [];
+        const item = one;
+        const text = (key) => typeof item[key] === "string" ? item[key] : null;
+        const [title, why, url, source, plug] = [text("title"), text("why"), text("url"), text("source"), text("plug")];
+        if (title === null || why === null || url === null || source === null || plug === null || !/^https?:\/\//.test(url))
+            return [];
+        return [{ title, why, url, source, plug, shot: typeof item["shot"] === "number" && Number.isSafeInteger(item["shot"]) ? item["shot"] : null }];
+    });
+}

package/dist/flow-send.d.ts

@@ -1,4 +1,5 @@
 import { type FlowDecision } from "./flow-engine.js";
+import { type FlowSendItem } from "./flow-items.js";
 import { type FlowDefinition, type FlowStage } from "./flows.js";
 import { type FlowCardRow, type FlowRow, type Store } from "./store.js";
 /** The notice a "Send to me" visit sends: `flow-send:<card>:<entry>`. */
@@ -26,6 +27,8 @@ export type FlowSendContent = {
         taskId: string;
         run: number;
     } | null;
+    /** After research: the report's items, numbered in this order in every message and screenshot caption (flow-items.ts). */
+    items?: FlowSendItem[];
     /** choose: the options as they were offered, and whether a reply is taken. */
     options?: {
         choice: number;
@@ -52,6 +55,8 @@ export declare function sendStep(store: Store, flow: FlowRow, definition: FlowDe
 export declare function chooseStep(store: Store, flow: FlowRow, definition: FlowDefinition, stage: FlowStage, card: FlowCardRow, now: Date, evidenceRoot?: string): void;
 /** The words above a choice's buttons: what was done, then what to do. */
 export declare function flowChooseBody(content: FlowSendContent): string;
+/** What a sent visit's message ends with, after its summary (and items): its pull request, and for a choice what to do. */
+export declare function flowSendTail(content: FlowSendContent): string[];
 export type FlowChoiceVisit = {
     card: FlowCardRow;
     flow: FlowRow;

package/dist/flow-send.js

@@ -16,7 +16,9 @@
 import { assignmentOf } from "./assignment.js";
 import { withActor } from "./actor.js";
 import { flowCardHref, flowDefinitionOf, revisionWithNote } from "./flow-engine.js";
+import { itemPlug, itemSource, readFlowItems } from "./flow-items.js";
 import { notifyPeople } from "./flow-people.js";
+import { readVerifiedReport } from "./evidence.js";
 import { FLOW_END, replyTarget } from "./flows.js";
 import { FLOW_SHOTS_KIND } from "./store.js";
 /** The notice a "Send to me" visit sends: `flow-send:<card>:<entry>`. */
@@ -63,6 +65,18 @@ function reportShotsOf(store, taskId) {
     const run = store.runsFor(ref.id).find(one => one.finishedAt !== null && one.role === "scout");
     return run !== undefined && run.outcome === "built" && store.artifactsFor(run.id).some(one => one.kind === "screenshot") ? { taskId, run: run.id } : null;
 }
+/** A research task's report items, each with its source, how it plugs in, and its screenshot from that run. */
+function reportItemsOf(store, taskId, shots, evidenceRoot) {
+    const ref = store.lookupRef(taskId);
+    const view = ref === null || evidenceRoot === undefined ? null : readVerifiedReport(store, evidenceRoot, ref.id);
+    if (view === null || !view.ok)
+        return [];
+    return view.report.items.map(item => {
+        const image = item.image === null ? undefined : view.report.images.find(one => one.file === item.image);
+        const shot = item.image === null || shots?.run !== view.run ? null : view.shots.find(one => one.file === item.image)?.artifactId ?? null;
+        return { title: plain(item.title), why: plain(item.why), url: item.url, source: itemSource(item.url), plug: plain(itemPlug(item.why, image?.caption ?? null)), shot };
+    });
+}
 /** What a visit sends its person, worked out from the card as it is now. */
 export function flowSendContent(store, flow, definition, stage, card, now, evidenceRoot) {
     const before = stepBefore(store, definition, card);
@@ -96,10 +110,12 @@ export function flowSendContent(store, flow, definition, stage, card, now, evide
         links.push({ label: "Report", path: `/t/${encodeURIComponent(report)}` });
     links.push({ label: "Card", path: flowCardHref(flow.id, card.id) });
     const options = stage.kind === "choose" ? (stage.options ?? []).map((one, choice) => ({ choice, label: one.label })) : undefined;
+    // After research, its own screenshots are what that step produced; otherwise the build's.
+    const shots = (report === null ? null : reportShotsOf(store, report)) ?? result?.shots ?? null;
+    const items = report === null ? [] : reportItemsOf(store, report, shots?.taskId === report ? shots : null, evidenceRoot);
     return {
         title: cut(plain(before === null ? card.title : `${card.title} · ${before.title}`), 200), ...(before === null ? {} : { from: before.title }),
-        // After research, its own screenshots are what that step produced; otherwise the build's.
-        summary: plain(lines.join("\n\n")), links, shots: (report === null ? null : reportShotsOf(store, report)) ?? result?.shots ?? null,
+        summary: plain(lines.join("\n\n")), links, shots, ...(items.length === 0 ? {} : { items }),
         ...(options === undefined ? {} : { options, reply: replyTarget(stage) !== null }),
     };
 }
@@ -107,7 +123,13 @@ export function flowSendContent(store, flow, definition, stage, card, now, evide
 export function readFlowSend(json) {
     try {
         const raw = JSON.parse(json);
-        return typeof raw.title === "string" && typeof raw.summary === "string" && Array.isArray(raw.links) ? raw : null;
+        if (typeof raw.title !== "string" || typeof raw.summary !== "string" || !Array.isArray(raw.links))
+            return null;
+        if (raw.items === undefined)
+            return raw;
+        const items = readFlowItems(raw.items);
+        const { items: _, ...rest } = raw;
+        return items.length === 0 ? rest : { ...rest, items };
     }
     catch {
         return null;
@@ -168,8 +190,12 @@ export function chooseStep(store, flow, definition, stage, card, now, evidenceRo
 }
 /** The words above a choice's buttons: what was done, then what to do. */
 export function flowChooseBody(content) {
+    return [content.summary, ...flowSendTail(content)].join("\n\n");
+}
+/** What a sent visit's message ends with, after its summary (and items): its pull request, and for a choice what to do. */
+export function flowSendTail(content) {
     const pull = content.links.find((one) => "url" in one);
-    return [content.summary, ...(pull === undefined ? [] : [`${pull.label}: ${pull.url}`]), content.reply === true ? `Choose one. ${REPLY_ASK}` : "Choose one."].join("\n\n");
+    return [...(pull === undefined ? [] : [`${pull.label}: ${pull.url}`]), ...(content.options === undefined ? [] : [content.reply === true ? `Choose one. ${REPLY_ASK}` : "Choose one."])];
 }
 /** The card, if it is still at that visit, waiting for its person's choice. */
 export function flowChoiceAt(store, cardId, entry) {

package/dist/flows-ui.js

@@ -7,6 +7,7 @@ import { flowSecretNames, readEmailSettings, sendingReady } from "./flow-actions
 import { projectToolsOf, secretsSetFor, toolStanding } from "./project-tools.js";
 import { flowFingerprint } from "./flow-live.js";
 import { flowChoiceAt, readFlowSend } from "./flow-send.js";
+import { itemCaption, whyLines } from "./flow-items.js";
 import { FLOW_FILE_MAX_BYTES } from "./flow-share.js";
 import { googleConnected } from "./google-mail.js";
 import { mailboxReady } from "./mailbox.js";
@@ -130,7 +131,10 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
         // On the card itself: where it came from (the card's title is right above), and only the links the panel doesn't already have.
         const own = new Set([`/flows/${flow.id}?card=${card.id}`, ...(task === null ? [] : [`/t/${encodeURIComponent(task)}`])]);
         const sentView = (content) => ({ title: content.from === undefined ? "What was done" : `From ${content.from}`, summary: content.summary,
-            links: content.links.map(one => ({ label: one.label, href: "url" in one ? one.url : one.path })).filter(one => !own.has(one.href)) });
+            links: content.links.map(one => ({ label: one.label, href: "url" in one ? one.url : one.path })).filter(one => !own.has(one.href)),
+            // After research: the same numbered items the message carried, each beside its screenshot.
+            ...(content.items === undefined ? {} : { items: content.items.map((item, index) => ({ number: index + 1, title: item.title, lines: whyLines(item.why), source: item.source, url: item.url,
+                    image: item.shot === null || content.shots === null ? null : { src: `/r/${content.shots.run}/evidence/${item.shot}`, caption: itemCaption(index + 1, item) } })) }) });
         return {
             id: card.id, title: card.title, description: card.description, stage: card.stage, state: card.state, waiting: card.waiting,
             task: task === null ? null : { id: task, href: `/t/${encodeURIComponent(task)}` },