Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Add prompt text field with reference smart chips

Bitti4d2e59f10939
diff --git a/src/components/ImageProject.integration.test.tsx b/src/components/ImageProject.integration.test.tsx
index 224c853..a064e9e 100644
--- a/src/components/ImageProject.integration.test.tsx
+++ b/src/components/ImageProject.integration.test.tsx
@@ -16,6 +16,8 @@ import fixture from "../../fixtures/project-v1-image.json";
import { invoke } from "@tauri-apps/api/core";
import * as persistence from "../lib/persistence";
+/* The prompt is a contenteditable: typing is its text and an input event. */
+const typePrompt = (field: HTMLElement, text: string) => { field.textContent = text; fireEvent.input(field); };
vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn(async () => () => undefined) }));
afterEach(() => { cleanup(); localStorage.clear(); vi.restoreAllMocks(); });
@@ -182,7 +184,7 @@ it("opens the three-tab image workspace and saves hierarchy/inspector edits thro
fireEvent.contextMenu(screen.getByRole("button", { name: "Image" }));
fireEvent.click(screen.getByRole("menuitem", { name: "New Text" }));
fireEvent.change(screen.getByLabelText("Text to render"), { target: { value: "Hello world" } });
- fireEvent.change(screen.getByLabelText("Description"), { target: { value: "Large blue letters" } });
+ typePrompt(screen.getByLabelText("Description"), "Large blue letters");
fireEvent.click(screen.getByRole("button", { name: "Save" }));
await waitFor(() => expect(save).toHaveBeenCalled());
expect(save.mock.calls[0]).toBeDefined();
diff --git a/src/components/workspace/ImageEditor.test.tsx b/src/components/workspace/ImageEditor.test.tsx
index 662c13e..dfa68c0 100644
--- a/src/components/workspace/ImageEditor.test.tsx
+++ b/src/components/workspace/ImageEditor.test.tsx
@@ -15,6 +15,9 @@ import * as persistence from "../../lib/persistence";
import fixture from "../../../fixtures/project-v1-image.json";
import snapshotFixture from "../../../fixtures/image-generation-snapshot.json";
+/* The prompt is a contenteditable: typing is its text and an input event. */
+const typePrompt = (field: HTMLElement, text: string) => { field.textContent = text; fireEvent.input(field); };
+const promptValue = (field: HTMLElement) => field.textContent;
vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
afterEach(() => { cleanup(); localStorage.clear(); vi.restoreAllMocks(); });
function setup(initial = parseProjectConfig(fixture)) {
@@ -50,7 +53,7 @@ it("adds image files in edit mode and saves whole-image and drawn edits with sep
addFile();
await waitFor(() => expect(current().imageScene?.sourceImage).toEqual(source));
expect(screen.queryByRole("combobox", { name: "Type" })).not.toBeInTheDocument();
- fireEvent.change(screen.getByLabelText("Edit prompt"), { target: { value: "Make the lighting warmer" } });
+ typePrompt(screen.getByLabelText("Edit prompt"), "Make the lighting warmer");
fireEvent.click(screen.getByRole("checkbox", { name: "Mood" }));
expect(compileImageEdits(current()).edits[0]).toMatchObject({ x: 0, y: 0, width: 1000, height: 800 });
const canvas = screen.getByLabelText("Image placement canvas");
@@ -68,7 +71,7 @@ it("adds image files in edit mode and saves whole-image and drawn edits with sep
pointer("pointerDown", 100, 80); pointer("pointerMove", 400, 320); pointer("pointerUp", 400, 320);
expect(current().imageScene!.nodes[1]).toMatchObject({ name: "Edit", box: { x: 100, y: 100, width: 300, height: 300 }, referenceIds: [] });
expect(screen.getByRole("checkbox", { name: "Mood" })).not.toBeChecked();
- fireEvent.change(screen.getByLabelText("Edit prompt"), { target: { value: "Add a red balloon" } });
+ typePrompt(screen.getByLabelText("Edit prompt"), "Add a red balloon");
fireEvent.click(screen.getByRole("checkbox", { name: "Balloon" }));
const edits = compileImageEdits(current()).edits;
expect(edits.map((edit) => edit.references.map((reference) => reference.id))).toEqual([["Mood"], ["Balloon"]]);
@@ -78,9 +81,9 @@ it("adds image files in edit mode and saves whole-image and drawn edits with sep
fireEvent.contextMenu(screen.getByLabelText("Generated images"));
fireEvent.click(screen.getByRole("menuitem", { name: "New empty image" }));
fireEvent.click(screen.getByRole("button", { name: "View Editing Imported" }));
- expect(screen.getByLabelText("Edit prompt")).toHaveValue("Make the lighting warmer");
+ expect(promptValue(screen.getByLabelText("Edit prompt"))).toBe("Make the lighting warmer");
fireEvent.click(screen.getByRole("button", { name: "Edit" }));
- expect(screen.getByLabelText("Edit prompt")).toHaveValue("Add a red balloon");
+ expect(promptValue(screen.getByLabelText("Edit prompt"))).toBe("Add a red balloon");
expect(screen.getByRole("checkbox", { name: "Balloon" })).toBeChecked();
const beforeFailure = current();
vi.mocked(invoke).mockRejectedValueOnce(new Error("Image file is unreadable"));
@@ -99,14 +102,14 @@ it("starts an image root from the thumbnail Edit menu with edit tools and no typ
expect(current().imageScene!.nodes).toHaveLength(1);
expect(screen.queryByLabelText("Prompt (high-level description)")).not.toBeInTheDocument();
expect(screen.queryByRole("combobox", { name: "Type" })).not.toBeInTheDocument();
- expect(screen.getByLabelText("Edit prompt")).toHaveValue("");
+ expect(promptValue(screen.getByLabelText("Edit prompt"))).toBe("");
expect(within(screen.getByRole("radiogroup", { name: "Canvas tool" })).getAllByRole("radio").map((tool) => tool.getAttribute("aria-label"))).toEqual(["Select", "Draw edit"]);
const draft = screen.getByRole("button", { name: "View Editing Saved" });
expect(draft).toHaveAttribute("aria-pressed", "true");
fireEvent.contextMenu(screen.getByRole("button", { name: "Image" }));
expect(screen.getAllByRole("menuitem").filter((item) => item.textContent?.startsWith("New ")).map((item) => item.textContent)).toEqual(["New Edit"]);
fireEvent.click(screen.getByRole("menuitem", { name: "New Edit" }));
- fireEvent.change(screen.getByLabelText("Edit prompt"), { target: { value: "A red balloon" } });
+ typePrompt(screen.getByLabelText("Edit prompt"), "A red balloon");
fireEvent.click(screen.getByRole("button", { name: "View Saved" }));
expect(draft).toHaveAttribute("aria-pressed", "false");
fireEvent.click(draft);
@@ -130,9 +133,9 @@ it("restores the hierarchy, prompts, settings and generator when selecting a sav
initial.assets = [original, saved].map((snapshot, index) => ({ id: `result-${index}`, name: `Result ${index}`, kind: "image", relativePath: `media/generated/result-${index}.jpg`, mimeType: "image/jpeg", createdAt: initial.createdAt, imageGeneration: snapshot }));
initial.imageScene!.outputAssetId = "result-0";
const current = setup(initial);
- fireEvent.change(screen.getByLabelText("Prompt (high-level description)"), { target: { value: "Unsaved edit" } });
+ typePrompt(screen.getByLabelText("Prompt (high-level description)"), "Unsaved edit");
fireEvent.click(screen.getByRole("button", { name: "View Result 1" }));
- expect(screen.getByLabelText("Prompt (high-level description)")).toHaveValue(saved.scene.nodes[0].description);
+ expect(promptValue(screen.getByLabelText("Prompt (high-level description)"))).toBe(saved.scene.nodes[0].description);
expect(screen.getByLabelText("Steps")).toHaveValue(30);
expect(comboValue(screen.getByRole("combobox", { name: "Generator" }))).toBe(saved.generatorTemplateId);
expect(screen.getByRole("button", { name: "Lantern" })).toBeInTheDocument();
@@ -141,8 +144,8 @@ it("restores the hierarchy, prompts, settings and generator when selecting a sav
expect(current().settings).toMatchObject({ resolution: "1088p", aspectRatio: "4:5" });
// Viewing a result starts a fresh history: Ctrl+Z has nothing to undo.
undoImageEdit();
- expect(screen.getByLabelText("Prompt (high-level description)")).toHaveValue(saved.scene.nodes[0].description);
- fireEvent.change(screen.getByLabelText("Prompt (high-level description)"), { target: { value: "Another edit" } });
+ expect(promptValue(screen.getByLabelText("Prompt (high-level description)"))).toBe(saved.scene.nodes[0].description);
+ typePrompt(screen.getByLabelText("Prompt (high-level description)"), "Another edit");
fireEvent.click(screen.getByRole("button", { name: "View Result 0" }));
expect(current().imageScene).toEqual({ ...original.scene, outputAssetId: "result-0" });
expect(comboValue(screen.getByRole("combobox", { name: "Generator" }))).toBe(original.generatorTemplateId);
@@ -216,19 +219,19 @@ it("creates a blank draft from the image bar and preserves it while browsing", (
fireEvent.contextMenu(screen.getByRole("button", { name: "View Saved" }));
fireEvent.click(screen.getByRole("menuitem", { name: "New empty image" }));
expect(screen.queryByRole("combobox", { name: "Type" })).not.toBeInTheDocument();
- expect(screen.getByLabelText("Prompt (high-level description)")).toHaveValue("");
+ expect(promptValue(screen.getByLabelText("Prompt (high-level description)"))).toBe("");
expect(current().imageScene!.nodes).toHaveLength(1);
expect(screen.getByRole("button", { name: "View New image" })).toHaveAttribute("aria-pressed", "true");
- fireEvent.change(screen.getByLabelText("Prompt (high-level description)"), { target: { value: "A green forest" } });
+ typePrompt(screen.getByLabelText("Prompt (high-level description)"), "A green forest");
fireEvent.click(screen.getByRole("button", { name: "View Saved" }));
fireEvent.click(screen.getByRole("button", { name: "View New image" }));
- expect(screen.getByLabelText("Prompt (high-level description)")).toHaveValue("A green forest");
+ expect(promptValue(screen.getByLabelText("Prompt (high-level description)"))).toBe("A green forest");
expect(parseProjectConfig(JSON.parse(JSON.stringify(current()))).assets).toEqual(current().assets);
fireEvent.contextMenu(screen.getByLabelText("Generated images"));
expect(screen.queryByRole("menuitem", { name: "Remove" })).not.toBeInTheDocument();
fireEvent.click(screen.getByRole("menuitem", { name: "New empty image" }));
expect(current().assets).toHaveLength(3);
- expect(screen.getByLabelText("Prompt (high-level description)")).toHaveValue("");
+ expect(promptValue(screen.getByLabelText("Prompt (high-level description)"))).toBe("");
});
it("creates an image from the empty bar's keyboard context menu", () => {
diff --git a/src/components/workspace/ImageEditor.tsx b/src/components/workspace/ImageEditor.tsx
index 6e130ea..26e02c8 100644
--- a/src/components/workspace/ImageEditor.tsx
+++ b/src/components/workspace/ImageEditor.tsx
@@ -5,6 +5,7 @@ import { addImageNode, createImageEditScene, createImageScene, duplicateImageNod
import { compileImageEdits, editGeneratedImage, imageEditDebugPrompt } from "../../lib/imageEditing";
import { outputDimensions } from "../../lib/export";
import { compileImagePrompt } from "../../lib/imagePrompt";
+import { promptReferenceNames } from "../../lib/promptReferences";
import { createEmptyImage, restoreGeneratedImage, saveImageDraft } from "../../lib/imageHistory";
import { isTauri } from "../../lib/persistence";
import { IMAGE_RESOLUTIONS, type ProjectConfig } from "../../lib/project";
@@ -12,6 +13,7 @@ import { defaultGeneratorTemplate, loadDebugOptionsEnabled, loadGeneratorTemplat
import { isWorkActive, type WorkItem } from "../../lib/workQueue";
import type { ConfigUpdate } from "./TimelineView";
import { ReferenceImage } from "./ReferenceImage";
+import { PromptTextField } from "./PromptTextField";
import { ImageBar } from "./ImageBar";
import { DebugPromptDialog } from "./DebugPromptDialog";
import { TagEditor } from "./TagEditor";
@@ -432,6 +434,22 @@ export function ImageEditor({ config, folderPath, onChange: changeConfig, onGene
</div>;
};
const rootField = (field: string) => `${editorId}-${field}`;
+ const promptLabel = imageRoot ? "Edit prompt" : selected.kind === "root" ? "Prompt (high-level description)" : "Description";
+ const promptReferences = config.references.filter((reference) => reference.kind === "image" || reference.kind === "text")
+ .map((reference) => ({ id: reference.id, name: reference.name, detail: reference.kind === "image" ? "Image" : "Text", icon: reference.kind === "image" ? <Image16 /> : <Text16 /> }));
+ /* A reference newly cited in a prompt is one the generation has to be
+ given, so citing it links it to the edit (or, composing, to the image). */
+ const changePrompt = (description: string) => {
+ const before = promptReferenceNames(selected.description);
+ const cited = promptReferenceNames(description).filter((name) => !before.includes(name))
+ .flatMap((name) => promptReferences.filter((reference) => reference.name === name).map((reference) => reference.id));
+ const nodes = scene.nodes.map((node) => node.id === selected.id ? { ...node, description } : node);
+ if (imageRoot) {
+ const referenceIds = selected.referenceIds ?? scene.referenceIds;
+ const linked = [...referenceIds, ...cited.filter((id) => !referenceIds.includes(id))];
+ commit({ ...scene, nodes: nodes.map((node) => node.id === selected.id && linked.length !== referenceIds.length ? { ...node, referenceIds: linked } : node) });
+ } else commit({ ...scene, nodes, referenceIds: selected.kind === "root" ? [...scene.referenceIds, ...cited.filter((id) => !scene.referenceIds.includes(id))] : scene.referenceIds });
+ };
return <div ref={editorRoot} className="image-editor" style={{ ...treePane.style, ...inspectorPane.style }}>
<aside ref={hierarchy} className="image-tree" aria-label="Image hierarchy" onContextMenu={(event) => { if ((event.target as HTMLElement).closest("input, textarea, [contenteditable=true]")) return; event.preventDefault(); setSelection(root.id); setContextMenu({ x: event.clientX, y: event.clientY }); }} onKeyDown={treeKeys}>
{/* Undo and Redo live in the title bar; Ctrl+Z / Ctrl+Y still step the image edits here. */}
@@ -575,7 +593,7 @@ export function ImageEditor({ config, folderPath, onChange: changeConfig, onGene
{scene.sourceImage && <p className="image-inspector__caption">{scene.sourceImage.name} · {scene.sourceImage.width} × {scene.sourceImage.height}</p>}
<p className="image-inspector__caption">Applies to the whole image before the individual edits.</p>
</>}
- <label className="image-inspector__area">{imageRoot ? "Edit prompt" : selected.kind === "root" ? "Prompt (high-level description)" : "Description"}<textarea className="text-field" rows={4} value={selected.description} onChange={(event) => patchNode({ description: event.target.value })} /></label>
+ <div className="image-inspector__area"><span id={rootField("prompt-label")}>{promptLabel}</span><PromptTextField key={selected.id} aria-labelledby={rootField("prompt-label")} value={selected.description} references={promptReferences} onChange={changePrompt} /></div>
{imageRoot && <PropSection title="References" persistKey="image.edit.references">
{config.references.filter((reference) => reference.kind === "image" || reference.kind === "text").map((reference) => {
const referenceIds = selected.referenceIds ?? scene.referenceIds;
diff --git a/src/components/workspace/PromptTextField.test.tsx b/src/components/workspace/PromptTextField.test.tsx
new file mode 100644
index 0000000..2cb07cd
--- /dev/null
+++ b/src/components/workspace/PromptTextField.test.tsx
@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+import { useState } from "react";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { PromptTextField, type PromptReference } from "./PromptTextField";
+import { canCitePromptReference, promptReferenceNames, splitPromptText } from "../../lib/promptReferences";
+
+afterEach(cleanup);
+
+const references: PromptReference[] = [{ id: "hero", name: "Hero" }, { id: "castle", name: "Castle" }, { id: "odd", name: "Odd [v2]" }];
+
+function setup(initial: string, onInsertReference = vi.fn()) {
+ let latest = initial;
+ function Harness() {
+ const [value, setValue] = useState(initial);
+ latest = value;
+ return <PromptTextField aria-label="Prompt" value={value} onChange={setValue} references={references} onInsertReference={onInsertReference} />;
+ }
+ render(<Harness />);
+ return { value: () => latest, field: screen.getByRole("textbox", { name: "Prompt" }) };
+}
+
+const caretAt = (node: Node, offset: number) => {
+ const range = document.createRange();
+ range.setStart(node, offset);
+ range.collapse(true);
+ document.getSelection()!.removeAllRanges();
+ document.getSelection()!.addRange(range);
+ fireEvent(document, new Event("selectionchange"));
+};
+
+it("reads references out of the text as [Name]", () => {
+ expect(splitPromptText("A [Hero] at the [Castle].")).toEqual([
+ { kind: "text", value: "A " }, { kind: "reference", value: "Hero" }, { kind: "text", value: " at the " },
+ { kind: "reference", value: "Castle" }, { kind: "text", value: "." },
+ ]);
+ expect(splitPromptText("[] and [a\nb] stay text")).toEqual([{ kind: "text", value: "[] and [a\nb] stay text" }]);
+ expect(promptReferenceNames("[Hero] meets [Castle] and [Hero]")).toEqual(["Hero", "Castle"]);
+ expect(canCitePromptReference("Odd [v2]")).toBe(false);
+});
+
+it("shows references as chips, and ones no reference is named as missing", () => {
+ const { field } = setup("[Hero] walks to [Tower]");
+ const chips = field.querySelectorAll(".prompt-chip");
+ expect([...chips].map((chip) => chip.textContent)).toEqual(["Hero", "Tower"]);
+ expect(chips[1]).toHaveClass("prompt-chip--missing");
+ expect(chips[0]).toHaveAttribute("contenteditable", "false");
+ expect(field).toHaveTextContent("Hero walks to Tower");
+});
+
+it("inserts the chosen reference at the caret from the toolbar", () => {
+ const onInsert = vi.fn();
+ const { field, value } = setup("A knight rides", onInsert);
+ caretAt(field.firstChild!, 2);
+ fireEvent.click(screen.getByRole("button", { name: "Reference" }));
+ expect(screen.getByRole("dialog", { name: "Insert a reference" })).toBeInTheDocument();
+ expect(screen.getByRole("button", { name: "Odd [v2]" })).toBeDisabled();
+ fireEvent.click(screen.getByRole("button", { name: "Hero" }));
+ expect(value()).toBe("A [Hero]knight rides");
+ expect(onInsert).toHaveBeenCalledWith(references[0]);
+ expect(field.querySelector(".prompt-chip")).toHaveTextContent("Hero");
+ expect(screen.queryByRole("dialog")).toBeNull();
+});
+
+it("adds a reference at the end of a field that was never focused", () => {
+ const { value } = setup("Ride to ");
+ fireEvent.click(screen.getByRole("button", { name: "Reference" }));
+ fireEvent.click(screen.getByRole("button", { name: "Castle" }));
+ expect(value()).toBe("Ride to [Castle]");
+});
+
+it("opens the picker from a chip to change it or take it out", () => {
+ const { field, value } = setup("[Hero] at the [Hero] gate");
+ fireEvent.click(field.querySelectorAll(".prompt-chip")[1]);
+ expect(screen.getByRole("dialog", { name: "Change reference Hero" })).toHaveTextContent("Cites Hero");
+ expect(screen.getByRole("button", { name: "Hero" })).toHaveAttribute("aria-pressed", "true");
+ fireEvent.click(screen.getByRole("button", { name: "Castle" }));
+ expect(value()).toBe("[Hero] at the [Castle] gate");
+
+ fireEvent.click(field.querySelectorAll(".prompt-chip")[0]);
+ fireEvent.click(screen.getByRole("button", { name: "Remove from the prompt" }));
+ expect(value()).toBe(" at the [Castle] gate");
+ expect(field.querySelectorAll(".prompt-chip")).toHaveLength(1);
+});
+
+it("turns a [Name] typed by hand into a chip and keeps line breaks as text", () => {
+ const { field, value } = setup("");
+ field.textContent = "Meet [Hero]";
+ fireEvent.input(field);
+ expect(value()).toBe("Meet [Hero]");
+ expect(field.querySelector(".prompt-chip")).toHaveTextContent("Hero");
+
+ field.focus();
+ caretAt(field.firstChild!, 4);
+ fireEvent.keyDown(field, { key: "Enter" });
+ expect(value()).toBe("Meet\n [Hero]");
+});
+
+it("pastes only the characters", () => {
+ const { field, value } = setup("Hello");
+ caretAt(field.firstChild!, 5);
+ fireEvent.paste(field, { clipboardData: { getData: (type: string) => type === "text/plain" ? " <b>[Castle]</b>\r\nnext" : "" } });
+ expect(value()).toBe("Hello <b>[Castle]</b>\nnext");
+});
diff --git a/src/components/workspace/PromptTextField.tsx b/src/components/workspace/PromptTextField.tsx
new file mode 100644
index 0000000..3ea1969
--- /dev/null
+++ b/src/components/workspace/PromptTextField.tsx
@@ -0,0 +1,394 @@
+import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type KeyboardEvent as ReactKeyboardEvent, type ReactNode } from "react";
+import { canCitePromptReference, promptReferenceToken, splitPromptText } from "../../lib/promptReferences";
+import { Add14, Delete14 } from "../ui/icons";
+import { Flyout, TextField } from "../ui";
+import "../../styles/prompt-field.css";
+
+export interface PromptReference {
+ id: string;
+ name: string;
+ /** A glyph or thumbnail shown beside the name in the picker. */
+ icon?: ReactNode;
+ /** A second line in the picker, e.g. the kind of reference. */
+ detail?: string;
+}
+
+/* A multi-line prompt whose references are smart chips inside the text.
+
+ The value is plain text; a reference is written into it as `[Name]` (see
+ lib/promptReferences) and the field shows every such token as a chip. The
+ Reference button on the toolbar above opens a picker and drops the chosen
+ reference at the caret; clicking a chip opens the same picker to change it
+ to another reference or take it out.
+
+ The editable surface is a contenteditable the component writes itself,
+ not React children, so React never reconciles against what the browser
+ typed. It is rebuilt from the value only when the two disagree — a change
+ from outside, a chip picked, or `[Name]` typed out by hand — and the caret
+ is put back by its offset in the text. */
+
+const CHIP = "data-prompt-reference";
+const END = "data-prompt-end";
+/* A chip is not editable, and a caret cannot sit after one that ends the
+ field; a zero-width space after it gives the caret somewhere to go. It is
+ never part of the value. */
+const CARET_ROOM = "​";
+
+interface Picking {
+ anchor: HTMLElement;
+ start: number;
+ end: number;
+ /** The chip being changed; none when inserting. */
+ current: string | null;
+}
+
+export function PromptTextField({ value, onChange, references, onInsertReference, disabled = false, placeholder, rows = 4, id, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy }: {
+ value: string;
+ onChange: (value: string) => void;
+ references: readonly PromptReference[];
+ /** Called with the reference a chip was made from, inserted or changed to. */
+ onInsertReference?: (reference: PromptReference) => void;
+ disabled?: boolean;
+ placeholder?: string;
+ /** The field's minimum height, in lines. */
+ rows?: number;
+ id?: string;
+ className?: string;
+ "aria-label"?: string;
+ "aria-labelledby"?: string;
+}) {
+ const field = useRef<HTMLDivElement>(null);
+ const addButton = useRef<HTMLButtonElement>(null);
+ const selection = useRef<{ start: number; end: number } | null>(null);
+ const pendingCaret = useRef<number | null>(null);
+ const [picking, setPicking] = useState<Picking | null>(null);
+ const known = new Set(references.map((reference) => reference.name));
+ const knownKey = [...known].join("\n");
+
+ /* Rebuilt when the value no longer matches what is on screen, or when a
+ reference is added, removed or renamed and a chip's broken state flips. */
+ const renderedKnown = useRef<string | null>(null);
+ useLayoutEffect(() => {
+ const root = field.current;
+ if (!root) return;
+ const caret = pendingCaret.current ?? (document.activeElement === root ? caretRange(root)?.end ?? null : null);
+ if (serialize(root) !== value || renderedKnown.current !== knownKey || needsRender(root)) {
+ render(root, value, known);
+ renderedKnown.current = knownKey;
+ if (caret !== null && document.activeElement === root) placeCaret(root, caret);
+ }
+ if (pendingCaret.current !== null) {
+ root.focus();
+ placeCaret(root, pendingCaret.current);
+ selection.current = { start: pendingCaret.current, end: pendingCaret.current };
+ pendingCaret.current = null;
+ }
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [value, knownKey]);
+
+ /* The toolbar button takes the focus, so where the caret was is kept as it
+ moves; a reference goes there, or at the end of a field never focused. */
+ useEffect(() => {
+ const remember = () => {
+ const root = field.current;
+ const range = root && caretRange(root);
+ if (range) selection.current = range;
+ };
+ document.addEventListener("selectionchange", remember);
+ return () => document.removeEventListener("selectionchange", remember);
+ }, []);
+
+ const replace = (start: number, end: number, text: string) => {
+ pendingCaret.current = start + text.length;
+ const next = value.slice(0, start) + text + value.slice(end);
+ if (next === value) {
+ // Nothing to re-render, but the caret still has to come back.
+ const root = field.current!;
+ root.focus();
+ placeCaret(root, pendingCaret.current);
+ pendingCaret.current = null;
+ } else onChange(next);
+ };
+
+ const input = (native: Event) => {
+ const root = field.current!;
+ const next = serialize(root);
+ // Chrome writes a chip out of `[Name]` typed by hand only once the
+ // composition (an IME, a dead key) is over.
+ if (!(native as InputEvent).isComposing && needsRender(root)) {
+ const caret = caretRange(root)?.end ?? next.length;
+ render(root, next, known);
+ placeCaret(root, caret);
+ }
+ if (next !== value) onChange(next);
+ };
+
+ const keyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+ if (event.key !== "Enter" || event.nativeEvent.isComposing) return;
+ // A line break is a character of the value, not a <div> the browser adds.
+ event.preventDefault();
+ const range = caretRange(field.current!) ?? { start: value.length, end: value.length };
+ replace(range.start, range.end, "\n");
+ };
+
+ const openPicker = (anchor: HTMLElement, start: number, end: number, current: string | null) => {
+ if (disabled) return;
+ setPicking({ anchor, start, end, current });
+ };
+
+ const choose = (reference: PromptReference) => {
+ if (!picking) return;
+ const { start, end } = picking;
+ setPicking(null);
+ replace(start, end, promptReferenceToken(reference.name));
+ onInsertReference?.(reference);
+ };
+
+ return <div className={`prompt-field ${disabled ? "prompt-field--disabled" : ""} ${className ?? ""}`}>
+ <div className="prompt-field__toolbar" role="toolbar" aria-label={`${ariaLabel ?? "Prompt"} tools`}>
+ <button
+ ref={addButton}
+ type="button"
+ className="prompt-field__tool"
+ disabled={disabled}
+ aria-haspopup="dialog"
+ aria-expanded={picking?.current === null}
+ data-tooltip="Insert a reference at the caret"
+ onClick={() => {
+ if (picking) { setPicking(null); return; }
+ const at = selection.current ?? { start: value.length, end: value.length };
+ openPicker(addButton.current!, Math.min(at.start, value.length), Math.min(at.end, value.length), null);
+ }}
+ ><Add14 aria-hidden="true" />Reference</button>
+ </div>
+ <div
+ ref={field}
+ id={id}
+ className="prompt-field__input text-field"
+ role="textbox"
+ aria-multiline="true"
+ aria-label={ariaLabel}
+ aria-labelledby={ariaLabelledBy}
+ aria-placeholder={placeholder}
+ aria-disabled={disabled || undefined}
+ data-placeholder={placeholder}
+ contentEditable={!disabled}
+ suppressContentEditableWarning
+ spellCheck
+ tabIndex={disabled ? -1 : 0}
+ style={{ "--prompt-rows": rows } as CSSProperties}
+ onInput={(event) => input(event.nativeEvent)}
+ onKeyDown={keyDown}
+ onPaste={(event) => {
+ // Only the characters: markup pasted from elsewhere would land as
+ // elements the value has no way to say.
+ event.preventDefault();
+ const text = event.clipboardData.getData("text/plain").replace(/\r\n?/g, "\n");
+ const range = caretRange(field.current!) ?? { start: value.length, end: value.length };
+ replace(range.start, range.end, text);
+ }}
+ onDrop={(event) => event.preventDefault()}
+ onClick={(event) => {
+ const chip = (event.target as HTMLElement).closest<HTMLElement>(`[${CHIP}]`);
+ if (!chip || !field.current) return;
+ event.preventDefault();
+ const start = offsetBefore(field.current, chip);
+ const name = chip.getAttribute(CHIP)!;
+ openPicker(chip, start, start + promptReferenceToken(name).length, name);
+ }}
+ />
+ <ReferencePicker
+ picking={picking}
+ references={references}
+ onChoose={choose}
+ onRemove={() => {
+ if (!picking) return;
+ setPicking(null);
+ replace(picking.start, picking.end, "");
+ }}
+ onClose={() => setPicking(null)}
+ />
+ </div>;
+}
+
+function ReferencePicker({ picking, references, onChoose, onRemove, onClose }: {
+ picking: Picking | null;
+ references: readonly PromptReference[];
+ onChoose: (reference: PromptReference) => void;
+ onRemove: () => void;
+ onClose: () => void;
+}) {
+ const [filter, setFilter] = useState("");
+ const list = useRef<HTMLDivElement>(null);
+ const filterInput = useRef<HTMLInputElement>(null);
+ useEffect(() => { if (picking) setFilter(""); }, [picking]);
+ const query = filter.trim().toLowerCase();
+ const shown = references.filter((reference) => !query || reference.name.toLowerCase().includes(query));
+ const missing = picking?.current != null && !references.some((reference) => reference.name === picking.current);
+
+ const move = (event: ReactKeyboardEvent, step: number) => {
+ const options = [...(list.current?.querySelectorAll<HTMLButtonElement>("button:not(:disabled)") ?? [])];
+ if (!options.length) return;
+ event.preventDefault();
+ const at = options.indexOf(document.activeElement as HTMLButtonElement);
+ options[at < 0 ? (step > 0 ? 0 : options.length - 1) : (at + step + options.length) % options.length].focus();
+ };
+
+ return <Flyout
+ open={Boolean(picking)}
+ anchor={picking?.anchor ?? null}
+ onClose={onClose}
+ aria-label={picking?.current != null ? `Change reference ${picking.current}` : "Insert a reference"}
+ className="prompt-reference-picker"
+ initialFocus={filterInput}
+ width={280}
+ >
+ {picking?.current != null && <p className="prompt-reference-picker__current">
+ {missing ? <>No reference is named <b>{picking.current}</b>. Choose one to cite instead.</> : <>Cites <b>{picking.current}</b></>}
+ </p>}
+ {references.length > 6 && <TextField
+ inputRef={filterInput}
+ value={filter}
+ onChange={setFilter}
+ placeholder="Find a reference"
+ aria-label="Find a reference"
+ onKeyDown={(event) => {
+ if (event.key === "ArrowDown") move(event, 1);
+ if (event.key === "Enter" && shown.length) { event.preventDefault(); if (canCitePromptReference(shown[0].name)) onChoose(shown[0]); }
+ }}
+ />}
+ <div ref={list} className="prompt-reference-picker__list" role="group" aria-label="References" onKeyDown={(event) => {
+ if (event.key === "ArrowDown") move(event, 1);
+ if (event.key === "ArrowUp") move(event, -1);
+ }}>
+ {shown.map((reference) => {
+ const citable = canCitePromptReference(reference.name);
+ return <button
+ key={reference.id}
+ type="button"
+ className="prompt-reference-picker__option ui-selectable"
+ aria-pressed={reference.name === picking?.current}
+ disabled={!citable}
+ data-tooltip={citable ? undefined : "Rename it without brackets to cite it in a prompt"}
+ onClick={() => onChoose(reference)}
+ >
+ {reference.icon && <span className="prompt-reference-picker__icon" aria-hidden="true">{reference.icon}</span>}
+ <span className="prompt-reference-picker__text"><span>{reference.name}</span>{reference.detail && <small>{reference.detail}</small>}</span>
+ </button>;
+ })}
+ {!references.length && <p className="prompt-reference-picker__empty">No references yet — add them under References.</p>}
+ {references.length > 0 && !shown.length && <p className="prompt-reference-picker__empty">No reference matches “{filter.trim()}”.</p>}
+ </div>
+ {picking?.current != null && <button type="button" className="prompt-reference-picker__option prompt-reference-picker__remove" onClick={onRemove}>
+ <span className="prompt-reference-picker__icon" aria-hidden="true"><Delete14 /></span>Remove from the prompt
+ </button>}
+ </Flyout>;
+}
+
+/* --- The editable surface ------------------------------------------------ */
+
+function chipElement(name: string, known: ReadonlySet<string>): HTMLElement {
+ const chip = document.createElement("span");
+ chip.setAttribute(CHIP, name);
+ chip.setAttribute("contenteditable", "false");
+ chip.className = known.has(name) ? "prompt-chip" : "prompt-chip prompt-chip--missing";
+ chip.setAttribute("role", "button");
+ chip.setAttribute("aria-label", known.has(name) ? `Reference ${name}` : `Missing reference ${name}`);
+ chip.dataset.tooltip = known.has(name) ? "Change or remove this reference" : "No reference has this name — click to choose one";
+ chip.textContent = name;
+ return chip;
+}
+
+function render(root: HTMLElement, value: string, known: ReadonlySet<string>) {
+ const parts = splitPromptText(value);
+ root.replaceChildren(...parts.map((part) => part.kind === "text" ? document.createTextNode(part.value) : chipElement(part.value, known)));
+ if (parts.at(-1)?.kind === "reference") root.append(document.createTextNode(CARET_ROOM));
+ // A closing line break draws no line of its own without something after it.
+ if (value.endsWith("\n")) {
+ const end = document.createElement("br");
+ end.setAttribute(END, "");
+ root.append(end);
+ }
+}
+
+/** The value a subtree stands for. Takes a fragment too, so the text before
+ * the caret is measured by the same rule as the whole. */
+function serialize(node: Node): string {
+ let out = "";
+ node.childNodes.forEach((child) => {
+ if (child.nodeType === Node.TEXT_NODE) out += (child.textContent ?? "").replaceAll(CARET_ROOM, "");
+ else if (child instanceof HTMLElement) {
+ if (child.hasAttribute(CHIP)) out += promptReferenceToken(child.getAttribute(CHIP)!);
+ else if (child.tagName === "BR") out += child.hasAttribute(END) ? "" : "\n";
+ else {
+ // A block the browser wrapped a line in starts a new line.
+ if ((child.tagName === "DIV" || child.tagName === "P") && out && !out.endsWith("\n")) out += "\n";
+ out += serialize(child);
+ }
+ }
+ });
+ return out;
+}
+
+/** Whether the surface holds anything `render` would not have written: a
+ * `[Name]` still as text, a stray element, or typing beside a caret room. */
+function needsRender(root: HTMLElement): boolean {
+ return [...root.childNodes].some((child) => {
+ if (child.nodeType === Node.TEXT_NODE) {
+ const text = child.textContent ?? "";
+ return splitPromptText(text.replaceAll(CARET_ROOM, "")).some((part) => part.kind === "reference") || (text.includes(CARET_ROOM) && text !== CARET_ROOM);
+ }
+ return !(child instanceof HTMLElement && (child.hasAttribute(CHIP) || child.hasAttribute(END)));
+ }) || (root.lastChild?.nodeType === Node.ELEMENT_NODE && (root.lastChild as HTMLElement).hasAttribute(CHIP));
+}
+
+function offsetBefore(root: HTMLElement, node: Node): number {
+ const range = document.createRange();
+ range.selectNodeContents(root);
+ range.setEndBefore(node);
+ return serialize(range.cloneContents()).length;
+}
+
+/** The selection as offsets into the value, or null when it is not in the field. */
+function caretRange(root: HTMLElement): { start: number; end: number } | null {
+ const selection = document.getSelection();
+ if (!selection?.rangeCount) return null;
+ const range = selection.getRangeAt(0);
+ if (!root.contains(range.startContainer) || !root.contains(range.endContainer)) return null;
+ const measure = (container: Node, offset: number) => {
+ const before = document.createRange();
+ before.selectNodeContents(root);
+ before.setEnd(container, offset);
+ return serialize(before.cloneContents()).length;
+ };
+ return { start: measure(range.startContainer, range.startOffset), end: measure(range.endContainer, range.endOffset) };
+}
+
+function placeCaret(root: HTMLElement, offset: number) {
+ const range = document.createRange();
+ let remaining = offset;
+ let placed = false;
+ for (const child of [...root.childNodes]) {
+ const length = serialize(wrap(child)).length;
+ if (child.nodeType === Node.TEXT_NODE && remaining <= length) {
+ // The caret room is invisible: offset 0 inside it is right after the chip.
+ range.setStart(child, child.textContent === CARET_ROOM ? 0 : remaining);
+ placed = true;
+ break;
+ }
+ if (remaining === 0) { range.setStartBefore(child); placed = true; break; }
+ if (remaining < length) { range.setStartAfter(child); placed = true; break; }
+ remaining -= length;
+ }
+ if (!placed) { range.selectNodeContents(root); range.collapse(false); }
+ range.collapse(true);
+ const selection = document.getSelection();
+ selection?.removeAllRanges();
+ selection?.addRange(range);
+}
+
+function wrap(node: Node): Node {
+ const fragment = document.createDocumentFragment();
+ fragment.append(node.cloneNode(true));
+ return fragment;
+}
diff --git a/src/lib/promptReferences.ts b/src/lib/promptReferences.ts
new file mode 100644
index 0000000..789870d
--- /dev/null
+++ b/src/lib/promptReferences.ts
@@ -0,0 +1,39 @@
+/** References cited inside a free-text prompt, stored in the text itself as
+ * `[Reference name]`. The prompt field reads the same syntax back and shows
+ * each one as a smart chip, so what is saved and what is shown are one parse.
+ * A name holding a bracket or a line break could not be read back, so such a
+ * reference cannot be cited this way. */
+
+export interface PromptPart {
+ kind: "text" | "reference";
+ /** The literal characters for `text`; the reference name for `reference`. */
+ value: string;
+}
+
+const PROMPT_REFERENCE = /\[([^[\]\n]+)\]/g;
+
+export const promptReferenceToken = (name: string): string => `[${name}]`;
+
+export const canCitePromptReference = (name: string): boolean => name.trim().length > 0 && !/[[\]\n]/.test(name);
+
+export function splitPromptText(text: string): PromptPart[] {
+ const parts: PromptPart[] = [];
+ let cursor = 0;
+ for (const match of text.matchAll(PROMPT_REFERENCE)) {
+ const at = match.index ?? 0;
+ if (at > cursor) parts.push({ kind: "text", value: text.slice(cursor, at) });
+ parts.push({ kind: "reference", value: match[1] });
+ cursor = at + match[0].length;
+ }
+ if (cursor < text.length) parts.push({ kind: "text", value: text.slice(cursor) });
+ return parts;
+}
+
+/** Every reference name cited by a prompt, in the order it is first cited. */
+export function promptReferenceNames(text: string): string[] {
+ const seen: string[] = [];
+ for (const part of splitPromptText(text)) {
+ if (part.kind === "reference" && !seen.includes(part.value)) seen.push(part.value);
+ }
+ return seen;
+}
diff --git a/src/styles/prompt-field.css b/src/styles/prompt-field.css
new file mode 100644
index 0000000..558a2b7
--- /dev/null
+++ b/src/styles/prompt-field.css
@@ -0,0 +1,97 @@
+/* --- Prompt field ------------------------------------------------------------
+ A multi-line text field with references as smart chips inside the text, and
+ a slim toolbar above it (PromptTextField.tsx). */
+
+.prompt-field { display: flex; flex-direction: column; gap: var(--space-1); min-width: 0; }
+
+.prompt-field__toolbar { display: flex; align-items: center; gap: var(--space-1); }
+
+.prompt-field__tool {
+ display: inline-flex;
+ align-items: center;
+ gap: var(--space-1);
+ height: var(--control-sm);
+ padding: 0 var(--space-2);
+ border: 1px solid transparent;
+ border-radius: var(--radius-sm);
+ color: var(--text-secondary);
+ background: transparent;
+ font-size: var(--text-xs);
+ font-weight: var(--weight-regular);
+ transition: var(--transition-control);
+}
+.prompt-field__tool:hover:not(:disabled) { color: var(--text-primary); background: var(--fill-subtle-hover); }
+.prompt-field__tool:active:not(:disabled) { background: var(--fill-subtle-pressed); }
+.prompt-field__tool[aria-expanded="true"] { color: var(--accent-on-soft); background: var(--accent-soft); }
+.prompt-field__tool:disabled { color: var(--text-disabled); }
+
+.prompt-field__input {
+ width: 100%;
+ height: auto;
+ min-height: calc(var(--prompt-rows, 4) * 1lh + 2 * var(--space-2) + 2px);
+ padding: var(--space-2);
+ overflow-wrap: anywhere;
+ white-space: pre-wrap;
+ color: var(--text-primary);
+ font-weight: var(--weight-regular);
+ line-height: var(--leading-normal);
+ cursor: text;
+}
+.prompt-field__input:focus {
+ outline: none;
+ border-bottom-color: var(--field-focus-line);
+ box-shadow: inset 0 -1px 0 var(--field-focus-line);
+}
+.prompt-field__input:empty::before { content: attr(data-placeholder); color: var(--text-muted); pointer-events: none; }
+.prompt-field--disabled .prompt-field__input { color: var(--text-disabled); background: var(--fill-control-disabled); cursor: default; }
+
+/* Inline with the words: a chip is one line tall, so it never pushes the line
+ apart, and wraps as a whole. */
+.prompt-chip {
+ display: inline-block;
+ max-width: 100%;
+ margin-inline: 1px;
+ padding: 0 var(--space-2);
+ overflow: hidden;
+ border: 1px solid var(--accent-line);
+ border-radius: var(--radius-pill);
+ color: var(--accent-on-soft);
+ background: var(--accent-soft);
+ font-size: var(--text-xs);
+ font-weight: var(--weight-semibold);
+ line-height: calc(1lh - 2px);
+ vertical-align: baseline;
+ white-space: nowrap;
+ text-overflow: ellipsis;
+ cursor: default;
+ user-select: none;
+}
+.prompt-chip:hover { background: var(--accent-soft-strong); }
+.prompt-chip--missing { border-color: var(--danger-line); color: var(--danger); background: var(--danger-soft); text-decoration: line-through; }
+.prompt-chip--missing:hover { background: var(--danger-soft-strong); }
+.prompt-field--disabled .prompt-chip { cursor: default; opacity: 0.6; }
+
+.prompt-reference-picker { display: flex; flex-direction: column; gap: var(--space-2); padding: var(--space-2); }
+.prompt-reference-picker__current { margin: 0; padding: var(--space-1) var(--space-2); color: var(--text-secondary); font-size: var(--text-xs); }
+.prompt-reference-picker__list { display: flex; flex-direction: column; gap: 2px; max-height: 280px; overflow-y: auto; }
+.prompt-reference-picker__option {
+ display: flex;
+ align-items: center;
+ gap: var(--space-2);
+ min-height: 32px;
+ padding: var(--space-1) var(--space-2);
+ border: 0;
+ border-radius: var(--radius-sm);
+ color: var(--text-primary);
+ background: transparent;
+ font-size: var(--text-base);
+ text-align: start;
+}
+.prompt-reference-picker__option:hover:not(:disabled) { background: var(--fill-subtle-hover); }
+.prompt-reference-picker__option:disabled { color: var(--text-disabled); }
+.prompt-reference-picker__icon { display: inline-flex; flex: none; align-items: center; justify-content: center; width: 20px; color: var(--text-secondary); }
+.prompt-reference-picker__text { display: flex; flex-direction: column; min-width: 0; }
+.prompt-reference-picker__text > span { overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+.prompt-reference-picker__text small { color: var(--text-muted); font-size: var(--text-xs); }
+.prompt-reference-picker__empty { margin: 0; padding: var(--space-2); color: var(--text-muted); font-size: var(--text-xs); }
+.prompt-reference-picker__remove { border-top: 1px solid var(--line); border-radius: 0; color: var(--danger); }