# Arbitrary At-Mention Services

## Overview

Mention services allow users to configure external XRPC services that appear in the `@` mention autocomplete. When typing `@`, configured services show as tab-into-able options (like publications). Inside a service scope, search queries are proxied to the service's endpoint and results can be inserted as inline mentions.

## Lexicons

**Source**: `lexicons/src/mentionService.ts`
**Generated JSON**: `lexicons/parts/page/mention/service.json`, `lexicons/parts/page/mention/config.json`
**Build**: `lexicons/build.ts` (handles `parts.page.*` namespace output path separately from `pub.leaflet.*`)

### `parts.page.mention.service`

Record type (key: `tid`) declaring a mention service:

- `name` (string, required) — display name
- `description` (string, optional)
- `endpoint` (string, uri, required) — URL accepting `?search=<string>`, returns `{ results: [{uri, name, href?}] }`

### `parts.page.mention.config`

Singleton record (key: `literal:self`) storing a user's enabled services:

- `services` (array of at-uri strings) — AT URIs pointing to `parts.page.mention.service` records

## Database

**Migration**: `supabase/migrations/20260323000000_add_mention_services.sql`

Two tables, both storing all data in a `record` JSONB column:

- `mention_services` — PK: `uri`, indexed on `identity_did`
- `mention_service_configs` — PK: `uri`, unique on `identity_did`

## Appview Ingestion

**File**: `appview/index.ts`

Both `parts.page.mention.service` and `parts.page.mention.config` are in `filterCollections`. The `handleEvent` function validates minimally (checks `name`/`endpoint` exist for services, `services` array for configs) then upserts `{uri, identity_did, record}` into the respective table. Deletes remove by URI.

## RPC Endpoints

All registered in `app/api/rpc/[command]/route.ts`.

### `get_user_mention_services`

**File**: `app/api/rpc/[command]/get_user_mention_services.ts`

- Input: `{ did: string }`
- Reads `mention_service_configs.record` to get the services array, then fetches matching `mention_services` rows
- Returns `{ services: [{uri, name, description?, endpoint_url}] }` (extracted from JSONB)

### `proxy_mention_search`

**File**: `app/api/rpc/[command]/proxy_mention_search.ts`

- Input: `{ service_uri: string, search: string }`
- Looks up the service's `endpoint` from JSONB, appends `?search=` param
- 5-second timeout, max 50 results
- Returns `{ results: [{uri, name, href?}] }`

## Mention UI

**File**: `components/Mention.tsx`

### Types

```
Mention union includes:
  | { type: "service"; serviceUri; name; description? }     — listed in default scope, never inserted
  | { type: "service_result"; uri; name; href? }            — inserted into editor

MentionScope union includes:
  | { type: "service"; serviceUri; name }
```

### `useMentionSuggestions` hook

- **Default scope**: fetches actors + publications as before, also calls `get_user_mention_services` (cached in a ref so it doesn't re-fetch per keystroke). Services always appear in the list regardless of query.
- **Service scope**: calls `proxy_mention_search` with the search query, maps results to `service_result` mentions.

### `MentionAutocomplete` component

- Sort order: `did` → `publication` → `post` → `service` → `service_result`
- **Tab** on a `service` item enters service scope (same pattern as publication Tab-to-enter)
- **Enter** on a `service_result` selects and inserts it
- Placeholder shows `"Search {service.name}..."` when in service scope
- `ServiceEntry` component renders name + description + arrow scope button
- `ServiceSearchResult` component renders result name (like `PostResult`)
- `ScopeHeader` handles `service` scope with a back button showing "Results from {name}"

## Editor Integration

### ProseMirror Schema

**File**: `components/Blocks/TextBlock/schema.ts`

The `atMention` node now has an `href` attribute (`default: undefined`). `parseDOM` reads `data-href`, `toDOM` writes it. The `toDOM` also wraps `AtUri` parsing in a try/catch so non-AT URIs from services don't throw.

### Insertion

**File**: `app/[leaflet_id]/publish/BskyPostEditorProsemirror.tsx` — `addMentionToEditor()`

New case for `mention.type === "service_result"`: creates an `atMention` node with `{atURI: mention.uri, text: mention.name, href: mention.href}`.

### Draft Rendering

**File**: `components/Blocks/TextBlock/RenderYJSFragment.tsx`

Reads `href` from the YJS `atMention` element and passes it to `AtMentionLink`.

## Published Rendering

### Facet Schema

**File**: `lexicons/src/facet.ts`

The `atMention` facet feature now has an optional `href` property alongside `atURI`.

### Facet Serialization

**File**: `actions/publishToPublication.ts` (around line 922)

When converting `atMention` YJS nodes to facets during publish, includes `href` from the node attribute if present.

### URL Resolution

**File**: `src/utils/mentionUtils.ts` — `atUriToUrl()`

Before returning `#` for unknown collections, tries to parse the URI as an HTTP(S) URL and returns it directly if valid. Also handles the case where `AtUri` parsing throws (non-AT URIs from services).

### Link Component

**File**: `components/AtMentionLink.tsx`

Accepts optional `href` prop. If `atUriToUrl()` returns `#` (unresolvable AT URI), falls back to `href`. Wraps `AtUri` parsing in try/catch for non-AT URIs.

### Published Text Rendering

**File**: `app/lish/[did]/[publication]/[rkey]/Blocks/TextBlockCore.tsx`

Passes `isAtMention.href` from the facet to `AtMentionLink`.

## Open Items

- The `useMentionSuggestions` hook passes an empty string for `did` when calling `get_user_mention_services` — needs to be wired to the authenticated user's DID from auth context.
- No mention service implementations exist yet — the infrastructure is ready for external services to be built against the `?search=` query interface.