diff --git a/AGENTS.md b/AGENTS.md index 17dfaf4..119be43 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ This file provides guidance to AI coding agents when working with code in this r - `pnpm lint` — ESLint (flat config in `eslint.config.mjs`, includes `eslint-plugin-jsdoc`). - `pnpm format` — Prettier over the repo. - `pnpm build` — `tsc` emits `.d.ts` types, then `copy:source` uses esbuild to minify/bundle `src/*.js` + `src/utils/*` into `dist/` as ESM. **`dist/` is what gets published; `src/` is shipped as the readable source.** -- `pnpm size-limit` — enforces the per-file byte budgets declared in `package.json` `size-limit` (each `dist/` file has its own, e.g. `WebComponent.js` ≤ 2.05 KB, `html.js` ≤ 0.6 KB, each util ≤ 0.5–0.8 KB). Keep additions tiny; this gate is a core project value. `size-change-log.md` is the running record of how each change moved the base-class bundle and why. +- `pnpm size-limit` — enforces the per-file byte budgets declared in `package.json` `size-limit` (each `dist/` file has its own, e.g. `WebComponent.js` ≤ 2.05 KB, `html.js` ≤ 0.6 KB, each util ≤ 0.5–0.8 KB). Keep additions tiny; this gate is a core project value. `size-change-log.md` is the running record of how each change moved the base-class bundle and why; its latest row's min+brotli figure is the single source of truth for the base-class size, so `docs/src/content/docs/guides/library-size.md` must be updated in lockstep whenever a new row lands. - `pnpm test:types` — builds, then type-checks the TS type tests (`test/types/typed-props.test-d.ts`) and the `demo/examples/typed-props/` example. `this.props` is typed by passing the props shape as a class type argument: `class X extends WebComponent`. - `pnpm docs` — run the Astro docs site (`docs/` workspace) locally. - `pnpm demo` — run the Vite examples showcase (`demo/` workspace) locally; `pnpm demo:build` builds it. @@ -54,7 +54,7 @@ Any change to observable behavior ships as one unit — code alone is an incompl 1. **Tests** — unit specs in `test/` (or colocated `*.test.mjs`) covering the new contract *and* the old behavior it replaces. Add a `test/e2e/` spec whenever the behavior depends on something happy-dom cannot model faithfully — CSS selector matching, computed styles, custom-element upgrade timing. 2. **Demo examples** — a runnable example under `demo/examples/` that demonstrates the behavior, linked from a card in `demo/index.html`. Update any existing example the change affects, including ones that now emit a console warning or model a discouraged pattern. 3. **Documentation** — the guide under `docs/src/content/docs/guides/` that doubles as the behavioral spec. For a breaking change, also update the `README.md` banner with the migration consumers have to perform. -4. **Size budget** — `pnpm size-limit` stays green. If an addition genuinely needs more headroom, raise the budget in `package.json` deliberately and say so in the change description; never let it drift silently. +4. **Size budget** — `pnpm size-limit` stays green. If an addition genuinely needs more headroom, raise the budget in `package.json` deliberately and say so in the change description; never let it drift silently. Whenever the change moves the base-class bundle, record it as a new row in `size-change-log.md` **and** update the headline size in `docs/src/content/docs/guides/library-size.md` to match that row's new min+brotli figure — the two must never disagree. Verify with `pnpm test:all` (unit + types + e2e across all engines) before calling the change done. diff --git a/docs/src/components/SizeChart.astro b/docs/src/components/SizeChart.astro index c869b64..3ba8ff4 100644 --- a/docs/src/components/SizeChart.astro +++ b/docs/src/components/SizeChart.astro @@ -6,7 +6,7 @@ const data = [ { name: 'vanilla', kb: 0.2 }, { name: 'web-component-base', kb: 2.6, accent: true }, - { name: '@elenajs/core', kb: 3.3 }, + { name: '@elenajs/core', kb: 3.4 }, { name: 'lit', kb: 5.3 }, { name: 'fast-element', kb: 12.2 }, ] @@ -15,7 +15,7 @@ const max = Math.max(...data.map((d) => d.kb))
{ diff --git a/docs/src/content/docs/guides/comparison.md b/docs/src/content/docs/guides/comparison.md index ed4a6ac..fec2684 100644 --- a/docs/src/content/docs/guides/comparison.md +++ b/docs/src/content/docs/guides/comparison.md @@ -15,10 +15,10 @@ See it live: [Library comparison demo ↗](https://demo.webcomponent.io/examples | Library | Version | Minified | Gzip | Brotli | | ------------------------- | ------- | -------- | ------- | ---------- | -| **web-component-base** | 6.1.0 | 6.7 kB | 2.9 kB | **2.6 kB** | -| `@elenajs/core` | 1.0.0 | 9.1 kB | 3.7 kB | 3.3 kB | +| **web-component-base** | 6.1.1 | 6.7 kB | 2.9 kB | **2.6 kB** | +| `@elenajs/core` | 1.0.0 | 9.1 kB | 3.7 kB | 3.4 kB | | `lit` | 3.3.3 | 15.3 kB | 5.9 kB | 5.3 kB | -| `@microsoft/fast-element` | 3.0.1 | 44.9 kB | 13.7 kB | 12.2 kB | +| `@microsoft/fast-element` | 3.0.1 | 44.8 kB | 13.6 kB | 12.2 kB | | vanilla `HTMLElement` | - | - | - | ~0.2 kB | For scale: even after all of the v5.2–v6.1 work, the WCB counter is **~21% smaller than Elena, ~51% smaller than Lit, and ~79% smaller than FAST**. @@ -51,4 +51,4 @@ For what these numbers and capabilities add up to (and when they don't) see [Why --- -_WCB re-measured 2026-07-20 at v6.1.0; the other libraries measured 2026-07-19, with esbuild, Node zlib (gzip −9, brotli q11), at the pinned versions above. Methodology: identical counter component per library, bundled per library, compressed. Re-run them yourself — the counters and the [`measure.mjs`](https://demo.webcomponent.io/examples/library-comparison/) script live in the demo workspace (`demo/examples/library-comparison/`). The benchmark is trivially reproducible with the versions pinned above._ +_WCB re-measured 2026-07-23 at v6.1.1; the other libraries measured 2026-07-19, with esbuild, Node zlib (gzip −9, brotli q11), at the pinned versions above. Methodology: identical counter component per library, bundled per library, compressed. Re-run them yourself — the counters and the [`measure.mjs`](https://demo.webcomponent.io/examples/library-comparison/) script live in the demo workspace (`demo/examples/library-comparison/`). The benchmark is trivially reproducible with the versions pinned above._ diff --git a/docs/src/content/docs/guides/why.md b/docs/src/content/docs/guides/why.md index dec0e3b..aff4e0a 100644 --- a/docs/src/content/docs/guides/why.md +++ b/docs/src/content/docs/guides/why.md @@ -11,7 +11,7 @@ WCB exists for five reasons: 2. **Zero tooling, genuinely.** No compiler, no decorators, no build step: one `import` from a CDN in a `