feat: add richtext facets for mentions, links, and hashtags

- Add richtext.js library for Bluesky-compatible facet parsing
- Add grain-rich-text component for rendering faceted text
- Parse facets on comment and gallery creation with handle resolution
- Render facets in comments, gallery descriptions, and profile bios
- Style facets as bold white with router navigation for mentions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

docs/plans/2025-12-29-richtext-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-compatible rich text facets (mentions, links, hashtags) to comments, gallery descriptions, and profile descriptions.
+
+**Architecture:** Adapt `~/code/tools/richtext.js` for Bluesky facet types. Parse facets on save for comments/galleries, parse on render for profiles. Create `<grain-rich-text>` component for display.
+
+**Tech Stack:** Lit components, Bluesky `app.bsky.richtext.facet` format, TextEncoder for UTF-8 byte positions.
+
+---
+
+## Task 1: Create richtext.js Library
+
+**Files:**
+- Create: `src/lib/richtext.js`
+
+**Step 1: Create the richtext library with Bluesky facet parsing**
+
+```javascript
+// src/lib/richtext.js - Bluesky-compatible richtext parsing and rendering
+
+/**
+ * Parse text for Bluesky facets: mentions, links, hashtags.
+ * Returns { text, facets } with byte-indexed positions.
+ *
+ * @param {string} text - Plain text to parse
+ * @param {function} resolveHandle - Optional async function to resolve @handle to DID
+ * @returns {Promise<{ text: string, facets: Array }>}
+ */
+export async function parseTextToFacets(text, resolveHandle = null) {
+  if (!text) return { text: '', facets: [] };
+
+  const facets = [];
+  const encoder = new TextEncoder();
+
+  function getByteOffset(str, charIndex) {
+    return encoder.encode(str.slice(0, charIndex)).length;
+  }
+
+  // Track claimed positions to avoid overlaps
+  const claimedPositions = new Set();
+
+  function isRangeClaimed(start, end) {
+    for (let i = start; i < end; i++) {
+      if (claimedPositions.has(i)) return true;
+    }
+    return false;
+  }
+
+  function claimRange(start, end) {
+    for (let i = start; i < end; i++) {
+      claimedPositions.add(i);
+    }
+  }
+
+  // URLs first (highest priority)
+  const urlRegex = /https?:\/\/[^\s<>\[\]()]+/g;
+  let urlMatch;
+  while ((urlMatch = urlRegex.exec(text)) !== null) {
+    const start = urlMatch.index;
+    const end = start + urlMatch[0].length;
+
+    if (!isRangeClaimed(start, end)) {
+      claimRange(start, end);
+      facets.push({
+        index: {
+          byteStart: getByteOffset(text, start),
+          byteEnd: getByteOffset(text, end),
+        },
+        features: [{
+          $type: 'app.bsky.richtext.facet#link',
+          uri: urlMatch[0],
+        }],
+      });
+    }
+  }
+
+  // Mentions: @handle or @handle.domain.tld
+  const mentionRegex = /@([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)*[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?/g;
+  let mentionMatch;
+  while ((mentionMatch = mentionRegex.exec(text)) !== null) {
+    const start = mentionMatch.index;
+    const end = start + mentionMatch[0].length;
+    const handle = mentionMatch[0].slice(1); // Remove @
+
+    if (!isRangeClaimed(start, end)) {
+      // Try to resolve handle to DID
+      let did = null;
+      if (resolveHandle) {
+        try {
+          did = await resolveHandle(handle);
+        } catch (e) {
+          // Skip this mention if resolution fails
+          continue;
+        }
+      }
+
+      if (did) {
+        claimRange(start, end);
+        facets.push({
+          index: {
+            byteStart: getByteOffset(text, start),
+            byteEnd: getByteOffset(text, end),
+          },
+          features: [{
+            $type: 'app.bsky.richtext.facet#mention',
+            did,
+          }],
+        });
+      }
+    }
+  }
+
+  // Hashtags: #tag (alphanumeric, no leading numbers)
+  const hashtagRegex = /#([a-zA-Z][a-zA-Z0-9_]*)/g;
+  let hashtagMatch;
+  while ((hashtagMatch = hashtagRegex.exec(text)) !== null) {
+    const start = hashtagMatch.index;
+    const end = start + hashtagMatch[0].length;
+    const tag = hashtagMatch[1]; // Without #
+
+    if (!isRangeClaimed(start, end)) {
+      claimRange(start, end);
+      facets.push({
+        index: {
+          byteStart: getByteOffset(text, start),
+          byteEnd: getByteOffset(text, end),
+        },
+        features: [{
+          $type: 'app.bsky.richtext.facet#tag',
+          tag,
+        }],
+      });
+    }
+  }
+
+  // Sort by byte position
+  facets.sort((a, b) => a.index.byteStart - b.index.byteStart);
+
+  return { text, facets };
+}
+
+/**
+ * Synchronous parsing for client-side render (no DID resolution).
+ * Mentions display as-is without profile links.
+ */
+export function parseTextToFacetsSync(text) {
+  if (!text) return { text: '', facets: [] };
+
+  const facets = [];
+  const encoder = new TextEncoder();
+
+  function getByteOffset(str, charIndex) {
+    return encoder.encode(str.slice(0, charIndex)).length;
+  }
+
+  const claimedPositions = new Set();
+
+  function isRangeClaimed(start, end) {
+    for (let i = start; i < end; i++) {
+      if (claimedPositions.has(i)) return true;
+    }
+    return false;
+  }
+
+  function claimRange(start, end) {
+    for (let i = start; i < end; i++) {
+      claimedPositions.add(i);
+    }
+  }
+
+  // URLs
+  const urlRegex = /https?:\/\/[^\s<>\[\]()]+/g;
+  let urlMatch;
+  while ((urlMatch = urlRegex.exec(text)) !== null) {
+    const start = urlMatch.index;
+    const end = start + urlMatch[0].length;
+
+    if (!isRangeClaimed(start, end)) {
+      claimRange(start, end);
+      facets.push({
+        index: {
+          byteStart: getByteOffset(text, start),
+          byteEnd: getByteOffset(text, end),
+        },
+        features: [{
+          $type: 'app.bsky.richtext.facet#link',
+          uri: urlMatch[0],
+        }],
+      });
+    }
+  }
+
+  // Hashtags
+  const hashtagRegex = /#([a-zA-Z][a-zA-Z0-9_]*)/g;
+  let hashtagMatch;
+  while ((hashtagMatch = hashtagRegex.exec(text)) !== null) {
+    const start = hashtagMatch.index;
+    const end = start + hashtagMatch[0].length;
+    const tag = hashtagMatch[1];
+
+    if (!isRangeClaimed(start, end)) {
+      claimRange(start, end);
+      facets.push({
+        index: {
+          byteStart: getByteOffset(text, start),
+          byteEnd: getByteOffset(text, end),
+        },
+        features: [{
+          $type: 'app.bsky.richtext.facet#tag',
+          tag,
+        }],
+      });
+    }
+  }
+
+  facets.sort((a, b) => a.index.byteStart - b.index.byteStart);
+  return { text, facets };
+}
+
+/**
+ * Render text with facets as HTML.
+ *
+ * @param {string} text - The text content
+ * @param {Array} facets - Array of facet objects
+ * @param {Object} options - Rendering options
+ * @returns {string} HTML string
+ */
+export function renderFacetedText(text, facets, options = {}) {
+  if (!text) return '';
+
+  // If no facets, just escape and return
+  if (!facets || facets.length === 0) {
+    return escapeHtml(text);
+  }
+
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const bytes = encoder.encode(text);
+
+  // Sort facets by start position
+  const sortedFacets = [...facets].sort(
+    (a, b) => a.index.byteStart - b.index.byteStart
+  );
+
+  let result = '';
+  let lastEnd = 0;
+
+  for (const facet of sortedFacets) {
+    // Validate byte indices
+    if (facet.index.byteStart < 0 || facet.index.byteEnd > bytes.length) {
+      continue; // Skip invalid facets
+    }
+
+    // Add text before this facet
+    if (facet.index.byteStart > lastEnd) {
+      const beforeBytes = bytes.slice(lastEnd, facet.index.byteStart);
+      result += escapeHtml(decoder.decode(beforeBytes));
+    }
+
+    // Get the faceted text
+    const facetBytes = bytes.slice(facet.index.byteStart, facet.index.byteEnd);
+    const facetText = decoder.decode(facetBytes);
+
+    // Determine facet type and render
+    const feature = facet.features?.[0];
+    if (!feature) {
+      result += escapeHtml(facetText);
+      lastEnd = facet.index.byteEnd;
+      continue;
+    }
+
+    const type = feature.$type || feature.__typename || '';
+
+    if (type.includes('link')) {
+      const uri = feature.uri || '';
+      result += `<a href="${escapeHtml(uri)}" target="_blank" rel="noopener noreferrer" class="facet-link">${escapeHtml(facetText)}</a>`;
+    } else if (type.includes('mention')) {
+      // Extract handle from text (remove @)
+      const handle = facetText.startsWith('@') ? facetText.slice(1) : facetText;
+      result += `<a href="/profile/${escapeHtml(handle)}" class="facet-mention">${escapeHtml(facetText)}</a>`;
+    } else if (type.includes('tag')) {
+      // Hashtag - styled but not clickable for now
+      result += `<span class="facet-tag">${escapeHtml(facetText)}</span>`;
+    } else {
+      result += escapeHtml(facetText);
+    }
+
+    lastEnd = facet.index.byteEnd;
+  }
+
+  // Add remaining text
+  if (lastEnd < bytes.length) {
+    const remainingBytes = bytes.slice(lastEnd);
+    result += escapeHtml(decoder.decode(remainingBytes));
+  }
+
+  return result;
+}
+
+function escapeHtml(text) {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+```
+
+**Step 2: Verify file exists**
+
+Run: `ls -la src/lib/richtext.js`
+Expected: File exists with correct permissions
+
+**Step 3: Commit**
+
+```bash
+git add src/lib/richtext.js
+git commit -m "feat: add richtext library for Bluesky facets"
+```
+
+---
+
+## Task 2: Add Handle Resolution to grain-api
+
+**Files:**
+- Modify: `src/services/grain-api.js`
+
+**Step 1: Add resolveHandle method to GrainApiService**
+
+Add after the `getComments` method (around line 1095):
+
+```javascript
+  async resolveHandle(handle) {
+    const query = `
+      query ResolveHandle($handle: String!) {
+        socialGrainActorProfile(first: 1, where: { actorHandle: { eq: $handle } }) {
+          edges {
+            node { did }
+          }
+        }
+      }
+    `;
+
+    const response = await this.#execute(query, { handle });
+    const did = response.data?.socialGrainActorProfile?.edges?.[0]?.node?.did;
+
+    if (!did) {
+      throw new Error(`Handle not found: ${handle}`);
+    }
+
+    return did;
+  }
+```
+
+**Step 2: Verify syntax**
+
+Run: `node --check src/services/grain-api.js`
+Expected: No syntax errors
+
+**Step 3: Commit**
+
+```bash
+git add src/services/grain-api.js
+git commit -m "feat: add resolveHandle method for mention facets"
+```
+
+---
+
+## Task 3: Create grain-rich-text Component
+
+**Files:**
+- Create: `src/components/atoms/grain-rich-text.js`
+
+**Step 1: Create the component**
+
+```javascript
+// src/components/atoms/grain-rich-text.js
+import { LitElement, html, css } from 'lit';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { renderFacetedText, parseTextToFacetsSync } from '../../lib/richtext.js';
+
+export class GrainRichText extends LitElement {
+  static properties = {
+    text: { type: String },
+    facets: { type: Array },
+    parse: { type: Boolean }
+  };
+
+  static styles = css`
+    :host {
+      display: inline;
+    }
+    .facet-link {
+      color: var(--color-link, #0066cc);
+      text-decoration: none;
+    }
+    .facet-link:hover {
+      text-decoration: underline;
+    }
+    .facet-mention {
+      color: var(--color-link, #0066cc);
+      text-decoration: none;
+    }
+    .facet-mention:hover {
+      text-decoration: underline;
+    }
+    .facet-tag {
+      color: var(--color-link, #0066cc);
+    }
+  `;
+
+  constructor() {
+    super();
+    this.text = '';
+    this.facets = null;
+    this.parse = false;
+  }
+
+  render() {
+    if (!this.text) return '';
+
+    let facetsToUse = this.facets;
+
+    // If parse mode and no facets provided, parse on the fly
+    if (this.parse && (!this.facets || this.facets.length === 0)) {
+      const parsed = parseTextToFacetsSync(this.text);
+      facetsToUse = parsed.facets;
+    }
+
+    const htmlContent = renderFacetedText(this.text, facetsToUse || []);
+    return html`${unsafeHTML(htmlContent)}`;
+  }
+}
+
+customElements.define('grain-rich-text', GrainRichText);
+```
+
+**Step 2: Verify syntax**
+
+Run: `node --check src/components/atoms/grain-rich-text.js`
+Expected: No syntax errors
+
+**Step 3: Commit**
+
+```bash
+git add src/components/atoms/grain-rich-text.js
+git commit -m "feat: add grain-rich-text component for facet rendering"
+```
+
+---
+
+## Task 4: Integrate Facet Parsing into Comment Creation
+
+**Files:**
+- Modify: `src/services/mutations.js`
+
+**Step 1: Add import at top of file**
+
+```javascript
+import { parseTextToFacets } from '../lib/richtext.js';
+import { grainApi } from './grain-api.js';
+```
+
+**Step 2: Modify createComment method (around line 103)**
+
+Replace the existing `createComment` method:
+
+```javascript
+  async createComment(galleryUri, text, replyToUri = null, focusUri = null) {
+    const client = auth.getClient();
+
+    // Parse text for facets with handle resolution
+    const resolveHandle = async (handle) => grainApi.resolveHandle(handle);
+    const { facets } = await parseTextToFacets(text, resolveHandle);
+
+    const input = {
+      subject: galleryUri,
+      text,
+      createdAt: new Date().toISOString()
+    };
+
+    // Only include facets if we found any
+    if (facets && facets.length > 0) {
+      input.facets = facets;
+    }
+
+    if (replyToUri) {
+      input.replyTo = replyToUri;
+    }
+
+    if (focusUri) {
+      input.focus = focusUri;
+    }
+
+    const result = await client.mutate(`
+      mutation CreateComment($input: SocialGrainCommentInput!) {
+        createSocialGrainComment(input: $input) { uri }
+      }
+    `, { input });
+
+    return result.createSocialGrainComment.uri;
+  }
+```
+
+**Step 3: Verify syntax**
+
+Run: `node --check src/services/mutations.js`
+Expected: No syntax errors
+
+**Step 4: Commit**
+
+```bash
+git add src/services/mutations.js
+git commit -m "feat: parse facets when creating comments"
+```
+
+---
+
+## Task 5: Integrate Facet Parsing into Gallery Creation
+
+**Files:**
+- Modify: `src/components/pages/grain-create-gallery.js`
+
+**Step 1: Add import at top of file**
+
+```javascript
+import { parseTextToFacets } from '../../lib/richtext.js';
+import { grainApi } from '../../services/grain-api.js';
+```
+
+**Step 2: Modify the gallery creation in #handlePost (around line 219)**
+
+Find this code block:
+```javascript
+      // Create gallery record
+      const galleryResult = await client.mutate(CREATE_GALLERY_MUTATION, {
+        input: {
+          title: this._title.trim(),
+          ...(this._description.trim() && { description: this._description.trim() }),
+          createdAt: now
+        }
+      });
+```
+
+Replace with:
+```javascript
+      // Parse description for facets
+      let facets = null;
+      if (this._description.trim()) {
+        const resolveHandle = async (handle) => grainApi.resolveHandle(handle);
+        const parsed = await parseTextToFacets(this._description.trim(), resolveHandle);
+        if (parsed.facets.length > 0) {
+          facets = parsed.facets;
+        }
+      }
+
+      // Create gallery record
+      const galleryResult = await client.mutate(CREATE_GALLERY_MUTATION, {
+        input: {
+          title: this._title.trim(),
+          ...(this._description.trim() && { description: this._description.trim() }),
+          ...(facets && { facets }),
+          createdAt: now
+        }
+      });
+```
+
+**Step 3: Verify syntax**
+
+Run: `node --check src/components/pages/grain-create-gallery.js`
+Expected: No syntax errors
+
+**Step 4: Commit**
+
+```bash
+git add src/components/pages/grain-create-gallery.js
+git commit -m "feat: parse facets when creating galleries"
+```
+
+---
+
+## Task 6: Add Facets to GraphQL Queries
+
+**Files:**
+- Modify: `src/services/grain-api.js`
+
+**Step 1: Add facets to getGalleryDetail comment query (around line 636)**
+
+Find the comment query section in `getGalleryDetail`:
+```javascript
+              socialGrainCommentViaSubject(
+                first: 20
+                sortBy: [{ field: createdAt, direction: ASC }]
+              ) {
+                totalCount
+                edges {
+                  node {
+                    uri
+                    text
+                    createdAt
+```
+
+Add `facets` field after `text`:
+```javascript
+                    uri
+                    text
+                    facets
+                    createdAt
+```
+
+**Step 2: Add facets field to gallery description query**
+
+In the same `getGalleryDetail` query, find where gallery fields are queried:
+```javascript
+              uri
+              did
+              actorHandle
+              title
+              description
+              createdAt
+```
+
+Add `facets` after `description`:
+```javascript
+              uri
+              did
+              actorHandle
+              title
+              description
+              facets
+              createdAt
+```
+
+**Step 3: Update the comment transform (around line 700)**
+
+Find the comment mapping:
+```javascript
+    const comments = galleryNode.socialGrainCommentViaSubject?.edges?.map(edge => {
+      const node = edge.node;
+      const commentProfile = node.socialGrainActorProfileByDid;
+      const focusPhoto = node.focusResolved;
+      return {
+        uri: node.uri,
+        text: node.text,
+        createdAt: node.createdAt,
+```
+
+Add facets to the returned object:
+```javascript
+      return {
+        uri: node.uri,
+        text: node.text,
+        facets: node.facets || [],
+        createdAt: node.createdAt,
+```
+
+**Step 4: Update gallery return object (around line 717)**
+
+Find the return statement:
+```javascript
+    return {
+      uri: galleryNode.uri,
+      title: galleryNode.title,
+      description: galleryNode.description,
+```
+
+Add facets:
+```javascript
+    return {
+      uri: galleryNode.uri,
+      title: galleryNode.title,
+      description: galleryNode.description,
+      facets: galleryNode.facets || [],
+```
+
+**Step 5: Verify syntax**
+
+Run: `node --check src/services/grain-api.js`
+Expected: No syntax errors
+
+**Step 6: Commit**
+
+```bash
+git add src/services/grain-api.js
+git commit -m "feat: query facets for comments and gallery descriptions"
+```
+
+---
+
+## Task 7: Update grain-comment to Render Facets
+
+**Files:**
+- Modify: `src/components/molecules/grain-comment.js`
+
+**Step 1: Add import and facets property**
+
+Add at top of file:
+```javascript
+import '../atoms/grain-rich-text.js';
+```
+
+Add to static properties:
+```javascript
+  static properties = {
+    uri: { type: String },
+    handle: { type: String },
+    displayName: { type: String },
+    avatarUrl: { type: String },
+    text: { type: String },
+    facets: { type: Array },  // Add this line
+    createdAt: { type: String },
+```
+
+**Step 2: Initialize facets in constructor**
+
+Add after `this.text = '';`:
+```javascript
+    this.facets = [];
+```
+
+**Step 3: Update render method (around line 162)**
+
+Find:
+```javascript
+            <span class="text">${this.text}</span>
+```
+
+Replace with:
+```javascript
+            <span class="text"><grain-rich-text .text=${this.text} .facets=${this.facets}></grain-rich-text></span>
+```
+
+**Step 4: Verify syntax**
+
+Run: `node --check src/components/molecules/grain-comment.js`
+Expected: No syntax errors
+
+**Step 5: Commit**
+
+```bash
+git add src/components/molecules/grain-comment.js
+git commit -m "feat: render comment facets with grain-rich-text"
+```
+
+---
+
+## Task 8: Pass Facets to grain-comment in Comment Sheet
+
+**Files:**
+- Modify: `src/components/organisms/grain-comment-sheet.js`
+
+**Step 1: Find comment rendering and add facets**
+
+Find where `<grain-comment>` is used and add `.facets` property.
+
+Look for pattern like:
+```javascript
+<grain-comment
+  uri=${comment.uri}
+  handle=${comment.handle}
+  ...
+  text=${comment.text}
+```
+
+Add facets:
+```javascript
+  .facets=${comment.facets || []}
+```
+
+**Step 2: Verify syntax**
+
+Run: `node --check src/components/organisms/grain-comment-sheet.js`
+Expected: No syntax errors
+
+**Step 3: Commit**
+
+```bash
+git add src/components/organisms/grain-comment-sheet.js
+git commit -m "feat: pass facets to grain-comment in comment sheet"
+```
+
+---
+
+## Task 9: Update Gallery Detail to Render Description Facets
+
+**Files:**
+- Modify: `src/components/pages/grain-gallery-detail.js`
+
+**Step 1: Add import**
+
+Add at top:
+```javascript
+import '../atoms/grain-rich-text.js';
+```
+
+**Step 2: Update description rendering (around line 399)**
+
+Find:
+```javascript
+            ${this._gallery.description ? html`
+              <p class="description">${this._gallery.description}</p>
+            ` : ''}
+```
+
+Replace with:
+```javascript
+            ${this._gallery.description ? html`
+              <p class="description"><grain-rich-text .text=${this._gallery.description} .facets=${this._gallery.facets || []}></grain-rich-text></p>
+            ` : ''}
+```
+
+**Step 3: Verify syntax**
+
+Run: `node --check src/components/pages/grain-gallery-detail.js`
+Expected: No syntax errors
+
+**Step 4: Commit**
+
+```bash
+git add src/components/pages/grain-gallery-detail.js
+git commit -m "feat: render gallery description facets"
+```
+
+---
+
+## Task 10: Update Profile Header to Render Bio Facets
+
+**Files:**
+- Modify: `src/components/organisms/grain-profile-header.js`
+
+**Step 1: Add import**
+
+Add at top:
+```javascript
+import '../atoms/grain-rich-text.js';
+```
+
+**Step 2: Update bio rendering (around line 302)**
+
+Find:
+```javascript
+          ${description ? html`<div class="bio">${description}</div>` : ''}
+```
+
+Replace with:
+```javascript
+          ${description ? html`<div class="bio"><grain-rich-text .text=${description} parse></grain-rich-text></div>` : ''}
+```
+
+Note: Using `parse` attribute since profile lexicon doesn't store facets yet.
+
+**Step 3: Verify syntax**
+
+Run: `node --check src/components/organisms/grain-profile-header.js`
+Expected: No syntax errors
+
+**Step 4: Commit**
+
+```bash
+git add src/components/organisms/grain-profile-header.js
+git commit -m "feat: render profile bio with client-side facet parsing"
+```
+
+---
+
+## Task 11: Final Verification
+
+**Step 1: Check all files exist and have no syntax errors**
+
+Run:
+```bash
+node --check src/lib/richtext.js && \
+node --check src/components/atoms/grain-rich-text.js && \
+node --check src/services/mutations.js && \
+node --check src/services/grain-api.js && \
+node --check src/components/pages/grain-create-gallery.js && \
+node --check src/components/molecules/grain-comment.js && \
+node --check src/components/pages/grain-gallery-detail.js && \
+node --check src/components/organisms/grain-profile-header.js && \
+echo "All files OK"
+```
+
+Expected: "All files OK"
+
+**Step 2: Run the dev server and test manually**
+
+Run: `npm run dev`
+
+Test checklist:
+- [ ] Create a comment with a URL - verify it becomes clickable
+- [ ] Create a comment with @mention - verify it links to profile
+- [ ] Create a comment with #hashtag - verify it's styled
+- [ ] Create a gallery with description containing URL - verify rendering
+- [ ] View a profile with URLs in bio - verify they're clickable
+
+**Step 3: Final commit with all changes**
+
+```bash
+git add -A
+git status
+# If all looks good:
+git commit -m "feat: complete richtext facet support for comments, galleries, and profiles"
+```
+
+---
+
+## Summary
+
+| File | Change |
+|------|--------|
+| `src/lib/richtext.js` | New - Parsing and rendering library |
+| `src/components/atoms/grain-rich-text.js` | New - Display component |
+| `src/services/grain-api.js` | Add `resolveHandle`, query facets |
+| `src/services/mutations.js` | Parse facets on comment creation |
+| `src/components/pages/grain-create-gallery.js` | Parse facets on gallery creation |
+| `src/components/molecules/grain-comment.js` | Render facets |
+| `src/components/organisms/grain-comment-sheet.js` | Pass facets to comment |
+| `src/components/pages/grain-gallery-detail.js` | Render description facets |
+| `src/components/organisms/grain-profile-header.js` | Client-side facet parsing for bio |

src/components/atoms/grain-rich-text.js

···
+// src/components/atoms/grain-rich-text.js
+import { LitElement, html, css } from 'lit';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { renderFacetedText, parseTextToFacetsSync } from '../../lib/richtext.js';
+import { router } from '../../router.js';
+
+export class GrainRichText extends LitElement {
+  static properties = {
+    text: { type: String },
+    facets: { type: Array },
+    parse: { type: Boolean }
+  };
+
+  static styles = css`
+    :host {
+      display: inline;
+    }
+    .facet-link {
+      color: var(--color-text-primary, #fff);
+      font-weight: var(--font-weight-semibold, 600);
+      text-decoration: none;
+    }
+    .facet-link:hover {
+      text-decoration: underline;
+    }
+    .facet-mention {
+      color: var(--color-text-primary, #fff);
+      font-weight: var(--font-weight-semibold, 600);
+      text-decoration: none;
+    }
+    .facet-mention:hover {
+      text-decoration: underline;
+    }
+    .facet-tag {
+      color: var(--color-text-primary, #fff);
+      font-weight: var(--font-weight-semibold, 600);
+    }
+  `;
+
+  constructor() {
+    super();
+    this.text = '';
+    this.facets = null;
+    this.parse = false;
+  }
+
+  #handleClick = (e) => {
+    const link = e.target.closest('.facet-mention');
+    if (link) {
+      e.preventDefault();
+      const href = link.getAttribute('href');
+      if (href) {
+        router.push(href);
+      }
+    }
+  };
+
+  firstUpdated() {
+    this.renderRoot.addEventListener('click', this.#handleClick);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.renderRoot.removeEventListener('click', this.#handleClick);
+  }
+
+  render() {
+    if (!this.text) return '';
+
+    let facetsToUse = this.facets;
+
+    // If parse mode and no facets provided, parse on the fly
+    if (this.parse && (!this.facets || this.facets.length === 0)) {
+      const parsed = parseTextToFacetsSync(this.text);
+      facetsToUse = parsed.facets;
+    }
+
+    const htmlContent = renderFacetedText(this.text, facetsToUse || []);
+    return html`${unsafeHTML(htmlContent)}`;
+  }
+}
+
+customElements.define('grain-rich-text', GrainRichText);

src/components/molecules/grain-comment.js

···
 import { LitElement, html, css } from 'lit';
 import { router } from '../../router.js';
 import '../atoms/grain-avatar.js';
+import '../atoms/grain-rich-text.js';
 
 export class GrainComment extends LitElement {
   static properties = {
···
     displayName: { type: String },
     avatarUrl: { type: String },
     text: { type: String },
+    facets: { type: Array },
     createdAt: { type: String },
     isReply: { type: Boolean },
     isOwner: { type: Boolean },
···
     this.displayName = '';
     this.avatarUrl = '';
     this.text = '';
+    this.facets = [];
     this.createdAt = '';
     this.isReply = false;
     this.isOwner = false;
···
             <span class="handle" @click=${this.#handleProfileClick}>
               ${this.handle}
             </span>
-            <span class="text">${this.text}</span>
+            <span class="text"><grain-rich-text .text=${this.text} .facets=${this.facets}></grain-rich-text></span>
           </div>
           <div class="meta">
             <span class="time">${this.#formatTime(this.createdAt)}</span>

src/components/organisms/grain-comment-sheet.js

···
                   displayName=${comment.displayName}
                   avatarUrl=${comment.avatarUrl}
                   text=${comment.text}
+                  .facets=${comment.facets || []}
                   createdAt=${comment.createdAt}
                   ?is-reply=${comment.isReply}
                   ?isOwner=${comment.handle === auth.user?.handle}

src/components/organisms/grain-profile-header.js

···
 import '../atoms/grain-icon.js';
 import '../atoms/grain-spinner.js';
 import '../atoms/grain-toast.js';
+import '../atoms/grain-rich-text.js';
 import '../molecules/grain-profile-stats.js';
 
 export class GrainProfileHeader extends LitElement {
···
             followerCount=${followerCount || 0}
             followingCount=${followingCount || 0}
           ></grain-profile-stats>
-          ${description ? html`<div class="bio">${description}</div>` : ''}
+          ${description ? html`<div class="bio"><grain-rich-text .text=${description} parse></grain-rich-text></div>` : ''}
         </div>
       </div>
 

src/components/pages/grain-create-gallery.js

···
 import { router } from '../../router.js';
 import { auth } from '../../services/auth.js';
 import { draftGallery } from '../../services/draft-gallery.js';
+import { parseTextToFacets } from '../../lib/richtext.js';
+import { grainApi } from '../../services/grain-api.js';
 import '../atoms/grain-icon.js';
 import '../atoms/grain-button.js';
 import '../atoms/grain-input.js';
···
         photoUris.push(photoResult.createSocialGrainPhoto.uri);
       }
 
+      // Parse description for facets
+      let facets = null;
+      if (this._description.trim()) {
+        const resolveHandle = async (handle) => grainApi.resolveHandle(handle);
+        const parsed = await parseTextToFacets(this._description.trim(), resolveHandle);
+        if (parsed.facets.length > 0) {
+          facets = parsed.facets;
+        }
+      }
+
       // Create gallery record
       const galleryResult = await client.mutate(CREATE_GALLERY_MUTATION, {
         input: {
           title: this._title.trim(),
           ...(this._description.trim() && { description: this._description.trim() }),
+          ...(facets && { facets }),
           createdAt: now
         }
       });

src/components/pages/grain-gallery-detail.js

···
 import '../organisms/grain-comment-sheet.js';
 import '../atoms/grain-spinner.js';
 import '../atoms/grain-icon.js';
+import '../atoms/grain-rich-text.js';
 import '../organisms/grain-action-dialog.js';
 
 const DELETE_GALLERY_MUTATION = `
···
           <div class="content">
             <p class="title">${this._gallery.title}</p>
             ${this._gallery.description ? html`
-              <p class="description">${this._gallery.description}</p>
+              <p class="description"><grain-rich-text .text=${this._gallery.description} .facets=${this._gallery.facets || []}></grain-rich-text></p>
             ` : ''}
             <time class="timestamp">${this.#formatDate(this._gallery.createdAt)}</time>
           </div>

src/lib/richtext.js

···
+// src/lib/richtext.js - Bluesky-compatible richtext parsing and rendering
+
+/**
+ * Parse text for Bluesky facets: mentions, links, hashtags.
+ * Returns { text, facets } with byte-indexed positions.
+ *
+ * @param {string} text - Plain text to parse
+ * @param {function} resolveHandle - Optional async function to resolve @handle to DID
+ * @returns {Promise<{ text: string, facets: Array }>}
+ */
+export async function parseTextToFacets(text, resolveHandle = null) {
+  if (!text) return { text: '', facets: [] };
+
+  const facets = [];
+  const encoder = new TextEncoder();
+
+  function getByteOffset(str, charIndex) {
+    return encoder.encode(str.slice(0, charIndex)).length;
+  }
+
+  // Track claimed positions to avoid overlaps
+  const claimedPositions = new Set();
+
+  function isRangeClaimed(start, end) {
+    for (let i = start; i < end; i++) {
+      if (claimedPositions.has(i)) return true;
+    }
+    return false;
+  }
+
+  function claimRange(start, end) {
+    for (let i = start; i < end; i++) {
+      claimedPositions.add(i);
+    }
+  }
+
+  // URLs first (highest priority)
+  const urlRegex = /https?:\/\/[^\s<>\[\]()]+/g;
+  let urlMatch;
+  while ((urlMatch = urlRegex.exec(text)) !== null) {
+    const start = urlMatch.index;
+    const end = start + urlMatch[0].length;
+
+    if (!isRangeClaimed(start, end)) {
+      claimRange(start, end);
+      facets.push({
+        index: {
+          byteStart: getByteOffset(text, start),
+          byteEnd: getByteOffset(text, end),
+        },
+        features: [{
+          $type: 'app.bsky.richtext.facet#link',
+          uri: urlMatch[0],
+        }],
+      });
+    }
+  }
+
+  // Mentions: @handle or @handle.domain.tld
+  const mentionRegex = /@([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)*[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?/g;
+  let mentionMatch;
+  while ((mentionMatch = mentionRegex.exec(text)) !== null) {
+    const start = mentionMatch.index;
+    const end = start + mentionMatch[0].length;
+    const handle = mentionMatch[0].slice(1); // Remove @
+
+    if (!isRangeClaimed(start, end)) {
+      // Try to resolve handle to DID
+      let did = null;
+      if (resolveHandle) {
+        try {
+          did = await resolveHandle(handle);
+        } catch (e) {
+          // Handle not found - skip this mention
+          continue;
+        }
+      }
+
+      if (did) {
+        claimRange(start, end);
+        facets.push({
+          index: {
+            byteStart: getByteOffset(text, start),
+            byteEnd: getByteOffset(text, end),
+          },
+          features: [{
+            $type: 'app.bsky.richtext.facet#mention',
+            did,
+          }],
+        });
+      }
+    }
+  }
+
+  // Hashtags: #tag (alphanumeric, no leading numbers)
+  const hashtagRegex = /#([a-zA-Z][a-zA-Z0-9_]*)/g;
+  let hashtagMatch;
+  while ((hashtagMatch = hashtagRegex.exec(text)) !== null) {
+    const start = hashtagMatch.index;
+    const end = start + hashtagMatch[0].length;
+    const tag = hashtagMatch[1]; // Without #
+
+    if (!isRangeClaimed(start, end)) {
+      claimRange(start, end);
+      facets.push({
+        index: {
+          byteStart: getByteOffset(text, start),
+          byteEnd: getByteOffset(text, end),
+        },
+        features: [{
+          $type: 'app.bsky.richtext.facet#tag',
+          tag,
+        }],
+      });
+    }
+  }
+
+  // Sort by byte position
+  facets.sort((a, b) => a.index.byteStart - b.index.byteStart);
+
+  return { text, facets };
+}
+
+/**
+ * Synchronous parsing for client-side render (no DID resolution).
+ * Mentions display as-is without profile links.
+ */
+export function parseTextToFacetsSync(text) {
+  if (!text) return { text: '', facets: [] };
+
+  const facets = [];
+  const encoder = new TextEncoder();
+
+  function getByteOffset(str, charIndex) {
+    return encoder.encode(str.slice(0, charIndex)).length;
+  }
+
+  const claimedPositions = new Set();
+
+  function isRangeClaimed(start, end) {
+    for (let i = start; i < end; i++) {
+      if (claimedPositions.has(i)) return true;
+    }
+    return false;
+  }
+
+  function claimRange(start, end) {
+    for (let i = start; i < end; i++) {
+      claimedPositions.add(i);
+    }
+  }
+
+  // URLs
+  const urlRegex = /https?:\/\/[^\s<>\[\]()]+/g;
+  let urlMatch;
+  while ((urlMatch = urlRegex.exec(text)) !== null) {
+    const start = urlMatch.index;
+    const end = start + urlMatch[0].length;
+
+    if (!isRangeClaimed(start, end)) {
+      claimRange(start, end);
+      facets.push({
+        index: {
+          byteStart: getByteOffset(text, start),
+          byteEnd: getByteOffset(text, end),
+        },
+        features: [{
+          $type: 'app.bsky.richtext.facet#link',
+          uri: urlMatch[0],
+        }],
+      });
+    }
+  }
+
+  // Mentions: @handle or @handle.domain.tld (no DID resolution in sync mode)
+  const mentionRegex = /@([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)*[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?/g;
+  let mentionMatch;
+  while ((mentionMatch = mentionRegex.exec(text)) !== null) {
+    const start = mentionMatch.index;
+    const end = start + mentionMatch[0].length;
+
+    if (!isRangeClaimed(start, end)) {
+      claimRange(start, end);
+      facets.push({
+        index: {
+          byteStart: getByteOffset(text, start),
+          byteEnd: getByteOffset(text, end),
+        },
+        features: [{
+          $type: 'app.bsky.richtext.facet#mention',
+          did: null, // No DID in sync mode
+        }],
+      });
+    }
+  }
+
+  // Hashtags
+  const hashtagRegex = /#([a-zA-Z][a-zA-Z0-9_]*)/g;
+  let hashtagMatch;
+  while ((hashtagMatch = hashtagRegex.exec(text)) !== null) {
+    const start = hashtagMatch.index;
+    const end = start + hashtagMatch[0].length;
+    const tag = hashtagMatch[1];
+
+    if (!isRangeClaimed(start, end)) {
+      claimRange(start, end);
+      facets.push({
+        index: {
+          byteStart: getByteOffset(text, start),
+          byteEnd: getByteOffset(text, end),
+        },
+        features: [{
+          $type: 'app.bsky.richtext.facet#tag',
+          tag,
+        }],
+      });
+    }
+  }
+
+  facets.sort((a, b) => a.index.byteStart - b.index.byteStart);
+  return { text, facets };
+}
+
+/**
+ * Render text with facets as HTML.
+ *
+ * @param {string} text - The text content
+ * @param {Array} facets - Array of facet objects
+ * @param {Object} options - Rendering options
+ * @returns {string} HTML string
+ */
+export function renderFacetedText(text, facets, options = {}) {
+  if (!text) return '';
+
+  // If no facets, just escape and return
+  if (!facets || facets.length === 0) {
+    return escapeHtml(text);
+  }
+
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const bytes = encoder.encode(text);
+
+  // Sort facets by start position
+  const sortedFacets = [...facets].sort(
+    (a, b) => a.index.byteStart - b.index.byteStart
+  );
+
+  let result = '';
+  let lastEnd = 0;
+
+  for (const facet of sortedFacets) {
+    // Validate byte indices
+    if (facet.index.byteStart < 0 || facet.index.byteEnd > bytes.length) {
+      continue; // Skip invalid facets
+    }
+
+    // Add text before this facet
+    if (facet.index.byteStart > lastEnd) {
+      const beforeBytes = bytes.slice(lastEnd, facet.index.byteStart);
+      result += escapeHtml(decoder.decode(beforeBytes));
+    }
+
+    // Get the faceted text
+    const facetBytes = bytes.slice(facet.index.byteStart, facet.index.byteEnd);
+    const facetText = decoder.decode(facetBytes);
+
+    // Determine facet type and render
+    const feature = facet.features?.[0];
+    if (!feature) {
+      result += escapeHtml(facetText);
+      lastEnd = facet.index.byteEnd;
+      continue;
+    }
+
+    const type = feature.$type || feature.__typename || '';
+
+    if (type.includes('link')) {
+      const uri = feature.uri || '';
+      result += `<a href="${escapeHtml(uri)}" target="_blank" rel="noopener noreferrer" class="facet-link">${escapeHtml(facetText)}</a>`;
+    } else if (type.includes('mention')) {
+      // Extract handle from text (remove @)
+      const handle = facetText.startsWith('@') ? facetText.slice(1) : facetText;
+      result += `<a href="/profile/${escapeHtml(handle)}" class="facet-mention">${escapeHtml(facetText)}</a>`;
+    } else if (type.includes('tag')) {
+      // Hashtag - styled but not clickable for now
+      result += `<span class="facet-tag">${escapeHtml(facetText)}</span>`;
+    } else {
+      result += escapeHtml(facetText);
+    }
+
+    lastEnd = facet.index.byteEnd;
+  }
+
+  // Add remaining text
+  if (lastEnd < bytes.length) {
+    const remainingBytes = bytes.slice(lastEnd);
+    result += escapeHtml(decoder.decode(remainingBytes));
+  }
+
+  return result;
+}
+
+function escapeHtml(text) {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}

src/services/grain-api.js

···
               actorHandle
               title
               description
+              facets
               createdAt
               socialGrainActorProfileByDid {
                 displayName
···
                   node {
                     uri
                     text
+                    facets
                     createdAt
                     actorHandle
                     replyTo
···
       return {
         uri: node.uri,
         text: node.text,
+        facets: node.facets || [],
         createdAt: node.createdAt,
         handle: node.actorHandle,
         displayName: commentProfile?.displayName || '',
···
       uri: galleryNode.uri,
       title: galleryNode.title,
       description: galleryNode.description,
+      facets: galleryNode.facets || [],
       createdAt: galleryNode.createdAt,
       handle: galleryNode.actorHandle,
       displayName: profile?.displayName || '',
···
             node {
               uri
               text
+              facets
               createdAt
               actorHandle
               replyTo
···
       return {
         uri: node.uri,
         text: node.text,
+        facets: node.facets || [],
         createdAt: node.createdAt,
         handle: node.actorHandle,
         displayName: profile?.displayName || '',
···
       pageInfo: connection.pageInfo || { hasNextPage: false, endCursor: null },
       totalCount: connection.totalCount || 0
     };
+  }
+
+  async resolveHandle(handle) {
+    const query = `
+      query ResolveHandle($handle: String!) {
+        socialGrainActorProfile(first: 1, where: { actorHandle: { eq: $handle } }) {
+          edges {
+            node { did }
+          }
+        }
+      }
+    `;
+
+    const response = await this.#execute(query, { handle });
+    const did = response.data?.socialGrainActorProfile?.edges?.[0]?.node?.did;
+
+    if (!did) {
+      throw new Error(`Handle not found: ${handle}`);
+    }
+
+    return did;
   }
 }
 

src/services/mutations.js

···
 import { auth } from './auth.js';
 import { recordCache } from './record-cache.js';
+import { parseTextToFacets } from '../lib/richtext.js';
+import { grainApi } from './grain-api.js';
 
 class MutationsService {
   async createFavorite(galleryUri) {
···
 
   async createComment(galleryUri, text, replyToUri = null, focusUri = null) {
     const client = auth.getClient();
+
+    // Parse text for facets with handle resolution
+    const resolveHandle = async (handle) => grainApi.resolveHandle(handle);
+    const { facets } = await parseTextToFacets(text, resolveHandle);
+
     const input = {
       subject: galleryUri,
       text,
       createdAt: new Date().toISOString()
     };
+
+    // Only include facets if we found any
+    if (facets && facets.length > 0) {
+      input.facets = facets;
+    }
 
     if (replyToUri) {
       input.replyTo = replyToUri;