visual-comments 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Convex Works
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# visual-comments
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Comments pinned to the elements of any web page or app, like a design tool's
+comments or Vercel's preview comments. People press **C**, click the element
+they mean, and start a thread pinned to it. One self-hosted comment server
+holds the threads of many sites; each site signs its own people in and passes
+their comment requests on through its own server.
+
+This package is the browser library (Svelte 5), the server-side proxy, the
+SvelteKit adapter, the command for coding agents, and the script-tag build. The comment server and full documentation live in the
+[repository](https://github.com/Convex-Works/visual-comments).
+
+```sh
+npm install visual-comments
+```
+
+## Proxy the comment requests
+
+The site's server passes `/_comments/*` on to the comment server with the
+space's secret and the signed-in person:
+
+```ts
+// src/hooks.server.ts
+import { sequence } from '@sveltejs/kit/hooks';
+import { commentsProxy } from 'visual-comments/server';
+
+const comments = commentsProxy({
+	server: 'https://comments.example.com',
+	space: 'my-team',
+	secret: env.COMMENTS_SECRET // the space's secret; never sent to browsers
+});
+
+// After the site's sign-in hook, which sets `event.locals.user`.
+export const handle = sequence(signIn, comments.sveltekit());
+```
+
+Other servers call `comments.handle(request, user)`. See the
+[proxy protocol](https://github.com/Convex-Works/visual-comments/blob/main/docs/PROTOCOL.md).
+
+## Add comments to the page
+
+```ts
+import { createVisualComments } from 'visual-comments';
+
+const comments = createVisualComments({
+	endpoint: '/_comments', // the default
+	auth: '/auth',
+	show: (thread) => canvas.zoomTo(thread.surface) // return true when handled
+});
+```
+
+The library compiles with the host's Svelte (a peer dependency). Its options
+are in the [library reference](https://github.com/Convex-Works/visual-comments/blob/main/docs/LIBRARY.md).
+Pages without a bundler can use the script build instead, served by the
+comment server at `/v1/visual-comments.js` and also shipped here as
+`visual-comments/widget.js`; see the
+[markup reference](https://github.com/Convex-Works/visual-comments/blob/main/docs/MARKUP.md).
+
+## SvelteKit
+
+`visual-comments/sveltekit` sets the comments up from environment variables
+(`VISUAL_COMMENTS_ENABLED`, `_SERVER`, `_SPACE`, `_SECRET`): a hook, a layout
+`load`, and `<Comments>` with a `<Toolbar>` at the bottom of the window. They
+can sign people in on their own, apart from the app's accounts, and the
+`visualComments()` Vite plugin from `visual-comments/vite` leaves them out of
+production builds. See the
+[SvelteKit guide](https://github.com/Convex-Works/visual-comments/blob/main/docs/SVELTEKIT.md).
+
+## Coding agents
+
+The package's `visual-comments` command lets a coding agent join a space:
+`npx visual-comments connect <site>`, then `next` to wait for new comments,
+`reply` and `presence`. See
+[coding agents](https://github.com/Convex-Works/visual-comments/blob/main/docs/CODING-AGENTS.md).
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// The `visual-comments` command, for coding agents: join a site's comment space
+// once a person allows it, wait for new comments, reply, and say what you are
+// doing. It talks only to the site's comments route (`/_comments`), with the
+// agent's token. Node built-ins only, and compiled, because Node does not strip
+// types in node_modules.
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { parseArgs } from 'node:util';
+const DEFAULT_PATH = '/_comments';
+/** The server holds `/agent/next` and the token request up to 50 s; give it room. */
+const LONG_POLL_MS = 80_000;
+const REQUEST_MS = 30_000;
+const MAX_BACKOFF_MS = 30_000;
+const IMAGE_EXTENSIONS = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp' };
+const HELP = {
+    main: `Usage: visual-comments <command> [options]
+
+Lets a coding agent take part in a site's comments. A person allows it once in
+the browser; then it waits for new comments, replies, and shows what it is doing.
+
+Commands:
+  connect <site>     Ask to join the site's comments, and wait for a person to allow it.
+  next               Wait for new comments; print them as JSON.
+  reply <thread>     Reply in a thread, with --body or stdin.
+  presence <state>   Say what you are doing: viewing, working or gone.
+  agents             List the space's agents.
+  disconnect         Leave the space and forget the token.
+
+Options:
+  --site <site>      Which connected site, when there are several. Or set VISUAL_COMMENTS_SITE.
+  -h, --help         Help for a command: visual-comments <command> --help
+
+Tokens are kept in \${XDG_CONFIG_HOME:-~/.config}/visual-comments/agents.json.
+Exit codes: 0 done, 1 error, 2 not connected or the token was rejected.`,
+    connect: `Usage: visual-comments connect <site> [--name <name>] [--path <path>]
+
+Asks to join the site's comments, prints the address where a person allows it
+(and opens it in the browser), waits, then saves the token.
+
+  --name <name>   The name people see on your comments. Default "Agent".
+  --path <path>   Where the site answers comment requests. Default /_comments.
+
+Example: visual-comments connect http://localhost:5173 --name Claude`,
+    next: `Usage: visual-comments next [--site <site>]
+
+Waits, as long as it takes, until a thread has something new for you, then
+prints { site, threads, participants } as JSON and exits. The threads are then
+read for you. Images are downloaded; each gets a "path". Network errors are
+retried. Run it again at once to keep listening.`,
+    reply: `Usage: visual-comments reply <thread> [--body <text>] [--site <site>]
+
+Replies in thread #<thread>. Without --body, the text is read from stdin.
+Prints { thread: { id, url, comment } }.
+
+Example: echo "Done: the table is tighter." | visual-comments reply 12`,
+    presence: `Usage: visual-comments presence <viewing|working|gone> [options]
+
+Says what you are doing, for everyone in the space to see. Each update states
+the whole presence: options left out are cleared.
+
+  --key <key>       One presence per key, to work on several things at once. Default "".
+  --thread <n>      The thread it is about.
+  --surface <id>    The surface (e.g. a frame) it is about.
+  --page <page>     The page it is about.
+  --note <text>     What you are doing, e.g. "Tightening the table".
+  --site <site>     Which connected site.
+
+Example: visual-comments presence working --key 12 --thread 12 --note "Tightening the table"
+         visual-comments presence gone --key 12`,
+    agents: `Usage: visual-comments agents [--site <site>]
+
+Prints the space's agents as JSON: { site, me, agents }.`,
+    disconnect: `Usage: visual-comments disconnect [--site <site>]
+
+Removes you from the space and forgets the token.`
+};
+/** Ends the command with a message and an exit code. */
+class CliError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** A failed request. Status 0 when the site could not be reached. */
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const log = (message) => process.stderr.write(`${message}\n`);
+/** Asked for, so on stdout; usage errors go to stderr. */
+const help = (text) => process.stdout.write(`${text}\n`);
+const print = (value) => process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+function parse(command, args, options) {
+    try {
+        return parseArgs({ args, options: { ...options, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        throw new CliError(1, `${error.message}\n\n${HELP[command]}`);
+    }
+}
+// Sites and saved tokens
+/** A site as typed: `localhost:5173` works too. */
+function siteUrl(site) {
+    const withScheme = /^[a-z][a-z\d+.-]*:\/\//i.test(site)
+        ? site
+        : `${/^(localhost|127\.|\[::1\])/.test(site) ? 'http' : 'https'}://${site}`;
+    try {
+        const url = new URL(withScheme);
+        if (url.protocol === 'http:' || url.protocol === 'https:')
+            return url;
+    }
+    catch { /* below */ }
+    throw new CliError(1, `"${site}" is not a web address.`);
+}
+/** The site, with any path, and where it answers comment requests: `<origin><path>`, which keys the saved token. */
+function locate(site, path = DEFAULT_PATH) {
+    const url = siteUrl(site);
+    const route = `/${path.replace(/^\/+|\/+$/g, '')}`;
+    return { site: `${url.origin}${url.pathname.replace(/\/+$/, '')}`, endpoint: `${url.origin}${route === '/' ? '' : route}` };
+}
+function credentialsFile() {
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'visual-comments', 'agents.json');
+}
+function loadAll() {
+    const file = credentialsFile();
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return {};
+        throw new CliError(1, `${file} cannot be read: ${error.message}`);
+    }
+}
+function saveAll(all) {
+    const file = credentialsFile();
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    // Written whole, then moved over the old file, so a crash never leaves half of it. Only you can read it.
+    const temporary = `${file}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(all, null, '\t')}\n`, { mode: 0o600 });
+    renameSync(temporary, file);
+}
+/** The site the command is for, when it is connected. Set for the hint on a rejected token. */
+let current;
+function connected(site) {
+    const all = loadAll();
+    const endpoints = Object.keys(all);
+    const wanted = site ?? process.env.VISUAL_COMMENTS_SITE;
+    let matches = endpoints;
+    if (wanted) {
+        const url = siteUrl(wanted);
+        const exact = `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+        matches = endpoints.filter((endpoint) => endpoint === exact);
+        if (!matches.length)
+            matches = endpoints.filter((endpoint) => new URL(endpoint).origin === url.origin);
+        if (!matches.length)
+            throw new CliError(2, `Not connected to ${wanted}. Run: visual-comments connect ${wanted}`);
+    }
+    else if (!matches.length) {
+        throw new CliError(2, 'Not connected to any site. Run: visual-comments connect <site>');
+    }
+    if (matches.length > 1) {
+        throw new CliError(1, `Connected to several sites; choose one with --site or VISUAL_COMMENTS_SITE:\n  ${matches.join('\n  ')}`);
+    }
+    const endpoint = matches[0];
+    current = { endpoint, site: new URL(endpoint).origin, saved: all[endpoint] };
+    return current;
+}
+// Requests
+async function call(endpoint, route, init = {}) {
+    const headers = { accept: 'application/json' };
+    if (init.token)
+        headers.authorization = `Bearer ${init.token}`;
+    if (init.body !== undefined)
+        headers['content-type'] = 'application/json';
+    let response;
+    let text;
+    try {
+        response = await fetch(`${endpoint}${route}`, {
+            method: init.method ?? 'GET',
+            headers,
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+            signal: AbortSignal.timeout(init.timeout ?? REQUEST_MS)
+        });
+        text = await response.text();
+    }
+    catch (error) {
+        throw new HttpError(0, `${endpoint} cannot be reached (${reason(error)}).`);
+    }
+    let data;
+    try {
+        data = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        // HTML from the site itself, e.g. a sign-in page: the comments route is elsewhere.
+        const message = `${endpoint}${route} did not answer like a comments route (status ${response.status}). Is --path right?`;
+        throw new HttpError(response.ok ? 404 : response.status, message);
+    }
+    if (!response.ok) {
+        const error = data && typeof data === 'object' && 'error' in data ? data.error : undefined;
+        throw new HttpError(response.status, typeof error === 'string' ? error : `The site answered ${response.status}.`);
+    }
+    return { status: response.status, data: data };
+}
+function reason(error) {
+    if (error instanceof Error && error.name === 'TimeoutError')
+        return 'no answer in time';
+    if (!(error instanceof Error))
+        return String(error);
+    // fetch fails with "fetch failed"; the cause says why, e.g. ECONNREFUSED.
+    const cause = error.cause;
+    if (cause instanceof Error)
+        return 'code' in cause && typeof cause.code === 'string' ? cause.code : cause.message;
+    return error.message;
+}
+/** Worth trying again: the site could not be reached, or had a passing problem. */
+function transient(error) {
+    return error instanceof HttpError && (error.status === 0 || error.status === 408 || error.status === 429 || error.status >= 500);
+}
+function backoff(previous) {
+    return previous ? Math.min(previous * 2, MAX_BACKOFF_MS) : 1000;
+}
+// Commands
+async function connect(args) {
+    const { values, positionals } = parse('connect', args, { name: { type: 'string' }, path: { type: 'string' } });
+    if (values.help)
+        return help(HELP.connect);
+    if (positionals.length !== 1)
+        throw new CliError(1, HELP.connect);
+    const { site, endpoint } = locate(positionals[0], values.path);
+    const name = (values.name ?? 'Agent').trim();
+    if (!name || name.length > 60)
+        throw new CliError(1, 'The name must be 1 to 60 characters.');
+    // Joining again would add a second agent to the space; a saved token that still works is enough.
+    const existing = loadAll()[endpoint];
+    if (existing) {
+        try {
+            const { data } = await call(endpoint, '/agents', { token: existing.token });
+            const agent = data.agents.find((agent) => agent.id === existing.agent.id);
+            if (agent) {
+                log(`Already connected to ${site} as ${agent.name}. To join again, run visual-comments disconnect first.`);
+                return print({ site, agent });
+            }
+        }
+        catch (error) {
+            if (!(error instanceof HttpError && error.status === 401))
+                throw error;
+        }
+    }
+    const { data: request } = await call(endpoint, '/agents/requests', { method: 'POST', body: { name } });
+    const approval = `${site}/#vc-connect=${encodeURIComponent(request.id)}`;
+    log(`To let ${name} join, open\n\n  ${approval}\n\ncheck that it shows the code ${request.code}, and click Allow. Waiting…`);
+    openBrowser(approval);
+    // The server answers 404 once the request expires; this only ends retries against a site that stays down.
+    const deadline = Date.now() + Math.max(request.expiresAt - Date.now(), 0) + 60_000;
+    let delay = 0;
+    while (Date.now() < deadline) {
+        try {
+            const { data } = await call(endpoint, `/agents/requests/${encodeURIComponent(request.id)}/token`, {
+                method: 'POST',
+                body: { secret: request.secret },
+                timeout: LONG_POLL_MS
+            });
+            delay = 0;
+            if ('token' in data) {
+                saveAll({ ...loadAll(), [endpoint]: { token: data.token, agent: data.agent } });
+                log(`Connected to ${site} as ${data.agent.name}, added by ${data.agent.addedBy.name}.`);
+                return print({ site, agent: data.agent });
+            }
+        }
+        catch (error) {
+            if (error instanceof HttpError && error.status === 404)
+                throw new CliError(1, 'The request was denied, or it expired. Run connect again.');
+            if (!transient(error))
+                throw error;
+            delay = backoff(delay);
+            log(`${error.message} Trying again in ${delay / 1000} s.`);
+            await sleep(delay);
+        }
+    }
+    throw new CliError(1, 'The request expired. Run connect again.');
+}
+/** Best effort: the address is printed anyway. */
+function openBrowser(url) {
+    const [command, args] = process.platform === 'darwin' ? ['open', [url]]
+        : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsVerbatimArguments: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch { /* no browser here */ }
+}
+async function next(args) {
+    const { values } = parse('next', args, { site: { type: 'string' } });
+    if (values.help)
+        return help(HELP.next);
+    const { endpoint, site, saved } = connected(values.site);
+    // Each request is short; the loop is what waits, so no proxy times out a request held for hours.
+    let delay = 0;
+    for (;;) {
+        let inbox;
+        try {
+            ({ data: inbox } = await call(endpoint, '/agent/next?wait=50', { token: saved.token, timeout: LONG_POLL_MS }));
+            delay = 0;
+        }
+        catch (error) {
+            if (!transient(error))
+                throw error;
+            delay = backoff(delay);
+            log(`${error.message} Trying again in ${delay / 1000} s.`);
+            await sleep(delay);
+            continue;
+        }
+        if (!inbox.threads.length)
+            continue;
+        // The threads are marked read now, so from here nothing may fail: an image that will not download keeps no path.
+        await downloadImages(endpoint, saved.token, inbox.threads);
+        return print({ site, threads: inbox.threads, participants: inbox.participants });
+    }
+}
+async function downloadImages(endpoint, token, threads) {
+    const host = new URL(endpoint).host;
+    const folder = join(tmpdir(), 'visual-comments', process.platform === 'win32' ? host.replace(/:/g, '_') : host);
+    mkdirSync(folder, { recursive: true });
+    for (const comment of threads.flatMap((thread) => thread.comments)) {
+        for (const image of comment.images) {
+            const name = `${image.id}-${image.key}`;
+            // An image's address never changes, so one downloaded before is the same image.
+            const known = Object.values(IMAGE_EXTENSIONS).map((extension) => join(folder, `${name}.${extension}`)).find((path) => existsSync(path));
+            if (known) {
+                image.path = known;
+                continue;
+            }
+            try {
+                image.path = await downloadImage(`${endpoint}/images/${image.id}/${encodeURIComponent(image.key)}`, token, join(folder, name));
+            }
+            catch (error) {
+                log(`Image ${image.id} could not be downloaded: ${error.message}`);
+            }
+        }
+    }
+}
+async function downloadImage(url, token, base) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            const response = await fetch(url, { headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(REQUEST_MS) });
+            if (!response.ok)
+                throw new HttpError(response.status, `the site answered ${response.status}`);
+            const type = response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() ?? '';
+            const path = `${base}.${IMAGE_EXTENSIONS[type] ?? 'bin'}`;
+            writeFileSync(path, new Uint8Array(await response.arrayBuffer()));
+            return path;
+        }
+        catch (error) {
+            const failure = error instanceof HttpError ? error : new HttpError(0, reason(error));
+            if (attempt >= 3 || !transient(failure))
+                throw failure;
+            await sleep(1000 * attempt);
+        }
+    }
+}
+async function reply(args) {
+    const { values, positionals } = parse('reply', args, { body: { type: 'string' }, site: { type: 'string' } });
+    if (values.help)
+        return help(HELP.reply);
+    if (positionals.length !== 1 || !/^\d+$/.test(positionals[0].replace(/^#/, '')))
+        throw new CliError(1, HELP.reply);
+    const number = Number(positionals[0].replace(/^#/, ''));
+    const { endpoint, saved } = connected(values.site);
+    const body = (values.body ?? (process.stdin.isTTY ? '' : await readStdin())).trim();
+    if (!body)
+        throw new CliError(1, 'The reply is empty. Pass --body, or the text on stdin.');
+    const { data } = await call(endpoint, `/threads/${number}/comments`, { method: 'POST', token: saved.token, body: { body } });
+    print({ thread: { id: data.thread.id, url: data.thread.url, comment: data.thread.comments.at(-1)?.id } });
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function presence(args) {
+    const { values, positionals } = parse('presence', args, {
+        key: { type: 'string' },
+        thread: { type: 'string' },
+        surface: { type: 'string' },
+        page: { type: 'string' },
+        note: { type: 'string' },
+        site: { type: 'string' }
+    });
+    if (values.help)
+        return help(HELP.presence);
+    const state = positionals[0];
+    if (positionals.length !== 1 || (state !== 'viewing' && state !== 'working' && state !== 'gone'))
+        throw new CliError(1, HELP.presence);
+    const update = { state };
+    if (values.key !== undefined)
+        update.key = values.key;
+    if (values.thread !== undefined) {
+        const thread = Number(values.thread.replace(/^#/, ''));
+        if (!Number.isInteger(thread) || thread < 1)
+            throw new CliError(1, '--thread must be a thread number.');
+        update.thread = thread;
+    }
+    if (values.surface !== undefined)
+        update.surface = values.surface;
+    if (values.page !== undefined)
+        update.page = values.page;
+    if (values.note !== undefined)
+        update.note = values.note;
+    const { endpoint, saved } = connected(values.site);
+    await call(endpoint, '/presence', { method: 'POST', token: saved.token, body: update });
+}
+async function agents(args) {
+    const { values } = parse('agents', args, { site: { type: 'string' } });
+    if (values.help)
+        return help(HELP.agents);
+    const { endpoint, site, saved } = connected(values.site);
+    const { data } = await call(endpoint, '/agents', { token: saved.token });
+    print({ site, me: saved.agent.id, agents: data.agents });
+}
+async function disconnect(args) {
+    const { values } = parse('disconnect', args, { site: { type: 'string' } });
+    if (values.help)
+        return help(HELP.disconnect);
+    const { endpoint, site, saved } = connected(values.site);
+    try {
+        await call(endpoint, `/agents/${encodeURIComponent(saved.agent.id)}`, { method: 'DELETE', token: saved.token });
+    }
+    catch (error) {
+        // Already removed by a person, or expired: forgetting the token is all that is left.
+        if (!(error instanceof HttpError && error.status === 401))
+            throw error;
+    }
+    const all = loadAll();
+    delete all[endpoint];
+    saveAll(all);
+    log(`Disconnected from ${site}.`);
+    print({ deleted: saved.agent.id });
+}
+const COMMANDS = { connect, next, reply, presence, agents, disconnect };
+async function main(argv) {
+    const [command, ...args] = argv;
+    if (!command || command === '-h' || command === '--help' || command === 'help') {
+        help(HELP.main);
+        return;
+    }
+    const run = COMMANDS[command];
+    if (!run)
+        throw new CliError(1, `Unknown command "${command}".\n\n${HELP.main}`);
+    await run(args);
+}
+main(process.argv.slice(2)).catch((error) => {
+    if (error instanceof CliError) {
+        log(error.message);
+        process.exitCode = error.code;
+    }
+    else if (error instanceof HttpError && error.status === 401 && current) {
+        log(`${error.message} Run: visual-comments connect ${current.site}`);
+        process.exitCode = 2;
+    }
+    else {
+        log(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+});

package/dist/core/aim.d.ts

@@ -0,0 +1,21 @@
+import { type CommentTarget } from './target.js';
+import { type Surface } from './surfaces.js';
+import type { Box } from './target.js';
+/** Where the pointer is aiming in comment mode. */
+export interface Aim {
+    surface: string;
+    /** Where a pin would go, in surface pixels: the pointer, moved onto the target if it is pulled to one. */
+    x: number;
+    y: number;
+    /** The pointer itself, in surface pixels. */
+    point: {
+        x: number;
+        y: number;
+    };
+    /** In the surface's document. */
+    target?: CommentTarget;
+    /** The target's box in surface pixels when it was aimed at. */
+    targetBox?: Box;
+}
+/** Where a pin goes for a pointer at a client point. With `free`, or without a document, it stays at the pointer. */
+export declare function aimAt(surface: Surface, x: number, y: number, free: boolean): Aim;

package/dist/core/aim.js

@@ -0,0 +1,21 @@
+import { clamp, MAGNET, targetAt } from './target.js';
+import { clientToDoc, docBoxToSurface, fromClient } from './surfaces.js';
+/** Where a pin goes for a pointer at a client point. With `free`, or without a document, it stays at the pointer. */
+export function aimAt(surface, x, y, free) {
+    const point = fromClient(surface, x, y);
+    const plain = { surface: surface.id, x: point.x, y: point.y, point };
+    if (free || !surface.doc)
+        return plain;
+    const d = clientToDoc(surface, x, y);
+    const target = targetAt(surface.doc, d.x, d.y, MAGNET / surface.docScale, surface.search);
+    if (!target)
+        return plain;
+    const box = docBoxToSurface(surface, target.box);
+    return {
+        ...plain,
+        x: clamp(point.x, box.x + 1, box.x + box.width - 1),
+        y: clamp(point.y, box.y + 1, box.y + box.height - 1),
+        target,
+        targetBox: box
+    };
+}

package/dist/core/api.d.ts

@@ -0,0 +1,5 @@
+export declare class Api {
+    readonly endpoint: string;
+    constructor(endpoint: string);
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+}

package/dist/core/api.js

@@ -0,0 +1,11 @@
+// The comments on the site's own server, which passes requests on to the
+// comment server with the space's secret and the person signed in on the site.
+export class Api {
+    endpoint;
+    constructor(endpoint) {
+        this.endpoint = endpoint.replace(/\/$/, '');
+    }
+    fetch(path, init = {}) {
+        return fetch(`${this.endpoint}${path}`, { ...init, credentials: 'same-origin', cache: 'no-store' });
+    }
+}

package/dist/core/metaball.d.ts

@@ -0,0 +1,15 @@
+/** A rounded box in pixels. */
+export interface RoundedBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    radius: number;
+}
+/**
+ * The bridge from a dot of radius `r` at `x`, `y` to the nearest edge of a
+ * box, as between two metaballs about to part: wide where it meets each,
+ * pinched between, and thinner the farther it stretches. Undefined when the
+ * dot touches or is inside the box, or is beyond `reach` from it.
+ */
+export declare function neck(x: number, y: number, r: number, box: RoundedBox, reach: number): string | undefined;