docs: add README and a live example page

[JohnMcLear]

What

The repo had no README and no runnable example, so this adds both.

README.md

Documents the library end to end:

• A component reference table — all 15 custom elements with their tags, classes, key attributes, and custom events.
• Theming via <ep-theme> (the 4 built-in token sets + runtime registration).
• The <ep-editor> API (Etherpad's Ace engine as a web component) including the collaboration/changeset methods.
• The dev / test / build workflow, and how the Storybook play functions double as the browser test suite.

examples/index.html

A single-page live demo wiring up every component — buttons, inputs, checkboxes, cards, dropdown, toolbar-select, color picker + wheel (driving a user badge), chat messages, modal, toasts, notifications, and a themed <ep-editor> with a working formatting toolbar — plus a theme switcher and a live event log.

Run it from the repo root:

pnpm dev
# open http://localhost:5173/examples/

examples/verify.mjs

A small Playwright script (used to validate the demo) that loads the page in headless Chromium and asserts every element upgrades and the key interactions (modal, toast, notification, theme switch, editor) work.

Verification

From a clean pnpm install:

• pnpm test --run → 82 tests / 15 files pass
• pnpm typecheck → clean
• pnpm build → emits dist/
• node examples/verify.mjs → all 20 checks pass, no console errors

🤖 Generated with Claude Code

---

Also: CI fix

The browser-test job was already failing (on the open dependabot PR too) because pnpm dlx playwright install fetched the latest Playwright instead of the pinned 1.59.1, leaving the expected chrome-headless-shell binary missing. Switched to pnpm exec so the pinned CLI installs the matching browser — this unblocks the test job for this PR and the repo generally.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Add README, live demo, and verification tests

📝 Documentation 🧪 Tests

Walkthroughs

Description

• Add comprehensive README documenting all 15 components with reference table
• Create single-page live demo (examples/index.html) showcasing every component
• Add Playwright verification script (examples/verify.mjs) validating demo functionality
• Document theming system, editor API, and development workflow

Diagram

flowchart LR
  A["Documentation"] -->|README.md| B["Component Reference<br/>Theming Guide<br/>Editor API"]
  A -->|examples/index.html| C["Live Demo<br/>All Components<br/>Event Log"]
  A -->|examples/verify.mjs| D["Playwright Tests<br/>Element Upgrades<br/>Interactions"]
  C -->|validates| D

Loading

File Changes

1. README.md 📝 Documentation +142/-0

Comprehensive library documentation and component reference

• Component reference table with tags, classes, attributes, and custom events
• Theming documentation via `` with built-in token sets
• `` API documentation including collaboration methods
• Development workflow, testing approach, and project layout

README.md

---

2. examples/index.html 📝 Documentation +267/-0

Live interactive demo of all web components

• Single-page demo wiring all 15 components with interactive examples
• Theme switcher demonstrating the four built-in token sets
• Working formatting toolbar for the `` component
• Event log showing real-time component interactions and custom events

examples/index.html

---

3. examples/verify.mjs 🧪 Tests +62/-0

Automated validation script for demo functionality

• Playwright script launching headless Chromium to validate the demo page
• Verifies all 14 custom elements upgrade and render correctly
• Tests key interactions (modal open/close, toast display, notifications, theme switching)
• Confirms editor content loads and no console errors occur

examples/verify.mjs

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0)

1. Verify script wrong port ✓ Resolved 🐞 Bug ≡ Correctness

Description

examples/verify.mjs hard-codes http://localhost:5199/examples/ while the demo page and dev script
assume Vite’s default http://localhost:5173/examples/, so the verification script will fail
out-of-the-box unless the user manually changes Vite’s port.

Code

examples/verify.mjs[R9-10]

Evidence

The demo page explicitly instructs using port 5173 with pnpm dev, and the repo’s dev script is
just vite (no custom port), but verify.mjs navigates to port 5199.

examples/verify.mjs[9-10]
examples/index.html[7-12]
package.json[35-42]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`examples/verify.mjs` navigates to a hard-coded localhost port (5199) that doesn't match the port users are instructed to use when running `pnpm dev` (Vite default 5173). This makes the verification script fail for a default setup.
## Issue Context
- `pnpm dev` runs `vite` with no port override.
- `examples/index.html` instructs opening the demo on port `5173`.
## Fix Focus Areas
- examples/verify.mjs[9-10]
- examples/index.html[7-12]
- package.json[35-42]
## Suggested fix
- Use `http://localhost:5173/examples/` as the default.
- Preferably make the base URL configurable via env var and/or CLI arg, e.g.:
- `const baseURL = process.env.DEMO_URL ?? 'http://localhost:5173/examples/';`
- `await page.goto(baseURL, ...)`
- Update comments/docs if you intentionally want a non-default port.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Verify ignores failed checks 🐞 Bug ☼ Reliability

Description

examples/verify.mjs logs failures from check() but discards the returned boolean and exits based
only on captured console errors, so it can exit 0 even when one or more checks fail.

Code

examples/verify.mjs[R12-26]

Evidence

check() returns a boolean, but every call site ignores it; the script’s exit code is computed
solely from errors.length, not from check results.

examples/verify.mjs[12-26]
examples/verify.mjs[58-62]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The verification script's `check()` helper returns a boolean but callers ignore it, so failed checks don't affect the exit code. The process exit status is currently determined only by `errors.length`, which can let broken interactions/components pass verification.
## Issue Context
This script is meant to validate the demo page. It should return non-zero if *either*:
- any `check()` fails, or
- any console/page errors were captured.
## Fix Focus Areas
- examples/verify.mjs[12-26]
- examples/verify.mjs[58-62]
## Suggested fix
- Track failures, e.g.:
- `let failed = 0;`
- `if (!(await check(...))) failed++;`
- At the end, exit non-zero when `failed > 0 || errors.length > 0`.
- (Recommended) Wrap the main body in `try/finally` to always `await browser.close()` even if navigation/clicks throw.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-free-for-open-source-projects]

2. Verify ignores failed checks 🐞 Bug ☼ Reliability

examples/verify.mjs logs failures from check() but discards the returned boolean and exits based
only on captured console errors, so it can exit 0 even when one or more checks fail.

Agent Prompt

## Issue description
The verification script's `check()` helper returns a boolean but callers ignore it, so failed checks don't affect the exit code. The process exit status is currently determined only by `errors.length`, which can let broken interactions/components pass verification.

## Issue Context
This script is meant to validate the demo page. It should return non-zero if *either*:
- any `check()` fails, or
- any console/page errors were captured.

## Fix Focus Areas
- examples/verify.mjs[12-26]
- examples/verify.mjs[58-62]

## Suggested fix
- Track failures, e.g.:
  - `let failed = 0;`
  - `if (!(await check(...))) failed++;`
- At the end, exit non-zero when `failed > 0 || errors.length > 0`.
- (Recommended) Wrap the main body in `try/finally` to always `await browser.close()` even if navigation/clicks throw.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools