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.

    eslint.config.ts and tsconfig.tools.json supply the typed lint-tool checks.
    src/app and crates/chat-server/src/app contain the private Rust CLI
    implementations; their parser and runtime changes are recorded in LINTING.txt.

    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.
    ESLint 10.14.0 and typescript-eslint 8.72.1 provide typed strict linting.
    TypeScript 6.0.3 supplies their supported JavaScript API; the pinned native
    TypeScript 7.0.2 alias remains the emitting compiler. Both check the sources.
    LINTING.txt documents the advisory-driven minimatch override.
    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 browser/worker/test/tool configurations,
    typed ESLint, both compiler versions, and npm advisories, then
    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.

    Recheck without reinstalling packages 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 development dependencies as part of npm run check and the
    Cargo check/release path. It does not audit Rust, browser-delivered code, or
    containers; cargo-deny remains the separate strict Rust dependency audit.

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.