Make every supported Flect host feel native and lag-free

[robinbraemer]

Outcome

Make platform-native quality a hard release gate. Flect shares its agent, canonical workspace, history, capability, and recovery contracts across hosts, but every supported host must behave, render, and respond like first-party software for that platform.

A generic WebView shell, fake native controls, visible input lag, scroll hitching, mismatched appearance, or platform-inappropriate navigation blocks release.

Dependencies

Builds on #20, #22, #23, #32, #35, and #37. This issue owns the cross-platform interaction contract those slices must satisfy together.

Required behavior

• Keep agent/workspace/history/capability logic shared while routing window chrome, menus, focus, shortcuts, scrolling, selection, drag and drop, file surfaces, appearance, accessibility, safe areas, touch, haptics, and lifecycle behavior through platform adapters.
• Use host-native protected surfaces when a WebView implementation cannot match the platform's behavior, latency, accessibility, or visual integration.
• Make the browser behave like an excellent web application: real URLs/history, browser navigation, text selection, clipboard, context menus, zoom, responsive reflow, pointer/touch adaptation, and no fake desktop chrome.
• Make macOS honor title-bar/traffic-light safe regions, menus, standard shortcuts, window/full-screen/reopen/quit behavior, trackpad and inertial scrolling, text editing, open/save panels, context menus, system appearance, reduced motion/transparency, increased contrast, VoiceOver, and state restoration.
• Do not call iOS or Android supported until real-device tests prove native back, keyboard avoidance, safe areas, touch/gesture, scrolling, sheet/menu, haptic, share/open, lifecycle, and accessibility behavior.
• Follow light, dark, high-contrast/forced-color, reduced-motion, text-size, pointer, and input settings without reload or state loss.
• Preserve the running canvas, focus, scroll position, and application state while the agent, compiler, and history are active.
• Keep optional compilers, sandboxes, workers, and Wasm out of the initial shell path and load/dispose them on demand.
• Keep the opened product UI separate from Flect authoring activation as defined by Adopt an Astro activation shell with an on-demand Flect runtime #37.

Performance and bundle gates

• A view-only browser route loads no Flect authoring runtime as specified in Adopt an Astro activation shell with an on-demand Flect runtime #37.
• Initial protected-shell JavaScript is <= 200 KiB gzip and <= 600 KiB decoded; initial CSS is <= 25 KiB gzip.
• No compiler, package-manager, sandbox, QuickJS, Rifty, or esbuild Worker/Wasm artifact is requested before its capability is used.
• Cold browser LCP is < 1,000 ms on the Fast 4G / 4x CPU reference profile and < 2,500 ms on the Slow 4G / 4x CPU profile.
• Composer input and ordinary protected-shell interactions have p95 response < 50 ms and release-gated INP < 100 ms.
• Scrolling, selection, resizing, dragging, and direct manipulation stay within a 16.7 ms frame budget on the 60 Hz reference device and target 8.3 ms on supported 120 Hz paths.
• No ordinary interaction creates a main-thread task > 50 ms.
• Menus, sheets, popovers, focus changes, and navigation acknowledge input in the same frame.
• All startup, edit-loop, cancellation, and memory budgets in Make Flect feel instant with strict live-editing performance budgets #20 remain mandatory per host.

Current AXI baseline — 2026-08-10

Measured from a clean production build at f5503b0 with chrome-devtools-axi:

• initial app JS: 539,229 bytes transferred gzip / 1,888,091 bytes decoded;
• initial CSS: 4,429 bytes transferred / 16,849 bytes decoded;
• full dist: about 20 MiB raw, including 13.94 MiB esbuild Wasm and a 3.93 MiB worker;
• local cold FCP 140 ms, LCP 157 ms, CLS 0, used JS heap about 9.6 MiB;
• Fast 4G + 4x CPU: FCP 1,063 ms, LCP 1,146 ms, one 63 ms long task;
• Slow 4G + 4x CPU: FCP 4,351 ms, LCP 4,434 ms, one 57 ms long task, CLS 0.0048;
• a measured no-op shell click completed in 24 ms with about 1 ms handler processing;
• Lighthouse accessibility 96, with current contrast and accessible-name failures in role/model controls;
• the current CSS declares dark-only color scheme and does not follow a light system appearance.

The local empty shell is fast, but the initial bundle and throttled browser path do not meet this issue's release gates.

Acceptance criteria

• Production Chromium tests cover cold/warm load, Fast/Slow 4G, 4x CPU, keyboard, mouse, trackpad-equivalent wheel, touch, zoom, reflow, light/dark, forced colors, reduced motion, and 50 edit cycles.
• Packaged macOS tests run on clean supported hardware and cover launch/reopen, menu bar, shortcuts, window resize/full screen, drag and drop, open/save panels, scrolling, appearance, VoiceOver, failure recovery, and long-session memory.
• Real-host traces attach frame, event, long-task, layout-shift, network, bundle, and memory evidence to the release report.
• Visual review is performed at normal, compact, large-text, light, dark, and increased-contrast settings on every supported host.
• No release is accepted with visible hitching, blank-canvas flashes, avoidable full reloads, focus loss, scroll reset, fake platform chrome, clipped safe areas, foreign controls, or demo-viewport-only layout.
• Shared tests prove semantic parity without requiring pixel-identical browser and macOS shells.
• Unsupported platform behavior degrades explicitly and never silently falls back to a misleading imitation.

Non-goals

• Making every platform pixel-identical.
• Reimplementing an operating system design language inside CSS.
• Loading every future platform adapter or development tool at startup.
• Claiming mobile support from responsive browser screenshots alone.

[robinbraemer]

Pushed verification update — 2026-08-10

The final browser path uses four view-only requests with a 3,159 B gzip activation bootstrap and 1,094 B gzip initial CSS. Production interaction measurements are 241 ms cold / 219 ms warm activation, 5 ms composer p95, and 149 ms worst rebuild request. AXI Chrome observed no console errors or horizontal overflow.

The actual packaged macOS Accessibility tree now proves Edit/Window/Help menus, three native traffic-light controls, the 760 × 560 minimum window clamp, actionable first-run setup, editable/restored draft, hard sidecar-loss survival, and single-window ownership. Evidence: browser/native verification and packaged run. Clean-machine trackpad, spoken VoiceOver, and long-session hardware traces remain external.

[robinbraemer]

Status audit: external gate. The issue-specific implemented boundary and exact remaining external authority are recorded in the open-issue audit; implementation evidence is PR #38 and hosted run 31401481772. This issue carries status:external-gate and must remain open until its documented credential, hardware, review, publication, or repository-policy evidence exists.

[robinbraemer]

Final host audit 2026-08-11: Chrome AXI measured the view-only shell at three resources, cold LCP 78 ms, TTFB 1 ms, CLS 0.00, and first-activation INP 25 ms. Lighthouse passed Accessibility, Best Practices, SEO, and Agentic Browsing at 100. The isolated packaged AX gate again proved native menus, three window controls, 760 x 560 minimum, draft restoration, hard sidecar recovery, and one-window ownership. Closure still requires the issue-specific clean-hardware trackpad, VoiceOver, appearance, long-session, and real-host trace walkthrough.