From cad2e27f254753ac23bca29f68255c5f426d5846 Mon Sep 17 00:00:00 2001 From: zereraz Date: Sat, 27 Jun 2026 22:05:46 +0530 Subject: [PATCH 1/3] feat: bake in a standard self-contained favicon for all generated pages - SKILL.md: add favicon to delivery rules + final checklist, plus a KaTeX '<'-escaping note that prevents formula truncation - templates: add the data-URI favicon to all 4 reference templates - extension.ts: ensureFavicon() deterministically injects the favicon after (or into ) on render unless an icon link already exists, so pages get it even if the agent omits it The favicon is a self-contained data-URI SVG (node-graph glyph, dark/accent palette), consistent with the self-contained-HTML requirement. --- plugins/visual-explainer/SKILL.md | 12 ++++++++++++ plugins/visual-explainer/extension.ts | 14 +++++++++++++- .../visual-explainer/templates/architecture.html | 1 + plugins/visual-explainer/templates/data-table.html | 1 + .../templates/mermaid-flowchart.html | 1 + plugins/visual-explainer/templates/slide-deck.html | 1 + 6 files changed, 29 insertions(+), 1 deletion(-) diff --git a/plugins/visual-explainer/SKILL.md b/plugins/visual-explainer/SKILL.md index ed59377..3c93817 100644 --- a/plugins/visual-explainer/SKILL.md +++ b/plugins/visual-explainer/SKILL.md @@ -19,6 +19,17 @@ Generate self-contained HTML pages that explain systems, code changes, plans, da - Write files to `~/.agent/diagrams/` or the explicit eval output path. Use descriptive filenames. - Open generated pages in the browser when running normally. In Pi package installs, use `visual_explainer` with `prepare` for planning/context and `render` only after the complete HTML document exists. - The final page must be a complete self-contained HTML document, including embedded CSS and any needed JS. +- Always include the standard self-contained data-URI favicon immediately after `` (see "Favicon" below). Never leave a page without a favicon. + +## Favicon + +Every generated page must include this exact self-contained data-URI favicon, placed immediately after the `` tag. It needs no external file and is a small node-graph glyph that matches the dark/accent palette: + +```html + +``` + +If math is rendered with KaTeX, escape `<` as `<` inside `$$...$$` (e.g. `y_{<t}`); a bare `<` makes the HTML parser truncate the formula. ## Reference routing @@ -92,6 +103,7 @@ If `surf` is available, generated images may be embedded as base64 for hero bann Before delivery, verify: - complete HTML document; +- standard favicon `` present immediately after ``; - output written to the requested path; - no console errors when opened; - no horizontal overflow at normal desktop width; diff --git a/plugins/visual-explainer/extension.ts b/plugins/visual-explainer/extension.ts index 57de38f..234fa4f 100644 --- a/plugins/visual-explainer/extension.ts +++ b/plugins/visual-explainer/extension.ts @@ -128,6 +128,17 @@ function outputFilename(input: string) { return /\.html?$/i.test(raw) ? raw : `${raw}.html`; } +const STANDARD_FAVICON = + ''; + +// Guarantees the house-style favicon is present, regardless of what the agent emitted. +function ensureFavicon(html: string): string { + if (/]*rel\s*=\s*["']?(?:shortcut\s+)?icon/i.test(html)) return html; + if (/<\/title>/i.test(html)) return html.replace(/<\/title>/i, `\n${STANDARD_FAVICON}`); + if (/]*>/i.test(html)) return html.replace(/]*>/i, (m) => `${m}\n${STANDARD_FAVICON}`); + return html; +} + function assertHtmlDocument(html: string) { const trimmed = html.trim(); if (!trimmed) throw new Error("html is required"); @@ -276,7 +287,8 @@ async function renderVisualExplanation(params: VisualExplainerParams, signal?: A } signal?.throwIfAborted(); - writeFileSync(outputPath, params.html, "utf8"); + const finalHtml = ensureFavicon(params.html); + writeFileSync(outputPath, finalHtml, "utf8"); signal?.throwIfAborted(); diff --git a/plugins/visual-explainer/templates/architecture.html b/plugins/visual-explainer/templates/architecture.html index edc1b43..87f3548 100644 --- a/plugins/visual-explainer/templates/architecture.html +++ b/plugins/visual-explainer/templates/architecture.html @@ -4,6 +4,7 @@ Architecture Diagram — Reference Template +