139 lines
7 KiB
Markdown
139 lines
7 KiB
Markdown
---
|
|
phase: 41-diagrams-icons-theme-engine
|
|
plan: "02"
|
|
subsystem: api
|
|
tags: [diagram-renderer, icon-renderer, playwright, dompurify, resvg, svgo, sharp, llm-synthesis, mermaid, tdd]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 41-01
|
|
provides: RenderResult/DiagramBundle/IconSetBundle types, renderer stubs, server deps installed
|
|
|
|
provides:
|
|
- server/src/services/renderers/diagram-renderer.ts — LLM prompt synthesis + Playwright Mermaid render + DOMPurify + Resvg
|
|
- server/src/services/renderers/icon-renderer.ts — LLM SVG icon generation + SVGO cleanup + sharp PNG rasterization
|
|
- server/src/services/puter-inference.ts — shared non-streaming LLM completion helper (Puter API)
|
|
- server/src/__tests__/diagram-renderer.test.ts — 18 tests for stripUnsafeDirectives, buildDiagramPrompt, renderDiagram
|
|
- server/src/__tests__/icon-renderer.test.ts — 12 tests for validateAndCleanSvg, renderIconSet
|
|
|
|
affects: [41-03-theme, 41-05-ui-generator, 41-06-ui-theme]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: []
|
|
patterns:
|
|
- "puterChatComplete: non-streaming LLM helper via PUTER_AUTH_TOKEN env var + Puter AI proxy (OpenAI-compatible)"
|
|
- "stripUnsafeDirectives: regex-based Mermaid security — removes %%{init}%% blocks and click directives before render"
|
|
- "renderDiagram: prompt -> LLM Mermaid synthesis -> stripUnsafeDirectives -> Playwright headless -> DOMPurify -> Resvg PNG"
|
|
- "validateAndCleanSvg: SVGO preset-default + viewBox/xmlns normalization + drawable element presence check"
|
|
- "renderIconSet: LLM JSON array -> validateAndCleanSvg each -> sharp rasterize 16/32/64 -> IconSetBundle"
|
|
- "JSON retry pattern: parse fail -> retry LLM with explicit JSON-only follow-up message"
|
|
|
|
key-files:
|
|
created:
|
|
- server/src/services/renderers/diagram-renderer.ts
|
|
- server/src/services/renderers/icon-renderer.ts
|
|
- server/src/services/puter-inference.ts
|
|
- server/src/__tests__/diagram-renderer.test.ts
|
|
- server/src/__tests__/icon-renderer.test.ts
|
|
modified: []
|
|
|
|
key-decisions:
|
|
- "puter-inference.ts created as shared non-streaming helper — avoids duplicating Puter fetch boilerplate in each renderer"
|
|
- "resolveBrowserPath uses built-in fs/path (not glob npm dep) — simpler, no new dependency"
|
|
- "DOMPurify window cast uses 'any' — @types/dompurify WindowLike interface incompatible with JSDOM window; type-safe cast not possible"
|
|
- "SVGO preset-default is applied before drawable element check — SVGO removes degenerate paths so test SVGs must use complete path data"
|
|
|
|
# Metrics
|
|
duration: 10min
|
|
completed: 2026-04-04
|
|
---
|
|
|
|
# Phase 41 Plan 02: Diagram Renderer + Icon Renderer Summary
|
|
|
|
**Diagram renderer synthesizes Mermaid from natural language via LLM (DIAG-01), strips unsafe directives (DIAG-05), renders SVG+PNG via Playwright+DOMPurify+Resvg; icon renderer generates SVG icon sets via LLM, cleans with SVGO, rasterizes to 3 PNG sizes via sharp**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** ~10 min
|
|
- **Started:** 2026-04-04T20:36:38Z
|
|
- **Completed:** 2026-04-04T20:42:00Z
|
|
- **Tasks:** 2
|
|
- **Files created/modified:** 5
|
|
|
|
## Accomplishments
|
|
|
|
- Diagram renderer: full LLM->Mermaid->Playwright->SVG->PNG pipeline with security stripping
|
|
- Icon renderer: full LLM->JSON->SVGO->sharp->PNG bundle pipeline with retry and partial failure handling
|
|
- puter-inference.ts: reusable non-streaming LLM helper for all server-side renderers
|
|
- 30 total tests passing (18 diagram + 12 icon), all TDD RED->GREEN
|
|
- TypeScript passes cleanly with `pnpm tsc --noEmit`
|
|
- Both renderers replace their Plan 01 stubs and conform to RenderResult contract
|
|
|
|
## Task Commits
|
|
|
|
1. **Task 1: Diagram renderer with LLM synthesis + Playwright + security + tests** - `9c3146fd` (feat)
|
|
2. **Task 2: Icon renderer with LLM SVG generation + SVGO + PNG variants + tests** - `175dce3b` (feat)
|
|
|
|
## Files Created
|
|
|
|
- `server/src/services/renderers/diagram-renderer.ts` - Full implementation replacing stub from Plan 01
|
|
- `server/src/services/renderers/icon-renderer.ts` - Full implementation replacing stub from Plan 01
|
|
- `server/src/services/puter-inference.ts` - Shared non-streaming LLM completion via Puter AI proxy
|
|
- `server/src/__tests__/diagram-renderer.test.ts` - 18 tests: stripUnsafeDirectives (5), buildDiagramPrompt (7), renderDiagram (6)
|
|
- `server/src/__tests__/icon-renderer.test.ts` - 12 tests: validateAndCleanSvg (6), renderIconSet (6)
|
|
|
|
## Decisions Made
|
|
|
|
- Created `puter-inference.ts` as a shared helper instead of inlining Puter fetch in each renderer. All renderer LLM calls flow through this one module, which reads `PUTER_AUTH_TOKEN` from environment.
|
|
- Used Node.js `fs`/`path` for browser path resolution instead of adding `glob` as a dependency.
|
|
- DOMPurify type cast uses `any` because `@types/dompurify`'s `WindowLike` interface does not match JSDOM's window type exactly — this is a known type incompatibility.
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 3 - Blocking] Replaced glob import with built-in fs/path**
|
|
- **Found during:** Task 1 (GREEN phase)
|
|
- **Issue:** `import { glob } from "glob"` failed — `glob` is not installed in server package
|
|
- **Fix:** Implemented a simple two-level directory scan using Node.js `fs.readdirSync` and `fs.existsSync`
|
|
- **Files modified:** server/src/services/renderers/diagram-renderer.ts
|
|
- **Commit:** 9c3146fd
|
|
|
|
**2. [Rule 1 - Bug] Fixed test SVG for "adds xmlns when missing" test**
|
|
- **Found during:** Task 2 (GREEN phase test run)
|
|
- **Issue:** SVGO `preset-default` correctly removes degenerate SVG paths (e.g. `d="M12 2"` — just a move, no shape). The test used this degenerate path, so after SVGO the SVG had no drawable elements and `validateAndCleanSvg` returned `valid: false`.
|
|
- **Fix:** Updated test SVG to use a complete triangle path `d="M12 2L2 7l10 5z"` that SVGO preserves
|
|
- **Files modified:** server/src/__tests__/icon-renderer.test.ts
|
|
- **Commit:** 175dce3b
|
|
|
|
**3. [Rule 1 - Bug] Fixed DOMPurify window type cast**
|
|
- **Found during:** Task 1 tsc check
|
|
- **Issue:** `window as unknown as Window` caused TS2345 error — JSDOM's window type is not assignable to `WindowLike`
|
|
- **Fix:** Changed cast to `window as any` with eslint-disable comments
|
|
- **Files modified:** server/src/services/renderers/diagram-renderer.ts
|
|
- **Commit:** 175dce3b
|
|
|
|
---
|
|
|
|
**Total deviations:** 3 auto-fixed (Rules 1 and 3 — blocking and bug)
|
|
**Impact on plan:** No scope change. All fixes are minor corrections that maintain the intent of the plan.
|
|
|
|
## Known Stubs
|
|
|
|
None — both renderers are fully implemented. All Plan 01 stubs have been replaced.
|
|
|
|
## User Setup Required
|
|
|
|
- `PUTER_AUTH_TOKEN` environment variable must be set for LLM calls to work at runtime
|
|
- `npx playwright install chromium` must be run (or `PLAYWRIGHT_BROWSERS_PATH` set) for diagram rendering at runtime
|
|
|
|
## Next Phase Readiness
|
|
|
|
- Plan 41-03 (theme renderer) can now follow the same pattern: `puterChatComplete` for LLM + `RenderResult` return
|
|
- puter-inference.ts is ready for reuse in theme-renderer.ts
|
|
- All Phase 41 content types (diagram, icon, theme) share the same job runner → renderer dispatch pattern
|
|
|
|
---
|
|
*Phase: 41-diagrams-icons-theme-engine*
|
|
*Completed: 2026-04-04*
|