From 8e3598fe5ec9a656ee969b0a14f6c78d145cb1e7 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Fri, 1 May 2026 15:58:18 +0530 Subject: [PATCH 1/7] docs: add design spec for WASM npm publish and package folder naming consistency Co-Authored-By: Claude Sonnet 4.6 --- .../2026-05-01-wasm-npm-publish-design.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-01-wasm-npm-publish-design.md diff --git a/docs/superpowers/specs/2026-05-01-wasm-npm-publish-design.md b/docs/superpowers/specs/2026-05-01-wasm-npm-publish-design.md new file mode 100644 index 0000000000..4f2556113b --- /dev/null +++ b/docs/superpowers/specs/2026-05-01-wasm-npm-publish-design.md @@ -0,0 +1,85 @@ +# Design: WASM npm Publish + Package Folder Naming Consistency + +**Date**: 2026-05-01 +**Status**: Approved + +## Problem + +Two oversights in the current release pipeline: + +1. The browser WASM package (`pkg/`) is never published to npm. The `wasm-release.yml` workflow + builds it and uploads it as a GitHub Release asset (`.tar.gz`) but has no `npm publish` step. +2. Top-level package folder names are inconsistent: `minigraf-node/` and `minigraf-c/` use the + `minigraf-*` prefix, but `swift/` does not, and `pkg/` is the wasm-pack default output name + rather than a meaningful package name. + +## Goals + +- Publish the browser WASM package to npm as `@minigraf/browser` on every tagged release. +- Rename `pkg/` → `minigraf-wasm/` and `swift/` → `minigraf-swift/` for uniform top-level naming. +- Keep the committed-source policy consistent with `minigraf-node/` (glue files checked in). + +## Out of Scope + +- WASI npm publish (`@minigraf/wasi`) — the WASI build produces a raw `.wasm` with no JS glue + and needs its own package structure. Tracked as a follow-up GitHub issue. +- `minigraf-ffi/` sub-packages (`java/`, `python/`, `android/`) — already consistently named. + +## Design + +### Directory Renames + +| Before | After | +|--------|-------| +| `pkg/` | `minigraf-wasm/` | +| `swift/` | `minigraf-swift/` | + +`pkg/.gitignore` (contains `*`, a wasm-pack default) is deleted. `minigraf-wasm/` is a committed +source directory; no blanket ignore belongs there. + +### `minigraf-wasm/package.json` + +- `"name"`: `"minigraf"` → `"@minigraf/browser"` +- `"version"`: reset to `"0.0.0"` (CI stamps the real version from the tag at publish time) +- All other fields unchanged + +### CI Workflow Changes + +**`wasm-browser.yml`** (build + test on PR/push to main): +- Add `--out-dir minigraf-wasm` to `wasm-pack build` and `wasm-pack test` invocations +- Update gzip size check path: `pkg/minigraf_bg.wasm` → `minigraf-wasm/minigraf_bg.wasm` +- Update artifact upload path: `pkg/` → `minigraf-wasm/` + +**`wasm-release.yml`** (tag-triggered release): +- Add `--out-dir minigraf-wasm` to the `wasm-pack build` invocation +- Update `tar` path: `-C . pkg/` → `-C . minigraf-wasm/` +- Keep the GitHub Release tarball upload — the browser WASM bundle is useful as a direct + download (CDN embedding, `