# Publishing Toolchain

## Canonical environment

The project is tested in Ubuntu WSL with the checkout, `node_modules`, npm
cache, TeX work, browser profiles, `build/`, and `dist/` on the Linux ext4
filesystem. When using WSL, run Node, npm, Git, TeX, Python, and Chrome
automation inside Linux rather than against a Windows or UNC-mounted copy.

Use Node 24 from `.nvmrc` (minimum 24.12, when type stripping became stable)
and npm 11. The publication tools intentionally contain erasable TypeScript
syntax only, so Node executes their `.ts` entry points directly while the
project-local TypeScript compiler performs the strict check separately.

```sh
cd <repo-root>
nvm use
npm ci
npm test
```

TypeScript 7.0.2 is the production `typescript` package. This repository does
not use compiler APIs, embedded-language plugins, or typescript-eslint, so it
does not need the transitional TypeScript 6 compatibility package. The strict
configuration is in `tsconfig.json` and includes NodeNext ESM,
`erasableSyntaxOnly`, `verbatimModuleSyntax`, exact optional properties,
unused-code checks, and no emit.

## Commands

```sh
npm test                    # TypeScript 7 plus shell/JSON/tooling validation
npm run generate:visuals    # Regenerate tracked Rethinking Reality SVG/PNG art
npm run build:covers        # Rebuild cover caches
npm run build               # Build every manifest-listed book and format
```

The renderers require Google Chrome or Chromium installed inside WSL. Set
`CHROME_BIN` to an absolute Linux executable path only when the standard
`/usr/bin/google-chrome` or `/usr/bin/chromium` locations are unavailable.
There is no application server, reserved port, file watcher, or localhost
binding in this repository; the bounded local smoke path is `npm test` followed
by a cached cover-generator invocation or the full publication build.

## TypeScript scope

The genuine JavaScript tooling surfaces are now strict TypeScript:

- companion-cover HTML/PDF/JPG generation;
- orientation concept-diagram generation;
- Ancient Near East map generation; and
- the shared reusable Chrome renderer.

TypeScript migration is intentionally not applicable to the canonical TeX and
Markdown manuscripts, localization prose, Python orchestration, shell
publication pipeline, shared TeX style, fonts, or source data. Those surfaces
retain their owning languages. In particular, no manuscript or localized prose
is generated, translated, or rewritten by the TypeScript tooling.

## Measured performance and fidelity

Measurements were taken in Ubuntu WSL2 on 2026-07-16 with 32 logical CPUs,
Node 24.15.0, npm 11.12.1, Chrome, and warm npm package data. Generated files
were written on ext4. Full builds forced both cover systems cold and disabled
the optional external text sync.

| Lane | Before | After | Result |
| --- | ---: | ---: | ---: |
| 18 orientation PNG screenshots | 65.90 s | 4.79 s | 92.7% faster (13.8x) |
| 18 companion covers, two PDF sizes plus JPG | 85.08 s | 40.29 s | 52.6% faster (2.1x) |
| Full 21-entry, 69-artifact publication build | 212.76 s | 193.46 s | 9.1% faster |

The speedup comes from sharing a pinned Playwright/Chrome process instead of
launching a new `npx`/Chrome process tree for every image or PDF. The optimized
orientation output was byte-for-byte identical to all 18 outputs from the old
Playwright CLI on the same machine. All 18 retail cover JPGs were byte-for-byte
identical, and all 36 retail/letter PDF pages had zero changed raster pixels.

The before/after full builds produced the same 69 relative output paths. All 24
PDFs retained identical page counts, page geometry, and extracted text; all 21
JPGs were byte-for-byte identical; and all entries in all 24 EPUBs were
identical after normalizing only their expected build timestamps in
`content.opf`. These are rendering optimizations only: canonical prose, fonts,
layout, pagination, and publication quality gates are unchanged.