@tineira/apc-web 0.0.0-stage → 0.7.1

package/dist/direct-agents.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The Direct profile's page part (APC 0.4, TIN-578): the list where the person makes and names the
+ * agents that connect to this app directly, each with its own MCP URL, and the connect instructions
+ * (the URL, and a prompt to paste to the agent). Revoke is the agent bar's (core). The server side is
+ * in @tineira/apc-server (direct.ts).
+ *
+ * A custom element in light DOM, like `<apc-agents>`: the app's fonts apply, styles are injected once,
+ * scoped by class prefix and themed through --apc-* custom properties. Set `agents` and `appName`;
+ * listen for `apc-add` (make an agent) and `apc-rename` (detail { id, name }).
+ */
+export interface DirectAgent {
+    /** The app's id for the agent's grant. */
+    id: string;
+    name: string;
+    /** Its MCP URL: the secret in it is the grant. */
+    url: string;
+    /** It has connected (sent initialize). */
+    connected: boolean;
+    /** The MCP client it connected with, e.g. "claude-code". */
+    client?: string | null;
+    /** It is also reached through a dock, shown as one agent (apc_link). */
+    linked?: boolean;
+}
+export type DirectAgentsEvent = "apc-add" | "apc-rename";
+/**
+ * What a person pastes to their own agent to connect it. Many agents can add a server themselves when
+ * asked in the chat, so it asks for that first, under a name the person will recognise, and for the
+ * steps only if the agent cannot.
+ */
+export declare function connectPrompt(url: string, appName: string): string;
+/** The words of one agent's line. Pure, so it is tested. */
+export declare function directAgentStatus(a: DirectAgent): string;
+/** Defines `<apc-direct-agents>` where custom elements exist (a browser), so importing this module in Node is safe. */
+export declare function defineDirectAgents(tag?: string): void;
+/** The element's type, for apps that hold a reference to it. */
+export interface ApcDirectAgentsElement extends HTMLElement {
+    agents: DirectAgent[];
+    appName: string;
+}

package/dist/direct-agents.js

@@ -0,0 +1,205 @@
+/**
+ * The Direct profile's page part (APC 0.4, TIN-578): the list where the person makes and names the
+ * agents that connect to this app directly, each with its own MCP URL, and the connect instructions
+ * (the URL, and a prompt to paste to the agent). Revoke is the agent bar's (core). The server side is
+ * in @tineira/apc-server (direct.ts).
+ *
+ * A custom element in light DOM, like `<apc-agents>`: the app's fonts apply, styles are injected once,
+ * scoped by class prefix and themed through --apc-* custom properties. Set `agents` and `appName`;
+ * listen for `apc-add` (make an agent) and `apc-rename` (detail { id, name }).
+ */
+/**
+ * What a person pastes to their own agent to connect it. Many agents can add a server themselves when
+ * asked in the chat, so it asks for that first, under a name the person will recognise, and for the
+ * steps only if the agent cannot.
+ */
+export function connectPrompt(url, appName) {
+    return `Please connect this remote MCP server, named "${appName}". URL: ${url}. It uses Streamable HTTP and needs no OAuth or API key: the access is in the URL. If you can add it yourself, do it now and tell me when it's connected. If you can't, tell me the exact steps to add it in the app I'm using you in right now. Do not open the URL in a browser.`;
+}
+/** The words of one agent's line. Pure, so it is tested. */
+export function directAgentStatus(a) {
+    if (!a.connected)
+        return "not connected yet";
+    const as = a.client ? `connected as ${a.client}` : "connected";
+    return a.linked ? `${as}, also through your dock` : as;
+}
+const STYLE_ID = "apc-direct-style";
+const CSS = `
+apc-direct-agents { display: flex; flex-direction: column; gap: 10px; color: var(--apc-ink, inherit); }
+.apc-direct__agent { display: flex; flex-direction: column; gap: 8px; padding: 10px 12px; border: 1px solid var(--apc-line, #d6dce5); border-radius: 10px; }
+.apc-direct__head { display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 8px; }
+.apc-direct__name { font-weight: 600; }
+.apc-direct__status { color: var(--apc-muted, #5b6575); font-size: 0.9em; }
+.apc-direct__link { border: 0; background: none; padding: 0; font: inherit; font-size: 0.9em; color: var(--apc-accent, #b85209); cursor: pointer; }
+.apc-direct__link:hover { text-decoration: underline; }
+.apc-direct__body { display: flex; flex-direction: column; gap: 6px; }
+.apc-direct__hint { margin: 0; color: var(--apc-muted, #5b6575); font-size: 0.85em; }
+.apc-direct__copy { display: flex; min-width: 0; align-items: stretch; border: 1px solid var(--apc-line, #d6dce5); border-radius: 8px; overflow: hidden; }
+.apc-direct__copy code { flex: 1; min-width: 0; padding: 6px 8px; font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; white-space: pre-wrap; overflow-wrap: anywhere; }
+.apc-direct__copy button { flex: none; border: 0; border-left: 1px solid var(--apc-line, #d6dce5); background: none; padding: 0 10px; font: inherit; font-size: 0.85em; font-weight: 600; color: var(--apc-accent, #b85209); cursor: pointer; }
+.apc-direct__rename { display: flex; flex-wrap: wrap; gap: 6px; }
+.apc-direct__rename input { flex: 1; min-width: 8em; padding: 4px 8px; border: 1px solid var(--apc-line, #d6dce5); border-radius: 6px; background: transparent; color: inherit; font: inherit; }
+.apc-direct__rename button, .apc-direct__add { padding: 5px 12px; border: 1px solid var(--apc-line, #d6dce5); border-radius: 8px; background: var(--apc-chip, transparent); color: inherit; font: inherit; font-weight: 600; cursor: pointer; }
+.apc-direct__add { align-self: flex-start; }
+.apc-direct__add:hover, .apc-direct__rename button:hover { border-color: var(--apc-accent, #b85209); }
+`;
+function copyField(text, label) {
+    const box = document.createElement("div");
+    box.className = "apc-direct__copy";
+    const code = document.createElement("code");
+    code.textContent = text;
+    const button = document.createElement("button");
+    button.type = "button";
+    button.textContent = label;
+    button.addEventListener("click", () => {
+        void navigator.clipboard?.writeText(text).then(() => {
+            button.textContent = "Copied";
+            setTimeout(() => (button.textContent = label), 1500);
+        }, () => undefined);
+    });
+    box.append(code, button);
+    return box;
+}
+/** Defines `<apc-direct-agents>` where custom elements exist (a browser), so importing this module in Node is safe. */
+export function defineDirectAgents(tag = "apc-direct-agents") {
+    if (typeof customElements === "undefined" || customElements.get(tag))
+        return;
+    class ApcDirectAgents extends HTMLElement {
+        list = [];
+        name = "this app";
+        /** Agents whose connection is unfolded; an agent not connected yet is unfolded until it connects. */
+        open = new Set();
+        shut = new Set();
+        editing = null;
+        draft = "";
+        get agents() {
+            return this.list;
+        }
+        set agents(next) {
+            this.list = next;
+            this.render();
+        }
+        get appName() {
+            return this.name;
+        }
+        set appName(next) {
+            this.name = next;
+            this.render();
+        }
+        connectedCallback() {
+            if (!document.getElementById(STYLE_ID)) {
+                const style = document.createElement("style");
+                style.id = STYLE_ID;
+                style.textContent = CSS;
+                document.head.append(style);
+            }
+            this.render();
+        }
+        emit(type, detail = {}) {
+            this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true }));
+        }
+        isOpen(a) {
+            return this.open.has(a.id) || (!a.connected && !this.shut.has(a.id));
+        }
+        render() {
+            if (!this.isConnected)
+                return;
+            const rows = this.list.map((a) => {
+                const row = document.createElement("div");
+                row.className = "apc-direct__agent";
+                const head = document.createElement("div");
+                head.className = "apc-direct__head";
+                if (this.editing === a.id) {
+                    const form = document.createElement("form");
+                    form.className = "apc-direct__rename";
+                    // The app re-renders on every update: what the person typed is kept in draft.
+                    const input = document.createElement("input");
+                    input.value = this.draft;
+                    input.addEventListener("input", () => (this.draft = input.value));
+                    input.maxLength = 40;
+                    input.setAttribute("aria-label", "Agent name");
+                    input.placeholder = "Empty: back to its own name";
+                    const save = document.createElement("button");
+                    save.type = "submit";
+                    save.textContent = "Save";
+                    const cancel = document.createElement("button");
+                    cancel.type = "button";
+                    cancel.textContent = "Cancel";
+                    cancel.addEventListener("click", () => {
+                        this.editing = null;
+                        this.render();
+                    });
+                    input.addEventListener("keydown", (e) => e.key === "Escape" && cancel.click());
+                    form.addEventListener("submit", (e) => {
+                        e.preventDefault();
+                        this.editing = null;
+                        this.emit("apc-rename", { id: a.id, name: this.draft });
+                        this.render();
+                    });
+                    form.append(input, save, cancel);
+                    head.append(form);
+                    queueMicrotask(() => {
+                        input.focus();
+                        input.setSelectionRange(input.value.length, input.value.length);
+                    });
+                }
+                else {
+                    const name = document.createElement("span");
+                    name.className = "apc-direct__name";
+                    name.textContent = a.name;
+                    const status = document.createElement("span");
+                    status.className = "apc-direct__status";
+                    status.textContent = directAgentStatus(a);
+                    const rename = document.createElement("button");
+                    rename.type = "button";
+                    rename.className = "apc-direct__link";
+                    rename.textContent = "Rename";
+                    rename.addEventListener("click", () => {
+                        this.editing = a.id;
+                        this.draft = a.name;
+                        this.render();
+                    });
+                    const toggle = document.createElement("button");
+                    toggle.type = "button";
+                    toggle.className = "apc-direct__link";
+                    const open = this.isOpen(a);
+                    toggle.textContent = open ? "Hide connection" : "Show connection";
+                    toggle.setAttribute("aria-expanded", String(open));
+                    toggle.addEventListener("click", () => {
+                        if (open) {
+                            this.open.delete(a.id);
+                            this.shut.add(a.id);
+                        }
+                        else {
+                            this.open.add(a.id);
+                            this.shut.delete(a.id);
+                        }
+                        this.render();
+                    });
+                    head.append(name, status, rename, toggle);
+                }
+                row.append(head);
+                if (this.isOpen(a)) {
+                    const body = document.createElement("div");
+                    body.className = "apc-direct__body";
+                    const urlHint = document.createElement("p");
+                    urlHint.className = "apc-direct__hint";
+                    urlHint.textContent = "Add this URL to your agent as a remote MCP server (Streamable HTTP). No login: the secret in the URL is its access, so give each agent its own.";
+                    const askHint = document.createElement("p");
+                    askHint.className = "apc-direct__hint";
+                    askHint.textContent = "Don't know how? Paste this to your agent:";
+                    body.append(urlHint, copyField(a.url, "Copy"), askHint, copyField(connectPrompt(a.url, this.name), "Copy prompt"));
+                    row.append(body);
+                }
+                return row;
+            });
+            const add = document.createElement("button");
+            add.type = "button";
+            add.className = "apc-direct__add";
+            add.textContent = this.list.length ? "Add another agent" : "Connect an agent";
+            add.addEventListener("click", () => this.emit("apc-add"));
+            this.replaceChildren(...rows, add);
+        }
+    }
+    customElements.define(tag, ApcDirectAgents);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./pinning.js";
+export * from "./presence.js";
+export * from "./view.js";
+export * from "./agents-bar.js";
+export * from "./pin-badge.js";
+export * from "./direct-agents.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./pinning.js";
+export * from "./presence.js";
+export * from "./view.js";
+export * from "./agents-bar.js";
+export * from "./pin-badge.js";
+export * from "./direct-agents.js";

package/dist/pin-badge.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The pin badge (TIN-482): the standard mark an APC app shows where an agent is pinned. It is the
+ * agent's logo in a square, a dashed breathing ring while the agent has not read the pin, a check
+ * once it has, × to remove the pin, and the agent's name as tooltip. The agent bar (agents-bar.ts)
+ * is where the agents are; this is where one points, and it works the same in every APC app.
+ *
+ * The badge is a mark: it carries data-apc-mark and data-grant, the hooks enablePinning drags by, so
+ * dragging it onto another target moves the pin with no code in the app. While it is dragged it
+ * dims, until the drop or Esc. Where the badge goes is the app's: Pulse floats badges over their
+ * targets, Signals puts them inline next to a post part.
+ *
+ * A custom element in light DOM, like <apc-agents>: enablePinning finds marks by event target, and
+ * the app's fonts and theme apply. Its styles are injected once and scoped by class prefix; the app
+ * themes it through --apc-* custom properties (--apc-chip, --apc-line, --apc-ink, --apc-muted, --apc-accent, --apc-ok, and --apc-pin-font for
+ * the check). Framework-agnostic: set `agent`, listen for apc-unpin.
+ *
+ * The browser extension keeps a copy of this badge's look (apps/extension/src/content.ts): a content
+ * script has no customElements, and it moves the badge with its own drag, since a moved reading is
+ * sent again from the page. Keep the two in step.
+ */
+export interface PinAgent {
+    /** The app's id for the agent (its grant): what the mark drags as. */
+    id: string;
+    name: string;
+    /** An image source for the agent's mark (a data URI or URL), unless the app draws it (renderIcon). */
+    icon?: string | null;
+    /** Whether the agent has read the pin: a check instead of the dashed ring. */
+    seen: boolean;
+}
+/** Event, with detail { id }: the person removed the pin. */
+export type PinBadgeEvent = "apc-unpin";
+/** The words a badge says, for its tooltip and screen readers. Pure, so it is tested. */
+export declare function pinBadgeLabels(a: Pick<PinAgent, "name" | "seen">): {
+    title: string;
+    unpin: string;
+};
+/** The element's constructor, defined only where custom elements exist (a browser), so importing this module in Node is safe. */
+export declare function definePinBadge(tag?: string): void;
+/** The element's type, for apps that hold a reference to it. */
+export interface ApcPinElement extends HTMLElement {
+    agent: PinAgent | null;
+    readonly mark: HTMLElement | null;
+    readonly iconHost: HTMLElement | null;
+    renderIcon: ((agent: PinAgent, into: HTMLElement) => void) | null;
+}

package/dist/pin-badge.js

@@ -0,0 +1,174 @@
+/**
+ * The pin badge (TIN-482): the standard mark an APC app shows where an agent is pinned. It is the
+ * agent's logo in a square, a dashed breathing ring while the agent has not read the pin, a check
+ * once it has, × to remove the pin, and the agent's name as tooltip. The agent bar (agents-bar.ts)
+ * is where the agents are; this is where one points, and it works the same in every APC app.
+ *
+ * The badge is a mark: it carries data-apc-mark and data-grant, the hooks enablePinning drags by, so
+ * dragging it onto another target moves the pin with no code in the app. While it is dragged it
+ * dims, until the drop or Esc. Where the badge goes is the app's: Pulse floats badges over their
+ * targets, Signals puts them inline next to a post part.
+ *
+ * A custom element in light DOM, like <apc-agents>: enablePinning finds marks by event target, and
+ * the app's fonts and theme apply. Its styles are injected once and scoped by class prefix; the app
+ * themes it through --apc-* custom properties (--apc-chip, --apc-line, --apc-ink, --apc-muted, --apc-accent, --apc-ok, and --apc-pin-font for
+ * the check). Framework-agnostic: set `agent`, listen for apc-unpin.
+ *
+ * The browser extension keeps a copy of this badge's look (apps/extension/src/content.ts): a content
+ * script has no customElements, and it moves the badge with its own drag, since a moved reading is
+ * sent again from the page. Keep the two in step.
+ */
+const STYLE_ID = "apc-pin-style";
+const CSS = `
+apc-pin { position: relative; display: inline-block; width: var(--apc-pin-size, 28px); height: var(--apc-pin-size, 28px); vertical-align: middle; }
+.apc-pin__mark { display: grid; place-items: center; width: var(--apc-pin-size, 28px); height: var(--apc-pin-size, 28px); border-radius: 6px; cursor: grab; touch-action: none; outline-offset: 2px;
+  background: var(--apc-chip, #ffffff); color: var(--apc-ink, #141a24); box-shadow: 0 2px 6px rgb(0 0 0 / 0.18); }
+.apc-pin__icon { display: grid; place-items: center; }
+.apc-pin__mark .apc-pin__img { width: 18px; height: 18px; display: block; object-fit: contain; pointer-events: none; }
+apc-pin[data-apc-pin-state="waiting"] .apc-pin__mark { outline: 2px dashed var(--apc-accent, #b85209); animation: apc-pin-breathe 1.8s ease-in-out infinite; }
+apc-pin.apc-pin--dragging { opacity: 0.35; }
+.apc-pin__check { position: absolute; right: -7px; bottom: -7px; width: 15px; height: 15px; border-radius: 50%; background: var(--apc-ok, #1f7a4d); color: #fff;
+  font: 700 10px/15px var(--apc-pin-font, ui-monospace, monospace); text-align: center; }
+.apc-pin__check[hidden] { display: none; }
+.apc-pin__unpin { position: absolute; right: -8px; top: -8px; width: 16px; height: 16px; padding: 0; border-radius: 50%; border: 1px solid var(--apc-line, #d6dce5);
+  background: var(--apc-pin-unpin-bg, var(--apc-chip, #ffffff)); color: var(--apc-muted, #56627a); font-size: 12px; line-height: 13px; cursor: pointer; opacity: 0.85; }
+.apc-pin__unpin:hover { color: var(--apc-ink, #141a24); opacity: 1; }
+@media (pointer: coarse), (max-width: 640px) { .apc-pin__unpin::after { content: ""; position: absolute; inset: -14px; } }
+@keyframes apc-pin-breathe { 0%, 100% { outline-offset: 2px; } 50% { outline-offset: 4px; } }
+@media (prefers-reduced-motion: reduce) { apc-pin .apc-pin__mark { animation: none !important; } }
+`;
+/** A small robot, for an agent with no icon. */
+const BOT = '<svg class="apc-pin__img" viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M11 2h2v2.07A7 7 0 0 1 19 11v7a3 3 0 0 1-3 3H8a3 3 0 0 1-3-3v-7a7 7 0 0 1 6-6.93V2Zm-2.5 10a1.5 1.5 0 1 0 0 3 1.5 1.5 0 0 0 0-3Zm7 0a1.5 1.5 0 1 0 0 3 1.5 1.5 0 0 0 0-3ZM2 12h2v5H2v-5Zm18 0h2v5h-2v-5Z"/></svg>';
+/** The words a badge says, for its tooltip and screen readers. Pure, so it is tested. */
+export function pinBadgeLabels(a) {
+    return {
+        title: `${a.name}: ${a.seen ? "read this pin" : "has not read this pin yet"}. Drag to point it at something else.`,
+        unpin: `Remove ${a.name}'s pin`,
+    };
+}
+/** The element's constructor, defined only where custom elements exist (a browser), so importing this module in Node is safe. */
+export function definePinBadge(tag = "apc-pin") {
+    // Null in a content script, where there are no custom elements.
+    if (!globalThis.customElements || customElements.get(tag))
+        return;
+    class ApcPin extends HTMLElement {
+        value = null;
+        parts = null;
+        iconKey = "";
+        stopDim = null;
+        draw = null;
+        /**
+         * The app draws the agent's icon into this element itself (for example with its own logos). Called on every update.
+         * A function that draws nothing says the app draws it elsewhere, into `iconHost` (React: a portal).
+         */
+        get renderIcon() {
+            return this.draw;
+        }
+        set renderIcon(next) {
+            this.draw = next;
+            this.render();
+        }
+        /** Where the agent's icon goes: the app may draw into it once the badge is connected. */
+        get iconHost() {
+            return this.parts?.icon ?? null;
+        }
+        get agent() {
+            return this.value;
+        }
+        set agent(next) {
+            this.value = next;
+            this.render();
+        }
+        /** The mark inside: what a drag starts from. */
+        get mark() {
+            return this.parts?.mark ?? null;
+        }
+        connectedCallback() {
+            // A property set before the element was defined (a framework, a script) sits on the instance: take it in through the setter.
+            const own = this;
+            for (const key of ["agent", "renderIcon"]) {
+                if (!Object.hasOwn(own, key))
+                    continue;
+                const value = own[key];
+                delete own[key];
+                own[key] = value;
+            }
+            if (!document.getElementById(STYLE_ID)) {
+                const style = document.createElement("style");
+                style.id = STYLE_ID;
+                style.textContent = CSS;
+                document.head.append(style);
+            }
+            if (!this.parts) {
+                const mark = document.createElement("span");
+                mark.className = "apc-pin__mark";
+                mark.setAttribute("data-apc-mark", "");
+                const icon = document.createElement("span");
+                icon.className = "apc-pin__icon";
+                mark.append(icon);
+                const check = document.createElement("span");
+                check.className = "apc-pin__check";
+                check.textContent = "✓";
+                check.setAttribute("aria-hidden", "true");
+                const unpin = document.createElement("button");
+                unpin.type = "button";
+                unpin.className = "apc-pin__unpin";
+                unpin.textContent = "×";
+                unpin.addEventListener("click", (e) => e.isTrusted && this.value && this.dispatchEvent(new CustomEvent("apc-unpin", { detail: { id: this.value.id }, bubbles: true })));
+                // The badge dims from the press until the drop or Esc (the drag itself is enablePinning's).
+                mark.addEventListener("pointerdown", (e) => e.button === 0 && this.dim());
+                this.parts = { mark, icon, check, unpin };
+                this.append(mark, check, unpin);
+            }
+            this.render();
+        }
+        disconnectedCallback() {
+            this.stopDim?.();
+        }
+        dim() {
+            this.stopDim?.();
+            this.classList.add("apc-pin--dragging");
+            const stop = () => this.stopDim?.();
+            const onKey = (e) => e.key === "Escape" && stop();
+            window.addEventListener("pointerup", stop);
+            window.addEventListener("pointercancel", stop);
+            window.addEventListener("keydown", onKey);
+            this.stopDim = () => {
+                window.removeEventListener("pointerup", stop);
+                window.removeEventListener("pointercancel", stop);
+                window.removeEventListener("keydown", onKey);
+                this.classList.remove("apc-pin--dragging");
+                this.stopDim = null;
+            };
+        }
+        render() {
+            const a = this.value;
+            if (!this.parts || !a)
+                return;
+            const { mark, icon, check, unpin } = this.parts;
+            const labels = pinBadgeLabels(a);
+            this.setAttribute("title", labels.title);
+            this.setAttribute("data-apc-pin-state", a.seen ? "seen" : "waiting");
+            mark.setAttribute("data-grant", a.id);
+            mark.setAttribute("role", "img");
+            mark.setAttribute("aria-label", `${a.name}, ${a.seen ? "has read its pin" : "has not read its pin yet"}`);
+            check.hidden = !a.seen;
+            unpin.setAttribute("aria-label", labels.unpin);
+            if (this.draw)
+                this.draw(a, icon);
+            else if (this.iconKey !== JSON.stringify(a.icon ?? null)) {
+                this.iconKey = JSON.stringify(a.icon ?? null);
+                if (a.icon) {
+                    const img = document.createElement("img");
+                    img.className = "apc-pin__img";
+                    img.src = a.icon;
+                    img.alt = a.name;
+                    icon.replaceChildren(img);
+                }
+                else
+                    icon.innerHTML = BOT;
+            }
+        }
+    }
+    customElements.define(tag, ApcPin);
+}

package/dist/pinning.d.ts

@@ -0,0 +1,160 @@
+import { type ApcRole, type FocusTarget } from "@tineira/apc-protocol";
+/** How long the page waits for its own apc.json: a held drop never waits longer. */
+export declare const APC_JSON_LOAD_MS = 3000;
+/**
+ * The profiles the page's own app offers, from its apc.json (APC 0.5), for `enablePinning({ profiles })`:
+ * read without cookies, with no redirect followed, within APC_JSON_LOAD_MS for headers and body, and at
+ * most APC_JSON_MAX_BYTES, as the hub and the extension read it. Kept per origin once read; null when
+ * there is no valid file in time, and then read again on the next call.
+ */
+export declare function loadApcProfiles(origin?: string, fetcher?: typeof fetch): Promise<ApcRole[] | null>;
+export interface PinningOptions {
+    /** Where marks and targets live; defaults to document. */
+    root?: Document | HTMLElement;
+    /** Selector of the draggable agent marks; each carries data-grant. */
+    markSelector?: string;
+    /** Refuse a target for one agent (for example outside a restricted grant). */
+    canTarget?: (grantId: string, target: FocusTarget) => boolean;
+    onPin: (grantId: string, target: FocusTarget, element: Element) => void;
+    /**
+     * APC v2, opt-in (TIN-369): also accept a native HTML5 drop of an agent dragged from another
+     * window (a dock), whose dataTransfer carries APC_AGENT_TYPE. Off by default: v1 apps do not turn it on.
+     */
+    acceptNativeDrops?: boolean;
+    /**
+     * The grant a dropped agent's public handle names in this app, or null when the app does not know
+     * it (the drop is then ignored). Defaults to the handle itself, taken as a grant id.
+     */
+    resolveAgent?: (handle: string) => string | null;
+    /**
+     * APC v2, opt-in (TIN-382): a dropped agent this app does not know yet, whose drag names its hub
+     * and carries a pairing ticket. The app asks the person, then pairs with the hub. Without it the drop is ignored.
+     */
+    onUnknownAgent?: (drag: AgentDrag & {
+        hub: string;
+        ticket: string;
+    }, target: FocusTarget, element: Element) => void;
+    /**
+     * APC 0.5: the profiles this app offers, as its apc.json says: a list; a promise of one; or a loader,
+     * such as `loadApcProfiles` itself, called now and again on a later dock drop if it gave nothing. An app
+     * without "dock" still takes the drop of an agent dragged from a dock, anywhere on the page and with or
+     * without acceptNativeDrops, and answers it with `onDockUnsupported` instead of `onUnknownAgent`: never
+     * a drop that silently does nothing. While the profiles load, a dock agent's drop is taken and held,
+     * then answered or paired as they say. When they cannot be read (null, an error, the time limit), the
+     * drop is never sent to pairing: it is answered as `unchecked` ("could not check this app").
+     */
+    profiles?: readonly ApcRole[] | PromiseLike<readonly ApcRole[] | null> | (() => PromiseLike<readonly ApcRole[] | null>);
+    /** For that answer: the app's name and the page where the person connects an agent directly (apc.json's `direct.connect`). */
+    direct?: {
+        name: string;
+        connect: string | null;
+    };
+    /** A dock agent dropped on an app that does not offer Dock. Without it, `showDockUnsupported` tells the person in the page. */
+    onDockUnsupported?: (answer: DockUnsupported) => void;
+    /**
+     * Which events may arm, tap, pin or drag (APC 0.6). By default only the person's own: `event.isTrusted`,
+     * so a script in the page (`element.click()`, a dispatched PointerEvent) cannot point an agent at data.
+     * A test that sends events of its own passes `() => true`; nothing in a page can reach this.
+     */
+    trusted?: (event: Event) => boolean;
+}
+/** The answer to a dock agent dropped on a Direct-only app: who it was, what to tell the person, and where they connect instead. */
+export interface DockUnsupported {
+    drag: AgentDrag;
+    /** The target under the drop, if any. */
+    target: FocusTarget | null;
+    name: string;
+    connect: string | null;
+    /**
+     * `direct_only`: the app's apc.json lists no "dock". `unchecked`: the page could not read its own
+     * apc.json, so it cannot tell, and it pairs nothing it cannot check.
+     */
+    reason: "direct_only" | "unchecked";
+    /** `directOnlyNote(name)`, or `couldNotCheckNote(name)`: the app's own words, on its own page. */
+    message: string;
+}
+export declare function showDockUnsupported(answer: DockUnsupported): HTMLElement;
+/** What an agent's drag carries. hub and ticket come with pairing (TIN-382): the hub's origin and a single-use, short-lived ticket. */
+export interface AgentDrag {
+    v: 1;
+    agent: string;
+    hub?: string;
+    ticket?: string;
+}
+/** The drag type a dock puts on an agent: its payload is agentDragPayload(handle), never a secret. */
+export declare const APC_AGENT_TYPE = "application/x-apc-agent";
+/**
+ * Set on the page's root element while enablePinning takes native agent drops (APC 0.5): the page
+ * answers every drop of a dock agent itself, so the browser extension stands back even on a
+ * Direct-only app. A Direct-only app without it gets the extension's answer instead.
+ */
+export declare const APC_DROPS_ATTR = "data-apc-native-drops";
+/**
+ * What an agent's drag carries: a public handle and nothing else. Any page the agent is dropped on
+ * can read it, so it must never hold a grant secret or an MCP URL.
+ */
+export declare function agentDragPayload(handle: string, pairing?: {
+    hub: string;
+    ticket: string;
+}): string;
+/**
+ * A drag payload, or null when it is not one (another app's data, a wrong version, junk). A hub
+ * that is not a bare http(s) origin, or a ticket that is not a short token, is dropped, not the drag.
+ */
+export declare function parseAgentDrag(text: string): AgentDrag | null;
+/** The handle in a drag payload, or null when it is not one. */
+export declare function parseAgentDragPayload(text: string): string | null;
+/** The innermost pointable element at a point, with its parsed target. */
+export declare function targetAt(x: number, y: number): {
+    element: Element;
+    target: FocusTarget;
+} | null;
+/** The innermost pointable element at or above a node, with its parsed target. */
+export declare function targetOf(start: Element | null): {
+    element: Element;
+    target: FocusTarget;
+} | null;
+/**
+ * Tap to pin (APC 0.6, the touch way): the person taps an agent's mark (the agent is then "armed"),
+ * then taps a target. Pure, so it is tested: it holds which agent is armed and what a tap on a target
+ * does. A second tap on the armed mark, or cancel, lets go; a tap that is no target, or a target the
+ * agent may not point at, keeps the agent armed.
+ */
+export type TapPinResult = "pinned" | "no_target" | "refused" | "idle";
+export interface TapPin {
+    /** The armed agent's grant id, or null. */
+    readonly armed: string | null;
+    /** Arm this agent; the armed one again lets go. Returns the armed agent after. */
+    toggle(grantId: string): string | null;
+    cancel(): void;
+    /** A tap, with the target under it (or null). Pins the armed agent there. */
+    tap(hit: {
+        element: Element;
+        target: FocusTarget;
+    } | null): TapPinResult;
+}
+export declare function createTapPin(options: {
+    canTarget?: PinningOptions["canTarget"];
+    onPin: PinningOptions["onPin"];
+    onChange?: (armed: string | null) => void;
+}): TapPin;
+/** The window event fired when an agent is armed or let go (detail.id: the grant id or null): the agent bar marks the armed mark. */
+export declare const APC_ARMED_EVENT = "apc-armed";
+/** Less than this many pixels between a touch's down and up is a tap, not a drag. */
+export declare const TAP_SLOP_PX = 10;
+/**
+ * Drag an agent's mark onto anything that carries data-focus. While dragging,
+ * the body has class apc-dragging (valid targets can outline themselves) and
+ * the target under the pointer has class apc-target. Escape cancels.
+ *
+ * Touch (APC 0.6): a finger can drag a mark the same way (pointer events), and a plain tap on a mark
+ * (a touch or pen press that moves under TAP_SLOP_PX, or a keyboard activation) arms the agent
+ * instead: "tap to pin". The body gets class apc-armed (and apc-dragging), every target is outlined,
+ * a note at the bottom of the page says what to do and has Cancel, and the next tap on a target pins
+ * the agent there (the click that follows is swallowed, so the target's own action does not run).
+ * Tapping the mark again, Cancel or Escape lets go. A mouse click on a mark does nothing, as before.
+ * A pin badge (<apc-pin>) can be dragged by touch but does not arm: it is where an agent points,
+ * not where agents are.
+ * Returns a function that removes the listeners.
+ */
+export declare function enablePinning(options: PinningOptions): () => void;