# The APC UX guide (non-normative)

How the reference software shows agents in a page, and why: the pet, the header, the pin badge, the states, motion, colour, phones and the pairing cards. Nothing here is checked by the [conformance suite](/docs/conformance) or required to interoperate: the words **MUST** and **SHOULD** do not bind in this guide, and an app that draws its agents another way is as conformant as one that follows it. [`@tineira/apc-web`](https://github.com/tineira/agent-pointed-context/tree/main/packages/web) is the reference implementation of every pattern below (`<apc-pets>`, `<apc-pet>`, `<apc-pin>`, `<apc-handoff>`, `enablePinning`), so most of this guide is what the package already does for an app that uses it. [Integrate](/docs/integrate) shows it wired into a page.

## What this guide is

Presentation moved out of [the spec](/docs/spec) so that the contract holds only what interoperability and security depend on. Some presentation rules stayed in the spec, with their force words, because something else relies on them. Whatever you draw, [the spec](/docs/spec#the-agent-in-the-page) binds you to these:

- **Marks carry `data-apc-mark` and `data-grant`.** A pet, a pin badge and the bar's mark are what the person drags (or taps, then a target) to point an agent, `enablePinning` finds them by those attributes, and the browser extension steps back from an APC app by them.
- **A state is shown only when the app's data says so.** Never guessed from timing, and `waiting` only from the wait signal ([states](#states)).
- **A logo says which agent is connected, never that it is verified.** No vendor's mascot is drawn ([logos](#logos)).
- **Revoke is in the agent bar, and the bar is never collapsed or hidden while it shows a Direct agent.**
- **On a phone the agents are in the page and a finger can pin and unpin.** Mobile is interoperability, not presentation: the conformance suite checks it ([phones](#phones), [Mobile](/docs/spec#mobile)).

The pairing rules that look like screen rules but are security rules (the code is shown only on the app owner's page, the dock names the app's host on a request, the consent names the hub's host, an unverified app's warning names the domain first and defaults to Deny, what an unverified app gives is marked untrusted) are in the spec too, in [the Dock profile](/docs/spec#the-dock-profile) and [the hub's trust model](/docs/spec#the-hubs-trust-model).

## The agent in the page

How an app shows each connected agent inside its page. An app may keep its own mark for agents; one that shows a pet is better off showing this one, the character the dock draws, so a person sees the same agent everywhere.

- **The pet.** One character for every agent: a soft blob with two eyes, with the agent's logo as a badge at its bottom right. It is APC's own, drawn in SVG; no vendor's character is drawn or animated, so the character is the same for every agent and only the logo says whose it is.
- **The header.** The pets sit in the app's header, next to the person's account, up to 3 of them, then one button: "+N" for the rest, or a list button when all show.
- **The popover.** That button opens a popover with every agent: what it is doing, where its pin is (a click goes there) and whether it read it. A pet whose pin is on another page wears a dot. The app's own links ("Manage agents") go at its foot.
- **A pet is only a mark.** A click, a tap or Enter on a pet is pinning's (it arms the agent), never the popover's, so the popover never covers the target the person is about to tap. That is why only the list button opens it.

From [orders-page.ts](https://github.com/tineira/agent-pointed-context/blob/main/apps/dock/src/docs/examples/orders-page.ts):

```ts
/**
 * The agent in the page: each agent a pet in the header, up to 3 and then "+N", the same character the dock draws.
 * A pet is a mark too: drag it onto a row to point the agent. Its state comes only from what the page knows: an
 * unread pin, a call presence just reported, a wait open (APC 0.11, from the wait events), a pairing waiting on the
 * person. Never a guess from timing.
 */
defineHeaderPets();
const pets = document.querySelector("apc-pets") as ApcPetsElement;
pets.scheme = "auto"; // follow the page's prefers-color-scheme; an app with a theme switch passes "light" or "dark"
const heard = new Map<string, number>(); // grant id -> when presence last reported a call
let openWaits: OpenWaits = NO_OPEN_WAITS; // the waits open now, from the wait events (APC 0.11)
let expiry: ReturnType<typeof setTimeout> | undefined;
events.addEventListener("message", (message) => {
  const data = JSON.parse(message.data as string) as { type: string; event?: { grant_id: string; kind?: string } };
  if (data.type !== "presence" || !data.event) return;
  if (data.event.kind === "wait") {
    openWaits = foldWaitEvent(openWaits, data.event);
    // A closed that never came runs out at the ceiling plus the margin: look again then.
    clearTimeout(expiry);
    const at = nextWaitExpiry(openWaits);
    if (at !== null) expiry = setTimeout(() => ((openWaits = dropExpiredWaits(openWaits)), showPets()), Math.max(0, at - Date.now()) + 50);
  } else heard.set(data.event.grant_id, Date.now());
  showPets();
  setTimeout(() => showPets(), 4000);
});
let petRows: AgentRow[] = [];
function showPets(rows: AgentRow[] = petRows): void {
  petRows = rows;
  pets.agents = rows.map((a) => ({
    id: a.id,
    name: a.name,
    badge: agentBadge({ clientName: a.client, key: a.id }),
    pin: a.pin ? { ...a.pin, here: true } : null,
    // An open wait_for_focus shows as `waiting` only from the wait events, and only on a Direct grant: a dock agent waits on the hub.
    state: petState({
      connected: a.client !== null,
      waiting: agentWaitOpen(openWaits, a.grants.map((id, i) => ({ id, path: a.paths[i] ?? a.paths[0]! }))),
      busy: Date.now() - (heard.get(a.id) ?? 0) < 4000,
      pin: a.pin && !a.pin.seen ? "unread" : "none",
      requests: a.waiting === "code" ? 1 : 0,
    }),
  }));
}
onRefresh.push(showPets);
```

`<apc-pets>` is a custom element in light DOM, so the app's fonts and theme apply, and it is framework-agnostic: set `agents`, listen for `apc-open`. A lone pet anywhere else is `createPet({ state, badge, label })` or `<apc-pet>`.

## Pin badges

Where an agent is pinned, the element wears the agent's logo, with × to unpin: `<apc-pin>`. It shows a dashed, breathing ring while the agent has not read the pin and a check once it has, with the agent's name as its tooltip. Where it goes is the app's: Pulse floats badges over their targets, Signals puts them inline.

From [ux-snippets.ts](https://github.com/tineira/agent-pointed-context/blob/main/apps/dock/src/docs/examples/ux-snippets.ts):

```ts
/** A pin badge on a row: the agent's logo, × to unpin. */
export function wearPin(row: HTMLElement, grantId: string, unpin: (grantId: string) => void): void {
  definePinBadge();
  const pin = document.createElement("apc-pin") as ApcPinElement;
  pin.agent = { id: grantId, name: "Claude", seen: false, badge: agentBadge({ clientName: "Claude", key: grantId }) };
  pin.addEventListener("apc-unpin", () => unpin(grantId));
  row.append(pin);
}
```

- **Several agents on one element each keep a badge**, side by side, so every × stays reachable. `pinStackIndex` gives each badge its place and `PIN_STACK_STEP` (30 px), or `PIN_STACK_STEP_TOUCH` (72 px) on touch, is the step.
- **On touch the × sits beside the mark, never over it**, so a tap on the mark never unpins.
- **The badge is a mark** (`data-apc-mark`, `data-grant`), so dragging it onto another target moves the pin with no code in the app. It dims while dragged, until the drop or Esc.
- **An armed mark** (the person tapped it, and now taps a target) wears `data-armed="true"` and `aria-pressed="true"`, on every mark of that agent: a pet, a badge and a bar mark. Style it with `[data-armed]`.

## States

A pet has 8 states. The app drives each one from data it has, and shows a state only when that data says so; **nothing is guessed from timing**. A pet that shows what the page cannot know is worse than one that shows nothing.

| State | What drives it in an app |
|---|---|
| `dragging` | the person is dragging this agent's mark, in this page |
| `pairing` | a pairing request of this agent waits on the person |
| `offline` | no agent client is connected on the grant, or the grant was revoked |
| `pinned` | the agent's pin is unread |
| `calling` | a call is in flight, or the page just heard one (presence) |
| `read` | the agent just read its pin (shown for 6 s, `READ_HOLD_MS`) |
| `waiting` | a `wait_for_focus` of this agent is open, as the page-readable wait signal says. Never inferred from how recently the agent called |
| `idle` | connected, and none of the above |

The first state that holds, top to bottom, is shown (`petState`). A field you leave out of `petState` stays at its default, so a pet never shows a wait your page cannot see. Pass `waiting` only once your page reads the wait events: `foldWaitEvent` and `waitOpen` turn them into "a wait is open now", and an `open` runs out at the app's ceiling plus `WAIT_EVENT_MARGIN_S` if its `closed` never comes ([wait events](/docs/spec#wait-events-since-011) hold the rule). A dock agent waits on the hub, not on the app, so a page never shows one as waiting; the dock shows its own agents' waits itself, from the hub's place for each.

`READ_HOLD_MS` exists because an app keeps a read pin until a new one comes: without a hold, the pet would stay on "read" for as long as the pin.

## Motion

One `requestAnimationFrame` loop per window drives every pet in it, with no render per frame. It stops while the page is hidden, and slows down (20 frames a second) once every pet has kept its state for 10 s. With `prefers-reduced-motion: reduce`, each pet is a still pose of its state: no hopping, orbiting, breathing or wobble. This is energy and accessibility guidance; the package does it for you.

## Colour and theming

The pet follows the page's colour scheme.

- On a light page, the light pet: a dark body with a white outline and eyes.
- On a dark page, the inverse pet: a near-white body (not pure white), a dark outline and eyes, and a shine tuned to the light body.
- The badge's white disc keeps a thin outline in the inverse pet, so it reads on both bodies. The orange ring, the "!" and the other state marks do not change.
- `scheme = "light" | "dark" | "auto"`: `auto` follows `prefers-color-scheme`; an app with its own theme switch passes its theme. An app with a strict palette tints the body and the line (`tint`, `{ body, line }` in hex, or `--apc-pet-body` and `--apc-pet-line`).
- **Size.** `--apc-pets-size` (36 px by default) sizes the pets, each of which stays a 44 px target; a lone pet takes `size` or `--apc-pet-size`.
- The popover, the badge and the cards take the app's colours from `--apc-chip`, `--apc-line`, `--apc-ink`, `--apc-muted` and `--apc-accent`.

### Logos

A badge is the brand's logo (`brandFor` the client's declared name), else the icon the client sent, else a neutral mark in a colour of the agent's own: `agentBadge({ clientName, icon, key })` does it. Brands only: never a vendor's mascot. A logo says which agent is connected, never that it is verified; the client's name is the client's own claim.

## Phones

The rule that matters is the spec's [Mobile](/docs/spec#mobile): the agents are in the page, never collapsed or hidden, and a finger can pin, unpin and Revoke. The rest is how the reference does it, and what to check in your own layout at `APC_MOBILE_VIEWPORT` (375 × 812):

- **The header.** Under `APC_MOBILE_MEDIA` the pets stay in the header, side by side with no overlap.
- **Targets.** Every tap target (a pet, the list button, ×, the popover's links) is at least 44 px. That is one implementation of "finger-sized".
- **The bar.** `<apc-agents>` stays in the page, uncollapsed, at the bottom of the viewport: reachable while the page scrolls, without covering the content a person is about to point at.
- **Tap to pin.** Tap the agent's mark, then the target. Say what to do while an agent is armed ("Tap what you want Claude to look at") and give a way to cancel. `createTapPin` is the same state machine without the note, for a page that draws its own.

From [ux-snippets.ts](https://github.com/tineira/agent-pointed-context/blob/main/apps/dock/src/docs/examples/ux-snippets.ts):

```ts
/** Pinning on a phone: tap the mark, then the target. Say what to do while an agent is armed, and give a way out. */
export function pinningWords(): () => void {
  return enablePinning({
    onPin: (grantId: string, target: FocusTarget) => void post(`/api/agents/${grantId}/pin`, { target }),
    strings: { tapPrompt: (name) => `Tap what you want ${name} to look at.`, cancel: "Cancel" },
  });
}
```

Check the page with touch emulation, as `scripts/mobile-e2e.mjs` does for Pulse and Signals, or give the suite's `page.mobile` adapter ([conformance](/docs/conformance#run-it-from-code)).

## Pairing and consent cards

What the person sees from the drop to the dock's yes. The mechanics (the nonce, the code, the hub call) are the spec's, in [the Dock profile](/docs/spec#the-dock-profile); this is how the reference apps present them.

### The consent card

The page shows the consent when the server answers `consent_required`: "Let your agent from the dock at *host* read *Orders*?" The host is the hub origin from the drag payload, which is the hub the app will call, so the person sees which dock is asking (the spec's [consent](/docs/spec#consent-in-the-app) says the consent should name it). Before the Allow it says only that the dock will ask for a code: "After Allow, your dock will ask for a code." The code is not shown yet. These are example words; the app's own are as good.

### The handoff card

After the Allow, the code is the one thing the person carries to another window, so the reference shows it in a card that takes the consent's place (`<apc-handoff>`):

- the code **large**, in a monospaced face, formatted `K7M-4P2` (`formatPairingCode`), with a **copy** button;
- the time left, as `m:ss`;
- **Cancel**, which takes the access back (the app's revoke);
- under the code, the sentence the spec's [pairing code](/docs/spec#the-pairing-code) asks for, in the reference's words: "Type it only in your own dock; never give it to anyone. Whoever types it gets this access." (`HandoffStrings.typeItOnlyInYourDock`; the rule is the spec's, only the words are the guide's);
- and "If your dock doesn't ask for this code, the agent wasn't yours: Cancel."

From [ux-snippets.ts](https://github.com/tineira/agent-pointed-context/blob/main/apps/dock/src/docs/examples/ux-snippets.ts):

```ts
/** The handoff card in the consent's place, from the Allow until the dock has the code. */
export function showHandoff(consentSlot: HTMLElement, hub: string, code: string, storedExpiry: string, grantId: string): void {
  defineHandoff();
  const card = document.createElement("apc-handoff") as ApcHandoffElement;
  card.host = new URL(hub).host;
  card.pairing = { code, expires_at: storedExpiry }; // the app's stored expiry, never a guess
  card.addEventListener("apc-cancel", () => void post("/api/cancel", { grant_id: grantId }));
  consentSlot.replaceChildren(card);
}
```

The card follows the **app's stored expiry**: the countdown stops at zero, the code goes, and it says the dock did not finish in time. It offers no "New code": a new code needs a new consent, so it asks the person to drop the agent again. Once the dock took the code and is connecting, it says so and hides the code (set `pairing` to `null`). A page that holds a code before it knows when it ends shows no countdown, never a guessed one.

### The dock's warning

An unverified app's request shows the dock's own warning, which an app's page cannot draw (the dock is the hub's page). The spec fixes what it says ([the warning](/docs/spec#the-warning)): the **domain first**, **Not verified**, what the app calls itself as its own word ("calls itself *Orders*"), the risk (your agent will read whatever this app tells it, which could lead it to move data out of your other apps), and **Deny** as the default button. Only placement and weight are layout, and they are the dock's choice.

### Notes when a drop cannot pair

A dock agent dropped on a page that offers Direct only is answered, never lost: the page says it connects agents directly, with its connect page. The protocol exports the reference sentence (`directOnlyNote(appName)`), and `couldNotCheckNote` for a page that could not read its own `apc.json` (it pairs nothing). Pass `directOnlyNote` and `couldNotCheckNote` in `PinningStrings` for your own words, or handle `onDockUnsupported` yourself.

## Presence feedback

The page lights up what the agent read. `flashTargets(event, initials)` marks each element a presence event named with `data-apc-presence` (`read`, dotted; `write`, solid) and the agent's initials, for four seconds, and ignores a wait event. The page's event stream carries the revoke too: both reference apps broadcast an event when a grant ends, so every tab and device drops the agent's mark without a reload. The waiting indicator comes from the wait events, never from `flashTargets`.

From [orders-page.ts](https://github.com/tineira/agent-pointed-context/blob/main/apps/dock/src/docs/examples/orders-page.ts):

```ts
/** The page's stream: an open page (what `then` and wait_for_focus look at), presence, and changes. flashTargets ignores a wait event (APC 0.11). */
const events = new EventSource("/api/events");
events.onmessage = (message) => {
  const data = JSON.parse(message.data as string) as { type: string; event?: Parameters<typeof flashTargets>[0] };
  if (data.type === "presence" && data.event) flashTargets(data.event, marks.get(data.event.grant_id) ?? "?");
  else void refresh();
};
/**
 * The heartbeat (Dock, APC 0.10): while the page is open it tells the server the person is here, at least every
 * T_idle / 2. A dock agent's grant sleeps T_idle after the last one, and wakes with the next. The server's answer
 * carries the T_idle it runs with (`idle_ms`), so the page follows it; until one arrives it assumes the recommended one.
 */
let idleMs = T_IDLE_RECOMMENDED_MS;
async function heartbeat(): Promise<void> {
  const answer = await post("/api/heartbeat").catch(() => null);
  if (typeof answer?.idle_ms === "number" && answer.idle_ms > 0) idleMs = answer.idle_ms;
  // Every quarter of T_idle: one beat that fails still leaves the next inside T_idle / 2.
  setTimeout(() => void heartbeat(), Math.max(1000, idleMs / 4));
}
void heartbeat();
```

## On any page: the extension's outline

With the APC browser extension the person can drop a dock agent on any web page. While they drag, the extension outlines what the drop would read: a block of text, a form's question or a whole form. What is inside the outline, with the person's selection, is what the agent gets, and only on the drop ([the spec](/docs/spec#the-browser-extension)). Once sent, the agent's mark stays pinned beside the paragraph with a pin badge like the one above.

## Words and localization

`@tineira/apc-web` draws words, and every one is a key an app can pass, so no fork is needed. Each component takes one `strings` object (`BarStrings`, `PetsStrings`, `PinStrings`, `DirectStrings`, `PinningStrings`, `HandoffStrings`); a key you leave out stays English. Names, counts and labels are functions, so no sentence is built from English fragments and the plural forms are yours; tooltips and `aria-label`s are strings too. [Integrate](/docs/integrate#localize-the-page) has the whole list and a Spanish example. The symbols (×, ⊘, ‹, !, ✓) and what the app passes in stay as they are. Localizing changes no protocol text, the tools or conformance.

## Accessibility

- **Marks announce their state.** An armed mark wears `aria-pressed="true"`, so a screen reader says the agent is selected; the popover's list button is a real button.
- **Focus.** A pet takes Enter to arm the agent (never to open the popover); the popover updates in place, so focus and a press inside it survive the app setting `agents` again on every presence event. The handoff card can move focus into itself when it appears (`autoFocus`), to the copy button or to Cancel once there is no code, as a dialog needs.
- **Contrast.** A tinted pet keeps its outline and eyes readable on the app's background: check `tint` on both schemes you ship.
- **Targets.** Finger-sized, 44 px, wherever the page may be touched.
- **Motion.** `prefers-reduced-motion: reduce` gives still poses ([motion](#motion)).

---

The APC standard is at 1.1.1, frozen and changing only by the versioning and compatibility policy (/docs/spec#versioning-and-compatibility). This page as HTML: /docs/ux. Text CC BY 4.0, code MIT. Source: https://github.com/tineira/agent-pointed-context/blob/main/apps/dock/src/docs/pages/ux.md
