talktrack 0.1.0 → 0.1.1

package/README.md

@@ -98,6 +98,42 @@ await finalizeFramedRecording(page, testInfo, {
 
 `bands` accepts any subset of `BandStyle`: `headerHeightPx`, `footerHeightPx`, `background`, `textColor`, `fontStack`, `headerFontSizePx`, `footerFontSizePx`. The same options exist on `recordDemo`.
 
+## Development
+
+TypeScript, pnpm, Turborepo, Playwright. You need Node 22 (see `.tool-versions`), the pnpm version in `packageManager`, and `ffmpeg` plus `ffprobe` with the `libvpx-vp9` encoder on `PATH`; the end-to-end suite needs them and nothing else does.
+
+```sh
+pnpm install
+pnpm exec playwright install chromium   # once, for the e2e suite
+pnpm typecheck && pnpm lint && pnpm test && pnpm test:e2e
+```
+
+`pnpm prepush` runs that whole matrix through turbo and is what the pre-push hook executes.
+
+### Architecture
+
+`src/` splits the pure halves (`human-path.ts` cursor geometry, `filter-graph.ts` caption windows and the ffmpeg filter graph, `timeline.ts` per-page narration events) from everything that touches a browser, the filesystem or ffmpeg (`cursor.ts`, `bands.ts`, `ffmpeg.ts`, `frame.ts`). The two adapters, `test-adapter.ts` (`finalizeFramedRecording`) and `standalone.ts` (`recordDemo`), are thin wrappers over `frameRecording`, so both driving modes produce identical output.
+
+Tests are `test/unit/` (Vitest, pure modules) and `test/e2e/` (Playwright against `test/fixtures/demo-page.html`, driving both modes and probing the framed video with ffprobe).
+
+### Conventions
+
+- Turbo task names are the underscore-prefixed leaf commands (`_build`, `_lint`, ...). Run the public names (`pnpm lint`, `pnpm test`); they go through turbo and its cache.
+- Conventional commits, enforced by commitlint in the `commit-msg` hook and in CI. Releases are cut from them by semantic-release on every push to `main` (`release.config.ts`); never bump the version or edit the changelog by hand.
+- Dependencies are added through the package manager and pinned exactly (`saveExact`). Anything younger than the configured release age waits, except the org's own `@exadev/*` tooling package, which is exempt in `pnpm-workspace.yaml` and `.npmrc`.
+- `AGENTS.md` and `CLAUDE.md` are symlinks to this file. Keep them that way.
+
+### Releasing
+
+Pushing to `main` runs the `release` job in `.github/workflows/ci.yml` after the required checks pass. It publishes to npm through trusted publishing (OIDC), so there is no npm token anywhere: the publisher is registered on npmjs.com for this repository and the `ci.yml` workflow. The release commit and tags are pushed to `main` straight from the job, which the ruleset on `main` otherwise forbids, so the job checks out with the repository's write deploy key (secret `RELEASE_DEPLOY_KEY`), the one actor the ruleset lets bypass its pull-request requirement. `release.config.ts` names the SSH repository URL so semantic-release pushes through that key rather than over HTTPS with the workflow token. Tags are `talktrack@<version>`, continuing from `talktrack@0.0.0`, the tag that marks the stub the npm name was reserved with.
+
+### Gotchas
+
+- The framing pass needs the recording to be exactly viewport-sized. In `@playwright/test`, set `video: { mode: "on", size }` to the viewport size; Playwright otherwise scales the video down and `finalizeFramedRecording` throws rather than produce a mis-laid-out file.
+- `finalizeFramedRecording` closes the page. Playwright only finalises a video once its page is closed, so the adapter does it itself; call it from `afterEach`, not mid-test.
+- Do not set `registry-url` in `actions/setup-node` anywhere: it writes an `_authToken` line that wins over the OIDC exchange and silently breaks publishing.
+- The ESLint config bans inline `eslint-disable` comments. Fix the code or restructure the test (for example `test.info()` instead of an empty destructuring pattern).
+
 ## Licence
 
 MIT

package/package.json

@@ -1,22 +1,34 @@
 {
   "name": "talktrack",
   "description": "Narrated, cursor-driven demo recordings from Playwright: a synthetic human-feeling cursor, caption bands timed to real page events, and ffmpeg-framed output, usable inside @playwright/test specs or from standalone scripts.",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "bugs": {
     "url": "https://github.com/ExaDev/talktrack/issues"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
     "@eslint/js": "^10.0.1",
     "@exadev/eslint-config": "2.27.0",
     "@playwright/test": "^1.63.0",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/github": "^12.0.9",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/node": "^26.4.0",
+    "conventional-changelog-conventionalcommits": "^10.4.0",
     "eslint": "^10.9.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
     "globals": "^17.11.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.4.1",
     "prettier": "^3.9.6",
     "publint": "^0.3.24",
+    "semantic-release": "^25.0.9",
     "tsdown": "^0.23.0",
     "turbo": "^2.10.12",
     "typescript": "^6.0.3",
@@ -54,6 +66,7 @@
   "license": "MIT",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
+  "packageManager": "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
   "peerDependencies": {
     "@playwright/test": ">=1.55"
   },
@@ -77,8 +90,10 @@
     "build": "turbo run _build",
     "lint": "turbo run _lint",
     "lint:fix": "eslint . --fix",
+    "prepare": "husky",
     "prepublishOnly": "pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build && publint && attw --pack",
     "prepush": "turbo run _prepush",
+    "release": "semantic-release",
     "test": "turbo run _test",
     "test:e2e": "turbo run _test:e2e",
     "typecheck": "turbo run _typecheck _typecheck:attw"