web-app-launcher/plans/phase-4-7-full-expansion/CONTEXT.md

Feature Context: Phases 4–7 — Full Feature Expansion

Configuration

• Development mode: Automated
• Execution mode: Orchestrator
• Strategy: Big Bang
• Build: npm run build
• Test: npm test
• Lint: npm run lint
• Type Check: npm run check
• Dev server: npm run dev (port: 5181)

Current State

All 8 phases are complete. Phase 8 (Integration & Polish) fixed all build, type, lint, and test errors. Build, check, lint, and tests all pass. All 10 new Prisma models created, existing models extended, migration applied, Prisma client regenerated. Widget types now include 13 values: app, bookmark, note, embed, status, clock, system_stats, rss, calendar, markdown, metric, link_group, camera. New constants added: CardSize, NotificationType, NotificationEvent, ApiTokenScope, AuditAction, BackgroundType. 5 new type files created, 4 existing type files extended, validators.ts has 19 new Zod schemas. 6 new widget services created: weatherService, systemStatsService, rssFeedService, calendarService, metricService, cameraService. 7 new API routes under /api/widgets/: weather, system-stats, rss, calendar, metric, camera, data (aggregation). boardService updated with widget config validation on create/update and new theme/visual field passthrough. Theme system uses HSL CSS variables with dark/light/system modes. Auth system: local + OAuth with JWT cookies + API token bearer auth. 7 new functional services created: favoriteService, recentAppsService, uptimeService, notificationService, tagService, apiTokenService, auditLogService. 16 new API routes for: favorites, recent-apps, uptime, notifications (channels, test), tags (app-tags), app-links, tokens, admin audit-log. appService extended with multi-URL link management and eager-loaded links. Healthcheck scheduler now triggers notifications on status transitions and prunes audit logs daily. Audit logging integrated into user CRUD, app CRUD, board CRUD, settings, import, and export routes. 8 new widget UI components created: ClockWeatherWidget, SystemStatsWidget, RssFeedWidget, CalendarWidget, MarkdownWidget, MetricWidget, LinkGroupWidget, CameraStreamWidget. WidgetRenderer routes all 13 widget types to their components. WidgetCreationForm has config forms for all 13 types. WidgetGrid updated with new full-width types (system_stats, rss, calendar, markdown, camera). Phase 6 functional frontend complete: 2 new stores (favorites, notifications), 22 new/modified component files, 6 new routes. FavoritesBar with drag-and-drop reordering, RecentAppsSection with time-ago display, Status page at /status with uptime summary. NotificationBell in header with unread badge and 60s polling, NotificationChannelForm with Discord/Slack/Telegram/HTTP support. TagManager admin CRUD, TagBadge component, TagFilter for board filtering. AppWidget updated with expandable multi-URL links, context menu for favorites, and click recording. API Token management at /settings/api-tokens with create/revoke form actions. AuditLogTable with filters, expandable JSON details, CSV export, and pagination. Phase 7 quality-of-life complete: onboarding wizard (5-step overlay with admin creation, auth mode, theme, board setup), URL preview (test connection with favicon/title extraction), board templates (4 builtins + user CRUD + import/export), keyboard shortcuts (j/k nav, 1-9 boards, ?-overlay, f-favorites, e-edit). New services: onboardingService, templateService. New stores: keyboard.svelte.ts. 3 new API route groups: /api/onboarding, /api/apps/preview, /api/templates.

Temporary Workarounds

(none yet)

Cross-Phase Dependencies

• Phase 1 (schema) must complete before Phase 2 (widget backend) and Phase 5 (functional backend)
• Phase 2 (widget backend) must complete before Phase 3 (widget frontend)
• Phase 5 (functional backend) must complete before Phase 6 (functional frontend)
• Phase 4 (visual) is independent — can run parallel with Phase 2 or 3
• Phase 7 (QoL) depends on Phases 5+6 for some features (onboarding references tags, templates)
• Phase 8 (integration) depends on all prior phases

Deferred Work

(none yet)

Failed Approaches

(none yet)

Review Findings Log

(none yet)

Visual Decisions (Phase 4)

• Glassmorphism uses color-mix(in srgb, ...) for semi-transparent backgrounds (works across light/dark modes)
• Card style classes (.card-solid, .card-glass, .card-outline) are global CSS in app.css, applied via card-${theme.cardStyle} derived class
• Board theme overrides apply at :root level (not scoped) for maximum CSS variable reach; cleanup restores global store values
• AnimatedStatusRing uses SVG stroke-dasharray/stroke-dashoffset animations, scales via size prop
• Card size grid columns: compact=6col, medium=4col, large=3col (responsive breakpoints)
• Custom CSS sanitization is regex-based (strips script tags, javascript: URLs, expression(), @import, behavior:, -moz-binding)
• updateBoardSchema backgroundType uses inline enum ['mesh', 'particles', 'aurora', 'wallpaper', 'none'] instead of BackgroundType constant

Phase Execution Log

Phase	Agent Used	Test Writer	Parallel	Notes
Phase 1	phase-implementer	⏭️ Skipped (Big Bang)	—	Schema & types only
Phase 2	phase-implementer	⏭️ Skipped (Big Bang)	—	6 services, 7 API routes, boardService updated
Phase 5	phase-implementer	⏭️ Skipped (Big Bang)	—	7 services, 16 API routes, appService/healthcheckScheduler/hooks.server/authenticate extended, audit logging integrated
Phase 3	phase-implementer	⏭️ Skipped (Big Bang)	—	8 widget components, WidgetRenderer + WidgetCreationForm + WidgetGrid updated
Phase 4	phase-implementer	⏭️ Skipped (Big Bang)	—	6 visual features, fixes to server action + validator + theme restore
Phase 6	phase-implementer	⏭️ Skipped (Big Bang)	—	8 functional frontend features: favorites, recent apps, status page, notifications, tags, multi-URL cards, API tokens, audit log
Phase 7	phase-implementer	⏭️ Skipped (Big Bang)	—	4 QoL features: onboarding wizard, URL preview, board templates, keyboard shortcuts

Environment & Runtime Notes

• SQLite database at file:/app/data/launcher.db
• Prisma ORM with cuid IDs
• Svelte 5 runes mode ($state, $derived, $props)
• Tailwind CSS v4 with @theme inline in app.css

Implementation Notes

• Existing widget types defined in WidgetType constant (src/lib/utils/constants.ts)
• Widget configs stored as JSON string in Widget.config column
• All Zod schemas in src/lib/utils/validators.ts
• Type definitions in src/lib/types/*.ts
• API routes use consistent envelope: { success, data, error, meta }
• Services in src/lib/server/services/*.ts — no business logic in routes