Status: Adopted as the binding strategic architecture via ADR-0021 (merged, PR #406). Wave 0
(both the decision and its CEF source/CI retirement execution) is complete β see Β§15 below for the
full per-wave status.
Repository: qnbs/WorldScript-Studio
Roadmap generation date: 2026-08-20
Supersedes: the CEF-first desktop migration strategy and all CEF-dependent execution sequencing
(ADR-0019, ADR-0020 β see docs/historical/cef/README.md)
Transitional desktop runtime: Tauri 2 / system WebView, retained only as a reference/fallback
until Qt admission and cutover gates are satisfied, and itself retired once Qt reaches Stable
Transitional maintenance policy: TAURI-TRANSITIONAL-MAINTENANCE.md defines the TM-0..TM-3 support boundary, #332 evidence rules, and retirement conditions.
Primary native desktop line: Qt 6 / Qt Quick (QML) β Hardened / Accessible / Long-Lived Edition
Deferred native exploration: GPUI β Vision / High-Performance Edition (not a numbered execution commitment)
Web line: React + Vite PWA, retained as a first-class product surface and behavioral reference
Authoritative product core: Rust
Architecture rule: no domain/business logic duplication across renderers
Revision: 2 β early killer-gate sequencing and GPUI exploration boundary
Revision date: 2026-08-21
Amended by Revision 3: DESKTOP-MIGRATION-ROADMAP-REV3.md is a binding amendment to this roadmap β it adds gates G1.5 and G2.5 and Wave 2.5, and must be read together with this document, not as an optional standalone note.
This document is adopted verbatim from the strategic roadmap supplied at reset time, with two corrections applied so it accurately reflects current repository state rather than the assumptions it was drafted against:
- Wave 1 (
DesktopPlatformboundary hardening) is not future work β it is already complete onmain.packages/desktop-contracts(14-facetDesktopPlatforminterface, Tauri/Web adapters),services/desktopPlatform.ts, and the zero-tolerancescripts/check-tauri-import-boundary.mjsguardrail (wired into.github/workflows/ci.yml,pnpm run guardrail:desktop-imports) all shipped via PR #384 and PR #385. See the Wave 1 entry below for the corrected status marker, anddocs/architecture/native-readiness.mdfor the live scorecard. - The R-15 desktop at-rest-encryption deliverable (Β§9) has a concrete, already-tracked reference
design and gap list to build from, not an abstract future risk β but correcting an overstatement
from this document's first draft: desktop fs-backed project data (
project.json, snapshots, Codex, images, RAG vectors) has no encryption at all today onmain(services/fs/fsCore.ts#encryptText/decryptTextexist but are dead code β zero call sites outside their own unit tests); desktop API-key fs storage is disabled outright (FsSettingsStore#saveApiKeythrows"...use storageService instead"). GitHub issues #357 (atomic writes need fsync of temp file + parent directory), #359 (fs-data key-rotation migration not crash-resumable), #360 (fs reads/writes don't participate in the encryption-migration admission lock), and #361 (fs ciphertext has no AAD/identity binding, enabling cross-file substitution) describe gaps in a closed, unmerged reference design (fix/desktop-project-data-encryption, PR #356, closed 2026-08-18 as superseded, explicitly meant to be rebuilt from scratch on the Rust Core) β not a live production path. All four issues remain open and are real, valid inputs to the Wave 3β4 crypto design; only the "this exists today with bugs" framing was wrong. Issue #332 (a live, user-reported Tauri.debsluggishness report) remains open as the historical/ongoing performance baseline referenced throughout this document.
The baseline below remains the adopted roadmap record; the sequencing reconciliation in this revision is recorded explicitly before the detailed sections it changes.
The three cheapest Qt feasibility risks β lifecycle/bridge, accessibility/input, and
crash/recovery β are now explicit early lanes before formal Wave 4.5. Wave 4.5 retains the
packaging, security, and admission work that depends on later Core semantics. Wave 5 is reduced to
the reusable harness and its remaining file-dialog/clipboard proof. GPUI Waves 21β24 are removed
from the numbered execution roadmap and preserved in docs/native/GPUI-EXPLORATIONS.md as a
deferred, separately gated exploration. This does not change the Core-first Wave-2 priority or
authorize production Qt UI before G2.
Decision summary: WorldScript Studio will not continue the CEF desktop-runtime program. The product will instead mature into a renderer-independent Rust platform with two native desktop surfaces: Qt as the first production-native, hardened reference desktop and GPUI as the performance-oriented second native product line. The React/PWA remains first-class. Tauri remains transitional only until Qt has proven replacement parity, and is itself retired once that parity is proven β it is not a permanent third runtime. CEF-specific source, build, runtime, packaging and operational requirements are removed from the target architecture.
WorldScript Studio adopts a Core First β Qt Stable strategy, with GPUI retained as a separately gated exploration rather than a concurrent execution commitment.
The previous CEF-first path is retired as an implementation target. Work already completed during the CEF investigation is not discarded blindly: renderer-neutral contracts, lifecycle lessons, process diagnostics, CI improvements, storage/security findings, accessibility evidence, native-readiness work and platform-boundary improvements are retained when they are independently useful. CEF-specific host code, SDK acquisition, Chromium subprocess assumptions, Crashpad-specific integration, CEF packaging and CEF-only operational complexity are not carried forward as product requirements.
The binding strategic order becomes:
CURRENT
React + Vite + Tauri 2
β
βΌ
Renderer-neutral platform boundary
β
βΌ
Rust-authoritative Core
Storage / Crypto / Migration / Tasks / AI / Diagnostics
β
βΌ
Qt early killer-gate qualification
β
βΌ
Qt architecture + executable learning harness
β
βΌ
Qt vertical slices
β
βΌ
Qt packaged beta
β
βΌ
Qt parity / security / accessibility / performance / recovery
β
βΌ
Qt Stable
β
βΌ
Tauri retirement review
β
ββββββββββββββββββββββββββββββββββββββββββββ
β β
βΌ βΌ
Web/PWA continues GPUI exploration record
(separate admission decision)
The end state is deliberately multi-renderer:
WORLD SCRIPT PLATFORM
β
βββββββββββββββββββββ΄ββββββββββββββββββββ
β β
WorldScript Core Shared Contracts
(pure Rust) typed commands/events/schemas
β β
βββββββββββββββββββββ¬ββββββββββββββββββββ
β
βββββββββββββββββΌββββββββββββββββ
β β β
βΌ βΌ βΌ
Web / PWA Qt Native GPUI Native
React/Vite QML/Qt Quick Rust/GPUI
The three surfaces are products, not three implementations of the domain.
WorldScript Studio should become a renderer-independent writing platform rather than an application whose product semantics are entangled with a particular UI runtime.
The durable investment is therefore not Qt, GPUI, React or any windowing toolkit. It is:
- the project format;
- the domain model;
- persistence;
- encryption;
- migration;
- recovery;
- AI orchestration;
- task supervision;
- collaboration semantics;
- diagnostics;
- update policy;
- typed contracts;
- deterministic state transitions;
- testable product behavior.
Renderers consume those capabilities.
The architectural target is:
WORLD SCRIPT PLATFORM
β
βββββββββββββββββββββββ΄ββββββββββββββββββββββ
β β
Authoritative Rust Core Versioned Contracts
β β
βββββββββΌβββββββββ¬ββββββββββ¬βββββββββ β
β β β β β β
Storage Crypto Projects AI Tasks/Diag β
β β β β β β
βββββββββ΄βββββββββ΄ββββββββββ΄βββββββββ΄βββββββββββββββββ
β
βββββββββββββββββββΌββββββββββββββββββ
β β β
React/PWA Qt 6 GPUI
browser native native
The defining invariant is:
A renderer may own presentation. It may not own product truth.
Qt is selected as the first native desktop target because WorldScript needs a mature toolkit for a demanding writing application with:
- complex text input;
- IME;
- BiDi/RTL;
- accessibility;
- high-DPI;
- printing;
- native menus and dialogs;
- clipboard and drag/drop;
- cross-platform windowing;
- mature localization;
- long-lived desktop deployments;
- extensive profiling/debugging facilities;
- native rendering without requiring a browser engine for the principal UI.
The preferred presentation technology is Qt 6 + Qt Quick/QML, with a deliberately thin C++ integration layer where Qt's native API requires it and the authoritative application/domain implementation remaining in Rust.
Qt Widgets are allowed for narrowly justified platform integrations or controls where they are materially superior, but the default product UI architecture is Qt Quick/QML to avoid two competing Qt presentation systems.
Qt WebEngine is not part of the default architecture. It may only be admitted for a narrowly isolated capability after a separate architecture/security/license review. Reintroducing a Chromium-backed primary application surface through Qt WebEngine would defeat the purpose of this reset.
GPUI remains a candidate high-performance Rust-native track because it aligns strongly with:
- Rust ownership;
- GPU-accelerated UI;
- editor-centric interaction;
- low-latency rendering;
- large virtualized surfaces;
- native state/entity models;
- direct reuse of the Rust core without a C++/QML boundary.
However, GPUI remains an actively evolving, pre-1.0 framework, and the first native product has not
yet completed a Qt wave. GPUI therefore has no numbered implementation commitment at this stage;
its proof targets and re-entry conditions live in docs/native/GPUI-EXPLORATIONS.md.
It cannot become a production desktop line until a separate admission decision is made after Qt
evidence exists.
The project must not assume a stable ReactβGPUI binding ecosystem. React reuse means, in descending order of reliability:
- reuse of domain behavior through the shared Rust core;
- reuse of schemas/contracts;
- reuse of design tokens, icons and assets;
- reuse of behavioral/interaction specifications and Golden Master scenarios;
- optional generated bindings or adapter layers where proven;
- direct React component reuse only if a maintained, production-quality mechanism is independently demonstrated.
No roadmap milestone may depend on an unproven "React bindings" assumption.
The PWA is not merely a temporary artifact. It remains:
- the web product;
- a Chromium/browser behavioral comparator;
- a rapid UI experimentation surface;
- an accessibility and i18n reference;
- a contract consumer;
- a regression oracle for domain behavior where appropriate.
The PWA must consume the same versioned product contracts wherever practical.
Any capability that materially affects project truth must be implementable and testable without Qt, GPUI, React, DOM or Tauri.
Examples:
- save;
- load;
- project validation;
- migration;
- encryption;
- snapshots;
- recovery;
- AI request orchestration;
- task cancellation;
- model metadata;
- export transforms;
- collaboration state;
- diagnostics state.
Qt is the only current native production target. GPUI implementation does not race Qt to parity.
Before Qt Stable, GPUI work is limited to:
- architecture documentation;
- dependency and license evaluation;
- small disposable spikes;
- performance experiments;
- text/input/accessibility feasibility;
- contract compatibility checks.
No GPUI feature-parity program begins unless the separate GPUI exploration record is re-admitted as an execution plan after Qt evidence and a signed GPUI Admission Gate decision.
Forbidden:
if renderer == Qt:
save differently
if renderer == GPUI:
migration behaves differently
Allowed:
renderer asks Core to SaveProject(command)
Core validates and persists
renderer presents result
Existing DesktopPlatform work is retained and generalized β and already exists:
packages/desktop-contracts (PR #384/#385) already defines a 14-facet renderer-neutral capability
interface with TauriDesktopPlatform and WebDesktopPlatform adapters, enforced by
scripts/check-tauri-import-boundary.mjs in CI.
The boundary must evolve from "hide Tauri" into "define product capabilities independent of
renderer" β which is exactly what the existing interface already does; a future Qt or GPUI adapter
implements the same DesktopPlatform interface without touching call sites.
During transition:
React/Tauri adapter ββ
Qt adapter ----------βΌβ Shared capability contracts β Rust Core
GPUI adapter --------β
Direct @tauri-apps/* imports remain confined to approved Tauri adapter locations, mechanically
enforced.
Qt and GPUI APIs must not leak into shared/domain code.
No renderer migration may weaken:
- atomic saves;
- append semantics;
- backups;
- recovery;
- migration;
- encryption;
- corruption detection;
- rollback;
- project compatibility.
QtβRust and any process boundary must use:
- named operations;
- typed inputs/outputs;
- validation;
- explicit ownership;
- size limits;
- cancellation where relevant;
- bounded queues/backpressure;
- structured errors;
- auditability;
- no arbitrary command execution.
Qt and GPUI may have different UI philosophies.
Parity is defined by user outcomes:
- create/open project;
- write/edit;
- autosave;
- undo/redo;
- plot;
- character/world management;
- AI assist;
- import/export;
- backup/recovery;
- settings;
- diagnostics;
- accessibility;
- update.
Tauri remains:
- current production/reference runtime;
- fallback while Qt lacks parity;
- regression comparator;
- emergency support path.
Do not build large new Tauri-only architecture. Tauri is retired (roadmap Wave 20, gate G5) once Qt reaches Stable (G4) plus a field-observation window β it is not a permanent third runtime alongside Qt and GPUI.
After the reset reconciliation:
- no CEF SDK fetch in required CI;
- no CEF host in product packaging;
- no CEF-specific runtime dependency;
- no Crashpad/Chromium fork obligation;
- no CEF wave may gate Qt/GPUI;
- historical CEF research may remain archived as engineering evidence
(
docs/historical/cef/README.md).
Profile: ubiquitous, browser-native, rapidly deployable.
Responsibilities:
- browser product;
- web collaboration;
- rapid experimentation;
- browser accessibility;
- compatibility reference;
- contract conformance.
Profile: robustness, accessibility, security, enterprise readiness, predictable support.
Priorities:
- data integrity;
- accessibility;
- IME/BiDi/text correctness;
- security;
- recovery;
- packaging/updater;
- predictable performance;
- long-term maintainability.
Profile: low latency, GPU-native interaction, large-document responsiveness, Rust-native architecture.
Priorities:
- editor latency;
- frame consistency;
- memory efficiency;
- large virtualized views;
- native Rust integration;
- high-performance graph/board interactions;
- eventual parity after framework maturity.
Create or converge toward workspace crates with responsibilities similar to:
crates/
worldscript-core/
worldscript-project/
worldscript-storage/
worldscript-crypto/
worldscript-migrations/
worldscript-tasks/
worldscript-ai/
worldscript-diagnostics/
worldscript-contracts/
worldscript-update/
worldscript-collaboration/
Exact names follow repository reality; do not perform cosmetic restructuring without benefit. Note:
apps/desktop-cef/rust-core/ (removed in Wave 0) was a 22-line FFI-boundary proof with no domain
logic and does not seed this work β the new Core starts from a fresh capability inventory of existing
TypeScript domain logic, primarily against src-tauri/'s ~1,610 lines of real production Rust as the
comparison baseline.
Preferred model:
QML / Qt Quick
β
βΌ
thin Qt-facing C++ faΓ§ade
β
βΌ
stable Rust FFI boundary
β
βΌ
WorldScript Rust Core
Alternative bridges (cxx, generated C ABI, qmetaobject-style approaches, cxx-qt or equivalent)
require an explicit scorecard. Selection criteria:
- Qt 6 support;
- QML property/signal integration;
- async support;
- ownership clarity;
- thread-affinity correctness;
- error mapping;
- build reproducibility;
- Windows/macOS/Linux support;
- maintenance health;
- unsafe surface;
- generated-code inspectability;
- license;
- upgrade burden.
Do not choose the bridge because a prototype compiles.
Preferred:
GPUI presentation/state entities
β
βΌ
worldscript-contracts
β
βΌ
WorldScript Rust Core
No FFI should be required for ordinary Core consumption.
Third-party GPUI component libraries may accelerate controls, docking, tables and text prototypes, but each must pass:
- license review;
- accessibility review;
- IME review;
- platform review;
- API stability review;
- dependency/supply-chain review;
- performance verification.
Every domain capability receives a scorecard:
[ ] no DOM dependency
[ ] no React lifecycle dependency
[ ] no Tauri API dependency
[ ] no Qt dependency
[ ] no GPUI dependency
[ ] deterministic inputs/outputs
[ ] typed errors
[ ] cancellation semantics defined
[ ] persistence semantics defined
[ ] security classification defined
[ ] headless tests exist
[ ] large-input behavior tested
[ ] migration/versioning impact known
[ ] telemetry/diagnostics policy known
A capability failing the scorecard is not renderer-ready. The existing docs/architecture/native-readiness.md
is the live scorecard document for this repository β extend it, do not fork a duplicate.
Accessibility is a release property, not a renderer feature.
- WCAG 2.2 AA target for applicable workflows;
- complete keyboard operation;
- focus visibility;
- logical focus order;
- screen-reader semantics;
- high contrast;
- reduced motion;
- scalable text;
- zoom;
- IME;
- RTL/BiDi;
- no color-only state;
- accessible errors and notifications.
Qt Quick accessibility semantics must be explicit for custom controls. Automated smoke tests must be supplemented by real AT validation on supported platforms.
Required platform matrix eventually includes:
- Windows UI Automation;
- macOS accessibility APIs / VoiceOver;
- Linux AT-SPI / Orca where supported.
Accessibility is an explicit admission risk. GPUI must not be promoted to production parity until its accessibility behavior is proven for WorldScript's actual editor and complex controls.
A fast renderer that cannot satisfy required assistive-technology workflows is not production-ready.
The desktop reset must strengthen, not postpone, security.
R-15 becomes a cross-renderer Core requirement.
Encryption must not be implemented separately in Qt and GPUI.
Required properties:
- authenticated encryption;
- versioned envelope format;
- key lifecycle;
- key derivation/storage strategy;
- atomic encrypted writes;
- corruption/tamper detection;
- migration from existing desktop data;
- backup compatibility;
- recovery behavior;
- no plaintext temporary-file leakage where avoidable;
- secure deletion claims avoided unless actually supportable;
- tests for interruption and partial writes.
Concrete open gaps this must close (see Document status note above): issues #357, #359, #360, and #361
are all open, describing gaps in the closed/unmerged reference design (PR #356), not a live path.
Desktop fs-backed project data has no encryption at all on main today; this deliverable is a
from-scratch build informed by that reference design and by the mature, "Accepted and implemented"
IDB-side scheme (ADR-0018), not a bug-fix pass on existing production encryption.
The exact current repository state must be reconciled before implementation. Their security/data- integrity invariants are treated as non-regression requirements, not as closed-history trivia.
A migration PR must explicitly answer:
Does this change affect any invariant established by #359/#360/#361?
YES / NO
Evidence:
Current status (2026-08-20): all three issues are open on GitHub, each documenting a real gap
(crash-resumability, admission-lock participation, AAD/identity binding respectively) in the closed,
unmerged reference design (PR #356) β not in a live production path, since desktop fs-backed
encryption does not exist on main today. None are fixed by Wave 0 β they remain concrete inputs to
the future Core storage/crypto design.
Issue #332 remains a performance/stability evidence source.
The Qt migration must not merely declare the WebKitGTK symptom irrelevant. It should preserve the useful lessons:
- long-session memory behavior;
- large-project behavior;
- animation/transparency cost;
- serialization amplification;
- autosave/snapshot amplification;
- process/resource diagnostics.
Qt and GPUI receive their own #332-equivalent performance proofs.
Current status (2026-08-20): Issue #332 is open on GitHub β a live, user-reported Tauri .deb
sluggishness report on high-end hardware, not yet root-caused by a maintainer. It stays open and
untouched by Wave 0; it is cited here as the ongoing performance baseline any native renderer must
not regress relative to.
Performance is measured against workflows, not framework marketing.
Baseline dimensions:
- cold start;
- warm start;
- project open;
- 1 MB / 10 MB / large-real-world manuscript;
- typing latency;
- cursor latency;
- selection;
- scroll;
- search;
- autosave;
- snapshot;
- AI streaming;
- board interaction;
- graph interaction;
- idle CPU;
- idle RAM;
- 30-minute session;
- 6-hour soak;
- repeated open/close;
- suspend/resume;
- GPU loss/recovery where relevant.
Qt targets:
No visible input jank in normal manuscript editing
P95 interaction latency explicitly budgeted
Idle CPU near quiescent
Memory growth bounded during soak
No unbounded scenegraph/resource accumulation
GPUI aspirational target:
120 Hz-capable editor path where hardware/display support it
frame budget < 8.33 ms for designated interactions
The 120 fps target is a performance objective, not a release claim until measured on defined hardware.
Fast Rust unit/property tests.
Every renderer adapter must pass the same capability contract suite.
Qt and GPUI-specific tests.
Tests run against the actual packaged application.
Long-running real-world validation.
Golden Masters should capture behavior and data, not brittle pixels by default.
Examples:
- project after migration;
- command result;
- export output;
- recovery state;
- event sequence;
- accessibility tree expectations where stable.
Visual regression remains useful for selected UI surfaces.
Use change-aware CI.
FAST GATE
β
βββββββββββΌββββββββββ
β β β
Core Web Native
React β
ββββββ΄βββββ
β β
Qt GPUI
Required principles:
- path-aware heavy jobs;
- concurrency cancellation for obsolete PR runs;
- Rust cache;
- Qt dependency cache where licensing permits;
- CMake/Ninja cache;
- cargo/sccache where useful;
- artifact reuse;
- packaged E2E on relevant changes;
- nightly heavy matrices;
- release-candidate full matrices.
No docs-only change should rebuild every native target without a concrete reason. No Qt/GPUI CI is
added until real Qt/GPUI code exists β the retired cef-learning-harness.yml is not replaced by a
placeholder.
Core/contracts have highest architectural authority.
Qt team owns presentation, native integration and Qt packaging, not domain semantics.
GPUI team owns presentation/performance integration, not domain semantics.
A breaking contract change requires:
- Core impact;
- Web impact;
- Qt impact;
- GPUI impact once admitted;
- migration plan;
- compatibility window.
After multiple renderers are production-active, a new cross-product domain capability is not fully "done" until:
- Core implementation exists;
- headless tests pass;
- contracts are versioned;
- all currently supported required renderers have an implementation or an explicitly approved capability exception.
This does not mean every experimental GPUI surface must block Qt releases.
- QObject ownership;
- QML engine;
- Qt Quick scene graph;
- render thread;
- signals/slots;
- queued connections;
- thread affinity;
- model/view;
- text stack;
- IME;
- accessibility;
- platform packaging;
- signing;
- deployment;
- updater integration;
- crash diagnostics;
- QML profiling.
- Application/Window lifecycle;
- entity ownership;
- retained/immediate hybrid model;
- async execution;
- text shaping/editing;
- focus/keymaps;
- accessibility;
- GPU resource lifecycle;
- platform support;
- framework upgrade/rebase discipline.
Required knowledge artifacts:
docs/native/
ROADMAP-QT-GPUI-DESKTOP.md (this document)
UI-DOMAIN-STATE-CLASSIFICATION.md (relocated from docs/cef/, Wave 0)
NATIVE-RISK-REGISTER.md (created when Wave 3+ begins)
OWNERSHIP.yaml (created when Wave 3+ begins)
qt/
architecture-primer.md
rust-bridge-decision.md
threading-and-lifetimes.md
accessibility-playbook.md
packaging-and-updates.md
debugging-and-crash-playbook.md
upgrade-playbook.md
gpui/
architecture-primer.md
dependency-policy.md
text-editor-feasibility.md
accessibility-playbook.md
performance-playbook.md
upgrade-playbook.md
Status: COMPLETE. PR A (#406) and PR B (#407) both merged.
Required:
[x] new ADR (ADR-0021) supersedes CEF production strategy β merged (PR A, #406)
[x] CEF PR/issue reconciled: PR #404 closed unmerged, Issue #405 closed as superseded β done
[x] no useful renderer-neutral work lost β DesktopPlatform boundary unaffected (already true,
independent of this reset); UI-DOMAIN-STATE-CLASSIFICATION.md relocated (PR B, #407)
[x] CEF-only CI removed (cef-learning-harness.yml, advisory-only) β removed (PR B, #407)
[x] CEF-only dependencies no longer required by product build (apps/desktop-cef/, scripts/cef/
removed, PR B #407)
[x] Tauri remains functional during transition β true throughout, unaffected by either PR
[x] Qt/GPUI roadmap adopted (this document) β merged (PR A, #406)
[x] DesktopPlatform capability inventory complete (packages/desktop-contracts)
[x] direct Tauri imports constrained (guardrail:desktop-imports, zero-tolerance)
[~] project headless API exists β crates/worldscript-project (schema/validation/migration/plain I/O);
storage (fs/IDB parity) and crypto remain, see docs/native/CORE-MIGRATION-LEDGER.md
[x] ArrayβEntityState compatibility adapter scoped and proven at the Core boundary; first observation-only desktop shadow caller wired (ledger row 9; authority switch remains deferred)
[ ] R-15 architecture approved
[~] task supervision renderer-neutral β bounded `text.analyze`/`text.diff` proof is CI-proven;
full worker-bus extraction and authority switch remain open
[~] diagnostics renderer-neutral β Core model/redaction and TS/Rust parity are CI-proven;
recursive redaction and typed TS sink boundary are locally proven in #441 and CI merge-gated;
sink migration and authority switch remain open
[x] contract versioning policy established β bounded TaskSupervisor request/result contract v1.0.0 is validated at the typed boundary; see docs/native/CONTRACT-VERSIONING-POLICY.md
[x] native-readiness CI gate active β enforced by `pnpm run native-readiness:check`
[ ] Qt license strategy approved
[ ] Qt version/LTS strategy approved
[ ] bridge technology confirmed by scorecard, informed by Wave 4.5 evidence
[ ] Wave 4.5 Qt Early Killer-Gate qualification accepted β see `docs/native/QT-EARLY-KILLER-GATES.md`
[ ] disposable pre-G2 Qt qualification probe and Wave 4.5 evidence accepted
[ ] IME feasibility passes
[ ] accessibility feasibility passes
[ ] packaged hello-world/native-core roundtrip passes
[ ] updater/packaging design approved
[ ] core writing workflows present
[ ] project compatibility proven
[ ] R-15 implemented for desktop
[ ] recovery proven
[ ] packaged update/rollback proven
[ ] accessibility gate passes
[ ] performance SLOs pass
[ ] no Critical/High unresolved security findings
[ ] feature parity matrix accepted
[ ] long-session soak passes
[ ] large-project tests pass
[ ] installer/signing/notarization proven
[ ] rollback proven
[ ] crash diagnostics proven
[ ] support playbooks complete
[ ] migration from Tauri proven
[ ] GO decision record signed
Only after Qt Stable and an explicit rollback window. Tauri is removed entirely at this gate β not kept as a permanent parallel runtime.
[ ] GPUI platform support meets target matrix
[ ] framework pin/update policy exists
[ ] accessibility feasibility proven
[ ] IME/BiDi proven
[ ] editor spike beats or materially matches Qt on target workloads
[ ] no dependency on speculative React bindings
[ ] packaging/update feasibility proven
[ ] maintenance/bus-factor acceptable
Core workflows + performance + accessibility + data compatibility.
Qt and GPUI both supported against one Core/project format. Tauri is no longer part of the architecture at this point β the end state is Web/PWA + Qt + GPUI only.
The roadmap intentionally preserves the original program's small, reviewable, reversible wave
discipline while replacing CEF-specific work with Qt-first milestones. GPUI is deliberately not
counted as a numbered execution commitment; its retained proof targets live in the separate
docs/native/GPUI-EXPLORATIONS.md record.
Status: COMPLETE β CI-PROVEN. Wave 0 executed as two PRs. PR A (#406: ADR-0021,
ADR-0019/0020 supersession, ROADMAP.md/README.md pointer updates) established the strategic
reset. Issue #405 and companion PR #404 are closed (#404 unmerged, superseded; #405 as
no-longer-applicable, not "fixed"). PR B (#407: removal of apps/desktop-cef/, scripts/cef/,
.github/workflows/cef-learning-harness.yml, and 14 of 15 docs/cef/ files; relocation of
docs/cef/UI-DOMAIN-STATE-CLASSIFICATION.md to docs/native/; this doc-sync) performed the actual
CEF source/CI/docs retirement. Both PRs merged, main CI green.
Goal: change direction without losing valid work.
Actions:
- write superseding ADR;
- mark CEF strategy historical/superseded;
- inventory every open CEF PR and branch;
- classify each change:
- renderer-neutral retain;
- Qt/GPUI-reusable retain;
- diagnostic archive;
- CEF-only drop;
- remove CEF from future architecture diagrams;
- preserve research logs where useful;
- ensure main remains green.
Exit:
CEF no longer a target runtime.
No valuable Core/security/CI improvement is accidentally discarded.
Status: COMPLETE β CI-PROVEN. Shipped via PR #384 (refactor(desktop): introduce renderer- neutral platform contracts) and PR #385 (refactor(desktop): route Tauri consumers through the DesktopPlatform adapter), both merged to main before Wave 0 began. packages/desktop-contracts
defines the 14-facet DesktopPlatform interface with TauriDesktopPlatform/WebDesktopPlatform
adapters; services/desktopPlatform.ts is the runtime selector; scripts/check-tauri-import-boundary.mjs
is a zero-tolerance CI gate (.github/workflows/ci.yml, pnpm run guardrail:desktop-imports). Only
3 documented exceptions remain outside the boundary (services/ai/fetchAdapter.ts and
services/localServerHttp.ts β permanent HTTP-facet exclusion; services/logger.ts β scheduled
future-wave debt). No further Wave 1 work is needed before Wave 2 begins.
Goal (as originally written, now satisfied): make renderer substitution real.
Actions (all complete):
- inventory all direct
@tauri-apps/*imports; - enforce allowlist;
- convert Tauri calls to capability-oriented contracts;
- remove renderer assumptions from application/domain modules;
- define async/error/cancellation semantics;
- add architectural lint/test.
Exit (met):
Shared product code cannot casually import Tauri, Qt or GPUI.
Status: IN PROGRESS β first slice shipped; bounded task proof also merged. crates/worldscript-project (a new, independent
Cargo workspace β see docs/native/CORE-MIGRATION-LEDGER.md for why it's not unified with
src-tauri) implements project schema, validation, a minimal versioned-migration mechanism, and
plain JSON load/save, proven by a headless cargo test suite and a wsproj demo-lifecycle CLI with
zero GUI/Tauri dependencies. This satisfies the wave's exit criterion below. Full task orchestration,
storage-backend parity, diagnostics sink migration, and AI request model extraction remain deferred β
see the ledger's priority order β so this wave stays "in progress," not "complete." Before G1 is evaluated, the
separate row-9 compatibility position must also define and prove the ArrayβEntityState boundary:
the current Core Vec model is intentionally renderer-neutral, while production Redux state uses
EntityState for characters and worlds. The typed boundary adapter, deterministic rejection
fixtures, and an observation-only desktop caller are now implemented in
features/project/coreBoundaryAdapter.ts and features/project/coreValidationShadow.ts; no
authority switch is claimed. The caller validates a synthesized partial envelope, so unknown
TS-only fields and the persisted project representation remain outside its verdict.
Goal: establish authoritative renderer-neutral execution.
Actions (checked = this slice, per docs/native/CORE-MIGRATION-LEDGER.md):
- project load/save (plain JSON, no compression/atomicity β that's Wave 3);
- validation;
- schema;
- migration (minimal versioned mechanism, one synthetic migration proving it);
- storage (fs backend parity, IDB backend β deferred);
- ArrayβEntityState compatibility adapter contract and fixtures (reject duplicate/missing/orphan IDs for characters and worlds; required before G1 evaluation);
- bounded task-supervisor proof (
text.analyze/text.diff, structured failures and input limits; #430) β full worker-bus extraction remains deferred; - [~] diagnostics structured model/redaction Core proof (
crates/worldscript-diagnostics) β sink migration and authority switch remain deferred; - AI request model (out of scope for all of Wave 2 β see ledger);
- headless CLI/test harness.
Exit:
Representative project lifecycle executes without any GUI runtime.
Met by this slice: cargo test in crates/ (9 tests: lifecycle + golden-master fixture parity) and
cargo run --bin wsproj -- demo-lifecycle both run with zero GUI/Tauri dependency in the crate's
cargo tree.
Status: PLANNED β bounded risk-discovery work may start once Wave 2 exposes a typed Core probe.
These three disposable lanes are deliberately pulled forward so the most dangerous Qt runtime
assumptions can be falsified while Waves 3 and 4 remain in progress. They are qualification
evidence, not production Qt implementation, and they must not grow into a product shell. Each lane
retains the maturity progression planned β locally proven β CI-proven β packaged-proven β admitted;
no lane is considered passed from documentation alone.
Execution order:
- Lifecycle and bridge spike β prove a minimal Qt 6/QML process can create a window, load QML, make one typed Rust call, receive one Rust event, bound one async/cancellation path, shut down cleanly, and repeat launch/close three times. Use a provisional bridge candidate only; G2 retains the final scorecard decision.
- Accessibility and input feasibility β prove a machine-observable Qt Quick accessibility tree, keyboard/focus, accessible errors, scalable/high-contrast text, RTL/BiDi, and IME smoke behavior on the supported Linux environment.
- Crash diagnostics and recovery feasibility β intentionally exercise a disposable crash path, produce actionable project-owned diagnostics/symbols, and prove deterministic restart/recovery without corrupting test data or weakening sandbox/process isolation.
Exit: all three lanes have evidence at their honest maturity level, a named owner, and explicit kill criteria. A failed lane stops Qt investment and returns the program to architecture review. The formal Wave 4.5 qualification consumes these results and adds packaging/update trust and security/permission evidence; it does not silently re-run the same feasibility work.
Status: PLANNED β not started.
Goal: settle data semantics before native UI.
Actions:
- atomic write;
- append semantics;
- fsync/durability policy;
- snapshots;
- backup retention;
- recovery;
- encrypted envelope design;
- key-management decision;
- migration from existing desktop storage.
Reconcile #359/#360/#361 invariants explicitly β all three remain open as of Wave 0 (see Β§8.2).
Exit: storage specification and destructive-failure tests approved.
Status: PLANNED β not started.
Implement renderer-neutral at-rest encryption.
Required tests:
- encrypt/decrypt;
- wrong key;
- corruption;
- truncated file;
- interrupted save;
- migration;
- backup restore;
- large project;
- key loss behavior;
- no accidental plaintext persistence.
Exit: desktop project data uses the approved encrypted path where required; #357/#359/#360/#361 all closed with evidence.
Status: PLANNED β formal qualification consumes the earlier lanes; its exit is required before substantial Qt implementation.
This formal checkpoint closes the remaining qualification gaps after the early lifecycle,
accessibility/input, and crash/recovery lanes have produced evidence. It is intentionally smaller
than a Qt port and does not claim production readiness. The complete test matrix, kill criteria,
evidence package, and maturity vocabulary live in
docs/native/QT-EARLY-KILLER-GATES.md.
Formal qualification order:
- review the early-lane evidence, complete the contract/threat inventory, and record the provisional bridge candidate plus rejected alternatives; G2 retains the final scorecard decision;
- after Wave 4's relevant storage/recovery semantics exist, test clean packaged launch, signing identity, updater trust, tamper rejection, and rollback;
- prove least-privilege filesystem/network/IPC behavior with negative tests and confirm that the early crash/recovery evidence did not weaken sandbox or identity-binding invariants;
- use the complete evidence to confirm or reject the bridge through the G2 scorecard, then record residual risk, owners, retest conditions, and an explicit GO/NO-GO decision.
Exit: each kill gate is locally and CI-proven at the required level, packaged trust and recovery evidence exists, no Critical/High security blocker remains, and the admission scorecard authorizes Wave 5. A failed gate stops Qt work and triggers architecture review; it does not get papered over by checking a later G2/G4 box.
This wave does not claim the early lanes as later gate completions. It is the formal qualification checkpoint between Core/R-15 work and Qt enablement: the cheap lifecycle, accessibility/input, and crash/recovery risks were already tested before storage work creates sunk cost, while packaging, updater, and security lanes wait for the storage and R-15 semantics they genuinely depend on.
Status: PLANNED β not started. Gated behind Wave 4.5 and G2.
Wave 5 builds on the accepted early-lane and formal Wave-4.5 evidence. It does not repeat or re-prove the early lifecycle, accessibility/input, or crash gates. It turns the disposable feasibility evidence into a distinct reusable, isolated Qt 6 learning harness and adds only the capability checks intentionally left out of qualification:
- file dialog;
- clipboard;
- packaging of the accepted probes into one repeatable harness;
- test/CI artifact collection and a stable evidence report for the accepted bridge/lifetime/threading model;
- repeated execution only as harness regression protection, not as a second admission decision.
No WorldScript feature migration yet.
Exit: the reusable harness includes the accepted qualification evidence, proves file-dialog and clipboard behavior, runs deterministically in the supported developer and CI environments, and preserves the evidence-backed bridge/lifetime/threading model without duplicating qualification.
Status: PLANNED β not started.
Implement:
- application shell;
- command routing;
- menus;
- dock/pane layout;
- theme tokens;
- typography;
- icons;
- focus model;
- shortcuts;
- notifications;
- dialogs;
- error surface.
Exit: shell consumes Core contracts but contains no duplicated domain logic.
Status: PLANNED β not started.
End-to-end:
launch
β recent projects
β open
β validate/migrate/decrypt
β edit metadata
β save
β close
β reopen
Packaged artifact required.
Exit: real project roundtrip with compatibility evidence.
Status: PLANNED β not started.
This is the highest-risk Qt product surface.
Prove:
- large text;
- cursor;
- selection;
- undo/redo;
- composition/IME;
- Unicode;
- grapheme correctness;
- BiDi/RTL;
- clipboard;
- drag/drop;
- find/replace;
- spellcheck strategy;
- autosave integration;
- recovery.
Do not prematurely force the web editor's internal model into Qt.
Exit: editor correctness gate.
Status: PLANNED β not started.
Benchmark against:
- current Tauri;
- PWA;
- Qt.
Measure memory amplification, typing latency, scrolling, long session, reduced-motion behavior and autosave. Issue #332 remains open and is the concrete comparator.
Exit: no known catastrophic resource behavior; budgets recorded.
Status: PLANNED β not started.
Migrate:
- Binder/navigation;
- project tree;
- characters;
- locations;
- world entities;
- notes;
- metadata;
- search.
Use virtualized models for large collections.
Exit: primary non-editor authoring workflows complete.
Status: PLANNED β not started.
Implement high-interaction visual tools natively.
Requirements:
- pan/zoom;
- keyboard accessibility;
- large graph;
- drag/drop;
- undoable operations;
- deterministic layout state;
- reduced motion;
- GPU fallback behavior.
Exit: interaction/performance/accessibility proof.
Status: PLANNED β not started.
UI consumes renderer-neutral AI Core.
Cover:
- streaming;
- cancellation;
- retry;
- provider errors;
- local model tasks;
- downloads;
- progress;
- RAG state;
- privacy controls.
No provider secrets in QML.
Exit: AI workflows parity.
Status: PLANNED β not started.
Move long-lived desktop tasks behind Rust supervision:
- model downloads;
- export;
- import;
- indexing;
- backup;
- maintenance;
- updater;
- diagnostics.
Requirements:
- cancellation;
- timeout;
- crash-safe state;
- bounded concurrency;
- progress events;
- no orphan work.
Status: PLANNED β not started.
Build real accessibility evidence.
Test:
- keyboard-only;
- screen reader;
- focus;
- roles/names/states;
- editor semantics;
- board alternatives;
- dialogs;
- notifications;
- high contrast;
- reduced motion;
- zoom;
- RTL.
Exit: documented platform evidence, not merely API usage.
Status: PLANNED β not started.
Linux, Windows, macOS as applicable.
Define:
- artifact layout;
- Qt runtime deployment;
- dynamic-library policy;
- license notices;
- SBOM;
- signing;
- notarization;
- installer;
- update metadata;
- rollback;
- offline behavior.
No release based solely on dev-run success.
Status: PLANNED β not started.
Prove:
- Rust panic capture policy;
- native crash collection strategy;
- symbol files;
- anonymization/privacy;
- recovery after crash;
- unsaved-work strategy;
- corrupted-state handling;
- support bundle.
Do not couple the product to a single crash vendor.
Status: PLANNED β not started.
Threat-model:
- local project files;
- malicious imported content;
- path traversal;
- symlink races;
- command injection;
- update trust;
- plugin/extension boundaries if any;
- AI secret storage;
- clipboard;
- drag/drop;
- temporary files;
- log redaction.
Run CodeQL/SAST/dependency/license/secrets review as applicable.
Status: PLANNED β not started.
Real artifact field validation:
- clean install;
- upgrade;
- rollback;
- old project;
- huge project;
- multi-hour session;
- suspend/resume;
- offline;
- network loss;
- disk full;
- permission denied;
- corrupted backup;
- interrupted update.
Exit: beta evidence set.
Status: PLANNED β not started.
Maintain explicit matrix:
Capability | Tauri | PWA | Qt | Evidence | Exception
No checkbox without evidence.
Stable requires G4.
Status: PLANNED β not started. Gated behind G4 + field-observation window.
Only after stable observation window.
Actions:
- migration communications;
- fallback window;
- remove Tauri-specific product code;
- remove unused dependencies;
- archive adapter;
- preserve migration tooling;
- verify PWA unaffected.
Exit: Qt is primary desktop; Tauri is fully removed, not kept as a parallel runtime.
GPUI Waves 21β24 are removed from the active numbered execution roadmap. Their proof targets,
non-goals, and explicit re-entry conditions are preserved in
docs/native/GPUI-EXPLORATIONS.md. This is a scope correction, not a
claim that GPUI has been rejected: no GPUI implementation begins until the separate exploration
record is reviewed after Qt evidence and G6 is explicitly admitted.
QML may own:
- expanded/collapsed;
- current tab;
- hover;
- animation;
- local focus;
- transient selection presentation.
Rust Core owns:
- project entities;
- persisted document state;
- save state;
- encryption state;
- migration state;
- task state;
- collaboration truth.
Large lists must not be copied wholesale across FFI on every render.
Prefer:
- stable IDs;
- paged/virtualized access;
- change events;
- diff-oriented updates;
- immutable snapshots where appropriate;
- bounded payloads.
Document:
- Qt GUI thread;
- Rust worker runtime;
- async bridge;
- cancellation;
- callback lifetime;
- shutdown ordering.
Forbidden:
- blocking disk/AI work on Qt GUI thread;
- Rust callback into destroyed QObject;
- unbounded event queues;
- reentrant mutation without policy.
QML is presentation code.
Avoid:
- project migrations in JavaScript;
- crypto in QML;
- filesystem paths as business logic;
- AI provider orchestration in QML;
- duplicated validation rules.
GPUI may exploit a different UI architecture.
Shared:
- Core;
- contracts;
- project format;
- commands/events;
- tests.
Not necessarily shared:
- widget hierarchy;
- layout implementation;
- animation implementation;
- editor rendering implementation.
Build a dedicated performance model:
- rope/piece-table decision;
- viewport virtualization;
- incremental shaping;
- syntax/semantic decorations;
- selection/caret;
- composition;
- undo integration;
- incremental search;
- background analysis.
Do not optimize for 120 fps by sacrificing text correctness.
Because GPUI is pre-1.0:
- pin exact revision/version;
- maintain upgrade notes;
- run compatibility CI;
- avoid deep dependence on undocumented internals;
- contribute fixes upstream when strategically useful;
- keep Core insulated.
The previous proposal's "maximal React reuse via bindings" is refined.
Guaranteed reuse:
- product behavior;
- Rust Core;
- schemas;
- commands/events;
- assets;
- design tokens;
- localization catalogs where format permits;
- test scenarios;
- UX specifications.
Potential reuse:
- generated view models;
- declarative schemaβUI generation;
- shared Markdown/content transforms.
Not assumed:
- direct React component execution inside Qt;
- direct React component execution inside GPUI;
- stable "gpuix" bridge.
A bridge may be adopted only after maintenance, performance, accessibility and platform gates.
Before Qt production work:
- choose commercial vs LGPL/GPL-compatible distribution strategy;
- identify every Qt module;
- classify each module's license;
- decide dynamic/static linking;
- define relinking obligations if LGPL path is used;
- provide required notices/source offers/materials;
- inventory third-party licenses;
- produce SBOM;
- legal review before commercial distribution.
Do not accidentally introduce a GPL-only Qt module into a distribution whose licensing model cannot accommodate it.
Qt WebEngine, if ever considered, gets a separate Chromium/license/security review and is not assumed.
The project format is renderer-independent.
Rules:
- explicit schema version;
- forward/backward compatibility policy;
- transactional migration;
- backup before destructive migration;
- downgrade policy;
- encrypted format versioning;
- deterministic validation;
- migration telemetry only with privacy-safe policy;
- test corpus of historical projects.
Cross-renderer invariant:
Project saved by Qt
β opens in PWA where capability exists
β opens in GPUI
β no silent semantic loss
Exceptions must be explicit and versioned.
Collaboration cannot depend on renderer implementation.
Define:
- document identity;
- operation/event schema;
- conflict semantics;
- offline queue;
- reconnect;
- auth;
- encryption boundary;
- presence;
- permissions;
- protocol versioning.
Qt and GPUI are protocol clients, not collaboration engines.
Renderer-neutral AI orchestration owns:
- provider abstraction;
- model selection;
- request state;
- cancellation;
- retries;
- token/cost metadata;
- local/remote policy;
- RAG;
- indexing;
- privacy;
- secrets references.
Renderer owns:
- prompt UI;
- streaming presentation;
- interaction affordances.
No renderer stores raw provider secrets unless explicitly delegated to a secure platform capability.
Shared diagnostics schema:
- app version;
- renderer/product line;
- Core version;
- project schema;
- task state;
- memory samples;
- performance markers;
- crash metadata;
- sanitized logs.
Privacy:
- no manuscript text by default;
- no AI prompt content by default;
- no secrets;
- explicit support-bundle preview;
- user-controlled export.
Qt and GPUI have separate artifact pipelines but shared release policy.
Required:
- signed metadata;
- channel model;
- rollback;
- staged rollout;
- minimum supported version;
- schema compatibility;
- delta/full update decision;
- failure recovery;
- offline install;
- provenance;
- SBOM.
Updater state belongs to Core/native services, not QML/GPUI widgets.
Severity: High. Mitigation: license gate before module adoption.
Severity: Critical where memory safety affected. Mitigation: minimal boundary, independent review, sanitizers where feasible, ownership docs.
Severity: High architectural risk. Mitigation: native-readiness lint/review.
Severity: High. Mitigation: delayed admission, exact pin, upgrade harness.
Severity: Release-blocking. Mitigation: early spike + hard gate.
Severity: Critical product risk. Mitigation: shared document model + extensive corpus/IME/BiDi tests.
Severity: Critical security risk. Mitigation: implement before Qt parity. Concrete tracked instances: #357, #359, #360, #361 (all open as of Wave 0).
Severity: High execution risk. Mitigation: Qt-first sequentiality; GPUI production starts only after admission.
Severity: Medium/High.
Mitigation: import allowlist CI (already active β scripts/check-tauri-import-boundary.mjs).
Severity: Critical. Mitigation: Core-owned schema and cross-renderer corpus.
Severity: High. Mitigation: packaged-artifact tests from early Qt slices.
Severity: High. Mitigation: measured SLOs; no framework-based claims. Comparator: Issue #332.
Severity: Critical release risk. Mitigation: accessibility from harness onward.
Severity: High. Mitigation: dependency monitoring and release SLA.
Severity: High. Mitigation: knowledge artifacts, ownership, reproducible harnesses.
Independent second-pass review required for:
- Qt/Rust FFI;
- unsafe Rust;
- ownership/lifetimes;
- storage;
- encryption;
- migration;
- updater;
- signing;
- task supervisor;
- crash recovery;
- GPUI framework internals;
- accessibility architecture.
No unresolved High/Critical finding may be waived silently.
Waivers require:
- owner;
- rationale;
- expiry/review date;
- mitigation;
- release impact.
Preferred:
one capability
β one bounded PR
β targeted local proof
β cloud CI
β independent review
β merge
Avoid:
- giant renderer rewrites;
- mixed Qt + GPUI implementation PRs;
- docs claiming future proof as completed;
- "temporary" direct Core bypasses;
- combining storage migration with unrelated UI redesign.
Every native PR states:
Core impact:
Contract impact:
Qt impact:
GPUI impact:
Web impact:
Tauri transition impact:
Security impact:
Accessibility impact:
Data migration impact:
Performance evidence:
Examples:
docs/native/** only:
- docs validation;
- links;
- schema consistency.
crates/worldscript-core/**:
- Rust;
- contract tests;
- Web adapter;
- Qt adapter;
- GPUI adapter when admitted.
apps/desktop-qt/**:
- Qt build;
- Qt integration;
- packaged smoke where required.
apps/desktop-gpui/**:
- GPUI build;
- GPUI integration/performance smoke.
No obsolete run should consume expensive capacity after a superseding push where cancellation is safe.
Build renderer-independent scenarios:
- New project.
- Open historical project.
- Migrate.
- Save.
- Crash/interruption recovery.
- Snapshot restore.
- Character edit.
- Plot change.
- Manuscript edit.
- Undo/redo.
- AI request/cancel.
- Export.
- Import.
- Backup.
- Encryption roundtrip.
- Collaboration reconnect.
Each renderer proves equivalent observable outcomes.
Mandatory corpus:
- Latin;
- German;
- combining marks;
- emoji/ZWJ;
- CJK;
- Arabic;
- Hebrew;
- mixed RTL/LTR;
- surrogate-equivalent Unicode edge cases;
- very long paragraphs;
- huge documents;
- IME composition;
- dead keys;
- clipboard rich/plain text.
A native editor is not accepted because ASCII typing works.
Create reproducible fixtures and scripts.
Record:
- hardware;
- OS;
- renderer;
- build type;
- project fixture;
- measurement method;
- median/P95/P99 where relevant.
Never compare Qt Release against Tauri Debug or GPUI on different hardware and call it evidence.
Qt Stable requires calendar-time evidence:
- repeated daily use;
- long sessions;
- sleep/wake;
- monitor changes;
- DPI changes;
- GPU/driver diversity;
- file permission changes;
- network interruption;
- disk pressure;
- old projects;
- very large projects.
GPUI receives equivalent validation before Stable.
Never solve a migration problem by:
- disabling encryption;
- loosening filesystem permissions broadly;
- executing arbitrary shell strings;
- storing secrets in UI state;
- skipping signature verification;
- accepting unbounded IPC payloads;
- trusting imported paths;
- suppressing security scanners to obtain green CI.
CEF-specific implementation was deprecated immediately as a target (Wave 0, complete).
Tauri is deprecated only after Qt Stable, and then fully removed (Wave 20/gate G5) β it is not a permanent third runtime.
React/PWA is not deprecated.
Qt is not a stepping stone that GPUI automatically replaces. Qt remains the Hardened product line unless a future ADR explicitly changes that.
GPUI is not guaranteed promotion merely because it is fast.
- 100% of critical domain capabilities headless-testable;
- no renderer-specific business rules;
- deterministic migrations;
- renderer-neutral encryption;
- bounded task lifecycle;
- project-format compatibility.
- accessibility gate;
- security gate;
- packaging/update gate;
- long-session stability;
- large-project stability;
- IME/BiDi correctness;
- supportable LTS/dependency posture.
- editor latency target;
- 120-Hz-capable designated workflows where supported;
- lower idle resource footprint than Qt target where realistic;
- no text-correctness regression;
- accessibility sufficient for release;
- framework upgrade burden acceptable.
- identical authoritative project format;
- identical Core semantics;
- compatible collaboration protocol;
- renderer-specific presentation freedom.
Create/supersede ADRs for:
- CEF strategy retirement. (ADR-0021, merged β PR #406)
- Qt-first native strategy. (ADR-0021, merged β PR #406)
- QtβRust bridge selection.
- Qt licensing/distribution model.
- R-15 key/storage architecture.
- Qt packaging/updater.
- Tauri retirement.
- GPUI admission.
- GPUI dependency/component strategy.
- Multi-renderer release governance.
Status: COMPLETE for the Wave 0 transition steps (items 1β9). Item 10 is a standing guardrail for later waves, not a Wave 0 task β it stays in effect until Wave 2 actually proves out; its bracket note is not a sign of incomplete Wave-0 work.
The first implementation sequence after adopting this roadmap is:
1. Freeze new CEF feature work. [DONE]
2. Inventory current CEF PR(s), especially any Draft work. [DONE]
3. Extract only renderer-neutral improvements. [DONE β PR B, #407]
4. Close/supersede CEF-specific PRs with a clear historical note. [DONE β #404 closed unmerged, #405 closed as superseded]
5. Adopt new ADR + this roadmap. [DONE β merged, PR #406]
6. Rename/generalize CEF-only governance docs where their content remains
useful. [DONE β UI-DOMAIN-STATE-CLASSIFICATION.md relocated to docs/native/, PR #407]
7. Re-run main CI. [DONE β green]
8. Re-audit DesktopPlatform/Tauri import boundary. [ALREADY TRUE β Wave 1 complete]
9. Start Wave 1. [ALREADY COMPLETE before Wave 0]
10. Do not begin Qt UI until Wave 1/2 prerequisites are sufficiently proven. [Wave 2 not yet started]
CEF research remains useful as historical evidence for:
- lifecycle discipline;
- CI false-green prevention;
- accessibility evidence discipline;
- native process diagnostics;
- review rigor;
- packaging skepticism;
- sandbox/security reasoning.
It does not remain a runtime dependency.
Conceptual only; adapt to current repository rather than mass-renaming:
apps/
web/
desktop-tauri/ # transitional β removed at Wave 20 / gate G5
desktop-qt/
desktop-gpui/ # only after admission
crates/
worldscript-core/
worldscript-contracts/
worldscript-storage/
worldscript-crypto/
worldscript-migrations/
worldscript-tasks/
worldscript-ai/
worldscript-diagnostics/
docs/
native/
ROADMAP-QT-GPUI-DESKTOP.md (this document)
NATIVE-RISK-REGISTER.md
UI-DOMAIN-STATE-CLASSIFICATION.md
qt/
gpui/
historical/
cef/ # short pointer doc only, not a maintained tree
Do not reorganize purely for aesthetics.
Qt Stable means all of the following are true:
- packaged product, not dev host;
- signed/notarized where applicable;
- update and rollback;
- project migration;
- encrypted storage;
- recovery;
- accessibility;
- IME/BiDi;
- editor correctness;
- core workflows;
- AI workflows;
- large project;
- long session;
- diagnostics;
- support bundle;
- security review;
- license compliance;
- no unresolved Critical;
- accepted High-risk disposition;
- field observation window;
- explicit GO record.
GPUI Stable requires everything relevant from Qt Stable plus:
- framework version/update discipline;
- demonstrated reason for product existence beyond novelty;
- measurable performance advantage on designated workflows or another approved strategic advantage;
- accessibility parity sufficient for target users;
- no project-format divergence;
- no hidden renderer-specific domain fork.
Allowed differentiation:
Qt Hardened:
- conservative defaults;
- longer support windows;
- enterprise deployment;
- maximum accessibility;
- predictable UI behavior.
GPUI Vision:
- experimental high-performance views;
- rapid GPU-native interaction;
- advanced visualizations;
- performance-first ergonomics.
Forbidden differentiation:
- incompatible project truth;
- incompatible encryption semantics;
- divergent migration rules;
- different collaboration meaning.
A unified installer with renderer choice is not an early goal.
It may be evaluated only after both native lines are stable.
Risks:
- artifact size;
- support complexity;
- update complexity;
- user confusion;
- duplicated runtime assets.
Separate products/channels are the default.
Possible mature model:
Core release train
ββ Web/PWA
ββ Qt Hardened
ββ GPUI Vision
Contracts declare compatibility ranges.
A Core release cannot assume all renderers ship simultaneously.
Qt:
- pinned supported Qt 6 line;
- explicit LTS decision;
- module allowlist;
- license inventory.
GPUI:
- exact pin;
- controlled update cadence;
- no wildcard production dependencies;
- compatibility harness;
- upstream monitoring.
Rust:
cargo audit/equivalent;- lockfile discipline;
- MSRV/toolchain policy;
- unsafe review.
For every packaged desktop artifact:
- source revision;
- dependency lock;
- compiler/toolchain version;
- Qt/GPUI version;
- build provenance;
- hashes;
- SBOM;
- signing identity metadata;
- reproducible recipe to the extent feasible.
Every Core operation defines:
success
recoverable error
user-actionable error
retryable error
cancelled
fatal/corrupt state
Renderers translate errors into presentation; they do not reinterpret persistence truth.
AI, indexing, export, import, search and snapshots require explicit cancellation.
UI event streams must be bounded/coalesced where appropriate.
Neither QML signals nor GPUI entity notifications may become an accidental unbounded event bus.
Shared shutdown state machine:
RUNNING
β QUIESCING
β FLUSHING
β TASK_CANCELLATION
β PERSIST_FINAL_STATE
β RELEASE_UI
β RELEASE_NATIVE_SERVICES
β EXIT
Test:
- normal close;
- OS shutdown;
- update restart;
- crash recovery;
- task in progress;
- save in progress.
On next launch:
- detect incomplete save/update/migration;
- validate last-known-good state;
- offer recovery;
- never silently overwrite a recoverable backup;
- log privacy-safe evidence.
Avoid whole-project cloning across renderer boundaries.
Use:
- stable entity IDs;
- incremental access;
- streaming;
- pagination;
- virtualized views;
- native serialization;
- bounded snapshots.
Large-project performance is a Core+renderer joint SLO.
Qt provides a strong native path, but export semantics stay renderer-neutral.
Core owns:
- document/export model;
- deterministic transforms.
Renderer/native service owns:
- print dialog;
- device integration;
- preview presentation.
GPUI may initially delegate printing through shared native service rather than reimplementing print layout.
One authoritative message/catalog strategy where feasible.
Requirements:
- plural rules;
- RTL;
- locale formatting;
- shortcut localization;
- font fallback;
- CJK;
- translation completeness checks.
Qt and React catalogs may require generated adapters, but source meaning should not diverge.
Maintain renderer-neutral tokens:
- semantic colors;
- spacing;
- typography roles;
- radius;
- motion durations;
- contrast requirements.
Renderer-specific implementation is allowed.
Do not attempt pixel-identical rendering across Qt and GPUI.
Do not introduce renderer-specific arbitrary-code plugins during migration.
Any future extension system must define:
- trust model;
- permissions;
- API versioning;
- sandbox/process model;
- data access;
- update/signing.
Core privacy policy applies to every renderer.
No renderer-specific telemetry expansion without review.
Support bundles must be inspectable before sharing.
Roadmap status must distinguish:
- PLANNED;
- IN PROGRESS;
- IMPLEMENTED;
- CI-PROVEN;
- PACKAGED-PROVEN;
- FIELD-PROVEN;
- BLOCKED;
- DEFERRED.
Never mark "done" because code exists.
A wave advances only when:
- exit criteria satisfied;
- required CI green;
- CodeQL/security gates green where applicable;
- review threads resolved;
- docs match reality;
- no new Critical/High blocker;
- next wave does not invalidate unresolved prerequisite.
Small overlap is allowed only for independent preparation.
Stop and request architecture review if:
- Qt bridge requires broad unsafe surface;
- Qt license strategy conflicts with distribution model;
- project format must diverge by renderer;
- R-15 would be weakened;
- GPUI cannot meet accessibility/IME requirements;
- a renderer requires domain duplication;
- updater/signing cannot meet trust requirements;
- a Critical security finding lacks a credible mitigation.
Do not:
- replace CEF with a Qt big-bang rewrite;
- start Qt and GPUI parity simultaneously;
- embed React in Qt as the default architecture;
- assume Qt WebEngine solves migration;
- assume GPUI's editor architecture can be copied wholesale from Zed;
- treat framework benchmarks as WorldScript benchmarks;
- postpone encryption;
- let UI own migrations;
- merge giant "native rewrite" PRs;
- retire Tauri before packaged Qt proof;
- promise 120 fps without defined evidence.
These are sequencing goals, not date guarantees.
- strategy reset; [DONE β PR #406]
- CEF reconciliation; [DONE β PR #407]
- DesktopPlatform boundary; [ALREADY DONE, pre-Wave-0]
- Core headless extraction;
- R-15/storage architecture;
- Qt licensing/bridge scorecard.
- Qt learning harness;
- packaged Qt shell;
- project lifecycle slice;
- editor feasibility;
- accessibility/IME evidence.
- Qt authoring workflows;
- AI/tasks;
- packaging/update;
- beta hardening.
Actual calendar duration is evidence-driven.
Every Wave PR may use:
## Native-readiness
- [ ] Domain logic is renderer-neutral
- [ ] No new direct Tauri import outside allowlist
- [ ] No Qt type leaked into Core
- [ ] No GPUI type leaked into Core
- [ ] Headless test exists
- [ ] Contract impact documented
- [ ] Storage/migration impact documented
- [ ] Security impact documented
- [ ] Accessibility impact documented
- [ ] Performance impact measured or N/A justified| Capability | Core | Web/PWA | Tauri transition | Qt | GPUI | Evidence |
|---|---|---|---|---|---|---|
| Project open | β | β | β | β | β | β |
| Save | β | β | β | β | β | β |
| Encryption | β | β | β | β | β | β |
| Recovery | β | β | β | β | β | β |
| Manuscript | β | β | β | β | β | β |
| Plot Board | β | β | β | β | β | β |
| AI | β | β | β | β | β | β |
| Accessibility | β | β | β | β | β | β |
| Update | β | β | β | β | β | β |
Populate from evidence, not assumptions.
Risk:
Severity:
Affected renderer(s):
Observed evidence:
Root cause:
Mitigation:
Residual risk:
Release impact:
Owner:
Review date:
Exit criterion:Before major native decisions:
Does this increase renderer coupling?
Does it duplicate domain logic?
Does it weaken data integrity?
Does it weaken R-15?
Does it create a new privileged boundary?
Does it affect project compatibility?
Does it affect accessibility?
Does it affect update trust?
Can it be headless-tested?
Can it be rolled back?
Is it documented?
Is there an independent review?
Older PRs, including CEF-era work, are never merged because their original goal was once valid.
For each:
- diff against current main;
- identify unique useful deltas;
- classify renderer-neutral vs obsolete;
- reimplement cleanly if necessary;
- run current tests;
- close/supersede stale architecture.
This same rule applies to historical Tauri work.
#332 should remain a tracked performance/stability reference until its useful application-level causes are either:
- fixed in Core;
- disproven;
- renderer-specific and superseded by measured Qt behavior.
Do not close it merely because WebKitGTK is no longer the future runtime. Current status (2026-08-20): open, unresolved, not root-caused by a maintainer yet β see Β§8.3.
R-15 is promoted to an early native-program gate.
Qt Stable is forbidden without the approved desktop at-rest encryption posture.
GPUI inherits the same implementation from Core. Concrete tracked instances: #357, #359, #360, and #361 β see Β§8.1β8.2.
Before the first Qt project-write path:
- inspect current issue/PR state;
- extract the exact invariants;
- encode them in regression tests where possible;
- link those tests from native migration documentation.
Historical closure does not remove their lessons. Current status (2026-08-20): all three open on
GitHub, describing gaps in the closed/unmerged reference design (PR #356) rather than a live path β
desktop fs-backed encryption does not exist on main today. See Β§8.2.
Every wave budgets time for:
- implementation;
- targeted tests;
- CI;
- security review;
- accessibility review where relevant;
- docs;
- review-finding reconciliation;
- performance evidence.
CI latency is optimized through orchestration, not by removing critical evidence.
Beta cohort should cover:
- Windows;
- macOS;
- Linux;
- Intel/AMD;
- relevant GPU diversity;
- screen reader users;
- IME users;
- RTL users;
- large-project users;
- long-session writers.
Collect structured privacy-safe failure reports.
Start narrower than Qt.
First cohort:
- performance-sensitive users;
- supported platforms with strongest GPUI maturity;
- large manuscripts;
- graph/board-heavy workflows.
Expand only after accessibility and platform evidence.
Qt Hardened may use longer support windows.
GPUI Vision may use faster update cadence.
Project format and Core compatibility must make cross-edition movement safe.
Any experimental bridge/component must have:
- replacement strategy;
- pin;
- owner;
- update cadence;
- test coverage.
No critical project capability may depend on an abandoned experimental crate without a contingency.
Within the long-term horizon WorldScript Studio should be capable of supporting:
WorldScript Web
React/PWA
β
βββββββββββββββββ
β β
βΌ βΌ
WorldScript Qt WorldScript GPUI
Hardened Edition Vision Edition
β β
βββββββββ¬ββββββββ
βΌ
WorldScript Core
authoritative Rust
β
βΌ
One project format
One migration model
One crypto model
One collaboration protocol
The user chooses the surface. The project does not fork its truth.
Qt is the conservative, mature native product.
GPUI is the performance-forward native product.
React/PWA remains the web product.
Tauri is retired once Qt proves replacement parity β it does not persist as a fourth surface alongside Web/PWA, Qt, and GPUI.
CEF is not part of the target architecture.
The program is successful only if WorldScript becomes more maintainable because it has multiple renderers, not less.
The multi-renderer strategy is therefore conditional on architectural discipline:
One Core. One project truth. Versioned contracts. Multiple surfaces. Evidence before promotion.
The purpose of Qt is not to replace one wrapper with another.
The purpose of GPUI is not to chase novelty.
The purpose of the roadmap is to turn WorldScript Studio into a durable product platform whose security, data integrity, accessibility and domain behavior survive renderer change.
That is the binding architectural objective.