Agent Pointed ContextYour dockGitHub

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 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 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 shows it wired into a page.

What this guide is#

Presentation moved out of the 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 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).
  • A logo says which agent is connected, never that it is verified. No vendor's mascot is drawn (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, 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 and the hub's 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.
orders-page.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.

ux-snippets.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.

StateWhat drives it in an app
draggingthe person is dragging this agent's mark, in this page
pairinga pairing request of this agent waits on the person
offlineno agent client is connected on the grant, or the grant was revoked
pinnedthe agent's pin is unread
callinga call is in flight, or the page just heard one (presence)
readthe agent just read its pin (shown for 6 s, READ_HOLD_MS)
waitinga wait_for_focus of this agent is open, as the page-readable wait signal says. Never inferred from how recently the agent called
idleconnected, 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 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: 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.
ux-snippets.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).

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; this is how the reference apps present them.

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 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 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."
ux-snippets.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): 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.

orders-page.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). 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-labels are strings too. Integrate 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).