pwa(installed): turn standalone mode into a polished OS-integrated writing shell

[qnbs]

Parent

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

Product opportunity

The manifest already declares display: standalone, window-controls-overlay in display_override, shortcuts, launch_handler, handle_links, a share target, protocol handler and Edge side-panel metadata. These declarations should become a coherent installed WorldScript experience, not merely manifest decoration.

A well-designed installed PWA can combine web deployment with an app-like window, deep links, shortcuts and selective OS integration while retaining instant update/zero-installer advantages.

Capability philosophy

Use progressive enhancement:

normal browser tab = complete baseline product
installed PWA = enhanced shell
supported Chromium desktop = additional OS/window integration
mobile installed PWA = touch/mobile shell

Never hide core writing features behind installation.

Window Controls Overlay

Where supported, evaluate integrating WorldScript chrome into the title-bar overlay.

Requirements:

• use window-controls-overlay only after runtime feature detection;
• respect env(titlebar-area-*) geometry;
• never place essential controls under draggable/window-control regions;
• preserve keyboard/accessibility semantics;
• high contrast/theme/reduced-transparency modes remain readable;
• fall back to normal standalone chrome cleanly.

Potential benefit: more vertical manuscript space and a genuinely app-like shell.

Launch handling / single-window preference

The manifest currently uses launch_handler.client_mode = navigate-existing.

Productize this:

• external launch should focus/reuse an appropriate existing installed window when the browser supports it;
• do not discard dirty navigation state to satisfy a new launch;
• route incoming intent through the typed external-launch layer (pwa(capture): make WorldScript an OS share target and offline research/idea inbox #484/pwa(files): add permission-scoped local file handles, native-like open/save & installed-PWA file handling #481);
• coordinate project ownership with pwa(concurrency): make multi-tab editing safe with Web Locks, BroadcastChannel & lifecycle ownership #480.

App shortcuts

The manifest already defines shortcuts for Templates, Manuscript, Characters, AI Writer, New Scene and Start Writing Session.

Audit them as product entry points:

• cold start to correct destination;
• warm existing-window navigation;
• offline behavior;
• unsaved-current-project handling;
• accessibility/focus after launch;
• invalid/stale query fallback.

Consider whether a small number of higher-value dynamic-ish workflows should replace lower-value shortcuts; manifest shortcuts themselves are static, so avoid pretending they can reflect live project state.

Link handling and protocol handler

handle_links: preferred and web+worldscript can enable deep app entry.

Define an allowlisted route grammar for safe intents such as:

open view
open project by local logical ID (only if already present/authorized)
open capture inbox
start writing session

Do not allow protocol/deep links to trigger:

• arbitrary file access;
• plugin installation;
• AI provider calls;
• secret/token changes;
• destructive project mutation;
• arbitrary external URL navigation.

Badging API — small but useful

Where supported, use app icon badging only for meaningful local state, e.g.:

• pending Capture Inbox items;
• possibly completed long-running local task requiring attention.

Do not badge ordinary autosaves or create notification spam. Clear badge deterministically when the state is handled.

Notifications — conservative admission

Do not request notification permission at startup.

Potential justified cases only after explicit user opt-in:

• a long local export/model download/task completes while app is backgrounded;
• a user-configured writing-session timer completes.

No marketing/push requirement is introduced by this issue. Prefer in-app status when the app is foregrounded.

Edge side panel / compact companion mode

The manifest already declares an Edge side-panel preferred width. Evaluate whether a compact reference/capture companion is genuinely useful:

• notes/research/codex lookup;
• capture inbox;
• character quick reference;
• no full manuscript editing if ergonomics are poor.

Do not contort the entire app to fit 480px merely because the manifest has metadata.

Display-mode-aware UX

Use matchMedia('(display-mode: standalone)') / supported signals to adjust only shell behavior:

• installation help/status;
• external-link behavior;
• title-bar spacing;
• shortcut/launch messaging;
• app-like navigation affordances.

Do not fork business logic by display mode.

Install UX

• contextual install affordance after demonstrated engagement, not immediate nagging;
• explain benefits honestly: offline shell, app window, shortcuts, supported OS integrations;
• hide custom install button when browser cannot provide install prompt;
• never imply installation is required for project safety;
• support users who prefer normal browser tabs.

Tests

• normal tab vs standalone;
• window-controls-overlay available/unavailable;
• cold/warm shortcut launch;
• protocol valid/invalid/malicious input;
• handle-links behavior;
• multiple windows (pwa(concurrency): make multi-tab editing safe with Web Locks, BroadcastChannel & lifecycle ownership #480);
• dirty project + external launch;
• offline shortcut launch;
• badge set/clear;
• notification permission denied;
• high contrast/zoom/titlebar geometry;
• mobile installed PWA.

Acceptance criteria

• Manifest capabilities correspond to tested product behavior rather than declarations only.
• Standalone shell is polished but normal-tab mode remains complete.
• Window Controls Overlay is accessible and safely feature-detected.
• Launch/shortcut/deep-link intents use one validated routing layer.
• Dirty work cannot be discarded by an external launch.
• Badging, if admitted, reflects bounded meaningful local state.
• Notification permission is never requested without explicit contextual user intent.
• Edge side-panel behavior is either productized for a useful compact workflow or removed/declared unsupported rather than left ambiguous.
• Browser support matrix documents enhanced/fallback behavior.

Non-goals

• recreating every native OS integration;
• requiring PWA installation;
• notification spam;
• making deep links a privileged command channel;
• forking core app logic by display mode.

[qnbs]

Architecture refinement / evolve the existing installed-PWA shell — 2026-08-24

Treat this as an evolution of the existing manifest + SW registration/install state, not as a second shell-state architecture.

Existing seeds

• public/manifest.json already declares standalone mode, window-controls-overlay, shortcuts, launch handling, preferred link handling, share target, protocol handler, and Edge side-panel metadata.
• register-sw.ts already owns install-prompt capture, installed-state detection, SW registration/update checks and related custom events through window.worldScriptPWA.
• existing PWA UI already exposes install/update status.

Prefer wrapping/typing/evolving this state. If a new PwaShellService or store is introduced, migrate the existing global/event path deliberately and retire duplicate state rather than keeping two authorities.

External launches

Protocol, shortcut, launch handler, share target, and future file-handler flows must route through the shared typed ExternalLaunchIntent boundary from #484. Display-mode code must not gain privileged parsing/mutation authority.

Display mode

Standalone/window-controls-overlay/side-panel mode may alter shell chrome, spacing, link escape behavior, install affordances, and compact workflows. It must not fork project, persistence, AI, migration, or command semantics.

Side panel

Treat the existing Edge side-panel manifest declaration as an admission question. Either productize a bounded useful companion workflow or remove/document the declaration as unsupported; do not distort the full application around 480px simply because metadata exists.

Acceptance additions

• Existing window.worldScriptPWA/event state is inventoried before a replacement state container is introduced.
• There is one authoritative install/update state after migration.
• All external launch mechanisms share the pwa(capture): make WorldScript an OS share target and offline research/idea inbox #484 intent router.
• Standalone/display mode changes presentation only.
• Window Controls Overlay geometry has accessibility/high-contrast/zoom/fallback tests.
• Manifest declarations without admitted product behavior are explicitly removed, deferred, or documented rather than left ambiguous.