pwa(concurrency): make multi-tab editing safe with Web Locks, BroadcastChannel & lifecycle ownership

[qnbs]

Parent

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

Why this can exceed native behavior

The PWA can have several independent same-origin tabs/windows/workers alive at once. That is often treated as a browser nuisance, but it can become a product advantage if WorldScript makes concurrency explicit and safe.

Browser-native primitives provide origin-wide coordination without inventing a native IPC daemon:

• Web Locks API for exclusive/shared ownership of critical resources;
• BroadcastChannel for low-latency same-origin presence/state notifications;
• Service Worker / workers as additional coordinated participants where appropriate;
• browser lifecycle semantics that release locks when a context actually dies.

The goal is not real-time collaborative editing between a user's own tabs. The goal is to make accidental or intentional multi-window usage safe, comprehensible, and useful.

Current opportunity

The repository already has sophisticated IndexedDB encryption-migration admission concepts (#338/#360 lineage), but there is no dedicated general PWA multi-tab ownership contract. Search of the current codebase did not find a generic BroadcastChannel or PWA-level navigator.locks coordination layer.

Proposed architecture

WorldScript origin
    │
    ├── Tab / Installed window A ─┐
    ├── Tab / Installed window B ─┼── BroadcastChannel: presence/events
    ├── Worker / local-AI owner ──┤
    └── Service Worker ───────────┘
                 │
                 ▼
          Web Locks ownership
                 │
                 ▼
       IndexedDB / OPFS authority

Lock classes

Define named, versioned lock namespaces rather than ad-hoc strings:

worldscript:project:<id>:writer
worldscript:project:<id>:migration
worldscript:project:<id>:backup
worldscript:local-ai:model:<id>:init
worldscript:duckdb:migration
worldscript:pwa:update-activation

Only introduce a lock when a real shared-resource race exists. Do not serialize unrelated work globally.

Project writing ownership

Recommended default:

• first context opening a project obtains the active writer lease/lock;
• a second context may open safely in read-only / observer mode rather than silently becoming another writer;
• the secondary context clearly identifies the active writer context;
• user may request Take over editing;
• takeover flushes/coordinates current dirty state before transferring ownership where possible;
• if the original tab is dead, lock loss permits deterministic recovery;
• never use wall-clock-only leases as the sole source of truth.

Do not make the entire application single-instance: multiple projects should remain usable in multiple tabs/windows if their resource ownership does not conflict.

BroadcastChannel protocol

BroadcastChannel is advisory coordination, not durable truth. Persisted state remains in IndexedDB/OPFS.

Suggested typed messages:

HELLO / GOODBYE
PROJECT_OPENED
PROJECT_WRITER_ACQUIRED
PROJECT_WRITER_RELEASED
DIRTY_GENERATION_ADVANCED
SAVE_STARTED / SAVE_COMMITTED / SAVE_FAILED
MIGRATION_STARTED / FINISHED / RECOVERY_REQUIRED
UPDATE_AVAILABLE / UPDATE_ACTIVATION_REQUESTED
LOCAL_AI_INIT_STARTED / READY / FAILED

Every message should include a protocol version, context ID, timestamp/monotonic sequence where useful, and bounded non-sensitive metadata. Never broadcast manuscript text, prompts, tokens, API keys, or encryption material merely for coordination.

Lifecycle behavior

Handle:

• normal close;
• crash/kill;
• browser discard/freeze/background;
• reload/navigation;
• installed PWA + normal browser tab simultaneously;
• service-worker replacement;
• suspend/resume where exposed;
• stale presence records.

Presence heartbeats may improve UX but must not become a correctness substitute for Web Locks / durable state.

Local-AI resource ownership

A major PWA-specific win is preventing multiple tabs from independently loading the same multi-GB local model or initializing WebGPU simultaneously.

Use per-model/per-backend locks to:

• deduplicate initialization;
• route/coordinate requests where architecture permits;
• prevent model-download duplication;
• avoid GPU-memory storms;
• allow safe cancellation/recovery if the owning context dies.

Coordinate with the dedicated PWA local-AI issue under #478.

Migration / encryption relationship

Do not replace the existing security-specific migration-admission invariants with generic UI locking.

Instead:

• reuse/align lock naming and semantics where safe;
• ensure migration obtains exclusive admission before protected writes;
• ensure generic project writer ownership cannot bypass encryption migration policy;
• keep Phase 4: wire encryption migration journal into production (disable/rotate flow, secondary-adapter startup, write-admission race, verification-deletion race) #338/Desktop fs reads/writes don't participate in the encryption-migration admission lock (race window during disable/rotate) #360 security behavior authoritative for protected data.

Failure UX

Never show a generic "database locked" error when the app can explain the situation.

Examples:

• “This project is currently being edited in another WorldScript window.”
• “A storage migration is finishing. Editing will resume when it is safe.”
• “Local model X is already loading in another WorldScript window.”

Provide safe actions: focus existing window where possible, retry, open read-only, or explicit takeover.

Testing

Automated/browser-matrix tests should cover:

• two tabs open same project concurrently;
• two tabs open different projects;
• active writer crashes;
• active writer reloads;
• dirty secondary tries takeover;
• migration starts while writer active;
• local model init from two tabs;
• installed PWA and normal browser tab coexist;
• BroadcastChannel unavailable/fails;
• Web Locks unavailable;
• background/frozen context recovers;
• service-worker update while multiple dirty clients exist.

Fallback must remain safe when a browser lacks one of the APIs; unsupported capability must not silently re-enable unsafe last-writer-wins behavior.

Acceptance criteria

• Typed same-origin coordination protocol exists.
• Same project cannot be silently written by two independent PWA contexts.
• Read-only/observer secondary-open UX is clear.
• Explicit safe takeover exists or is deliberately deferred with clear UX.
• Dead-tab recovery does not require manual storage deletion.
• BroadcastChannel is never treated as durable authority.
• Critical shared operations use Web Locks or an equivalent proven admission primitive.
• Local-AI/model initialization can be deduplicated across contexts where practical.
• Existing encryption migration admission remains fail-closed.
• No sensitive content is broadcast as coordination metadata.
• Multi-tab lifecycle tests exist.
• Unsupported browsers degrade safely and explicitly.

Non-goals

• building Google-Docs-style collaboration between the user's own tabs;
• introducing a server requirement;
• forcing single-instance application behavior;
• using BroadcastChannel as persistence;
• weakening encryption migration locks for convenience.

[qnbs]

Architecture refinement / existing coordination reconciliation — 2026-08-24

This issue should explicitly begin from the fact that generic project-level multi-context ownership is missing, but browser coordination primitives already exist in two specialized production paths.

Existing seed A — protected storage admission

services/storage/protectedWriteAdmission.ts already provides:

• navigator.locks;
• shared/exclusive reader-writer semantics;
• fair admission around encryption migration vs protected writes;
• a documented same-tab fallback when Web Locks are unavailable.

This security-specific policy remains authoritative. A generic PWA lock layer must not replace or weaken it.

Existing seed B — local-AI tab ownership

packages/ai-core/src/tabLeaderElection.ts already provides:

• BroadcastChannel coordination;
• context identity/election;
• localStorage heartbeat;
• leadership surrender/recovery semantics.

Audit this before creating a second AI/model leader mechanism.

Refined architecture

If real duplication justifies extraction, extract only narrow browser coordination primitives, e.g.:

context identity
lock request helper
bounded/versioned typed channel envelope
channel lifecycle
capability/fallback state

Keep semantic policy distributed to the correct owner:

storage/encryption admission -> storage/security
project writer ownership     -> project/PWA coordination
local AI ownership           -> AI subsystem
update activation            -> SW/update subsystem

Do not build a global WorldScriptLockManager that becomes semantic authority for every subsystem.

Project writer ownership

The proposed first-writer/read-only-secondary/takeover model remains valid. Its correctness source should be Web Locks/durable state, while BroadcastChannel/presence improves UX only.

Fallback rule

When Web Locks are unavailable, fallback behavior must be explicitly classified. A same-tab in-process lock is not equivalent to cross-tab exclusion. Unsupported capability must never silently degrade to unsafe last-writer-wins editing.

Acceptance additions

• Both existing coordination implementations are inventoried and regression-tested before extraction/replacement.
• Security migration admission remains fail-closed and authoritative.
• AI leadership is composed/replaced deliberately rather than duplicated indefinitely.
• Generic coordination owns primitives, not subsystem business/security policy.
• Browser capability limitations are surfaced through pwa(capabilities): establish progressive-enhancement registry, browser support tiers & runtime diagnostics #489.
• No BroadcastChannel message becomes durable project truth.
• Lock namespace/version ownership is documented to avoid collisions across subsystems.