feat(ci): bundle-size tracking + ES-compat checks (OSS-123, OSS-121)

Adds two CI signals for keeping the published packages small and broadly compatible:

- Bundle size: size-limit file-mode config across packages plus a
  CopilotChat import-size regression signal (gzip) so growth in the
  headline consumer entrypoint is visible on every PR. A bundle-size
  workflow comments results on the PR (Phase 1: no hard-fail).
- ES compatibility: a compat-check (es-check) script across 9 packages
  with a root .browserslistrc, validating built .mjs/.cjs against the
  es2022 build target.

The measure script is importable (measureBundle) and unit-tested. Dev
docs live under dev-docs/ (bundle-size.md, browser-compat.md). All
action refs are pinned to full commit SHAs for supply-chain safety.

Author: davidmckayv

.browserslistrc

@@ -0,0 +1,6 @@
+# kaios 2.5 excluded deliberately — Gecko 48 era; excluded for CSS autoprefixer consumers.
+# JS compat targets (es2022 ESM/CJS, es2018 UMD; es2020 for react-core UMD) are hardcoded in tsdown configs and compat-check scripts.
+defaults
+not dead
+not op_mini all
+not kaios 2.5

.github/workflows/static_bundle_size.yml

@@ -0,0 +1,105 @@
+name: static / bundle-size
+
+on:
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "README.md"
+      - "examples/**"
+      - "showcase/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  NODE_OPTIONS: "--max-old-space-size=4096"
+  NX_VERBOSE_LOGGING: true
+
+jobs:
+  # Posts a per-PR comment with per-file gzip diffs for the 9 in-scope packages.
+  # Runs preactjs/compressed-size-action, which builds the PR head and the base
+  # branch, scans the `pattern` glob in each, and diffs the gzip sizes; the
+  # comment updates in place on subsequent pushes. No hard-fail (Phase 1) — see
+  # dev-docs/bundle-size.md for the rollout plan.
+  #
+  # Fork limitation: pull_request runs from a fork get a read-only GITHUB_TOKEN,
+  # so the action cannot post the comment and prints the report to the logs
+  # instead. The measurement still runs. Accepted for Phase 1 (informational, no
+  # hard-fail); see dev-docs/bundle-size.md for the relay pattern if the comment
+  # ever becomes required.
+  bundle-size:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    # pull-requests: write is scoped to this job only — it's the one that posts
+    # the size-diff comment. The import-size job below stays read-only.
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        # Omit `version:` so pnpm/action-setup inherits from the repo's
+        # `packageManager` field in package.json (via corepack).
+        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 20.x
+          # setup-node built-in cache is fork-safe (fork PRs can't write to base repo cache)
+          cache: "pnpm"
+          cache-dependency-path: "**/pnpm-lock.yaml"
+
+      - name: Measure compressed bundle sizes
+        uses: preactjs/compressed-size-action@66325aad6443cb7cf89c4bfcd414aea2367cda94 # 2.9.1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          # Use the root `build` script (present on both this branch and the base
+          # branch) so compressed-size-action can build both sides for comparison.
+          # The `pattern` below restricts measurement to the 9 in-scope packages.
+          build-script: build
+          pattern: "packages/{core,shared,react-core,react-ui,react-textarea,runtime-client-gql,web-inspector,voice,a2ui-renderer}/dist/**/*.{mjs,js,cjs}"
+
+  # Measures what an app importing { CopilotChat } from
+  # @copilotkit/react-core/v2 bundles, by driving esbuild over a synthetic entry
+  # and summing the gzipped output. Writes the total to the GitHub job summary
+  # for per-PR visibility. It is a relative regression signal across PRs, not a
+  # production Vite/Next figure — see dev-docs/bundle-size.md.
+  copilotchat-import-size:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 20.x
+          cache: "pnpm"
+          cache-dependency-path: "**/pnpm-lock.yaml"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build react-core
+        run: npx nx run @copilotkit/react-core:build
+
+      - name: Measure CopilotChat bundle regression signal
+        run: pnpm --filter @copilotkit/react-core size:headline

.github/workflows/static_compat.yml

@@ -0,0 +1,59 @@
+name: static / compat
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "docs/**"
+      - "README.md"
+      - "examples/**"
+      - "showcase/**"
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "README.md"
+      - "examples/**"
+      - "showcase/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  compat-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        # Omit `version:` so pnpm/action-setup inherits from the repo's
+        # `packageManager` field in package.json (via corepack).
+        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 20.x
+          # setup-node built-in cache is fork-safe (fork PRs can't write to base repo cache)
+          cache: "pnpm"
+          cache-dependency-path: "**/pnpm-lock.yaml"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages
+        run: >
+          npx nx run-many -t build
+          --projects=@copilotkit/core,@copilotkit/shared,@copilotkit/react-core,@copilotkit/react-ui,@copilotkit/react-textarea,@copilotkit/runtime-client-gql,@copilotkit/web-inspector,@copilotkit/voice,@copilotkit/a2ui-renderer
+
+      - name: Run compat-check
+        run: >
+          npx nx run-many -t compat-check
+          --projects=@copilotkit/core,@copilotkit/shared,@copilotkit/react-core,@copilotkit/react-ui,@copilotkit/react-textarea,@copilotkit/runtime-client-gql,@copilotkit/web-inspector,@copilotkit/voice,@copilotkit/a2ui-renderer

.oxfmtrc.json

@@ -12,6 +12,7 @@
     "packages/web-inspector/src/styles/generated.css",
     "showcase/aimock/shared/**",
     "showcase/aimock/d4/**",
-    "showcase/aimock/d6/**"
+    "showcase/aimock/d6/**",
+    "**/package.json"
   ]
 }

dev-docs/browser-compat.md

@@ -0,0 +1,45 @@
+# Browser Compatibility
+
+## Browserslist Matrix
+
+The `.browserslistrc` at the repo root declares the intended browser support policy. It is useful for tools that read browserslist directly (e.g. PostCSS autoprefixer, documentation generators). To see the current resolved matrix, run:
+
+```
+npx browserslist
+```
+
+The resolved set changes over time as `defaults` is a dynamic query maintained by the browserslist project — there is no fixed version table in this doc.
+
+One entry is explicitly excluded: `not kaios 2.5`. KaiOS 2.5 ships a Gecko 48-era engine and is documented here as out-of-scope so that consumers of this policy (autoprefixer and similar tools) know not to target it.
+
+Note: `.browserslistrc` does **not** drive `compat-check`. The `es-check` targets (ES2022 for ESM/CJS; ES2018 for UMD, except `@copilotkit/react-core` UMD which uses ES2020 — see "What `compat-check` Does" below) are hardcoded in the `compat-check` scripts and are independent of the browserslist query. See the "Decoupled" section below for why these two concerns are kept separate.
+
+## What `compat-check` Does
+
+`compat-check` runs `es-check` against the built `dist/` output after a build:
+
+- **ESM and CJS files** are checked against **ES2022** (matches the `tsdown` `target: "es2022"` setting for all packages).
+- **UMD files** are checked against **ES2018** for all packages except `@copilotkit/react-core`, which uses **ES2020** because its source contains dynamic `import()` expressions that cannot be downcompiled to ES2018 by rollup when the imported modules are external.
+
+If any file uses syntax above the target level, `es-check` fails loudly with the offending file and the problematic feature. The check runs in CI so failures surface before a release.
+
+## Why It Is Decoupled from the `tsdown` Target
+
+`tsdown`'s `target` option tells the compiler what it _should_ emit — but there are two ways the actual output syntax can exceed that target without tsdown itself introducing the violation:
+
+1. **Transitive dependencies.** Bundled code from a dep can carry syntax that was never downcompiled because tsdown only transforms its own output, not pre-compiled dep artifacts.
+2. **tsdown version bumps.** A new tsdown version may change how it handles certain patterns, inadvertently emitting newer syntax.
+
+Neither of those failures would be caught by reading the tsdown config. The `compat-check` catches them by inspecting the real built artifacts, so drift is detected before a customer encounters a parse error in a supported browser.
+
+## Handling a Failure
+
+When `compat-check` fails, the output from `es-check` will name the offending file and the syntax it objected to. The decision tree is:
+
+1. **Identify the offending file.** Look at the `es-check` error output — it will point to a specific file in `dist/`.
+2. **Trace it to a dep or to first-party code.** Check whether the syntax comes from a bundled dependency or from code we wrote. Source maps or a quick `grep` of the dist file for a known identifier usually clarifies this.
+3. **Decide:**
+   - If the violation came from **a dep update** that unintentionally introduced newer syntax: pin or override the dep, or open an issue upstream asking them to ship a downcompiled artifact.
+   - If we **intentionally dropped support** for an older browser tier: raise the `es-check` target in the `compat-check` script and update this document to match. Note: updating `.browserslistrc` has no effect on `compat-check` — the es-check targets are hardcoded in the scripts and are independent of the browserslist query.
+
+Do not suppress the failure or widen the allowed syntax band without updating the `compat-check` targets and this document to match.

dev-docs/bundle-size.md

@@ -0,0 +1,87 @@
+# Bundle Size Tracking
+
+## How it works — two tiers
+
+### Tier 1: CI (compressed-size-action)
+
+`static_bundle_size.yml` runs on every PR via `preactjs/compressed-size-action@v2.9.1`. It scans a glob (`packages/{...}/dist/**/*.{mjs,js,cjs}`), computes the gzip size of each matched file (the action's default compression; the workflow sets no `compression` input), and posts a PR comment showing per-file diffs. It has **no hard-fail** (Phase 1).
+
+> **Fork PRs:** `pull_request` runs triggered from a fork receive a read-only `GITHUB_TOKEN`, so `compressed-size-action` cannot post or update the PR comment — it prints the size report to the job logs instead. The measurement still runs; only the comment is unavailable. This is an accepted Phase 1 limitation (the report is informational and there is no hard-fail). If the PR comment ever becomes a required signal, switch to a `pull_request_target` + `workflow_run` relay pattern so the comment is posted from a trusted context without exposing write tokens to fork code.
+
+Key facts:
+
+- Reports by **file path**, not by named entry — it does not read `.size-limit.json` at all.
+- The action runs `build-script: build` (the root `build` script — `nx run-many -t build` over all `packages/**`) on both the PR branch and the base branch, then measures only the files matched by the `pattern` glob. The root `build` script is used (rather than a bundle-size-specific one) because the action must build the base branch too, and `build` exists on every branch. No separate build step is needed before the workflow triggers — the action handles both builds.
+- PR comments show paths like `packages/react-core/dist/index.mjs (+1.2 kB gzip)`.
+
+### The CopilotChat regression signal (job summary, not the PR comment)
+
+The `copilotchat-import-size` job in `static_bundle_size.yml` measures what an app
+importing `{ CopilotChat }` from `@copilotkit/react-core/v2` bundles, via
+`packages/react-core/scripts/measure-copilotchat.mjs` (run locally with
+`pnpm --filter @copilotkit/react-core size:headline`). It drives `esbuild`
+directly — bundling `{ CopilotChat }` minified, with `react`/`react-dom` external
+and CSS/fonts stubbed to `empty` (we measure JS) — and writes the total gzipped
+JS to the GitHub **job summary**.
+
+**This is a _relative_ regression signal, not a production figure.** Its absolute
+value (currently ~3 MB gzip) is an esbuild number; a real consumer bundler
+(Vite/Next/webpack) splits eager-vs-lazy differently and reports different
+absolutes — the Notion "Header Embed Bundle Readout" measured ~386 kB _main
+initial JS_ under Vite, with the shiki/mermaid language packs as separate
+generated chunks. The script's worth is **consistency**: the same measurement
+every PR, so a change that grows CopilotChat's JS shows up, and the number
+collapses once OSS-122 moves the language packs to a CDN. A faithful _production_
+headline (real Next 15 fixture + `@next/bundle-analyzer`) is OSS-122 Phase 0.
+
+Why a custom script and not `size-limit`: CopilotChat pulls `katex`'s CSS, whose
+`url()` font refs crash `@size-limit/esbuild` (which exposes no loader hook).
+Driving esbuild directly lets us stub the CSS/font assets.
+
+### Tier 2: Local dev (size-limit)
+
+The four **bundled** packages (`core`, `react-core`, `react-ui`, `react-textarea`) each have a `.size-limit.json` at their root listing one or more named entries pointing at `dist/` paths. Run locally via:
+
+```
+pnpm --filter <pkg> size
+```
+
+The five unbundled packages (`shared`, `runtime-client-gql`, `web-inspector`, `voice`, `a2ui-renderer`) have no `.size-limit.json` and no `size` script — their sizes are tracked by the CI glob only.
+
+> **Node version requirement:** `size-limit@12.1.0` requires Node 20, 22, or 24+ (`^20 || ^22 || >=24`). Running `pnpm --filter <pkg> size` on Node 18 will produce an `EBADENGINE` error.
+
+## Where configuration lives
+
+`.size-limit.json` files live at the root of each bundled package (`core`, `react-core`, `react-ui`, `react-textarea`) and are used exclusively by the local `size` script. They are not read by CI.
+
+## Adding a new measurement
+
+Only bundled packages support local size tracking. For unbundled packages, CI covers all chunk files via the glob; no local config is needed.
+
+To add a measurement to a bundled package:
+
+1. Add an entry to the package's `.size-limit.json`:
+   ```json
+   { "name": "my-package: MyExport", "path": "dist/index.mjs", "gzip": true }
+   ```
+2. Build the package first: `pnpm --filter <pkg> build`
+3. Run locally: `pnpm --filter <pkg> size`
+4. Commit the updated `.size-limit.json`.
+
+Note: named entries appear in **local** size-limit output only. CI PR comments report by file path from the glob, not by these names.
+
+> **Bundled vs. unbundled packages:** `@size-limit/file` reports accurate sizes for bundled packages (those that build a single-file bundle). For unbundled packages (those that emit re-export barrels with separate chunk files), `@size-limit/file` only counts the barrel file — the CI `compressed-size-action` glob covers all chunks correctly regardless.
+
+## CI behavior (Phase 1 — current)
+
+`static_bundle_size.yml` posts a comment with per-file gzip diffs on every PR. It has **no hard-fail**. Sizes today reflect pre-OSS-122 bloat; adding budget limits now would either lock in that bloat permanently or fail immediately on every PR. Neither is useful.
+
+## Phase 2 — after OSS-122 (separate ticket, blocked)
+
+Once OSS-122 has reduced the baseline:
+
+1. Add `"limit"` fields to each `.size-limit.json` entry.
+2. Add a size-limit step to the CI workflow (currently the workflow has no size-limit step — Phase 2 adds one, it does not flip an existing step).
+3. PRs that regress past a limit will fail CI.
+
+Do not add `"limit"` fields before OSS-122 lands.

lefthook.yml

@@ -49,9 +49,16 @@ pre-commit:
       run: |
         set -- {staged_files}
         if [ "$#" -gt 0 ]; then
-          pnpm exec oxlint --fix "$@" &&
-          pnpm exec oxfmt --write "$@" ;
-          ruff format "$@" 2>/dev/null || true
+          pnpm exec oxlint --fix "$@"
+          # Defense-in-depth: filter package.json from explicit oxfmt args even though
+          # .oxfmtrc.json ignorePatterns covers it. Explicit-path invocations bypass the
+          # pattern in some tool versions; the shell filter makes the exclusion unconditional.
+          fmt_files=""; for f in "$@"; do case "$f" in */package.json|package.json) ;; *) fmt_files="$fmt_files $f" ;; esac; done
+          [ -n "$fmt_files" ] && pnpm exec oxfmt --write $fmt_files
+          # ruff v0.9+ formats JSON with trailing commas (JSONC), which breaks
+          # pnpm's JSON parser in the sync-lockfile hook. Scope it to .py only.
+          py_files=""; for f in "$@"; do case "$f" in *.py) py_files="$py_files $f";; esac; done
+          [ -n "$py_files" ] && ruff format $py_files 2>/dev/null || true
         fi
       stage_fixed: true
     test-and-check-packages:

nx.json

@@ -87,6 +87,11 @@
       "dependsOn": ["build"],
       "inputs": ["{projectRoot}/package.json", "{projectRoot}/dist/**"],
       "cache": true
+    },
+    "compat-check": {
+      "dependsOn": ["build"],
+      "inputs": ["{projectRoot}/package.json", "{projectRoot}/dist/**"],
+      "cache": true
     }
   },
   "parallel": 14,

package.json

@@ -42,13 +42,16 @@
     "@arethetypeswrong/cli": "^0.18.2",
     "@commitlint/cli": "^20.3.0",
     "@commitlint/config-conventional": "^20.3.0",
+    "@size-limit/file": "12.1.0",
     "@storybook/addon-docs": "^10.2.10",
     "@storybook/addon-webpack5-compiler-swc": "^4.0.2",
     "@storybook/react-webpack5": "^10.2.10",
     "@types/jscodeshift": "^17.3.0",
     "@types/node": "^18.11.17",
     "@vitest/coverage-v8": "^3.2.4",
+    "browserslist": "^4.24.0",
     "danger": "^12.3.3",
+    "es-check": "9.6.4",
     "glob": "^10.3.12",
     "install": "^0.13.0",
     "jscodeshift": "^17.3.0",
@@ -61,6 +64,7 @@
     "remark": "^15.0.1",
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
+    "size-limit": "12.1.0",
     "storybook": "^10.2.10",
     "ts-node": "^10.9.2",
     "tsdown": "^0.20.3",

packages/a2ui-renderer/package.json

@@ -47,6 +47,7 @@
   },
   "scripts": {
     "build": "tsdown",
+    "compat-check": "es-check es2022 --module 'dist/**/!(*.umd).{mjs,cjs,js}' && es-check es2018 'dist/**/*.umd.js'",
     "check-types": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",