# pebble/library Prebuilt [pebble](https://toboggan.cloud/pebble/pebble) components: drop-in custom elements, no compiler needed. Each package in `packages/` builds a self-contained dist — bundle, types, stylesheet — that a consumer vendors or loads with a ` ``` or import it from your own module graph — a plain ESM file, side effect and all: ```ts import "./vendor/pebble-library/toaster.js"; ``` Installed as a package (the registry flow, once published), the same import by name: ```ts import "@pebble/toaster"; ``` The element registers itself; there is nothing else to import and nothing to compile. Importing twice is safe: a second bundle carrying the component gets the first's constructor back. ## Size Whole-bundle numbers from `bun run sizes` (the release pipeline: Bun bundle + minify, then a Terser internal-property pass), budgets enforced in [test/size.test.ts](test/size.test.ts): | component | gzip | brotli | Δ over floor | |---|---|---|---| | floor (an empty component: shell + runtime + signals) | 4020 B | 3618 B | — | | combobox | 6627 B | 5988 B | 2607 B | | sequence | 11391 B | 10301 B | 7371 B | | lite-youtube | 5049 B | 4469 B | 1029 B | | more | 5728 B | 5121 B | 1708 B | | timeline | 12273 B | 10961 B | 8253 B | | toaster | 8513 B | 7639 B | 4493 B | | vote | 6023 B | 5393 B | 2003 B | tablet: engine rewrite in flight; its size row lands with it. The floor is one-time runtime cost, shared by every component on the page; the Δ is what a component itself adds. ## The pebble dependency The framework comes from the forge's npm registry as an exact pin, `"@pebble/pebble": "0.2.1"`, with the `@pebble` scope mapped in `bunfig.toml` (the token is `$TOBOGGAN_TOKEN`, never a literal). Exact pins, never ranges; a bump is its own commit. Consumers of the library never install pebble: it is bundled into each `dist/.js`. The library compiles its JSX through pebble's consumer compiler, `@pebble/pebble/plugin` (the test preload in `plugins/preload.ts`, the build, the size script). Since 0.2.0 the compiler's Babel packages are optional peers of pebble, needed only by that entry, so the library pins them itself as exact dev dependencies at the versions pebble names: `@babel/core` 7.29.7, `@babel/preset-typescript` 7.29.7, `babel-plugin-jsx-dom-expressions` 0.40.10. Bump them with pebble. For a dev loop against an unpublished pebble, `"@pebble/pebble": "file:../pebble/dist"` works as a local override (pebble's dist is its published face; `bun run sync-pebble` prepares it). Never commit it. ## Contributing ```sh TOBOGGAN_TOKEN=… bun install # the @pebble scope needs the registry token bun test # happy-dom + the consumer compiler — the consumer's path bun run typecheck # tsc --noEmit bun run build # per-package dists in dist/ bun run sizes # the release-size table; budgets in test/size.test.ts bun run smoke # dist/toaster.js on real headless Chromium (build first) ``` With the `file:` override in an OpenCode worktree (`.worktrees/`), run `bun run sync-pebble` **before** the first `bun install` — it symlinks `../pebble` so the `file:` dependency resolves. If `bun test` fails with a CSS compile error naming a worktree that no longer exists, the staleness is bun's transpiler cache, not the tree: delete the offending entries under `~/.bun/install/cache` (or the whole cache) and re-run. Rules that bite, from the pebble repo: - Workspace packages use `workspace:*`, never `file:`. - Build entrypoints are shims generated into `.build/`, never a package's own `index` (Bun elides the graph of an entrypoint that lives inside the package it builds). - Never `_$`-prefix a property on a `Symbol.for` record — the Terser pass mangles `_$` names per build, and those records cross build boundaries. - Component packages do not set `sideEffects: false` — the import IS the registration. `scripts/build.ts` refuses to build one that does. ## Adding a component ``` packages//package.json "@pebble/", type: module, exports: { ".": "./index.ts" } packages//index.ts(x) self-registering: define("", …) packages//.css optional: also shipped raw as dist/.css ``` `bun run build` picks it up → `dist/.js` + `dist/.d.ts` (+ `dist/.css`). Then add its row to `test/size.test.ts`: the measured size + ~15%. ## Docs [docs/](docs/README.md)