/** * Build the visual companion instruction block to append to sub-agent prompts. * Tells the agent how to write HTML screens, what CSS classes are available, * and how to read user interaction events. */ export function buildVisualInstructions(url: string, sessionDir: string): string { const fence = "```"; const sections: string[] = [ "## Visual Companion Active", "", `A browser companion is running at ${url}. The user can see visual content there.`, "", "### When to Use Browser vs Terminal", "", "- **Use the browser** for content that IS visual: mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs, A/B/C option cards, pros/cons tables", "- **Use the terminal** for content that is text: requirements questions, conceptual choices, discussion, final plan output", "", "A question about a UI topic is not automatically a visual question. Conceptual questions go to the terminal. Visual comparisons go to the browser.", "", "### How to Write HTML Screens", "", `Write HTML fragment files to \`${sessionDir}/\` with descriptive filenames:`, "- `screen-001-approaches.html`", "- `screen-002-architecture.html`", "", "The server auto-wraps fragments in a styled frame with dark/light theme support. You do NOT need to write full HTML documents — just the content inside ``.", "", "### Available CSS Classes", "", "Your HTML fragments can use these classes (provided by the frame template):", "", "**Choices (A/B/C options):**", "- `.options` > `.option[data-choice=\"x\"]` with `.letter` + `.content` children", "", `${fence}html`, '
', '
', '
A
', '
', "

Option Title

", "

Description text

", "
", "
", "
", fence, "", "**Cards (grid layout, multi-select with `data-multiselect`):**", '- `.cards` > `.card[data-choice="x"]` with `.card-image` + `.card-body`', "", "**Mockup containers:**", "- `.mockup` > `.mockup-header` + `.mockup-body`", "", "**Side-by-side comparison:**", "- `.split` — two-column grid (responsive)", "", "**Pros/Cons:**", "- `.pros-cons` > `.pros` + `.cons` — color-coded green/red headers", "", "**Placeholders:**", "- `.placeholder` — dashed border boxes for areas to be filled", "", "**Mock UI elements:**", "- `.mock-nav`, `.mock-sidebar`, `.mock-content`, `.mock-button`, `.mock-input`", "", "**Typography:**", "- `h2` (page title), `h3` (section heading), `.subtitle`, `.label`, `.section`", "", "### Example Screen", "", `${fence}html`, '

Architecture Approach

', '

Choose the approach that best fits your needs

', '
', '
', '
A
', '
', "

Monolith

", "

Single service, simpler deployment

", "
", "
", '
', '
B
', '
', "

Microservices

", "

Distributed, independently scalable

", "
", "
", "
", fence, "", "### Reading User Choices", "", "When you present choices in the browser, the user clicks `[data-choice]` elements.", `Read \`${sessionDir}/.events\` to see their selections (newline-delimited JSON).`, 'Each event: `{ "type": "click", "choice": "a", "text": "Option Title", "timestamp": 1234 }`', "", "After presenting a visual screen, tell the user to check their browser and respond in the terminal. Then read the .events file to see what they clicked.", ]; return sections.join("\n"); }