visual-comments 0.0.0-stage → 0.1.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,61 @@
-# 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, 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).
+
+## License
+
+MIT

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;

package/dist/core/metaball.js

@@ -0,0 +1,42 @@
+/**
+ * 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 function neck(x, y, r, box, reach) {
+    const corner = Math.min(box.radius, box.width / 2, box.height / 2);
+    // The nearest point on a rounded box: clamp to the box shrunk by its corner, then step out by the corner.
+    const cx = clamp(x, box.left + corner, box.left + box.width - corner);
+    const cy = clamp(y, box.top + corner, box.top + box.height - corner);
+    const away = Math.hypot(x - cx, y - cy);
+    const gap = away - corner;
+    if (gap <= r || gap > reach)
+        return undefined;
+    const ux = (cx - x) / away;
+    const uy = (cy - y) / away;
+    const nx = -uy;
+    const ny = ux;
+    // Sink the foot into the outline's stroke so the two read as one shape.
+    const qx = cx - ux * (corner - 1);
+    const qy = cy - uy * (corner - 1);
+    const stretch = Math.min(1, (gap - r) / Math.max(reach - r, 1));
+    const start = r * 0.85;
+    const foot = r * (1.8 - 0.8 * stretch);
+    const waist = Math.max(0.6, r * (0.55 - 0.35 * stretch));
+    // A quadratic's middle sits at (start + foot) / 4 + control / 2; solve for the waist.
+    const control = 2 * waist - (start + foot) / 2;
+    const ax = x + ux * r * 0.3;
+    const ay = y + uy * r * 0.3;
+    const mx = (ax + qx) / 2;
+    const my = (ay + qy) / 2;
+    const point = (px, py, side, width) => `${(px + nx * side * width).toFixed(2)} ${(py + ny * side * width).toFixed(2)}`;
+    return [
+        `M ${point(ax, ay, 1, start)}`,
+        `Q ${point(mx, my, 1, control)} ${point(qx, qy, 1, foot)}`,
+        `L ${point(qx, qy, -1, foot)}`,
+        `Q ${point(mx, my, -1, control)} ${point(ax, ay, -1, start)}`,
+        'Z'
+    ].join(' ');
+}
+const clamp = (value, min, max) => Math.min(Math.max(value, min), Math.max(min, max));

package/dist/core/surfaces.d.ts

@@ -0,0 +1,95 @@
+import { type Box, type Search } from './target.js';
+import type { CommentThread } from '../shared/types.js';
+export interface Rect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export interface Surface {
+    /** '' for the page. */
+    id: string;
+    title: string;
+    /** Null for the page. */
+    element: Element | null;
+    /** Where its elements are found, if that document can be read. */
+    doc?: Document;
+    /** Surface pixels to client pixels: client = origin + surface × scale. */
+    origin: {
+        x: number;
+        y: number;
+    };
+    scale: number;
+    /** In surface pixels. */
+    size: {
+        width: number;
+        height: number;
+    };
+    /** The visible part of the surface, in client pixels. */
+    clip: Rect;
+    /** The visible part of what holds it, in client pixels: where its cards can go. */
+    stage: Rect;
+    /** The document's client pixels to the host's: client = docOrigin + doc × docScale. */
+    docOrigin: {
+        x: number;
+        y: number;
+    };
+    docScale: number;
+    /** Where targets are looked for in the document. */
+    search: Search;
+    /** A frame that takes pointer events itself, so comment mode needs a layer over it to catch them. */
+    catches: boolean;
+    /** The host keeps its own drag and pan gestures over this surface in comment mode. */
+    passGestures: boolean;
+    /** From `data-vc-context`. */
+    context: Record<string, string>;
+}
+export interface DiscoverOptions {
+    /** Whether an element belongs to the comment UI. */
+    ours: (element: Element) => boolean;
+    documentOf?: (surface: Element, frame: HTMLIFrameElement) => Document | undefined;
+}
+/** The surfaces on the page now, outermost first. */
+export declare function discover(doc: Document, options: DiscoverOptions): Surface[];
+/** A same-origin frame's document once it has loaded, or undefined. */
+export declare function frameDocument(_surface: Element, frame: HTMLIFrameElement): Document | undefined;
+/** The surface under a client point, if a comment can go there. */
+export declare function surfaceAt(surfaces: Surface[], doc: Document, x: number, y: number, ours: (element: Element) => boolean): Surface | undefined;
+export declare const toClient: (s: Surface, x: number, y: number) => {
+    x: number;
+    y: number;
+};
+export declare const fromClient: (s: Surface, x: number, y: number) => {
+    x: number;
+    y: number;
+};
+export declare const docToClient: (s: Surface, x: number, y: number) => {
+    x: number;
+    y: number;
+};
+export declare const clientToDoc: (s: Surface, x: number, y: number) => {
+    x: number;
+    y: number;
+};
+/** A box in the surface's document, in client pixels. */
+export declare function docBoxToClient(s: Surface, b: Box): Rect;
+/** A box in the surface's document, in surface pixels. */
+export declare function docBoxToSurface(s: Surface, b: Box): Box;
+export interface Spot {
+    /** The pin, in client pixels. */
+    x: number;
+    y: number;
+    /** The element under it, if found, and its box in client pixels. */
+    element?: Element;
+    box?: Rect;
+    /** Out of view, or its element is gone. */
+    hidden: boolean;
+}
+/**
+ * Where a thread's pin is now. A pin on an element moves with it, at the same
+ * share of its width and height, and hides while it is out of view or gone; a
+ * free pin, or one whose document cannot be read, stays where it was placed.
+ */
+export declare function spotOf(s: Surface, thread: Pick<CommentThread, 'x' | 'y' | 'anchor'>): Spot;
+export declare function inside(r: Rect, x: number, y: number): boolean;
+export declare function intersect(a: Rect, b: Rect): Rect;

package/dist/core/surfaces.js

@@ -0,0 +1,197 @@
+// Surfaces: the parts of a page that take comments. Without any declared
+// surface, the page itself is one. A host declares surfaces in markup:
+//
+//   <div data-vc-surface="inbox" data-vc-title="Inbox">        part of the page
+//   <iframe data-vc-surface="inbox" data-vc-title="Inbox">      a frame
+//   <div data-vc-surface="inbox"> … <iframe data-vc-frame> …     a box holding a frame
+//
+// Each surface has its own pixels, from its top-left corner, so pins stay put
+// however the host zooms, pans or scrolls it: the scale and position come from
+// measuring the element on screen against its layout size. The page's pixels
+// are the document's, so pins scroll with it. Elements are found in the
+// surface's document: the host page, or a same-origin frame's own document.
+import { elementsAt, findAnchor, shows, clamp } from './target.js';
+/** The surfaces on the page now, outermost first. */
+export function discover(doc, options) {
+    const view = doc.defaultView;
+    const elements = [...doc.querySelectorAll('[data-vc-surface]')];
+    const viewport = { left: 0, top: 0, right: doc.documentElement.clientWidth, bottom: doc.documentElement.clientHeight };
+    const skip = (element) => options.ours(element) || Boolean(element.closest('[data-vc-ignore]'));
+    if (!elements.length) {
+        const root = doc.scrollingElement ?? doc.documentElement;
+        return [{
+                id: '',
+                title: doc.title,
+                element: null,
+                doc,
+                origin: { x: -view.scrollX, y: -view.scrollY },
+                scale: 1,
+                size: { width: root.scrollWidth, height: root.scrollHeight },
+                clip: viewport,
+                stage: viewport,
+                docOrigin: { x: 0, y: 0 },
+                docScale: 1,
+                search: { region: box(viewport), skip },
+                catches: false,
+                passGestures: false,
+                context: {}
+            }];
+    }
+    const styles = new Map();
+    const style = (element) => {
+        let value = styles.get(element);
+        if (!value)
+            styles.set(element, (value = view.getComputedStyle(element)));
+        return value;
+    };
+    const surfaces = [];
+    for (const element of elements) {
+        const rect = element.getBoundingClientRect();
+        if (rect.width < 1 || rect.height < 1)
+            continue;
+        const html = element;
+        const layoutWidth = html.offsetWidth || rect.width;
+        const scale = rect.width / layoutWidth;
+        const stage = intersect(viewport, clipOf(element, style));
+        const frame = (element.localName === 'iframe' ? element : element.querySelector('iframe[data-vc-frame]'));
+        const surface = {
+            id: element.getAttribute('data-vc-surface') ?? '',
+            title: element.getAttribute('data-vc-title') ?? frame?.title ?? element.getAttribute('aria-label') ?? '',
+            element,
+            origin: { x: rect.left + html.clientLeft * scale, y: rect.top + html.clientTop * scale },
+            scale,
+            size: { width: html.clientWidth || layoutWidth, height: html.clientHeight || html.offsetHeight || rect.height / scale },
+            clip: intersect(stage, { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom }),
+            stage,
+            docOrigin: { x: 0, y: 0 },
+            docScale: 1,
+            search: { region: { x: 0, y: 0, width: 0, height: 0 }, skip },
+            catches: false,
+            passGestures: Boolean(element.closest('[data-vc-gestures="host"]')),
+            context: contextOf(element)
+        };
+        if (frame) {
+            const doc = (options.documentOf ?? frameDocument)(element, frame);
+            const r = frame.getBoundingClientRect();
+            const docScale = frame.offsetWidth ? r.width / frame.offsetWidth : scale;
+            surface.doc = doc;
+            surface.docOrigin = { x: r.left + frame.clientLeft * docScale, y: r.top + frame.clientTop * docScale };
+            surface.docScale = docScale;
+            surface.search = { region: { x: 0, y: 0, width: frame.clientWidth, height: frame.clientHeight }, skip };
+            surface.catches = style(frame).pointerEvents !== 'none';
+        }
+        else {
+            surface.doc = doc;
+            surface.search = { region: box(surface.clip), within: element, skip };
+        }
+        surfaces.push(surface);
+    }
+    return surfaces;
+}
+/** A same-origin frame's document once it has loaded, or undefined. */
+export function frameDocument(_surface, frame) {
+    try {
+        const doc = frame.contentDocument;
+        if (!doc || doc.readyState === 'loading' || doc.URL === 'about:blank')
+            return undefined;
+        return doc;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The surface under a client point, if a comment can go there. */
+export function surfaceAt(surfaces, doc, x, y, ours) {
+    const top = elementsAt(doc, x, y, ours)[0];
+    if (!top || top.closest('[data-vc-ignore]'))
+        return undefined;
+    let found;
+    for (const surface of surfaces) {
+        if (!inside(surface.clip, x, y))
+            continue;
+        if (surface.element && !(surface.element === top || surface.element.contains(top)))
+            continue;
+        // The innermost of nested surfaces.
+        if (!found || (found.element && surface.element && found.element.contains(surface.element)))
+            found = surface;
+    }
+    return found;
+}
+export const toClient = (s, x, y) => ({ x: s.origin.x + x * s.scale, y: s.origin.y + y * s.scale });
+export const fromClient = (s, x, y) => ({ x: (x - s.origin.x) / s.scale, y: (y - s.origin.y) / s.scale });
+export const docToClient = (s, x, y) => ({ x: s.docOrigin.x + x * s.docScale, y: s.docOrigin.y + y * s.docScale });
+export const clientToDoc = (s, x, y) => ({ x: (x - s.docOrigin.x) / s.docScale, y: (y - s.docOrigin.y) / s.docScale });
+/** A box in the surface's document, in client pixels. */
+export function docBoxToClient(s, b) {
+    const a = docToClient(s, b.x, b.y);
+    return { left: a.x, top: a.y, right: a.x + b.width * s.docScale, bottom: a.y + b.height * s.docScale };
+}
+/** A box in the surface's document, in surface pixels. */
+export function docBoxToSurface(s, b) {
+    const a = docToClient(s, b.x, b.y);
+    const p = fromClient(s, a.x, a.y);
+    const k = s.docScale / s.scale;
+    return { x: p.x, y: p.y, width: b.width * k, height: b.height * k };
+}
+/**
+ * Where a thread's pin is now. A pin on an element moves with it, at the same
+ * share of its width and height, and hides while it is out of view or gone; a
+ * free pin, or one whose document cannot be read, stays where it was placed.
+ */
+export function spotOf(s, thread) {
+    const free = () => {
+        const c = toClient(s, Math.min(thread.x, s.size.width), Math.min(thread.y, s.size.height));
+        return { ...c, hidden: !inside(s.clip, c.x, c.y) };
+    };
+    const { anchor } = thread;
+    if (!anchor || !s.doc)
+        return free();
+    const element = findAnchor(s.doc, anchor);
+    if (!element)
+        return { ...free(), hidden: true };
+    const r = element.getBoundingClientRect();
+    const b = docBoxToSurface(s, { x: r.left, y: r.top, width: r.width, height: r.height });
+    const share = (offset, size) => (size > 0 ? offset / size : 0);
+    const x = b.x + clamp(share(thread.x - anchor.x, anchor.width) * b.width, 1, b.width - 1);
+    const y = b.y + clamp(share(thread.y - anchor.y, anchor.height) * b.height, 1, b.height - 1);
+    const c = toClient(s, x, y);
+    const d = clientToDoc(s, c.x, c.y);
+    const box = docBoxToClient(s, { x: r.left, y: r.top, width: r.width, height: r.height });
+    const visible = r.width > 0 && r.height > 0 && inside(s.clip, c.x, c.y) && shows(element, d.x, d.y, s.search);
+    return { x: c.x, y: c.y, element, box, hidden: !visible };
+}
+export function inside(r, x, y) {
+    return x >= r.left && x <= r.right && y >= r.top && y <= r.bottom;
+}
+export function intersect(a, b) {
+    return { left: Math.max(a.left, b.left), top: Math.max(a.top, b.top), right: Math.min(a.right, b.right), bottom: Math.min(a.bottom, b.bottom) };
+}
+const box = (r) => ({ x: r.left, y: r.top, width: Math.max(0, r.right - r.left), height: Math.max(0, r.bottom - r.top) });
+/** What clips an element: every ancestor that does not let its overflow show. */
+function clipOf(element, style) {
+    let clip = { left: -Infinity, top: -Infinity, right: Infinity, bottom: Infinity };
+    const body = element.ownerDocument.body;
+    for (let node = element.parentElement; node && node !== body; node = node.parentElement) {
+        const s = style(node);
+        if (s.overflowX === 'visible' && s.overflowY === 'visible')
+            continue;
+        const r = node.getBoundingClientRect();
+        clip = intersect(clip, { left: r.left, top: r.top, right: r.right, bottom: r.bottom });
+    }
+    return clip;
+}
+function contextOf(element) {
+    const raw = element.getAttribute('data-vc-context');
+    if (!raw)
+        return {};
+    try {
+        const value = JSON.parse(raw);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return {};
+        return Object.fromEntries(Object.entries(value).filter(([, v]) => typeof v === 'string' || typeof v === 'number')
+            .map(([k, v]) => [k, String(v)]));
+    }
+    catch {
+        return {};
+    }
+}

package/dist/core/target.d.ts

@@ -0,0 +1,59 @@
+/** A box in a document's client pixels. */
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** An element a pin can attach to. */
+export interface CommentTarget {
+    element: Element;
+    box: Box;
+    /** Corner radius in document pixels, so the highlight takes the element's shape. */
+    radius: number;
+    /** What it is and what it says, e.g. `button “Add prompts”`. */
+    label: string;
+}
+/** Where to look, and what to pass over. */
+export interface Search {
+    /** The part of the document that takes comments: a frame's viewport, or a surface's box. */
+    region: Box;
+    /** Only elements inside this one, for a surface that is part of a page. */
+    within?: Element;
+    /** Elements that are never targets, with what they contain: the comment UI, host chrome. */
+    skip: (element: Element) => boolean;
+}
+/** How far the pull reaches, in screen pixels. */
+export declare const MAGNET = 14;
+/** The elements at a point, top first, without skipped ones. */
+export declare function elementsAt(doc: Document, x: number, y: number, skip: Search['skip']): Element[];
+/**
+ * The element nearest the point, or undefined for open space. Under the
+ * pointer, the innermost meaningful element wins. A smaller one within
+ * `radius` pulls the pointer onto it, as long as it sits inside that element.
+ */
+export declare function targetAt(doc: Document, x: number, y: number, radius: number, search: Search): CommentTarget | undefined;
+/** The meaningful element around this one, for when the pin meant more than it caught. */
+export declare function widen(target: CommentTarget, search: Search): CommentTarget | undefined;
+/** The element an anchor names in a document, if it is still there and still says the same. */
+export declare function findAnchor(doc: Document, anchor: {
+    selector: string;
+    text: string;
+}): Element | undefined;
+/**
+ * Whether the point of the element shows: inside the region, not clipped by a
+ * scrolling container, and not covered (a sticky header).
+ */
+export declare function shows(element: Element, x: number, y: number, search: Search): boolean;
+/** Scrolls the document's containers until the element is in the middle of them. */
+export declare function reveal(element: Element): void;
+/** The scrolling container from this element up that can still scroll, to pass wheel turns to. */
+export declare function scrollerFrom(start: Element | null, dx: number, dy: number): Element | undefined;
+/** What a thread stores about its target: a selector, its label and text. */
+export declare function describeTarget(target: CommentTarget): {
+    selector: string;
+    label: string;
+    text: string;
+};
+export declare const clamp: (value: number, min: number, max: number) => number;
+export declare const shorten: (text: string, max: number) => string;