Track architecture and dependency modernization implementation

[mohidmakhdoomi]

Purpose

Track implementation of the staged recommendations from Architecture and Dependency Modernization, produced by #4 and merged in #5.

The research report is decision input, not a single implementation scope. Work should be delivered as bounded, sequential issues so regressions and lockfile changes remain attributable and reversible.

Delivery principles

• Establish validation and lifecycle safety before dependency migrations.
• Process lockfile-changing work sequentially to avoid conflicts and preserve bisectability.
• Reverify registry versions, support ranges, and advisories when each issue begins; the report reflects 2026-07-17.
• Never use --force or --legacy-peer-deps to conceal incompatibility.
• Preserve the client-only WebGL boundary and validate behavior, not merely install/build success.
• Review and roll back package.json and package-lock.json together.
• Regenerate and inspect the lockfile at every dependency stage.
• Explicitly disposition Next's known nested PostCSS residual instead of claiming that the direct PostCSS update eliminates it.

Ordered required path

Stage 0 — safe baseline

• Establish a reproducible Node 22 modernization baseline #7
• Harden FocusGraph lifecycle and remove blanket Three.js type suppression #8

Stage 1 — supported security and maintenance baseline

• Patch Next 15 and React to the supported security baseline #9
• Patch and reclassify CSS, build, and ESLint 9 dependencies #10

Stage 2 — 3D/WebGL unit

• Upgrade and behaviorally qualify the Three.js force-graph stack #11

Stage 3 — Active-LTS framework

• Migrate the application to Next 16 Active LTS #12

Stage 4 — language/lint qualification and type tightening

• Adopt TypeScript 6 and finalize the supported ESLint 9 flat config #13
• Experiment with a clean, supported ESLint 10 migration #14
• Remove skipLibCheck after 3D and TypeScript alignment #15

Optional or policy-gated Stage 5

These issues may conclude with an evidence-based defer decision where stated:

• Qualify Tailwind 4 and its browser baseline #16
• Upgrade and validate Vercel Analytics and Speed Insights #17
• Replace the geist package with Next's self-hosted Geist font #18

Deferred or conditional work without active implementation issues

Do not create implementation work yet for:

• TypeScript 7, until typescript-eslint supports it.
• React Compiler, until the imperative WebGL lifecycle is cleaned up and modernization is stable.
• Node 24 qualification, which should be a separate runtime decision after the Node 22 baseline.
• Replacing force-graph with React Three Fiber, unless Upgrade and behaviorally qualify the Three.js force-graph stack #11 fails product requirements.

Completion

This tracker is complete when the required supported-baseline work is merged, optional experiments have recorded decisions, final audits and UX checks are documented, and durable architecture/lesson updates have been made without copying volatile patch-version data into the hot documentation tier.