3D engine that AI agents drive
Measure the package archive against the base branch
Nguyen Xuan An4a6616e61594
diff --git a/.github/workflows/test.yml b/.github/workflows/test.ymlindex 57a1809d..acbcc610 100644--- a/.github/workflows/test.yml+++ b/.github/workflows/test.yml@@ -33,7 +33,7 @@ jobs:- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0with:path: node_modules/.cache/size-base- key: size-base-${{ steps.base.outputs.sha }}-${{ hashFiles('scripts/measure-size.mjs', 'scripts/size-*.mjs', 'scripts/*tool-cost*.mjs', 'package-lock.json') }}+ key: size-base-${{ steps.base.outputs.sha }}-${{ hashFiles('scripts/measure-size.mjs', 'scripts/size-*.mjs', 'scripts/*tool-cost*.mjs', 'scripts/measure-archive.mjs', 'scripts/build-mcp.mjs', 'vite.lib.config.js', 'package-lock.json') }}- run: npm run size -- --base "$SIZE_BASE_REF"- run: npm run tool-cost -- --base "$SIZE_BASE_REF"- run: npm testdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex f5ed9676..1562588e 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -35,7 +35,7 @@ Run `npm run smoke` or the `smoke:*` script for the area that you changed, and lA change to skinning, glTF loading, poses or IK also needs `npm run smoke:character`, which takes a real character through the MCP server. Run `npm run prepare:release` first.Screenshots and other output go to `artifacts/`, which Git ignores.-Every pull request runs `npm audit`, `npm run size`, `npm run tool-cost`, `npm test`, `npm run test:isolated` (each test file in its own process), `prepare:release`, `smoke:package` and `smoke:mcp-package` in the `Test` workflow. `smoke:mcp-package` draws through the MCP server on SwiftShader in Chrome. `npm run size` compares every bundle with `origin/main`. If a bundle grows past its allowance (64 bytes gzip for core and the scenes), add `changes/<issue>.size.md` with the line `- entry:core: <why it is worth the bytes>` and say why in the pull request. Never edit `bench/size/budgets.json` or `baseline.json` in a pull request. `bench/size/README.md` has the details.+Every pull request runs `npm audit`, `npm run size`, `npm run tool-cost`, `npm test`, `npm run test:isolated` (each test file in its own process), `prepare:release`, `smoke:package` and `smoke:mcp-package` in the `Test` workflow. `smoke:mcp-package` draws through the MCP server on SwiftShader in Chrome. `npm run size` compares every bundle with `origin/main`. If a bundle grows past its allowance (64 bytes gzip for core and the scenes, 2% for the npm archive), add `changes/<issue>.size.md` with the line `- entry:core: <why it is worth the bytes>` and say why in the pull request. Never edit `bench/size/budgets.json` or `baseline.json` in a pull request. `bench/size/README.md` has the details.`npm run tool-cost` does the same for what the MCP tools cost an agent. If a tool schema grows by more than 64 bytes, a typical result by more than 128 bytes, or the schema total by more than 128 bytes, first move rare detail into `scene_capabilities` or a shared schema. If the growth is worth it, add a line to `changes/<issue>.size.md`, such as `- tool:scene_create: <why it is worth the bytes>`, `- tool-total: <why>` or `- result:scene_capabilities: <why>`. Never edit `bench/tool-cost-budgets.json` in a pull request. `bench/tool-cost/README.md` has the details.diff --git a/bench/size/README.md b/bench/size/README.mdindex 81609cc2..b2e81747 100644--- a/bench/size/README.md+++ b/bench/size/README.md@@ -81,7 +81,9 @@ Release steps in `CONTRIBUTING.md` run `npm run changes:fold`, which deletes the## Package archive-`archiveBytes` in `budgets.json` caps the npm archive that `npm pack` makes. `npm run smoke:package` checks it, after `npm run prepare:release`. The archive has a ceiling and not a base measurement, because measuring the base archive needs a full build. A pull request that pushes the archive over the ceiling accepts it with an `archive` line in its size note. Only a release edits `archiveBytes`. The archive was 904,975 bytes before the MCP preview shared the package's engine chunks and 666,214 after; features then grew it to 802,581, and one-line notices in each built file plus a stub for the SDK's unused Ajv shim brought it to 695,041. The budget is now 740,000 bytes (measured 2026-11-02 against `budgets.json`: lower it when the archive shrinks). Lower `archiveBytes` when work shrinks it.+`npm run smoke:package` checks the npm archive that `npm pack` makes, after `npm run prepare:release`. It measures the archive of the base branch the same way as the bundles. It unpacks the base, builds the library and the MCP server there, and asks `npm pack --dry-run` for the size. That takes about ten seconds, and CI caches the result by base with the bundle sizes. The archive may grow by 2% of the base archive. A pull request that grows it more accepts it with an `archive` line in its size note. Two pull requests that each stay inside 2% never fail each other, because each one is compared with its own base.++`archiveBytes` in `budgets.json` is the release ceiling. `smoke:package` reports it, and `npm run smoke:package -- --absolute` enforces it. `npm run size:release` resets it to 2% over the archive of the current build. A pull request never edits it. The archive was 904,975 bytes before the MCP preview shared the package's engine chunks and 666,214 after; features then grew it to 802,581, and one-line notices in each built file plus a stub for the SDK's unused Ajv shim brought it to 695,041. The budget is now 740,000 bytes (measured 2026-11-02 against `budgets.json`: lower it when the archive shrinks). Lower `archiveBytes` when work shrinks it.Moving code into installed dependencies would shrink the archive further but adds install size to every consumer, including library users who never run MCP. Making `@modelcontextprotocol/server` and `zod` dependencies saved about 125 KB of archive for about 14.5 MB on disk, so it was not kept.diff --git a/changes/345.md b/changes/345.mdindex 6059efaa..5fbac36f 100644--- a/changes/345.md+++ b/changes/345.md@@ -1 +1 @@-- Measure tool schema and result bytes against the base branch with `npm run tool-cost` (issue #345). A pull request that grows a tool by more than 64 bytes, a result by more than 128 or the total by more than 128 accepts it in its own `changes/<issue>.size.md`, so `bench/tool-cost-budgets.json` no longer conflicts. The `measured` history string is gone and the absolute budgets are release ceilings, refreshed by `npm run tool-cost:release`.+- Measure tool schema and result bytes against the base branch with `npm run tool-cost` (issue #345). A pull request that grows a tool by more than 64 bytes, a result by more than 128 or the total by more than 128 accepts it in its own `changes/<issue>.size.md`, so `bench/tool-cost-budgets.json` no longer conflicts. The `measured` history string is gone and the absolute budgets are release ceilings, refreshed by `npm run tool-cost:release`. The npm archive is measured the same way (issue #337): it may grow by 2% of the base branch archive, and an `archive` line in a size note accepts more, so one stale ceiling no longer fails every later pull request.diff --git a/scripts/measure-archive.mjs b/scripts/measure-archive.mjsnew file mode 100644index 00000000..e0f98201--- /dev/null+++ b/scripts/measure-archive.mjs@@ -0,0 +1,39 @@+// Packs the library the way a release does and prints the archive size: node scripts/measure-archive.mjs --json+// The base measurement of the size check runs it inside a checkout of the base branch, so the numbers come from the base source.+// It builds the library and the MCP server like prepare-release.mjs, then asks npm for the size of the archive without writing one.+import { spawnSync } from 'node:child_process';+import { existsSync } from 'node:fs';+import { dirname, resolve } from 'node:path';++const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;++function run(arguments_, capture = false) {+ const result = spawnSync(process.execPath, arguments_, { encoding: 'utf8', windowsHide: true, stdio: capture ? 'pipe' : ['ignore', 2, 2], maxBuffer: MAX_OUTPUT_BYTES });+ if (result.status !== 0) throw new Error(`${arguments_.join(' ')} failed: ${result.stderr ?? ''}`);+ return result.stdout;+}++// The MCP build records the source commit and refuses a folder that is not a repository. The unpacked base branch is one folder+// of files, so it gets a throwaway repository with one commit, which is clean like a release checkout.+function ensureRepository() {+ if (existsSync('.git')) return;+ const identity = ['-c', 'user.name=archive', '-c', '[email protected]', '-c', 'commit.gpgsign=false'];+ for (const command of [['init', '-q'], ['add', '-A'], [...identity, 'commit', '-q', '-m', 'base']]) {+ const result = spawnSync('git', command, { encoding: 'utf8', windowsHide: true, maxBuffer: MAX_OUTPUT_BYTES });+ if (result.status !== 0) throw new Error(`git ${command.join(' ')} failed: ${result.stderr}`);+ }+}++export function measureArchiveBytes() {+ ensureRepository();+ run(['node_modules/vite/bin/vite.js', 'build', '--config', 'vite.lib.config.js']);+ run(['scripts/build-mcp.mjs']);+ const npmCli = process.env.npm_execpath ?? resolve(dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js');+ const packResult = JSON.parse(run([npmCli, 'pack', '--ignore-scripts', '--dry-run', '--json'], true));+ const packed = Array.isArray(packResult) ? packResult[0] : Object.values(packResult)[0];+ return packed.size;+}++if (process.argv.includes('--json')) {+ process.stdout.write(JSON.stringify({ archiveBytes: measureArchiveBytes() }));+}diff --git a/scripts/measure-size.mjs b/scripts/measure-size.mjsindex aa2c31d8..f21bc20c 100644--- a/scripts/measure-size.mjs+++ b/scripts/measure-size.mjs@@ -8,6 +8,7 @@ import { brotliCompressSync, gzipSync } from 'node:zlib';import { build } from 'esbuild';import { budgetsFrom, compareToBudgets, formatRows, initialOutputPaths } from './size-budget.mjs';import { compareToBase, formatGrowthRows } from './size-growth.mjs';+import { measureArchiveBytes } from './measure-archive.mjs';import { DEFAULT_BASE_REF, baseRefExists, measureBase, readAcceptedBundles } from './size-base.mjs';const BUDGETS_PATH = 'bench/size/budgets.json';@@ -188,7 +189,10 @@ const budgetFile = await readJson(BUDGETS_PATH);const baselineFile = await readJson(BASELINE_PATH);// Budgets and the baseline move at release, never in a feature pull request.-if (flags.has('--set-budgets')) budgetFile.budgets = budgetsFrom(measured);+if (flags.has('--set-budgets')) {+ budgetFile.budgets = budgetsFrom(measured);+ budgetFile.archiveBytes = Math.ceil(measureArchiveBytes() * 1.02);+}if (flags.has('--set-budgets') || flags.has('--update-baseline')) {const threeManifest = await readJson('node_modules/three/package.json');await writeJson(BUDGETS_PATH, budgetFile);diff --git a/scripts/size-base.mjs b/scripts/size-base.mjsindex cf2e143d..c460e6bf 100644--- a/scripts/size-base.mjs+++ b/scripts/size-base.mjs@@ -50,6 +50,9 @@ export function readAcceptedBundles(baseRef, cwd = process.cwd()) {return accepted;}+// The archive: the base branch is built and packed in its own checkout by this checkout's script.+export const ARCHIVE_METHOD = { script: join(SCRIPTS_FOLDER, 'measure-archive.mjs'), runInBase: false, files: ['measure-archive.mjs', 'size-base.mjs', '../vite.lib.config.js', 'build-mcp.mjs'] };+// The cache key holds everything that decides the base numbers: the base commit, the measuring method and the lock file.function cacheFileFor(baseRef, method) {const hash = createHash('sha256');@@ -90,3 +93,8 @@ export async function measureBase(baseRef, method = SIZE_METHOD) {writeFileSync(cacheFile, JSON.stringify(measured));return measured;}++// The size in bytes of the npm archive of the base branch, cached by base commit like the bundle sizes.+export async function measureBaseArchive(baseRef) {+ return (await measureBase(baseRef, ARCHIVE_METHOD)).archiveBytes;+}diff --git a/scripts/size-growth.mjs b/scripts/size-growth.mjsindex ce670d89..dd15895b 100644--- a/scripts/size-growth.mjs+++ b/scripts/size-growth.mjs@@ -62,8 +62,21 @@ export function formatGrowthRows(rows) {return [header, ...lines].join('\n');}-// The packed archive has a ceiling instead of a base measurement, because measuring the base archive needs a full build.-export function archiveProblem(archiveBytes, ceiling, accepted = new Map()) {- if (archiveBytes <= ceiling || accepted.has(ARCHIVE_NAME)) return null;- return `The current source package is ${archiveBytes} bytes, over its archive ceiling of ${ceiling} in bench/size/budgets.json by ${archiveBytes - ceiling}. ${acceptInstruction(ARCHIVE_NAME)}`;+// The packed archive is measured like a bundle, against the archive of the base branch. It gets 2% of that archive, because+// every consumer downloads it and 2% is what the other entries get. An archive line in a size note accepts more.+export function archiveAllowance(baseBytes) {+ return Math.floor(baseBytes * OTHER_ALLOWANCE_FRACTION);+}++export function archiveGrowthProblem(archiveBytes, baseBytes, accepted = new Map()) {+ const allowance = archiveAllowance(baseBytes);+ const growth = archiveBytes - baseBytes;+ if (growth <= allowance || accepted.has(ARCHIVE_NAME)) return null;+ return `The source package is ${archiveBytes} bytes, ${growth} more than the ${baseBytes} bytes of the base branch, over its allowance of ${allowance}. ${acceptInstruction(ARCHIVE_NAME)}`;+}++// The ceiling in bench/size/budgets.json is a release report like the other absolute budgets. --absolute enforces it.+export function archiveCeilingProblem(archiveBytes, ceiling) {+ if (archiveBytes <= ceiling) return null;+ return `The source package is ${archiveBytes} bytes, over its release ceiling of ${ceiling} in bench/size/budgets.json by ${archiveBytes - ceiling}. A release refreshes it.`;}diff --git a/scripts/smoke-package.mjs b/scripts/smoke-package.mjsindex 85e0b0e5..768d4b39 100644--- a/scripts/smoke-package.mjs+++ b/scripts/smoke-package.mjs@@ -4,8 +4,8 @@ import { tmpdir } from 'node:os';import { resolve, dirname } from 'node:path';import { spawnSync } from 'node:child_process';import { createHash } from 'node:crypto';-import { DEFAULT_BASE_REF, readAcceptedBundles } from './size-base.mjs';-import { archiveProblem } from './size-growth.mjs';+import { DEFAULT_BASE_REF, baseRefExists, measureBaseArchive, readAcceptedBundles } from './size-base.mjs';+import { archiveCeilingProblem, archiveGrowthProblem } from './size-growth.mjs';const metadata = JSON.parse(await readFile('package.json', 'utf8'));const release = JSON.parse(await readFile('public/release.json', 'utf8'));@@ -18,6 +18,21 @@ assert.equal(release.packageAlias, '67js');assert.equal(release.integrity, `sha512-${createHash('sha512').update(binary).digest('base64')}`);assert.ok(binary.length < 1024 * 1024, 'Library and optional addon wrappers must fit within a 1 MiB archive.');assert.ok((await readFile('build/67.module.js')).length < 150000, 'The core must exclude the optional asset decoder.');+// The archive is measured against the base branch like a bundle. The release ceiling in budgets.json is reported, and+// npm run smoke:package -- --absolute enforces it.+async function checkArchiveSize(archiveBytes) {+ const baseRef = process.env.SIZE_BASE_REF ?? DEFAULT_BASE_REF;+ if (baseRefExists(baseRef)) {+ const accepted = readAcceptedBundles(baseRef);+ const growthFailure = archiveGrowthProblem(archiveBytes, await measureBaseArchive(baseRef), accepted);+ assert.ok(!growthFailure, growthFailure);+ } else {+ console.log(`No ${baseRef} to compare the archive with, so the archive growth check is skipped. Fetch it, or set SIZE_BASE_REF.`);+ }+ const ceilingFailure = archiveCeilingProblem(archiveBytes, sizeBudgets.archiveBytes);+ if (ceilingFailure && process.argv.includes('--absolute')) assert.fail(ceilingFailure);+ if (ceilingFailure) console.log(ceilingFailure);+}const consumer = await mkdtemp(resolve(tmpdir(), '67js-consumer-'));await writeFile(resolve(consumer, 'package.json'), JSON.stringify({ private: true, type: 'module' }));const npmCli = process.env.npm_execpath ?? resolve(dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js');@@ -34,8 +49,7 @@ if (published) {const sourcePackResult = JSON.parse(sourcePack.stdout);const packedSource = Array.isArray(sourcePackResult) ? sourcePackResult[0] : sourcePackResult[metadata.name];assert.ok(packedSource?.filename, 'npm pack must return a source archive.');- const archiveFailure = archiveProblem(packedSource.size, sizeBudgets.archiveBytes, readAcceptedBundles(process.env.SIZE_BASE_REF ?? DEFAULT_BASE_REF));- assert.ok(!archiveFailure, archiveFailure);+ await checkArchiveSize(packedSource.size);const sourceArchive = resolve(consumer, packedSource.filename);installTarget = `67js@file:${sourceArchive.replaceAll('\\', '/')}`;}diff --git a/tests/size-growth.test.js b/tests/size-growth.test.jsindex 8828a808..44755e5c 100644--- a/tests/size-growth.test.js+++ b/tests/size-growth.test.js@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os';import { join } from 'node:path';import test from 'node:test';import { readAcceptedBundles } from '../scripts/size-base.mjs';-import { archiveProblem, compareToBase, growthAllowance, parseSizeNote } from '../scripts/size-growth.mjs';+import { archiveAllowance, archiveCeilingProblem, archiveGrowthProblem, compareToBase, growthAllowance, parseSizeNote } from '../scripts/size-growth.mjs';const size = gzip => ({ min: gzip * 3, gzip });@@ -42,10 +42,28 @@ test('a size note accepts only the bundles it names', () => {assert.match(problems[0], /scene:lit-box grew by 4000/);});-test('the archive fails over its ceiling unless a note names it', () => {- assert.match(archiveProblem(741000, 740000), /over its archive ceiling of 740000 in bench\/size\/budgets\.json by 1000\. Reduce it, or accept it/);- assert.equal(archiveProblem(739000, 740000), null);- assert.equal(archiveProblem(741000, 740000, new Map([['archive', 'ships the new guide']])), null);+test('the archive gets 2% of the base archive, and a note accepts more', () => {+ assert.equal(archiveAllowance(750000), 15000);+ assert.match(archiveGrowthProblem(765001, 750000), /765001 bytes, 15001 more than the 750000 bytes of the base branch, over its allowance of 15000\. Reduce it, or accept it/);+ assert.match(archiveGrowthProblem(765001, 750000), /- archive: <why it is worth the bytes>/);+ assert.equal(archiveGrowthProblem(765000, 750000), null);+ assert.equal(archiveGrowthProblem(700000, 750000), null);+ assert.equal(archiveGrowthProblem(790000, 750000, new Map([['archive', 'ships the new guide']])), null);+});++test('two pull requests that each grow the archive within the allowance both pass against their own base', () => {+ const mainBase = 750000;+ const firstPull = archiveGrowthProblem(mainBase + 14000, mainBase);+ const mainAfterFirst = mainBase + 14000;+ const secondPull = archiveGrowthProblem(mainAfterFirst + 14000, mainAfterFirst);+ assert.equal(firstPull, null);+ assert.equal(secondPull, null);+ assert.match(archiveGrowthProblem(mainAfterFirst + 16000, mainAfterFirst), /over its allowance of 15280/);+});++test('the release ceiling is a report that names the number a release refreshes', () => {+ assert.match(archiveCeilingProblem(741000, 740000), /over its release ceiling of 740000 in bench\/size\/budgets\.json by 1000/);+ assert.equal(archiveCeilingProblem(739000, 740000), null);});function git(folder, ...args) {