From 00316ab1a7ee22489d42b785b155ddd775ca8b63 Mon Sep 17 00:00:00 2001 From: Isaac Zhang Date: Wed, 4 Nov 2026 21:17:41 -0500 Subject: [PATCH 01/88] feat: annotate figures cropped from the learner's PDFs The teacher can now annotate a figure that lives inside one of the learner's PDFs (a diagram on a lecture slide, a plot in a paper) without the learner screenshotting it first. - visual gains an optional `pdf: { path, page }` beside `image` (never both). Dispatch checks the path against File access, that pdfjs opens the file, and that the page exists; a bad PDF or page fails the call before any job exists. - At job start the page is re-checked and rendered natively (~1600px). The visual-maker sees the page and calls a new PDF-only `crop_page` tool with a box in page-image pixels. The crop is re-rendered from the PDF (fitLongSide 1600, at most 300 dpi), shown back, and becomes the picture it annotates through the existing placeholder pipeline. Re-cropping discards the SVG; a figure that fills the page may be annotated whole; a figure that is not on the page fails with notes. - Only the final crop is stored as a session snapshot. VisualResult.image records the page and crop (page fractions) for provenance. - renderPdfPages takes an optional crop and fitLongSide; existing callers are unchanged. learner-image.ts exports learnerImageFromBytes so PDF renders share the photo normalization and snapshot identity. - Teacher prompt 55-images.md, README and docs updated. --- README.md | 2 +- docs/architecture.md | 2 + docs/getting-started.md | 2 +- src/agent/prompts/teacher/55-images.md | 5 +- src/agent/subagents/headless.ts | 41 +- src/agent/subagents/pdf-ops.ts | 10 + src/agent/subagents/runner.ts | 16 +- src/agent/subagents/visual-maker.ts | 132 ++++++- src/agent/tools/jobs.ts | 29 +- src/agent/tools/learner-image.ts | 10 +- src/agent/tools/pdf-figure.ts | 98 +++++ src/core/contracts/jobs.ts | 9 +- tests/file-access.test.ts | 9 +- tests/helpers/tiny-pdf.ts | 11 + tests/pdf-figure-annotation.test.tsx | 502 +++++++++++++++++++++++++ 15 files changed, 844 insertions(+), 34 deletions(-) create mode 100644 src/agent/tools/pdf-figure.ts create mode 100644 tests/pdf-figure-annotation.test.tsx diff --git a/README.md b/README.md index 2b751724da..3469b7eb57 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Instead of just giving you an explanation, it uses your answers and thinking to **Bring your files.** In the desktop app, attach PDFs, photos, or any other file with the paperclip, or drag them in. The file stays where it is: the message carries its path, and the agent reads it from there. -The agent can also research questions in the background, create visual explanations, show your own images in the lesson and mark them up with arrows and labels, and build interactive demonstrations. +The agent can also research questions in the background, create visual explanations, show your own images in the lesson and mark them up with arrows and labels (including figures it crops straight out of your PDFs, such as lecture slides), and build interactive demonstrations. ## Knowledge that carries forward diff --git a/docs/architecture.md b/docs/architecture.md index afcde91798..ed2523cc01 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -89,6 +89,8 @@ This is single-process coordination over JSON files, not a transactional queue o `show_image` displays a local raster picture; `visual` with an image path annotates it. Both use the file-access policy and shared processing: input bounds of 25 MiB, 16 megapixels, and 8192px per side; off-thread orientation/metadata cleanup; stored PNG/JPEG bounded to 1600px per side and below 1 MiB of base64. +`visual` with `pdf: { path, page }` annotates a figure on one page of a learner's PDF. Dispatch checks the path, that pdfjs can open the file, and that the page exists. At job start [`pdf-figure.ts`](../src/agent/tools/pdf-figure.ts) checks again and renders the page natively (pdfjs + Skia, about 1600px on the long side). The maker finds the figure and calls `crop_page` with a box in page-image pixels. The crop is re-rendered from the PDF (at most 300 dpi) rather than cut from the page bitmap. Recropping replaces the picture and discards the SVG. Both renders go through the same snapshot processing; only the picture finally annotated is stored, and the result records its page and crop. + [`learner-image.ts`](../src/agent/tools/learner-image.ts) stores processed bytes under SHA-256 identities in `ChatRecord.imageSnapshots`, deduplicated per session. Cards and annotation SVGs reference snapshots, so moving the original does not break saved results. Session-scoped image reads resolve references; SVG downloads embed their image. The annotator edits a placeholder href, not base64, and uses static native rendering. Ordinary visual SVGs retain their existing behavior. Offline regression tests exercise snapshot storage, display, and payload delivery, not model-driven annotation quality. ## Knowledge graph and imports diff --git a/docs/getting-started.md b/docs/getting-started.md index 5e578de208..774b43d896 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -37,7 +37,7 @@ Audio streams from your browser directly to Deepgram using a short-lived token. In the desktop app, use the paperclip's **Files** or **Folder** choice, or drag files/folders into the content area, to insert their local paths. Files supports any file type and multiple selections; Folder attaches one directory path, including an empty folder, without expanding or reading its contents. Newly picked or dropped known folders get a trailing directory separator so their Folder icon survives saved messages and reloads; files stay unchanged. Older unmarked paths are not retrospectively classified. The agent can then locate/read supported content on the machine running LearnHarness under the existing file-access guards; attaching a path does not grant permissions. This is **not an upload**: originals stay where they are. Ordinary browsers cannot expose these local paths through the picker or drag-and-drop; you can paste a full path instead. -The teacher can show a local raster image or request an annotated visual based on it. Displayed/annotated pictures are saved as session-owned snapshots, so those saved results no longer depend on the original file. This does not snapshot every file attachment. Offline regression tests cover snapshot/payload behavior, not the quality of model-generated annotations. +The teacher can show a local raster image or request an annotated visual based on it. It can also annotate a figure on a page of a local PDF, such as a diagram on a lecture slide: the visual maker crops the figure from that page itself, so you don't have to screenshot it. Displayed/annotated pictures are saved as session-owned snapshots, so those saved results no longer depend on the original file. This does not snapshot every file attachment. Offline regression tests cover snapshot/payload behavior, not the quality of model-generated annotations. File tools are read-only but have broad filesystem access under the server's user; they are not confined to a selected folder. The sensitive-path guard blocks known credential/private locations, not all sensitive content. Review what you make available: file content read by an agent may be sent to its configured model provider. See [file-access boundaries](architecture.md#file-access-and-external-services). diff --git a/src/agent/prompts/teacher/55-images.md b/src/agent/prompts/teacher/55-images.md index 95255926a3..4fede0abd7 100644 --- a/src/agent/prompts/teacher/55-images.md +++ b/src/agent/prompts/teacher/55-images.md @@ -1,10 +1,11 @@ -## The learner's own images — show them, mark them up +## The learner's own images and PDF figures — show them, mark them up When the lesson turns on something in one of the learner's pictures — a photo of their circuit, a textbook page, a screenshot, a whiteboard — put the picture in the lesson instead of describing it, and when the point is one part of it, mark that part. - `show_image` puts a local image file into the lesson as-is, instantly, with an optional `caption`. Use it for the first useful display of a picture, or to bring an earlier picture alongside a later explanation when that genuinely helps. If it is already available in the current teaching context, reference it rather than duplicate it. Its result only confirms what was shown — to see the picture yourself, `read` it. It does not retrieve generated SVG figures. - `visual` with `image` set to the file's path has its maker annotate the picture: arrows, outlines, and labels on the features you name. The `brief` says which features to mark and what each label reads; the maker sees the picture but nothing of the lesson. Same fire-and-forget discipline as any visual. +- `visual` with `pdf: { path, page }` does the same for a figure inside one of the learner's PDFs — a diagram on a lecture slide, a plot in a paper. The maker sees that one page, crops the figure out, and marks up the crop, so the learner never has to screenshot it. Give the exact page (from the learner, or from a `pdf` brief's page citations), and open the `brief` by saying which figure it is so the maker can tell it from everything else on the page. If the figure isn't on that page, the maker says so instead of drawing. Visual results, including annotated images, display automatically when delivered. Teach from the delivered card; do not call `show_image` to repeat it, and do not regenerate a figure merely to reference it again. -Brief only marks you can ground — in what you saw through `read`, or what the learner told you is there. A label on the wrong part teaches something false; if the maker can't find a feature, its notes say so. +Brief only marks you can ground — in what you saw through `read`, what a `pdf` brief described, or what the learner told you is there. A label on the wrong part teaches something false; if the maker can't find a feature, its notes say so. diff --git a/src/agent/subagents/headless.ts b/src/agent/subagents/headless.ts index d00d324561..cf88c12ee2 100644 --- a/src/agent/subagents/headless.ts +++ b/src/agent/subagents/headless.ts @@ -49,8 +49,22 @@ export interface RenderSvgOptions { } export interface RenderPdfOptions { - /** Render DPI — 72 is 100% zoom; the skill's guidance is 100/150/200. */ + /** Render DPI — 72 is 100% zoom; the skill's guidance is 100/150/200. + * With fitLongSide it is the ceiling instead. */ dpi?: number; + /** Rasterize only this part of the page (fractions of the page as + * displayed, after rotation, from the top-left corner). */ + crop?: PdfCrop; + /** Scale so the rendered region's longer side is about this many pixels, + * never above dpi. */ + fitLongSide?: number; +} + +export interface PdfCrop { + x: number; + y: number; + width: number; + height: number; } export interface RenderedPdfPage { @@ -512,6 +526,13 @@ export function pdfCanvasGeometry(baseWidth: number, baseHeight: number, dpi: nu return { scale, ...dimensions(scale) }; } +function checkPdfCrop({ x, y, width, height }: PdfCrop): void { + if (![x, y, width, height].every(Number.isFinite)) throw new Error("PDF crop values must be finite numbers"); + if (width <= 0 || height <= 0) throw new Error("PDF crop width and height must be greater than 0"); + const slack = 1e-9; + if (x < 0 || y < 0 || x + width > 1 + slack || y + height > 1 + slack) throw new Error("PDF crop must lie inside the page"); +} + /** Render PDF pages to PNGs — the sources-v0 pdf-reader's eyes. * * History: pdfjs ALWAYS painted the pages (scale = dpi/72, the skill's @@ -529,6 +550,12 @@ async function renderPdfPages( if (!Number.isFinite(dpi) || dpi <= 0 || dpi / 72 === 0) { throw new Error("PDF render DPI must be finite and positive"); } + const crop = opts.crop ?? { x: 0, y: 0, width: 1, height: 1 }; + checkPdfCrop(crop); + const fitLongSide = opts.fitLongSide; + if (fitLongSide !== undefined && !(Number.isFinite(fitLongSide) && fitLongSide > 0)) { + throw new Error("PDF render fitLongSide must be finite and positive"); + } // NATIVE CANVAS (Wave E, owner 2026-10-10): pdfjs paints into // @napi-rs/canvas in this process — no browser involved. pdfjs-dist v6's // own Node integration IS @napi-rs/canvas (its optionalDependency: the @@ -550,8 +577,16 @@ async function renderPdfPages( if (pageNo < 1 || pageNo > doc.numPages) continue; const pg = await doc.getPage(pageNo); const base = pg.getViewport({ scale: 1 }); - const geometry = pdfCanvasGeometry(base.width, base.height, dpi); - const vp = pg.getViewport({ scale: geometry.scale }); + const regionWidth = base.width * crop.width; + const regionHeight = base.height * crop.height; + const regionDpi = fitLongSide === undefined ? dpi : Math.min(dpi, (fitLongSide * 72) / Math.max(regionWidth, regionHeight)); + const geometry = pdfCanvasGeometry(regionWidth, regionHeight, regionDpi); + // A crop is the page shifted up and left under a crop-sized canvas. + const vp = pg.getViewport({ + scale: geometry.scale, + offsetX: -crop.x * base.width * geometry.scale, + offsetY: -crop.y * base.height * geometry.scale, + }); const canvas = createCanvas(geometry.width, geometry.height); const ctx = canvas.getContext("2d"); // pdfjs's render types speak the DOM context; @napi-rs/canvas's diff --git a/src/agent/subagents/pdf-ops.ts b/src/agent/subagents/pdf-ops.ts index 870492c3f2..5b58fa2084 100644 --- a/src/agent/subagents/pdf-ops.ts +++ b/src/agent/subagents/pdf-ops.ts @@ -111,6 +111,16 @@ export async function pdfProbe(filePath: string): Promise { await task.destroy(); } +/** Page count only (no page walk): the PDF figure tool's page-range gate. */ +export async function pdfPageCount(filePath: string): Promise { + const { doc, task } = await openDocument(filePath); + try { + return doc.numPages; + } finally { + await task.destroy(); + } +} + /** pdf_info: page count + per-page triage signals. ALWAYS run first. */ export async function pdfInfo(filePath: string): Promise { const pdfjs = await loadPdfjs(); // OPS constant for the operator-list scan diff --git a/src/agent/subagents/runner.ts b/src/agent/subagents/runner.ts index 17a1ecbfad..a74e29a88f 100644 --- a/src/agent/subagents/runner.ts +++ b/src/agent/subagents/runner.ts @@ -31,6 +31,7 @@ import { runPdfReaderAgent } from "./pdf-reader.ts"; import { runResearcherAgent } from "./researcher.ts"; import { runVisualMaker } from "./visual-maker.ts"; import { loadLearnerImage, type LearnerImage } from "../tools/learner-image.ts"; +import { loadPdfFigureSource, type PdfFigureSource } from "../tools/pdf-figure.ts"; /** * The background job runner (contracts.ts "THE ASYNC PROTOCOL" §2–3), created @@ -456,6 +457,7 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner { const input = (passedInput ?? resolveInput(job, passedInput)) as VisualToolInput | undefined; const brief = typeof input?.brief === "string" ? input.brief : ""; const imagePath = typeof input?.image === "string" ? input.image : undefined; + const pdfInput = input?.pdf && typeof input.pdf.path === "string" && typeof input.pdf.page === "number" ? input.pdf : undefined; try { // Annotation (issue #363): the learner image is read once, here, @@ -465,9 +467,16 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner { jobStore.updateJob(jobId, { activity: "loading image" }); image = await loadLearnerImage(imagePath, loop.abortSignal); } - jobStore.updateJob(jobId, { activity: image ? "annotating image" : "drawing figure" }); + // A PDF page: the maker crops the figure itself, so the stored + // image is whichever page or crop it finally annotated. + let pdf: PdfFigureSource | undefined; + if (pdfInput) { + jobStore.updateJob(jobId, { activity: `rendering page ${pdfInput.page}` }); + pdf = await loadPdfFigureSource(pdfInput.path, pdfInput.page, loop.abortSignal); + } + jobStore.updateJob(jobId, { activity: pdf ? "finding figure" : image ? "annotating image" : "drawing figure" }); const result = await runVisualMaker( - { brief, image }, + { brief, image, pdf }, { engine: model, abortSignal: loop.abortSignal, @@ -476,7 +485,8 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner { onActivity: (line) => jobStore.updateJob(jobId, { activity: line }), }, ); - if (image && result.svg && stillRunning(jobId)) chatStore.saveImageSnapshot(job.chatId, image.snapshotId, image); + const annotated = image ?? (result.image ? pdf?.imageFor(result.image.snapshotId) : undefined); + if (annotated && result.svg && stillRunning(jobId)) chatStore.saveImageSnapshot(job.chatId, annotated.snapshotId, annotated); if (isVisualFailure(result) && stillRunning(jobId)) jobStore.updateJob(jobId, { error: result.notes ?? "visual build failed" }); await finishJob(jobId, result); diff --git a/src/agent/subagents/visual-maker.ts b/src/agent/subagents/visual-maker.ts index 8731846ad0..532fdee186 100644 --- a/src/agent/subagents/visual-maker.ts +++ b/src/agent/subagents/visual-maker.ts @@ -8,6 +8,7 @@ import { providerEventObserver, type ProviderEventObserver } from "../provider-e import { backgroundCaptureStream, createBackgroundCapture, type BackgroundCapture } from "../background-capture.ts"; import type { VisualResult } from "../../core/contracts.ts"; import type { LearnerImage } from "../tools/learner-image.ts"; +import type { PdfFigureImage, PdfFigureSource } from "../tools/pdf-figure.ts"; import { embedLearnerImage, LEARNER_IMAGE_HREF } from "../../core/learner-image-svg.ts"; import { annotationPlacementProblem } from "./annotation-svg.ts"; import { getHeadless, type HeadlessApi } from "./headless.ts"; @@ -39,12 +40,18 @@ import { getHeadless, type HeadlessApi } from "./headless.ts"; * href (LEARNER_IMAGE_HREF); the loop embeds bytes only for rendering. * Delivered SVGs retain the placeholder and a session snapshot reference. * The maker receives native image content, never base64 in SVG text/edits. + * + * PDF MODE: with a PDF page the maker first sees the whole page, crops the + * figure the brief names with crop_page (re-rendered from the PDF, then + * shown back), and annotates the crop exactly as in image mode. */ export interface VisualMakerInput { brief: string; /** The learner image to annotate, already bounded for storage. */ image?: LearnerImage; + /** A page of the learner's PDF to crop a figure from and annotate. */ + pdf?: PdfFigureSource; } /** The placeholder href the model gives the learner's picture. */ @@ -126,11 +133,42 @@ figure is that picture with marks on it, not a new drawing: - If a feature the brief names is not in the picture, never guess where it is: leave it unmarked and say so in your notes.`; +const PDF_INSTRUCTIONS = `FINDING THE FIGURE ON A PDF PAGE — the picture you were given is one whole page of the learner's PDF +(often a lecture slide), and the brief names one figure on it: + +- Find that figure on the page first. Then call crop_page with a box, in the page image's pixels, that + holds the whole figure (with its labels, axes, and legend) plus a small margin, and leaves out the slide + title, footer, logos, and unrelated text unless the brief needs them. +- Look at the crop that comes back. If any of the figure is cut off, or the box holds too much, call + crop_page again with a corrected box, always measured on the original page image. +- The crop is the picture you annotate: place it at the W×H given with the crop. Cropping again replaces + it and discards any SVG you wrote, so settle the crop before you draw. +- If the figure fills the page, skip crop_page and annotate the whole page. +- If the figure the brief names is not on this page, write no SVG: finish with notes saying so and what + the page shows instead.`; + /** The wire declarations (pi-ai Tool, TypeBox parameters): this loop owns * execution itself — write/edit dispatch inline below, render feeds the * image-in-the-loop message — so the declarations carry no execute. */ -export function createVisualTools(): Record { +export function createVisualTools(mode: { pdf?: boolean } = {}): Record { return { + ...(mode.pdf + ? { + crop_page: { + name: "crop_page", + description: + "Crop the PDF page to the figure. x, y, width and height are a box in the pixels of the page image you were shown " + + "(origin top-left). The crop is re-rendered sharp from the PDF, shown to you, and becomes the picture you annotate. " + + "Call again to adjust; that discards any SVG written so far.", + parameters: Type.Object({ + x: Type.Number({ description: "Left edge, in page-image pixels." }), + y: Type.Number({ description: "Top edge, in page-image pixels." }), + width: Type.Number({ description: "Box width, in page-image pixels." }), + height: Type.Number({ description: "Box height, in page-image pixels." }), + }), + }, + } + : {}), write_svg: { name: "write_svg", description: "Write the complete SVG source for the figure (overwrites any previous version).", @@ -157,20 +195,24 @@ export function createVisualTools(): Record { const LOOK_MESSAGE = "Here is the current render of your SVG — inspect it critically (geometry, labels, clipping, readability):"; +const cropLookMessage = (width: number, height: number) => + `Here is your crop (${width}×${height} px) — check it holds the whole figure the brief names, with nothing cut off:`; const UNLOOKED_FINISH_MESSAGE = "You finished without looking at a render of your final SVG. Above is its render. If it is correct and clean, reply with just your notes; otherwise call write_svg with fixes and render again."; export async function runVisualMaker(input: VisualMakerInput, opts: VisualMakerOptions = {}): Promise { const headless = opts.headless ?? getHeadless(); const brief = input.brief.trim() || "(no brief)"; - const maxIterations = opts.maxIterations ?? 8; + const pdf = input.pdf; + // Finding and cropping a PDF figure costs a couple of extra rounds. + const maxIterations = opts.maxIterations ?? (pdf ? 10 : 8); const reason = headless.unavailableReason(); if (reason) { return { svg: "", notes: `FAILED: ${reason}` }; } - const tools = createVisualTools(); + const tools = createVisualTools({ pdf: Boolean(pdf) }); const toolDeclarations = Object.values(tools); const engine = opts.engine ?? piEngineFor("visualMaker"); // BYOK (owner, 2026-09-22): the level rides the injected engine — no @@ -179,19 +221,30 @@ export async function runVisualMaker(input: VisualMakerInput, opts: VisualMakerO const sessionId = randomUUID(); const capture = createBackgroundCapture({ role: "visualMaker", runId: sessionId, sourceId: opts.chatId }); const streamEngine = { ...engine, streamFn: backgroundCaptureStream(engine.streamFn, capture) }; - const learnerImage = input.image; - const systemPrompt = learnerImage ? `${INSTRUCTIONS}\n\n${IMAGE_INSTRUCTIONS}` : INSTRUCTIONS; + /** The picture being annotated; in PDF mode crop_page replaces it. */ + let learnerImage: LearnerImage | PdfFigureImage | undefined = input.image ?? pdf?.pageImage; + const systemPrompt = pdf + ? `${INSTRUCTIONS}\n\n${IMAGE_INSTRUCTIONS}\n\n${PDF_INSTRUCTIONS}` + : learnerImage + ? `${INSTRUCTIONS}\n\n${IMAGE_INSTRUCTIONS}` + : INSTRUCTIONS; const prompt = [ - learnerImage - ? "Brief for ONE annotated image (from the teacher, verbatim — it is everything you know):" - : "Brief for ONE precise figure (from the teacher, verbatim — it is everything you know):", + pdf + ? "Brief for ONE annotated figure from the learner's PDF (from the teacher, verbatim — it is everything you know):" + : learnerImage + ? "Brief for ONE annotated image (from the teacher, verbatim — it is everything you know):" + : "Brief for ONE precise figure (from the teacher, verbatim — it is everything you know):", brief, "", - ...(learnerImage + ...(pdf && learnerImage ? [ - `The learner's image follows: ${learnerImage.width}×${learnerImage.height} px. Place it with .`, + `Page ${pdf.page} of the learner's PDF follows: ${learnerImage.width}×${learnerImage.height} px. Find the figure the brief names, then crop_page to it — or, if it fills the page, place the whole page with .`, ] - : []), + : learnerImage + ? [ + `The learner's image follows: ${learnerImage.width}×${learnerImage.height} px. Place it with .`, + ] + : []), "Author the SVG, render it, look at it, iterate until correct, then finish with your notes.", ].join("\n"); @@ -287,6 +340,7 @@ export async function runVisualMaker(input: VisualMakerInput, opts: VisualMakerO const toolResults: ToolResultMessage[] = []; let renderImage: Extract | null = null; // appended AFTER the tool results + let cropImage: { image: Extract; width: number; height: number } | null = null; for (const call of toolCalls) { if (call.name === "write_svg") { const svg = (call.arguments as { svg?: unknown }).svg; @@ -357,13 +411,61 @@ export async function runVisualMaker(input: VisualMakerInput, opts: VisualMakerO opts.onActivity?.("render_svg: render error"); toolResults.push(toolText(call.id, call.name, `RENDER ERROR (the SVG may be malformed): ${msg}. Fix it with write_svg and render again.`)); } + } else if (call.name === "crop_page" && pdf) { + const box = call.arguments as Record; + const [x, y, width, height] = [box.x, box.y, box.width, box.height]; + if (typeof x !== "number" || typeof y !== "number" || typeof width !== "number" || typeof height !== "number") { + toolResults.push(toolText(call.id, call.name, "ERROR: expected numbers x, y, width and height (page-image pixels).")); + continue; + } + try { + const cropped = await pdf.crop({ x, y, width, height }, opts.abortSignal); + const shown = await processImage(Buffer.from(cropped.data, "base64"), cropped.mimeType, { + resizeOptions: engine.model.inputLimits?.images?.resize, + }); + opts.abortSignal?.throwIfAborted(); + if (!shown.ok) throw new Error(shown.message); + const discarded = currentSvg !== null; + learnerImage = cropped; + currentSvg = null; + renderedSvg = null; + renderImage = null; // a render from earlier in this batch shows a discarded SVG + cropImage = { image: shown, width: cropped.width, height: cropped.height }; + opts.onActivity?.(`crop_page: ${cropped.width}×${cropped.height} px`); + toolResults.push( + toolText( + call.id, + call.name, + `Cropped: ${cropped.width}×${cropped.height} px — the crop follows in the next message. It is now the picture you annotate: place it with .` + + (discarded ? " Your earlier SVG was discarded; write_svg again." : ""), + ), + ); + } catch (err) { + opts.abortSignal?.throwIfAborted(); + const msg = err instanceof Error ? err.message : String(err); + toolResults.push(toolText(call.id, call.name, `ERROR: crop failed — ${msg}.`)); + } } else { - toolResults.push(toolText(call.id, call.name, `ERROR: unknown tool "${call.name}". Use write_svg, edit_svg, or render_svg.`)); + const known = pdf ? "write_svg, edit_svg, render_svg, or crop_page" : "write_svg, edit_svg, or render_svg"; + toolResults.push(toolText(call.id, call.name, `ERROR: unknown tool "${call.name}". Use ${known}.`)); } } // Message order: assistant tool-calls → tool results → render image. for (const result of toolResults) capture?.toolResult(result); messages = [...messages, ...toolResults]; + if (cropImage) { + messages = [ + ...messages, + { + role: "user", + content: [ + { type: "text", text: [cropLookMessage(cropImage.width, cropImage.height), ...cropImage.image.hints].join("\n") }, + { type: "image", data: cropImage.image.data, mimeType: cropImage.image.mimeType }, + ], + timestamp: Date.now(), + }, + ]; + } if (renderImage) { messages = [ ...messages, @@ -467,12 +569,14 @@ function snippetAround(svg: string, target: string): string { .join("\n"); } -function finish(svg: string | null, finalText: string, image?: LearnerImage): VisualResult { +function finish(svg: string | null, finalText: string, image?: LearnerImage | PdfFigureImage): VisualResult { if (!svg) { return { svg: "", notes: `FAILED: the maker never wrote an SVG.${finalText ? ` (${finalText.slice(0, 300)})` : ""}`, }; } - return { svg, notes: finalText || undefined, ...(image ? { image: { path: image.path, snapshotId: image.snapshotId } } : {}) }; + if (!image) return { svg, notes: finalText || undefined }; + const fromPdf = "page" in image ? { page: image.page, ...(image.crop ? { crop: image.crop } : {}) } : {}; + return { svg, notes: finalText || undefined, image: { path: image.path, snapshotId: image.snapshotId, ...fromPdf } }; } diff --git a/src/agent/tools/jobs.ts b/src/agent/tools/jobs.ts index 45ba97a35c..5aeae6a659 100644 --- a/src/agent/tools/jobs.ts +++ b/src/agent/tools/jobs.ts @@ -4,6 +4,7 @@ import { serverExecute } from "../tool-execute.ts"; import type { JobRecord } from "../../core/contracts.ts"; import type { JobStore } from "../../core/ports.ts"; import { checkLearnerImage } from "./learner-image.ts"; +import { checkPdfPage } from "./pdf-figure.ts"; import { resolveSourcePath } from "./fs-shared.ts"; /** @@ -65,6 +66,19 @@ export const visualInputSchema = Type.Object({ "instead of drawing from scratch.", }), ), + pdf: Type.Optional( + Type.Object( + { + path: Type.String({ minLength: 1, description: "Path to the learner's PDF (relative or absolute), exactly as they gave it." }), + page: Type.Integer({ minimum: 1, description: "The 1-based page that holds the figure." }), + }, + { + description: + "A figure on one page of the learner's PDF (lecture slides, a textbook chapter) to annotate — the maker crops it from " + + "that page and draws on the crop. Never together with image.", + }, + ), + ), }); export const pdfInputSchema = Type.Object({ @@ -121,7 +135,10 @@ const VISUAL_DESCRIPTION = "Dispatch a background sub-agent that hand-authors ONE precise SVG figure, renders it, LOOKS at the render, and iterates " + "until correct. Use it for exact spatial pictures auto-layout diagrams can't do: coordinate geometry, number lines, vectors, " + "function plots, physical layouts. For flows/relations/taxonomies write mermaid inline instead. " + - "Pass `image` (a learner image file) to have the maker annotate that picture — arrows, outlines, labels — instead. Local image paths follow File access settings; use ls to discover allowed folders. " + + "Pass `image` (a learner image file) to have the maker annotate that picture — arrows, outlines, labels — instead. " + + "Pass `pdf` ({ path, page }) to annotate a figure on one page of a learner's PDF: the maker crops it from that page itself; " + + "name the exact page and describe the figure in the brief so the maker can find it. " + + "Local image and PDF paths follow File access settings; use ls to discover allowed folders. " + "The call is ASYNC and fire-and-forget — it resolves immediately and your turn continues; the verified figure arrives later " + "as a new message."; const PDF_DESCRIPTION = @@ -162,10 +179,14 @@ export function jobTools(ctx: JobToolContext): Record> { label: "visual", description: VISUAL_DESCRIPTION, parameters: visualInputSchema, - // An unusable image path fails the CALL (no job is created), so the - // teacher corrects the path in the same turn. + // An unusable image path, PDF or page fails the CALL (no job is + // created), so the teacher corrects it in the same turn. execute: serverExecute("visual", visualInputSchema, async (input, { toolCallId, signal }) => { - if (!ctx.jobStore.findJobByToolCallId(ctx.chatId, toolCallId) && input.image !== undefined) await checkLearnerImage(input.image); + if (!ctx.jobStore.findJobByToolCallId(ctx.chatId, toolCallId)) { + if (input.image !== undefined && input.pdf !== undefined) throw new Error("Pass either image or pdf, not both."); + if (input.image !== undefined) await checkLearnerImage(input.image); + if (input.pdf !== undefined) await checkPdfPage(input.pdf.path, input.pdf.page); + } signal?.throwIfAborted(); return dispatch(ctx, "visual", toolCallId, VISUAL_ACK, input); }), diff --git a/src/agent/tools/learner-image.ts b/src/agent/tools/learner-image.ts index 8e63a9a748..908efc0b3b 100644 --- a/src/agent/tools/learner-image.ts +++ b/src/agent/tools/learner-image.ts @@ -72,12 +72,18 @@ export async function loadLearnerImage(rawPath: string, signal?: AbortSignal): P signal?.throwIfAborted(); const absolute = await checkLearnerImage(rawPath); const bytes = await readBounded(absolute, signal); + return learnerImageFromBytes(bytes, absolute, signal); +} + +/** Store image bytes from any source (a file, a rendered PDF page) the same + * way; sourcePath is provenance only. */ +export async function learnerImageFromBytes(bytes: Uint8Array, sourcePath: string, signal?: AbortSignal): Promise { const mime = detectSupportedImageMimeType(bytes); - if (!mime) throw new Error(`Not a supported image: ${absolute}`); + if (!mime) throw new Error(`Not a supported image: ${sourcePath}`); checkImageDimensions(bytes, mime); const stored = await normalize(bytes, signal); signal?.throwIfAborted(); if (stored.mimeType !== "image/png" && stored.mimeType !== "image/jpeg") throw new Error("Unexpected stored image format"); const snapshotId = createHash("sha256").update(Buffer.from(stored.data, "base64")).digest("hex"); - return { path: absolute, snapshotId, mimeType: stored.mimeType, data: stored.data, width: stored.width, height: stored.height }; + return { path: sourcePath, snapshotId, mimeType: stored.mimeType, data: stored.data, width: stored.width, height: stored.height }; } diff --git a/src/agent/tools/pdf-figure.ts b/src/agent/tools/pdf-figure.ts new file mode 100644 index 0000000000..9587a3ea61 --- /dev/null +++ b/src/agent/tools/pdf-figure.ts @@ -0,0 +1,98 @@ +import * as fs from "node:fs/promises"; +import { getHeadless, type PdfCrop } from "../subagents/headless.ts"; +import { pdfPageCount } from "../subagents/pdf-ops.ts"; +import { resolveSourcePath } from "./fs-shared.ts"; +import { learnerImageFromBytes, type LearnerImage } from "./learner-image.ts"; + +/** Pages and crops render at about this long side; storage caps at 1600 too. */ +const FIGURE_LONG_SIDE = 1600; +/** A small crop stops gaining detail here instead of upscaling further. */ +const MAX_FIGURE_DPI = 300; +export const MIN_CROP_SIDE = 16; + +/** A page or crop of the learner's PDF, stored like any learner image. */ +export interface PdfFigureImage extends LearnerImage { + page: number; + /** Absent for the whole page. */ + crop?: PdfCrop; +} + +/** A box in the pixels of the page image the maker was shown. */ +export interface CropBox { + x: number; + y: number; + width: number; + height: number; +} + +/** One page of the learner's PDF, ready for the visual maker to crop. */ +export interface PdfFigureSource { + path: string; + page: number; + pageImage: PdfFigureImage; + crop(box: CropBox, signal?: AbortSignal): Promise; + /** Any page or crop image this source produced, by snapshot id. */ + imageFor(snapshotId: string): PdfFigureImage | undefined; +} + +/** Dispatch-time gate: an unusable PDF or page fails the visual call. */ +export async function checkPdfPage(rawPath: string, page: number): Promise { + // Reuse the shared file-access policy, including canonical/symlink checks. + const absolute = resolveSourcePath(rawPath); + let pages: number; + try { + const stat = await fs.stat(absolute); + if (!stat.isFile()) throw new Error("it is not a regular file"); + if (stat.size === 0) throw new Error("the file is empty"); + pages = await pdfPageCount(absolute); + } catch (error) { + const reason = (error as NodeJS.ErrnoException).code === "ENOENT" ? "no such file" : error instanceof Error ? error.message : String(error); + throw new Error(`Cannot open PDF ${absolute}: ${reason}`); + } + if (!Number.isInteger(page) || page < 1 || page > pages) { + throw new Error(`PDF ${absolute} has ${pages} page${pages === 1 ? "" : "s"}; page ${page} does not exist`); + } + return absolute; +} + +/** Job-time load: checks access again, then renders the page for the maker. */ +export async function loadPdfFigureSource(rawPath: string, page: number, signal?: AbortSignal): Promise { + signal?.throwIfAborted(); + const path = await checkPdfPage(rawPath, page); + const made = new Map(); + + const render = async (crop: PdfCrop | undefined, abort?: AbortSignal): Promise => { + const [rendered] = await getHeadless().renderPdfPages(path, [page], { dpi: MAX_FIGURE_DPI, fitLongSide: FIGURE_LONG_SIDE, crop }); + if (!rendered) throw new Error(`page ${page} of ${path} could not be rendered`); + abort?.throwIfAborted(); + const image: PdfFigureImage = { ...(await learnerImageFromBytes(rendered.png, path, abort)), page, ...(crop ? { crop } : {}) }; + made.set(image.snapshotId, image); + return image; + }; + + const pageImage = await render(undefined, signal); + return { + path, + page, + pageImage, + crop: (box, abort) => render(cropFraction(box, pageImage.width, pageImage.height), abort), + imageFor: (snapshotId) => made.get(snapshotId), + }; +} + +/** Clamp a pixel box to the page and turn it into page fractions. */ +export function cropFraction(box: CropBox, pageWidth: number, pageHeight: number): PdfCrop { + if (![box.x, box.y, box.width, box.height].every(Number.isFinite)) throw new Error("x, y, width and height must be numbers"); + const clamp = (v: number, max: number) => Math.min(max, Math.max(0, v)); + const left = clamp(box.x, pageWidth); + const top = clamp(box.y, pageHeight); + const right = clamp(box.x + box.width, pageWidth); + const bottom = clamp(box.y + box.height, pageHeight); + if (right - left < MIN_CROP_SIDE || bottom - top < MIN_CROP_SIDE) { + throw new Error(`the crop must cover at least ${MIN_CROP_SIDE}×${MIN_CROP_SIDE} px of the ${pageWidth}×${pageHeight} page`); + } + const round = (v: number) => Math.round(v * 10_000) / 10_000; + const x = round(left / pageWidth); + const y = round(top / pageHeight); + return { x, y, width: Math.min(round(right / pageWidth), 1) - x, height: Math.min(round(bottom / pageHeight), 1) - y }; +} diff --git a/src/core/contracts/jobs.ts b/src/core/contracts/jobs.ts index ba203e7c8e..53b0ad7431 100644 --- a/src/core/contracts/jobs.ts +++ b/src/core/contracts/jobs.ts @@ -219,6 +219,9 @@ export interface VisualToolInput { /** A learner image file to annotate (issue #363): the maker draws its * marks on top of it instead of authoring a figure from scratch. */ image?: string; + /** A page of the learner's PDF: the maker crops the figure the brief + * names from it and annotates the crop. Never set with image. */ + pdf?: { path: string; page: number }; } export interface VisualResult { @@ -227,8 +230,10 @@ export interface VisualResult { svg: string; notes?: string; /** Present when the figure annotates a learner image: its absolute - * path. Photos never invert, so the card hides the switch. */ - image?: { path: string; snapshotId: string }; + * path. Photos never invert, so the card hides the switch. From a PDF, + * path is the PDF, page is 1-based, and crop (page fractions from the + * top-left) is absent when the whole page was annotated. */ + image?: { path: string; snapshotId: string; page?: number; crop?: { x: number; y: number; width: number; height: number } }; } /** The pdf-reader (sources v0, 2026-09): reads a learner-provided PDF on diff --git a/tests/file-access.test.ts b/tests/file-access.test.ts index 3db574c30c..ff58ca62ca 100644 --- a/tests/file-access.test.ts +++ b/tests/file-access.test.ts @@ -225,6 +225,7 @@ describe("live policy and all learner-source surfaces", () => { await assert.rejects(tools.pdf!.execute!("x", { path: path.join(outside, "sample.pdf"), question: "?" }), boundary); if (tools.show_image) await assert.rejects(tools.show_image.execute!("x", { path: path.join(outside, "image.png") }), boundary); if (tools.visual) await assert.rejects(tools.visual.execute!("x", { brief: "mark", image: path.join(outside, "image.png") }), boundary); + if (tools.visual) await assert.rejects(tools.visual.execute!("x", { brief: "mark", pdf: { path: path.join(outside, "sample.pdf"), page: 1 } }), boundary); } const faux = createFauxCore({ tokenSize: { min: 64, max: 64 } }); await assert.rejects(createReadTool(faux.getModel()).execute!("x", { path: path.join(outside, "image.png") }), boundary); @@ -246,10 +247,14 @@ describe("live policy and all learner-source surfaces", () => { const faux = createFauxCore({ tokenSize: { min: 64, max: 64 } }); let calls = 0; const engine = { model: faux.getModel(), streamFn: (() => { calls++; throw new Error("must not call model"); }) as typeof faux.streamSimple }; - for (const kind of ["pdf", "visual"] as const) { + const queued = [ + { kind: "pdf", input: { path: "StudyA/sample.pdf", question: "?" } }, + { kind: "visual", input: { image: "StudyA/image.png", brief: "mark" } }, + { kind: "visual", input: { pdf: { path: "StudyA/sample.pdf", page: 2 }, brief: "mark" } }, + ] as const; + for (const { kind, input } of queued) { policy = { restricted: true, folders: [a] }; const chat = chatStore.createChat(`synthetic queued ${kind}`); - const input = kind === "pdf" ? { path: "StudyA/sample.pdf", question: "?" } : { image: "StudyA/image.png", brief: "mark" }; let spawned = 0; let id = ""; const tools = jobTools({ chatId: chat.id, jobStore, spawn: (job) => { id = job.id; spawned++; } }); diff --git a/tests/helpers/tiny-pdf.ts b/tests/helpers/tiny-pdf.ts index 2fa588dc6b..a9734461c8 100644 --- a/tests/helpers/tiny-pdf.ts +++ b/tests/helpers/tiny-pdf.ts @@ -11,10 +11,20 @@ export interface Run { rotated?: boolean; } +/** A filled vector rectangle in PDF points (origin bottom-left), color 0..1. */ +export interface Rect { + x: number; + y: number; + width: number; + height: number; + rgb: [number, number, number]; +} + export interface TinyPage { runs?: Run[]; /** A full-page picture: ordinary XObject, stencil mask, or inline bitmap. */ image?: boolean | "mask" | "inline"; + rects?: Rect[]; } const WIDTH = 612; @@ -36,6 +46,7 @@ function content(page: TinyPage): string { const ops: string[] = []; if (page.image === "inline") ops.push(`q ${WIDTH} 0 0 ${HEIGHT} 0 0 cm BI /W 2 /H 2 /CS /G /BPC 8 ID \x80\x40\x40\x80 EI Q`); else if (page.image) ops.push(`q ${WIDTH} 0 0 ${HEIGHT} 0 0 cm /${page.image === "mask" ? "Mask" : "Im1"} Do Q`); + for (const r of page.rects ?? []) ops.push(`q ${r.rgb.join(" ")} rg ${r.x} ${r.y} ${r.width} ${r.height} re f Q`); for (const run of page.runs ?? []) { const matrix = run.rotated ? `0 1 -1 0 ${run.x} ${run.y}` : `1 0 0 1 ${run.x} ${run.y}`; ops.push(`BT /F1 ${run.size ?? 10} Tf ${run.invisible ? 3 : 0} Tr ${matrix} Tm ${pdfString(run.text)} Tj ET`); diff --git a/tests/pdf-figure-annotation.test.tsx b/tests/pdf-figure-annotation.test.tsx new file mode 100644 index 0000000000..1395fb7f32 --- /dev/null +++ b/tests/pdf-figure-annotation.test.tsx @@ -0,0 +1,502 @@ +/** + * Annotating a figure on a page of the learner's PDF — deterministic, zero network: + * + * 1. crop rendering (real pdfjs + Skia): only the crop is rasterized, sized + * by fitLongSide, and bad crops are refused + * 2. pixel boxes → page fractions (clamping, the minimum size) + * 3. visual with pdf: the dispatch-time gate and the raw input on the job + * 4. the maker in PDF mode (fake model + fake source): sees the page, crops, + * annotates the crop; re-crops discard the SVG; whole page; not found + * 5. the job runner end to end on a real PDF: only the final crop is stored + */ + +import assert from "node:assert/strict"; +import * as fs from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { after, describe, it } from "node:test"; +import { createCanvas } from "@napi-rs/canvas"; +import * as photon from "@silvia-odwyer/photon-node"; +import { + createFauxCore, + fauxAssistantMessage, + fauxText, + fauxToolCall, + type FauxResponseStep, + type ImageContent, + type TranscriptContext, +} from "@earendil-works/pi-ai"; +import { PATHS } from "../config.ts"; +import { learnerImageFromBytes } from "../src/agent/tools/learner-image.ts"; +import { checkPdfPage, cropFraction, loadPdfFigureSource, type PdfFigureImage, type PdfFigureSource } from "../src/agent/tools/pdf-figure.ts"; +import { jobTools } from "../src/agent/tools/jobs.ts"; +import { createVisualTools, LEARNER_IMAGE_HREF, runVisualMaker } from "../src/agent/subagents/visual-maker.ts"; +import { headlessOverride, realHeadless, type HeadlessApi, type PdfCrop } from "../src/agent/subagents/headless.ts"; +import { createJobRunner, visualModelOverride } from "../src/agent/subagents/runner.ts"; +import { isSubagentFailure, type JobRecord, type SteerMessage, type VisualResult } from "../src/core/contracts.ts"; +import type { JobStore } from "../src/core/ports.ts"; +import type { PiEngine } from "../src/agent/models.ts"; +import { chatStore } from "../src/store/chats.ts"; +import { jobStore } from "../src/store/jobs.ts"; +import { tinyPdf } from "./helpers/tiny-pdf.ts"; + +// The key-presence gate (see demos.test.tsx): the runner's model checks +// read env-first truth. +process.env.OPENROUTER_API_KEY ??= "test-key-presence-gate"; + +const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "lh-pdf-figures-")); +const JOBS_DIR = path.join(PATHS.data, "jobs"); +const createdChats: string[] = []; +const createdJobs: string[] = []; + +after(() => { + fs.rmSync(scratch, { recursive: true, force: true }); + for (const id of createdChats) fs.rmSync(path.join(PATHS.chats, `${id}.json`), { force: true }); + for (const id of createdJobs) fs.rmSync(path.join(JOBS_DIR, `${id}.json`), { force: true }); + headlessOverride.current = undefined; + visualModelOverride.current = undefined; +}); + +// ─── fixtures ──────────────────────────────────────────────────────────────── + +const RED: [number, number, number] = [1, 0, 0]; +/** A US-letter page (612×792 pt) whose bottom-right quarter is a red block. */ +const QUARTER_PAGE = { rects: [{ x: 306, y: 0, width: 306, height: 396, rgb: RED }] }; + +function file(name: string, bytes: Uint8Array | string): string { + const p = path.join(scratch, name); + fs.writeFileSync(p, bytes); + return p; +} + +/** A two-page deck: page 1 blank, page 2 with the red quarter. */ +function deck(name: string): string { + return file(name, tinyPdf([{}, QUARTER_PAGE])); +} + +function decode(png: Buffer | string): { width: number; height: number; at(x: number, y: number): [number, number, number] } { + const image = photon.PhotonImage.new_from_byteslice(typeof png === "string" ? Buffer.from(png, "base64") : png); + try { + const width = image.get_width(); + const height = image.get_height(); + const raw = image.get_raw_pixels(); + return { + width, + height, + at: (x, y) => { + const i = (y * width + x) * 4; + return [raw[i]!, raw[i + 1]!, raw[i + 2]!]; + }, + }; + } finally { + image.free(); + } +} + +const isRed = ([r, g, b]: [number, number, number]) => r > 200 && g < 60 && b < 60; +const isWhite = ([r, g, b]: [number, number, number]) => r > 230 && g > 230 && b > 230; + +/** A solid raster (a different color gives a different snapshot). */ +function raster(width: number, height: number, color = "#1144cc"): Buffer { + const canvas = createCanvas(width, height); + const context = canvas.getContext("2d"); + context.fillStyle = color; + context.fillRect(0, 0, width, height); + return canvas.toBuffer("image/png"); +} + +/** A faux engine that snapshots every provider-facing context. */ +function scripted(steps: FauxResponseStep[]) { + const faux = createFauxCore({ tokenSize: { min: 64, max: 64 } }); + faux.setResponses(steps); + const base = faux.getModel(); + const requests: TranscriptContext[] = []; + const engine: PiEngine = { + model: { ...base, input: ["text", "image"] }, + streamFn: (model, context, options) => { + requests.push(structuredClone(context)); + return faux.streamSimple(model, context, options); + }, + }; + return { engine, requests }; +} + +function images(context: TranscriptContext): ImageContent[] { + return context.messages.flatMap((message) => + Array.isArray(message.content) ? message.content.filter((part): part is ImageContent => part.type === "image") : [], + ); +} + +function text(context: TranscriptContext): string { + return context.messages + .map((message) => + typeof message.content === "string" + ? message.content + : message.content + .filter((part) => part.type === "text") + .map((part) => (part as { text: string }).text) + .join("\n"), + ) + .join("\n"); +} + +function fakeHeadless(renderPdfPages: HeadlessApi["renderPdfPages"] = async () => { throw new Error("unexpected pdf render"); }): HeadlessApi & { svgCalls: string[] } { + const svgCalls: string[] = []; + return { + svgCalls, + available: () => true, + unavailableReason: () => null, + runDemo: async () => { + throw new Error("unexpected demo run"); + }, + renderSvg: async (svg) => { + svgCalls.push(svg); + return raster(4, 3); + }, + renderPdfPages, + }; +} + +const marked = (width: number, height: number) => + ``; + +/** A hand-made source: an 80×60 "page" whose crops are solid rasters of the crop's size. */ +async function fakeSource(page = 3) { + const sourcePath = "/learner/Courses/lec5.pdf"; + const pageImage: PdfFigureImage = { ...(await learnerImageFromBytes(raster(80, 60, "#ffffff"), sourcePath)), page }; + const made = new Map([[pageImage.snapshotId, pageImage]]); + const crops: PdfCrop[] = []; + const source: PdfFigureSource = { + path: sourcePath, + page, + pageImage, + crop: async (box) => { + const crop = cropFraction(box, pageImage.width, pageImage.height); + crops.push(crop); + const color = crops.length === 1 ? "#cc0000" : "#00aa00"; + const image: PdfFigureImage = { + ...(await learnerImageFromBytes(raster(Math.round(crop.width * 80), Math.round(crop.height * 60), color), sourcePath)), + page, + crop, + }; + made.set(image.snapshotId, image); + return image; + }, + imageFor: (id) => made.get(id), + }; + return { source, crops, made }; +} + +// ─── 1. crop rendering ─────────────────────────────────────────────────────── + +describe("PDF crop rendering (real pdfjs + Skia)", () => { + const pdf = file("quarter.pdf", tinyPdf([QUARTER_PAGE])); + + it("without a crop renders the whole page as before", async () => { + const [page] = await realHeadless.renderPdfPages(pdf, [1], { dpi: 72 }); + const png = decode(page!.png); + assert.equal(png.width, 612); + assert.equal(png.height, 792); + assert.ok(isRed(png.at(459, 594)), "bottom-right is red"); + assert.ok(isWhite(png.at(153, 198)), "top-left is white"); + }); + + it("rasterizes only the crop, at the crop's own size", async () => { + const [page] = await realHeadless.renderPdfPages(pdf, [1], { dpi: 72, crop: { x: 0.5, y: 0.5, width: 0.5, height: 0.5 } }); + const png = decode(page!.png); + assert.equal(png.width, 306); + assert.equal(png.height, 396); + assert.ok(isRed(png.at(5, 5)) && isRed(png.at(300, 390)), "the crop is all red quarter"); + }); + + it("places the crop's top-left at the requested point", async () => { + const [page] = await realHeadless.renderPdfPages(pdf, [1], { dpi: 72, crop: { x: 0.25, y: 0.25, width: 0.5, height: 0.5 } }); + const png = decode(page!.png); + assert.ok(isWhite(png.at(50, 50)), "top-left of the crop is page white"); + assert.ok(isRed(png.at(250, 350)), "bottom-right of the crop is the red quarter"); + }); + + it("fitLongSide sizes the region's longer side, capped by dpi", async () => { + const quarter = { x: 0.5, y: 0.5, width: 0.5, height: 0.5 }; + const [fit] = await realHeadless.renderPdfPages(pdf, [1], { dpi: 300, fitLongSide: 800, crop: quarter }); + const fitted = decode(fit!.png); + assert.equal(fitted.height, 800, "396pt tall → 800px"); + assert.equal(fitted.width, Math.ceil(306 * (800 / 396))); + const [capped] = await realHeadless.renderPdfPages(pdf, [1], { dpi: 72, fitLongSide: 800, crop: quarter }); + assert.equal(decode(capped!.png).height, 396, "dpi stays the ceiling"); + }); + + it("refuses crops outside the page, empty crops, and non-numbers", async () => { + await assert.rejects(realHeadless.renderPdfPages(pdf, [1], { crop: { x: 0.6, y: 0, width: 0.5, height: 1 } }), /inside the page/); + await assert.rejects(realHeadless.renderPdfPages(pdf, [1], { crop: { x: 0, y: 0, width: 0, height: 1 } }), /greater than 0/); + await assert.rejects(realHeadless.renderPdfPages(pdf, [1], { crop: { x: Number.NaN, y: 0, width: 1, height: 1 } }), /finite/); + await assert.rejects(realHeadless.renderPdfPages(pdf, [1], { fitLongSide: -1 }), /fitLongSide/); + }); +}); + +// ─── 2. pixel box → page fractions ────────────────────────────────────────── + +describe("cropFraction", () => { + it("turns a pixel box into page fractions", () => { + assert.deepEqual(cropFraction({ x: 200, y: 150, width: 400, height: 300 }, 800, 600), { x: 0.25, y: 0.25, width: 0.5, height: 0.5 }); + }); + + it("clamps a box that spills past the page", () => { + const crop = cropFraction({ x: -40, y: 500, width: 200, height: 400 }, 800, 600); + assert.deepEqual(crop, { x: 0, y: 0.8333, width: 0.2, height: 1 - 0.8333 }); + assert.ok(crop.y + crop.height <= 1); + }); + + it("refuses a box under 16 px or with non-numbers", () => { + assert.throws(() => cropFraction({ x: 10, y: 10, width: 10, height: 100 }, 800, 600), /at least 16×16 px of the 800×600 page/); + assert.throws(() => cropFraction({ x: 790, y: 0, width: 100, height: 100 }, 800, 600), /at least 16×16 px/); + assert.throws(() => cropFraction({ x: Number.NaN, y: 0, width: 100, height: 100 }, 800, 600), /must be numbers/); + }); +}); + +// ─── 3. visual with pdf: dispatch ──────────────────────────────────────────── + +describe("visual with a PDF page: dispatch", () => { + function fakeJobs() { + const created: unknown[] = []; + const spawned: unknown[] = []; + const store = { + findJobByToolCallId: () => undefined, + createJob: (record: Pick) => { + const job = { ...record, id: `job_${created.length + 1}`, status: "running", activity: "", createdAt: "", updatedAt: "" }; + created.push(job); + return job; + }, + } as unknown as JobStore; + const tools = jobTools({ chatId: "chat_x", jobStore: store, spawn: (_job, input) => spawned.push(input) }); + return { tools, created, spawned }; + } + + it("unusable PDFs and pages fail the call and create no job", async () => { + const { tools, created, spawned } = fakeJobs(); + const good = deck("dispatch.pdf"); + const notPdf = file("notes.txt", "plain text, not a PDF"); + await assert.rejects(tools.visual!.execute("c1", { brief: "b", pdf: { path: path.join(scratch, "gone.pdf"), page: 1 } }), /Cannot open PDF .*gone\.pdf: no such file/); + await assert.rejects(tools.visual!.execute("c2", { brief: "b", pdf: { path: notPdf, page: 1 } }), /Cannot open PDF .*notes\.txt: /); + await assert.rejects(tools.visual!.execute("c3", { brief: "b", pdf: { path: good, page: 3 } }), /has 2 pages; page 3 does not exist/); + await assert.rejects(tools.visual!.execute("c4", { brief: "b", pdf: { path: scratch, page: 1 } }), /not a regular file/); + const image = file("photo.png", raster(8, 8)); + await assert.rejects(tools.visual!.execute("c5", { brief: "b", image, pdf: { path: good, page: 1 } }), /either image or pdf, not both/); + assert.equal(created.length, 0); + assert.equal(spawned.length, 0); + }); + + it("a usable page dispatches the job with the raw input", async () => { + const { tools, created, spawned } = fakeJobs(); + const p = deck("dispatch-ok.pdf"); + const result = await tools.visual!.execute("c6", { brief: "Circle the red block.", pdf: { path: p, page: 2 } }); + assert.match((result.content[0] as { text: string }).text, /^Dispatched \(job job_1\)/); + assert.equal(created.length, 1); + assert.deepEqual(spawned, [{ brief: "Circle the red block.", pdf: { path: p, page: 2 } }]); + }); + + it("resolves relative paths against the learner's home, like read", async () => { + await assert.rejects(checkPdfPage("lh-no-such-deck.pdf", 1), (err: Error) => err.message.includes(path.join(os.homedir(), "lh-no-such-deck.pdf"))); + }); +}); + +// ─── 4. the maker in PDF mode ──────────────────────────────────────────────── + +describe("visual maker with a PDF page (fake model + fake source)", () => { + it("shows the page, crops the figure, and annotates the crop", async () => { + const { source, crops } = await fakeSource(); + const headless = fakeHeadless(); + const { engine, requests } = scripted([ + fauxAssistantMessage([fauxToolCall("crop_page", { x: 40, y: 30, width: 40, height: 30 }, { id: "c1" })], { stopReason: "toolUse" }), + fauxAssistantMessage( + [fauxToolCall("write_svg", { svg: marked(40, 30) }, { id: "w1" }), fauxToolCall("render_svg", {}, { id: "r1" })], + { stopReason: "toolUse" }, + ), + fauxAssistantMessage([fauxText("Circled the red block.")]), + ]); + const result = await runVisualMaker({ brief: "The red block. Circle it.", pdf: source }, { engine, headless }); + + assert.match(text(requests[0]!), /FINDING THE FIGURE ON A PDF PAGE/, "the PDF doctrine joins the system prompt"); + assert.match(text(requests[0]!), /ANNOTATING THE LEARNER'S IMAGE/); + assert.match(text(requests[0]!), /Page 3 of the learner's PDF follows: 80×60 px/); + assert.ok(JSON.stringify(requests[0]).includes('"crop_page"'), "crop_page is declared"); + assert.equal(images(requests[0]!).length, 1, "the maker sees the page up front"); + + assert.deepEqual(crops, [{ x: 0.5, y: 0.5, width: 0.5, height: 0.5 }]); + assert.match(text(requests[1]!), /Cropped: 40×30 px/); + assert.match(text(requests[1]!), /Here is your crop \(40×30 px\)/); + assert.equal(images(requests[1]!).length, 2, "page, then the crop"); + + const cropImage = source.imageFor(result.image!.snapshotId)!; + assert.equal(cropImage.width, 40); + assert.ok(headless.svgCalls[0]!.includes(`href="data:${cropImage.mimeType};base64,${cropImage.data}"`), "renders embed the crop"); + assert.equal(result.svg, marked(40, 30)); + assert.deepEqual(result.image, { path: source.path, snapshotId: cropImage.snapshotId, page: 3, crop: { x: 0.5, y: 0.5, width: 0.5, height: 0.5 } }); + for (const request of requests) { + assert.ok(!text(request).includes(source.pageImage.data) && !text(request).includes(cropImage.data), "base64 never enters the model's text"); + } + }); + + it("re-cropping discards the SVG and switches the placement size", async () => { + const { source, crops } = await fakeSource(); + const { engine, requests } = scripted([ + fauxAssistantMessage([fauxToolCall("crop_page", { x: 40, y: 30, width: 40, height: 30 }, { id: "c1" })], { stopReason: "toolUse" }), + fauxAssistantMessage( + [fauxToolCall("write_svg", { svg: marked(40, 30) }, { id: "w1" }), fauxToolCall("render_svg", {}, { id: "r1" })], + { stopReason: "toolUse" }, + ), + fauxAssistantMessage([fauxToolCall("crop_page", { x: 20, y: 15, width: 60, height: 45 }, { id: "c2" })], { stopReason: "toolUse" }), + fauxAssistantMessage([fauxToolCall("write_svg", { svg: marked(40, 30) }, { id: "w2" })], { stopReason: "toolUse" }), + fauxAssistantMessage( + [fauxToolCall("write_svg", { svg: marked(60, 45) }, { id: "w3" }), fauxToolCall("render_svg", {}, { id: "r3" })], + { stopReason: "toolUse" }, + ), + fauxAssistantMessage([fauxText("Re-cropped to include the legend.")]), + ]); + const result = await runVisualMaker({ brief: "b", pdf: source }, { engine, headless: fakeHeadless() }); + assert.equal(crops.length, 2); + assert.match(text(requests[3]!), /Cropped: 60×45 px .*Your earlier SVG was discarded; write_svg again\./); + assert.match(text(requests[4]!), /place the image at its natural 60×45 pixel size/, "the old size is refused"); + assert.equal(result.svg, marked(60, 45)); + assert.deepEqual(result.image?.crop, { x: 0.25, y: 0.25, width: 0.75, height: 0.75 }); + assert.equal(source.imageFor(result.image!.snapshotId)?.width, 60); + }); + + it("annotates the whole page when the maker never crops", async () => { + const { source } = await fakeSource(1); + const { engine } = scripted([ + fauxAssistantMessage( + [fauxToolCall("write_svg", { svg: marked(80, 60) }, { id: "w1" }), fauxToolCall("render_svg", {}, { id: "r1" })], + { stopReason: "toolUse" }, + ), + fauxAssistantMessage([fauxText("The figure fills the slide.")]), + ]); + const result = await runVisualMaker({ brief: "b", pdf: source }, { engine, headless: fakeHeadless() }); + assert.deepEqual(result.image, { path: source.path, snapshotId: source.pageImage.snapshotId, page: 1 }); + }); + + it("reports bad boxes to the model and keeps going", async () => { + const { source, crops } = await fakeSource(); + const { engine, requests } = scripted([ + fauxAssistantMessage( + [fauxToolCall("crop_page", { x: 0, y: 0, width: 5, height: 5 }, { id: "c1" }), fauxToolCall("crop_page", { x: "left" }, { id: "c2" })], + { stopReason: "toolUse" }, + ), + fauxAssistantMessage( + [fauxToolCall("write_svg", { svg: marked(80, 60) }, { id: "w1" }), fauxToolCall("render_svg", {}, { id: "r1" })], + { stopReason: "toolUse" }, + ), + fauxAssistantMessage([fauxText("Whole page.")]), + ]); + const result = await runVisualMaker({ brief: "b", pdf: source }, { engine, headless: fakeHeadless() }); + assert.match(text(requests[1]!), /ERROR: crop failed — the crop must cover at least 16×16 px of the 80×60 page/); + assert.match(text(requests[1]!), /ERROR: expected numbers x, y, width and height/); + assert.equal(crops.length, 0); + assert.equal(result.image?.snapshotId, source.pageImage.snapshotId); + }); + + it("a figure that is not on the page fails with the maker's notes", async () => { + const { source } = await fakeSource(); + const { engine } = scripted([fauxAssistantMessage([fauxText("The page shows only a title slide; no circuit diagram is on it.")])]); + const result = await runVisualMaker({ brief: "The circuit diagram.", pdf: source }, { engine, headless: fakeHeadless() }); + assert.equal(result.svg, ""); + assert.match(result.notes ?? "", /^FAILED: the maker never wrote an SVG\. \(The page shows only a title slide/); + }); + + it("crop_page exists only in PDF mode", () => { + assert.ok(!("crop_page" in createVisualTools())); + assert.ok("crop_page" in createVisualTools({ pdf: true })); + }); +}); + +// ─── 5. the job runner on a real PDF ───────────────────────────────────────── + +describe("visual job runner with a PDF page", () => { + function testRunner() { + const steers: SteerMessage[] = []; + const runner = createJobRunner({ + chatStore, + jobStore, + deliver: async (steer) => { + steers.push(steer); + const jobId = (steer.details as { jobId: string }).jobId; + const job = jobStore.getJob(jobId); + if (job && job.status === "running") { + const failed = job.result ? isSubagentFailure(job.kind, job.result as never) : true; + jobStore.updateJob(jobId, { status: failed ? "error" : "done", activity: failed ? "failed" : "delivered" }); + } + }, + }); + return { steers, runner }; + } + + function visualChat(title: string, input: { brief: string; pdf: { path: string; page: number } }) { + const chat = chatStore.createChat(title); + createdChats.push(chat.id); + const job = jobStore.createJob({ kind: "visual", chatId: chat.id, toolCallId: "call-vp", input }); + createdJobs.push(job.id); + return job; + } + + const realPdfHeadless = () => fakeHeadless((pdfPath, pages, opts) => realHeadless.renderPdfPages(pdfPath, pages, opts)); + + it("renders the page, stores only the final crop, and steers an annotated image", async () => { + const p = deck("runner.pdf"); + // The same deterministic renders the job will make, to script the model. + const preview = await loadPdfFigureSource(p, 2); + const { width: W, height: H } = preview.pageImage; + const box = { x: W / 2, y: H / 2, width: W / 2, height: H / 2 }; + const expectedCrop = await preview.crop(box); + + const job = visualChat("Test: annotate a PDF figure", { brief: "The red block. Outline it.", pdf: { path: p, page: 2 } }); + headlessOverride.current = realPdfHeadless(); + visualModelOverride.current = scripted([ + fauxAssistantMessage([fauxToolCall("crop_page", box, { id: "c1" })], { stopReason: "toolUse" }), + fauxAssistantMessage( + [ + fauxToolCall("write_svg", { svg: marked(expectedCrop.width, expectedCrop.height) }, { id: "w1" }), + fauxToolCall("render_svg", {}, { id: "r1" }), + ], + { stopReason: "toolUse" }, + ), + fauxAssistantMessage([fauxText("Outlined the red block.")]), + ]).engine; + const { steers, runner } = testRunner(); + try { + await runner.runJob(job.id); + } finally { + headlessOverride.current = undefined; + visualModelOverride.current = undefined; + } + + const result = jobStore.getJob(job.id)!.result as VisualResult; + assert.deepEqual(result.image, { path: fs.realpathSync.native(p), snapshotId: expectedCrop.snapshotId, page: 2, crop: expectedCrop.crop }); + assert.ok(Math.abs(expectedCrop.crop!.x - 0.5) < 0.001 && Math.abs(expectedCrop.crop!.width - 0.5) < 0.001); + const stored = chatStore.getChat(job.chatId)?.imageSnapshots ?? {}; + assert.deepEqual(Object.keys(stored), [expectedCrop.snapshotId], "only the crop is stored, never the page"); + const crop = decode(stored[expectedCrop.snapshotId]!.data); + assert.ok(isRed(crop.at(10, 10)) && isRed(crop.at(crop.width - 10, crop.height - 10)), "the stored crop is the red quarter"); + assert.ok(Math.max(crop.width, crop.height) <= 1600); + assert.equal(steers.length, 1); + assert.match(steers[0]!.content as string, /^The annotated image is drawn, verified by inspection/); + }); + + it("a PDF gone by run time delivers a FAILED steer", async () => { + const p = deck("vanishing.pdf"); + const job = visualChat("Test: annotate a PDF figure, vanished", { brief: "b", pdf: { path: p, page: 2 } }); + fs.rmSync(p); + headlessOverride.current = realPdfHeadless(); + visualModelOverride.current = scripted([]).engine; + const { steers, runner } = testRunner(); + try { + await runner.runJob(job.id); + } finally { + headlessOverride.current = undefined; + visualModelOverride.current = undefined; + } + const result = (steers[0]!.details as { result: VisualResult }).result; + assert.equal(result.svg, ""); + assert.match(result.notes ?? "", /^FAILED: Cannot open PDF .*vanishing\.pdf: no such file/); + assert.equal(jobStore.getJob(job.id)!.status, "error"); + }); +}); From 6badc17fbd5405348fef6edd4afc15025e0d5ce2 Mon Sep 17 00:00:00 2001 From: Isaac Zhang Date: Sat, 7 Nov 2026 19:14:38 -0500 Subject: [PATCH 02/88] fix(deps): clear production npm audit advisories Lockfile-only npm audit fix (zod, puppeteer-core/chromium-bidi, dompurify, undici, fast-uri, source-map-js and their trees), resolved with a 14-day release cooldown (--before=2026-10-24). Remove the unused ansi-to-react (the only path to vulnerable linkify-it) and react-jsx-parser; neither is imported anywhere. --- package-lock.json | 322 ++++++++++++++++------------------------------ package.json | 4 +- 2 files changed, 112 insertions(+), 214 deletions(-) diff --git a/package-lock.json b/package-lock.json index 037fe9571c..5a31bb5bc1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22,7 +22,6 @@ "@streamdown/math": "^1.0.2", "@streamdown/mermaid": "^1.0.2", "@xyflow/react": "^12.11.3", - "ansi-to-react": "^6.2.6", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "cmdk": "^1.1.1", @@ -51,7 +50,6 @@ "radix-ui": "^1.6.7", "react": "^19.2.8", "react-dom": "^19.2.8", - "react-jsx-parser": "^2.4.1", "remark-breaks": "^4.0.0", "streamdown": "^2.5.0", "tailwind-merge": "^3.6.0", @@ -1413,9 +1411,9 @@ "license": "MIT" }, "node_modules/@eslint/config-array/node_modules/brace-expansion": { - "version": "1.1.18", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz", - "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==", + "version": "1.1.21", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz", + "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==", "dev": true, "license": "MIT", "dependencies": { @@ -1494,9 +1492,9 @@ "license": "MIT" }, "node_modules/@eslint/eslintrc/node_modules/brace-expansion": { - "version": "1.1.18", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz", - "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==", + "version": "1.1.21", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz", + "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==", "dev": true, "license": "MIT", "dependencies": { @@ -3072,12 +3070,12 @@ "license": "BSD-3-Clause" }, "node_modules/@puppeteer/browsers": { - "version": "3.2.1", - "resolved": "https://registry.npmjs.org/@puppeteer/browsers/-/browsers-3.2.1.tgz", - "integrity": "sha512-KDz+3qDRdBAlRlMjmKyj6dEs33YHTk/xRHEENSXq6TNnhgoU15ruSHtEBeVF6OZ9tBDY55Se4P0nFMNsipzU9A==", + "version": "3.2.6", + "resolved": "https://registry.npmjs.org/@puppeteer/browsers/-/browsers-3.2.6.tgz", + "integrity": "sha512-MJP29gVoHznmqmwhH1tlZqzfeQ3aylTpSSa6WKZXtkwYUH02i9imBmWGTyZrbnAou5paX78SE4jMAUqnEPf8ug==", "license": "Apache-2.0", "dependencies": { - "modern-tar": "^0.8.0", + "modern-tar": "^0.8.6", "yargs": "^18.0.0" }, "bin": { @@ -5868,13 +5866,6 @@ "undici-types": "~7.18.0" } }, - "node_modules/@types/prop-types": { - "version": "15.7.15", - "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz", - "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==", - "license": "MIT", - "optional": true - }, "node_modules/@types/react": { "version": "19.2.18", "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.18.tgz", @@ -5932,16 +5923,16 @@ "license": "MIT" }, "node_modules/@typescript-eslint/parser": { - "version": "8.68.0", - "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.68.0.tgz", - "integrity": "sha512-fHq2VC1kpyYfvEcbiMjOpySY4WS7voEp89yAThrHRX5sm9j2lzYppCb2umFMEed4fWcyeLjHxrz0mpjNBaBxMQ==", + "version": "8.72.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.72.0.tgz", + "integrity": "sha512-0O+x3ynciD6zuXb1CKSu165haQV6ey53DKhHHUnujP7U+XlltJG+/keT0Xhd1HXCze+IHf7Tvt39ovyepX/LNw==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/scope-manager": "8.68.0", - "@typescript-eslint/types": "8.68.0", - "@typescript-eslint/typescript-estree": "8.68.0", - "@typescript-eslint/visitor-keys": "8.68.0", + "@typescript-eslint/scope-manager": "8.72.0", + "@typescript-eslint/types": "8.72.0", + "@typescript-eslint/typescript-estree": "8.72.0", + "@typescript-eslint/visitor-keys": "8.72.0", "debug": "^4.4.3" }, "engines": { @@ -5957,14 +5948,14 @@ } }, "node_modules/@typescript-eslint/project-service": { - "version": "8.68.0", - "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.68.0.tgz", - "integrity": "sha512-5GQtWZCXFcFYux955pvoS02WLc49pXNlvIxocKjS0clvwo3in1RdlzVKyiqQH9vE5AKWFLTaUgeQkOrTS+0Qxw==", + "version": "8.72.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.72.0.tgz", + "integrity": "sha512-bzHngBbmIgzj6TsTjVUCntGx6FFLgE7mPjpO0PzHycOaZHXqS43XnrkFIHRS16LLr/xO6FHSXG3GJFo/F4bSBQ==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/tsconfig-utils": "^8.68.0", - "@typescript-eslint/types": "^8.68.0", + "@typescript-eslint/tsconfig-utils": "^8.72.0", + "@typescript-eslint/types": "^8.72.0", "debug": "^4.4.3" }, "engines": { @@ -5979,14 +5970,14 @@ } }, "node_modules/@typescript-eslint/scope-manager": { - "version": "8.68.0", - "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.68.0.tgz", - "integrity": "sha512-T5eXpcaJNg8bhjHJ8Rjp68Vq/QBteYtTKY8TZqVNPaUbuz0f6jI9t6aDkylwvalpAB9XTTFeFOjrjXAZ3YvmVA==", + "version": "8.72.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.72.0.tgz", + "integrity": "sha512-JewPyJOYcXBSAS7PIgufscHOwZqhTGyBRiQJhhuDln66tMchxvvt7nJ90JKKIoOelmdHA3kAQbm9cEUHc4JSEA==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/types": "8.68.0", - "@typescript-eslint/visitor-keys": "8.68.0" + "@typescript-eslint/types": "8.72.0", + "@typescript-eslint/visitor-keys": "8.72.0" }, "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" @@ -5997,9 +5988,9 @@ } }, "node_modules/@typescript-eslint/tsconfig-utils": { - "version": "8.68.0", - "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.68.0.tgz", - "integrity": "sha512-F7zrGQfiJHojPwi8vhxZQC1tWtJzvL74cK/nqri2lk8YUXvYaYwl263xOJ69jDWPUk1hmcdoayFwk9lX09npVw==", + "version": "8.72.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.72.0.tgz", + "integrity": "sha512-0vbxCf7xLVPSjcOdm6eQbgViH8EDJ8xnl1laLT9yoqSz2YmcSfSg5Vdl0JUvZf6rcuJ0ZivJIuMD4edTg8obaA==", "dev": true, "license": "MIT", "engines": { @@ -6014,9 +6005,9 @@ } }, "node_modules/@typescript-eslint/types": { - "version": "8.68.0", - "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.68.0.tgz", - "integrity": "sha512-9RnpsGJjrAllCMefGVVsImJM24YurhC0Q1h4UbvivtvOqXmR/vEJge2OoE++z9m6hyg8T1Q8t5SNT6tHSbrxcg==", + "version": "8.72.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.72.0.tgz", + "integrity": "sha512-Adfoy59kxNEjT5E5fnyrp7GpHYuWs8ONbdohu4ez6IU46qDq8LltG90tLmkucZB2uhYL8mqBjtXqGd8yhfjXqQ==", "dev": true, "license": "MIT", "engines": { @@ -6028,16 +6019,16 @@ } }, "node_modules/@typescript-eslint/typescript-estree": { - "version": "8.68.0", - "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.68.0.tgz", - "integrity": "sha512-OKKsD0tYmoNiU5PW2zehO1yO56jYOm1ShYlxon/Z0SJNidAkdVg86eg9ruRuoXf8xfnuWZGbwDsStkoXbZtIIA==", + "version": "8.72.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.72.0.tgz", + "integrity": "sha512-gwLfFgWcw15tN2KXDCJvxEOQjPn+P3j/n3eSqkZ5sX4VpW9Cosodr+tWwBZRvJT3TcKx6HnPRGZMCNAiP1Xhug==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/project-service": "8.68.0", - "@typescript-eslint/tsconfig-utils": "8.68.0", - "@typescript-eslint/types": "8.68.0", - "@typescript-eslint/visitor-keys": "8.68.0", + "@typescript-eslint/project-service": "8.72.0", + "@typescript-eslint/tsconfig-utils": "8.72.0", + "@typescript-eslint/types": "8.72.0", + "@typescript-eslint/visitor-keys": "8.72.0", "debug": "^4.4.3", "minimatch": "^10.2.2", "semver": "^7.7.3", @@ -6056,13 +6047,13 @@ } }, "node_modules/@typescript-eslint/visitor-keys": { - "version": "8.68.0", - "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.68.0.tgz", - "integrity": "sha512-YR65gGdGvTUAWLldC3xLOvOzamdGzB4A5/N8rehEaHs3Zvoe39BhgY+u0SPch1OvrVTfLcc55wsSgK2NcnTS/A==", + "version": "8.72.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.72.0.tgz", + "integrity": "sha512-E2mroviasaWecDzTGiGMtuEguuLVOeRggnrIn93CJuxYJzQBHbyymlT08aVQydbBal5538o+JkBKXh2sRuCyIA==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/types": "8.68.0", + "@typescript-eslint/types": "8.72.0", "eslint-visitor-keys": "^5.0.0" }, "engines": { @@ -6560,6 +6551,7 @@ "version": "8.18.0", "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.18.0.tgz", "integrity": "sha512-lGq+9yr1/GuAWaVYIHRjvvySG5/4VfKIvC8EWxStPdcDh/Ka7FG3twP6v4d5BkravUilhIAsG4Qj83t02LWUPQ==", + "dev": true, "license": "MIT", "bin": { "acorn": "bin/acorn" @@ -6572,6 +6564,7 @@ "version": "5.3.2", "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz", "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==", + "dev": true, "license": "MIT", "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" @@ -6642,12 +6635,6 @@ "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", "license": "MIT" }, - "node_modules/anser": { - "version": "2.3.5", - "resolved": "https://registry.npmjs.org/anser/-/anser-2.3.5.tgz", - "integrity": "sha512-vcZjxvvVoxTeR5XBNJB38oTu/7eDCZlwdz32N1eNgpyPF7j/Z7Idf+CUwQOkKKpJ7RJyjxgLHCM7vdIK0iCNMQ==", - "license": "MIT" - }, "node_modules/ansi-regex": { "version": "6.3.0", "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.3.0.tgz", @@ -6672,21 +6659,6 @@ "url": "https://github.com/chalk/ansi-styles?sponsor=1" } }, - "node_modules/ansi-to-react": { - "version": "6.2.6", - "resolved": "https://registry.npmjs.org/ansi-to-react/-/ansi-to-react-6.2.6.tgz", - "integrity": "sha512-Eqi0iaMK5OZ3jsVFxWvU2B74UZBnGuHlkflKMX6wTOeH+luy9KE2O0gUkc2PxhIP1R4IO0xohv62UMFInQOSeg==", - "license": "BSD-3-Clause", - "dependencies": { - "anser": "^2.3.2", - "escape-carriage": "^1.3.1", - "linkify-it": "^3.0.3" - }, - "peerDependencies": { - "react": "^16.3.2 || ^17.0.0 || ^18.0.0 || ^19.0.0", - "react-dom": "^16.3.2 || ^17.0.0 || ^18.0.0 || ^19.0.0" - } - }, "node_modules/app-builder-lib": { "version": "26.16.1", "resolved": "https://registry.npmjs.org/app-builder-lib/-/app-builder-lib-26.16.1.tgz", @@ -7285,9 +7257,9 @@ "license": "MIT" }, "node_modules/brace-expansion": { - "version": "5.0.9", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz", - "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==", + "version": "5.0.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.12.tgz", + "integrity": "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==", "dev": true, "license": "MIT", "dependencies": { @@ -7591,13 +7563,13 @@ } }, "node_modules/chromium-bidi": { - "version": "17.0.2", - "resolved": "https://registry.npmjs.org/chromium-bidi/-/chromium-bidi-17.0.2.tgz", - "integrity": "sha512-5v9GQFhTktFvotn/OFNJBmKLKRAb6n9r0bVCwf7sHgWc3/JryK0bj1nn93L3pHFrfgcsu6Be6EWsDi+1XHTGDg==", + "version": "157.0.8090-0", + "resolved": "https://registry.npmjs.org/chromium-bidi/-/chromium-bidi-157.0.8090-0.tgz", + "integrity": "sha512-KJw7IQgqXwxpJgJlEIPg5mr2ZoqA+jkTRtc5EABI7sUJ3bu3cpI7NuEBoj4Gn1AsF78CaT9So5WQWspK3/wYag==", "license": "Apache-2.0", "dependencies": { "mitt": "^3.0.1", - "zod": "^3.24.1" + "zod": "^4.6.5" }, "engines": { "node": ">=20.19.0 <22.0.0 || >=22.12.0" @@ -7606,15 +7578,6 @@ "devtools-protocol": "*" } }, - "node_modules/chromium-bidi/node_modules/zod": { - "version": "3.25.76", - "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", - "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", - "license": "MIT", - "funding": { - "url": "https://github.com/sponsors/colinhacks" - } - }, "node_modules/chromium-pickle-js": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/chromium-pickle-js/-/chromium-pickle-js-0.2.0.tgz", @@ -7801,15 +7764,15 @@ "license": "MIT" }, "node_modules/concurrently": { - "version": "10.0.5", - "resolved": "https://registry.npmjs.org/concurrently/-/concurrently-10.0.5.tgz", - "integrity": "sha512-JaP/CoftUrCcAFW/g//RbgEGwlelnEae6cfBLgH6ZdO6s8jPkn6p9SB9u6pdVxYXoiSnFqseOlHfrEfF82TVOg==", + "version": "10.0.6", + "resolved": "https://registry.npmjs.org/concurrently/-/concurrently-10.0.6.tgz", + "integrity": "sha512-qgICXXFp2/3nAebRLmxcINKEXM1mLK3ij/y31P02VTs/KIkddIeC05n73DxOXsXMB9LFSqNU1/na3lDlOhcbIw==", "dev": true, "license": "MIT", "dependencies": { "chalk": "5.6.2", "rxjs": "7.8.2", - "shell-quote": "1.9.0", + "shell-quote": "1.12.0", "supports-color": "10.2.2", "tree-kill": "1.2.2", "yargs": "18.0.0" @@ -8793,9 +8756,9 @@ } }, "node_modules/devtools-protocol": { - "version": "0.0.1666840", - "resolved": "https://registry.npmjs.org/devtools-protocol/-/devtools-protocol-0.0.1666840.tgz", - "integrity": "sha512-gCcO42XCHKEs7Ag0S7aGYsnJ7hlgrO3qderYqeiY0Eqk+0GFfuvT13IA0hHreJTa2KCdDVyGMeOhdMNmrrTjVg==", + "version": "0.0.1704951", + "resolved": "https://registry.npmjs.org/devtools-protocol/-/devtools-protocol-0.0.1704951.tgz", + "integrity": "sha512-GQhQOs9u/Mvm1zMtJIH872JS4AskuZdUSsPNPk4ChahtWAUqgz6atEtIsMt+nO7MqF1Ic4HxII/k8Cu36JivNg==", "license": "BSD-3-Clause" }, "node_modules/dir-compare": { @@ -8928,9 +8891,9 @@ } }, "node_modules/dompurify": { - "version": "3.4.14", - "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.14.tgz", - "integrity": "sha512-dVoH9z+MY+C9IilgGCk3YfFqjLi3fChm2OiKJMzh6axrJ5qwxqWaZamgmHrpv22CN/KdbZJuGEGgfQoL00LTdg==", + "version": "3.4.17", + "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.17.tgz", + "integrity": "sha512-B/pSlYVHQ58kqISD/yDjuJ1yfzI34m1gF4lAod2bwSRhiN4K5Cl3H8Af7hqB2PmTL911tdEudnnXn5FnhRoz0w==", "license": "(MPL-2.0 OR Apache-2.0)", "optionalDependencies": { "@types/trusted-types": "^2.0.7" @@ -9663,12 +9626,6 @@ "node": ">=6" } }, - "node_modules/escape-carriage": { - "version": "1.3.1", - "resolved": "https://registry.npmjs.org/escape-carriage/-/escape-carriage-1.3.1.tgz", - "integrity": "sha512-GwBr6yViW3ttx1kb7/Oh+gKQ1/TrhYwxKqVmg5gS+BK+Qe2KrOa/Vh7w3HPBvgGf0LfcDGoY9I6NHKoA5Hozhw==", - "license": "MIT" - }, "node_modules/escape-html": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", @@ -9900,9 +9857,9 @@ "license": "MIT" }, "node_modules/eslint-plugin-import/node_modules/brace-expansion": { - "version": "1.1.18", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz", - "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==", + "version": "1.1.21", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz", + "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==", "dev": true, "license": "MIT", "dependencies": { @@ -9981,9 +9938,9 @@ "license": "MIT" }, "node_modules/eslint/node_modules/brace-expansion": { - "version": "1.1.18", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz", - "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==", + "version": "1.1.21", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz", + "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==", "dev": true, "license": "MIT", "dependencies": { @@ -10317,9 +10274,9 @@ "license": "Unlicense" }, "node_modules/fast-uri": { - "version": "3.1.8", - "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.8.tgz", - "integrity": "sha512-GZMtZUTNRpOVIECoXwLNZS5xUGE+mVNbTB8h/7Rwh2TFWcBQiPzTgyZi05BF9UMZKkLJv8XBRJTlU7zg8+ZfMg==", + "version": "3.1.9", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.9.tgz", + "integrity": "sha512-hS/0Wt3Ya043oKXs0sIxrMpKQITXhMLIrVAKKXi4gozGC9v7YRWVnXIZzjNPTO02M9BdxLCWqK1yRXgNziVyJQ==", "funding": [ { "type": "github", @@ -12708,15 +12665,6 @@ } } }, - "node_modules/linkify-it": { - "version": "3.0.3", - "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-3.0.3.tgz", - "integrity": "sha512-ynTsyrFSdE5oZ/O9GEf00kPngmOfVwazR5GKDq6EYfhlpFug3J2zybX56a2PRRpc9P+FuSoGNAwjlbDs9jJBPQ==", - "license": "MIT", - "dependencies": { - "uc.micro": "^1.0.1" - } - }, "node_modules/locate-path": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", @@ -14088,9 +14036,9 @@ } }, "node_modules/modern-tar": { - "version": "0.8.4", - "resolved": "https://registry.npmjs.org/modern-tar/-/modern-tar-0.8.4.tgz", - "integrity": "sha512-gN54ddmyzEg10orwZ2u4OOv+bjpMWdIl5jIkodK97bMq8QBSL5c0D7YX0lT1Ooz+99S7+PvFbnxzdjgHo1r41g==", + "version": "0.8.6", + "resolved": "https://registry.npmjs.org/modern-tar/-/modern-tar-0.8.6.tgz", + "integrity": "sha512-LYSks0tNVqbtez/9OB0YFP6qLRSqkdAxJWOQpVaR67lNTbj2zNLyYpowkRMia5lXLCZKzxwoxkxH2MbbBR2aEg==", "license": "MIT", "engines": { "node": ">=18.0.0" @@ -15313,17 +15261,17 @@ } }, "node_modules/puppeteer-core": { - "version": "25.8.0", - "resolved": "https://registry.npmjs.org/puppeteer-core/-/puppeteer-core-25.8.0.tgz", - "integrity": "sha512-LDOrawV8vfCVk+yLj2ozvajNP4Sv3OV9y3Tpiyy2g2Z+aQlbcozP6KJfI4iSBq7YQER+86ihEtPa5ioiZyWxMQ==", + "version": "25.16.0", + "resolved": "https://registry.npmjs.org/puppeteer-core/-/puppeteer-core-25.16.0.tgz", + "integrity": "sha512-VA5Pf54N8shfopNkZZXCdiiwfnnY8ZJYAMqFQRhlH5mGUhfwf53Ar770GPtdpTDLUqvQeYpIBtC9/G2Jij2IJw==", "license": "Apache-2.0", "dependencies": { - "@puppeteer/browsers": "3.2.1", - "chromium-bidi": "17.0.2", - "devtools-protocol": "0.0.1666840", - "typed-query-selector": "^2.12.2", - "webdriver-bidi-protocol": "0.4.2", - "ws": "^8.21.1" + "@puppeteer/browsers": "3.2.6", + "chromium-bidi": "157.0.8090-0", + "devtools-protocol": "0.0.1704951", + "typed-query-selector": "^2.12.3", + "webdriver-bidi-protocol": "1.0.1", + "ws": "^8.22.0" }, "engines": { "node": ">=22.12.0" @@ -15541,48 +15489,6 @@ "react": "^19.2.8" } }, - "node_modules/react-jsx-parser": { - "version": "2.4.1", - "resolved": "https://registry.npmjs.org/react-jsx-parser/-/react-jsx-parser-2.4.1.tgz", - "integrity": "sha512-gE25DiHseuKmSbb5O1K1IkyQ/bwth3zl4z3EdW8XMhwrb2agUpuh8GvqHFvGwh/wdZjDDuadGrSR2lEgjcOvqQ==", - "license": "MIT", - "dependencies": { - "acorn": "^8.12.1", - "acorn-jsx": "^5.3.2" - }, - "engines": { - "bun": "^1.1.27" - }, - "optionalDependencies": { - "@types/react": "^18.3.12", - "@types/react-dom": "^18.3.1" - }, - "peerDependencies": { - "react": ">=18", - "react-dom": ">=18" - } - }, - "node_modules/react-jsx-parser/node_modules/@types/react": { - "version": "18.3.31", - "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.31.tgz", - "integrity": "sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==", - "license": "MIT", - "optional": true, - "dependencies": { - "@types/prop-types": "*", - "csstype": "^3.2.2" - } - }, - "node_modules/react-jsx-parser/node_modules/@types/react-dom": { - "version": "18.3.7", - "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.7.tgz", - "integrity": "sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==", - "license": "MIT", - "optional": true, - "peerDependencies": { - "@types/react": "^18.0.0" - } - }, "node_modules/react-remove-scroll": { "version": "2.7.2", "resolved": "https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.7.2.tgz", @@ -16537,9 +16443,9 @@ } }, "node_modules/shell-quote": { - "version": "1.9.0", - "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.9.0.tgz", - "integrity": "sha512-Iov+JwFv/2HcTpcwNMKd8+IWNb8tboQJNQTkAY/LLVK7gGH9jy+LGkVqPxfekHl+yMmiqXszdGWXgkfml7hjqA==", + "version": "1.12.0", + "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.12.0.tgz", + "integrity": "sha512-PcByqNyT/38F2kDNi006HAMRJaULuBzq/FOsw3qdZvX/GA9W/jamDaRskgHjubHiftXK5sIFxLNkvrXUwcof6Q==", "dev": true, "license": "MIT", "engines": { @@ -16652,9 +16558,9 @@ } }, "node_modules/source-map-js": { - "version": "1.2.1", - "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz", - "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==", + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.2.tgz", + "integrity": "sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==", "license": "BSD-3-Clause", "engines": { "node": ">=0.10.0" @@ -16806,9 +16712,9 @@ "license": "MIT" }, "node_modules/string-width": { - "version": "8.2.2", - "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.2.tgz", - "integrity": "sha512-GaPUh5gfdrYzqeVNZvUfT23vYYxXzKYidUcnMtJg/3rxRV63EFZy3k6xfKlmfeJD0176lnUV/Usr3XcwSvFzpg==", + "version": "8.3.0", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.3.0.tgz", + "integrity": "sha512-ZbmZM0JCihQN91dWnxoipT2KOEyHqEyfRXUyjuRhW8b/xnqPDoq4gWEVApTVa9db2wN8mmoikgFBbjh71+cGeQ==", "license": "MIT", "dependencies": { "get-east-asian-width": "^1.5.0", @@ -17527,9 +17433,9 @@ } }, "node_modules/typed-query-selector": { - "version": "2.12.2", - "resolved": "https://registry.npmjs.org/typed-query-selector/-/typed-query-selector-2.12.2.tgz", - "integrity": "sha512-EOPFbyIub4ngnEdqi2yOcNeDLaX/0jcE1JoAXQDDMIthap7FoN795lc/SHfIq2d416VufXpM8z/lD+WRm2gfOQ==", + "version": "2.12.3", + "resolved": "https://registry.npmjs.org/typed-query-selector/-/typed-query-selector-2.12.3.tgz", + "integrity": "sha512-/dtuMZyutHLlrxWhhC1uib00ELUr2dZ8C9B8YzZYsJmeE3V56OxRblrSM2UaF142pcMtak7ehZ6+poWGeehNIg==", "license": "MIT" }, "node_modules/typescript": { @@ -17546,12 +17452,6 @@ "node": ">=14.17" } }, - "node_modules/uc.micro": { - "version": "1.0.6", - "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz", - "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==", - "license": "MIT" - }, "node_modules/uhyphen": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/uhyphen/-/uhyphen-0.2.0.tgz", @@ -17578,9 +17478,9 @@ } }, "node_modules/undici": { - "version": "7.29.0", - "resolved": "https://registry.npmjs.org/undici/-/undici-7.29.0.tgz", - "integrity": "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw==", + "version": "7.30.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.30.1.tgz", + "integrity": "sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==", "license": "MIT", "optional": true, "engines": { @@ -17982,9 +17882,9 @@ } }, "node_modules/webdriver-bidi-protocol": { - "version": "0.4.2", - "resolved": "https://registry.npmjs.org/webdriver-bidi-protocol/-/webdriver-bidi-protocol-0.4.2.tgz", - "integrity": "sha512-VSV+fzfChirL3e7jay2yUC7B4HQCGtEWEg/MSSQbK+qWbqeGlRLlXTzPpYr3XGUvbpDHumWZBJxgesg4N7dbtA==", + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/webdriver-bidi-protocol/-/webdriver-bidi-protocol-1.0.1.tgz", + "integrity": "sha512-WXWs/aXF2a6Al1Z2/V/7Gp2oPZOAAmHjJOTmv4KCXRJ122IMj3tSSMc6a4q3K4QOmhQbse/Ahr+oTVJOU2dUiw==", "license": "Apache-2.0" }, "node_modules/which": { @@ -18142,9 +18042,9 @@ "license": "ISC" }, "node_modules/ws": { - "version": "8.21.3", - "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz", - "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==", + "version": "8.22.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.22.0.tgz", + "integrity": "sha512-Ydggc987+RO0AnWtZ/7Wq9FtNvcrL1b/RO0ud9mWjUPgDrsAAwQSF51sm2hm1XofbU/4jkpGEsLFsZZxU+1DOg==", "license": "MIT", "engines": { "node": ">=10.0.0" @@ -18189,9 +18089,9 @@ "license": "ISC" }, "node_modules/yargs": { - "version": "18.1.0", - "resolved": "https://registry.npmjs.org/yargs/-/yargs-18.1.0.tgz", - "integrity": "sha512-2rAgRKu54VsHkqI0/tYkmluGXHD4KW7yZoycuqDQ15QOTnc2VVfy0nN/1eMhnQLO00A+dwtK20xuCnc1YGeUyg==", + "version": "18.2.0", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-18.2.0.tgz", + "integrity": "sha512-9OpKOLeaoNFecEp7P6iYbzze/5CqWoH7N3SMs/6y1XF4nMvFMspEGZzJ6uFi9MmQwXhyzqYoSEKO3tvA3Z/o2w==", "license": "MIT", "dependencies": { "cliui": "^9.0.1", @@ -18228,9 +18128,9 @@ } }, "node_modules/zod": { - "version": "4.4.3", - "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz", - "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==", + "version": "4.6.7", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.7.tgz", + "integrity": "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==", "license": "MIT", "funding": { "url": "https://github.com/sponsors/colinhacks" diff --git a/package.json b/package.json index 60c8f1ba89..2e1e2e82ba 100644 --- a/package.json +++ b/package.json @@ -37,7 +37,6 @@ "@streamdown/math": "^1.0.2", "@streamdown/mermaid": "^1.0.2", "@xyflow/react": "^12.11.3", - "ansi-to-react": "^6.2.6", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "cmdk": "^1.1.1", @@ -55,8 +54,8 @@ "mdast-util-from-markdown": "2.0.3", "mdast-util-math": "3.0.0", "media-chrome": "^4.19.2", - "micromark-extension-math": "3.1.0", "mermaid": "^11.17.0", + "micromark-extension-math": "3.1.0", "motion": "^13.1.1", "nanoid": "^6.0.1", "next": "^16.4.3", @@ -66,7 +65,6 @@ "radix-ui": "^1.6.7", "react": "^19.2.8", "react-dom": "^19.2.8", - "react-jsx-parser": "^2.4.1", "remark-breaks": "^4.0.0", "streamdown": "^2.5.0", "tailwind-merge": "^3.6.0", From d3b5ddb93c4d6a0955655de3deea8bb092588d3d Mon Sep 17 00:00:00 2001 From: Isaac Zhang Date: Sat, 7 Nov 2026 19:36:19 -0500 Subject: [PATCH 03/88] fix: tighten update-install IPC, CLI env, and ChatGPT credential reads - lh:update-install now uses the same trusted-window/main-frame sender check as lh:update:get and lh:update:check; untrusted requests are dropped and logged. - externalCliEnv strips LH_DESKTOP_API_SECRET and LH_DESKTOP_SERVER, as the browser-service helper's spawn env already does. - The ChatGPT credential reader refuses symlinks and, outside Windows, files readable by group/other or owned by another user, matching subscription-store.cjs. --- electron/chatgpt.cjs | 4 ++++ electron/main.cjs | 10 +++++++++- src/core/auth-env.ts | 4 ++++ tests/automatic-updates.test.ts | 22 ++++++++++++++++++++-- tests/chatgpt-file-store.test.ts | 17 +++++++++++++++++ tests/server-keys.test.ts | 7 +++++++ 6 files changed, 61 insertions(+), 3 deletions(-) diff --git a/electron/chatgpt.cjs b/electron/chatgpt.cjs index 6b3c6e9983..2764e0bb17 100644 --- a/electron/chatgpt.cjs +++ b/electron/chatgpt.cjs @@ -55,6 +55,10 @@ function fileStore(file) { return { async read() { try { + // Same rule as subscription-store.cjs: refuse a non-regular file, or + // (outside Windows) one readable by others or owned by another user. + const stat = await fs.lstat(file); + if (!stat.isFile() || (process.platform !== "win32" && ((stat.mode & 0o077) !== 0 || (typeof process.getuid === "function" && stat.uid !== process.getuid())))) throw fail("storage"); return validateState(JSON.parse(await fs.readFile(file, "utf8"))); } catch (err) { if (err.code === "ENOENT") return null; diff --git a/electron/main.cjs b/electron/main.cjs index 38c1e1afbf..833436935c 100644 --- a/electron/main.cjs +++ b/electron/main.cjs @@ -721,7 +721,15 @@ async function main() { // interval fire after it below. setupAutoUpdater's contract: failures // are log lines — this can never block boot. setupAutoUpdater(); - ipcMain.on("lh:update-install", () => installUpdateNow()); + // Same sender rule as lh:update:get/check. ipcMain.on has no reply channel, + // so an untrusted request is dropped and logged. + ipcMain.on("lh:update-install", (event) => { + if (!trustedAppWindows.has(BrowserWindow.fromWebContents(event.sender)) || !trustedSender(event, new URL(url).origin, BrowserWindow)) { + log("auto-update: ignored install request from an untrusted sender"); + return; + } + installUpdateNow(); + }); ipcMain.handle("lh:update:get", (event) => { if (!trustedAppWindows.has(BrowserWindow.fromWebContents(event.sender)) || !trustedSender(event, new URL(url).origin, BrowserWindow)) throw new Error("Untrusted desktop request."); return updateState; diff --git a/src/core/auth-env.ts b/src/core/auth-env.ts index f2d8a65c6a..bb31ff108a 100644 --- a/src/core/auth-env.ts +++ b/src/core/auth-env.ts @@ -20,5 +20,9 @@ export function externalCliEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.Pro for (const name of fillGap) { if (!realEnv.has(name)) delete result[name]; } + // The per-launch desktop API capability is for the trusted window only + // (same rule as the browser-service helper's spawn env). + delete result.LH_DESKTOP_API_SECRET; + delete result.LH_DESKTOP_SERVER; return result; } diff --git a/tests/automatic-updates.test.ts b/tests/automatic-updates.test.ts index 5875a7e1a4..92ac70932b 100644 --- a/tests/automatic-updates.test.ts +++ b/tests/automatic-updates.test.ts @@ -19,6 +19,7 @@ function fixture({ packaged = true, updaterMissing = false } = {}) { const order: string[] = []; const intervals: { callback: () => void; delay: number }[] = []; const handles = new Map unknown>(); + const listeners = new Map void>(); const windows: FakeWindow[] = []; let enumerationFails = false; let userData = "/fixture/custom-user-data"; @@ -81,7 +82,7 @@ function fixture({ packaged = true, updaterMissing = false } = {}) { const electron = { app, BrowserWindow: FakeWindow, Menu: { buildFromTemplate: (value: typeof menu) => value, setApplicationMenu: (value: typeof menu) => { menu = value; } }, - ipcMain: { on() {}, handle: (channel: string, fn: (event: unknown) => unknown) => handles.set(channel, fn) }, + ipcMain: { on: (channel: string, fn: (event: unknown) => void) => listeners.set(channel, fn), handle: (channel: string, fn: (event: unknown) => unknown) => handles.set(channel, fn) }, session: { defaultSession: { setPermissionRequestHandler() {}, setPermissionCheckHandler() {} } }, }; const context = createContext({ @@ -109,7 +110,7 @@ function fixture({ packaged = true, updaterMissing = false } = {}) { runInContext(mainSource, context, { filename: mainFile }); const run = (code: string) => runInContext(code, context); return { - run, updater, windows, intervals, handles, settingsReads, order, app, + run, updater, windows, intervals, handles, listeners, settingsReads, order, app, setSettings: (value: unknown) => { settings = JSON.stringify(value); }, setSettingsFailure: (value: string | Error) => { settings = value; }, setEnumerationFailure: (value: boolean) => { enumerationFails = value; }, @@ -270,6 +271,23 @@ describe("startup, timer, trusted IPC and menu wiring", () => { assert.equal(f.updater.checks, 1); }); + it("restart-to-install IPC accepts only an owned main frame", async () => { + const f = fixture(); await f.run("main()"); + const sender = f.windows[0]!.webContents; + const install = f.listeners.get("lh:update-install")!; + for (const bad of [ + { sender: {}, senderFrame: sender.mainFrame }, + { sender, senderFrame: { url: sender.mainFrame.url } }, + ]) install(bad); + const ownFrame = sender.mainFrame; + sender.mainFrame = { url: "https://untrusted.invalid/" }; + install({ sender, senderFrame: sender.mainFrame }); + assert.deepEqual(f.order, [], "untrusted senders never reach quit-and-install"); + sender.mainFrame = ownFrame; + install({ sender, senderFrame: sender.mainFrame }); + assert.deepEqual(f.order, ["install"]); + }); + it("menu restores/focuses a minimized window, opens General, and manually checks while OFF", async () => { const f = fixture(); f.setSettings({ general: { autoUpdate: false } }); await f.run("main()"); const win = f.windows[0]!; win.webContents.loading = false; win.minimized = true; diff --git a/tests/chatgpt-file-store.test.ts b/tests/chatgpt-file-store.test.ts index b4e56e5e30..47b9ede309 100644 --- a/tests/chatgpt-file-store.test.ts +++ b/tests/chatgpt-file-store.test.ts @@ -100,6 +100,23 @@ for (const phase of ["sync", "rename"] as const) { }); } +// Same rule as subscription-store.cjs. Symlink creation and POSIX modes are +// not portable to Windows test hosts, where the mode check is skipped anyway. +test("reads refuse symlinks and credentials readable by group/other", { skip: process.platform === "win32" }, async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), "lh-chatgpt-mode-")); + const file = path.join(dir, "chatgpt-credentials.json"); + try { + await fileStore(file).write(initial()); + assert.equal((await fs.stat(file)).mode & 0o777, 0o600); + assert.deepEqual(await fileStore(file).read(), initial(), "the store's own 0600 file reads normally"); + const link = path.join(dir, "linked-credentials.json"); + await fs.symlink(file, link); + await assert.rejects(fileStore(link).read(), /^Error: storage$/, "a symlink is not a regular credentials file"); + await fs.chmod(file, 0o644); + await assert.rejects(fileStore(file).read(), /^Error: storage$/, "group/other-readable credentials are refused"); + } finally { await fs.rm(dir, { recursive: true, force: true }); } +}); + test("file read/write failures are sanitized and cannot leak credential or path details", async () => { const dir = await fs.mkdtemp(path.join(os.tmpdir(), "lh-chatgpt-io-")); try { diff --git a/tests/server-keys.test.ts b/tests/server-keys.test.ts index acafc09fcc..717ac83d78 100644 --- a/tests/server-keys.test.ts +++ b/tests/server-keys.test.ts @@ -79,6 +79,13 @@ describe("boot fill-gap + precedence", () => { assert.equal(externalCliEnv().OPENROUTER_API_KEY, ENV_OWNED, "external CLIs retain launch-env ownership"); }); + it("external CLIs never receive the desktop API capability", () => { + const env = externalCliEnv({ ...process.env, PATH: "/usr/bin", LH_DESKTOP_SERVER: "1", LH_DESKTOP_API_SECRET: "d".repeat(64) }); + assert.equal(env.LH_DESKTOP_API_SECRET, undefined); + assert.equal(env.LH_DESKTOP_SERVER, undefined); + assert.equal(env.PATH, "/usr/bin", "ordinary launch env is kept"); + }); + it("unknown file var: fill-gapped into env, surfaced as a generic row", () => { assert.equal(process.env.FUTURE_PLANS_TOKEN, "opaque-plans-token", "reflected at boot"); assert.equal(externalCliEnv().FUTURE_PLANS_TOKEN, undefined, "external CLIs exclude unknown file-only injections too"); From 39babf15ea9f5dbf2bce7f1287f81394dbb3c0a8 Mon Sep 17 00:00:00 2001 From: Isaac Zhang Date: Mon, 9 Nov 2026 22:51:22 -0500 Subject: [PATCH 04/88] feat(claude-code): offer Fable in the model list --- docs/claude-code.md | 2 +- src/agent/claude-code/provider.ts | 1 + tests/claude-code-opt-in.test.ts | 2 +- tests/claude-code-provider.test.ts | 8 ++++---- tests/claude-code-usage.test.tsx | 2 +- tests/model-catalog.test.ts | 4 ++-- tests/send-to-user.test.ts | 1 + 7 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/claude-code.md b/docs/claude-code.md index c0d8781637..1393a63bad 100644 --- a/docs/claude-code.md +++ b/docs/claude-code.md @@ -7,7 +7,7 @@ LearnHarness can use an externally installed **Claude Code CLI** as a model prov 1. [Install and authenticate Claude Code](https://code.claude.com/docs/en/setup) outside LearnHarness, on **the machine running the LearnHarness server**, under its OS user. No always-running CLI process is needed. 2. Make the executable discoverable in that server's `PATH` or a common user/native installation location. On Windows, a directly runnable `claude.exe` is required; `claude.cmd` alone does not qualify. Desktop launch environments may differ from terminals. 3. Enable **Settings → Providers → External CLI → Claude Code**. This app-wide opt-in is **off by default**. Use **Check again** to refresh installation status. -4. Select a Claude Code model: `opus`, `sonnet`, or `haiku`. These are CLI aliases, not pinned underlying versions. +4. Select a Claude Code model: `opus`, `sonnet`, `haiku`, or `fable`. These are CLI aliases, not pinned underlying versions. The minimum version is **2.1.259** ([contract](../src/core/contracts/claude-code.ts)). The check runs only `--version`, not authentication or inference. Fresh model processes check again and refuse old/unverifiable versions. Passing proves neither account access, quota, billing method, nor complete protocol compatibility. diff --git a/src/agent/claude-code/provider.ts b/src/agent/claude-code/provider.ts index 0165e04b0b..49929079aa 100644 --- a/src/agent/claude-code/provider.ts +++ b/src/agent/claude-code/provider.ts @@ -21,6 +21,7 @@ export const CLAUDE_CODE_MODELS: readonly Model[] = [ { ...SHARED_MODEL_FIELDS, id: "opus", name: "Claude Opus" }, { ...SHARED_MODEL_FIELDS, id: "sonnet", name: "Claude Sonnet" }, { ...SHARED_MODEL_FIELDS, id: "haiku", name: "Claude Haiku" }, + { ...SHARED_MODEL_FIELDS, id: "fable", name: "Claude Fable" }, ]; export function createClaudeCodeProvider(streamSimple: StreamFunction): Provider { diff --git a/tests/claude-code-opt-in.test.ts b/tests/claude-code-opt-in.test.ts index b0e0026710..8322d33fa9 100644 --- a/tests/claude-code-opt-in.test.ts +++ b/tests/claude-code-opt-in.test.ts @@ -60,7 +60,7 @@ test("default off even with an installed binary; section writes toggle availabil assert(!modelCatalog().models.some((m) => m.provider === "claude-code")); assert.equal((await save({ enabled: true })).status, 200); assert.equal(claudeCodeEnabled(), true); assert.equal(claudeCodeAvailable(), true); - assert.equal(modelCatalog().models.filter((m) => m.provider === "claude-code").length, 3); + assert.equal(modelCatalog().models.filter((m) => m.provider === "claude-code").length, 4); assert.equal((await save({ enabled: false })).status, 200); assert.equal(claudeCodeAvailable(), false); assert(!modelCatalog().models.some((m) => m.provider === "claude-code")); diff --git a/tests/claude-code-provider.test.ts b/tests/claude-code-provider.test.ts index a8ef24d868..2035a27b34 100644 --- a/tests/claude-code-provider.test.ts +++ b/tests/claude-code-provider.test.ts @@ -18,15 +18,15 @@ function createCollection() { return collection; } -test("lists exactly the opus, sonnet and haiku aliases", () => { +test("lists exactly the opus, sonnet, haiku and fable aliases", () => { const models = createCollection().getModels(CLAUDE_CODE_PROVIDER); assert.deepEqual( models.map((m) => m.id), - ["opus", "sonnet", "haiku"], + ["opus", "sonnet", "haiku", "fable"], ); assert.deepEqual( models.map((m) => m.name), - ["Claude Opus", "Claude Sonnet", "Claude Haiku"], + ["Claude Opus", "Claude Sonnet", "Claude Haiku", "Claude Fable"], ); }); @@ -53,5 +53,5 @@ test("every cost field is zero", () => { test("auth resolves as configured without any key", async () => { const collection = createCollection(); assert.ok(await collection.checkAuth(CLAUDE_CODE_PROVIDER)); - assert.equal((await collection.getAvailable(CLAUDE_CODE_PROVIDER)).length, 3); + assert.equal((await collection.getAvailable(CLAUDE_CODE_PROVIDER)).length, 4); }); diff --git a/tests/claude-code-usage.test.tsx b/tests/claude-code-usage.test.tsx index 8415d2fab3..5e6d40447e 100644 --- a/tests/claude-code-usage.test.tsx +++ b/tests/claude-code-usage.test.tsx @@ -49,7 +49,7 @@ test("model-catalog API and menus never advertise the CLI adapter's placeholder const models = CLAUDE_CODE_MODELS.map(toModelDto); assert(models.every((model) => model.cost === null)); const html = renderToStaticMarkup( {}} />); - assert.equal((html.match(/>CLI billing<\/span>/g) ?? []).length, 3); + assert.equal((html.match(/>CLI billing<\/span>/g) ?? []).length, 4); assert.match(html, /does not estimate it/); assert(!html.includes("$0")); assert(!html.includes("USD per 1M")); assert(!html.includes("(subscription)")); }); diff --git a/tests/model-catalog.test.ts b/tests/model-catalog.test.ts index da2242c7d7..f1063bdd44 100644 --- a/tests/model-catalog.test.ts +++ b/tests/model-catalog.test.ts @@ -366,12 +366,12 @@ function withClaudeInstalled(installed: boolean, fn: () => void, enabled = true) } describe("the claude-code provider (native CLI authentication, no LearnHarness key)", () => { - it("modelCatalog() lists claude-code opus/sonnet/haiku when the CLI is installed", () => { + it("modelCatalog() lists claude-code opus/sonnet/haiku/fable when the CLI is installed", () => { withClaudeInstalled(true, () => { const ids = modelCatalog() .models.filter((m) => m.provider === "claude-code") .map((m) => m.id); - assert.deepEqual(ids, ["haiku", "opus", "sonnet"]); + assert.deepEqual(ids, ["fable", "haiku", "opus", "sonnet"]); }); }); diff --git a/tests/send-to-user.test.ts b/tests/send-to-user.test.ts index 8b31f001a2..b8c3c5b235 100644 --- a/tests/send-to-user.test.ts +++ b/tests/send-to-user.test.ts @@ -93,6 +93,7 @@ describe("send_to_user model gate", () => { ["claude-code", "opus", true], ["claude-code", "sonnet", true], ["claude-code", "haiku", true], + ["claude-code", "fable", true], ["openrouter", "z-ai/glm-5.3-flash", false], ["openai", "gpt-4o-mini", false], ["anthropic", "opaque-alias", false], From a1363aa1fa6610251dbb7ce885fdf1dd066ad3d8 Mon Sep 17 00:00:00 2001 From: Isaac Zhang Date: Tue, 10 Nov 2026 16:45:46 -0500 Subject: [PATCH 05/88] ci: re-run checks (plugin type-build tests timed out on the runner) From 7aee3722d5a8c23e0f6c6464b3693dc9ca30f74d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B0=D0=BB=D1=8C=D1=87=D1=83=D0=BA=D0=BE=D0=B2=20?= =?UTF-8?q?=D0=90=D0=BB=D0=B5=D0=BA=D1=81=D0=B5=D0=B9?= <106741316+LexMalch@users.noreply.github.com> Date: Thu, 12 Nov 2026 11:07:16 +0700 Subject: [PATCH 06/88] fix(side-chat): send the chat id as OpenCode's routing session Side questions on OpenCode Go fail before any token is used: 400 {"type":"MissingSessionID","message":"Request is missing x-opencode-session and cannot be routed efficiently."} pi-ai adds that header only when the request carries a session id, and streamSideAnswer deliberately left it out to keep Claude Code from resuming the lesson's live CLI process. That reason only applies to Claude Code: every HTTP provider now gets the chat id, so OpenCode Go can route the side question and keep its prompt cache warm. Regression coverage lives in tests/session-identity.test.ts: both OpenCode Go transports carry x-opencode-session, and a Claude Code side question still sends no session id. --- src/agent/side-chat.ts | 18 ++++++++++++++---- tests/session-identity.test.ts | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 4 deletions(-) diff --git a/src/agent/side-chat.ts b/src/agent/side-chat.ts index 4abce76c52..46fff2b663 100644 --- a/src/agent/side-chat.ts +++ b/src/agent/side-chat.ts @@ -1,9 +1,13 @@ /** * The SIDE-QUESTION model call: #487's tool-less streamed generation, - * using the session's conversation model. No agent loop, no tools, no - * session identity — a Claude Code - * call without a session id never retains or reuses the lesson's live - * CLI process (docs/claude-code.md "Questions, reuse, and cancellation"). + * using the session's conversation model. No agent loop, no tools, and no + * Claude Code session identity — a Claude Code call without a session id + * never retains or reuses the lesson's live CLI process + * (docs/claude-code.md "Questions, reuse, and cancellation"). Every other + * provider gets the chat id: pi-ai only adds OpenCode's required + * `x-opencode-session` routing header when the request carries a session + * id, so omitting it fails OpenCode Go side questions with 400 + * MissingSessionID before any token is used. * * Instructions: the side-chat base, then the curated shared appendix the * practice agent also composes (voice, accuracy, formatting — one law @@ -19,6 +23,7 @@ import path from "node:path"; import { randomUUID } from "node:crypto"; import { normalizeContext, type AssistantMessage, type Message, type Usage } from "@earendil-works/pi-ai"; import { backgroundCaptureStream, createBackgroundCapture } from "./background-capture.ts"; +import { CLAUDE_CODE_PROVIDER } from "./claude-code/constants.ts"; import { providerEventObserver } from "./provider-events.ts"; import { PATHS } from "../../config.ts"; import type { SideModelTurn } from "../core/side-chat.ts"; @@ -107,10 +112,15 @@ export async function streamSideAnswer(opts: { let failure: unknown; const capture = createBackgroundCapture({ role: "sideQuestion", runId: opts.runId ?? randomUUID(), sourceId: opts.chatId }); const providerEvents = opts.chatId ? providerEventObserver(opts.chatId, "sideQuestion") : undefined; + // OpenCode Go rejects requests without `x-opencode-session`; pi-ai derives + // it from this option. Claude Code treats it as a live process to resume, + // which a side question must never do. + const sessionId = opts.chatId && opts.engine.model.provider !== CLAUDE_CODE_PROVIDER ? opts.chatId : undefined; try { const stream = backgroundCaptureStream(opts.engine.streamFn, capture)(opts.engine.model, normalizeContext({ systemPrompt: opts.instructions, messages, tools: [] }), { signal: opts.signal, reasoning: opts.engine.level === "off" ? undefined : opts.engine.level, + ...(sessionId ? { sessionId } : {}), ...(providerEvents ? { onProviderStreamEvent: providerEvents } : {}), }); for await (const event of stream) { diff --git a/tests/session-identity.test.ts b/tests/session-identity.test.ts index 06a85e42d1..0f4473dc97 100644 --- a/tests/session-identity.test.ts +++ b/tests/session-identity.test.ts @@ -9,6 +9,8 @@ import { streamSimple as streamCodex } from "@earendil-works/pi-ai/api/openai-co import { APP_IDENTITY, piEngineForSpec, type PiEngine } from "../src/agent/models.ts"; import { createPluginWorkerService } from "../src/agent/plugin-workers.ts"; import { createProberAgent, createTeacherAgent, createPracticeAgent, type AgentBuildOptions } from "../src/agent/teacher-agent.ts"; +import { streamSideAnswer } from "../src/agent/side-chat.ts"; +import { CLAUDE_CODE_PROVIDER } from "../src/agent/claude-code/constants.ts"; import { runSubagent } from "../src/agent/subagents/pi-run.ts"; import { healToolRecord } from "../src/agent/tools/heal.ts"; import type { ModelCatalogResponse } from "../src/core/contracts/models.ts"; @@ -131,6 +133,37 @@ describe("native app and conversation identity", { concurrency: false }, () => { })); } + for (const [id, endpoint] of [ + ["claude-haiku-5-5", "/inference/go/v1/messages"], + ["glm-5.3", "/inference/go/v1/chat/completions"], + ] as const) { + it(`side questions carry the chat id so OpenCode Go can route ${id}`, async () => closed(async () => { + const engine = piEngineForSpec({ provider: "opencode-go", id, thinkingLevel: "off" }); + const requests: Request[] = []; + globalThis.fetch = async (input, init) => { const request = new Request(input, init); requests.push(request); await request.text(); return new Response('{"error":{"message":"closed fixture"}}', { status: 400, headers: { "content-type": "application/json" } }); }; + const result = await streamSideAnswer({ engine, instructions: "Offline", turns: [{ role: "user", text: "Why this step?" }], chatId: "chat_wire_side" }); + assert.equal(result.outcome, "error"); + assert.equal(requests.length, 1); + assert.equal(new URL(requests[0]!.url).pathname, endpoint); + assert.equal(requests[0]!.headers.get("x-opencode-session"), "chat_wire_side"); + assert.equal(requests[0]!.headers.get("x-opencode-client"), metadata.name); + })); + } + + it("side questions never resume a Claude Code live process", async () => { + const faux = createFauxCore({}); + faux.setResponses([fauxAssistantMessage([fauxText("offline answer")])]); + const seen: (string | undefined)[] = []; + const engine: PiEngine = { + model: { ...faux.getModel(), provider: CLAUDE_CODE_PROVIDER }, + level: "off", + streamFn: (model, context, options) => { seen.push(options?.sessionId); return faux.streamSimple(model, context, options); }, + }; + const result = await streamSideAnswer({ engine, instructions: "Offline", turns: [{ role: "user", text: "Why?" }], chatId: "chat_side_claude" }); + assert.equal(result.outcome, "done"); + assert.deepEqual(seen, [undefined]); + }); + it("native OpenAI cache keys clamp to 64 characters while affinity retains exact session", async () => closed(async () => { const engine = piEngineForSpec({ provider: "openai", id: "gpt-4o-mini", thinkingLevel: "off" }); const sessionId = "chat_" + "a".repeat(70); From 18d77ec1f07703173ba1343a97390e3d5164e44b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B0=D0=BB=D1=8C=D1=87=D1=83=D0=BA=D0=BE=D0=B2=20?= =?UTF-8?q?=D0=90=D0=BB=D0=B5=D0=BA=D1=81=D0=B5=D0=B9?= <106741316+LexMalch@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:16:31 +0700 Subject: [PATCH 07/88] test(side-chat): assert the provider session id at the service seam The unit test covers the stream options; this one drives the real side-chat service and records what reaches the engine, so a future refactor that drops the chat id from streamSideAnswer fails here instead of at the provider. --- tests/side-chat.test.ts | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/tests/side-chat.test.ts b/tests/side-chat.test.ts index 4838e16002..68b90e4708 100644 --- a/tests/side-chat.test.ts +++ b/tests/side-chat.test.ts @@ -472,3 +472,23 @@ describe("side chat service", () => { assert.equal(chatStore.getChat(other.chatId), null); }); }); + +describe("side chat provider routing", () => { + it("carries the chat id as the provider session so OpenCode Go can route the answer", async () => { + const faux = createFauxCore({}); + faux.appendResponses([() => fauxAssistantMessage("Short answer.")]); + let seen: string | undefined; + const engine: PiEngine = { + model: { ...faux.getModel(), provider: "opencode-go", id: "claude-haiku-5-5" }, + streamFn: (model, context, options) => { seen = options?.sessionId; return faux.streamSimple(model, context, options); }, + }; + const service = createSideChatService({ chatStore, engineFor: async () => engine, instructions: () => "SIDE-INSTRUCTIONS" }); + const chat = chatStore.createChat("side routing"); + const prose = assistant([text("A paragraph the learner selects."), call("q-routing", "quiz", QUIZ_ARGS)]); + chatStore.saveMessages(chat.id, [newUserMessage("teach me"), prose]); + const anchor: SideChatAnchor = { messageId: prose.id, partId: `${prose.id}-t0`, blockIndex: 0, blockText: "A paragraph the learner selects." }; + const lines = await readAll(await service.ask(chat.id, { anchor, text: "why?", quotes: [] })); + assert.equal(lines.at(-1)!.type, "done"); + assert.equal(seen, chat.id); + }); +}); From e8167fd750a560a3b13e216ea96815e2d249de38 Mon Sep 17 00:00:00 2001 From: smitmachhi Date: Thu, 12 Nov 2026 11:12:48 -0500 Subject: [PATCH 08/88] fix(chat): stop next dev from returning 500 on chat pages React's development server renderer seals each useRef object (Object.seal). Chat assigned `changed` onto one ref after creating it, and DockOverlay assigned it onto three more, so every chat page threw "Cannot add property changed, object is not extensible" under next dev. Production builds skip the seal, which hid the bug. The readers are now plain objects made once with useState, with `changed` included from the start. DockOverlay's readers forward `changed` to the latest parent reader, the same callback the old per-render assignment set. tests/chat-dev-render.test.tsx renders the chat with React's development server renderer. It failed with the same error before this change. --- components/chat.tsx | 22 +++++++++++----- tests/chat-dev-render.test.tsx | 47 ++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+), 7 deletions(-) create mode 100644 tests/chat-dev-render.test.tsx diff --git a/components/chat.tsx b/components/chat.tsx index f36d3c44e4..5a28da38de 100644 --- a/components/chat.tsx +++ b/components/chat.tsx @@ -321,10 +321,14 @@ export function Chat({ const submissionMounted = useRef(true); useEffect(() => { submissionMounted.current = true; return () => { submissionMounted.current = false; submissionRunner.dispose(); }; }, [submissionRunner]); useEffect(() => () => submissionRunner.dispose(), [surfaceTarget, submissionRunner]); - const inputViewReader = useRef<(() => PluginSessionViewInput) | null>(null) as SessionInputViewReader; const refreshPluginActions = useRef<(() => void) | null>(null); - const notifyViewChanged = useCallback(() => { if (submissionMounted.current) refreshPluginActions.current?.(); }, []); - inputViewReader.changed = notifyViewChanged; + // One stable object with `changed` from the start: React's development + // server renderer seals useRef objects, so adding `changed` to a ref later + // threw "object is not extensible" and every chat page 500ed under next dev. + const [inputViewReader] = useState(() => ({ + current: null, + changed: () => { if (submissionMounted.current) refreshPluginActions.current?.(); }, + })); const submissionLive = useRef({ nativeMessages, surfaceTarget, ready: true }); submissionLive.current = { nativeMessages, surfaceTarget, ready: true }; const runSubmission = async (target: PluginSubmissionTarget, capture: () => PluginSubmission | Promise, current: () => boolean, deliver: (prepared: PluginSubmission, attempt: SubmissionAttempt) => Promise): Promise => { @@ -2501,10 +2505,14 @@ export function DockOverlay({ const readingInputRef = useRef(null); const ownsDock = !!pending || !!pluginQuestion || unreadablePlugin || !!practice; const initialPendingRef = useRef(pendingId); - const nativeViewReader = useRef<(() => NativeQuestionViewState) | null>(null) as ViewReaderRef; - const practiceViewReader = useRef<(() => string) | null>(null) as ViewReaderRef; - const customViewReader = useRef<(() => { available: boolean }) | null>(null) as ViewReaderRef<{ available: boolean }>; - nativeViewReader.changed = practiceViewReader.changed = customViewReader.changed = viewReader?.changed; + // Stable reader objects with `changed` from the start (React's development + // server renderer seals useRef objects, so assigning `changed` onto refs + // threw under next dev). `changed` forwards to the latest parent reader. + const parentViewReader = useRef(viewReader); + parentViewReader.current = viewReader; + const [nativeViewReader] = useState>(() => ({ current: null, changed: () => parentViewReader.current?.changed?.() })); + const [practiceViewReader] = useState>(() => ({ current: null, changed: () => parentViewReader.current?.changed?.() })); + const [customViewReader] = useState>(() => ({ current: null, changed: () => parentViewReader.current?.changed?.() })); // Teach-question ARRIVAL state, applied during render — BEFORE the // first paint (owner, scroll-honesty round 2026-09-25). Until now the diff --git a/tests/chat-dev-render.test.tsx b/tests/chat-dev-render.test.tsx new file mode 100644 index 0000000000..49ab6ea36a --- /dev/null +++ b/tests/chat-dev-render.test.tsx @@ -0,0 +1,47 @@ +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { renderToString } from "react-dom/server"; +import { AppRouterContext } from "next/dist/shared/lib/app-router-context.shared-runtime.js"; +import { PathnameContext } from "next/dist/shared/lib/hooks-client-context.shared-runtime.js"; +import { Chat } from "../components/chat.tsx"; +import { ActivityProvider } from "../components/activity-dock.tsx"; +import { InteractionLayersProvider } from "../components/interaction-layers.tsx"; +import { PluginsProvider } from "../components/plugins.tsx"; +import { ServerEventsProvider } from "../components/server-events.tsx"; +import { AppearanceProvider } from "../components/settings/appearance.tsx"; +import { SettingsDialogProvider } from "../components/settings/settings-dialog.tsx"; +import { SidebarProvider } from "../components/sidebar.tsx"; +import { DEFAULT_THEME } from "../src/core/themes.ts"; + +// `next dev` server-renders every chat page with React's development build, +// which seals each useRef object (Object.seal). A property assigned to a ref +// afterwards throws "object is not extensible" and the page returns 500. +// Production builds skip the seal, so only dev broke. This renders the chat +// the same way, inside the providers app/layout.tsx and AppShell give it. +describe("chat server render (React development build)", () => { + it("renders an empty teaching chat without throwing", () => { + const router = { bfcacheId: "fixture", back() {}, forward() {}, refresh() {}, hmrRefresh() {}, push() {}, replace() {}, async prefetch() {} }; + const html = renderToString( + + + + + + + + + + + + + + + + + + + , + ); + assert.match(html, /Dev render/); + }); +}); From 25922a5a38f7f7c54ca8aa5363b8ad814ee4d040 Mon Sep 17 00:00:00 2001 From: smitmachhi Date: Thu, 12 Nov 2026 11:13:31 -0500 Subject: [PATCH 09/88] refactor(plan): move plan layout into plan-layout.ts plan-block.tsx held three things in 984 lines: layout math, edge geometry and three React views. The layout math (character-class width estimate, 28-letter wrap, dagre placement, edge paths) now lives in components/plan-layout.ts, unchanged. HEAD_H and HEAD_W become exports so the arrow markers keep using them. No behavior change. The existing plan tests pass with only their import paths changed. --- components/plan-block.tsx | 388 ++----------------------------- components/plan-layout.ts | 386 ++++++++++++++++++++++++++++++ tests/plan-window.test.tsx | 3 +- tests/render-plan-block.test.tsx | 6 +- 4 files changed, 403 insertions(+), 380 deletions(-) create mode 100644 components/plan-layout.ts diff --git a/components/plan-block.tsx b/components/plan-block.tsx index 99fd51bfb3..b1d07f0957 100644 --- a/components/plan-block.tsx +++ b/components/plan-block.tsx @@ -3,16 +3,19 @@ import { useEffect, useId, useMemo, useRef, useState } from "react"; import { MaximizeIcon, MinusIcon, PlusIcon, XIcon } from "lucide-react"; import { cn } from "@/lib/utils"; -// The placement engine — literally mermaid's: dagre-d3-es, the fork -// mermaid 11 ships with (owner, plan-graph round 8: same engine as the -// mermaid graphs, our SVG skin stays). The deep subpath is how mermaid -// itself imports it. -import { graphlib } from "dagre-d3-es"; -import { layout as dagreLayout } from "dagre-d3-es/src/dagre/index.js"; -// Mermaid's default flowchart edge curve: dagre's waypoints drawn through -// d3's curveBasis (the exact recipe dagre-d3's own renderer uses). -import { curveBasis, line } from "d3-shape"; import { fitGraphView, fitZoomFor, zoomedGraphView, type Viewport } from "@/components/pan-zoom"; +import { + blockLayout, + edgePathD, + wrapTitle, + HEAD_H, + HEAD_W, + LINE_H, + NODE_H, + NODE_W_MIN, + STROKE_W, + type LayoutNode, +} from "@/components/plan-layout"; import type { PlanBlockData, PlanNodeStatus, PlanTree } from "@/src/core"; import { derivedNodeStatus, derivePlanStatuses } from "@/src/core"; import { Hint } from "@/components/ui/hint"; @@ -37,256 +40,13 @@ import { InteractionLayerOwner, useInteractionLayer } from "./interaction-layers * * Hand-built SVG everywhere (user decision): placement runs on dagre * (mermaid's engine — deterministic, synchronous, DOM-free, so SSR and - * render tests stay exact); the skin is ours — no coupling to the graph + * render tests stay exact) in components/plan-layout.ts; the skin is ours — no coupling to the graph * stream's internals. Pan/zoom in the popup * is harvested from the retired tree panel's graph (fit-floor semantics: * fully zoomed out IS the fit; panning locks at the floor). */ -// ─── Layout constants + pure helpers (exported for tests) ──────────────────── -/** Text-first node sizing (owner, plan-hug round 2026-10-07): the box - * hugs its wrapped text instead of a fixed 160px slab. Width comes from - * the wrapped lines — a per-character-CLASS width estimate (the flat - * px/char rate of the first cut overshot the real rendered width, and - * the invisible slack read as "a lot of empty space" beside the text; - * owner follow-up 2026-10-07) plus symmetric padding, floored at a - * minimum so short titles don't collapse into pills. Estimate, NOT - * canvas measurement: the layout path stays deterministic, - * synchronous, and DOM-free (SSR + exact render pins keep working). */ - -/** Symmetric horizontal padding — EQUALS the vertical padding the - * single-line text gets in NODE_H (owner: "the horizontal padding - * should be the same as the vertical one"): (44 − 11) / 2 ≈ 16 (the - * prose font renders text-xs at 11px). */ -export const PAD_X = 16; -export const NODE_W_MIN = 96; -export const NODE_H = 44; - -// Width classes for the PROSE font (Source Sans 3 as shipped, text-xs -// rendering at 11px): narrow stems and punctuation, wide m/w, caps + -// digits, everything else. Rates least-squares-fitted against -// getComputedTextLength() measurements of the live plan titles -// (2026-10-07 smoke) — residuals land within ±4px per LINE, so -// per-side padding reads as PAD_X ±2. A different reading font -// (Appearance override) drifts the estimate slightly; accepted. -const NARROW_CHARS = new Set(" ijltfr.,:;'!|()[]-\\"); -const WIDE_CHARS = new Set("mwMW@"); -const CAP_DIGIT = /[A-Z0-9]/; - -/** Estimated rendered width (px) of one line at text-xs. Pure. */ -export function estimateLineWidth(line: string): number { - let w = 0; - for (const ch of line) { - if (NARROW_CHARS.has(ch)) w += 3.1; - else if (WIDE_CHARS.has(ch)) w += 9.2; - else if (CAP_DIGIT.test(ch)) w += 6.0; - else w += 5.4; - } - return w; -} -/** Baseline-to-baseline distance of node titles. */ -export const LINE_H = 13; -export const GAP_X = 24; -export const GAP_Y = 48; - -/** A node for layout purposes — the payload's shape and the tree's shape agree. */ -export interface LayoutNode { - id: string; - title: string; -} - -/** Topological order + longest-path depth (Kahn, authoring tie-break) — - * order + depth semantics kept for tests; placement itself runs on dagre - * now (owner, round 8). */ -export function topoFor(nodes: readonly LayoutNode[], edges: ReadonlyArray<{ from: string; to: string }>) { - const index = new Map(nodes.map((n, i) => [n.id, i] as const)); - const indegree = new Map(nodes.map((n) => [n.id, 0] as const)); - const dependents = new Map(); - for (const e of edges) { - if (!index.has(e.from) || !index.has(e.to)) continue; // defensive: dangling ids - indegree.set(e.to, (indegree.get(e.to) ?? 0) + 1); - const list = dependents.get(e.from); - if (list) list.push(e.to); - else dependents.set(e.from, [e.to]); - } - const ready = nodes.filter((n) => (indegree.get(n.id) ?? 0) === 0).map((n) => n.id); - const order: LayoutNode[] = []; - const depth = new Map(); - const byId = new Map(nodes.map((n) => [n.id, n] as const)); - while (ready.length > 0) { - ready.sort((a, b) => (index.get(a) ?? 0) - (index.get(b) ?? 0)); - const id = ready.shift()!; - const node = byId.get(id); - if (node) order.push(node); - const d = depth.get(id) ?? 0; - depth.set(id, d); - for (const t of dependents.get(id) ?? []) { - if ((depth.get(t) ?? -1) < d + 1) depth.set(t, d + 1); - const left = (indegree.get(t) ?? 0) - 1; - indegree.set(t, left); - if (left === 0) ready.push(t); - } - } - for (const n of nodes) { - if (!depth.has(n.id)) { - order.push(n); - depth.set(n.id, 0); - } - } - return { order, depth }; -} - -/** Placement — dagre (mermaid's engine, owner round 8): Sugiyama-style - * layered layout, TB, with our geometry (text-first sized boxes, - * GAP_X/GAP_Y - * separations, zero margin — the caller adds GRAPH_PAD/POPUP_PAD). - * Node sizes are fed in (boxes grow with their wrapped content, round - * 7); dagre returns node CENTERS, we hand back top-lefts like before, - * so every consumer (diagram, popup fit, plan window) is unchanged. - * Deterministic + synchronous + DOM-free: SSR and render tests stay - * exact. Dangling edges are ignored defensively — a ghost endpoint - * would spawn an unmeasured node and break the measurer. */ -export function blockLayout(nodes: readonly LayoutNode[], edges: ReadonlyArray<{ from: string; to: string }>) { - const x = new Map(); - const y = new Map(); - const nodeH = new Map(); - const nodeW = new Map(); - /** Dagre's per-edge waypoint routes — each starts/ends at the node - * border intersection on whatever SIDE the edge leaves/enters - * (round 11: the mermaid line drawing, no more fixed bottom-center → - * top-center). Keyed `${from}->${to}`. */ - const edgePts = new Map>(); - if (nodes.length === 0) return { x, y, nodeH, nodeW, edgePts, width: 0, height: 0 }; - const ids = new Set(nodes.map((n) => n.id)); - const routed: Array<{ from: string; to: string }> = []; - const g = new graphlib.Graph({ compound: false, multigraph: true }); - g.setGraph({ rankdir: "TB", nodesep: GAP_X, ranksep: GAP_Y, marginx: 0, marginy: 0 }); - for (const n of nodes) { - const lines = wrapTitle(n.title); - const h = NODE_H + Math.max(0, lines.length - 2) * LINE_H; - nodeH.set(n.id, h); - nodeW.set(n.id, nodeWidth(lines)); - g.setNode(n.id, { width: nodeW.get(n.id)!, height: h }); - } - for (const e of edges) { - if (ids.has(e.from) && ids.has(e.to)) { - g.setEdge(e.from, e.to, { label: "", width: 0, height: 0 }); - routed.push(e); - } - } - // (the d.ts marks opts required; the runtime ignores it) - dagreLayout(g, undefined); - for (const n of nodes) { - const pos = g.node(n.id); - const h = nodeH.get(n.id) ?? NODE_H; - const w = nodeW.get(n.id) ?? NODE_W_MIN; - if (pos) { - x.set(n.id, pos.x - w / 2); - y.set(n.id, pos.y - h / 2); - } - } - for (const e of routed) { - const pts: Array<{ x: number; y: number }> | undefined = g.edge(e.from, e.to)?.points; - if (pts) edgePts.set(`${e.from}->${e.to}`, pts.map((pt) => ({ x: pt.x, y: pt.y }))); - } - // THE CANVAS MUST COVER THE ARROWS (owner, 2026-10-10): dagre's - // graph extent is the NODE bounding box — the edge curves drawn on - // top can bow past it (cross-column edges' bezier control points; - // measured 14–20px cut on the right in the owner's plans) and the - // viewBox clipped them. The ink extent unions the node boxes with - // every edge path's control-point hull: a bezier never leaves the - // hull of its control points, and parsing the d-string edgePathD - // builds (the SAME call the renderer makes, same inputs) bounds every - // segment — M, L and C pairs alternate strictly, so even/odd matches - // are x/y. Dagre's extent stays the FLOOR: plans whose arrows stay - // inside keep byte-identical viewBoxes (no reflow of every pinned - // render), and the origin only moves when ink bulges past zero. - let inkMinX = Infinity; - let inkMinY = Infinity; - let inkMaxX = -Infinity; - let inkMaxY = -Infinity; - const stretch = (px: number, py: number) => { - if (px < inkMinX) inkMinX = px; - if (py < inkMinY) inkMinY = py; - if (px > inkMaxX) inkMaxX = px; - if (py > inkMaxY) inkMaxY = py; - }; - for (const n of nodes) { - const nx = x.get(n.id); - const ny = y.get(n.id); - if (nx === undefined || ny === undefined) continue; - stretch(nx, ny); - stretch(nx + (nodeW.get(n.id) ?? NODE_W_MIN), ny + (nodeH.get(n.id) ?? NODE_H)); - } - for (const e of routed) { - const pts = edgePts.get(`${e.from}->${e.to}`); - if (!pts) continue; - const tx = x.get(e.to); - const ty = y.get(e.to); - const target = - tx !== undefined && ty !== undefined - ? { - x: tx, - y: ty, - w: nodeW.get(e.to) ?? NODE_W_MIN, - h: nodeH.get(e.to) ?? NODE_H, - } - : undefined; - const nums = edgePathD(pts, target).match(/-?\d+(?:\.\d+)?/g); - if (!nums) continue; - for (let i = 0; i + 1 < nums.length; i += 2) { - stretch(parseFloat(nums[i]!), parseFloat(nums[i + 1]!)); - } - } - // Dagre coordinates start at 0; only ink past zero on the negative - // side moves the origin (viewBox x/y shift with it). - const originX = Math.min(0, inkMinX === Infinity ? 0 : inkMinX); - const originY = Math.min(0, inkMinY === Infinity ? 0 : inkMinY); - return { - x, - y, - nodeH, - nodeW, - edgePts, - originX, - originY, - width: Math.max((g.graph().width ?? 0) - originX, inkMaxX === -Infinity ? 0 : inkMaxX - originX, 1), - height: Math.max((g.graph().height ?? 0) - originY, inkMaxY === -Infinity ? 0 : inkMaxY - originY, 1), - }; -} - -/** Greedy word wrap to lines of ≤ maxChars — NOTHING is dropped: the - * node's box grows to fit every line (owner: show the full content of - * each node). A single oversized word is hard-chunked across lines at - * maxChars. Pure. */ -export function wrapTitle(title: string, maxChars = 28): string[] { - const words = title.trim().split(/\s+/).filter(Boolean); - if (words.length === 0) return [""]; - // Oversized words can never fit a line — chunk them so no content is lost. - const atoms: string[] = []; - for (const w of words) { - for (let i = 0; i < w.length; i += maxChars) atoms.push(w.slice(i, i + maxChars)); - } - const lines: string[] = []; - for (const a of atoms) { - const last = lines[lines.length - 1]; - if (last !== undefined && last.length + 1 + a.length <= maxChars) { - lines[lines.length - 1] = `${last} ${a}`; - } else { - lines.push(a); - } - } - return lines; -} - -// ─── Geometry caps (owner, plan-graph refinement round 1) ───────────────────── - -/** A node's box width for its wrapped lines — the hug itself. Pure. */ -export function nodeWidth(lines: readonly string[]): number { - const widest = Math.max(1, ...lines.map(estimateLineWidth)); - return Math.max(NODE_W_MIN, Math.ceil(widest) + 2 * PAD_X); -} /** SVG-unit padding around the layout extent: strokes are centered on the * geometry (half bleeds outside the extent) and the glow halo reaches −4 — @@ -313,129 +73,7 @@ export const TEXT_CAP_SCALE = 16 / 12.5; * x 27.2 with a 9.6-tall opening — at full height 104 the tail opening * is ≈10, per the owner's spec. Solid strong-ink fill, no padding. */ export const ARROW_HEAD = "M48,55.2C49.4,54.6 50.2,53.4 50.2,52C50.2,50.6 49.4,49.4 48,48.8C38.2,45.6 29.2,38.8 21,28.4C15.2,21.4 11.4,13.2 9.6,3.8C9,1.2 7.4,0 4.8,0C1.6,0 0,1.6 0,5L0.2,5.6C3.6,23 12.6,36.8 27.2,47.2L27.2,56.8C12.6,67.2 3.6,81 0.2,98.4L0,99C0,102.4 1.6,104 4.8,104C7.4,104 9,102.8 9.6,100.2C11.4,90.8 15.2,82.6 21,75.6C29.2,65.2 38.2,58.4 48,55.2Z"; -/** Lines + outlines run at the app's standard border weight (owner, - * 2026-09-26 — same 1px the UI borders use; was 1.5). */ -export const STROKE_W = 1; -/** The heads scale by the SAME factor the lines thinned by (owner, - * 2026-09-26): 16 was the height tuned for 1.5-wide lines, so both sides - * of the head:shaft proportion shrink together — the LaTeX ratio (tail - * opening tucking the line flush) is preserved exactly, just smaller. */ -const HEAD_H = 16 * (STROKE_W / 1.5); -const HEAD_SCALE = HEAD_H / 104; -const HEAD_W = 50.2 * HEAD_SCALE; -/** The drawn line terminates at the notch mouth (refX 27.2) — it never - * reaches the narrow tip, where it would show through (owner). The tip - * overhangs the line's end by this much, so edges shorten by it to land - * the tip exactly on the target node's border. */ -const HEAD_TIP_OVERHANG = (50.2 - 27.2) * HEAD_SCALE; -/** The head floats this far off the target face — the tip kisses nothing - * (owner, round 12). ~half a head length: clearly docked-off, still - * visually attached. Scaled with the head (2026-09-26) so "half a head" - * stays true at the thinner lines. */ -const DOCK_GAP = 4 * (STROKE_W / 1.5); -/** The shaft stub — the straight run before the head (owner, round 12): - * control points from Q on sit exactly on the approach line, so the - * basis spline renders that stretch perfectly straight and the head - * lands on a straight shaft; the corner where the route squares up onto - * the line is rounded by the curve. ~1.5 head lengths of shaft. */ -const STRAIGHT_RUN = 12; -/** The tilt limit at the termination point, measured off the entry - * face's perpendicular: past ±40° one of the head's barbs crosses the - * tip's level and the silhouette breaks (owner measured it in - * Photoshop, round 14). The final run swings to the cone edge instead. */ -const ENTRY_ANGLE_LIMIT = (40 * Math.PI) / 180; -const edgeLine = line<{ x: number; y: number }>() - .x((p) => p.x) - .y((p) => p.y) - .curve(curveBasis); - -/** The entry face's outward unit normal — whichever face of the target - * box dagre's border point sits on. Pure. */ -function faceNormal( - border: { x: number; y: number }, - box: { x: number; y: number; w: number; h: number }, -): { x: number; y: number } { - const d = { top: border.y - box.y, bottom: box.y + box.h - border.y, left: border.x - box.x, right: box.x + box.w - border.x }; - const face = (Object.keys(d) as Array).reduce((a, b) => (d[a] <= d[b] ? a : b)); - switch (face) { - case "top": - return { x: 0, y: -1 }; - case "bottom": - return { x: 0, y: 1 }; - case "left": - return { x: -1, y: 0 }; - default: - return { x: 1, y: 0 }; - } -} -/** The edge path — mermaid's own line drawing: dagre's border-intersected - * waypoints through d3's curveBasis (mermaid's default flowchart curve — - * the same recipe dagre-d3's renderer uses). The head docks off the - * target: its TIP floats DOCK_GAP past the border along the FACE NORMAL - * (constant gap at any tilt), its mouth sits at the path's end on a - * straight run (the shaft stub), and — when the target box is given — - * the entry direction is clamped to ±ENTRY_ANGLE_LIMIT of the face's - * perpendicular (owner, round 14): a steeper natural approach swings to - * the 40° cone edge instead of breaking the head's silhouette. Without - * a target box the unclamped geometry applies. Straight collinear - * routes render identically. Pure, exported for tests. */ -export function edgePathD( - points: Array<{ x: number; y: number }>, - target?: { x: number; y: number; w: number; h: number }, -): string { - const pts = points.map((p) => ({ ...p })); - if (pts.length >= 2) { - const last = pts[pts.length - 1]!; - const prev = pts[pts.length - 2]!; - const dx = last.x - prev.x; - const dy = last.y - prev.y; - const len = Math.hypot(dx, dy) || 1; - let ux = dx / len; - let uy = dy / len; - // The tip: DOCK_GAP outside the face along its normal (or along the - // approach when no box is known). - let tipx: number; - let tipy: number; - if (target) { - const n = faceNormal(last, target); - tipx = last.x + n.x * DOCK_GAP; - tipy = last.y + n.y * DOCK_GAP; - // Clamp the approach to the ±LIMIT cone around the normal: if - // the outgoing direction -u tilts past ENTRY_ANGLE_LIMIT, swing - // it to the cone edge (same rotation side as the route). - const v = { x: -ux, y: -uy }; - const vn = v.x * n.x + v.y * n.y; - if (vn < Math.cos(ENTRY_ANGLE_LIMIT)) { - const t = { x: v.x - vn * n.x, y: v.y - vn * n.y }; - const tl = Math.hypot(t.x, t.y); - const that = tl > 0 ? { x: t.x / tl, y: t.y / tl } : { x: -n.y, y: n.x }; - const c = Math.cos(ENTRY_ANGLE_LIMIT); - const s = Math.sin(ENTRY_ANGLE_LIMIT); - v.x = c * n.x + s * that.x; - v.y = c * n.y + s * that.y; - ux = -v.x; - uy = -v.y; - } - } else { - tipx = last.x - ux * DOCK_GAP; - tipy = last.y - uy * DOCK_GAP; - } - // The mouth: overhang back from the tip along the (clamped) approach. - const M = { x: tipx - ux * HEAD_TIP_OVERHANG, y: tipy - uy * HEAD_TIP_OVERHANG }; - // From Q the control points lie on the approach line — the basis - // spline renders Q→M perfectly straight (a B-spline span with - // collinear control points IS the line), and curveBasis's internal - // endpoint repetition makes the end tangent exactly the approach - // direction. NOTE: do NOT repeat M manually — a duplicated final - // control point renders a zero-length last segment, and - // orient="auto" on a zero-length segment falls back to 0° (every - // head pointing right — the round-12 regression, fixed round 13). - const Q = { x: M.x - ux * STRAIGHT_RUN, y: M.y - uy * STRAIGHT_RUN }; - pts.splice(pts.length - 1, 1, Q, M); - } - return edgeLine(pts) ?? ""; -} // ─── Status styling (the retired panel's color language, unchanged) ────────── diff --git a/components/plan-layout.ts b/components/plan-layout.ts new file mode 100644 index 0000000000..e828864270 --- /dev/null +++ b/components/plan-layout.ts @@ -0,0 +1,386 @@ +/** + * PLAN LAYOUT — where every plan box goes and how big it is. Pure: no DOM, + * no React. Shared by the in-chat block, the popup and the dock marginalia + * (components/plan-block.tsx, components/plan-window.tsx). + */ + +// The placement engine — literally mermaid's: dagre-d3-es, the fork +// mermaid 11 ships with (owner, plan-graph round 8: same engine as the +// mermaid graphs, our SVG skin stays). The deep subpath is how mermaid +// itself imports it. +import { graphlib } from "dagre-d3-es"; +import { layout as dagreLayout } from "dagre-d3-es/src/dagre/index.js"; +// Mermaid's default flowchart edge curve: dagre's waypoints drawn through +// d3's curveBasis (the exact recipe dagre-d3's own renderer uses). +import { curveBasis, line } from "d3-shape"; + +// ─── Layout constants + pure helpers (exported for tests) ──────────────────── + +/** Text-first node sizing (owner, plan-hug round 2026-10-07): the box + * hugs its wrapped text instead of a fixed 160px slab. Width comes from + * the wrapped lines — a per-character-CLASS width estimate (the flat + * px/char rate of the first cut overshot the real rendered width, and + * the invisible slack read as "a lot of empty space" beside the text; + * owner follow-up 2026-10-07) plus symmetric padding, floored at a + * minimum so short titles don't collapse into pills. Estimate, NOT + * canvas measurement: the layout path stays deterministic, + * synchronous, and DOM-free (SSR + exact render pins keep working). */ + +/** Symmetric horizontal padding — EQUALS the vertical padding the + * single-line text gets in NODE_H (owner: "the horizontal padding + * should be the same as the vertical one"): (44 − 11) / 2 ≈ 16 (the + * prose font renders text-xs at 11px). */ +export const PAD_X = 16; +export const NODE_W_MIN = 96; +export const NODE_H = 44; + +// Width classes for the PROSE font (Source Sans 3 as shipped, text-xs +// rendering at 11px): narrow stems and punctuation, wide m/w, caps + +// digits, everything else. Rates least-squares-fitted against +// getComputedTextLength() measurements of the live plan titles +// (2026-10-07 smoke) — residuals land within ±4px per LINE, so +// per-side padding reads as PAD_X ±2. A different reading font +// (Appearance override) drifts the estimate slightly; accepted. +const NARROW_CHARS = new Set(" ijltfr.,:;'!|()[]-\\"); +const WIDE_CHARS = new Set("mwMW@"); +const CAP_DIGIT = /[A-Z0-9]/; + +/** Estimated rendered width (px) of one line at text-xs. Pure. */ +export function estimateLineWidth(line: string): number { + let w = 0; + for (const ch of line) { + if (NARROW_CHARS.has(ch)) w += 3.1; + else if (WIDE_CHARS.has(ch)) w += 9.2; + else if (CAP_DIGIT.test(ch)) w += 6.0; + else w += 5.4; + } + return w; +} +/** Baseline-to-baseline distance of node titles. */ +export const LINE_H = 13; +export const GAP_X = 24; +export const GAP_Y = 48; + +/** A node for layout purposes — the payload's shape and the tree's shape agree. */ +export interface LayoutNode { + id: string; + title: string; +} + +/** Topological order + longest-path depth (Kahn, authoring tie-break) — + * order + depth semantics kept for tests; placement itself runs on dagre + * now (owner, round 8). */ +export function topoFor(nodes: readonly LayoutNode[], edges: ReadonlyArray<{ from: string; to: string }>) { + const index = new Map(nodes.map((n, i) => [n.id, i] as const)); + const indegree = new Map(nodes.map((n) => [n.id, 0] as const)); + const dependents = new Map(); + for (const e of edges) { + if (!index.has(e.from) || !index.has(e.to)) continue; // defensive: dangling ids + indegree.set(e.to, (indegree.get(e.to) ?? 0) + 1); + const list = dependents.get(e.from); + if (list) list.push(e.to); + else dependents.set(e.from, [e.to]); + } + const ready = nodes.filter((n) => (indegree.get(n.id) ?? 0) === 0).map((n) => n.id); + const order: LayoutNode[] = []; + const depth = new Map(); + const byId = new Map(nodes.map((n) => [n.id, n] as const)); + while (ready.length > 0) { + ready.sort((a, b) => (index.get(a) ?? 0) - (index.get(b) ?? 0)); + const id = ready.shift()!; + const node = byId.get(id); + if (node) order.push(node); + const d = depth.get(id) ?? 0; + depth.set(id, d); + for (const t of dependents.get(id) ?? []) { + if ((depth.get(t) ?? -1) < d + 1) depth.set(t, d + 1); + const left = (indegree.get(t) ?? 0) - 1; + indegree.set(t, left); + if (left === 0) ready.push(t); + } + } + for (const n of nodes) { + if (!depth.has(n.id)) { + order.push(n); + depth.set(n.id, 0); + } + } + return { order, depth }; +} + +/** Placement — dagre (mermaid's engine, owner round 8): Sugiyama-style + * layered layout, TB, with our geometry (text-first sized boxes, + * GAP_X/GAP_Y + * separations, zero margin — the caller adds GRAPH_PAD/POPUP_PAD). + * Node sizes are fed in (boxes grow with their wrapped content, round + * 7); dagre returns node CENTERS, we hand back top-lefts like before, + * so every consumer (diagram, popup fit, plan window) is unchanged. + * Deterministic + synchronous + DOM-free: SSR and render tests stay + * exact. Dangling edges are ignored defensively — a ghost endpoint + * would spawn an unmeasured node and break the measurer. */ +export function blockLayout(nodes: readonly LayoutNode[], edges: ReadonlyArray<{ from: string; to: string }>) { + const x = new Map(); + const y = new Map(); + const nodeH = new Map(); + const nodeW = new Map(); + /** Dagre's per-edge waypoint routes — each starts/ends at the node + * border intersection on whatever SIDE the edge leaves/enters + * (round 11: the mermaid line drawing, no more fixed bottom-center → + * top-center). Keyed `${from}->${to}`. */ + const edgePts = new Map>(); + if (nodes.length === 0) return { x, y, nodeH, nodeW, edgePts, width: 0, height: 0 }; + const ids = new Set(nodes.map((n) => n.id)); + const routed: Array<{ from: string; to: string }> = []; + const g = new graphlib.Graph({ compound: false, multigraph: true }); + g.setGraph({ rankdir: "TB", nodesep: GAP_X, ranksep: GAP_Y, marginx: 0, marginy: 0 }); + for (const n of nodes) { + const lines = wrapTitle(n.title); + const h = NODE_H + Math.max(0, lines.length - 2) * LINE_H; + nodeH.set(n.id, h); + nodeW.set(n.id, nodeWidth(lines)); + g.setNode(n.id, { width: nodeW.get(n.id)!, height: h }); + } + for (const e of edges) { + if (ids.has(e.from) && ids.has(e.to)) { + g.setEdge(e.from, e.to, { label: "", width: 0, height: 0 }); + routed.push(e); + } + } + // (the d.ts marks opts required; the runtime ignores it) + dagreLayout(g, undefined); + for (const n of nodes) { + const pos = g.node(n.id); + const h = nodeH.get(n.id) ?? NODE_H; + const w = nodeW.get(n.id) ?? NODE_W_MIN; + if (pos) { + x.set(n.id, pos.x - w / 2); + y.set(n.id, pos.y - h / 2); + } + } + for (const e of routed) { + const pts: Array<{ x: number; y: number }> | undefined = g.edge(e.from, e.to)?.points; + if (pts) edgePts.set(`${e.from}->${e.to}`, pts.map((pt) => ({ x: pt.x, y: pt.y }))); + } + // THE CANVAS MUST COVER THE ARROWS (owner, 2026-10-10): dagre's + // graph extent is the NODE bounding box — the edge curves drawn on + // top can bow past it (cross-column edges' bezier control points; + // measured 14–20px cut on the right in the owner's plans) and the + // viewBox clipped them. The ink extent unions the node boxes with + // every edge path's control-point hull: a bezier never leaves the + // hull of its control points, and parsing the d-string edgePathD + // builds (the SAME call the renderer makes, same inputs) bounds every + // segment — M, L and C pairs alternate strictly, so even/odd matches + // are x/y. Dagre's extent stays the FLOOR: plans whose arrows stay + // inside keep byte-identical viewBoxes (no reflow of every pinned + // render), and the origin only moves when ink bulges past zero. + let inkMinX = Infinity; + let inkMinY = Infinity; + let inkMaxX = -Infinity; + let inkMaxY = -Infinity; + const stretch = (px: number, py: number) => { + if (px < inkMinX) inkMinX = px; + if (py < inkMinY) inkMinY = py; + if (px > inkMaxX) inkMaxX = px; + if (py > inkMaxY) inkMaxY = py; + }; + for (const n of nodes) { + const nx = x.get(n.id); + const ny = y.get(n.id); + if (nx === undefined || ny === undefined) continue; + stretch(nx, ny); + stretch(nx + (nodeW.get(n.id) ?? NODE_W_MIN), ny + (nodeH.get(n.id) ?? NODE_H)); + } + for (const e of routed) { + const pts = edgePts.get(`${e.from}->${e.to}`); + if (!pts) continue; + const tx = x.get(e.to); + const ty = y.get(e.to); + const target = + tx !== undefined && ty !== undefined + ? { + x: tx, + y: ty, + w: nodeW.get(e.to) ?? NODE_W_MIN, + h: nodeH.get(e.to) ?? NODE_H, + } + : undefined; + const nums = edgePathD(pts, target).match(/-?\d+(?:\.\d+)?/g); + if (!nums) continue; + for (let i = 0; i + 1 < nums.length; i += 2) { + stretch(parseFloat(nums[i]!), parseFloat(nums[i + 1]!)); + } + } + // Dagre coordinates start at 0; only ink past zero on the negative + // side moves the origin (viewBox x/y shift with it). + const originX = Math.min(0, inkMinX === Infinity ? 0 : inkMinX); + const originY = Math.min(0, inkMinY === Infinity ? 0 : inkMinY); + return { + x, + y, + nodeH, + nodeW, + edgePts, + originX, + originY, + width: Math.max((g.graph().width ?? 0) - originX, inkMaxX === -Infinity ? 0 : inkMaxX - originX, 1), + height: Math.max((g.graph().height ?? 0) - originY, inkMaxY === -Infinity ? 0 : inkMaxY - originY, 1), + }; +} + +/** Greedy word wrap to lines of ≤ maxChars — NOTHING is dropped: the + * node's box grows to fit every line (owner: show the full content of + * each node). A single oversized word is hard-chunked across lines at + * maxChars. Pure. */ +export function wrapTitle(title: string, maxChars = 28): string[] { + const words = title.trim().split(/\s+/).filter(Boolean); + if (words.length === 0) return [""]; + // Oversized words can never fit a line — chunk them so no content is lost. + const atoms: string[] = []; + for (const w of words) { + for (let i = 0; i < w.length; i += maxChars) atoms.push(w.slice(i, i + maxChars)); + } + const lines: string[] = []; + for (const a of atoms) { + const last = lines[lines.length - 1]; + if (last !== undefined && last.length + 1 + a.length <= maxChars) { + lines[lines.length - 1] = `${last} ${a}`; + } else { + lines.push(a); + } + } + return lines; +} + +// ─── Geometry caps (owner, plan-graph refinement round 1) ───────────────────── + +/** A node's box width for its wrapped lines — the hug itself. Pure. */ +export function nodeWidth(lines: readonly string[]): number { + const widest = Math.max(1, ...lines.map(estimateLineWidth)); + return Math.max(NODE_W_MIN, Math.ceil(widest) + 2 * PAD_X); +} + +// ─── Edge paths (the owner's arrowhead geometry) ────────────────────────────── + +/** Lines + outlines run at the app's standard border weight (owner, + * 2026-09-26 — same 1px the UI borders use; was 1.5). */ +export const STROKE_W = 1; +/** The heads scale by the SAME factor the lines thinned by (owner, + * 2026-09-26): 16 was the height tuned for 1.5-wide lines, so both sides + * of the head:shaft proportion shrink together — the LaTeX ratio (tail + * opening tucking the line flush) is preserved exactly, just smaller. */ +export const HEAD_H = 16 * (STROKE_W / 1.5); +const HEAD_SCALE = HEAD_H / 104; +export const HEAD_W = 50.2 * HEAD_SCALE; +/** The drawn line terminates at the notch mouth (refX 27.2) — it never + * reaches the narrow tip, where it would show through (owner). The tip + * overhangs the line's end by this much, so edges shorten by it to land + * the tip exactly on the target node's border. */ +const HEAD_TIP_OVERHANG = (50.2 - 27.2) * HEAD_SCALE; +/** The head floats this far off the target face — the tip kisses nothing + * (owner, round 12). ~half a head length: clearly docked-off, still + * visually attached. Scaled with the head (2026-09-26) so "half a head" + * stays true at the thinner lines. */ +const DOCK_GAP = 4 * (STROKE_W / 1.5); +/** The shaft stub — the straight run before the head (owner, round 12): + * control points from Q on sit exactly on the approach line, so the + * basis spline renders that stretch perfectly straight and the head + * lands on a straight shaft; the corner where the route squares up onto + * the line is rounded by the curve. ~1.5 head lengths of shaft. */ +const STRAIGHT_RUN = 12; +/** The tilt limit at the termination point, measured off the entry + * face's perpendicular: past ±40° one of the head's barbs crosses the + * tip's level and the silhouette breaks (owner measured it in + * Photoshop, round 14). The final run swings to the cone edge instead. */ +const ENTRY_ANGLE_LIMIT = (40 * Math.PI) / 180; +const edgeLine = line<{ x: number; y: number }>() + .x((p) => p.x) + .y((p) => p.y) + .curve(curveBasis); + +/** The entry face's outward unit normal — whichever face of the target + * box dagre's border point sits on. Pure. */ +function faceNormal( + border: { x: number; y: number }, + box: { x: number; y: number; w: number; h: number }, +): { x: number; y: number } { + const d = { top: border.y - box.y, bottom: box.y + box.h - border.y, left: border.x - box.x, right: box.x + box.w - border.x }; + const face = (Object.keys(d) as Array).reduce((a, b) => (d[a] <= d[b] ? a : b)); + switch (face) { + case "top": + return { x: 0, y: -1 }; + case "bottom": + return { x: 0, y: 1 }; + case "left": + return { x: -1, y: 0 }; + default: + return { x: 1, y: 0 }; + } +} + +/** The edge path — mermaid's own line drawing: dagre's border-intersected + * waypoints through d3's curveBasis (mermaid's default flowchart curve — + * the same recipe dagre-d3's renderer uses). The head docks off the + * target: its TIP floats DOCK_GAP past the border along the FACE NORMAL + * (constant gap at any tilt), its mouth sits at the path's end on a + * straight run (the shaft stub), and — when the target box is given — + * the entry direction is clamped to ±ENTRY_ANGLE_LIMIT of the face's + * perpendicular (owner, round 14): a steeper natural approach swings to + * the 40° cone edge instead of breaking the head's silhouette. Without + * a target box the unclamped geometry applies. Straight collinear + * routes render identically. Pure, exported for tests. */ +export function edgePathD( + points: Array<{ x: number; y: number }>, + target?: { x: number; y: number; w: number; h: number }, +): string { + const pts = points.map((p) => ({ ...p })); + if (pts.length >= 2) { + const last = pts[pts.length - 1]!; + const prev = pts[pts.length - 2]!; + const dx = last.x - prev.x; + const dy = last.y - prev.y; + const len = Math.hypot(dx, dy) || 1; + let ux = dx / len; + let uy = dy / len; + // The tip: DOCK_GAP outside the face along its normal (or along the + // approach when no box is known). + let tipx: number; + let tipy: number; + if (target) { + const n = faceNormal(last, target); + tipx = last.x + n.x * DOCK_GAP; + tipy = last.y + n.y * DOCK_GAP; + // Clamp the approach to the ±LIMIT cone around the normal: if + // the outgoing direction -u tilts past ENTRY_ANGLE_LIMIT, swing + // it to the cone edge (same rotation side as the route). + const v = { x: -ux, y: -uy }; + const vn = v.x * n.x + v.y * n.y; + if (vn < Math.cos(ENTRY_ANGLE_LIMIT)) { + const t = { x: v.x - vn * n.x, y: v.y - vn * n.y }; + const tl = Math.hypot(t.x, t.y); + const that = tl > 0 ? { x: t.x / tl, y: t.y / tl } : { x: -n.y, y: n.x }; + const c = Math.cos(ENTRY_ANGLE_LIMIT); + const s = Math.sin(ENTRY_ANGLE_LIMIT); + v.x = c * n.x + s * that.x; + v.y = c * n.y + s * that.y; + ux = -v.x; + uy = -v.y; + } + } else { + tipx = last.x - ux * DOCK_GAP; + tipy = last.y - uy * DOCK_GAP; + } + // The mouth: overhang back from the tip along the (clamped) approach. + const M = { x: tipx - ux * HEAD_TIP_OVERHANG, y: tipy - uy * HEAD_TIP_OVERHANG }; + // From Q the control points lie on the approach line — the basis + // spline renders Q→M perfectly straight (a B-spline span with + // collinear control points IS the line), and curveBasis's internal + // endpoint repetition makes the end tangent exactly the approach + // direction. NOTE: do NOT repeat M manually — a duplicated final + // control point renders a zero-length last segment, and + // orient="auto" on a zero-length segment falls back to 0° (every + // head pointing right — the round-12 regression, fixed round 13). + const Q = { x: M.x - ux * STRAIGHT_RUN, y: M.y - uy * STRAIGHT_RUN }; + pts.splice(pts.length - 1, 1, Q, M); + } + return edgeLine(pts) ?? ""; +} diff --git a/tests/plan-window.test.tsx b/tests/plan-window.test.tsx index 66d9b98550..6ff00b0e99 100644 --- a/tests/plan-window.test.tsx +++ b/tests/plan-window.test.tsx @@ -2,7 +2,8 @@ import { renderToStaticMarkup } from "react-dom/server"; import { describe, it } from "node:test"; import assert from "node:assert/strict"; import { PlanMarginalia, planExists } from "../components/plan-window.tsx"; -import { blockLayout, edgePathD, type LayoutNode, type PopupMessage } from "../components/plan-block.tsx"; +import type { PopupMessage } from "../components/plan-block.tsx"; +import { blockLayout, edgePathD, type LayoutNode } from "../components/plan-layout.ts"; import type { PlanTree } from "../src/core/contracts.ts"; // The plan marginalia: the bare diagram in the dock band's right flank — diff --git a/tests/render-plan-block.test.tsx b/tests/render-plan-block.test.tsx index 271a4f0419..20779bbb83 100644 --- a/tests/render-plan-block.test.tsx +++ b/tests/render-plan-block.test.tsx @@ -4,9 +4,8 @@ import { InteractionLayersProvider } from "../components/interaction-layers.tsx" const renderToStaticMarkup = (node: ReactNode) => renderMarkup({node}); import { describe, it } from "node:test"; import assert from "node:assert/strict"; +import { PlanBlock, PlanPopup, type PopupMessage } from "../components/plan-block.tsx"; import { - PlanBlock, - PlanPopup, blockLayout, topoFor, edgePathD, @@ -16,8 +15,7 @@ import { NODE_W_MIN, nodeWidth, estimateLineWidth, - type PopupMessage, -} from "../components/plan-block.tsx"; +} from "../components/plan-layout.ts"; import type { PlanBlockData, PlanTree } from "../src/core/contracts.ts"; // Plan blocks: the pure layered layout, the frozen-snapshot rendering From 120c964f08c0d2cb09837c273bc0010f6a95e1de Mon Sep 17 00:00:00 2001 From: smitmachhi Date: Thu, 12 Nov 2026 11:14:15 -0500 Subject: [PATCH 10/88] fix(plan): size plan boxes from labels laid out in the real font Plan boxes got their width from one per-letter chart fitted to Source Sans 3, and lines broke after 28 letters, while the labels drew in whatever reading font Appearance picked. JetBrains Mono labels came out 40-55% wider than the chart said: 13 of 14 boxes in the test session spilled past their borders, and side-by-side labels ran into each other. Chinese and Japanese titles spilled with the default font too. blockLayout() now takes the measurer as its third argument. The measurer answers line breaks, line widths and font size, and usePlanLayout() asks the browser for all three, inside the diagram's own svg: - Line breaks: one hidden HTML block, capped at 12.75 em, where the browser breaks each title by its own Unicode rules. Words never split and never hyphenate; any word wider than the cap widens its box. Korean titles use word-break: keep-all, since Korean separates words with spaces. - Widths: one hidden SVG at the heaviest weight any label uses. Line height and vertical centering come from the measured font size. The server and the first client render still lay out with the old chart, now only as stand-in measurer that wraps at spaces, so server HTML and hydration match. One ResizeObserver on fixed sample text re-measures when the label font changes size: web font loads, font picks in Settings, size changes. The popup now computes its layout once and shares it with the diagram. --- components/plan-block.tsx | 259 ++++++++++++++++++++++++++----- components/plan-layout.ts | 214 +++++++++++++------------ components/plan-window.tsx | 3 + tests/plan-window.test.tsx | 8 +- tests/render-plan-block.test.tsx | 181 ++++++++++++++++----- 5 files changed, 480 insertions(+), 185 deletions(-) diff --git a/components/plan-block.tsx b/components/plan-block.tsx index b1d07f0957..0b0176a7e0 100644 --- a/components/plan-block.tsx +++ b/components/plan-block.tsx @@ -1,20 +1,21 @@ "use client"; -import { useEffect, useId, useMemo, useRef, useState } from "react"; +import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type RefObject } from "react"; +import { flushSync } from "react-dom"; import { MaximizeIcon, MinusIcon, PlusIcon, XIcon } from "lucide-react"; import { cn } from "@/lib/utils"; import { fitGraphView, fitZoomFor, zoomedGraphView, type Viewport } from "@/components/pan-zoom"; import { blockLayout, + chartMeasure, edgePathD, - wrapTitle, HEAD_H, HEAD_W, - LINE_H, - NODE_H, NODE_W_MIN, STROKE_W, + type LabelMeasure, type LayoutNode, + type PlanLayout, } from "@/components/plan-layout"; import type { PlanBlockData, PlanNodeStatus, PlanTree } from "@/src/core"; import { derivedNodeStatus, derivePlanStatuses } from "@/src/core"; @@ -28,8 +29,8 @@ import { InteractionLayerOwner, useInteractionLayer } from "./interaction-layers * * - kind "full": the whole DAG, BORDERLESS — no wrapping chrome, the SVG * scales to the full column width (viewBox = layout extent + GRAPH_PAD, - * so strokes/glow never clip), natural height, capped at the chat prose - * font size (TEXT_CAP_SCALE — fills the column, never oversizes text). + * so strokes/glow never clip), natural height, capped by TEXT_CAP_SCALE + * (fills the column, never oversizes text). * - Clicking opens the full plan in a session-scoped focus overlay * (absolute inside the session area, below the drag bar — chrome-melt * wave, 2026-09-19; was a fixed inset-0 full-screen popup) — @@ -39,14 +40,164 @@ import { InteractionLayerOwner, useInteractionLayer } from "./interaction-layers * the popup is the live view (user decision, 2026-09). * * Hand-built SVG everywhere (user decision): placement runs on dagre - * (mermaid's engine — deterministic, synchronous, DOM-free, so SSR and - * render tests stay exact) in components/plan-layout.ts; the skin is ours — no coupling to the graph - * stream's internals. Pan/zoom in the popup - * is harvested from the retired tree panel's graph (fit-floor semantics: - * fully zoomed out IS the fit; panning locks at the floor). + * (mermaid's engine) in components/plan-layout.ts; the skin is ours — no + * coupling to the graph stream's internals. Box sizes come from the real + * label text measured in the real font (usePlanLayout below, #671). Pan/zoom + * in the popup is harvested from the retired tree panel's graph (fit-floor + * semantics: fully zoomed out IS the fit; panning locks at the floor). */ +// ─── Measuring the labels (#671) ────────────────────────────────────────────── +/** The label type every plan view draws its titles in. Width-relevant + * classes only (size + weight) — the probe measures with exactly these. + * font-medium is the HEAVIEST weight any status draws (the current node, + * TEXT.current below), so every box fits its text at any status and the + * layout never shifts when the current step moves (owner, #671 design). */ +const LABEL_TYPE = "text-xs"; +const PROBE_TYPE = `${LABEL_TYPE} font-medium`; +/** The sentinel's fixed sample: Latin, digits and CJK, so a font change or + * a font finishing its load changes its size whatever script the plan + * uses. */ +const SENTINEL_TEXT = "Hamburgefonstiv 0123 漢字"; + +/** The hidden probe a diagram carries (rendered by PlanDiagram, inside its + * own so it inherits exactly the cascade the real labels do — + * subtrees may redefine --font-prose, e.g. chain-table.tsx): + * - sentinel: fixed text the ResizeObserver watches; + * - measurer: SVG whose width answers `width(line)`; + * - breaker: HTML block where the browser's own line breaker lays out each + * title, answering `lines(title)`. */ +export interface PlanProbe { + sentinel: RefObject; + measurer: RefObject; + breaker: RefObject; +} + +const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" }); +const HANGUL = /\p{Script=Hangul}/u; + +/** The lines the browser itself broke `title` into, read back from where + * each grapheme landed: a grapheme on a new row starts a new line. The + * breaker never splits words or hyphenates (CSS on the element), so this + * is the browser's word-level line breaking, every script's rules + * included. */ +function browserLines(box: HTMLDivElement, title: string, maxWidth: number): string[] { + box.style.maxWidth = `${maxWidth}px`; + // Korean separates words with spaces, but browsers break Hangul between + // any two syllables by default; keep-all keeps its words whole. Chinese + // and Japanese have no spaces and break between characters by their own + // rules, so they keep the default. + box.style.wordBreak = HANGUL.test(title) ? "keep-all" : "normal"; + box.textContent = title; + const text = box.firstChild; + if (!text) return [""]; + const range = document.createRange(); + const lines: string[] = []; + let line = ""; + let top: number | null = null; + for (const { segment, index } of graphemes.segment(title)) { + range.setStart(text, index); + range.setEnd(text, index + segment.length); + const rect = [...range.getClientRects()].find((r) => r.width > 0); + if (rect && top !== null && Math.abs(rect.top - top) > rect.height / 2) { + lines.push(line.trim()); + line = ""; + } + if (rect) top = rect.top; + line += segment; + } + lines.push(line.trim()); + const kept = lines.filter((l) => l !== ""); + return kept.length > 0 ? kept : [""]; +} + +/** The real-font measure: the breaker answers line breaks, the SVG + * measurer answers widths (PROBE_TYPE on both). Answers are cached per + * measure — a new measure is made whenever the font may have changed. */ +function probeMeasure(el: SVGTextElement, box: HTMLDivElement): LabelMeasure { + const widths = new Map(); + const breaks = new Map(); + return { + fontSize: parseFloat(getComputedStyle(el).fontSize), + width(text) { + let w = widths.get(text); + if (w === undefined) { + el.textContent = text; + w = el.getComputedTextLength(); + widths.set(text, w); + } + return w; + }, + lines(title, maxWidth) { + const key = `${maxWidth}\n${title}`; + let lines = breaks.get(key); + if (lines === undefined) { + lines = browserLines(box, title, maxWidth); + breaks.set(key, lines); + } + return lines; + }, + }; +} + +/** Stable empties for "no plan yet" (the layout keys on identity). */ +const NO_NODES: readonly LayoutNode[] = []; +const NO_EDGES: ReadonlyArray<{ from: string; to: string }> = []; + +/** + * One plan's layout, measured in the real font (null plan = empty layout). + * Pass the result to the PlanDiagram that draws this plan. + * + * - Server render and the first client render lay out with `chartMeasure` + * (the Source Sans estimate), so the server HTML and hydration agree. + * - Right after mount (layout effect, before paint) the real labels are + * measured and the layout is replaced. + * - A ResizeObserver on the sentinel re-measures whenever the label font + * actually changes size on screen: a web font finishing its load, a + * reading font picked in Settings (applied by the Appearance provider's + * own layout effect, which runs AFTER ours — so we watch the result, not + * the cause), an installed font that never fires a load event. The + * sentinel is never rewritten, so measuring can't retrigger it. + * + * Does NOT measure while the diagram has no layout box (an ancestor with + * display:none reads 0 widths); the chart layout stays until it shows. + */ +export function usePlanLayout(plan: { nodes: readonly LayoutNode[]; edges: ReadonlyArray<{ from: string; to: string }> } | null) { + const nodes = plan?.nodes ?? NO_NODES; + const edges = plan?.edges ?? NO_EDGES; + const sentinel = useRef(null); + const measurer = useRef(null); + const breaker = useRef(null); + const chart = useMemo(() => blockLayout(nodes, edges, chartMeasure), [nodes, edges]); + const [measured, setMeasured] = useState<{ nodes: typeof nodes; edges: typeof edges; layout: PlanLayout } | null>(null); + useLayoutEffect(() => { + const watch = sentinel.current; + const el = measurer.current; + const box = breaker.current; + if (!watch || !el || !box || typeof el.getComputedTextLength !== "function") return; + const measure = () => { + if (watch.getComputedTextLength() === 0) return; // not rendered yet + setMeasured({ nodes, edges, layout: blockLayout(nodes, edges, probeMeasure(el, box)) }); + }; + measure(); + if (typeof ResizeObserver === "undefined") return; + let seen = watch.getComputedTextLength(); + const observer = new ResizeObserver(() => { + const now = watch.getComputedTextLength(); + if (now === seen) return; + seen = now; + // Commit before the browser paints, so the new font never shows + // in the old boxes for a frame. + flushSync(measure); + }); + observer.observe(watch); + return () => observer.disconnect(); + }, [nodes, edges]); + const layout = measured && measured.nodes === nodes && measured.edges === edges ? measured.layout : chart; + const probe: PlanProbe = { sentinel, measurer, breaker }; + return { layout, probe }; +} /** SVG-unit padding around the layout extent: strokes are centered on the * geometry (half bleeds outside the extent) and the glow halo reaches −4 — @@ -60,10 +211,11 @@ export const GRAPH_PAD = 8; export const GLOW_MARGIN = 8; export const GLOW_BLUR = 5; export const GLOW_REACH = GLOW_MARGIN + 3 * GLOW_BLUR; -/** Node titles render at text-xs (12.5px) in svg units. The in-chat block - * scales up to fill the column but NEVER past the chat prose size - * (--lh-prose-size, 16px — the ladder's reading rung) — the width cap - * that makes that hold. */ +/** The in-chat block's zoom ceiling: it scales up to fill the column but + * never past extent × this. Node titles render at text-xs, which is 11px + * in svg units (--text-xs) — so the cap lands titles at ≈14px on screen. + * (The 12.5 here dates from when text-xs was 12.5px; it was meant to stop + * at the 16px chat prose size.) */ export const TEXT_CAP_SCALE = 16 / 12.5; // ─── The owner's arrowhead (plan-graph round 5) ────────────────────────────── @@ -74,7 +226,6 @@ export const TEXT_CAP_SCALE = 16 / 12.5; * is ≈10, per the owner's spec. Solid strong-ink fill, no padding. */ export const ARROW_HEAD = "M48,55.2C49.4,54.6 50.2,53.4 50.2,52C50.2,50.6 49.4,49.4 48,48.8C38.2,45.6 29.2,38.8 21,28.4C15.2,21.4 11.4,13.2 9.6,3.8C9,1.2 7.4,0 4.8,0C1.6,0 0,1.6 0,5L0.2,5.6C3.6,23 12.6,36.8 27.2,47.2L27.2,56.8C12.6,67.2 3.6,81 0.2,98.4L0,99C0,102.4 1.6,104 4.8,104C7.4,104 9,102.8 9.6,100.2C11.4,90.8 15.2,82.6 21,75.6C29.2,65.2 38.2,58.4 48,55.2Z"; - // ─── Status styling (the retired panel's color language, unchanged) ────────── // The simple look (owner, plan-graph round 4): rectangular boxes, @@ -92,25 +243,30 @@ const BOX: Record = { // The grayed-out not-yet-visited look stays as-is (owner). upcoming: "fill-card stroke-border", }; +// Every label's size + weight must stay within PROBE_TYPE (the probe +// measures the heaviest of them), or boxes stop fitting their text. const TEXT: Record = { - visited: "fill-line-strong text-xs", - current: "fill-line-strong text-xs font-medium", - upcoming: "fill-muted-foreground/80 text-xs", + visited: `fill-line-strong ${LABEL_TYPE}`, + current: `fill-line-strong ${LABEL_TYPE} font-medium`, + upcoming: `fill-muted-foreground/80 ${LABEL_TYPE}`, }; // The in-chat block speaks the dock language now (owner, plan-hug // round 2026-10-07): boxes in the lighter background variant like // the composer/dock shells — but the outlines STAY the strong line ink, // white in dark (owner follow-up: the gray fill is good, white box edges). const MONO_BOX = "fill-card stroke-line-strong"; -const MONO_TEXT = "fill-foreground text-xs"; - -/** The diagram itself: positioned nodes + bezier edges. Pure-ish render — - * every input is data, so SSR render tests pin the whole thing. The root - * sets font-family var(--font-prose): node titles render in the READING - * font, not the mono UI font (owner, 2026-09-26) — and the runtime var - * rides the Appearance reading-font override (the utility can't: @theme - * inline bakes literals — the --font-title trap). */ +const MONO_TEXT = `fill-foreground ${LABEL_TYPE}`; + +/** The diagram itself: positioned nodes + bezier edges, drawn from the + * layout usePlanLayout hands it (`plan`) — every input is data, so SSR + * render tests pin the whole thing. The root sets font-family + * var(--font-prose): node titles render in the READING font, not the mono + * UI font (owner, 2026-09-26) — and the runtime var rides the Appearance + * reading-font override (the utility can't: @theme inline bakes literals — + * the --font-title trap). It also carries the plan's hidden probe, so the + * probe measures under this exact cascade. */ export function PlanDiagram({ + plan, nodes, edges, statusOf, @@ -123,6 +279,8 @@ export function PlanDiagram({ monochrome, fill, }: { + /** usePlanLayout's result for these same nodes + edges. */ + plan: { layout: PlanLayout; probe: PlanProbe }; nodes: readonly LayoutNode[]; edges: ReadonlyArray<{ from: string; to: string }>; statusOf: (id: string) => PlanNodeStatus; @@ -149,7 +307,7 @@ export function PlanDiagram({ * flank's width and the band's height rather than run width-first. */ fill?: boolean; }) { - const layout = useMemo(() => blockLayout(nodes, edges), [nodes, edges]); + const { layout, probe } = plan; // Pad only the full-extent render — the plan window's override viewBox is // a deliberate viewport crop, and the popup keeps its own fit margins. const pad = viewBoxOverride ? 0 : (padUnits ?? 0); @@ -227,7 +385,7 @@ export function PlanDiagram({ const ty = layout.y.get(e.to); const target = tx !== undefined && ty !== undefined - ? { x: tx, y: ty, w: layout.nodeW.get(e.to) ?? NODE_W_MIN, h: layout.nodeH.get(e.to) ?? NODE_H } + ? { x: tx, y: ty, w: layout.nodeW.get(e.to) ?? NODE_W_MIN, h: layout.nodeH.get(e.to) ?? 0 } : undefined; // An arrow is white only when BOTH its ends are white (owner, // 2026-09-26): origin AND terminal covered — a gray box's outgoing @@ -250,12 +408,14 @@ export function PlanDiagram({ {nodes.map((n) => { const status = statusOf(n.id); const glow = n.id === glowId && !monochrome; - const lines = wrapTitle(n.title); - // The box hugs its wrapped content; text centers in it — - // horizontally too now (text-first sizing round, 2026-10-07). - const h = layout.nodeH.get(n.id) ?? NODE_H; + const lines = layout.lines.get(n.id) ?? [n.title]; + // The box hugs its measured, wrapped lines; text centers in it + // both ways — each line's middle sits on its own row's middle + // (dominant-baseline central), so no font-specific baseline + // offset is needed. + const h = layout.nodeH.get(n.id) ?? 0; const w = layout.nodeW.get(n.id) ?? NODE_W_MIN; - const y0 = (h - lines.length * LINE_H) / 2 + 10; + const y0 = (h - lines.length * layout.lineH) / 2 + layout.lineH / 2; return ( {line} @@ -299,6 +460,22 @@ export function PlanDiagram({ ); })} + {/* The probe (usePlanLayout): a fixed-text sentinel the resize + observer watches, the measurer whose text gets swapped per + line, and the HTML breaker where the browser breaks each + title into lines (words never split: no overflow-wrap, no + hyphens). Hidden, but laid out under this svg's own cascade. */} +