feat(compression-ui): unified compression config UI — per-engine pages + combos editor + menu + WS default-on

[diegosouzapw]

Unified Compression Config UI

Makes every compression engine configurable and activatable from the dashboard, so compression actually runs on normal calls — not just the WS visualization. Follow-up to #3848 (engines + 2 Studios).

Built via brainstorming → spec → implementation plan → subagent-driven TDD, then deployed to the VPS and validated end-to-end via Chrome. Planning docs live in docs/research/compression/ (git-ignored, not committed).

What ships (validated live on the VPS)

Per-engine config pages (rich layout: explainer + enable toggle + config form + live preview + 7-day analytics), one per technology — reusing the engines' own getConfigSchema():

• Headroom, Session-Dedup, CCR, LLMLingua (new pages). Caveman/RTK keep their existing bespoke pages.
• ✅ Validated: the Headroom page renders the full layout (toggle + prerequisite notice + config form with minRows + Salvar + Preview + analytics).

Activation model (no new schema) — enabling an engine on its page edits the default compression combo's pipeline (setEngineInDefaultCombo), inserting at the stackPriority-ordered position. The stacked pipeline runs that combo on real calls.

• ✅ Validated live: enabling Headroom turned [rtk,caveman] → [rtk,headroom,caveman] (sorted by stackPriority) with config {minRows:5} persisted; disabling removed it. The normalizePipeline allowlist fix lets the new engines survive the write→read round-trip.
• Single-engine activation works: the default-combo guard was pipeline.length > 1 (dropped a one-engine combo) → changed to >= 1.
• Prerequisite: the default combo only runs when the global compression mode resolves to stacked; the engine pages show a notice pointing to Compression Settings.

Unified compression menu group — flat list under "Compression Context": Settings · Caveman · RTK · Headroom · Session-Dedup · CCR · LLMLingua · Combos · Compression Studio + a Combo Studio item. ✅ Menu validated.

Compression Settings surfaced in the group (mounts the existing CompressionSettingsTab).

Live dashboard WebSocket default-ON (loopback-bound). DEFAULT_HOST stays 127.0.0.1; build/test never auto-start; LAN exposure remains opt-in via LIVE_WS_HOST=0.0.0.0 + LIVE_WS_ALLOWED_ORIGINS.

Backend

• GET /api/compression/engines — engine catalog + each getConfigSchema() (management-auth gated).
• POST /api/compression/preview — gains an engineId branch (single-engine stacked preview, async/fail-open).
• GET /api/context/analytics/engine?engineId=&days= — per-engine aggregation over the engine column (mirrors the existing byEngine query; no new column/migration).
• GET|PUT /api/context/combos/default — read default combo / toggle one engine.
• ✅ All three new routes return 200 with correct data on the VPS.

Deferred to a follow-up

Combos ordered-layer editor (Task 8/9) was reverted (a49b407ae). The redesigned CompressionCombosPageClient did not hydrate on the production build (useEffect never ran, React buttons inert). During validation the previous combos editor showed the same non-hydration symptom, which points to a pre-existing combos-page hydration issue (the Headroom page and the rest of the dashboard hydrate fine) rather than a regression introduced here. The revert keeps the combos page at parity with production (the old editor degrades gracefully) and removes the now-unused pipeline reducer. The ordered-layer redesign — plus root-causing the combos hydration with a local npm run dev session (production suppresses hydration error detail) — returns in a dedicated follow-up.

Bugs found + fixed during live validation

• i18n freeze (6a4b33c3a): the Header strict-resolves each sidebar item's i18nKey; the new menu items had no message key, so a missing-message error froze hydration on every new page. Added the 7 keys across all 42 locales. Verified the pages load after.
• Slow initial load (587928544): EngineConfigPage's three reads were sequential (~6-9s on the VPS) → parallelized with Promise.all.
• Post-review fixes (9f4abc482): Hard Rule fix(ui): fix Select dropdown dark theme inconsistency #12 sanitized preview error · single-engine guard · engines-route auth + error body · handleSave no longer force-enables a disabled engine · engineId allowlist validation · ENVIRONMENT.md default corrected.

Tests & gates

• New tests: node:test (routes, db, WS, sidebar) + vitest render (createRoot+act). typecheck:core 0 · check:cycles 0 · check:any-budget PASS · ESLint 0 errors on changed files · test:vitest (MCP) 171/171.
• CI docs-sync is red branch-wide on pre-existing stale i18n CHANGELOG translations (refreshed at release time) — unrelated to this PR.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[gemini-code-assist]

Code Review

This pull request introduces per-engine configuration pages and analytics for compression engines (CCR, Headroom, LLMLingua, and Session Dedup), along with supporting API endpoints, database functions, and comprehensive tests. Feedback on the changes highlights a potential usability issue where users could lose configuration changes if they click save while an engine is disabled, and suggests disabling the save button in this state. Additionally, the API should distinguish between an invalid engine ID (400) and a missing default combo (404). Finally, inline Zod schemas in the route files should be moved to src/shared/validation/schemas.ts to comply with the repository style guide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Since the database only stores configuration for engines that are active in the pipeline (via compression_combos), saving the configuration while the engine is disabled (enabled === false) will result in the configuration being silently discarded on the backend.

To prevent users from losing their configuration changes, we should disable the Salvar button when the engine is not enabled, or prompt them to enable the engine first.

Here is a suggestion to disable the button and add a descriptive tooltip when the engine is disabled:

Suggested change

	<button
	onClick={handleSave}
	disabled={saving}
	className="px-4 py-1.5 rounded bg-primary text-primary-foreground text-sm font-medium disabled:opacity-50"
	>
	{saving ? "Salvando…" : "Salvar"}
	</button>
	<button
	onClick={handleSave}
	disabled={saving || !enabled}
	className="px-4 py-1.5 rounded bg-primary text-primary-foreground text-sm font-medium disabled:opacity-50"
	title={!enabled ? "Ative a camada para salvar a configuração" : undefined}
	>
	{saving ? "Salvando…" : "Salvar"}
	</button>

[gemini-code-assist]

The setEngineInDefaultCombo function returns null if either the engineId is invalid (not in KNOWN_ENGINE_IDS) or if the default compression combo is not found in the database.

Currently, if an invalid engineId is provided, the API misleadingly responds with a 404 status and the message "No default compression combo found".

We should distinguish between these two cases so that an invalid engine ID correctly returns a 400 Bad Request error.

  const combo = setEngineInDefaultCombo(engineId, enabled, config);
  if (!combo) {
    if (!getDefaultCompressionCombo()) {
      return NextResponse.json({ error: "No default compression combo found" }, { status: 404 });
    }
    return NextResponse.json({ error: "Invalid engine ID" }, { status: 400 });
  }
  return NextResponse.json(combo);

[gemini-code-assist]

According to the repository style guide, all input validation Zod schemas should be defined in src/shared/validation/schemas.ts rather than inline in the route files. Please move engineToggleSchema to src/shared/validation/schemas.ts and import it here.

References

1. Always validate inputs with Zod schemas from src/shared/validation/schemas.ts ^(link)

[gemini-code-assist]

According to the repository style guide, all input validation Zod schemas should be defined in src/shared/validation/schemas.ts rather than inline in the route files. Please move PreviewRequestSchema to src/shared/validation/schemas.ts and import it here.

References

1. Always validate inputs with Zod schemas from src/shared/validation/schemas.ts ^(link)