131 lines
6.9 KiB
Markdown
131 lines
6.9 KiB
Markdown
---
|
|
phase: 41-diagrams-icons-theme-engine
|
|
plan: "01"
|
|
subsystem: api
|
|
tags: [culori, resvg, svgo, wcag-contrast, playwright-core, shadcn, sse, content-jobs]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 40-job-infrastructure
|
|
provides: content_jobs table, renderContent stub, SSE events, contentJobRunner.dispatch, content-job routes
|
|
provides:
|
|
- culori, @resvg/resvg-js, wcag-contrast, svgo, playwright-core installed in server
|
|
- server/src/services/renderers/types.ts — RenderResult, DiagramBundle, IconSetBundle, ThemePaletteBundle, PaletteRole, ContentBundle
|
|
- content-job-runner switch dispatching diagram/icon-set/theme-palette to renderer imports
|
|
- stub renderer files: diagram-renderer.ts, icon-renderer.ts, theme-renderer.ts (ready for Phase 41 plans 02-04)
|
|
- ui/src/api/contentJobs.ts — submitContentJob, getContentJob, getContentJobAsset
|
|
- ui/src/hooks/useContentJob.ts — submit, reset, SSE progress tracking
|
|
- ui/src/components/ui/progress.tsx and toggle.tsx (shadcn)
|
|
affects: [41-02-diagram, 41-03-icon, 41-04-theme, 41-05-ui-generator, 41-06-ui-theme]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: [culori, "@resvg/resvg-js", wcag-contrast, svgo, "playwright-core@1.58.2"]
|
|
patterns:
|
|
- "Dynamic import renderer dispatch: switch(jobType) { case 'x': const { fn } = await import('./renderers/x-renderer.js') }"
|
|
- "useContentJob hook: companyId parameter, submit/reset, EventSource SSE, progress = queued:5% / running:50% / done:100%"
|
|
- "culori ESM (converter/formatHex) works directly under NodeNext — no fn/ import needed"
|
|
|
|
key-files:
|
|
created:
|
|
- server/src/services/renderers/types.ts
|
|
- server/src/services/renderers/diagram-renderer.ts
|
|
- server/src/services/renderers/icon-renderer.ts
|
|
- server/src/services/renderers/theme-renderer.ts
|
|
- ui/src/api/contentJobs.ts
|
|
- ui/src/hooks/useContentJob.ts
|
|
- ui/src/components/ui/progress.tsx
|
|
- ui/src/components/ui/toggle.tsx
|
|
modified:
|
|
- server/src/services/content-job-runner.ts
|
|
- server/package.json
|
|
- pnpm-lock.yaml
|
|
|
|
key-decisions:
|
|
- "Renderer stub files created to satisfy tsc module resolution — plans 02-04 replace with real implementations"
|
|
- "playwright-core@1.58.2 pinned to match @playwright/test version in root"
|
|
- "culori ESM import confirmed working under NodeNext — no workaround needed"
|
|
|
|
patterns-established:
|
|
- "Renderer pattern: each renderer in server/src/services/renderers/{name}-renderer.ts, exports async function with RenderResult return type"
|
|
- "UI hook pattern: useContentJob(companyId) — accept companyId as parameter (not from context) matching other hooks in codebase"
|
|
|
|
requirements-completed: [DIAG-01, DIAG-02, ICON-01, THEME-01]
|
|
|
|
# Metrics
|
|
duration: 15min
|
|
completed: 2026-04-04
|
|
---
|
|
|
|
# Phase 41 Plan 01: Foundation — Shared Types, Deps, Job Runner, UI Hook Summary
|
|
|
|
**culori/resvg/svgo deps installed, RenderResult bundle types defined, content-job-runner wired to diagram/icon-set/theme-palette switch, and useContentJob SSE hook ready for UI plans**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** ~15 min
|
|
- **Started:** 2026-04-04T20:30:00Z
|
|
- **Completed:** 2026-04-04T20:45:00Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 9
|
|
|
|
## Accomplishments
|
|
- All 5 server deps (culori, @resvg/resvg-js, wcag-contrast, svgo, playwright-core@1.58.2) installed and verified importable via tsx
|
|
- Bundle type contracts (RenderResult, DiagramBundle, IconSetBundle, ThemePaletteBundle) defined as stable API for all Phase 41 renderers
|
|
- content-job-runner.ts `renderContent` stub replaced with dynamic import switch dispatching to three renderer files
|
|
- useContentJob hook with SSE progress tracking, EventSource cleanup on unmount/done/failed
|
|
- shadcn progress and toggle components added to UI
|
|
|
|
## Task Commits
|
|
|
|
1. **Task 1: Install dependencies and add shadcn components** - `f3c08690` (feat)
|
|
2. **Task 2: Shared types, content-job-runner switch, useContentJob hook, API helpers** - `39af92c6` (feat)
|
|
|
|
## Files Created/Modified
|
|
- `server/src/services/renderers/types.ts` - Shared bundle type contracts for all renderers
|
|
- `server/src/services/renderers/diagram-renderer.ts` - Stub (tsc resolution; Phase 41-02 implements)
|
|
- `server/src/services/renderers/icon-renderer.ts` - Stub (tsc resolution; Phase 41-03 implements)
|
|
- `server/src/services/renderers/theme-renderer.ts` - Stub (tsc resolution; Phase 41-04 implements)
|
|
- `server/src/services/content-job-runner.ts` - Replaced stub renderContent with switch dispatch
|
|
- `ui/src/api/contentJobs.ts` - submitContentJob, getContentJob, getContentJobAsset
|
|
- `ui/src/hooks/useContentJob.ts` - submit/reset, SSE EventSource progress tracking
|
|
- `ui/src/components/ui/progress.tsx` - shadcn Progress component
|
|
- `ui/src/components/ui/toggle.tsx` - shadcn Toggle component
|
|
- `server/package.json` - Added 5 new dependencies
|
|
- `pnpm-lock.yaml` - Updated lockfile
|
|
|
|
## Decisions Made
|
|
- Created stub renderer files (diagram-renderer.ts, icon-renderer.ts, theme-renderer.ts) to satisfy TypeScript module resolution. The plan noted runtime failure is expected until renderers are implemented — tsc still requires the files exist for `import()` to resolve.
|
|
- playwright-core pinned at 1.58.2 to match @playwright/test version in root to avoid binary mismatch.
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 2 - Missing Critical] Created renderer stub files for tsc resolution**
|
|
- **Found during:** Task 2 (content-job-runner switch implementation)
|
|
- **Issue:** TypeScript's `--noEmit` check fails on dynamic imports to non-existent files even when the plan explicitly says runtime failure is expected
|
|
- **Fix:** Created minimal stub files exporting the expected function signatures with `throw new Error("not yet implemented")`
|
|
- **Files modified:** server/src/services/renderers/diagram-renderer.ts, icon-renderer.ts, theme-renderer.ts
|
|
- **Verification:** `pnpm tsc --noEmit --project server/tsconfig.json` passes with exit 0
|
|
- **Committed in:** 39af92c6 (Task 2 commit)
|
|
|
|
---
|
|
|
|
**Total deviations:** 1 auto-fixed (Rule 2 - missing for correctness)
|
|
**Impact on plan:** Necessary for tsc verification criterion. Stubs are clearly marked and will be replaced by plans 02-04.
|
|
|
|
## Issues Encountered
|
|
- Pre-existing TypeScript errors exist in ui/tsconfig.json (unrelated files: AgentConfigForm.tsx, useKeyboardShortcuts.ts, useNexusMode.ts, usePiperTts.ts, useVadRecorder.ts, InstanceGeneralSettings.tsx, PersonalAssistant.tsx). These are out-of-scope pre-existing issues, not caused by this plan. Server TSC passes cleanly.
|
|
|
|
## User Setup Required
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
- Plans 41-02 (diagram renderer), 41-03 (icon renderer), 41-04 (theme renderer) can now import from `./renderers/types.js` and implement their functions against the stub signatures
|
|
- useContentJob hook ready for consumption by UI plans 41-05 and 41-06
|
|
- All deps available: culori for OKLCH color math, @resvg/resvg-js for SVG→PNG, svgo for SVG optimization, wcag-contrast for WCAG AA checks
|
|
|
|
---
|
|
*Phase: 41-diagrams-icons-theme-engine*
|
|
*Completed: 2026-04-04*
|