Add Ripple TS browser extension template

AGENTS.md

@@ -44,6 +44,11 @@ framework-specific values such as its Tailwind stylesheet path.
 
 - `templates/astro/`: standalone Astro template and Astro-specific runtime,
   build, and Cloudflare static-assets configuration.
+- `templates/ripple-ts/`: standalone Ripple TS small-app workspace with a
+  source-first reusable component package.
+- `templates/ripple-ts-browser-extension/`: standalone Manifest V3 extension
+  template with Ripple UI, WXT entrypoints, typed messaging, and a source-first
+  reusable component package.
 - `templates/tanstack-start/`: standalone TanStack Start template and its
   Cloudflare Workers SSR configuration.
 - `shared/agent/`: agent instructions materialized into every template.
@@ -128,8 +133,8 @@ bun run build
 ```
 
 After changing a shared source, run `bun run shared:sync` before validation.
-`bun run check` covers root checks, shared drift, and both template checks;
-`bun run build` builds both templates.
+`bun run check` covers root checks, shared drift, and every template check;
+`bun run build` builds every template.
 
 For a framework-local investigation, run scripts from that template directory
 or through `bun run --cwd templates/<name> <script>`. Astro lifecycle commands

README.md

@@ -6,11 +6,12 @@ repository does not maintain versioned template releases.
 
 ## Templates
 
-| Template       | Source directory           | Runtime                                               |
-| -------------- | -------------------------- | ----------------------------------------------------- |
-| Astro          | `templates/astro`          | Astro 7, Keystatic, React 19 islands, Tailwind CSS v4 |
-| Ripple TS      | `templates/ripple-ts`      | Ripple, TSRX, Vite+, Bun workspace                    |
-| TanStack Start | `templates/tanstack-start` | TanStack Start, React 19, Tailwind CSS v4             |
+| Template                    | Source directory                        | Runtime                                               |
+| --------------------------- | --------------------------------------- | ----------------------------------------------------- |
+| Astro                       | `templates/astro`                       | Astro 7, Keystatic, React 19 islands, Tailwind CSS v4 |
+| Ripple TS                   | `templates/ripple-ts`                   | Ripple, TSRX, Vite+, Bun workspace                    |
+| Ripple TS Browser Extension | `templates/ripple-ts-browser-extension` | Ripple, WXT, Manifest V3, Bun workspace               |
+| TanStack Start              | `templates/tanstack-start`              | TanStack Start, React 19, Tailwind CSS v4             |
 
 Create an Astro project:
 
@@ -38,6 +39,19 @@ vp create github:celados/templates/templates/ripple-ts \
   -- <project-directory>
 ```
 
+Create a Ripple TS browser extension:
+
+```bash
+vp create github:celados/templates/templates/ripple-ts-browser-extension \
+  --package-manager bun \
+  --no-agent \
+  --editor vscode \
+  --hooks \
+  --git \
+  --no-interactive \
+  -- <project-directory>
+```
+
 Create a TanStack Start project:
 
 ```bash

package.json

@@ -5,11 +5,11 @@
   "scripts": {
     "shared:sync": "bun scripts/sync-shared.ts",
     "shared:check": "bun scripts/sync-shared.ts --check",
-    "install:templates": "bun install --cwd templates/astro --frozen-lockfile && bun install --cwd templates/ripple-ts --frozen-lockfile && bun install --cwd templates/tanstack-start --frozen-lockfile",
+    "install:templates": "bun install --cwd templates/astro --frozen-lockfile && bun install --cwd templates/ripple-ts --frozen-lockfile && bun install --cwd templates/ripple-ts-browser-extension --frozen-lockfile && bun install --cwd templates/tanstack-start --frozen-lockfile",
     "check:root": "vp check",
-    "check:templates": "bun run --cwd templates/astro check && bun run --cwd templates/ripple-ts check && bun run --cwd templates/tanstack-start check",
+    "check:templates": "bun run --cwd templates/astro check && bun run --cwd templates/ripple-ts check && bun run --cwd templates/ripple-ts-browser-extension check && bun run --cwd templates/tanstack-start check",
     "check": "bun run check:root && bun run shared:check && bun run check:templates",
-    "build": "bun run --cwd templates/astro build && bun run --cwd templates/ripple-ts build && bun run --cwd templates/tanstack-start build"
+    "build": "bun run --cwd templates/astro build && bun run --cwd templates/ripple-ts build && bun run --cwd templates/ripple-ts-browser-extension build && bun run --cwd templates/tanstack-start build"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",

scripts/sync-shared.ts

@@ -23,6 +23,11 @@ const mappings = [
     source: "shared/agent/AGENTS.md",
     targets: ["templates/ripple-ts/AGENTS.md"],
   },
+  {
+    appendTextSources: ["shared/agent/ripple-ts.md", "shared/agent/ripple-ts-browser-extension.md"],
+    source: "shared/agent/AGENTS.md",
+    targets: ["templates/ripple-ts-browser-extension/AGENTS.md"],
+  },
   {
     source: "shared/editor/vscode/extensions.json",
     targets: [
@@ -34,6 +39,7 @@ const mappings = [
     source: "shared/editor/vscode/settings.json",
     targets: [
       "templates/astro/.vscode/settings.json",
+      "templates/ripple-ts-browser-extension/.vscode/settings.json",
       "templates/ripple-ts/.vscode/settings.json",
       "templates/tanstack-start/.vscode/settings.json",
     ],
@@ -58,6 +64,7 @@ const mappings = [
     source: "shared/tooling/oxfmt.ts",
     targets: [
       "templates/astro/tooling/oxfmt.ts",
+      "templates/ripple-ts-browser-extension/tooling/oxfmt.ts",
       "templates/ripple-ts/tooling/oxfmt.ts",
       "templates/tanstack-start/tooling/oxfmt.ts",
     ],

shared/agent/ripple-ts-browser-extension.md

@@ -0,0 +1,22 @@
+## Ripple browser extension contract
+
+- Before changing WXT configuration, entrypoints, storage, messaging, or browser
+  lifecycle behavior, read https://wxt.dev/llms.txt and the relevant linked
+  official browser-extension documentation.
+- Manifest V3 is the default. Treat the background service worker as ephemeral:
+  persist durable state in extension storage and keep message handlers safe
+  across worker restarts.
+- Keep permissions and host matches at the narrowest feature-required scope.
+  Do not add a fixed extension key, broad host permission, remote executable
+  code, or a main-world content script without a concrete requirement.
+- Content-script UI uses a Shadow Root with event isolation. Preserve explicit
+  mount and disposal behavior, use the WXT context lifecycle helpers, and avoid
+  `rem` units because the host page controls the root font size.
+- Keep cross-context communication behind the typed protocol in
+  `src/extension/`. Validate messages at runtime because webpage and extension
+  boundaries are not trustworthy TypeScript callers.
+- System Google Chrome no longer accepts command-line extension sideloading.
+  Do not download Playwright Chromium as a fallback. Use the repository Chrome
+  launcher, which loads the unpacked output through the official experimental
+  `Extensions.loadUnpacked` CDP command, and connect E2E automation through the
+  same endpoint.

shared/agent/ripple-ts.md

@@ -4,6 +4,9 @@
   language server and TSRX TypeScript plugin both require that peer range. Do
   not upgrade TypeScript until both packages declare support for the newer line
   and `bun run check && bun run build` pass.
+- Do not use ordinary JavaScript destructuring in `.tsrx` files. Reactive state
+  uses TSRX-specific destructuring syntax; learn the correct form from the
+  indexes below before inspecting or editing code.
 - Before inspecting or editing application or component code, read
   https://ripple-ts.com/llms.txt in full.
 - When changing TSRX syntax, compiler or language tooling, or behavior shared

templates/ripple-ts-browser-extension/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Check
+        run: bun run check
+
+      - name: Build and package extension
+        run: bun run zip

templates/ripple-ts-browser-extension/.gitignore

@@ -0,0 +1,9 @@
+node_modules
+.output
+.wxt
+.chrome-profile
+*.local
+.env*
+*.tgz
+*.tsbuildinfo
+test-results

templates/ripple-ts-browser-extension/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+	"recommendations": [
+		"Ripple-TS.ripple-ts-vscode-plugin",
+		"VoidZero.vite-plus-extension-pack"
+	]
+}

templates/ripple-ts-browser-extension/.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+	"npm.scriptRunner": "vp",
+	"editor.defaultFormatter": "oxc.oxc-vscode",
+	"[javascript]": {
+		"editor.defaultFormatter": "oxc.oxc-vscode"
+	},
+	"[javascriptreact]": {
+		"editor.defaultFormatter": "oxc.oxc-vscode"
+	},
+	"[typescript]": {
+		"editor.defaultFormatter": "oxc.oxc-vscode"
+	},
+	"[typescriptreact]": {
+		"editor.defaultFormatter": "oxc.oxc-vscode"
+	},
+	"oxc.fmt.configPath": "./vite.config.ts",
+	"editor.formatOnSave": true,
+	"editor.formatOnSaveMode": "file",
+	"editor.codeActionsOnSave": {
+		"source.fixAll.oxc": "explicit"
+	}
+}

templates/ripple-ts-browser-extension/AGENTS.md

@@ -0,0 +1,59 @@
+<!--VITE PLUS START-->
+
+# Using Vite+, the Unified Toolchain for the Web
+
+This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, and it invokes Vite through `vp dev` and `vp build`. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
+
+Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.dev/guide/.
+
+## Review Checklist
+
+- [ ] Run `vp install` after pulling remote changes and before getting started.
+- [ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
+- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
+- [ ] If setup, runtime, or package-manager behavior looks wrong, run `vp env doctor` and include its output when asking for help.
+
+After completing a meaningful development stage, if the project defines
+`deploy:temporary`, use it when an online preview would help verify or share the
+result. Return the deployment URL and the time-sensitive Cloudflare claim URL
+to the user.
+
+<!--VITE PLUS END-->
+
+## Ripple TS workspace contract
+
+- TypeScript is intentionally pinned to `^5.9.3` because the current Ripple
+  language server and TSRX TypeScript plugin both require that peer range. Do
+  not upgrade TypeScript until both packages declare support for the newer line
+  and `bun run check && bun run build` pass.
+- Do not use ordinary JavaScript destructuring in `.tsrx` files. Reactive state
+  uses TSRX-specific destructuring syntax; learn the correct form from the
+  indexes below before inspecting or editing code.
+- Before inspecting or editing application or component code, read
+  https://ripple-ts.com/llms.txt in full.
+- When changing TSRX syntax, compiler or language tooling, or behavior shared
+  across compiler targets, also read https://tsrx.dev/llms.txt. Ripple docs are
+  authoritative for the runtime; TSRX docs are authoritative for the language.
+
+## Ripple browser extension contract
+
+- Before changing WXT configuration, entrypoints, storage, messaging, or browser
+  lifecycle behavior, read https://wxt.dev/llms.txt and the relevant linked
+  official browser-extension documentation.
+- Manifest V3 is the default. Treat the background service worker as ephemeral:
+  persist durable state in extension storage and keep message handlers safe
+  across worker restarts.
+- Keep permissions and host matches at the narrowest feature-required scope.
+  Do not add a fixed extension key, broad host permission, remote executable
+  code, or a main-world content script without a concrete requirement.
+- Content-script UI uses a Shadow Root with event isolation. Preserve explicit
+  mount and disposal behavior, use the WXT context lifecycle helpers, and avoid
+  `rem` units because the host page controls the root font size.
+- Keep cross-context communication behind the typed protocol in
+  `src/extension/`. Validate messages at runtime because webpage and extension
+  boundaries are not trustworthy TypeScript callers.
+- System Google Chrome no longer accepts command-line extension sideloading.
+  Do not download Playwright Chromium as a fallback. Use the repository Chrome
+  launcher, which loads the unpacked output through the official experimental
+  `Extensions.loadUnpacked` CDP command, and connect E2E automation through the
+  same endpoint.

templates/ripple-ts-browser-extension/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md