mirror of
https://github.com/PR0M3TH3AN/bitgate.git
synced 2026-10-27 08:31:00 +00:00
thePR0M3TH3AN
adeba151b8
Renames the project and makes it as easy to adopt as BitLogin, which was the stated bar and which it did not previously meet. Rename (ADR 0005): @nostr-governance/* -> @bitgate/*, governance-* elements -> bitgate-*, createGovernanceRuntime -> createBitGate. "Governance" reads as DAO voting to this audience and named a category rather than a product; BitGate names the benefit and joins the bit- family that BitVid and BitRoad compose with. Domain types keep their names — the product is BitGate, the subject matter is still governance. The migration plan is left as written; this ADR records the change rather than rewriting history. Drop-in distribution (ADR 0006): adopting BitGate meant supplying a transport, authoring a policy, and wiring every element in JavaScript. Now: - createRelayTransport(urls) — WebSocket transport with reconnection, backoff, subscription replay, and cross-relay dedupe - policy presets (social, commerce, admin-only) addressable by name; the engine still carries no thresholds of its own - <bitgate-provider> — configuration in markup, with descendants finding the runtime through a bubbling context event rather than DOM walking, which breaks across shadow boundaries - npm run build:widget — a self-contained dist/bitgate.js That last one came from running it in a browser rather than from a test. Bare specifiers resolve in Node and vitest but not in a browser, so the widget source worked everywhere except a plain static page — the one place it exists to serve. The bundle is not committed: consumers build from reviewed source. Also found by running it: the provider's ready event fires during element upgrade, before a page that defines elements after parsing can attach a listener, so it now exposes `ready` as a promise too. Four bugs fixed along the way, three found by new tests and one by the browser: admin state stayed silent when a roster change altered capabilities but no denials; the relay transport sent every subscription twice on connect; the commerce preset computed a meaningless visibility verdict at checkout and could hide a listing from its own seller; <bitgate-status> threw on an unusable decision. 759 tests; lint, typecheck, and both builds clean.
51 lines
2.2 KiB
Markdown
51 lines
2.2 KiB
Markdown
# ADR 0006 — Ship a built, self-contained widget
|
|
|
|
**Status:** accepted
|
|
|
|
## Context
|
|
|
|
BitGate was a well-factored SDK that was not droppable into a page. Adopting it
|
|
required supplying a transport adapter, authoring a policy definition, and
|
|
wiring every element in JavaScript. BitLogin sets a much higher bar: copy two
|
|
files, add one script tag and one element.
|
|
|
|
Testing the widget in a real browser exposed a failure no unit test could
|
|
catch. `packages/widget/src/index.js` imports `@bitgate/core` and
|
|
`@bitgate/runtime` as bare specifiers. Node and the test runner resolve those
|
|
through `node_modules`; a browser cannot resolve them at all. The source worked
|
|
everywhere except the one place the widget exists to serve.
|
|
|
|
## Decision
|
|
|
|
Three pieces close the gap.
|
|
|
|
1. **`createRelayTransport(urls)`** — a small WebSocket transport, so nobody
|
|
writes an adapter to get started. It speaks enough of the protocol to load
|
|
state, subscribe, and publish; it is not a general-purpose relay client.
|
|
|
|
2. **Policy presets** — `social`, `commerce`, `admin-only`, addressable by name.
|
|
The engine still carries no thresholds: these are application policies that
|
|
happen to ship in the box, and every number in them is documented as a
|
|
starting point.
|
|
|
|
3. **`<bitgate-provider>`** — configuration in markup. Descendants find the
|
|
runtime by firing a bubbling context-request event rather than walking up
|
|
the DOM, which would break across shadow boundaries.
|
|
|
|
Plus a build step (`npm run build:widget`) producing a single self-contained
|
|
`dist/bitgate.js` via esbuild.
|
|
|
|
## Consequences
|
|
|
|
A static page needs one script tag and one element, matching BitLogin.
|
|
|
|
The build output is deliberately **not** committed. Consumers build from
|
|
reviewed source and self-host the result, as BitLogin instructs, because a
|
|
moderation widget is exactly the kind of artifact where reading the source
|
|
matters and trusting a prebuilt minified blob does not.
|
|
|
|
The provider exposes `ready` as a promise as well as an event. The event fires
|
|
during element upgrade — before a page that calls `defineBitGateElements()`
|
|
after parsing could attach a listener — so an event alone was a race that
|
|
silently lost. This was found by running the demo, not by a test.
|