Prevent protected-shell visibility regressions across all interaction states

[robinbraemer]

Parent epic: #40

Outcome

The protected Flect shell remains visibly usable, calm, and subordinate to the running interface in every supported state. Contrast, control affordance, overlay layering, drag affordance, focus, and appearance cannot regress unnoticed when colors, loading states, or host surfaces change.

Product-quality coverage

FQ-02.2, FQ-18.1–FQ-18.9, FQ-19.1–FQ-19.9, and FQ-20.2–FQ-20.5.

Dependencies

• Complete accessibility, reflow, and adaptive appearance gates #22 owns full accessibility and reflow gates.
• Make every supported Flect host feel native and lag-free #36 owns native host and window behavior.
• [Epic] Make the protected Flect shell immediately understandable and dependable #40 owns the protected-shell experience as a whole.

Required behavior

• Establish a protected-shell visual state matrix for composer, conversation sheet, settings sheet, recovery, history, selections, capability decisions, and native window interaction.
• Test default, hover, focus-visible, active, disabled, pending, error, success, unavailable, and restored states in supported light/dark and increased-contrast settings; every control has a readable label, boundary, and focus signal.
• Treat settings and conversation as overlay sheets over the foreground app, with deliberate scrim, hierarchy, dismissal, focus trapping/restoration, reflow, and keyboard behavior. The opened interface keeps its own visual identity.
• Keep Flect identity restrained and protected-shell-local; do not place product-brand chrome over the user’s application.
• Make desktop drag regions large enough to be discoverable and route native window movement through the host’s approved native drag boundary. Do not simulate window dragging in the web canvas.
• Add automated visual/semantic regression coverage that fails on contrast or state-affordance loss, plus targeted visual review for the matrix. Tests must exercise rendered behavior, not assert source strings.

Acceptance criteria

• The complete matrix is rendered and checked in production Chromium and packaged macOS where applicable, including settings open, conversation open, history/recovery open, agent activity, error, disabled/unavailable, and restored states.
• Every protected interactive control meets WCAG 2.2 AA contrast in every supported appearance and does not rely only on color for state.
• Keyboard focus enters and exits every overlay predictably, returns to the invoking control or canvas, and never becomes trapped behind the foreground app.
• The protected shell does not obscure required app interaction except while its explicit overlay is open; closing it restores the running interface without a reload or lost context.
• The macOS drag region is reliably reachable, excludes interactive controls, moves the native window, and does not change browser-host behavior.
• Screenshot diffs, accessibility checks, and a human visual pass gate changes to protected-shell tokens or states. At least one test reproduces each prior class of low-contrast/indistinguishable-control regression.
• 320 CSS px, 200% zoom, increased text, reduced motion, dark/light, forced colors where supported, and VoiceOver paths remain complete.

Constraints

• Maintain one semantic token system in DESIGN.md; no component-specific hard-coded color escape hatches.
• Native behavior stays behind Effect platform services and reviewed host adapters; React may render state but cannot own window lifecycle.
• User-generated UI cannot imitate, cover, or replace protected recovery, permission, or Flect overlay surfaces.

Non-goals

• Making user projects adopt Flect styling.
• Pixel-identical browser and macOS rendering.
• Replacing the native title bar with custom application branding.

Owning documentation

DESIGN.md, ARCHITECTURE.md for verified platform boundaries only, docs/product-quality.md, and dated visual/accessibility/native evidence under docs/verification/.