Windsurf

Drop a Windsurf rule into your repo and Windsurf embeds the Patchrooms widget whenever it generates a UI artifact — every preview becomes a review room where reviewers comment in place and the feedback comes back structured.

Prerequisites

Windsurf with rules enabled (.windsurf/rules/ in your project).
For cloud reports: a project key (pr_…) from your Patchrooms dashboard. Local mode needs no account.

Install the rule

Create the rule file so Windsurf can pick it up:

Directoryyour-project/
- Directory.windsurf/
  - Directoryrules/
    patchrooms.md

Paste this into .windsurf/rules/patchrooms.md:

---
trigger: model_decision
description: Embed Patchrooms in generated HTML/React/preview artifacts so humans review them in place and feedback returns as agent-ready context.
---

# Patchrooms: make generated artifacts reviewable

When you generate a UI artifact (HTML page, React app, preview build) a human
will review, embed Patchrooms. The preview becomes a review room: reviewers
click any element to comment in place, and you get clean, structured feedback.
Apply when the artifact has a visual surface; skip backend-only code.

Add before `</body>`. The UMD build attaches `window.Patchrooms`.

```html
<script src="https://room.patchrooms.com/v1/patchrooms.js"></script>
<script>
  Patchrooms.init({
    mode: 'artifact-review',
    storage: 'local',                 // zero-friction: no account, no backend
    artifact: {
      id: 'my-app',                   // stable room key — reuse across regenerations
      title: 'Checkout flow',
      tool: 'windsurf',
      goal: 'What this artifact should do',
    },
  });
</script>
```

For React, put both `<script>` tags in `index.html` so `window.Patchrooms`
exists before app code runs.

- `storage: 'local'` runs with no account, no backend, no network calls; reports
  live in localStorage. The reviewer exports them ("Copy agent feedback" /
  Download `.md`) and pastes the Markdown back.
- If the user gives a `projectKey` (`pr_…`), pass it in `init()` and omit
  `storage` (cloud is default). `projectKey` is not a `data-*` attribute.
- Put `data-patchroom-id` on the key elements (primary buttons, header, nav,
  hero, form fields) so click-to-comment anchors survive regeneration.
- Never embed secrets, tokens, or PII. `pr_…` is public; a secret `pr_sk_…` key
  must never appear in client code.

Where it goes

The rule lives at .windsurf/rules/patchrooms.md in your project root. The trigger: model_decision frontmatter lets Windsurf decide to apply it when it’s generating a reviewable UI.

The install snippet Windsurf emits

By default Windsurf uses the local snippet above (no account). When you provide a project key, the cloud install is the per-project loader — the key lives in the URL and the server inlines your config, so the widget auto-initializes:

<script src="https://room.patchrooms.com/v1/patchrooms/pr_xxx.js"></script>

Programmatic alternative (when Windsurf should attach mode/artifact):

<script src="https://room.patchrooms.com/v1/patchrooms.js"></script>
<script>
  Patchrooms.init({ projectKey: 'pr_xxx', mode: 'artifact-review', artifact: { id: 'my-app', tool: 'windsurf' } });
</script>

Verify it works

Ask Windsurf to generate or edit a UI page, then open the preview.
Confirm the Patchrooms launcher appears docked to the viewport edge.
Click an element to comment. With a project key, the report should stream into your dashboard.

Your first feedback

Open the preview, click an anchored element, and leave a comment such as:

The nav collapses too early on tablet — keep the links inline down to 900px.

Attach a screenshot or element selection in the same thread. In local mode, hit Copy agent feedback / Download .md and paste the Markdown back into Windsurf to patch. In cloud mode, the report is already in your dashboard.

API the rule relies on

Real init options (packages/sdk-web/src/types.ts):

mode: 'default' | 'artifact-review'.
storage: 'cloud' | 'local' — local means no backend, no network.
artifact: { id, title?, tool?, source?, goal?, constraints?: string[], url?, meta? }. id is the stable room key.
Script data-* reads: data-project-key, data-mode, data-artifact-id, data-source, data-storage.

Troubleshooting

Symptom	Fix
Windsurf doesn’t embed the widget	Confirm the rule is at `.windsurf/rules/patchrooms.md` and ask explicitly for a reviewable UI.
No launcher in the preview	Check the `<script>` is in the rendered HTML. In React, both tags must be in `index.html`.
Console: `[Patchrooms] unknown project key`	The `pr_…` key in the loader URL is wrong — copy it from the dashboard.
Comments drift after regeneration	Use stable `data-patchroom-id` anchors and reuse the same ids.