# Publishing `@wisepunk/*` to public npm

The portable runtime ships four packages — **`@wisepunk/core`**, **`@wisepunk/renderer-html`**,
**`@wisepunk/renderer-svelte`**, **`@wisepunk/sdk`** — to the **public npm registry**
(registry.npmjs.org), under the `@wisepunk` scope. Publishing is **deliberate and gated** — it never
happens automatically. `apps/web` and `@midl/optimizer` are **not** published (`private: true`).

> Scope history: the original `@midl` scope is taken on public npm by an unrelated package, so the
> packages are scoped `@wisepunk` (free, and aligned with the wisepunk.com brand).

## How it's built (in-repo source vs published dist)

Each package keeps two `exports`:

- top-level `exports` → **`src/*.ts`** — what the monorepo consumes (the app, vitest, svelte-check, HMR).
  No build step needed in-repo; zero build-order coupling.
- `publishConfig.exports` → **`dist/*`** + `publishConfig.access: "public"`, applied by
  `pnpm pack`/`pnpm publish`, so the *published* package is a Node-native-loadable build (bundled ESM +
  `.d.ts`), public on npm. Proven by `tools/smoke-standalone.sh` (CI): packs the tarballs, installs them
  in a throwaway dir, renders via plain `node`.

Builds: `@wisepunk/core` + `@wisepunk/renderer-html` + `@wisepunk/sdk` use **tsup** (single-file ESM
bundle, deps external); `@wisepunk/renderer-svelte` uses **`@sveltejs/package`**. `pnpm -r build` builds all.

## One-time setup (account + token)

1. **Own the `@wisepunk` scope on npm** — register the npm user/org so the scope is yours (a free npm
   **org** named `wisepunk` covers public packages).
2. **Create an npm Automation access token** (npmjs.com → Access Tokens → Generate → **Automation**).
   Automation tokens **bypass 2FA** — a normal publish token 403s in CI. Set it as the repo secret:
   `gh secret set NPM_TOKEN --repo renewisepunk/midl`.

## Releasing (the deliberate steps)

1. **Describe the change** — `pnpm changeset` (pick packages + semver bump). Commit the `.changeset/*.md`.
2. **Bump versions** — `pnpm changeset version`. Commit, open a PR, merge to `main`.
3. **Publish** — GitHub → **Actions → "Release (@wisepunk/* → npm)" → Run workflow**, type `publish`.
   The job builds, runs the standalone smoke test, then `pnpm changeset publish` (auth = `NPM_TOKEN`).

## Installing the published packages (consumers)

Public — no auth, no `.npmrc`:

```sh
npm install @wisepunk/renderer-html @wisepunk/core   # render anywhere
npm install @wisepunk/sdk                            # manage pages over the write API
```