* docs: apply Vercel technical writing standards
Audit the complete documentation corpus, package READMEs, skills, and
source TSDoc/comments against the vercel-technical-writing skill and
style-rules.md. Normalize sentence-case headings without changing
published anchors, remove prose em dashes and filler wording, improve
active voice and self-contained phrasing, standardize product/brand
capitalization, American English, list punctuation, units, and code
fence languages, and preserve exact runtime strings/table placeholders.
All executable code is unchanged. Modified skills have their metadata
versions bumped.
* docs: extend writing audit to repository Markdown
Apply the same technical-writing rules to design documents, compiler
specifications, workbench guides, package changelogs, and the remaining
tracked Markdown outside the deployed docs corpus. Preserve historical
meaning, commands, output literals, table placeholders, and heading
anchors.
* docs: exclude generated package changelogs from audit
* ci: stop deploying changeset-release/main, run its e2e against production
The changesets action force-pushes `changeset-release/main`, and it can
point at exactly main's HEAD SHA. Vercel keeps one commit status per
project per SHA, so when both a production deployment (from main) and a
preview deployment (from changeset-release/main) are built for the same
commit, whichever finishes last owns the status. On 2026-07-30 the
preview finished last, so `vercel/wait-for-deployment-action` — which
reads the deployment ID out of that status — handed production e2e runs
a preview deployment ID and forked runs across environments.
Disable git deployments for that branch in every Vercel project rooted
in this repo, and give the changeset PR's Vercel e2e lanes a deployment
to test that actually exists: main's production deployment for the PR's
base SHA, resolved by SHA so a mid-flight production build is waited out
rather than silently replaced by an older one.
Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
* ci: resolve changeset-release e2e deployments with the wait action, tokenless
Per review: with changeset-release/main no longer deployed, main SHAs
can never again be deployed to a second environment of these projects,
so the per-SHA commit status the action reads is unambiguous for
exactly this lane. Reuse vercel/wait-for-deployment-action with
environment: production and sha pinned to the PR base SHA instead of
the Vercel-API polling script, drop the script and its VERCEL_TOKEN
usage, and inherit the action's inactive/skipped-build handling.
Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
---------
Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
* Fix Biome lint violations and add Biome CI check
Biome was not configured to respect .gitignore, so ~92% of the 13,355
reported diagnostics came from gitignored build artifacts. Enable VCS
integration (useIgnoreFile), apply safe auto-fixes across the repo, fix
the remaining mechanical errors by hand, downgrade judgment-call a11y /
dangerouslySetInnerHTML rules to warnings, and add a 'biome ci' job to
the Lint workflow so violations block PRs going forward.
* Use an empty changeset (no behavior change, no release needed)
* tarballs: redesign preview tarballs index page
Rebuild the static index page produced by `tarballs/scripts/pack.ts`:
- Featured `workflow` package up top with prominent install command,
copy button, and direct tarball download
- Top-of-page metadata chips: short SHA (linked to commit), branch,
PR number, build timestamp, package count + total size
- Collapsible "What is this?" explainer
- Package-manager tab toggle (pnpm / npm / yarn / bun) that swaps the
install command for every row in place
- Live filter input over the rest of the package list (with `/` shortcut)
- Per-row install command, copy button, and direct download
- Modern dark/light theme with system preference, Geist-inspired styling
Also captures tarball size during pack and renders human-readable byte counts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* tarballs: fix client-side interactivity broken by HTML-encoded JSON
`escapeHtml(JSON.stringify(catalog))` was HTML-encoding every quote in
the embedded catalog JSON to `"`, so `JSON.parse(textContent)` threw
on the first character and the IIFE bailed before attaching any event
listeners — package-manager toggle, search filter, copy buttons, and the
`/` shortcut were all dead UI on the deployed page.
`<script type="application/json">` content is treated as text by the HTML
parser; the only sequence that can break out is `</script>` (or `</`
in legacy parsers). Replace `<` with the JSON `<` escape, which is
legal per the JSON spec and prevents the breakout without needing entity
encoding.
Also switch `formatBytes` from `KB`/`MB` to `KiB`/`MiB` since the
divisor is 1024.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* tarballs: rewrite as Vite + Preact SPA with file breakdown, fix bundling
Address TooTallNate's review feedback by replacing the hand-rolled HTML-
in-template-literal approach with a small Vite + Preact SPA. The old
~600 lines of inlined HTML/CSS/JS in `pack.ts` is now `~80 lines of TSX`,
fully type-checked.
Layout:
- `tarballs/index.html`, `vite.config.ts`, `tsconfig.json` at the root
- `src/main.tsx` mounts the Preact app and fetches `/catalog.json`
- `src/app.tsx` is the page (Header, FeaturedCard, PackageRow, etc.)
- `src/catalog.ts` is the shared types + helpers (`buildInstallCommand`,
`formatBytes`)
- `src/icons.tsx`, `src/styles.css`
- `scripts/pack.ts` is now data-only — it scans packages, packs
tarballs, and writes `public/catalog.json`
The eliminates several smells the reviewer called out:
- The interactive script is now TypeScript with strict mode and JSX
type checking instead of an inline `<script>` block
- The `escapeHtml`-around-JSON-blob hack that broke client-side JS in
the prior commit is gone; the SPA fetches `catalog.json` and parses
it natively
- Pack-time logic and presentation logic no longer share a file
# Fix bundling: tarballs now actually contain compiled code
While verifying real tarball sizes I noticed `workflow-serde.tgz` was
only 828 bytes — it had `package.json`, `LICENSE.md`, `README.md` and
*nothing* else, because each package's `files: ["dist"]` excludes
sources but `dist/` hadn't been built. The Vercel build was running
`pnpm --filter tarballs build`, which only builds the `tarballs`
package itself — its workspace dependencies were never built.
Switch `vercel.json#buildCommand` to `pnpm turbo run build
--filter=tarballs`, which transitively builds dependencies first via
the `dependsOn: ["^build"]` rule already in the root `turbo.json`. With
the fix:
workflow: 241 KiB → 252 KiB tarball, 916 KiB unpacked, 205 files
@workflow/core: 59 KiB → 493 KiB tarball, 1.70 MiB unpacked, 236 files
@workflow/serde: 828 B → 1.4 KiB tarball, 4.6 KiB unpacked, 7 files
Add a smoke check that the `workflow` package has at least 5 files in
its tarball — catches the regression directly.
# Per-package contents view (packagephobia-style)
`pack.ts` now also runs `tar -tvzf` on each tarball and records the
file list with sizes. The SPA renders this as an expandable
"What's inside?" disclosure per package, grouped by top-level
directory (e.g. `dist/`, `docs/`) with proportional bars showing
each group's share of the unpacked size, and the largest files
listed below.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* tarballs: replace tar shell-out with in-process tar reader
The smoke check broke in CI: `'workflow' tarball only has 0 files`.
Root cause is that `tar -tvzf` emits a different verbose layout on GNU
tar (Linux, what CI runs) vs BSD tar (macOS, where I tested locally) —
the parser only matched the BSD column ordering, so on Linux every line
was rejected and `fileCount` came out as 0.
Replace the shell-out with a small in-process tar reader using
`zlib.gunzipSync` + manual 512-byte block walk. ustar headers are
trivially structured (name at offset 0, octal size at 124, typeflag at
156, ustar prefix at 345). We emit regular files only (`typeflag` `0`
or NUL) and consume but skip pax extended headers (`x`/`g`) and GNU
long-name entries (`L`). Result is identical on every platform.
Verified locally: 206 files / 998413 bytes for `workflow.tgz` matches
`tar -tvzf` exactly.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* tarballs: redesign per-package details with packagephobia-style stats
The previous "What's inside?" view crammed nested directory groups,
proportional bars, and per-group file lists into a `<details>` inside
an already-narrow row. It was hard to read and harder to compare.
Replace it with the layout packagephobia uses on its result page:
- Two large headline metric tiles (Publish size / Unpacked size)
with a big bold value, smaller unit, and small uppercase label.
Modeled directly on packagephobia's `Stats` component but using
our existing CSS variables so it tracks light/dark theme.
- A single sortable file table beneath. Default is size-descending so
the contributors to package size are immediately visible. Click a
header to flip direction or switch sort key. Sticky header keeps
the columns visible inside the scrollable region.
Drop the `groupByTopLevel`, `ContentsGroup`, and bar-chart styles —
they were the source of the "hard to use" feedback and don't add
information that the flat sortable table doesn't already convey.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* tarballs: address Copilot review feedback (a11y, dev script, caching)
- main.tsx: drop `cache: 'no-store'` from the catalog fetch. Each
tarballs deployment is immutable per commit, so HTTP caching is
appropriate; forcing no-store made every visit re-download the full
catalog (which now includes per-package file lists).
- app.tsx (search input): add `aria-label="Filter packages"`. The
visible label only contained an icon and placeholder, so screen
readers had no name for the control.
- app.tsx (PmTabs): replace `role="tablist"` / `role="tab"` /
`aria-selected` with plain buttons that use `aria-pressed`. The
ARIA tab pattern requires arrow-key roving focus we never wired
up; toggle buttons are the honest representation. Each button
also gets an explicit `aria-label`.
- app.tsx (row buttons): include the package name in the accessible
label of every per-row copy/download button (and on the featured
card too), so the screen reader buttons/links list distinguishes
them. Added an `accessibleName` prop to `CopyButton`.
- app.tsx (CopyButton): only flip to the "Copied" state when the
write actually succeeded. Both the modern `navigator.clipboard`
path and the `execCommand` fallback can fail; the new
`writeToClipboard` helper returns success and the button shows a
short "Failed" state if both paths fail.
# Make `pnpm dev` work from a clean checkout
The previous `dev: vite` couldn't actually serve the page because
`/catalog.json` 404s and the SPA boots into the error fallback.
Restructure the build layout to vite's conventional shape:
- `public/` is now a true vite public dir — pack writes tarballs and
catalog.json there. In dev, vite serves these at the root.
- `dist/` is the production build output (vite copies public/ into it
and adds index.html + assets/).
- `vercel.json#outputDirectory` switches from `public` → `dist`.
- `turbo.json` outputs updated to match.
- `dev` chains pack before vite so the catalog exists when the dev
server starts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Nathan Rajlich