@welcome-back/brand 0.1.2 → 0.1.3

package/README.md

@@ -21,7 +21,8 @@ Use it for loading moments that mean "on the way to the next step".
 - [Accessibility](#accessibility)
 - [Where to use it, and where not](#where-to-use-it-and-where-not)
 - [Troubleshooting](#troubleshooting)
-- [Release](#release)
+- [Develop](#develop)
+- [Publish a change](#publish-a-change)
 - [Source art](#source-art)
 
 ## Install
@@ -320,17 +321,146 @@ the content will appear.
 | The runner fills the whole container | No width is set | Give it a width (`w-24`, or `width` in CSS) |
 | A Tailwind arbitrary property has no effect | Tailwind does not scan the file | Check the `content` globs in the Tailwind config |
 
-## Release
+## Develop
 
-1. Bump `version` in `package.json` in a PR, and merge it to `main`.
-2. Tag the merge commit: `git tag v0.2.0 && git push origin v0.2.0`.
-3. The Publish workflow checks the tag against the version, runs typecheck,
-   tests and build, and publishes to npm.
+### Repo layout
 
-Publishing uses npm trusted publishing (GitHub OIDC): no npm token is stored.
-The trusted publisher is set on npmjs.com → `@welcome-back/brand` → Settings:
-GitHub Actions, `WelcomeBackLoyalty/brand`, workflow `publish.yml`, with
-**Allow npm publish** ticked.
+| Path | What it holds |
+|---|---|
+| `src/index.ts` | Public exports. Only what is exported here is part of the API. |
+| `src/RunnerLoader.tsx` | The component: SVG structure, clip paths, props |
+| `src/runnerCss.ts` | The animation: keyframes, timing, swing angles, reduced motion |
+| `src/runnerArt.ts` | Vector data: paths, pants fills, clip polygons |
+| `src/*.test.tsx` | Vitest tests (server render, no browser) |
+| `scripts/mark-cjs.mjs` | Marks `dist/cjs` as CommonJS after the build |
+| `.github/workflows/ci.yml` | Runs on every PR and on `main` |
+| `.github/workflows/publish.yml` | Runs on a `v*` tag and publishes to npm |
+
+### Commands
+
+Node 22 or later.
+
+```bash
+npm ci             # install
+npm run typecheck  # tsc, no output
+npm test           # vitest
+npm run build      # dist/esm (ESM + types) and dist/cjs (CommonJS)
+```
+
+CI runs all four, then loads both builds to prove that `import` and `require`
+work.
+
+### Try a change in an app before you publish
+
+Pack the package and install the tarball in the app:
+
+```bash
+# in brand/
+npm run build && npm pack          # writes welcome-back-brand-<version>.tgz
+
+# in the app, for example staff-ui/
+npm i ../brand/welcome-back-brand-<version>.tgz
+```
+
+Undo it in the app with `npm i @welcome-back/brand@latest`. Do not commit the
+tarball path in the app's `package.json`.
+
+Prefer `npm pack` to `npm link`. A linked package can load a second copy of
+React, and then hooks fail with "Invalid hook call".
+
+### Common changes
+
+| To change | Edit | Note |
+|---|---|---|
+| Speed | `--wb-runner-step-default` in `src/runnerCss.ts` | Apps can already override it per use with `--wb-runner-step` |
+| Stride length (swing angles) | `@keyframes wb-runner-swing-front` / `-back` in `src/runnerCss.ts` | Angles are measured from each leg drawing's rest pose. The front leg is vertical at `-36deg`, the back leg at `39deg`. Keep forward and back swings equal around those values. |
+| Where the legs join the body | `@keyframes wb-runner-hip-front` / `-back` | Values are in the art's coordinates (the 1500×1500 PDF page) |
+| What is hidden behind the W | `LEGS_CLIP` / `BODY_CLIP` in `src/runnerArt.ts` | See [Source art](#source-art) |
+| A new prop | `src/RunnerLoader.tsx`, plus a test and a row in the props table | |
+| A new asset (logo, icon, token) | A new file in `src/`, exported from `src/index.ts`, plus a test and a README section | |
+
+After a visual change, check it in a real app with `npm pack` (above) in light
+mode, dark mode and with reduced motion on.
+
+## Publish a change
+
+Every change reaches npm through a PR and a tag. Nobody publishes from a laptop,
+and there is no npm token: GitHub Actions publishes with npm trusted publishing.
+
+### 1. Pick the version
+
+The package follows [semver](https://semver.org). Apps install it with `^`, so
+they get minor and patch releases on their next install.
+
+| Change | Bump | Example |
+|---|---|---|
+| Docs, tests, or a fix with no visible change | patch | `0.1.2` → `0.1.3` |
+| A new prop, asset or CSS variable; a visual tweak that keeps the API | minor | `0.1.3` → `0.2.0` |
+| A removed or renamed prop, export or CSS variable | major | `0.9.0` → `1.0.0` |
+
+While the version is `0.x`, npm treats a minor bump as breaking for `^`
+ranges. Apps then need an explicit update to get it.
+
+### 2. Open a PR with the change and the new version
+
+```bash
+git switch main && git pull
+git switch -c <type>/<short-name>
+# make the change
+npm version <patch|minor|major> --no-git-tag-version   # edits package.json and package-lock.json
+git commit -am "<type>: <what changed> (v<new version>)"
+git push -u origin HEAD
+gh pr create --base main
+```
+
+CI must pass before you merge. Squash-merge the PR.
+
+### 3. Tag the merge commit
+
+```bash
+git switch main && git pull
+git tag v<new version>          # must equal "version" in package.json
+git push origin v<new version>
+```
+
+The tag starts the Publish workflow. It:
+
+1. checks that the tag equals `version` in `package.json`,
+2. runs typecheck, tests and build (`prepublishOnly`),
+3. publishes to npm through trusted publishing.
+
+Watch it with `gh run watch`, or in the repo's **Actions** tab.
+
+### 4. Check npm and update the apps
+
+```bash
+npm view @welcome-back/brand version     # the new version, after a few minutes
+```
+
+A new version can take up to about 3 minutes to show on the registry. Then, in
+each app:
+
+```bash
+npm i @welcome-back/brand@latest
+```
+
+### If the publish fails
+
+| Error in the workflow log | Cause | Fix |
+|---|---|---|
+| `Tag must match package.json version` step fails | The tag and `version` differ | Delete the tag (`git push origin :v<x>` and `git tag -d v<x>`), fix the version in a PR, tag again |
+| `403 … OIDC permission denied` | The trusted publisher on npmjs.com does not allow direct publish, or its fields do not match | npmjs.com → package → Settings → Trusted Publisher: `WelcomeBackLoyalty` / `brand` / `publish.yml`, no environment, **Allow npm publish** ticked |
+| `403 … cannot publish over the previously published versions` | That version is already on npm | Bump the version in a new PR and tag again. npm never allows a republish of a version. |
+| Typecheck or test fails | The tagged commit is broken | Fix it in a PR, bump the version, tag again |
+
+To rerun a failed publish without a new tag: `gh run rerun <run-id> --failed`.
+
+### npm settings (for maintainers)
+
+- Org: `welcome-back`. Package access: public.
+- Trusted publisher: GitHub Actions, `WelcomeBackLoyalty/brand`, `publish.yml`,
+  no environment, **Allow npm publish** ticked.
+- No provenance: npm cannot generate it for a private GitHub repo.
 
 ## Source art
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@welcome-back/brand",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "WelcomeBack brand assets for React apps: the running-W loader.",
   "license": "UNLICENSED",
   "repository": {