pwa(mobile): build a keyboard-aware, touch-first distraction-free writing mode

[qnbs]

Parent

Part of #478 — PWA first-class excellence/hardening.

Product opportunity

The PWA can reach phones/tablets immediately, without a separate mobile binary. That is not merely compatibility: WorldScript can offer a purpose-built mobile writing/capture surface that complements the full desktop workspace.

The goal is not to squeeze the desktop UI onto a phone. It is to design a focused mobile mode around browser-native viewport, touch, sharing and installed-PWA capabilities.

Primary workflows

Prioritize workflows that make sense on mobile:

1. distraction-free manuscript writing/editing;
2. scene/note quick edits;
3. Capture Inbox triage (pwa(capture): make WorldScript an OS share target and offline research/idea inbox #484);
4. character/world reference;
5. writing-session timer/progress;
6. local/lightweight AI where device capability admits it;
7. offline writing and later normal project continuation.

Complex desktop-only panels may remain available but should not dictate mobile layout.

Virtual keyboard / viewport correctness

Mobile editors commonly fail when the on-screen keyboard changes the visual viewport.

Use standards-based capability detection (VisualViewport, Virtual Keyboard API where available) to ensure:

• caret remains visible;
• selected text/toolbars are not hidden behind keyboard;
• bottom controls respect keyboard geometry;
• scrolling does not jump unpredictably on focus;
• dialogs/popovers remain reachable;
• orientation changes preserve editing position;
• fallback works when Virtual Keyboard API is absent.

Do not hard-code keyboard heights.

Safe areas / installed mode

Respect:

• env(safe-area-inset-*);
• display cutouts/notches;
• standalone browser chrome differences;
• portrait/landscape transitions;
• zoom/text scaling.

Touch editor ergonomics

• minimum practical touch targets;
• avoid hover-only controls;
• long-press/context behavior must not conflict with native text selection;
• drag/drop affordances have touch alternatives;
• selection handles and formatting UI do not obscure text;
• sidebars become drawers/sheets rather than tiny fixed columns;
• preserve keyboard-only accessibility for tablets/hardware keyboards.

Distraction-free writing mode

Provide a mobile-focused shell with:

• manuscript/scene title;
• editor;
• compact save/offline status;
• word/session progress;
• minimal navigation;
• optional focus timer;
• quick AI action sheet rather than permanent heavy AI panels.

The mode should be usable in a normal browser tab and installed PWA.

Screen Wake Lock — opt-in

During an explicit writing/focus session, offer an optional “Keep screen awake during session” feature where Screen Wake Lock is supported.

Rules:

• user explicitly enables it;
• release on session end/visibility loss as required;
• reacquire only according to API/lifecycle semantics;
• no battery-draining always-on default;
• unavailable API simply hides/disables the option.

Mobile performance policy

Mobile is not a smaller desktop GPU.

• avoid eager loading large AI/model chunks;
• prioritize editor-ready time;
• lazy-load heavy workspace views;
• bound image previews;
• avoid background model initialization;
• use device/capability admission for local AI;
• preserve autosave responsiveness under thermal/memory pressure.

Coordinate with #450/#483.

Offline behavior

A mobile PWA should be especially strong for disconnected writing:

• cold offline launch to recent/local project where supported;
• edit/autosave offline;
• clear local/offline status;
• no blocking network dependency for core writing;
• safe recovery after browser process eviction/relaunch;
• storage/quota truth via pwa(storage): engineer a durable IDB+OPFS storage tier with persistence, quota & recovery UX #482.

Accessibility

Test:

• screen reader;
• large text/browser zoom;
• high contrast;
• reduced motion/transparency;
• external hardware keyboard;
• switch/keyboard navigation where applicable;
• focus restoration after drawers/dialogs.

Tests / evidence matrix

At minimum representative:

• Android Chromium normal tab;
• Android installed PWA;
• iOS/iPadOS Safari/PWA according to support policy;
• tablet landscape + hardware keyboard;
• keyboard open/close loops;
• orientation changes;
• offline launch/edit/relaunch;
• low-memory/background discard;
• large project;
• Capture Inbox launch;
• local-AI capability unavailable/available.

Acceptance criteria

• Mobile mode is intentionally designed, not desktop CSS compressed.
• Virtual keyboard never routinely hides active caret/critical controls.
• Safe areas/orientation are handled.
• Core writing works offline on admitted mobile browsers.
• Heavy features are lazy/capability loaded.
• Touch interactions have accessible alternatives.
• Optional Screen Wake Lock is session-scoped and user-controlled.
• Installed and normal-tab mobile modes both work.
• Mobile performance/accessibility evidence exists.

Non-goals

• matching every desktop workspace panel on a phone;
• requiring installation;
• always-on Wake Lock;
• loading multi-GB local models automatically on mobile;
• creating a separate divergent mobile domain model.

[qnbs]

Architecture refinement / presentation-only mobile specialization — 2026-08-24

Keep the issue's existing non-goal as a hard architecture rule: no divergent mobile domain model.

Mobile-specific ownership

Mobile may own:

• shell/layout and drawer/sheet composition;
• touch affordances;
• VisualViewport / Virtual Keyboard geometry;
• safe-area/orientation behavior;
• wake-lock lifecycle;
• mobile-specific performance/admission policy;
• compact status/action presentation.

Shared authority remains:

• project/manuscript/scene/note/entity models;
• commands and undo/redo semantics;
• persistence/autosave;
• migration/encryption;
• AI facade;
• Capture Inbox records and assignment semantics.

Editor rule

Do not create a second mobile editor engine solely because layout and input differ. First prove whether the existing editor can satisfy caret/selection/IME/viewport/touch correctness with responsive presentation and capability-specific adapters. A replacement editor requires measured correctness/performance evidence and an explicit migration plan.

Capability reuse

Use #489 for VisualViewport/Virtual Keyboard/Wake Lock capability facts. This issue owns mobile workflow admission and UX policy; it should not duplicate generic capability probes.

Performance

Editor-ready time and autosave responsiveness outrank eager local-AI/model initialization. Heavy AI, analytics, graphs, and large workspace panels should remain lazy/capability-loaded on mobile.

Acceptance additions

• Mobile shell uses the canonical project and command model.
• Existing editor correctness is tested before any replacement architecture is proposed.
• Viewport/keyboard probes come from pwa(capabilities): establish progressive-enhancement registry, browser support tiers & runtime diagnostics #489 or a deliberately shared primitive.
• Installed and normal-tab mobile modes preserve the same persistence semantics.
• Low-memory/background discard recovery is tested against acknowledged-edit durability.
• Touch alternatives do not remove keyboard/hardware-keyboard accessibility.