@tineira/apc-web 0.7.1 → 0.9.0

package/README.md

@@ -27,4 +27,6 @@ const stop = enablePinning({ onPin: (grantId, target) => savePin(grantId, target
 
 `onPin` gets the agent's grant and a `FocusTarget` (`{ kind, id, part, params }`); your server keeps it as that grant's pin and gives it to the agent ([`@tineira/apc-server`](https://www.npmjs.com/package/@tineira/apc-server)).
 
+Every string it draws can be passed by your app (`strings` on each component; see "Localize the page" in the docs), with the English as default.
+
 Source, the worked examples (Pulse and Signals) and the changelog: https://github.com/tineira/agent-pointed-context. MIT.

package/dist/agents-bar.d.ts

@@ -30,6 +30,7 @@
  *   per browser). On by default; an app turns it off with `dockHint = null` or `dock-hint="off"`.
  */
 import { type ApcProfile } from "@tineira/apc-protocol";
+import { type BarStrings } from "./strings.js";
 export type AgentState = "off" | "idle" | "waiting" | "busy" | "seen";
 export interface BarAgent {
     /** The app's id for the agent (its grant): what pins name. */
@@ -65,14 +66,14 @@ export declare function mergePins<P extends {
     label: string;
     seen: boolean;
     here: boolean;
-}>(pins: ReadonlyArray<P | null | undefined>): P | null;
+}>(pins: ReadonlyArray<P | null | undefined>, strings?: Partial<BarStrings> | null): P | null;
 /** The hint that offers the dock to a Direct user, and where it leads. */
 export declare const DOCK_HINT: {
-    readonly text: "Use this agent across apps with the dock";
+    readonly text: string;
     readonly url: "https://apc.tineira.com/dock";
 };
 /** The words for the path an agent came by, for its tag. Null when the app does not say. */
-export declare function pathLabel(paths: readonly ApcProfile[] | undefined): {
+export declare function pathLabel(paths: readonly ApcProfile[] | undefined, given?: Partial<BarStrings> | null): {
     text: string;
     title: string;
 } | null;
@@ -84,14 +85,14 @@ export declare function isMobileViewport(): boolean;
  */
 export declare function barCanCollapse(agents: readonly BarAgent[], mobile?: boolean): boolean;
 /** Who is reading, for the collapsed indicator: the agents that connected. */
-export declare function readingSummary(agents: readonly BarAgent[]): string;
+export declare function readingSummary(agents: readonly BarAgent[], given?: Partial<BarStrings> | null): string;
 /** The dock hint shows while an agent that came only directly is connected, unless the app turned it off or the person dismissed it. */
 export declare function showDockHint(agents: readonly BarAgent[], options: {
     enabled: boolean;
     dismissed: boolean;
 }): boolean;
 /** The words a mark, its dot and its revoke button say, for tooltips and screen readers. Pure, so it is tested. */
-export declare function agentLabels(a: BarAgent): {
+export declare function agentLabels(a: BarAgent, given?: Partial<BarStrings> | null): {
     mark: string;
     dot: string | null;
     revoke: string;
@@ -107,4 +108,6 @@ export interface ApcAgentsElement extends HTMLElement {
         text: string;
         url: string;
     } | null;
+    /** The bar's strings (TIN-668): set the keys you translate; the rest stay English. */
+    strings: Partial<BarStrings> | null;
 }

package/dist/agents-bar.js

@@ -31,6 +31,7 @@
  */
 import { APC_MOBILE_MEDIA } from "@tineira/apc-protocol";
 import { APC_ARMED_EVENT } from "./pinning.js";
+import { DEFAULT_BAR_STRINGS, resolveStrings } from "./strings.js";
 /** How long the first click on ⊘ waits for the second before it lets go. */
 export const REVOKE_CONFIRM_MS = 4000;
 /**
@@ -39,23 +40,24 @@ export const REVOKE_CONFIRM_MS = 4000;
  * target once), unread until both are read, and "here" only when both targets are on screen (so the
  * dot still opens the one that is not). No pin at all is null.
  */
-export function mergePins(pins) {
+export function mergePins(pins, strings) {
     const some = pins.filter((p) => !!p);
     if (some.length < 2)
         return some[0] ?? null;
-    return { ...some[0], label: [...new Set(some.map((p) => p.label))].join(" and "), seen: some.every((p) => p.seen), here: some.every((p) => p.here) };
+    return { ...some[0], label: resolveStrings(DEFAULT_BAR_STRINGS, strings).joinPins([...new Set(some.map((p) => p.label))]), seen: some.every((p) => p.seen), here: some.every((p) => p.here) };
 }
 /** The hint that offers the dock to a Direct user, and where it leads. */
-export const DOCK_HINT = { text: "Use this agent across apps with the dock", url: "https://apc.tineira.com/dock" };
+export const DOCK_HINT = { text: DEFAULT_BAR_STRINGS.dockHint, url: "https://apc.tineira.com/dock" };
 const COLLAPSED_KEY = "apc-agents.collapsed";
 const HINT_KEY = "apc-agents.dock-hint";
 /** The words for the path an agent came by, for its tag. Null when the app does not say. */
-export function pathLabel(paths) {
+export function pathLabel(paths, given) {
     if (!paths?.length)
         return null;
+    const strings = resolveStrings(DEFAULT_BAR_STRINGS, given);
     if (paths.includes("direct") && paths.includes("dock"))
-        return { text: "direct + dock", title: "The same agent, connected directly and through a dock. Each way keeps its own access; Revoke cuts both." };
-    return paths[0] === "direct" ? { text: "direct", title: "Connected directly, on this app's own MCP URL" } : { text: "via dock", title: "Came through an agent dock" };
+        return { text: strings.pathBoth, title: strings.pathBothTitle };
+    return paths[0] === "direct" ? { text: strings.pathDirect, title: strings.pathDirectTitle } : { text: strings.pathDock, title: strings.pathDockTitle };
 }
 /** Whether this window is a phone or any touch viewport (APC 0.6): a coarse pointer or a narrow width. False where there is no window. */
 export function isMobileViewport() {
@@ -69,13 +71,10 @@ export function barCanCollapse(agents, mobile = false) {
     return !mobile && agents.length > 0 && agents.every((a) => !!a.paths?.length && !a.paths.includes("direct"));
 }
 /** Who is reading, for the collapsed indicator: the agents that connected. */
-export function readingSummary(agents) {
+export function readingSummary(agents, given) {
+    const strings = resolveStrings(DEFAULT_BAR_STRINGS, given);
     const names = agents.filter((a) => a.state !== "off").map((a) => a.name);
-    if (!names.length)
-        return "No agent is reading";
-    if (names.length === 1)
-        return `${names[0]} is reading`;
-    return `${names.slice(0, -1).join(", ")} and ${names.at(-1)} are reading`;
+    return names.length ? strings.reading(names) : strings.nobodyReading;
 }
 /** The dock hint shows while an agent that came only directly is connected, unless the app turned it off or the person dismissed it. */
 export function showDockHint(agents, options) {
@@ -163,15 +162,15 @@ html.apc-bar-fixed body { padding-bottom: var(--apc-bar-height, 0px); }
 /** A small robot, for an agent with no icon. */
 const BOT = '<svg 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 mark, its dot and its revoke button say, for tooltips and screen readers. Pure, so it is tested. */
-export function agentLabels(a) {
-    const mark = `${a.name}${a.state === "off" ? " (not connected yet)" : ""}. Drag onto anything to point this agent.`;
+export function agentLabels(a, given) {
+    const strings = resolveStrings(DEFAULT_BAR_STRINGS, given);
+    const mark = strings.markTitle(a.name, a.state !== "off");
     const both = !!a.paths?.includes("direct") && !!a.paths.includes("dock");
-    const revoke = `Revoke ${a.name}: it can no longer read this app${both ? ", directly or through the dock" : ""}, at once. To let it back, connect or drop it here again.`;
-    const revokeArmed = `Click again to revoke ${a.name}.`;
+    const revoke = strings.revokeTitle(a.name, both);
+    const revokeArmed = strings.revokeConfirmTitle(a.name);
     if (!a.pin)
         return { mark, dot: null, revoke, revokeArmed };
-    const read = a.pin.seen ? "your agent read it" : "waiting for your agent's next call";
-    return { mark, dot: `Pinned to ${a.pin.label}: ${read}${a.pin.here ? "" : ". Click to open it."}`, revoke, revokeArmed };
+    return { mark, dot: strings.pinTitle(a.pin.label, a.pin.seen, a.pin.here), revoke, revokeArmed };
 }
 /** The room each fixed bar takes at the bottom of the page: the page keeps the largest, as --apc-bar-height and padding on <body>. */
 const reserved = new Map();
@@ -202,7 +201,12 @@ export function defineAgentBar(tag = "apc-agents") {
         armed = new Map();
         /** The app draws an agent's icon into this element itself (for example with its own logos). Called on every update. */
         renderIcon = null;
-        hint = { ...DOCK_HINT };
+        /** undefined: the default hint, in the bar's strings; null: off. */
+        hint = undefined;
+        words = DEFAULT_BAR_STRINGS;
+        given = null;
+        /** Bumped when the strings change, so every entry is drawn again. */
+        stringsVersion = 0;
         /** The collapsed indicator's icons, kept per agent like the marks' (an app's renderIcon may keep state in them). */
         miniIcons = new Map();
         get agents() {
@@ -214,12 +218,26 @@ export function defineAgentBar(tag = "apc-agents") {
         }
         /** The hint that offers the dock to a Direct user; null turns it off. */
         get dockHint() {
-            return this.getAttribute("dock-hint") === "off" ? null : this.hint;
+            if (this.getAttribute("dock-hint") === "off" || this.hint === null)
+                return null;
+            return this.hint ?? { text: this.words.dockHint, url: DOCK_HINT.url };
         }
         set dockHint(next) {
             this.hint = next;
             this.render();
         }
+        /** Every string the bar shows (TIN-668): the keys you set, over the English defaults. */
+        get strings() {
+            return this.given;
+        }
+        set strings(next) {
+            this.given = next;
+            this.words = resolveStrings(DEFAULT_BAR_STRINGS, next);
+            this.stringsVersion++;
+            if (this.getAttribute("data-apc-label") === "default")
+                this.setAttribute("aria-label", this.words.toolbar);
+            this.render();
+        }
         /** Mobile (APC 0.6): the viewport is a phone's or a touch one's; the bar then never collapses. */
         media = null;
         resizer = null;
@@ -268,8 +286,10 @@ export function defineAgentBar(tag = "apc-agents") {
             }
             if (!this.hasAttribute("role"))
                 this.setAttribute("role", "toolbar");
-            if (!this.hasAttribute("aria-label"))
-                this.setAttribute("aria-label", "Agents");
+            if (!this.hasAttribute("aria-label")) {
+                this.setAttribute("aria-label", this.words.toolbar);
+                this.setAttribute("data-apc-label", "default");
+            }
             this.render();
         }
         emit(type, id) {
@@ -334,8 +354,8 @@ export function defineAgentBar(tag = "apc-agents") {
                 fold.type = "button";
                 fold.className = "apc-agents__collapse apc-agents__extra";
                 fold.textContent = "‹";
-                fold.title = "Collapse to who is reading. Your agents came through your dock: drag them from there.";
-                fold.setAttribute("aria-label", "Collapse the agent bar");
+                fold.title = this.words.collapseTitle;
+                fold.setAttribute("aria-label", this.words.collapseAria);
                 fold.addEventListener("click", () => {
                     store(COLLAPSED_KEY, "1");
                     this.render();
@@ -352,9 +372,9 @@ export function defineAgentBar(tag = "apc-agents") {
             const button = document.createElement("button");
             button.type = "button";
             button.className = "apc-agents__mini apc-agents__extra";
-            const summary = readingSummary(this.list);
-            button.title = `${summary}. Show the agents.`;
-            button.setAttribute("aria-label", `${summary}. Show the agents.`);
+            const summary = readingSummary(this.list, this.words);
+            button.title = this.words.showAgents(summary);
+            button.setAttribute("aria-label", this.words.showAgents(summary));
             for (const a of reading.slice(0, 4)) {
                 let icon = this.miniIcons.get(a.id);
                 if (!icon) {
@@ -374,7 +394,7 @@ export function defineAgentBar(tag = "apc-agents") {
                     icon.innerHTML = BOT;
                 button.append(icon);
             }
-            button.append(document.createTextNode(reading.length ? `${reading.length} reading` : "no agent reading"));
+            button.append(document.createTextNode(reading.length ? this.words.readingCount(reading.length) : this.words.nobodyReadingShort));
             button.addEventListener("click", () => {
                 store(COLLAPSED_KEY, null);
                 this.render();
@@ -397,15 +417,15 @@ export function defineAgentBar(tag = "apc-agents") {
             const close = document.createElement("button");
             close.type = "button";
             close.textContent = "×";
-            close.setAttribute("aria-label", "Dismiss this hint");
+            close.setAttribute("aria-label", this.words.dockHintDismiss);
             close.addEventListener("click", dismiss);
             box.append(link, close);
             return box;
         }
         fill(node, a) {
-            const labels = agentLabels(a);
+            const labels = agentLabels(a, this.words);
             const armed = this.armed.has(a.id);
-            const key = JSON.stringify([a.name, a.state, a.pin, a.warning, a.restricted, typeof a.icon === "string" ? a.icon.length : null, armed, a.paths ?? null]);
+            const key = JSON.stringify([a.name, a.state, a.pin, a.warning, a.restricted, typeof a.icon === "string" ? a.icon.length : null, armed, a.paths ?? null, this.stringsVersion]);
             if (this.renderIcon)
                 this.renderIcon(a, node.icon);
             else if (node.key === "" || JSON.stringify(a.icon ?? null) !== node.icon.dataset.src) {
@@ -451,19 +471,19 @@ export function defineAgentBar(tag = "apc-agents") {
                 dot.type = "button";
                 dot.className = `apc-agents__dot${a.pin.seen ? " apc-agents__dot--seen" : ""}${a.pin.here ? "" : " apc-agents__dot--away"}`;
                 dot.title = labels.dot;
-                dot.setAttribute("aria-label", `${a.name} pinned to ${a.pin.label}${a.pin.seen ? ", read" : ", not read yet"}`);
+                dot.setAttribute("aria-label", this.words.pinAria(a.name, a.pin.label, a.pin.seen));
                 dot.addEventListener("click", () => !a.pin?.here && this.emit("apc-open", a.id));
                 const unpin = document.createElement("button");
                 unpin.type = "button";
                 unpin.className = "apc-agents__unpin";
                 unpin.textContent = "×";
-                unpin.setAttribute("aria-label", `Remove ${a.name}'s pin`);
+                unpin.setAttribute("aria-label", this.words.unpinAria(a.name));
                 unpin.addEventListener("click", (e) => e.isTrusted && this.emit("apc-unpin", a.id));
                 pin.append(dot, unpin);
                 parts.push(pin);
             }
             // Which path it came by; a linked agent can be shown as two again.
-            const path = pathLabel(a.paths);
+            const path = pathLabel(a.paths, this.words);
             if (path) {
                 const tag = document.createElement("span");
                 tag.className = "apc-agents__path";
@@ -474,9 +494,9 @@ export function defineAgentBar(tag = "apc-agents") {
                     const unlink = document.createElement("button");
                     unlink.type = "button";
                     unlink.className = "apc-agents__unlink";
-                    unlink.textContent = "unlink";
-                    unlink.title = `Show ${a.name}'s two connections as two agents again. Nothing else changes.`;
-                    unlink.setAttribute("aria-label", `Unlink ${a.name}`);
+                    unlink.textContent = this.words.unlink;
+                    unlink.title = this.words.unlinkTitle(a.name);
+                    unlink.setAttribute("aria-label", this.words.unlinkAria(a.name));
                     unlink.addEventListener("click", (e) => e.isTrusted && this.emit("apc-unlink", a.id));
                     parts.push(unlink);
                 }
@@ -485,9 +505,9 @@ export function defineAgentBar(tag = "apc-agents") {
             const revoke = document.createElement("button");
             revoke.type = "button";
             revoke.className = `apc-agents__revoke${armed ? " apc-agents__revoke--armed" : ""}`;
-            revoke.textContent = armed ? "Revoke?" : "⊘";
+            revoke.textContent = armed ? this.words.revokeConfirm : "⊘";
             revoke.title = armed ? labels.revokeArmed : labels.revoke;
-            revoke.setAttribute("aria-label", armed ? labels.revokeArmed : `Revoke ${a.name}`);
+            revoke.setAttribute("aria-label", armed ? labels.revokeArmed : this.words.revokeAria(a.name));
             revoke.addEventListener("click", (e) => e.isTrusted && this.revokeClicked(a.id));
             revoke.addEventListener("keydown", (e) => e.key === "Escape" && this.disarm(a.id));
             parts.push(revoke);

package/dist/direct-agents.d.ts

@@ -8,6 +8,7 @@
  * 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 }).
  */
+import { type DirectStrings } from "./strings.js";
 export interface DirectAgent {
     /** The app's id for the agent's grant. */
     id: string;
@@ -27,13 +28,15 @@ export type DirectAgentsEvent = "apc-add" | "apc-rename";
  * 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;
+export declare function connectPrompt(url: string, appName: string, strings?: Partial<DirectStrings> | null): string;
 /** The words of one agent's line. Pure, so it is tested. */
-export declare function directAgentStatus(a: DirectAgent): string;
+export declare function directAgentStatus(a: DirectAgent, strings?: Partial<DirectStrings> | null): 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;
+    /** The list's strings (TIN-668): set the keys you translate; the rest stay English. */
+    strings: Partial<DirectStrings> | null;
 }

package/dist/direct-agents.js

@@ -8,20 +8,18 @@
  * 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 }).
  */
+import { DEFAULT_DIRECT_STRINGS, resolveStrings } from "./strings.js";
 /**
  * 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.`;
+export function connectPrompt(url, appName, strings) {
+    return resolveStrings(DEFAULT_DIRECT_STRINGS, strings).prompt(url, appName);
 }
 /** 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;
+export function directAgentStatus(a, strings) {
+    return resolveStrings(DEFAULT_DIRECT_STRINGS, strings).status(a);
 }
 const STYLE_ID = "apc-direct-style";
 const CSS = `
@@ -43,7 +41,7 @@ apc-direct-agents { display: flex; flex-direction: column; gap: 10px; color: var
 .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) {
+function copyField(text, label, copied) {
     const box = document.createElement("div");
     box.className = "apc-direct__copy";
     const code = document.createElement("code");
@@ -53,7 +51,7 @@ function copyField(text, label) {
     button.textContent = label;
     button.addEventListener("click", () => {
         void navigator.clipboard?.writeText(text).then(() => {
-            button.textContent = "Copied";
+            button.textContent = copied;
             setTimeout(() => (button.textContent = label), 1500);
         }, () => undefined);
     });
@@ -66,7 +64,9 @@ export function defineDirectAgents(tag = "apc-direct-agents") {
         return;
     class ApcDirectAgents extends HTMLElement {
         list = [];
-        name = "this app";
+        name = null;
+        words = DEFAULT_DIRECT_STRINGS;
+        given = null;
         /** Agents whose connection is unfolded; an agent not connected yet is unfolded until it connects. */
         open = new Set();
         shut = new Set();
@@ -80,12 +80,21 @@ export function defineDirectAgents(tag = "apc-direct-agents") {
             this.render();
         }
         get appName() {
-            return this.name;
+            return this.name ?? this.words.thisApp;
         }
         set appName(next) {
             this.name = next;
             this.render();
         }
+        /** Every string the list shows (TIN-668): the keys you set, over the English defaults. */
+        get strings() {
+            return this.given;
+        }
+        set strings(next) {
+            this.given = next;
+            this.words = resolveStrings(DEFAULT_DIRECT_STRINGS, next);
+            this.render();
+        }
         connectedCallback() {
             if (!document.getElementById(STYLE_ID)) {
                 const style = document.createElement("style");
@@ -104,6 +113,7 @@ export function defineDirectAgents(tag = "apc-direct-agents") {
         render() {
             if (!this.isConnected)
                 return;
+            const w = this.words;
             const rows = this.list.map((a) => {
                 const row = document.createElement("div");
                 row.className = "apc-direct__agent";
@@ -117,14 +127,14 @@ export function defineDirectAgents(tag = "apc-direct-agents") {
                     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";
+                    input.setAttribute("aria-label", w.nameLabel);
+                    input.placeholder = w.namePlaceholder;
                     const save = document.createElement("button");
                     save.type = "submit";
-                    save.textContent = "Save";
+                    save.textContent = w.save;
                     const cancel = document.createElement("button");
                     cancel.type = "button";
-                    cancel.textContent = "Cancel";
+                    cancel.textContent = w.cancel;
                     cancel.addEventListener("click", () => {
                         this.editing = null;
                         this.render();
@@ -149,11 +159,11 @@ export function defineDirectAgents(tag = "apc-direct-agents") {
                     name.textContent = a.name;
                     const status = document.createElement("span");
                     status.className = "apc-direct__status";
-                    status.textContent = directAgentStatus(a);
+                    status.textContent = directAgentStatus(a, w);
                     const rename = document.createElement("button");
                     rename.type = "button";
                     rename.className = "apc-direct__link";
-                    rename.textContent = "Rename";
+                    rename.textContent = w.rename;
                     rename.addEventListener("click", () => {
                         this.editing = a.id;
                         this.draft = a.name;
@@ -163,7 +173,7 @@ export function defineDirectAgents(tag = "apc-direct-agents") {
                     toggle.type = "button";
                     toggle.className = "apc-direct__link";
                     const open = this.isOpen(a);
-                    toggle.textContent = open ? "Hide connection" : "Show connection";
+                    toggle.textContent = open ? w.hideConnection : w.showConnection;
                     toggle.setAttribute("aria-expanded", String(open));
                     toggle.addEventListener("click", () => {
                         if (open) {
@@ -184,11 +194,11 @@ export function defineDirectAgents(tag = "apc-direct-agents") {
                     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.";
+                    urlHint.textContent = w.urlHint;
                     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"));
+                    askHint.textContent = w.askHint;
+                    body.append(urlHint, copyField(a.url, w.copy, w.copied), askHint, copyField(connectPrompt(a.url, this.appName, w), w.copyPrompt, w.copied));
                     row.append(body);
                 }
                 return row;
@@ -196,7 +206,7 @@ export function defineDirectAgents(tag = "apc-direct-agents") {
             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.textContent = this.list.length ? w.addAnother : w.connectAgent;
             add.addEventListener("click", () => this.emit("apc-add"));
             this.replaceChildren(...rows, add);
         }

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export * from "./view.js";
 export * from "./agents-bar.js";
 export * from "./pin-badge.js";
 export * from "./direct-agents.js";
+export * from "./strings.js";

package/dist/index.js

@@ -4,3 +4,4 @@ export * from "./view.js";
 export * from "./agents-bar.js";
 export * from "./pin-badge.js";
 export * from "./direct-agents.js";
+export * from "./strings.js";

package/dist/pin-badge.d.ts

@@ -18,6 +18,7 @@
  * 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.
  */
+import { type PinStrings } from "./strings.js";
 export interface PinAgent {
     /** The app's id for the agent (its grant): what the mark drags as. */
     id: string;
@@ -30,7 +31,7 @@ export interface PinAgent {
 /** 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">): {
+export declare function pinBadgeLabels(a: Pick<PinAgent, "name" | "seen">, given?: Partial<PinStrings> | null): {
     title: string;
     unpin: string;
 };
@@ -42,4 +43,6 @@ export interface ApcPinElement extends HTMLElement {
     readonly mark: HTMLElement | null;
     readonly iconHost: HTMLElement | null;
     renderIcon: ((agent: PinAgent, into: HTMLElement) => void) | null;
+    /** The badge's strings (TIN-668): set the keys you translate; the rest stay English. */
+    strings: Partial<PinStrings> | null;
 }

package/dist/pin-badge.js

@@ -18,6 +18,7 @@
  * 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.
  */
+import { DEFAULT_PIN_STRINGS, resolveStrings } from "./strings.js";
 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; }
@@ -40,11 +41,9 @@ apc-pin.apc-pin--dragging { opacity: 0.35; }
 /** 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`,
-    };
+export function pinBadgeLabels(a, given) {
+    const strings = resolveStrings(DEFAULT_PIN_STRINGS, given);
+    return { title: strings.title(a.name, a.seen), unpin: strings.unpinAria(a.name) };
 }
 /** 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") {
@@ -57,6 +56,17 @@ export function definePinBadge(tag = "apc-pin") {
         iconKey = "";
         stopDim = null;
         draw = null;
+        words = DEFAULT_PIN_STRINGS;
+        given = null;
+        /** Every string the badge shows (TIN-668): the keys you set, over the English defaults. */
+        get strings() {
+            return this.given;
+        }
+        set strings(next) {
+            this.given = next;
+            this.words = resolveStrings(DEFAULT_PIN_STRINGS, next);
+            this.render();
+        }
         /**
          * 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).
@@ -86,7 +96,7 @@ export function definePinBadge(tag = "apc-pin") {
         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"]) {
+            for (const key of ["agent", "renderIcon", "strings"]) {
                 if (!Object.hasOwn(own, key))
                     continue;
                 const value = own[key];
@@ -146,12 +156,12 @@ export function definePinBadge(tag = "apc-pin") {
             if (!this.parts || !a)
                 return;
             const { mark, icon, check, unpin } = this.parts;
-            const labels = pinBadgeLabels(a);
+            const labels = pinBadgeLabels(a, this.words);
             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"}`);
+            mark.setAttribute("aria-label", this.words.markAria(a.name, a.seen));
             check.hidden = !a.seen;
             unpin.setAttribute("aria-label", labels.unpin);
             if (this.draw)

package/dist/pinning.d.ts

@@ -1,4 +1,5 @@
 import { type ApcRole, type FocusTarget } from "@tineira/apc-protocol";
+import { type PinningStrings } from "./strings.js";
 /** How long the page waits for its own apc.json: a held drop never waits longer. */
 export declare const APC_JSON_LOAD_MS = 3000;
 /**
@@ -57,6 +58,12 @@ export interface PinningOptions {
      * A test that sends events of its own passes `() => true`; nothing in a page can reach this.
      */
     trusted?: (event: Event) => boolean;
+    /**
+     * The words enablePinning shows the person (TIN-668): the tap-to-pin note, the answers to a refused
+     * drop, and the note for a dock agent dropped on a Direct-only app (`directOnlyNote`, `couldNotCheckNote`
+     * replace the protocol's English ones). The keys you leave out stay English.
+     */
+    strings?: Partial<PinningStrings>;
 }
 /** 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 {
@@ -67,13 +74,30 @@ export interface DockUnsupported {
     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.
+     * apc.json, so it cannot tell, and it pairs nothing it cannot check. `refused` (TIN-756): the app offers
+     * Dock and answered the drag, then cannot place the drop (its `canTarget` said no, or it does not know the
+     * agent); `connect` is null and the app's handler need not send the person to its connect page.
      */
-    reason: "direct_only" | "unchecked";
+    reason: "direct_only" | "unchecked" | "refused";
     /** `directOnlyNote(name)`, or `couldNotCheckNote(name)`: the app's own words, on its own page. */
     message: string;
 }
-export declare function showDockUnsupported(answer: DockUnsupported): HTMLElement;
+export declare function showDockUnsupported(answer: DockUnsupported, given?: Partial<PinningStrings> | null): HTMLElement;
+/** What the person is told when an app answered a dock agent's drop and then cannot place it (TIN-756). */
+export declare const REFUSED_NOTE: string;
+export declare const UNKNOWN_AGENT_NOTE: string;
+/** How a refused drop is told: through the app's `onDockUnsupported` when it has one, else the page note (TIN-756). */
+export declare function refusalTeller(options: Pick<PinningOptions, "onDockUnsupported" | "direct" | "strings">): (message: string, drag: AgentDrag, target: FocusTarget) => void;
+/**
+ * What an app does with a native drop of a dock agent it answered on dragover (`preventDefault`): pins it, hands an
+ * agent it does not know to `onUnknownAgent`, or says why it did nothing with `tell`. A drop the browser delivered
+ * is never left without a word (TIN-756): the extension stands back from an app that answered the dragover, so a
+ * silent refusal here was a drop with no answer at all.
+ */
+export declare function placeNativeDrop(options: Pick<PinningOptions, "canTarget" | "onPin" | "resolveAgent" | "onUnknownAgent" | "strings">, drag: AgentDrag | null, hit: {
+    element: Element;
+    target: FocusTarget;
+} | null, tell: (message: string, drag: AgentDrag, target: FocusTarget) => void): "pinned" | "unknown_agent" | "refused" | "none";
 /** 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;

package/dist/pinning.js

@@ -1,4 +1,5 @@
-import { APC_JSON_MAX_BYTES, APC_JSON_PATH, couldNotCheckNote, directOnlyNote, parseApcManifest, parseFocusAttrs, urlOnOrigin } from "@tineira/apc-protocol";
+import { APC_JSON_MAX_BYTES, APC_JSON_PATH, parseApcManifest, parseFocusAttrs, urlOnOrigin } from "@tineira/apc-protocol";
+import { DEFAULT_PINNING_STRINGS, resolveStrings } from "./strings.js";
 const profileLoads = new Map();
 /** How long the page waits for its own apc.json: a held drop never waits longer. */
 export const APC_JSON_LOAD_MS = 3000;
@@ -61,7 +62,8 @@ export function loadApcProfiles(origin = location.origin, fetcher = (...a) => fe
  * replaces it: never a stack of notes.
  */
 let shownNote = null;
-export function showDockUnsupported(answer) {
+export function showDockUnsupported(answer, given) {
+    const strings = resolveStrings(DEFAULT_PINNING_STRINGS, given);
     if (shownNote) {
         clearTimeout(shownNote.timer);
         shownNote.box.remove();
@@ -73,20 +75,21 @@ export function showDockUnsupported(answer) {
     Object.assign(box.style, { position: "fixed", zIndex: "2147483647", right: "16px", bottom: "calc(16px + max(var(--apc-bar-height, 0px), env(safe-area-inset-bottom, 0px)))", maxWidth: "340px", padding: "12px 14px", borderRadius: "10px", background: "#1f1f1f", color: "#fff", font: "13px/1.45 system-ui, sans-serif", boxShadow: "0 4px 16px rgba(0,0,0,.25)" });
     const text = document.createElement("p");
     text.textContent = answer.message;
-    Object.assign(text.style, { margin: "0 0 8px" });
-    box.appendChild(text);
     // Only an http(s) page of this app: the same check apc.json's direct.connect passes (no blob:, javascript: or another site).
     const connect = typeof location === "undefined" ? null : urlOnOrigin(answer.connect, location.origin);
+    // Room under the words only when a link follows them.
+    Object.assign(text.style, { margin: connect ? "0 0 8px" : "0" });
+    box.appendChild(text);
     if (connect) {
         const link = document.createElement("a");
         link.setAttribute("href", connect);
-        link.textContent = `Connect an agent to ${answer.name}`;
+        link.textContent = strings.connectLink(answer.name);
         Object.assign(link.style, { color: "#f2a46b", fontWeight: "600" });
         box.appendChild(link);
     }
     const close = document.createElement("button");
     close.setAttribute("type", "button");
-    close.setAttribute("aria-label", "Close");
+    close.setAttribute("aria-label", strings.close);
     close.textContent = "×";
     Object.assign(close.style, { position: "absolute", top: "4px", right: "6px", background: "none", border: "0", color: "#ccc", font: "16px system-ui, sans-serif", cursor: "pointer" });
     const remove = () => {
@@ -102,6 +105,39 @@ export function showDockUnsupported(answer) {
     shownNote = { box, timer: setTimeout(remove, 20_000) };
     return box;
 }
+/** What the person is told when an app answered a dock agent's drop and then cannot place it (TIN-756). */
+export const REFUSED_NOTE = DEFAULT_PINNING_STRINGS.refused;
+export const UNKNOWN_AGENT_NOTE = DEFAULT_PINNING_STRINGS.unknownAgent;
+/** How a refused drop is told: through the app's `onDockUnsupported` when it has one, else the page note (TIN-756). */
+export function refusalTeller(options) {
+    const words = resolveStrings(DEFAULT_PINNING_STRINGS, options.strings);
+    return (message, drag, target) => (options.onDockUnsupported ?? ((answer) => showDockUnsupported(answer, words)))({ drag, target, name: options.direct?.name ?? words.thisApp, connect: null, reason: "refused", message });
+}
+/**
+ * What an app does with a native drop of a dock agent it answered on dragover (`preventDefault`): pins it, hands an
+ * agent it does not know to `onUnknownAgent`, or says why it did nothing with `tell`. A drop the browser delivered
+ * is never left without a word (TIN-756): the extension stands back from an app that answered the dragover, so a
+ * silent refusal here was a drop with no answer at all.
+ */
+export function placeNativeDrop(options, drag, hit, tell) {
+    if (!drag || !hit)
+        return "none";
+    const grantId = options.resolveAgent ? options.resolveAgent(drag.agent) : drag.agent;
+    if (!grantId) {
+        if (drag.hub && drag.ticket && options.onUnknownAgent) {
+            options.onUnknownAgent({ ...drag, hub: drag.hub, ticket: drag.ticket }, hit.target, hit.element);
+            return "unknown_agent";
+        }
+        tell(resolveStrings(DEFAULT_PINNING_STRINGS, options.strings).unknownAgent, drag, hit.target);
+        return "refused";
+    }
+    if (options.canTarget && !options.canTarget(grantId, hit.target)) {
+        tell(resolveStrings(DEFAULT_PINNING_STRINGS, options.strings).refused, drag, hit.target);
+        return "refused";
+    }
+    options.onPin(grantId, hit.target, hit.element);
+    return "pinned";
+}
 /** The drag type a dock puts on an agent: its payload is agentDragPayload(handle), never a secret. */
 export const APC_AGENT_TYPE = "application/x-apc-agent";
 /**
@@ -202,7 +238,7 @@ body.apc-armed [data-focus] { outline: 2px dashed var(--apc-accent, #b85209); ou
 [data-apc-mark][aria-pressed="true"] { outline: 3px solid var(--apc-accent, #b85209); outline-offset: 2px; }
 `;
 /** The note shown while an agent is armed: what to do, and a way out. Fixed above the agent bar (--apc-bar-height). */
-function armedNote(name, onCancel) {
+function armedNote(name, onCancel, words) {
     const box = document.createElement("div");
     box.setAttribute("role", "status");
     box.setAttribute("data-apc-tap-pin", "");
@@ -212,11 +248,11 @@ function armedNote(name, onCancel) {
     const say = (t) => {
         text.textContent = t;
     };
-    say(`Tap what to point ${name} at.`);
+    say(words.tapPrompt(name));
     const cancel = document.createElement("button");
     cancel.setAttribute("type", "button");
     cancel.setAttribute("data-apc-tap-cancel", "");
-    cancel.textContent = "Cancel";
+    cancel.textContent = words.cancel;
     Object.assign(cancel.style, { minHeight: "44px", minWidth: "64px", padding: "0 14px", borderRadius: "10px", border: "1px solid #666", background: "transparent", color: "#fff", font: "600 14px system-ui, sans-serif", cursor: "pointer" });
     cancel.addEventListener("click", onCancel);
     box.append(text, cancel);
@@ -239,6 +275,7 @@ function armedNote(name, onCancel) {
  */
 export function enablePinning(options) {
     const root = options.root ?? document;
+    const words = resolveStrings(DEFAULT_PINNING_STRINGS, options.strings);
     const markSelector = options.markSelector ?? "[data-apc-mark]";
     let drag = null;
     // Tap to pin: the agent armed by a tap on its mark, and the note that says so.
@@ -276,8 +313,8 @@ export function enablePinning(options) {
                     document.head.append(style);
                 }
                 const mark = [...document.querySelectorAll(markSelector)].find((m) => m.getAttribute("data-grant") === armed && !m.closest("apc-pin"));
-                const name = mark?.getAttribute("aria-label") || mark?.getAttribute("title") || "your agent";
-                note = armedNote(name, () => tapPin.cancel());
+                const name = mark?.getAttribute("aria-label") || mark?.getAttribute("title") || words.yourAgent;
+                note = armedNote(name, () => tapPin.cancel(), words);
                 document.body.append(note.box);
                 document.body.classList.add("apc-armed", "apc-dragging");
                 document.documentElement.setAttribute("data-apc-armed", armed);
@@ -310,7 +347,7 @@ export function enablePinning(options) {
             restore.push([el, null]);
             el.setAttribute("tabindex", "0");
         }
-        note?.say("Pointing your agent: Tab to an outlined item, then press Enter or Space to pin it. Escape cancels.");
+        note?.say(words.keyboardArmed);
         targets[0]?.focus();
     };
     const setCurrent = (next) => {
@@ -399,7 +436,7 @@ export function enablePinning(options) {
         swallowClickUntil = Date.now() + 500;
         swallowOn = hit?.element ?? null;
         if (result === "refused")
-            note?.say("This agent cannot point at that. Tap another outlined target, or Cancel.");
+            note?.say(words.refusedTap);
     };
     // Only the click that follows a pinning (or refused) tap is swallowed; every other click goes through.
     const onClickCapture = (event) => {
@@ -498,7 +535,7 @@ export function enablePinning(options) {
         if (fromDock && unread() && typeof given === "function")
             load(given());
         // A dock agent dropped before the app's profiles are known: held until they are, within the
-        // loader's own time limit (loadApcProfiles: 3 s; the ticket lives 60 s).
+        // loader's own time limit (loadApcProfiles: 3 s; the ticket lives 240 s).
         if (fromDock && loading) {
             void ready.then(() => deliver(drag, hit));
             return;
@@ -509,26 +546,17 @@ export function enablePinning(options) {
         // A dock agent on an app that does not offer Dock, or whose profiles could not be read: answered,
         // never sent to pairing (an app that cannot check its own file pairs nothing on a guess).
         if (drag?.hub && drag.ticket && (dockless() || unread())) {
-            const name = options.direct?.name ?? "This app";
+            const name = options.direct?.name ?? words.thisApp;
             const reason = dockless() ? "direct_only" : "unchecked";
-            const answer = { drag, target: hit?.target ?? null, name, connect: options.direct?.connect ?? null, reason, message: reason === "direct_only" ? directOnlyNote(name) : couldNotCheckNote(name) };
-            (options.onDockUnsupported ?? showDockUnsupported)(answer);
+            const answer = { drag, target: hit?.target ?? null, name, connect: options.direct?.connect ?? null, reason, message: reason === "direct_only" ? words.directOnlyNote(name) : words.couldNotCheckNote(name) };
+            (options.onDockUnsupported ?? ((a) => showDockUnsupported(a, words)))(answer);
             return;
         }
         // A drop held while the profiles loaded, on an app that turns out to offer Dock but takes no native drops.
         if (!options.acceptNativeDrops)
             return;
-        if (!drag || !hit)
-            return;
-        const grantId = options.resolveAgent ? options.resolveAgent(drag.agent) : drag.agent;
-        if (!grantId) {
-            if (drag.hub && drag.ticket)
-                options.onUnknownAgent?.({ ...drag, hub: drag.hub, ticket: drag.ticket }, hit.target, hit.element);
-            return;
-        }
-        if (options.canTarget && !options.canTarget(grantId, hit.target))
-            return;
-        options.onPin(grantId, hit.target, hit.element);
+        // Through the app's own handler when it has one (Pulse and Signals show it in their own banners), else the page note.
+        placeNativeDrop(options, drag, hit, refusalTeller(options));
     };
     const onKey = (event) => {
         swallowClickUntil = 0; // a new key press: nothing from before is swallowed
@@ -547,7 +575,7 @@ export function enablePinning(options) {
             swallowClickUntil = Date.now() + 500;
             swallowOn = hit.element;
             if (tapPin.tap(hit) === "refused")
-                note?.say("This agent cannot point at that. Tab to another outlined item, or press Escape.");
+                note?.say(words.refusedKeys);
         }
     };
     root.addEventListener("pointerdown", onDown);

package/dist/strings.d.ts

@@ -0,0 +1,133 @@
+/** What `<apc-agents>` says. Tooltips and `aria-label`s included. */
+export interface BarStrings {
+    /** The bar's own `aria-label` (unless the element has one). */
+    toolbar: string;
+    /** A mark's tooltip: the agent and what to do with it. `connected` is false until it first connects. */
+    markTitle(name: string, connected: boolean): string;
+    /** A pin dot's tooltip. `read`: the agent read the pin; `here`: its target is on this screen. */
+    pinTitle(label: string, read: boolean, here: boolean): string;
+    /** A pin dot's `aria-label`. */
+    pinAria(name: string, label: string, read: boolean): string;
+    /** The × that removes a pin: its `aria-label`. */
+    unpinAria(name: string): string;
+    /** The ⊘ button's tooltip. `both`: the agent is linked, so revoking cuts both its paths. */
+    revokeTitle(name: string, both: boolean): string;
+    /** The ⊘ button's `aria-label`. */
+    revokeAria(name: string): string;
+    /** The ⊘ button's text after the first click. */
+    revokeConfirm: string;
+    /** The armed button's tooltip and `aria-label`. */
+    revokeConfirmTitle(name: string): string;
+    /** The tag of an agent that came directly: text, then tooltip. */
+    pathDirect: string;
+    pathDirectTitle: string;
+    pathDock: string;
+    pathDockTitle: string;
+    /** The tag of an agent linked across both. */
+    pathBoth: string;
+    pathBothTitle: string;
+    /** The Unlink button: text, tooltip and `aria-label`. */
+    unlink: string;
+    unlinkTitle(name: string): string;
+    unlinkAria(name: string): string;
+    /** The ‹ button that collapses the bar: tooltip and `aria-label`. */
+    collapseTitle: string;
+    collapseAria: string;
+    /** The collapsed indicator, long form (tooltip and `aria-label`): who is reading. Names in the order given. */
+    reading(names: readonly string[]): string;
+    /** The same when nobody is. */
+    nobodyReading: string;
+    /** The collapsed indicator's tooltip and `aria-label`: the summary above, then how to open the bar. */
+    showAgents(summary: string): string;
+    /** The collapsed indicator's visible text: "2 reading". Plurals are yours. */
+    readingCount(count: number): string;
+    /** …and when no agent is reading. */
+    nobodyReadingShort: string;
+    /** The dock hint's text (the link). An app can also set `dockHint = { text, url }`, or turn it off with `dockHint = null`. */
+    dockHint: string;
+    /** The hint's × button: `aria-label`. */
+    dockHintDismiss: string;
+    /** Two or more pinned targets of one linked agent as one label: "A and B". Called with the distinct labels. */
+    joinPins(labels: readonly string[]): string;
+}
+export declare const DEFAULT_BAR_STRINGS: BarStrings;
+/** What `<apc-pin>` says. */
+export interface PinStrings {
+    /** The badge's tooltip. */
+    title(name: string, seen: boolean): string;
+    /** The × button's `aria-label`. */
+    unpinAria(name: string): string;
+    /** The mark's `aria-label`. */
+    markAria(name: string, seen: boolean): string;
+}
+export declare const DEFAULT_PIN_STRINGS: PinStrings;
+/** What `<apc-direct-agents>` says, and the prompt it hands the person to paste to their agent. */
+export interface DirectStrings {
+    /** The agent name field: `aria-label` and placeholder. */
+    nameLabel: string;
+    namePlaceholder: string;
+    save: string;
+    cancel: string;
+    rename: string;
+    hideConnection: string;
+    showConnection: string;
+    /** Above the URL, and above the prompt. */
+    urlHint: string;
+    askHint: string;
+    /** The copy buttons, and what the first says for a moment after it copied. */
+    copy: string;
+    copyPrompt: string;
+    copied: string;
+    /** The add button once there is an agent, and before. */
+    addAnother: string;
+    connectAgent: string;
+    /** The app's name in the prompt until `appName` is set. */
+    thisApp: string;
+    /** One agent's status line. */
+    status(agent: {
+        connected: boolean;
+        client?: string | null;
+        linked?: boolean;
+    }): string;
+    /** What the person pastes to their own agent to connect it. */
+    prompt(url: string, appName: string): string;
+}
+export declare const DEFAULT_DIRECT_STRINGS: DirectStrings;
+/** What `enablePinning` shows the person: the tap-to-pin note and the answers to a dock agent's drop. */
+export interface PinningStrings {
+    /** The note while an agent is armed, with the agent's name (from its mark). */
+    tapPrompt(name: string): string;
+    /** The agent's name when its mark has none. */
+    yourAgent: string;
+    /** The note's Cancel button. */
+    cancel: string;
+    /** Armed from the keyboard. */
+    keyboardArmed: string;
+    /** The armed agent may not point there: by tap, and by keyboard. */
+    refusedTap: string;
+    refusedKeys: string;
+    /** A native drop the app cannot place: the agent may not point there, or is not known. */
+    refused: string;
+    unknownAgent: string;
+    /** The app's name in those answers until `direct.name` says it. */
+    thisApp: string;
+    /** The page note for a dock agent dropped on a Direct-only app: the link to the app's connect page, and its × (`aria-label`). */
+    connectLink(appName: string): string;
+    close: string;
+    /** A dock agent dropped on a Direct-only app, and when the page could not check whether it is one. Default: the protocol's notes. */
+    directOnlyNote(appName: string): string;
+    couldNotCheckNote(appName: string): string;
+}
+export declare const DEFAULT_PINNING_STRINGS: PinningStrings;
+/** The defaults with the app's overrides on top. A key set to `undefined` keeps its default. */
+export declare function resolveStrings<T extends object>(defaults: T, given?: Partial<T> | null): T;
+/**
+ * The locale a page's dates and times are shown in: the one the app names, else the page's own
+ * (`<html lang>`), else English. Never the operating system's: a Spanish page on an English machine
+ * reads Spanish dates.
+ */
+export declare function pageLocale(explicit?: string | null): string;
+/** A time or date for the person, in the page's locale (see `pageLocale`). For an app's own labels, such as a pin's "read 12:04". */
+export declare function formatPageTime(value: Date | number | string, options?: Intl.DateTimeFormatOptions & {
+    locale?: string | null;
+}): string;

package/dist/strings.js

@@ -0,0 +1,126 @@
+/**
+ * Every string the package puts in the page (TIN-668), so an app in another language ships it without
+ * a fork. Each component takes one `strings` object (a `Partial` of its type below): the keys you leave
+ * out keep their English default, which is exactly the text the package always showed. A string that
+ * holds a name, a count or a label is a function, so the app decides the word order and the plural
+ * forms: nothing here is joined from English fragments.
+ *
+ * - `<apc-agents>`: `agentBar.strings = { ... }` (type `BarStrings`)
+ * - `<apc-pin>`: `pin.strings = { ... }` (type `PinStrings`)
+ * - `<apc-direct-agents>`: `list.strings = { ... }` (type `DirectStrings`)
+ * - `enablePinning({ strings: { ... } })` (type `PinningStrings`)
+ *
+ * Left as they are, on purpose: the symbols (×, ⊘, ‹, !, ✓), which carry no language; the agents' own
+ * names, labels and URLs, which the app passes in; and the page text an agent reads, which is not this
+ * package's. The note for a dock agent dropped on a Direct-only app is the protocol's `directOnlyNote`;
+ * `PinningStrings.directOnlyNote` replaces it with the app's own words.
+ */
+import { couldNotCheckNote, directOnlyNote } from "@tineira/apc-protocol";
+export const DEFAULT_BAR_STRINGS = {
+    toolbar: "Agents",
+    markTitle: (name, connected) => `${name}${connected ? "" : " (not connected yet)"}. Drag onto anything to point this agent.`,
+    pinTitle: (label, read, here) => `Pinned to ${label}: ${read ? "your agent read it" : "waiting for your agent's next call"}${here ? "" : ". Click to open it."}`,
+    pinAria: (name, label, read) => `${name} pinned to ${label}${read ? ", read" : ", not read yet"}`,
+    unpinAria: (name) => `Remove ${name}'s pin`,
+    revokeTitle: (name, both) => `Revoke ${name}: it can no longer read this app${both ? ", directly or through the dock" : ""}, at once. To let it back, connect or drop it here again.`,
+    revokeAria: (name) => `Revoke ${name}`,
+    revokeConfirm: "Revoke?",
+    revokeConfirmTitle: (name) => `Click again to revoke ${name}.`,
+    pathDirect: "direct",
+    pathDirectTitle: "Connected directly, on this app's own MCP URL",
+    pathDock: "via dock",
+    pathDockTitle: "Came through an agent dock",
+    pathBoth: "direct + dock",
+    pathBothTitle: "The same agent, connected directly and through a dock. Each way keeps its own access; Revoke cuts both.",
+    unlink: "unlink",
+    unlinkTitle: (name) => `Show ${name}'s two connections as two agents again. Nothing else changes.`,
+    unlinkAria: (name) => `Unlink ${name}`,
+    collapseTitle: "Collapse to who is reading. Your agents came through your dock: drag them from there.",
+    collapseAria: "Collapse the agent bar",
+    reading: (names) => (names.length === 1 ? `${names[0]} is reading` : `${names.slice(0, -1).join(", ")} and ${names.at(-1)} are reading`),
+    nobodyReading: "No agent is reading",
+    showAgents: (summary) => `${summary}. Show the agents.`,
+    readingCount: (count) => `${count} reading`,
+    nobodyReadingShort: "no agent reading",
+    dockHint: "Use this agent across apps with the dock",
+    dockHintDismiss: "Dismiss this hint",
+    joinPins: (labels) => labels.join(" and "),
+};
+export const DEFAULT_PIN_STRINGS = {
+    title: (name, seen) => `${name}: ${seen ? "read this pin" : "has not read this pin yet"}. Drag to point it at something else.`,
+    unpinAria: (name) => `Remove ${name}'s pin`,
+    markAria: (name, seen) => `${name}, ${seen ? "has read its pin" : "has not read its pin yet"}`,
+};
+export const DEFAULT_DIRECT_STRINGS = {
+    nameLabel: "Agent name",
+    namePlaceholder: "Empty: back to its own name",
+    save: "Save",
+    cancel: "Cancel",
+    rename: "Rename",
+    hideConnection: "Hide connection",
+    showConnection: "Show connection",
+    urlHint: "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.",
+    askHint: "Don't know how? Paste this to your agent:",
+    copy: "Copy",
+    copyPrompt: "Copy prompt",
+    copied: "Copied",
+    addAnother: "Add another agent",
+    connectAgent: "Connect an agent",
+    thisApp: "this app",
+    status: (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;
+    },
+    prompt: (url, appName) => `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.`,
+};
+export const DEFAULT_PINNING_STRINGS = {
+    tapPrompt: (name) => `Tap what to point ${name} at.`,
+    yourAgent: "your agent",
+    cancel: "Cancel",
+    keyboardArmed: "Pointing your agent: Tab to an outlined item, then press Enter or Space to pin it. Escape cancels.",
+    refusedTap: "This agent cannot point at that. Tap another outlined target, or Cancel.",
+    refusedKeys: "This agent cannot point at that. Tab to another outlined item, or press Escape.",
+    refused: "This agent cannot point at that. Drop it on another highlighted item.",
+    unknownAgent: "This app does not know that agent.",
+    thisApp: "This app",
+    connectLink: (appName) => `Connect an agent to ${appName}`,
+    close: "Close",
+    directOnlyNote,
+    couldNotCheckNote,
+};
+/** The defaults with the app's overrides on top. A key set to `undefined` keeps its default. */
+export function resolveStrings(defaults, given) {
+    const out = { ...defaults };
+    if (given)
+        for (const key of Object.keys(given))
+            if (given[key] !== undefined)
+                out[key] = given[key];
+    return out;
+}
+/**
+ * The locale a page's dates and times are shown in: the one the app names, else the page's own
+ * (`<html lang>`), else English. Never the operating system's: a Spanish page on an English machine
+ * reads Spanish dates.
+ */
+export function pageLocale(explicit) {
+    const lang = explicit || (typeof document === "undefined" ? "" : document.documentElement?.lang);
+    const tag = (lang ?? "").trim();
+    if (!tag)
+        return "en";
+    try {
+        return Intl.getCanonicalLocales(tag)[0] ?? "en";
+    }
+    catch {
+        return "en";
+    }
+}
+/** A time or date for the person, in the page's locale (see `pageLocale`). For an app's own labels, such as a pin's "read 12:04". */
+export function formatPageTime(value, options) {
+    const { locale, ...given } = options ?? {};
+    // No format option at all: a date and a time, in the medium and short styles.
+    const format = Object.keys(given).length ? given : { dateStyle: "medium", timeStyle: "short" };
+    const date = value instanceof Date ? value : new Date(value);
+    return new Intl.DateTimeFormat(pageLocale(locale), format).format(date);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tineira/apc-web",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Agent Pointed Context (APC) for an app's page, in the browser: pinning agents to what the person sees, the agent bar (<apc-agents>), the pin badge, presence and the Direct agents list.",
   "keywords": [
     "apc",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@tineira/apc-protocol": "^0.7.1"
+    "@tineira/apc-protocol": "^0.9.0"
   },
   "scripts": {},
   "types": "./dist/index.d.ts"