From 49e73b932544ff65113a66a380989aea51f2e2bd Mon Sep 17 00:00:00 2001 From: Travis Bonnet Date: Wed, 20 May 2026 15:09:44 -0500 Subject: [PATCH] docs: replace broken install snippets in README + docs Caught during a final pre-send audit. The CDN snippet pointed at `https://eats.travisfixes.com/v1.js`, which returns 401 (the worker only serves API routes). The npm snippet pointed at `@travisbreaks/travisEATSbugs`, which is not on the public npm registry (the README's own Status line correctly states "Public npm publish lands at v1.0.0", so the snippet contradicted itself). This PR replaces both with paths that actually work today, mirroring the fix that just landed on the marketing site: - **README.md** Install section: script tag pointing at the travismakes.org bundle that the live demo uses, plus a vendor-from- repo path. Includes the canonical wiring snippet (`LocalStorageAdapter` + `AnnotationPageMode` + `init({ onToggle })`). - **docs/install.md** fully rewritten. Four options (script tag, vendor bundle, pnpm pack, self-hosted worker) with a picking-guide table at the bottom. Honest note about `eats.travisfixes.com` being a not-public-signup destination today; public hosted tier lands in the `teb-cloud` repo per the strategic plan. - **docs/architecture.md** Widget Delivery section: same swap; the `eats.travisfixes.com/v1.js` route is correctly framed as a v1.0 deliverable, not a present-tense claim. `client-facing-tenancy.md` line 239 still mentions `eats.travisfixes.com/v1.js` but that file is a design doc for the multi-tenant Phase 2 work and correctly describes future state. No change needed there. No code or schema change. Tests + lint untouched. Em-dash gate green. Co-Authored-By: Tadao --- README.md | 35 +++++++++++---- docs/architecture.md | 14 +++--- docs/install.md | 104 +++++++++++++++++++++++++++++-------------- 3 files changed, 105 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 5267e0a..d903bef 100644 --- a/README.md +++ b/README.md @@ -11,24 +11,43 @@ ## Install -CDN: +Pre-1.0. A dedicated CDN endpoint and a public npm publish both land at v1.0. Until then, two paths that work today: + +### Script tag (alpha demo) + +Drop in the same bundle the live demo uses, served from the travismakes.org static site: ```html - + ``` -npm / pnpm / yarn: +The bundle exposes `window.travisEATSbugs`. Wire it up: -```bash -pnpm add @travisbreaks/travisEATSbugs +```html + ``` -```ts -import { init } from '@travisbreaks/travisEATSbugs' +### Vendor from the repo -init({ project: 'YOUR_PROJECT_TOKEN' }) +For production use, clone, build, and serve the bundle from your own CDN: + +```bash +git clone https://github.com/travisbreaks/travisEATSbugs.git +cd travisEATSbugs +pnpm install +pnpm --filter @travisbreaks/travisEATSbugs run build +# packages/widget/dist/index.global.js is the IIFE bundle ``` +Swap the `LocalStorageAdapter` for `@travisbreaks/travisEATSbugs-cloudflare` (D1-backed) or `@travisbreaks/travisEATSbugs-http` (any REST endpoint) when you're ready to persist beyond the visitor's browser. See [docs/install.md](docs/install.md) for the full walkthrough. + ## What it does - Visitors click the bug icon, then click any element on the page to leave a comment. diff --git a/docs/architecture.md b/docs/architecture.md index 710614c..7727fae 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -24,20 +24,22 @@ No existing tool ships visual feedback + agency project rollups + hours tracking ## Core architecture -### Widget delivery: snippet + npm +### Widget delivery: script tag + vendored package -Two install paths: +Pre-1.0 install paths (see [install.md](./install.md) for the full walkthrough): -1. **One-line CDN snippet:** +1. **Script tag (alpha demo):** ```html - + ``` -2. **npm package:** +2. **Vendored package:** ```ts import { init } from '@travisbreaks/travisEATSbugs' - init({ project: 'YOUR_TOKEN' }) + init({ /* opts */ }) ``` +A dedicated CDN endpoint (e.g. `eats.travisfixes.com/v1.js`) and a public npm publish both land at v1.0; see the strategic plan for the bundle-versioning + tenant-pin design. + ### Style isolation: Shadow DOM The widget injects into a Shadow DOM root. Required for installability: host pages have unpredictable CSS, and the widget must not leak into or absorb from host styles. The Shadow DOM also makes the widget invisible to host-page event handlers unless we explicitly bubble events out. diff --git a/docs/install.md b/docs/install.md index 68e5766..f7ac602 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,69 +1,105 @@ # Installing travisEATSbugs -**Status:** v0 scaffold. The instructions below describe the v0.1+ target install paths. +**Status:** alpha (`0.0.10-alpha.0`). A dedicated CDN endpoint and a public npm publish both land at v1.0. Until then, the install paths below are how to drop the widget into a real app today. -## Option 1: CDN snippet (recommended for most users) +## Option 1: Script tag (alpha demo) -Add one line to your HTML ``: +Drop in the same bundle the [live demo](https://travismakes.org/travis-eats-bugs/) uses, served from the travismakes.org static site: ```html - + ``` -That's it. The widget injects a floating bug icon in the bottom-right of every page. Click it to enter mark mode. +The bundle exposes `window.travisEATSbugs`. Wire it up with the localStorage adapter (browser-only, no backend needed): -## Option 2: npm package +```html + +``` + +Good for prototypes, demos, internal-only feedback flows. Notes live in the visitor's browser; nothing leaves their machine. + +## Option 2: Vendor the bundle from the repo -If your app is JS-bundled (React, Vue, Svelte, Solid, etc): +For production use, clone the repo, build the widget, and serve the bundle from your own CDN: ```bash -pnpm add @travisbreaks/travisEATSbugs +git clone https://github.com/travisbreaks/travisEATSbugs.git +cd travisEATSbugs +pnpm install +pnpm --filter @travisbreaks/travisEATSbugs run build ``` -Then in your app entry point: +The IIFE bundle lands at `packages/widget/dist/index.global.js`. Drop it into your asset pipeline (`/static/`, an R2 bucket, your own CDN, whatever). -```ts -import { init } from '@travisbreaks/travisEATSbugs' +## Option 3: Vendor the workspace as a pnpm dependency -init({ - project: 'YOUR_PROJECT_TOKEN', - position: 'bottom-right', // optional -}) -``` +If your app is JS-bundled (React, Vue, Svelte, Solid, etc), you can vendor the widget package directly while waiting for the public npm publish. From your app: -## Option 3: Self-hosted backend +```bash +pnpm pack /path/to/travisEATSbugs/packages/widget +pnpm add ./travisbreaks-travisEATSbugs-0.0.10-alpha.0.tgz +``` -If you want full control of where comments are stored, use the HTTP adapter: +Then in your app entry point: ```ts -import { init } from '@travisbreaks/travisEATSbugs' -import { httpAdapter } from '@travisbreaks/travisEATSbugs-http' +import { init, AnnotationPageMode, LocalStorageAdapter } from '@travisbreaks/travisEATSbugs' -init({ - adapter: httpAdapter({ - baseUrl: 'https://your-app.com/api/feedback', - headers: { Authorization: `Bearer ${token}` }, - }), -}) +const api = new LocalStorageAdapter({ namespace: 'my-app' }) +const pageMode = new AnnotationPageMode({ api }) +pageMode.mount() +init({ onToggle: (active) => active ? pageMode.activate() : pageMode.deactivate() }) ``` -Your endpoint needs to implement the [Adapter interface](./architecture.md#store-pluggable-adapter). - -## Option 4: Self-hosted on Cloudflare +## Option 4: Self-hosted Cloudflare worker + D1 -If you want our backend topology but on your own Cloudflare account, deploy the worker package: +For a persistent backend with full multi-user CRUD + AI triage, deploy the worker package to your own Cloudflare account: ```bash git clone https://github.com/travisbreaks/travisEATSbugs.git cd travisEATSbugs/apps/worker pnpm install +# Configure wrangler.toml with your D1 binding and secrets pnpm wrangler deploy ``` -Then point the widget at your worker URL. +Point the widget at your worker by swapping the adapter: + +```ts +import { httpAdapter } from '@travisbreaks/travisEATSbugs-http' +import { init } from '@travisbreaks/travisEATSbugs' + +const api = httpAdapter({ + baseUrl: 'https://your-worker.your-subdomain.workers.dev', + headers: { Authorization: `Bearer ${process.env.MEMBER_TOKEN}` }, +}) +init({ adapter: api, ... }) +``` + +The worker exposes `/annotations`, `/annotations/bulk`, `/authors`, and `/triage` (opt-in AI classification via `ANTHROPIC_API_KEY`). See [architecture.md](./architecture.md) for the full data model and adapter contracts. + +## What about the hosted backend at `eats.travisfixes.com`? -## Getting a project token +The Cloudflare worker that backs the maintainer's own deployments is live at `https://eats.travisfixes.com`. It is **not a public signup destination** today. The route surface is the same as Option 4 (you'd authenticate with a member token and call the same endpoints), but member token provisioning is a manual step out-of-band. A signup UI + public hosted tier land in the paid `teb-cloud` repo, not in this OSS repo. -For the hosted backend (Option 1 or 2 without a custom adapter), sign up at [eats.travisfixes.com](https://eats.travisfixes.com) and create a project. The dashboard shows your token. +## Picking between options -For self-hosted (Options 3 or 4), the token is whatever string you want; the widget passes it through unchanged. +| If you want to... | Use option | +|---|---| +| Try the widget on your site in 60 seconds with no backend | 1 (script tag + localStorage) | +| Ship the widget on a production site with your own CDN | 2 (vendor the bundle) | +| Use the widget inside a JS-bundled app (React/Vue/etc) | 3 (pnpm pack + vendor) | +| Run the full hosted-backend topology on your own Cloudflare | 4 (self-hosted worker) |