thrunium 0.0.0-stage → 1.2.0-rc.2

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# Thrunium
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official Thrungames game engine — a single-file, dependency-free browser
+game library.
+
+## Usage
+
+```html
+<script src="https://cdn.thrungames.com/thrunium/v1.1.0/thrunium.js"></script>
+<!-- or the minified build (with a source map): -->
+<script src="https://cdn.thrungames.com/thrunium/v1.1.0/thrunium.min.js"></script>
+<script>
+  var v = new THRUNIUM.Vector(10, 10);
+</script>
+```
+
+The [CDN image](#cdn-image) serves the files at its root (`/thrunium.js`,
+`/thrunium.min.js`). The CDN maps them under `/thrunium/v<version>/`, and
+`https://cdn.thrungames.com/thrunium/versions.json` lists the published versions.
+
+The engine attaches itself to the global `THRUNIUM` namespace. It has no runtime
+dependencies. The source is TypeScript in `src/`; `npm run build` bundles it with
+esbuild into a classic (non-module) script, `dist/thrunium.js` (readable) and
+`dist/thrunium.min.js` plus `dist/thrunium.min.js.map` (minified). Both start
+with a `/*! THRUNIUM v<version> | (c) Infobits ApS | MIT License */` banner and target ES2017.
+
+> The `Storage` user-token members (`reqToken`, `userToken`, `timeout`,
+> `loginPopup`, `accessRequested`, `_options`, `setReqToken`, `reqUserToken`,
+> `_receiveMessage`, `request`) are work in progress: they talk to endpoints that no
+> longer exist and will change when authentication is added.
+
+## Package and CLI
+
+The engine is also on npm as `thrunium` (Node 24 or newer):
+
+```bash
+npx thrunium init my-game   # new TypeScript project; add --js for JavaScript
+cd my-game && npm run dev   # init installs for you; use pnpm dev, yarn dev or bun run dev
+```
+
+```ts
+import { Game } from 'thrunium';
+```
+
+`exports` in `package.json`:
+
+| Import | Gives you |
+|---|---|
+| `thrunium` | the engine as an ES module, with types |
+| `thrunium/thrunium.js` | the readable classic script |
+| `thrunium/thrunium.min.js` | the minified classic script |
+| `thrunium/package.json` | the package manifest |
+
+Commands (`thrunium --help`, `--version`):
+
+| Command | Options |
+|---|---|
+| `thrunium dev` | `--port <n>` (default 3000, tries the next 10 ports if busy), `--host <name>` (default `localhost`), `--no-open` |
+| `thrunium build` | `--out <dir>` (default `dist`), `--engine cdn\|bundle` |
+| `thrunium init [dir]` | `--js` (TypeScript by default), `--pm npm\|pnpm\|yarn\|bun` (default: the one that ran it, else npm), `--no-install`; the folder must be empty. Installs by default; if that fails the project is kept and the command is printed |
+
+A project needs no `index.html`: without one, `dev` and `build` generate the page
+from `game.json` (`entry`, else the first of `game.ts`, `game.js`, `src/game.ts`,
+`src/game.js`; the title is `name`, else the folder name). A hand-written
+`index.html` is used as written, and having both it and `entry` is an error.
+`import './style.css'` from game code is bundled and linked, with `url()` fonts and
+images; remote `@import` stays remote.
+
+`dev` never uses the CDN. For a project with a module entry
+(a generated page, or `<script type="module" src=...>` importing `thrunium`), `build` has two engine
+modes. `cdn` (the default) adds a script tag for
+`https://cdn.thrungames.com/thrunium/v<version>/thrunium.min.js` with a `sha384`
+integrity hash, pinned to the installed version. It fails, and leaves the output
+folder alone, if that version is not on the CDN or the CDN's file differs from
+the installed one (for example with `npm link` or local changes). `bundle` copies
+`thrunium.min.js` next to the game. Set `"thrunium": { "engine": "bundle" }` in
+the game's `package.json` to make it the default; `--engine` wins. A script-tag
+folder (no module entry) keeps its own Thrunium tag: `build` copies it unchanged,
+without a CDN check, and `--engine bundle` is an error. The
+`THRUNIUM_CDN_URL` environment variable replaces the CDN base URL (for tests).
+See `docs/guides/getting-started.md` and `docs/guides/dev-and-build.md` for the full guides.
+
+The release stages the npm package after the CDN publish succeeds, from the
+tarball inside the scanned image. Prereleases (`1.2.0-rc.1`) go under the `next`
+dist-tag, stable versions under `latest`. It needs the `NPM_TOKEN` Actions secret:
+an npm granular token with "Read and write (stage only)" on `thrunium` and no
+organization access. npm does not let CI tokens publish directly, so the version
+goes live only when a maintainer approves it with 2FA:
+
+```bash
+npm stage list thrunium               # the id is also in the release log
+npm stage approve <id> --otp <code>
+```
+
+It refuses to stage if `license` is missing from `package.json`.
+
+## Development
+
+Requires Node 24.
+
+```bash
+npm ci
+npm run build         # dist/thrunium.js, dist/thrunium.min.js, source map
+npm test              # typecheck + build + unit and bundle tests, 90% line coverage
+npm run coverage      # unit and bundle tests with coverage (after a build)
+npm run test:browser  # real-Chromium tests (builds first)
+npm run test:games    # smoke-tests the sibling game repos against the built engine
+```
+
+`VERSION=1.2.3 npm run build` stamps another version into the banner and
+`THRUNIUM.version`; it defaults to `version` in `package.json` and must look like
+`1.2.3` or `1.2.3-rc.1`.
+
+`test:games` needs the game repositories checked out next to this one. Set
+`GAMES_ENGINE_FILE` to point it at a different engine file (for example a 1.0.0
+copy) to compare behavior.
+
+Browser tests use Playwright's Chromium, or the system Chromium when
+`CHROME_BIN` is set (as on the arm64 CI runner, where `--no-sandbox` is added
+because it runs as root). Without `CHROME_BIN`, `test:browser` and `test:games`
+need Playwright's Chromium installed once with `npx playwright-core install chromium`.
+
+## Docs
+
+`VERSION=1.2.3 npm run docs` writes the versioned docs to `dist/docs/`: guides from
+`docs/guides/` (listed in `docs/guides.json`) and one reference page per part of the
+`THRUNIUM` global, generated from the doc comments in `src/`. It fails if a public
+member has no description. The release image carries them at `/usr/share/thrunium/docs`
+(never served over HTTP) and the release publishes them to the CDN next to the JS.
+
+## CDN image
+
+The engine is distributed as a hardened static image serving the file over HTTP.
+
+```bash
+docker build --build-arg VERSION=1.1.0 -t thrunium-game-engine:dev .
+
+docker run --read-only --tmpfs /tmp \
+  --cap-drop ALL --security-opt no-new-privileges \
+  -p 8080:8080 thrunium-game-engine:dev
+```
+
+`VERSION` is required and is stamped into the bundle. The image builds the
+bundle in a Node 24 stage and serves only the output.
+
+The hardening flags above are supplied by the operator and cannot be baked into
+the image — run it this way in every environment.
+
+| Route | Response |
+|---|---|
+| `GET /thrunium.js` | the engine, `Cache-Control: public, max-age=3600`, CORS `*` |
+| `GET /thrunium.min.js` | the minified engine, same headers |
+| `GET /thrunium.min.js.map` | its source map (`application/json`), same headers |
+| `GET /healthz` | `200 ok` |
+| anything else | `404` |
+
+The container listens on **8080** as **UID 101**. It never runs as root.
+
+## Releases
+
+Publishing a release on Forgejo builds the image for `linux/arm64` (the
+cluster's architecture), scans it, and pushes it to Scaleway Container
+Registry:
+
+```
+rg.fr-par.scw.cloud/infobits/thrunium-game-engine:<version>
+rg.fr-par.scw.cloud/infobits/thrunium-game-engine:latest
+```
+
+The release tag must match the `version` in `package.json`, or the workflow
+fails before building.
+
+It then publishes the image's files to the `infobits-thrunium-cdn` bucket, which
+`cdn.thrungames.com` serves, so a release needs no deploy step:
+
+| CDN path | Holds |
+|---|---|
+| `/thrunium/v<version>/` | that version, never changed once published |
+| `/thrunium/v<major>/`, `/thrunium/v<major>.<minor>/` | the newest release in that range |
+| `/thrunium/latest/` | the newest release |
+| `/thrunium/versions.json` (also `/thrunium/`) | JSON list of versions, aliases and files |
+
+Prereleases (`1.2.0-rc.1`) get an exact-version path but never an alias.
+Publishing a version again is a no-op if its files are unchanged, and fails if
+they differ. To publish an already-released version (for example, one released
+before the bucket existed), dispatch `publish-cdn.yml` with its version:
+
+```bash
+fj actions dispatch publish-cdn.yml main -I version=1.1.0
+```
+
+Both workflows need the `THRUNIUM_CDN_ACCESS_KEY` and `THRUNIUM_CDN_SECRET_KEY`
+Actions secrets.
+
+## License
+
+MIT, see [LICENSE](LICENSE). The names "Thrunium" and "ThrunGames" are
+trademarks of Infobits ApS: [TRADEMARKS.md](TRADEMARKS.md) explains how you
+can use them.