Migrate browser code and tests to strict TypeScript

1 files changed, 128 insertions, 0 deletions

diff --git a/docs/TYPESCRIPT.txt b/docs/TYPESCRIPT.txt
new file mode 100644
index 0000000..d50ea95
--- /dev/null
+++ b/docs/TYPESCRIPT.txt
@@ -0,0 +1,128 @@
+Copyright (C) 2026 Doan Luu Duc Tai <doan@luuduct.ai>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+TYPESCRIPT BROWSER TOOLCHAIN
+
+    All first-party browser logic and browser automation are TypeScript.
+    Rust still implements cryptography, the API, backups, and deployment.
+    Browsers execute JavaScript generated by TypeScript; TypeScript adds
+    compile-time checks and does not replace validation of untrusted input.
+
+SOURCE LAYOUT
+
+    crates/chat-server/web/app.ts
+        Interface, session state, history, downloads, and API validation.
+    crates/chat-server/web/worker.ts
+        One-shot cryptographic worker; its lifetime ends after each request.
+    crates/chat-crypto/browser/wasi.ts
+        Restricted browser WASI host for the unchanged Rust/OpenSSL module.
+    crates/chat-crypto/browser/protocol.d.ts
+        Shared API and cryptographic request/response contracts. Declarations
+        emit no JavaScript and are checked for both browser environments.
+    crates/chat-crypto/tests/browser.ts
+        Real WebAssembly compatibility, entropy, and capability tests.
+    crates/chat-server/tests/browser.ts
+        Complete browser chat and recovery tests, including GNU LibreJS.
+    crates/chat-server/tests/progress.ts
+        Download progress and failure tests, including GNU LibreJS.
+    tests/browser-support.ts
+        Checked fixture parsing and typed browser-automation helpers.
+
+    tsconfig.json supplies shared strict checks. The browser, worker, and
+    test configurations use separate DOM, WebWorker, and Node environments.
+    Production browser builds cannot accidentally rely on Node APIs.
+    strict, unchecked indexed access, exact optional properties, unused
+    declarations/parameters, implicit returns, switch fallthrough, implicit
+    overrides, and indexed-property access are checked. Type errors prevent
+    emission. No suppression directives or untyped escape hatches are used.
+
+DEVELOPMENT
+
+    Install Node >=22.18.0 and npm on the development machine. Root package.json
+    and package-lock.json pin TypeScript 7.0.2, Playwright 1.64.1, Node type
+    declarations, platform compiler packages, and their integrity hashes.
+    There are no npm application/runtime dependencies. TypeScript and
+    Playwright use the Apache License, Version 2.0; Node declarations and
+    undici-types use the Expat License. Original notices remain in the
+    installed packages. SPDX identifiers retain their required spelling.
+
+    Build and check all TypeScript, including browser tests:
+
+        npm run build
+
+    infra/chat/build-typescript.sh installs the locked development packages
+    with lifecycle scripts disabled, checks all three configurations, and
+    emits JavaScript under var/build/typescript. The npm cache stays under
+    .tools/npm-cache. node_modules and generated outputs are ignored by Git.
+    Generated scripts are readable and unminified; no bundler is needed.
+
+    cargo stack check includes this build, then the strict Rust checks and
+    cargo-about license generation. cargo stack release builds TypeScript
+    before packaging the complete production release.
+
+    Check without installing packages or emitting output after npm run build:
+
+        npm run check
+
+    Fetch the pinned Playwright browser versions once:
+
+        PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" node_modules/.bin/playwright install chromium firefox
+
+    After building the native chat server and WASI module:
+
+        PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:crypto
+        PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:chat
+        PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:progress
+        CHAT_LIBREJS=1 PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:chat
+        CHAT_LIBREJS=1 PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:progress
+
+    LibreJS variants require the signed Mozilla extension at
+    .tools/librejs.xpi as documented in CHAT-APPLICATION.txt. The complete
+    chat test proves LibreJS is active and rejects an unlicensed control.
+    Run chat variants sequentially because they share the default test port.
+    npm audit checks the development dependency lock separately from
+    cargo-deny; it does not audit Rust, browser-delivered code, or containers.
+
+RELEASES, SOURCE, AND LIBREJS
+
+    Generated app.js, worker.js, and wasi.mjs keep their existing public URLs.
+    They preserve the AGPL headers and recognized @license/@license-end
+    markers. The JavaScript license table links each generated file to its
+    complete corresponding TypeScript and Rust source archive. Classic scripts
+    and importScripts remain in use for LibreJS compatibility; the migration
+    introduces no runtime module loader or third-party browser scripts.
+
+    Local native-server tests serve generated files from var/build/typescript.
+    The release packages those files into bin/chat/web and bin/chat/wasi.mjs.
+    Containers serve the packaged files. HTML and CSS are copied explicitly,
+    so TypeScript source files are not substituted for executable JavaScript.
+    /SOURCE.tar.gz includes TypeScript, shared declarations, all compiler
+    configurations, the npm lock, tests and build scripts, together with the
+    existing Cargo-vendored dependencies and verified OpenSSL source archive.
+    Node/npm/TypeScript are general-purpose development tools, documented and
+    pinned here; their installed copies and downloaded browsers are excluded.
+
+    Source exports, releases, and backups carry the root npm manifests and
+    TypeScript configurations. Release activation and restored prebuilt images
+    need no Node, npm, TypeScript, or Rust installation on the destination.
+    They retain the single private root .env and existing persistent data.
+    The source archive excludes that .env, credentials, runtime databases,
+    exports, .git, node_modules, and build/cache directories. The root
+    .env.example remains public. No additional environment file is introduced.
+
+    Test the actual generated JavaScript after any compiler upgrade. Static
+    types cannot guarantee privacy, security, or LibreJS recognition. Browser
+    storage restrictions, protocol validation, and algorithm choices continue
+    to be enforced by the existing runtime and Rust implementation.