pebble/library
Prebuilt 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 <script type="module"> tag. pebble is bundled in: there is no JSX compiler and no pebble build step on the consumer's side. The import IS the registration.
Components
- toaster —
<pebble-toaster>: toast announcements, polite and assertive channels. docs/toaster.md - timeline —
<pebble-timeline>: phases on a shared time axis, one lane per track, drawn from the server's<table>, which stays the data of record. docs/timeline.md - tablet —
<pebble-tablet>: a notes editor on its own pebble-native engine, plain text or a page-defined dialect (commands, a decorated backdrop, task boxes); the<textarea>stays the surface and the form field of record. 10.0 kB gz. docs/tablet.md - vote —
<pebble-vote>: an up/down vote over the server's two forms, painted at once, posted with fetch and reconciled with the server's tally; a captcha falls back to the native post. docs/vote.md - more —
<pebble-more>: a feed's "load more" link that loads the next page's items into the list as it nears the viewport; the link stays the no-JS path. docs/more.md - lite-youtube —
<pebble-lite-youtube>: a YouTube poster link that becomes the privacy-enhanced player on activation; nothing loads from YouTube before. docs/lite-youtube.md - combobox —
<pebble-combobox>: suggestions under a search form's field as the reader types, from the server's HTML, with the ARIA combobox pattern; the form stays a plain GET search. docs/combobox.md - sequence —
<pebble-sequence>: a sequence of steps edited as a tree of cards — linear runs, branching steps split into outcomes — with the page's kinds and fields; a<textarea>of JSON stays the form field of record. docs/sequence.md
Using a component
Vendor the dist (the flow today — docs/consuming.md):
<script type="module" src="vendor/pebble-library/toaster.js"></script>
<pebble-toaster></pebble-toaster>
or import it from your own module graph — a plain ESM file, side effect and all:
import "./vendor/pebble-library/toaster.js";
Installed as a package (the registry flow, once published), the same import by name:
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:
| 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/<name>.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
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/<name>), 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:*, neverfile:. - Build entrypoints are shims generated into
.build/, never a package's ownindex(Bun elides the graph of an entrypoint that lives inside the package it builds). - Never
_$-prefix a property on aSymbol.forrecord — 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.tsrefuses to build one that does.
Adding a component
packages/<name>/package.json "@pebble/<name>", type: module, exports: { ".": "./index.ts" }
packages/<name>/index.ts(x) self-registering: define("<tag>", …)
packages/<name>/<name>.css optional: also shipped raw as dist/<name>.css
bun run build picks it up → dist/<name>.js + dist/<name>.d.ts (+ dist/<name>.css). Then add its row to test/size.test.ts: the measured size + ~15%.