visual-comments 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,6 @@
+export { VisualComments, pageOf } from './visual-comments.svelte.js';
+import { VisualComments } from './visual-comments.svelte.js';
+/** Adds comments to the page. Call once, in the browser. */
+export function createVisualComments(options, doc) {
+    return new VisualComments(options, doc);
+}

package/dist/server/index.d.ts

@@ -0,0 +1,33 @@
+export interface CommentsProxyOptions {
+    /** The comment server, e.g. `https://comments.convex.works`. */
+    server: string;
+    /** The site's space on it. */
+    space: string;
+    /** The space's secret. Keep it on the server. */
+    secret: string;
+    /** Where the browser reaches the comments on this site. Default `/_comments`. */
+    path?: string;
+}
+/** The person signed in on the site, as its sign-in knows them. Null or undefined when nobody is. */
+export type CommentsUser = {
+    sub: string;
+    name: string;
+    email?: string;
+    picture?: string;
+} | null | undefined;
+/** Matches SvelteKit's `Handle` without depending on SvelteKit. */
+export type Handle<E extends {
+    request: Request;
+    locals: object;
+}> = (input: {
+    event: E;
+    resolve: (event: E) => Response | Promise<Response>;
+}) => Promise<Response>;
+export declare function commentsProxy(options: CommentsProxyOptions): {
+    path: string;
+    handle: (request: Request, user: CommentsUser) => Promise<Response | undefined>;
+    sveltekit: <E extends {
+        request: Request;
+        locals: object;
+    }>(user?: (event: E) => CommentsUser | Promise<CommentsUser>) => Handle<E>;
+};

package/dist/server/index.js

@@ -0,0 +1,67 @@
+// For the site's server: passes the browser's comment requests on to the
+// comment server, with the space's secret and the person signed in on the site.
+// Uses only the Fetch API, so it runs in Node, Bun, Deno and Workers.
+import { USER_HEADER } from '../shared/protocol.js';
+const REQUEST_HEADERS = ['content-type', 'accept', 'last-event-id'];
+const RESPONSE_HEADERS = ['content-type', 'cache-control', 'content-security-policy', 'x-content-type-options', 'x-accel-buffering'];
+export function commentsProxy(options) {
+    const server = options.server.replace(/\/$/, '');
+    const path = (options.path ?? '/_comments').replace(/\/$/, '');
+    const space = encodeURIComponent(options.space);
+    /** Answers requests under `path`; undefined for any other request. */
+    async function handle(request, user) {
+        const url = new URL(request.url);
+        if (url.pathname !== path && !url.pathname.startsWith(`${path}/`))
+            return undefined;
+        const headers = new Headers({ Authorization: `Bearer ${options.secret}` });
+        for (const name of REQUEST_HEADERS) {
+            const value = request.headers.get(name);
+            if (value)
+                headers.set(name, value);
+        }
+        if (user) {
+            const { sub, name, email, picture } = user;
+            headers.set(USER_HEADER, base64url(JSON.stringify({ sub, name, email, picture })));
+        }
+        const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+        let response;
+        try {
+            response = await fetch(`${server}/v1/spaces/${space}${url.pathname.slice(path.length)}${url.search}`, {
+                method: request.method,
+                headers,
+                body: hasBody ? await request.arrayBuffer() : undefined,
+                signal: request.signal,
+                redirect: 'manual'
+            });
+        }
+        catch {
+            return Response.json({ error: 'The comments cannot be reached. Try again.' }, { status: 502, headers: { 'Cache-Control': 'no-store' } });
+        }
+        const out = new Headers();
+        for (const name of RESPONSE_HEADERS) {
+            const value = response.headers.get(name);
+            if (value)
+                out.set(name, value);
+        }
+        return new Response(response.body, { status: response.status, headers: out });
+    }
+    /**
+     * SvelteKit's `handle` hook. Put it after the sign-in's hook; by default the
+     * user is `event.locals.user`.
+     */
+    function sveltekit(user = (event) => event.locals.user) {
+        return async ({ event, resolve }) => {
+            const url = new URL(event.request.url);
+            if (url.pathname !== path && !url.pathname.startsWith(`${path}/`))
+                return resolve(event);
+            return (await handle(event.request, await user(event)));
+        };
+    }
+    return { path, handle, sveltekit };
+}
+function base64url(text) {
+    let binary = '';
+    for (const byte of new TextEncoder().encode(text))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}

package/dist/shared/limits.d.ts

@@ -0,0 +1,9 @@
+/** Per image. A proxy in front of the server must allow request bodies this large. */
+export declare const MAX_IMAGE_BYTES: number;
+export declare const MAX_IMAGES = 6;
+/** No SVG: it can carry script. */
+export declare const IMAGE_TYPES: string[];
+export declare const MAX_BODY = 5000;
+/** Context entries a thread keeps, and the length of each value. */
+export declare const MAX_CONTEXT = 20;
+export declare const MAX_CONTEXT_VALUE = 200;

package/dist/shared/limits.js

@@ -0,0 +1,10 @@
+// Limits shared by the browser and the server.
+/** Per image. A proxy in front of the server must allow request bodies this large. */
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+export const MAX_IMAGES = 6;
+/** No SVG: it can carry script. */
+export const IMAGE_TYPES = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'];
+export const MAX_BODY = 5000;
+/** Context entries a thread keeps, and the length of each value. */
+export const MAX_CONTEXT = 20;
+export const MAX_CONTEXT_VALUE = 200;

package/dist/shared/protocol.d.ts

@@ -0,0 +1,2 @@
+/** The header with who is signed in on the site: their `Viewer` as base64url-encoded JSON. */
+export declare const USER_HEADER = "visual-comments-user";

package/dist/shared/protocol.js

@@ -0,0 +1,3 @@
+// How a site's server talks to the comment server.
+/** The header with who is signed in on the site: their `Viewer` as base64url-encoded JSON. */
+export const USER_HEADER = 'visual-comments-user';

package/dist/shared/types.d.ts

@@ -0,0 +1,93 @@
+/** Who wrote a comment. From the site's sign-in, saved by the server. */
+export interface Author {
+    sub: string;
+    name: string;
+    picture?: string;
+}
+/** The person signed in on the site. */
+export interface Viewer extends Author {
+    email?: string;
+}
+/** An image in a comment, served at `<endpoint>/images/<id>/<key>`. */
+export interface CommentImage {
+    id: number;
+    /** Part of its address, so addresses cannot be guessed from ids. */
+    key: string;
+    /** Its size in pixels, so it can be laid out before it loads. */
+    width: number;
+    height: number;
+}
+export interface Comment {
+    id: number;
+    author: Author;
+    /** Empty when the comment is only images. */
+    body: string;
+    images: CommentImage[];
+    /** Milliseconds since the epoch. */
+    createdAt: number;
+    editedAt: number | null;
+    /** Sent but not yet confirmed by the server. */
+    pending?: boolean;
+}
+/** The element a pin was placed on, as it was then. */
+export interface CommentAnchor {
+    /** A CSS selector for it in its document. */
+    selector: string;
+    /** What it is and what it says, e.g. `button “Add prompts”`. */
+    label: string;
+    /** Its visible text, shortened. */
+    text: string;
+    /** Its box in the surface's CSS pixels. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A pin and the conversation under it. The first comment opens the thread. */
+export interface CommentThread {
+    /** Its number in the space, shown as #id. Never reused. */
+    id: number;
+    /** The page it is on: by default the URL's origin and path. */
+    page: string;
+    /** The address it was placed at. */
+    url: string;
+    /** The surface on the page, or '' for the page itself. */
+    surface: string;
+    /** The surface's title, or the page's, when the thread was placed. */
+    title: string;
+    /** Pin position in the surface's CSS pixels, from its top-left corner. */
+    x: number;
+    y: number;
+    /** Null for a pin in open space. */
+    anchor: CommentAnchor | null;
+    /** What the host said about where the thread was placed, e.g. the viewport size. */
+    context: Record<string, string>;
+    createdAt: number;
+    resolvedAt: number | null;
+    resolvedBy: Author | null;
+    /** Someone else has written in the thread since the viewer last opened it. */
+    unread: boolean;
+    comments: Comment[];
+}
+export interface CommentsSnapshot {
+    space: {
+        id: string;
+        name: string;
+    };
+    /** Null when signed out. */
+    viewer: Viewer | null;
+    threads: CommentThread[];
+}
+/** What a client sends to start a thread. */
+export interface NewThreadInput {
+    page: string;
+    url: string;
+    surface: string;
+    title: string;
+    x: number;
+    y: number;
+    anchor?: CommentAnchor | null;
+    context?: Record<string, string>;
+    body: string;
+    images?: number[];
+}

package/dist/shared/types.js

@@ -0,0 +1,2 @@
+// Shapes shared by the browser client and the server.
+export {};

package/dist/ui/Account.svelte

@@ -0,0 +1,68 @@
+<svelte:options css="injected" />
+
+<!--
+  The account button: the viewer's avatar with a menu to sign out, or Sign in.
+  It sits in the floating toolbar, or in a host's own toolbar where the host
+  puts a `data-vc-account` element; there it takes the host's text colour.
+-->
+<script lang="ts">
+	import type { VisualComments } from '../visual-comments.svelte.js';
+	import Avatar from './Avatar.svelte';
+	import { setComments } from './context.js';
+	import Icon from './Icon.svelte';
+	import Menu from './Menu.svelte';
+	import MenuItem from './MenuItem.svelte';
+
+	let { vc, slot = false }: { vc: VisualComments; slot?: boolean } = $props();
+	// svelte-ignore state_referenced_locally
+	if (slot) setComments(vc);
+
+	const tool = $derived(slot ? 'vc-slot-tool' : 'vc-island-tool');
+</script>
+
+<span class={['vc-ui inline-flex', slot && 'vc-slot']}>
+	{#if vc.viewer}
+		<Menu label={`Account: ${vc.viewer.name}`} align="end" class="{tool} pr-2 pl-0.5">
+			{#snippet trigger()}
+				{#if vc.viewer}<Avatar user={vc.viewer} size={28} />{/if}
+				<Icon name="chevron-down" size={14} />
+			{/snippet}
+			{#snippet children(close)}
+				<div class="max-w-72 border-b border-vc-line px-3 py-2">
+					<p class="truncate font-medium">{vc.viewer?.name}</p>
+					{#if vc.viewer?.email}<p class="mt-0.5 truncate text-xs text-vc-muted">{vc.viewer.email}</p>{/if}
+					{#if vc.store.spaceName}<p class="mt-0.5 truncate text-xs text-vc-muted">Comments in {vc.store.spaceName}</p>{/if}
+				</div>
+				<MenuItem onselect={() => { close(); vc.signOut(); }}>Sign out</MenuItem>
+			{/snippet}
+		</Menu>
+	{:else}
+		<button type="button" part="button" class="{tool} px-3.5 font-medium" disabled={vc.loading} onclick={() => vc.signIn()}>
+			{vc.loading ? 'Connecting…' : 'Sign in'}
+		</button>
+	{/if}
+</span>
+
+<style>
+	.vc-slot {
+		font-family: inherit;
+		font-size: inherit;
+		color: inherit;
+	}
+	:global(.vc-slot-tool) {
+		display: inline-flex;
+		height: 2rem;
+		align-items: center;
+		gap: 0.375rem;
+		border-radius: 9999px;
+		color: inherit;
+		outline: none;
+	}
+	:global(.vc-slot-tool:hover),
+	:global(.vc-slot-tool[aria-expanded='true']) {
+		background: color-mix(in srgb, currentColor 14%, transparent);
+	}
+	:global(.vc-slot-tool:focus-visible) {
+		box-shadow: 0 0 0 2px color-mix(in srgb, currentColor 50%, transparent);
+	}
+</style>

package/dist/ui/Account.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { VisualComments } from '../visual-comments.svelte.js';
+type $$ComponentProps = {
+    vc: VisualComments;
+    slot?: boolean;
+};
+declare const Account: import("svelte").Component<$$ComponentProps, {}, "">;
+type Account = ReturnType<typeof Account>;
+export default Account;

package/dist/ui/App.svelte

@@ -0,0 +1,68 @@
+<!--
+  Everything the comments draw over the page, in one shadow root: layers that
+  catch clicks over frames in comment mode, pins and cards, the list of
+  threads and the floating toolbar.
+-->
+<script lang="ts">
+	import type { VisualComments } from '../visual-comments.svelte.js';
+	import type { Surface } from '../core/surfaces.js';
+	import { setComments } from './context.js';
+	import Overlay from './Overlay.svelte';
+	import Panel from './Panel.svelte';
+	import Toolbar from './Toolbar.svelte';
+
+	let { vc }: { vc: VisualComments } = $props();
+	// svelte-ignore state_referenced_locally
+	setComments(vc);
+
+	// A thread deleted, here or elsewhere, is no longer open.
+	$effect(() => {
+		if (vc.openId !== undefined && !vc.loading && !vc.open) vc.openId = undefined;
+	});
+
+	/** Frames take pointer events themselves; in comment mode a layer over each catches them first. */
+	const catchers = $derived(vc.active ? vc.surfaces.filter((surface) => surface.catches) : []);
+
+	function wheel(surface: Surface) {
+		return (node: HTMLElement) => {
+			const onwheel = (event: WheelEvent) => vc.wheel(surface, event);
+			node.addEventListener('wheel', onwheel, { passive: false });
+			return () => node.removeEventListener('wheel', onwheel);
+		};
+	}
+
+	const panel = $derived(vc.panelRect);
+</script>
+
+<div class="vc-ui pointer-events-none fixed inset-0 font-vc text-[13px] text-vc-ink">
+	{#each catchers as surface (surface.id)}
+		<!-- svelte-ignore a11y_click_events_have_key_events -->
+		<div
+			{@attach wheel(surface)}
+			role="presentation"
+			class={['pointer-events-auto absolute', vc.cursor ? 'cursor-none!' : 'vc-comment-cursor']}
+			style:left="{surface.clip.left}px"
+			style:top="{surface.clip.top}px"
+			style:width="{Math.max(0, surface.clip.right - surface.clip.left)}px"
+			style:height="{Math.max(0, surface.clip.bottom - surface.clip.top)}px"
+			onpointermove={(event) => vc.move({ x: event.clientX, y: event.clientY, alt: event.altKey })}
+			onpointerleave={() => vc.move(undefined)}
+			onclick={(event) => vc.place(surface, event.clientX, event.clientY, event.altKey)}
+		></div>
+	{/each}
+
+	<Overlay />
+
+	{#if vc.active}
+		<Panel
+			class={panel ? 'absolute z-20' : 'absolute top-3 right-3 bottom-3 z-20 w-80'}
+			style={panel ? `left:${panel.left}px;top:${panel.top}px;width:${panel.right - panel.left}px;height:${panel.bottom - panel.top}px` : ''}
+			onselect={(thread) => vc.focus(thread)}
+			onclose={() => vc.toggle(false)}
+		/>
+	{/if}
+
+	{#if vc.showToolbar}
+		<Toolbar />
+	{/if}
+</div>

package/dist/ui/App.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { VisualComments } from '../visual-comments.svelte.js';
+type $$ComponentProps = {
+    vc: VisualComments;
+};
+declare const App: import("svelte").Component<$$ComponentProps, {}, "">;
+type App = ReturnType<typeof App>;
+export default App;

package/dist/ui/Avatar.svelte

@@ -0,0 +1,42 @@
+<!-- A person's profile picture, or their initial on a colour of their own. -->
+<script lang="ts" module>
+	// Others get a stable colour from their id; the viewer keeps the account colour.
+	const COLORS = ['#7b61ff', '#f24822', '#14ae5c', '#ffa629', '#0d99ff', '#e5487d', '#667799'];
+
+	function colorFor(sub: string) {
+		let hash = 0;
+		for (const char of sub) hash = (hash * 31 + char.codePointAt(0)!) | 0;
+		return COLORS[Math.abs(hash) % COLORS.length];
+	}
+</script>
+
+<script lang="ts">
+	import { useComments } from './context.js';
+
+	let { user, size = 24, class: className = '' }: {
+		user: { sub: string; name: string; picture?: string };
+		size?: number;
+		class?: string;
+	} = $props();
+
+	const vc = useComments();
+	let failed = $state<string>();
+	const initial = $derived(Array.from(user.name.trim() || '?')[0].toLocaleUpperCase());
+	const self = $derived(vc?.viewer?.sub === user.sub);
+</script>
+
+<span
+	class={['flex shrink-0 items-center justify-center overflow-hidden rounded-full leading-none text-white select-none', className]}
+	style:width="{size}px"
+	style:height="{size}px"
+	style:font-size="{Math.round(size * 0.5)}px"
+	style:background={self ? 'var(--color-vc-avatar)' : colorFor(user.sub)}
+	aria-hidden="true"
+>
+	{#if user.picture && user.picture !== failed}
+		<img src={user.picture} alt="" referrerpolicy="no-referrer" class="size-full object-cover" draggable="false"
+			onerror={() => { failed = user.picture; }} />
+	{:else}
+		{initial}
+	{/if}
+</span>

package/dist/ui/Avatar.svelte.d.ts

@@ -0,0 +1,12 @@
+type $$ComponentProps = {
+    user: {
+        sub: string;
+        name: string;
+        picture?: string;
+    };
+    size?: number;
+    class?: string;
+};
+declare const Avatar: import("svelte").Component<$$ComponentProps, {}, "">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;