Skip to content
Fera Docs

Search is only available in production builds. Try building and previewing the site to test it out locally.

The target platform set is never stated, native-qt appears once and vanishes, and "triads" is still the support vocabulary

Источник: dev/fera-research/docs/oc1/022-target-platform-set-never-stated-qt-ghost.md (read-only; сгенерировано scripts/sync-docs.mjs)

The target platform set is never stated, native-qt appears once and vanishes, and “triads” is still the support vocabulary

Section titled “The target platform set is never stated, native-qt appears once and vanishes, and “triads” is still the support vocabulary”
  • kind: problem
  • area: ui / modules
  • evidence:
    • No document states the target OS set. Verified by grep across the corpus: the phrase “three target OSes” occurs exactly once, in QA.md:163-164 (“the launcher replaces the core module on all three target OSes”) — and no other document says which three. ADR-023 (:918-925) generalises to “GTK, Qt, WinUI … macOS is merely the first example”; OQ.md:259 sets a priority order (“Windows first — our primary dev platform; then macOS, Linux”) which is not the same thing as a support commitment.
    • native-qt is a ghost. ADR.md:929-930 lists the Native axis as native-macos, native-linux-gtk, native-qt, native-winui, “…”. Everywhere else Qt disappears: TECHSPEC.md:36 — “native-macos / native-linux-gtk / native-winui”; TECHSPEC.md:280-282 — the same three; ADR.md:977-979 — macOS NSTextView, Windows WinUI3, Linux GTK GtkTextView via gtk4-rs; TECHSPEC.md:429 — notify-rust (Linux/DBus). So: is Linux GTK or Qt? Both? Was Qt an example that got dropped, or a commitment nobody made?
    • Per-OS modules are assumed by four ADRs and never enumerated. TECHSPEC.md:34-36 lists /style-macos/ /style-win/ /style-linux/ (Style as dylibs — superseded, per my finding 002) and /feature-macos/ /feature-win/ /feature-linux/; ADR.md:242-249 defines Engine/Style/Feature “per-OS” sets; ADR.md:983-985 puts macOS native scroll behaviors into the native surface “consistent with the 1:1 native-look goal”.
    • “Triads” is still the operative support vocabulary in the ADR. ADR.md:252-254 — “The ‘official triads’ per OS (one Engine + one Style + one Feature set) are the primarily tested/supported combinations; arbitrary user-mixed combinations are best-effort.” But OQ.md:320-322 (2026-10-02, author-confirmed): “‘triad’ is obsolete… The official per-OS combination is a quad: Engine + Native + Feature + Style-data.” The question inside OQ-012 (what the supported set is, and what “best-effort” means) is still open, and the ADR states as current policy a set that is both the wrong shape (3 not 4) and undefined in content.
    • The frozen benchmark scene assumes two accounts, which presumes a platform story too: OQ.md:151 — “1 main + 1 secondary (notifications merge)”.
    • Nothing in the corpus mentions refresh-rate variance, HiDPI/scaling, colour management, or input latency budgets — all of which are per-platform and all of which interact with the frame budgets (my finding 008) and with ADR-030’s single-pass hit-testing (ADR.md:1013-1016).
  • severity: mid

Суть / Substance

Section titled “Суть / Substance”

The UI architecture is built on per-OS axes, and per-OS axes require a support matrix — but the corpus has no such matrix, states one OS count only inside a QA gate, and carries a fourth toolkit (Qt) that exists in one line and nowhere else.

This is not pedantry, because the missing matrix is load-bearing for at least four things:

  1. What is tested. QA’s gates are per-platform in spirit: pixel-diff “scoped per Style module … per-OS aesthetic” (QA.md:102-104, ADR.md:294-295), Native-slot fallback per platform (QA.md:111-113), launcher replacement on “all three target OSes” (QA.md:163-164), IME per platform (QA.md:114-115). Without a stated set, “supported” is unfalsifiable and CI scope is undefined.
  2. What “best-effort” means, which OQ-012 still leaves open while ADR-009 asserts a triad policy. Bug triage needs a ground truth: is this user’s combination supported?
  3. Effort estimation for the Native axis. Each toolkit is a module with a window-ownership question (ADR.md:934-939): macOS embeds native views into our window; Linux/WinUI often invert it. Qt on top of GTK would be a second Linux module — a real cost line that appears in no document.
  4. The 1:1 fidelity goal (RFC.md §1) is per-OS; the corpus’s power and frame budgets (finding 008) assume one display model.

The Qt ghost is worth calling out specifically because it is the kind of detail that quietly multiplies: an implementer reading ADR-023’s Native list may build a Qt module; one reading ADR-028/TECHSPEC will not; and “one instance per toolkit” (ADR.md:923-925) suggests the author originally intended more than three.

Варианты решения (tradeoffs)

Section titled “Варианты решения (tradeoffs)”
  • (A) Declare the matrix explicitly: three OSes (Windows/macOS/Linux), one Native module per OS (GTK on Linux; no Qt), one Feature module per OS, one Engine, Style as data. Fix ADR-023’s list, and make OQ-012’s open half answerable against it. Cheap; forecloses Qt.
  • (B) Declare Qt in (four modules). Costs a second Linux integration and doubles the per-platform Native/Feature test matrix; buys a real option for non-GTK Linux (KDE users).
  • (C) Declare Windows-only for the first public release (matching OQ.md:259’s “Windows first — our primary dev platform”), with macOS and Linux as alpha/beta targets. Reduces the matrix during the phase where the architecture is least settled — and honestly contradicts “1:1 per-OS fidelity” as a v1 goal, so it needs an explicit scope decision (see my finding 011 on v1 scope).
  • (D) Leave it open. Reject: QA already assumes three.

Предлагаемое решение

Section titled “Предлагаемое решение”

(A), with (C) as the sequencing variant if the author wants fewer platforms during the architecture phase. Either way it must be written down once and referenced.

  1. One short table in TECHSPEC (or a new ADR if it is a commitment): OS | Native module | Feature module | Engine | Style data | status. Then: ADR-023:929-930 drops native-qt (or keeps it as a named non-goal), TECHSPEC.md:34-36/:280-282 is checked against it, and QA.md:163-164’s “all three target OSes” gets a pointer instead of being the only statement of the fact.
  2. Amend ADR-009’s triad sentence (:252-254) to quads and to point at OQ-012 for the actual support list — and answer OQ-012’s open half (the recommended shape is in my finding 014’s context: one quad per OS supported; cross-OS Feature mixing unsupported; Style data freely mixable because it is data, which is a nice consequence of ADR-029).
  3. Add the missing per-platform variables to the budget ADR (finding 008): display refresh rate, HiDPI scaling, and what happens when the window is occluded. A hard 24 fps chrome budget against a 30 Hz panel or a variable-refresh laptop display is currently unspecified territory.
  4. File one small OQ for Qt: keep GTK-only, or fund a second Linux Native module? The answer changes the Native axis cost estimate, so it should precede building the first one.