docs: add rich text facets implementation plan

docs/plans/2025-12-17-rich-text-facets.md

···
+# Rich Text Facets Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add Bluesky rich text facet support to render clickable links in bug descriptions, steps, comments, and responses.
+
+**Architecture:** Two utility functions (`parseFacets` for detection, `renderFacetedText` for display), GraphQL query updates to fetch facet data, mutation updates to save parsed facets, and render call replacements.
+
+**Tech Stack:** Vanilla JavaScript, GraphQL, TextEncoder/TextDecoder APIs
+
+---
+
+### Task 1: Add CSS for facet links
+
+**Files:**
+- Modify: `bugs.html:~225` (after `.hidden` utility class)
+
+**Step 1: Add the facet link styles**
+
+Add after the `.hidden { display: none !important; }` rule:
+
+```css
+/* Facet links */
+.facet-link {
+  color: var(--accent);
+  text-decoration: underline;
+}
+
+.facet-link:hover {
+  color: var(--accent-hover);
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): add CSS for facet links"
+```
+
+---
+
+### Task 2: Add parseFacets utility function
+
+**Files:**
+- Modify: `bugs.html:~1179` (after the `esc()` function)
+
+**Step 1: Add the parseFacets function**
+
+Add after the `esc()` function closing brace:
+
+```javascript
+function parseFacets(text) {
+  if (!text) return { text, facets: null };
+
+  const urlRegex = /https?:\/\/[^\s<>"\]\)]+/gi;
+  const facets = [];
+
+  let match;
+  while ((match = urlRegex.exec(text)) !== null) {
+    const url = match[0];
+    const charStart = match.index;
+    const charEnd = charStart + url.length;
+
+    const byteStart = new TextEncoder().encode(text.slice(0, charStart)).length;
+    const byteEnd = new TextEncoder().encode(text.slice(0, charEnd)).length;
+
+    facets.push({
+      index: { byteStart, byteEnd },
+      features: [{ $type: "app.bsky.richtext.facet#link", uri: url }]
+    });
+  }
+
+  return {
+    text,
+    facets: facets.length > 0 ? facets : null
+  };
+}
+```
+
+**Step 2: Verify in browser console**
+
+Open bugs.html, open DevTools console, run:
+```javascript
+parseFacets("Check https://example.com for info")
+// Expected: { text: "Check https://example.com for info", facets: [{ index: { byteStart: 6, byteEnd: 25 }, features: [...] }] }
+```
+
+**Step 3: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): add parseFacets utility for URL detection"
+```
+
+---
+
+### Task 3: Add renderFacetedText utility function
+
+**Files:**
+- Modify: `bugs.html` (after `parseFacets` function)
+
+**Step 1: Add the renderFacetedText function**
+
+Add after the `parseFacets()` function:
+
+```javascript
+function renderFacetedText(text, facets) {
+  if (!text) return "";
+  if (!facets || facets.length === 0) return esc(text);
+
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const bytes = encoder.encode(text);
+
+  const sorted = [...facets].sort((a, b) => a.index.byteStart - b.index.byteStart);
+
+  let result = "";
+  let lastEnd = 0;
+
+  for (const facet of sorted) {
+    if (facet.index.byteStart > lastEnd) {
+      result += esc(decoder.decode(bytes.slice(lastEnd, facet.index.byteStart)));
+    }
+
+    const facetText = decoder.decode(bytes.slice(facet.index.byteStart, facet.index.byteEnd));
+    const link = facet.features.find(f => f.uri);
+
+    if (link) {
+      result += `<a href="${esc(link.uri)}" target="_blank" rel="noopener noreferrer" class="facet-link">${esc(facetText)}</a>`;
+    } else {
+      result += esc(facetText);
+    }
+
+    lastEnd = facet.index.byteEnd;
+  }
+
+  if (lastEnd < bytes.length) {
+    result += esc(decoder.decode(bytes.slice(lastEnd)));
+  }
+
+  return result;
+}
+```
+
+**Step 2: Verify in browser console**
+
+```javascript
+const parsed = parseFacets("Check https://example.com for info");
+renderFacetedText(parsed.text, parsed.facets);
+// Expected: 'Check <a href="https://example.com" target="_blank" rel="noopener noreferrer" class="facet-link">https://example.com</a> for info'
+```
+
+**Step 3: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): add renderFacetedText utility for displaying links"
+```
+
+---
+
+### Task 4: Update BUGS_QUERY to fetch facets
+
+**Files:**
+- Modify: `bugs.html:~1381` (BUGS_QUERY constant)
+
+**Step 1: Add facet fields to the query**
+
+In BUGS_QUERY, after `stepsToReproduce` field, add:
+
+```graphql
+descriptionFacets {
+  index { byteStart byteEnd }
+  features {
+    ... on AppBskyRichtextFacetLink { uri }
+  }
+}
+stepsToReproduceFacets {
+  index { byteStart byteEnd }
+  features {
+    ... on AppBskyRichtextFacetLink { uri }
+  }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): fetch description and steps facets in BUGS_QUERY"
+```
+
+---
+
+### Task 5: Update COMMENTS_QUERY to fetch facets
+
+**Files:**
+- Modify: `bugs.html:~1512` (COMMENTS_QUERY constant)
+
+**Step 1: Add facet fields to the query**
+
+In COMMENTS_QUERY, after `body` field, add:
+
+```graphql
+bodyFacets {
+  index { byteStart byteEnd }
+  features {
+    ... on AppBskyRichtextFacetLink { uri }
+  }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): fetch body facets in COMMENTS_QUERY"
+```
+
+---
+
+### Task 6: Update RESPONSES_QUERY to fetch facets
+
+**Files:**
+- Modify: `bugs.html:~1461` (RESPONSES_QUERY constant)
+
+**Step 1: Add facet fields to the query**
+
+In RESPONSES_QUERY, after `message` field, add:
+
+```graphql
+messageFacets {
+  index { byteStart byteEnd }
+  features {
+    ... on AppBskyRichtextFacetLink { uri }
+  }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): fetch message facets in RESPONSES_QUERY"
+```
+
+---
+
+### Task 7: Update bug overlay rendering to use facets
+
+**Files:**
+- Modify: `bugs.html:~1977` and `~2051` (renderOverlay and updateOverlayContent)
+
+**Step 1: Replace description rendering in renderOverlay**
+
+Find:
+```javascript
+<p>${esc(bug.description)}</p>
+```
+
+Replace with:
+```javascript
+<p>${renderFacetedText(bug.description, bug.descriptionFacets)}</p>
+```
+
+**Step 2: Replace stepsToReproduce rendering in renderOverlay**
+
+Find:
+```javascript
+<p>${esc(bug.stepsToReproduce)}</p>
+```
+
+Replace with:
+```javascript
+<p>${renderFacetedText(bug.stepsToReproduce, bug.stepsToReproduceFacets)}</p>
+```
+
+**Step 3: Repeat for updateOverlayContent function**
+
+Apply the same two replacements in `updateOverlayContent()` (~lines 2051 and 2056).
+
+**Step 4: Verify manually**
+
+Open a bug with a URL in description or steps. The URL should now be a clickable link.
+
+**Step 5: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): render faceted text in bug overlay"
+```
+
+---
+
+### Task 8: Update comment rendering to use facets
+
+**Files:**
+- Modify: `bugs.html:~2519` (renderComment function)
+
+**Step 1: Replace comment body rendering**
+
+Find:
+```javascript
+<p class="comment-body">${esc(comment.body)}</p>
+```
+
+Replace with:
+```javascript
+<p class="comment-body">${renderFacetedText(comment.body, comment.bodyFacets)}</p>
+```
+
+**Step 2: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): render faceted text in comments"
+```
+
+---
+
+### Task 9: Update response rendering to use facets
+
+**Files:**
+- Modify: `bugs.html` (renderResponse function - search for `r.message`)
+
+**Step 1: Find and replace response message rendering**
+
+Find where response message is rendered (search for `esc(r.message)` or similar) and replace with:
+```javascript
+renderFacetedText(r.message, r.messageFacets)
+```
+
+**Step 2: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): render faceted text in responses"
+```
+
+---
+
+### Task 10: Update handleSubmitBug to parse facets
+
+**Files:**
+- Modify: `bugs.html:~3206` (handleSubmitBug function)
+
+**Step 1: Parse description and steps before creating input**
+
+Before the mutation input is constructed, add:
+
+```javascript
+const descriptionParsed = parseFacets(description);
+const stepsParsed = parseFacets(steps);
+```
+
+**Step 2: Update the input object**
+
+Change the input object to use parsed values:
+
+```javascript
+description: descriptionParsed.text,
+descriptionFacets: descriptionParsed.facets,
+stepsToReproduce: stepsParsed.text,
+stepsToReproduceFacets: stepsParsed.facets,
+```
+
+**Step 3: Verify manually**
+
+Submit a new bug with a URL in description. After reload, the URL should be clickable.
+
+**Step 4: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): parse facets when submitting new bugs"
+```
+
+---
+
+### Task 11: Update handleUpdateBug to parse facets
+
+**Files:**
+- Modify: `bugs.html:~3465` (handleUpdateBug function)
+
+**Step 1: Parse description and steps**
+
+Add before mutation:
+
+```javascript
+const descriptionParsed = parseFacets(description);
+const stepsParsed = parseFacets(steps);
+```
+
+**Step 2: Update the input object**
+
+```javascript
+description: descriptionParsed.text,
+descriptionFacets: descriptionParsed.facets,
+stepsToReproduce: stepsParsed.text,
+stepsToReproduceFacets: stepsParsed.facets,
+```
+
+**Step 3: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): parse facets when updating bugs"
+```
+
+---
+
+### Task 12: Update handleSubmitComment to parse facets
+
+**Files:**
+- Modify: `bugs.html:~2730` (handleSubmitComment function)
+
+**Step 1: Parse body before creating input**
+
+Find where `body` is used in the input and add:
+
+```javascript
+const bodyParsed = parseFacets(body);
+```
+
+**Step 2: Update the input object**
+
+```javascript
+body: bodyParsed.text,
+bodyFacets: bodyParsed.facets,
+```
+
+**Step 3: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): parse facets when submitting comments"
+```
+
+---
+
+### Task 13: Update handleSaveEditComment to parse facets
+
+**Files:**
+- Modify: `bugs.html:~2696` (handleSaveEditComment function)
+
+**Step 1: Parse body before updating**
+
+Find where `newBody` is used and add:
+
+```javascript
+const bodyParsed = parseFacets(newBody);
+```
+
+**Step 2: Update the input object**
+
+```javascript
+body: bodyParsed.text,
+bodyFacets: bodyParsed.facets,
+```
+
+**Step 3: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): parse facets when editing comments"
+```
+
+---
+
+### Task 14: Update handleSubmitResponse to parse facets
+
+**Files:**
+- Modify: `bugs.html` (handleSubmitResponse function - search for it)
+
+**Step 1: Parse message before creating input**
+
+Find where the response message is used and add:
+
+```javascript
+const messageParsed = parseFacets(message);
+```
+
+**Step 2: Update the input object**
+
+```javascript
+message: messageParsed.text,
+messageFacets: messageParsed.facets,
+```
+
+**Step 3: Commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): parse facets when submitting responses"
+```
+
+---
+
+### Task 15: Final verification and cleanup commit
+
+**Step 1: Full manual test**
+
+1. Create a new bug with URL in description and steps
+2. Verify links are clickable
+3. Add a comment with a URL
+4. Verify comment link is clickable
+5. Add a response with a URL (if you have permissions)
+6. Verify response link is clickable
+7. Edit a bug/comment - verify links still work
+
+**Step 2: Final commit**
+
+```bash
+git add bugs.html
+git commit -m "feat(bugs): complete rich text facet support for links"
+```