# QoL And Performance Backlog

Date: 2026-05-27

Scope: current build-noise, bundle, Prisma, sourcemap, lint, and Docker follow-up state. This is not a broad runtime performance rewrite.

## Intake Rules

- Capture the exact command, warning text, and affected package before fixing.
- Prefer one warning class per PR or phase step.
- Fix configuration and ownership issues before speculative runtime optimization.
- Add a regression gate when a warning is suppressed or accepted.

## Current State

| Item | Current Signal | Decision | Done When |
| --- | --- | --- | --- |
| Build warnings | `pnpm run build` is green but still emits known Production-build warnings: sourcemaps enabled, React Router empty chunks, AWS/Smithy circular chunk warnings, and Vite dynamic+static import chunk notices. See `docs/ops/production-build-warnings.md`. | Keep unknown warnings visible through `apps/web/app/utils/build/buildWarningTriage.ts`. Keep empty client chunks guarded through `pnpm run verify:bundle-size`. | New warning classes fail visibly or require an explicit allowlist/test update. |
| Bundle chunks | `pnpm run verify:bundle-size` enforces root/initial-payload/vendor/route/other/total JS/CSS budgets and reports largest JS chunks. | The default shell no longer inherits the large chatbot, command palette, onboarding, WYSIWYG editor, disposable-email validation payloads, AI-SDK chat runtime, Streamdown, syntax-language payloads, Mermaid, Cytoscape, or Recharts chart runtime. The 2026-05-27 baseline also accounts for intentional lazy observability chunks and aligns the aggregate route bucket with React Router v7 route-id chunks. Treat remaining top chunks as lazy feature-owned payloads, not shell blockers. The explicit `initial_payload_js` guard tracks only parser-known boot assets (`entry.client-*`, `root-*`, `manifest-*`) so lazy chunks do not distort shell regressions. | Any intentional growth updates budgets with rationale; unexpected empty JS chunks fail the gate. |
| Prisma / ORM | Prisma is already on `7.8.0`; there is no active Prisma 6 deprecation warning. | Keep Prisma per `packages/db/ORM-DECISION.md`; revisit only if Prisma 7 generated-client ownership or adapter behavior causes deploy friction. | ORM decision remains documented and DB package boundaries stay green. |
| Sourcemaps | Web source maps are now opt-in with `TOOLCTRL_BUILD_SOURCEMAPS=1`, `SOURCEMAP=true`, or `BUILD_SOURCEMAPS=true`; CI quality builds set `TOOLCTRL_BUILD_SOURCEMAPS=1` before uploading the `web-client-sourcemaps` artifact for Sentry, while bundle-budget and local production builds skip map generation. API and worker esbuild sourcemaps are off by default because CI Sentry release jobs do not upload them and runtime Docker layers remove maps before final copy. | Keep web sourcemaps enabled only for the existing Sentry path. Enable API/worker maps only with `SOURCEMAP=true` or `BUILD_SOURCEMAPS=true` when debugging a backend release. | Default builds stay smaller and quieter; any future sourcemap warning is fixed, tracked upstream, or documented with the exact opt-in flag. |
| Lint | `pnpm run lint` is the active hard ESLint gate, not a config-level failure. | Keep lint hard with `--max-warnings=0`. | Lint remains a reliable code-quality signal. |
| Docker | `pnpm run verify:docker-baseline` and `pnpm run verify:docker-non-root` pass. | Keep Docker checks static and cheap by default; run runtime smoke gates when changing Dockerfile/start/runtime copy behavior. | Platform-specific warnings are captured with the exact Docker command if they reappear. |

## Verified Commands

```text
pnpm exec vitest run apps/web/app/utils/build/buildWarningTriage.test.ts scripts/build-web-server.test.mjs scripts/verify-production-seed-artifact.test.mjs scripts/verify-bundle-size.test.mjs
pnpm exec vitest run apps/web/app/modules/onboarding/services/OnboardingService.single-user-tenant-flow.test.ts apps/web/app/modules/onboarding/services/step-registry/gating.server.test.ts apps/web/app/services/dashboard-registry/dashboard-registry.test.ts
pnpm --filter @toolctrl/api build && pnpm --filter @toolctrl/worker build
pnpm run verify:production-seed-artifact
pnpm run verify:docker-baseline
pnpm run verify:docker-non-root
pnpm run build
pnpm run verify:bundle-size
```

## Bundle Baseline

`pnpm run verify:bundle-size` after the current build:

```text
root        755812 / 790964
initial_payload_js 755812 / 790964
vendor      1610165 / 1690674
route       2548448 / 2650000
other       1633849 / 1821650
manifest_js 668335 / 699563
total_js    6548274 / 6776505
css         735421 / 770317
empty_js_chunks unexpected=0
```

Largest JS chunks currently reported by the gate:

```text
manifest-*.js                         ~668335
vendor-charts-*.js                    ~442228
vendor-react-*.js                     ~319732
browserTracingIntegration-*.js        ~281322
vendor-editor-tiptap-*.js             ~278010
vendor-editor-prosemirror-*.js        ~216198
errorboundary-*.js                    ~166846
vendor-ai-sdk-*.js                    ~153261
vendor-workflow-*.js                  ~123534
otel.client-*.js                      ~116321
```

Completed optimization slices: split shell-only user display helpers from email validation; lazy-load chatbot, command palette dialog, onboarding session, and WYSIWYG editor surfaces; split read-only chatbot from interactive AI-SDK runtime; replace the AI tool JSON code block highlighter with a lightweight renderer; replace Streamdown in chat history with a lightweight safe Markdown renderer; remove the Streamdown dependency; split Tiptap/ProseMirror editor bundles; isolate React/core utility/vendor chart ownership; lazy-load analytics overview charts; and keep client observability behind lazy/runtime-gated entrypoints. `AppLayout`, `overview`, and `entry.client` remain small shell/route chunks instead of megabyte-scale default payloads.

Next useful optimization slice: reduce the manifest surface by trimming route inventory, revisit editor collaboration owners only when those optional feature surfaces move toward plugin extraction, and consider upgrading the initial-payload guard to a dependency-graph-aware or gzip-aware shell budget if the build starts emitting a stable manifest that distinguishes eager vendor chunks from lazy feature chunks.