Skip to content

Commit 484ba93

Browse files
committed
Publish the JavaScript player to npm as @wildwinter/game-subtitles.
players/player-js becomes a real package: ES module exports with hand-written TypeScript declarations for the public API, files limited to dist, and the version kept in step with the repository's releases. The build writes dist/ for the package and still copies the bundles to build/player-js for the zips and the demo. npm test type-checks the declarations under strict mode, and npm run check:package checks what npm pack ships, installs the tarball in a scratch project, runs it in Node, and type-checks a consumer. CI runs it. publish-npm.yml publishes each GitHub Release to npm with trusted publishing (OIDC) and provenance, on npm 11 (npm 12.0.0's provenance is broken, npm/cli#9722). The first version, 0.3.1, was published by hand, since npm only lets a package trust a workflow once it exists.
1 parent c0c1afb commit 484ba93

14 files changed

Lines changed: 564 additions & 32 deletions

File tree

‎.github/workflows/build.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ jobs:
3333
- name: Test
3434
run: npm test
3535

36+
- name: Check the npm package
37+
run: npm run check:package --prefix players/player-js
38+
3639
# Godot runs headless with no licence, so the addon is tested here for real, as in the
3740
# patter and storylets ports workflows. Unity and Unreal are not: their players need the engines.
3841
godot:

‎.github/workflows/publish-npm.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: Publish to npm
2+
3+
# Publishes the JavaScript player (players/player-js) to npm as @wildwinter/game-subtitles
4+
# whenever a GitHub Release is published. `npm run release` publishes that Release, and sets
5+
# the package's version to match, so each release reaches npm at the same version.
6+
#
7+
# Authenticates with npm TRUSTED PUBLISHING (OIDC): the package trusts this repository and
8+
# this workflow file on npmjs.com, so no npm token is stored anywhere, and npm adds provenance
9+
# automatically. That needs `id-token: write`, Node 22.14 or later, and npm 11.5.1 or later.
10+
# npm only lets a package trust a workflow once the package exists, so its first version was
11+
# published by hand.
12+
#
13+
# `workflow_dispatch` reruns the publish for the version on main, for when a release's own
14+
# run failed. A version that is already on npm is skipped, never republished.
15+
16+
on:
17+
release:
18+
types: [published]
19+
workflow_dispatch:
20+
21+
permissions:
22+
contents: read
23+
id-token: write # npm trusted publishing (OIDC) and provenance
24+
25+
jobs:
26+
publish:
27+
runs-on: ubuntu-latest
28+
defaults:
29+
run:
30+
working-directory: players/player-js
31+
steps:
32+
- uses: actions/checkout@v4
33+
34+
- uses: actions/setup-node@v4
35+
with:
36+
node-version: 22
37+
cache: npm
38+
cache-dependency-path: players/player-js/package-lock.json
39+
40+
# Pinned to the 11.x line on purpose: npm 12.0.0 ships a broken provenance path
41+
# ("Cannot find module 'sigstore'") that aborts every publish, npm/cli#9722.
42+
- name: OIDC-aware npm (11.5.1 or later; pin off the broken npm 12.x)
43+
run: npm install -g npm@11
44+
45+
# No token anywhere: npm's OIDC detection handles auth by itself.
46+
- run: echo "# auth via npm trusted publishing (OIDC) - no token" > ~/.npmrc
47+
48+
- run: npm ci
49+
50+
- name: The package version matches the release
51+
if: github.event_name == 'release'
52+
run: |
53+
version=$(node -p "require('./package.json').version")
54+
[ "v$version" = "$GITHUB_REF_NAME" ] || { echo "package.json says $version but the release is $GITHUB_REF_NAME"; exit 1; }
55+
56+
- run: npm run build
57+
- run: npm test
58+
- run: npm run check:package
59+
60+
- name: Publish @wildwinter/game-subtitles
61+
run: |
62+
version=$(node -p "require('./package.json').version")
63+
if npm view "@wildwinter/game-subtitles@$version" version >/dev/null 2>&1; then
64+
echo "@wildwinter/game-subtitles@$version is already on npm; skipping."
65+
else
66+
npm publish
67+
fi

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,3 +100,6 @@ players/player-unity/**/*.mdb.meta
100100

101101
# Godot
102102
players/player-godot/.godot/
103+
104+
# npm package: the JS build copies the repository's LICENSE in
105+
players/player-js/LICENSE

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ Notable changes to Game Subtitles. Each version is published as a [GitHub Releas
44

55
## [Unreleased]
66

7+
### Added
8+
9+
- The JavaScript player is on npm as `@wildwinter/game-subtitles`, with TypeScript declarations for its public API. Each release publishes it at the release's version, from CI with provenance.
10+
711
## [0.3.1] - 2026-10-04
812

913
### Fixed

‎README.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,9 @@ Pre-built releases are available in the [Releases](https://github.com/wildwinter
5757
| `game-subtitles-godot-v{version}.zip` | Godot addon + Windows & macOS preprocessor binaries | **Godot developers** |
5858
| `game-subtitles-lib-v{version}.zip` | C# `PreprocessorLib.dll` + all players | Custom tooling / calling the preprocessor as a library |
5959

60-
Download the zip for your platform. Each contains everything you need with no additional dependencies. [CHANGELOG.md](CHANGELOG.md) lists what changed in each version.
60+
Download the zip for your platform. Each contains everything you need with no additional dependencies. The JavaScript player is also on npm as [`@wildwinter/game-subtitles`](https://www.npmjs.com/package/@wildwinter/game-subtitles), published from each release. [CHANGELOG.md](CHANGELOG.md) lists what changed in each version.
6161

62-
To make a release (maintainers only), write the notes under `## [Unreleased]` in `CHANGELOG.md`, commit them, and run `npm run release -- <version>` on a Mac. Add `--dry-run` to check everything first without changing anything. The script tests, builds, signs and notarises the macOS preprocessor, tags, pushes to `main`, and publishes the GitHub Release. Its tests include the Godot addon's, and the Unity and Unreal tests in each engine that is installed; a check whose engine is missing says so and is skipped. See `scripts/release.mjs` and `scripts/macos.mjs` for the signing setup it expects.
62+
To make a release (maintainers only), write the notes under `## [Unreleased]` in `CHANGELOG.md`, commit them, and run `npm run release -- <version>` on a Mac. Add `--dry-run` to check everything first without changing anything. The script tests, builds, signs and notarises the macOS preprocessor, tags, pushes to `main`, and publishes the GitHub Release. Its tests include the Godot addon's, and the Unity and Unreal tests in each engine that is installed; a check whose engine is missing says so and is skipped. Publishing the GitHub Release starts `.github/workflows/publish-npm.yml`, which publishes the JavaScript player to npm at the same version. See `scripts/release.mjs` and `scripts/macos.mjs` for the signing setup it expects.
6363

6464
---
6565

@@ -211,11 +211,13 @@ IReadOnlyList<string> langs = SubtitlePreprocessor.SupportedLanguages;
211211

212212
### JavaScript Player (`players/player-js`)
213213

214-
Copy `game-subtitles-player.js` from the `game-subtitles-js-v{version}.zip` release into your project. The zip also contains the preprocessor binaries (`game-subtitles-preprocess` / `game-subtitles-preprocess.exe`) — place these wherever is convenient on your machine (e.g. somewhere on your `PATH`).
214+
Install it from npm as [`@wildwinter/game-subtitles`](https://www.npmjs.com/package/@wildwinter/game-subtitles). It is ES modules, with TypeScript types included, and its version matches the release it came from:
215215

216-
| File | Format |
217-
| --- | --- |
218-
| `game-subtitles-player.js` | IIFE — `window.GameSubtitles` |
216+
```bash
217+
npm install @wildwinter/game-subtitles
218+
```
219+
220+
Or, for a plain `<script>` tag, copy `game-subtitles-player.js` from the `game-subtitles-js-v{version}.zip` release into your project. It defines a `window.GameSubtitles` global with the same exports, and the npm package carries the same file as `@wildwinter/game-subtitles/iife`. The zip also contains the preprocessor binaries (`game-subtitles-preprocess` and `game-subtitles-preprocess.exe`); put these wherever is convenient on your machine, for example somewhere on your `PATH`.
219221

220222
#### Real-world usage
221223

@@ -224,7 +226,7 @@ Here is how you would wire this up in a typical game with a DOM-based subtitle o
224226
**1. Set up the player once, pointing it at your subtitle element.**
225227

226228
```javascript
227-
import { SubtitlePlayer, DomRenderer } from './game-subtitles-player.esm.js';
229+
import { SubtitlePlayer, DomRenderer } from '@wildwinter/game-subtitles';
228230

229231
const subtitleEl = document.getElementById('subtitle-bar');
230232
const renderer = new DomRenderer(subtitleEl);
@@ -274,7 +276,7 @@ That is all. The player handles multi-page display, proportional timing across p
274276
If your subtitle overlay is drawn on a canvas rather than DOM elements, swap in the `CanvasRenderer`:
275277

276278
```javascript
277-
import { SubtitlePlayer, CanvasRenderer } from './game-subtitles-player.esm.js';
279+
import { SubtitlePlayer, CanvasRenderer } from '@wildwinter/game-subtitles';
278280

279281
const canvas = document.getElementById('game-canvas');
280282
const renderer = new CanvasRenderer(canvas, '16px Arial');
@@ -297,7 +299,7 @@ player.start({ text, duration, onComplete, characterName, characterNameColor, li
297299
player.start({ text, onComplete });
298300

299301
// The same estimate, as a standalone function. All options are optional.
300-
import { estimateDuration } from './game-subtitles-player.esm.js'; // or GameSubtitles.estimateDuration from the IIFE build
302+
import { estimateDuration } from '@wildwinter/game-subtitles'; // or GameSubtitles.estimateDuration from the script-tag build
301303
const seconds = estimateDuration(text, { charsPerSecond: 14, minSeconds: 1.5, maxSeconds: 18 });
302304

303305
// Call once per frame from your game loop

‎players/player-js/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# @wildwinter/game-subtitles
2+
3+
The JavaScript player from [Game Subtitles](https://github.com/wildwinter/game-subtitles): give it a subtitle and how long it should stay up, and it wraps the text to fit your subtitle box, hyphenates long words in the right places, splits the text into pages, and shows each page for its share of the time.
4+
5+
It measures text in your actual font at runtime, so it copes with any font, box size, or number of lines, including ones the player changes in the settings. Hyphenation comes from soft hyphens (U+00AD) that the Game Subtitles **preprocessor** adds to your localised strings at build time, using the TeX hyphenation rules for each language. The preprocessor, and players for Unity, Unreal, and Godot that behave the same way, are in the [GitHub repository](https://github.com/wildwinter/game-subtitles).
6+
7+
## Install
8+
9+
```bash
10+
npm install @wildwinter/game-subtitles
11+
```
12+
13+
The package is ES modules, with TypeScript types included. For a plain `<script>` tag there is also a build that defines a `GameSubtitles` global, at `@wildwinter/game-subtitles/iife` (`dist/game-subtitles-player.js`).
14+
15+
## Usage
16+
17+
```javascript
18+
import { SubtitlePlayer, DomRenderer } from '@wildwinter/game-subtitles';
19+
20+
// Once: a renderer for your subtitle element, and a player that uses it.
21+
const renderer = new DomRenderer(document.getElementById('subtitle-bar'));
22+
const player = new SubtitlePlayer({ renderer, maxLines: 2 });
23+
24+
// For each line of dialogue:
25+
player.start({
26+
text, // a string from the preprocessor's output
27+
duration: 4.5, // seconds; leave it out to estimate one from the text
28+
characterName: 'Tam', // optional: shown as "Tam: " at the start of every page
29+
characterNameColor: '#f0cc88', // optional
30+
lineColor: '#ffffff', // optional
31+
onComplete: () => player.stop(), // the last page stays up until you stop the player
32+
});
33+
34+
// Every frame, with the seconds since the last frame:
35+
player.tick(deltaSeconds);
36+
```
37+
38+
`start()` lays out the text and shows the first page straight away, stopping any subtitle already playing. Create the player and renderer once and reuse them for every line.
39+
40+
### Without a duration
41+
42+
If you leave out the duration, or pass 0 or less, the player estimates one with `estimateDuration`, which you can also call yourself:
43+
44+
```javascript
45+
import { estimateDuration } from '@wildwinter/game-subtitles';
46+
47+
const seconds = estimateDuration(text, { charsPerSecond: 14, minSeconds: 1.5, maxSeconds: 18 });
48+
```
49+
50+
It counts characters (Unicode code points, not counting soft hyphens), divides by the reading rate, and clamps the result; the options shown are the defaults. Counting characters rather than words means languages written without spaces, such as Chinese and Japanese, still get an estimate. The Unity, Unreal, and Godot players use the same rule, so the same text gets the same estimate everywhere.
51+
52+
## Renderers
53+
54+
**`DomRenderer(element)`** draws each line as a `<p>` inside `element`, and measures text in that element's own computed font, so it follows your stylesheet. The character name is a `<span>` with the class `gs-character-name` (exported as `CHARACTER_NAME_CLASS`); style that class and the renderer measures with it too. If you change the element's font at runtime, call `renderer.invalidateFont()`.
55+
56+
**`CanvasRenderer(canvas, font, lineHeight?, characterNameFont?)`** draws onto a canvas. `font` and `characterNameFont` are CSS font strings such as `'16px Arial'`; `lineHeight` defaults to 1.2 times the font size.
57+
58+
**Your own renderer** can be any object with these four methods, so the player works with any engine or drawing layer:
59+
60+
```typescript
61+
import type { SubtitleRenderer } from '@wildwinter/game-subtitles';
62+
63+
const renderer: SubtitleRenderer = {
64+
measureLineWidth(text, useCharacterNameFont) { /* the width of text in your font */ },
65+
getContainerWidth() { /* the width available for a line */ },
66+
render(lines, characterContext) { /* show the lines; draw "Name: " first if characterContext has a name */ },
67+
clear() { /* remove the subtitle */ },
68+
};
69+
```
70+
71+
`measureLineWidth` must count trailing spaces, because the player measures `"Name: "` to reserve room for the character name.
72+
73+
## Layout on its own
74+
75+
The functions the player uses are exported too:
76+
77+
```javascript
78+
import { wrapAndPaginate, allocateTimings } from '@wildwinter/game-subtitles';
79+
80+
const pages = wrapAndPaginate(text, measureWidth, containerWidth, maxLines); // string[][]
81+
const timings = allocateTimings(pages, totalSeconds); // seconds per page
82+
```
83+
84+
## Licence
85+
86+
MIT. See the [repository](https://github.com/wildwinter/game-subtitles) for the full documentation and the preprocessor.

‎players/player-js/build.mjs‎

Lines changed: 31 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,31 @@
11
import { build } from 'esbuild';
2-
import { readFileSync } from 'node:fs';
2+
import { readFileSync, writeFileSync, copyFileSync, mkdirSync, rmSync } from 'node:fs';
33

44
const { version } = JSON.parse(readFileSync('../../package.json', 'utf8'));
5-
const banner = { js: `/* game-subtitles-player v${version} | MIT */` };
5+
const banner = { js: `/* @wildwinter/game-subtitles v${version} | MIT */` };
6+
7+
// Keep the npm package's version, and the lockfile's copy of it, in step with the repository's.
8+
const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
9+
if (pkg.version !== version) {
10+
const text = readFileSync('package.json', 'utf8');
11+
writeFileSync('package.json', text.replace(/("version":\s*")[^"]+(")/, `$1${version}$2`));
12+
}
13+
const lock = JSON.parse(readFileSync('package-lock.json', 'utf8'));
14+
if (lock.version !== version || lock.packages[''].version !== version) {
15+
lock.version = version;
16+
lock.packages[''].version = version;
17+
writeFileSync('package-lock.json', JSON.stringify(lock, null, 2) + '\n');
18+
}
19+
20+
// dist/ is what the npm package ships. The release zips and the demo take the same two
21+
// bundles from build/player-js/.
22+
rmSync('dist', { recursive: true, force: true });
623

724
await build({
825
entryPoints: ['src/index.js'],
926
bundle: true,
1027
format: 'esm',
11-
outfile: '../../build/player-js/game-subtitles-player.esm.js',
28+
outfile: 'dist/game-subtitles-player.esm.js',
1229
banner,
1330
});
1431

@@ -17,8 +34,17 @@ await build({
1734
bundle: true,
1835
format: 'iife',
1936
globalName: 'GameSubtitles',
20-
outfile: '../../build/player-js/game-subtitles-player.js',
37+
outfile: 'dist/game-subtitles-player.js',
2138
banner,
2239
});
2340

24-
console.log(`Built game-subtitles-player v${version}`);
41+
copyFileSync('src/index.d.ts', 'dist/index.d.ts');
42+
// npm adds a LICENSE file in the package folder to the package; this one is the repository's.
43+
copyFileSync('../../LICENSE', 'LICENSE');
44+
45+
mkdirSync('../../build/player-js', { recursive: true });
46+
for (const file of ['game-subtitles-player.esm.js', 'game-subtitles-player.js']) {
47+
copyFileSync(`dist/${file}`, `../../build/player-js/${file}`);
48+
}
49+
50+
console.log(`Built @wildwinter/game-subtitles v${version}`);

‎players/player-js/package-lock.json‎

Lines changed: 20 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎players/player-js/package.json‎

Lines changed: 38 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,45 @@
11
{
2-
"name": "game-subtitles-player",
3-
"private": true,
4-
"description": "Runtime subtitle player for games — JS, browser-compatible",
2+
"name": "@wildwinter/game-subtitles",
3+
"version": "0.3.1",
4+
"description": "Subtitle player for games: wraps, hyphenates, paginates, and times subtitles, using the soft hyphens the Game Subtitles preprocessor adds.",
5+
"keywords": ["subtitles", "captions", "games", "hyphenation", "localization", "text-layout"],
6+
"license": "MIT",
7+
"author": "Ian Thomas",
8+
"homepage": "https://github.com/wildwinter/game-subtitles#readme",
9+
"bugs": "https://github.com/wildwinter/game-subtitles/issues",
10+
"repository": {
11+
"type": "git",
12+
"url": "git+https://github.com/wildwinter/game-subtitles.git",
13+
"directory": "players/player-js"
14+
},
515
"type": "module",
6-
"main": "../../build/player-js/game-subtitles-player.esm.js",
16+
"exports": {
17+
".": {
18+
"types": "./dist/index.d.ts",
19+
"default": "./dist/game-subtitles-player.esm.js"
20+
},
21+
"./iife": "./dist/game-subtitles-player.js",
22+
"./package.json": "./package.json"
23+
},
24+
"module": "./dist/game-subtitles-player.esm.js",
25+
"types": "./dist/index.d.ts",
26+
"files": ["dist"],
27+
"sideEffects": false,
28+
"publishConfig": {
29+
"access": "public"
30+
},
731
"scripts": {
8-
"build": "node build.mjs",
9-
"test": "vitest run",
10-
"test:watch": "vitest",
11-
"demo": "node build.mjs && node -e \"console.log('\\nDemo built. Open players/player-js/demo/index.html in your browser (no server needed).\\n')\""
32+
"build": "node build.mjs",
33+
"test": "vitest run && tsc -p test/tsconfig.json",
34+
"test:watch": "vitest",
35+
"check:package": "node scripts/check-package.mjs",
36+
"prepack": "node build.mjs",
37+
"demo": "node build.mjs && node -e \"console.log('\\nDemo built. Open players/player-js/demo/index.html in your browser (no server needed).\\n')\""
1238
},
1339
"devDependencies": {
14-
"esbuild": "^0.24.0",
15-
"vitest": "^2.0.0",
16-
"jsdom": "^24.0.0"
40+
"esbuild": "^0.24.0",
41+
"jsdom": "^24.0.0",
42+
"typescript": "^5.6.0",
43+
"vitest": "^2.0.0"
1744
}
1845
}

0 commit comments

Comments
 (0)