# Source restoration, build and replacement

## Restore the complete snapshots

Use Python 3.12 or newer. From this material directory:

```sh
python3 restore-source.py --output /tmp/subneat-source-restored
```

The output directory must not already exist. The script checks each original
archive's SHA-256, validates its paths, and restores the nested source tree.
It never downloads or executes upstream code. If downloading split files, keep
every numbered part together in this directory with `downloads.json`; the helper
checks every part and the rejoined archive before extraction. Alternatively join
parts in their listed order with a binary concatenation tool and verify the full
archive hash from `source-lock.json`.

The result includes `jassub/lib/{brotli,freetype,fribidi,harfbuzz,libass}`,
FreeType's `subprojects/dlg`, `toolchain/emscripten` with its three test
submodules, and `npm-package`. Upstream source files and license texts are not
rewritten. The restore directory has no fabricated Git history.

## Verified native build route

On 2026-10-25 both native variants were compiled from the supplied snapshots in
a Linux ARM64 container on Mac M4. The first archive-only build matched npm in
120 sampled browser frame pairs but differed in embedded date/time and libass
version-label data. Restoring that generated metadata and recompiling libass /
relinking produced both full npm WASM files byte for byte. The regenerated raw
legacy glue and its TypeScript-transformed npm form matched as well.

Download `native-rebuild-recipe.tar.gz` and follow its README. It includes the
digest-pinned Dockerfile, compilation script, metadata restoration script,
recorded metadata, system package versions and binary comparisons. The final
verification summary is `native-rebuild.json`. It records the distinction
between the two passes and does not claim a fabricated Git working tree.

## Upstream build entry points

The original JASSUB `Dockerfile` names `docker.io/emscripten/emsdk:6.0.4`.
`Makefile` and `functions.mk` specify all native flags and dependency order.
`build/patches/freetype/0002-disable-pthread.patch` and
`build/patches/harfbuzz/0001-force_disable_pthread.patch` are applied by those
scripts. The input C++ wrapper is `src/JASSUB.cpp`; Emscripten pre-JavaScript is
also under `src/`. Both legacy and modern variants must be built.

After reviewing the upstream scripts, with Docker available, this is the upstream
build route from the restored `jassub` directory:

```sh
docker build -t subneat-jassub-builder .
docker run --rm -v "$PWD:/code" subneat-jassub-builder bash -c 'make && env MODERN=1 make'
```

These commands may download the toolchain image and operating system packages,
consume substantial disk/CPU resources, and execute upstream build scripts.
The verified recipe uses a digest-pinned image and four build jobs; the generic
commands above show the upstream route. The `&&` above stops if the first build
fails; the original Dockerfile uses `;`. Some autogen scripts
may use Git metadata for version information. If the archive route requires that
metadata, obtain an ordinary upstream checkout at the exact commit and restore
the submodules at the exact revisions in `source-lock.json`. Do not substitute
current branch heads. No project-specific Git reset/clean targets are needed.

Emscripten's source/runtime snapshot is included for inspection and modification;
the Docker image supplies its precompiled LLVM/Binaryen toolchain. The upstream
Dockerfile does not lock the image digest or operating system packages; our
verified recipe pins the base digest and records the package versions actually
used. A different environment or archive-only build may differ; byte equality
is established for the recorded recipe with the metadata-restoration pass.

## TypeScript and browser packaging

The original npm archive includes the SDK sources, compiled SDK JavaScript and
Emscripten glue. JASSUB's `package.json` and `tsconfig.json` describe its SDK
build. The glue match was checked with TypeScript 5.9.3:

```js
ts.transpileModule(glueSource, {
  fileName: 'jassub-worker.js',
  compilerOptions: {
    target: ts.ScriptTarget.ESNext,
    module: ts.ModuleKind.ESNext,
    allowJs: true,
    sourceMap: true,
  },
}).outputText;
```

Subtitle Tools does not change the two native WASM binaries or Emscripten glue.
Its `scripts/prepare-assets.mjs` copies the npm `dist` tree and bundles these two
SDK entries using esbuild 0.28.2:

| Input | Output | Options |
| --- | --- | --- |
| `dist/jassub.js` | `jassub.js` | bundle, ESM, browser, ES2022, minify |
| `dist/worker/worker.js` | `worker/worker.js` | same; keep `../wasm/jassub-worker.js` external |

The external glue keeps Emscripten's relative worker URLs intact. Complete npm
sources are included, so this packaging does not depend on minified code as the
only available form. Retain the relative SDK, worker, glue and WASM layout.

## Use a compatible modified renderer

You may inspect and modify the library sources and replace the renderer subject
to their applicable licenses. This notice adds no restriction on modification,
reverse engineering for debugging those modifications, or use of a compatible
replacement. There is no runtime signature or integrity gate preventing a
compatible WASM replacement in a locally served copy.

In a saved static site, the renderer lives at `/vendor/jassub-2.5.18/`. Replace
both `wasm/jassub-worker.wasm` and `wasm/jassub-worker-modern.wasm` together with
the corresponding `wasm/jassub-worker.js`; replace the SDK worker and SDK entry
as well if the API changes. Serve the copy over HTTP with the required
cross-origin isolation and correct WASM MIME type. HTTP caching or a modern SIMD
selection can otherwise leave an old or alternate variant in use.

For a source build of this site, the provenance checks intentionally reject
unreviewed library bytes. After making a modified library, update the local
library package, source archive records, notices and expected hashes to describe
your modified version, then rebuild. These are build-time provenance checks, not
an authorization requirement or a runtime lock. Keep changes and their dates
documented, preserve upstream attributions, and test the public SDK API,
multithread and fallback paths, seeking, animation, fonts, retry and disposal.

This document supplies the verified technical route and its limits. It does not
claim every deployment, real-device, performance or legal condition has passed.