Adopt Changesets v3 for viewer packages

.changeset/README.md

@@ -0,0 +1,14 @@
+# Any Doc viewer releases
+
+Changesets manages the eight public `@baseblocks/anydoc-*` npm packages as one
+fixed, lockstep release. The workspace is in the `alpha` prerelease channel, so
+each accepted patch changeset advances the shared `0.1.0-alpha.N` version.
+
+- Run `pnpm changeset` in a feature branch and commit the generated Markdown file.
+- Use a patch release type while the viewer platform remains in alpha.
+- Use `pnpm changeset --empty` for changes that intentionally do not release packages.
+- Open a `changeset-release/*` version PR with `pnpm version:viewers` when a release is ready.
+- Publication remains gated by the verified `viewer-v*` tag workflow.
+
+The Rust, Node native, WASM, and Python `@firecrawl/anydoc` release family is
+intentionally outside this Changesets workspace and keeps its existing release process.

.changeset/config.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@4.0.0/schema.json",
+  "changelog": false,
+  "commit": false,
+  "fixed": [
+    [
+      "@baseblocks/anydoc-contracts",
+      "@baseblocks/anydoc-spreadsheet-engine",
+      "@baseblocks/anydoc-spreadsheet-viewer",
+      "@baseblocks/anydoc-presentation-viewer",
+      "@baseblocks/anydoc-react-viewer",
+      "@baseblocks/anydoc-ingestion",
+      "@baseblocks/anydoc",
+      "@baseblocks/anydoc-convex"
+    ]
+  ],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "privatePackages": {
+    "version": false,
+    "tag": false
+  },
+  "format": "auto",
+  "ignore": []
+}

.changeset/pre.json

@@ -0,0 +1,4 @@
+{
+  "mode": "pre",
+  "tag": "alpha"
+}

.github/workflows/ci.yml

@@ -19,6 +19,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Expose the Changesets base branch
+        if: github.event_name == 'pull_request'
+        run: git branch --force main origin/main
       - uses: pnpm/action-setup@v4
         with:
           version: 11.9.0
@@ -27,6 +33,10 @@ jobs:
           node-version: 24
           cache: pnpm
       - run: pnpm install --frozen-lockfile
+      - run: pnpm run release:metadata
+      - name: Require release intent for changed viewer packages
+        if: github.event_name != 'pull_request' || !startsWith(github.head_ref, 'changeset-release/')
+        run: pnpm run release:status
       # Build workspace packages first so umbrella subpath declarations resolve
       # exactly as they will for registry consumers.
       - run: pnpm run build:viewers

.github/workflows/publish-viewers.yml

@@ -28,6 +28,9 @@ jobs:
           node-version: 24
           cache: pnpm
       - run: pnpm install --frozen-lockfile
+      - run: pnpm run release:metadata
+      - name: Confirm the tagged packages are publishable
+        run: pnpm run release:plan
       - run: pnpm run build:viewers
       - run: pnpm run typecheck:viewers
       - run: pnpm run test:viewers

README.md

@@ -29,6 +29,9 @@ The BaseBlocks application façade exposes `ingest(...)`, the universal React
 viewer, and durable Convex ingestion. See
 [`packages/platform/README.md`](packages/platform/README.md) and the
 runtime-light [`packages/ingestion/README.md`](packages/ingestion/README.md).
+The public viewer packages use Changesets v3 for lockstep alpha versioning; see
+[`docs/VIEWER_PUBLISHING.md`](docs/VIEWER_PUBLISHING.md) for the contribution,
+version-PR, and tag-gated publishing workflow.
 
 Built by [Firecrawl](https://firecrawl.dev) to turn any office document into LLM-ready Markdown in single-digit milliseconds, with one consistent output no matter which format goes in. It powers [Firecrawl Parse](https://firecrawl.dev/parse), so if you'd rather not run it yourself, the hosted API gives you the same conversion plus our OCR models for the scanned pages anydoc can't read on its own.
 

docs/VIEWER_PUBLISHING.md

@@ -0,0 +1,59 @@
+# Viewer package publishing
+
+The eight public `@baseblocks/anydoc-*` npm packages are versioned together with
+Changesets v3. They remain independent from the Rust, native Node, WASM, and
+Python `@firecrawl/anydoc` release family.
+
+## Day-to-day changes
+
+Add a patch changeset with every public viewer-package change:
+
+```sh
+pnpm changeset
+```
+
+Commit the generated `.changeset/*.md` file with the implementation. Changes
+that do not affect a published package can carry an explicit empty changeset:
+
+```sh
+pnpm changeset --empty
+```
+
+CI runs `changeset status --since main` so a changed viewer package cannot be
+merged without recorded release intent. Changesets keeps all eight packages in
+one fixed group and updates their internal `workspace:` dependency ranges.
+
+## Version PR
+
+When a viewer release is ready, create a branch from `main`, apply the accumulated
+changesets, and open a dedicated version PR:
+
+```sh
+git switch -c changeset-release/viewers
+pnpm version:viewers
+git add .
+git commit -m "Version Any Doc viewer packages"
+```
+
+The command consumes accumulated changesets and advances the shared alpha
+version, for example from `0.1.0-alpha.13` to `0.1.0-alpha.14`.
+
+Review the package versions and dependency ranges before merging that PR.
+
+## Publish
+
+Publication remains an explicit, tag-gated operation so the existing build,
+test, package, checksum, and registry-integrity checks stay authoritative:
+
+```sh
+git tag viewer-v0.1.0-alpha.14
+git push origin viewer-v0.1.0-alpha.14
+```
+
+The `Publish viewer platform` workflow verifies that every package manifest
+matches the tag, uploads the exact verified tarballs, publishes only missing
+packages, verifies any already-published artifacts, and creates the GitHub
+release. Alpha versions publish under the npm `next` dist-tag.
+
+Do not use Changesets to version the `@firecrawl/anydoc` binding packages. Their
+cross-language `v*` workflow and version gate remain separate.

package.json

@@ -9,9 +9,10 @@
   "type": "module",
   "packageManager": "pnpm@11.9.0",
   "engines": {
-    "node": ">=20"
+    "node": ">=22.11.0"
   },
   "scripts": {
+    "changeset": "changeset",
     "dev:playground": "pnpm --dir apps/playground dev",
     "build:viewers": "pnpm --recursive --if-present build",
     "test:viewers": "pnpm --recursive --if-present test",
@@ -21,9 +22,15 @@
     "budget:viewers": "node scripts/check-viewer-budgets.mjs",
     "budget:ingestion": "node scripts/benchmark-ingestion.mjs",
     "closure:server": "node scripts/verify-server-closure.mjs",
-    "closure:platform": "node scripts/verify-packed-platform.mjs"
+    "closure:platform": "node scripts/verify-packed-platform.mjs",
+    "release:metadata": "node scripts/validate-viewer-releases.mjs",
+    "release:status": "changeset status --since main",
+    "release:validate": "pnpm release:metadata && pnpm release:status",
+    "release:plan": "changeset publish-plan",
+    "version:viewers": "pnpm release:metadata && changeset version"
   },
   "devDependencies": {
+    "@changesets/cli": "3.0.0",
     "typescript": "5.9.3",
     "vitest": "3.2.6"
   }