@web-remarq/cloud 0.1.1

package/README.md

@@ -0,0 +1,89 @@
+# @web-remarq/cloud
+
+Cloud storage adapter for [web-remarq](../core/). Sync annotations across team members through Supabase.
+
+[![npm](https://img.shields.io/npm/v/@web-remarq/cloud)](https://www.npmjs.com/package/@web-remarq/cloud) [![license](https://img.shields.io/npm/l/@web-remarq/cloud)](../../LICENSE)
+
+## What it does
+
+Replaces the default `LocalStorageAdapter` with a Supabase-backed one. Annotations made by anyone with the same project key sync to a shared backend, so designers and developers see the same set of markers across browsers and devices. Self-host Supabase — the free tier is enough for a team.
+
+## Install
+
+```bash
+npm install @web-remarq/cloud @supabase/supabase-js
+```
+
+`@supabase/supabase-js` is a peer dependency — bring your own version so it isn't duplicated in your bundle.
+
+## Setup (10 minutes)
+
+### 1. Create a Supabase project
+
+Go to [dashboard.supabase.com](https://dashboard.supabase.com), create a new project on the free tier, and save the `Project URL` and `anon public` key from Settings → API.
+
+### 2. Apply the schema
+
+Copy the contents of [`sql/001_init.sql`](./sql/001_init.sql) into Supabase Studio → SQL Editor → New query → Run. Creates `projects`, `annotations`, RLS policies, and the `current_project_id()` helper.
+
+### 3. Generate a project key
+
+```sh
+npx @web-remarq/cloud gen-key --name "My App"
+```
+
+Save the printed `pk_...` key — it can't be recovered. Paste the generated `insert into projects ...` snippet into Supabase Studio → SQL Editor → Run.
+
+### 4. Wire it up
+
+```ts
+import { WebRemarq } from 'web-remarq'
+import { createCloudStorage } from '@web-remarq/cloud'
+
+WebRemarq.init({
+  storage: createCloudStorage({
+    supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
+    supabaseAnonKey: import.meta.env.VITE_SUPABASE_ANON_KEY,
+    projectKey: import.meta.env.VITE_REMARQ_PROJECT_KEY,
+  })
+})
+```
+
+## API
+
+### `createCloudStorage(options): StorageAdapter`
+
+Returns a `StorageAdapter` you can pass to `WebRemarq.init({ storage })`.
+
+Options:
+
+- `supabaseUrl` (required) — your Supabase project URL
+- `supabaseAnonKey` (required) — anon/publishable key (safe to ship to the browser — RLS gates everything)
+- `projectKey` (required) — `pk_...` key you generated in step 3
+- `onError` (`'throw' | 'memory-fallback'`, default `'throw'`) — what to do when a Supabase call fails
+
+### `generateProjectKey(): string`
+
+Generates a `pk_<32 random chars>` key. Browser-safe (uses Web Crypto).
+
+### `hashProjectKey(key): Promise<string>`
+
+SHA-256 hex (64 chars) of the key. This is what the database stores.
+
+## Security
+
+- The anon key is **safe** in the browser. Supabase RLS gates every operation by the project key sent in the `x-remarq-project-key` header.
+- The project key acts like a shared password — anyone with it has full read/write access to your annotations. **Treat it as a secret.**
+- The database only ever stores the SHA-256 hash of the project key, never the plaintext.
+- If a key leaks, generate a new one (step 3) and delete the old project row in Supabase Studio.
+
+## Limits (cloud-0.1.0 MVP)
+
+- One project key per team — no user accounts yet
+- No realtime sync — refresh the page to pick up other people's changes (coming in cloud-0.2.0 with MCP server + team UX)
+- No web dashboard — manage annotations via Supabase Studio for now
+- Two tabs editing the same annotation: last write wins
+
+## License
+
+MIT

package/bin/gen-key.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import { webcrypto } from 'node:crypto'
+
+const PREFIX = 'pk_'
+const KEY_LENGTH = 32
+const ALPHABET = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
+
+function generateProjectKey() {
+  const bytes = new Uint8Array(KEY_LENGTH)
+  webcrypto.getRandomValues(bytes)
+  let key = PREFIX
+  for (let i = 0; i < KEY_LENGTH; i++) {
+    key += ALPHABET[bytes[i] % ALPHABET.length]
+  }
+  return key
+}
+
+async function hashProjectKey(key) {
+  const data = new TextEncoder().encode(key)
+  const buf = await webcrypto.subtle.digest('SHA-256', data)
+  return Array.from(new Uint8Array(buf))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+function parseFlag(argv, flag) {
+  const i = argv.indexOf(flag)
+  if (i === -1) return undefined
+  return argv[i + 1]
+}
+
+function sqlString(value) {
+  return `'${value.replace(/'/g, "''")}'`
+}
+
+function printUsage(stream) {
+  stream.write(
+    [
+      'Usage: web-remarq-cloud <command> [options]',
+      '',
+      'Commands:',
+      '  gen-key --name "<project name>" [--origin "<url>"]',
+      '      Generate a project key, print its sha256 hash and an',
+      '      insert-snippet to register the project in Supabase.',
+      '',
+    ].join('\n')
+  )
+}
+
+async function runGenKey(argv) {
+  const name = parseFlag(argv, '--name')
+  const origin = parseFlag(argv, '--origin')
+
+  if (!name) {
+    process.stderr.write('Error: --name is required.\n\n')
+    printUsage(process.stderr)
+    process.exit(1)
+  }
+
+  const key = generateProjectKey()
+  const hash = await hashProjectKey(key)
+  const originSql = origin ? sqlString(origin) : 'null'
+
+  process.stdout.write(
+    [
+      `Project key:   ${key}`,
+      `Hash (sha256): ${hash}`,
+      '',
+      'Store the project key securely — it will not be shown again.',
+      '',
+      'Run this in Supabase SQL Editor:',
+      '',
+      `  insert into projects (name, origin, secret_key_hash)`,
+      `  values (${sqlString(name)}, ${originSql}, '${hash}');`,
+      '',
+    ].join('\n')
+  )
+}
+
+async function main() {
+  const [, , command, ...rest] = process.argv
+
+  if (command === 'gen-key') {
+    await runGenKey(rest)
+    return
+  }
+
+  printUsage(process.stdout)
+}
+
+main()

package/dist/index.cjs

@@ -0,0 +1,131 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  CloudStorageAdapter: () => CloudStorageAdapter,
+  createCloudStorage: () => createCloudStorage,
+  generateProjectKey: () => generateProjectKey,
+  hashProjectKey: () => hashProjectKey
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/cloud-storage-adapter.ts
+var import_supabase_js = require("@supabase/supabase-js");
+function rowToAnnotation(row) {
+  var _a;
+  return {
+    id: row.id,
+    comment: row.comment,
+    fingerprint: row.fingerprint,
+    route: row.route,
+    viewport: row.viewport,
+    viewportBucket: row.viewport_bucket,
+    timestamp: row.timestamp_ms,
+    status: row.status,
+    lifecycle: (_a = row.lifecycle) != null ? _a : []
+  };
+}
+function annotationToRow(a) {
+  return {
+    id: a.id,
+    route: a.route,
+    viewport: a.viewport,
+    viewport_bucket: a.viewportBucket,
+    fingerprint: a.fingerprint,
+    comment: a.comment,
+    status: a.status,
+    timestamp_ms: a.timestamp,
+    updated_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var CloudStorageAdapter = class {
+  constructor(opts) {
+    this.isMemoryOnly = false;
+    var _a;
+    this.onError = (_a = opts.onError) != null ? _a : "throw";
+    this.client = (0, import_supabase_js.createClient)(opts.supabaseUrl, opts.supabaseAnonKey, {
+      global: {
+        headers: { "x-remarq-project-key": opts.projectKey }
+      },
+      auth: { persistSession: false }
+    });
+  }
+  async load() {
+    const { data, error } = await this.client.from("annotations").select("*").order("timestamp_ms", { ascending: true });
+    if (error) {
+      return this.handleError(error, { version: 1, annotations: [] });
+    }
+    const rows = data != null ? data : [];
+    return { version: 1, annotations: rows.map(rowToAnnotation) };
+  }
+  async save(annotation) {
+    const row = annotationToRow(annotation);
+    const { error } = await this.client.from("annotations").upsert(row, { onConflict: "id" });
+    if (error) this.handleError(error, void 0);
+  }
+  async remove(id) {
+    const { error } = await this.client.from("annotations").delete().eq("id", id);
+    if (error) this.handleError(error, void 0);
+  }
+  async clear() {
+    const { error } = await this.client.from("annotations").delete().neq("id", "__never_matches__");
+    if (error) this.handleError(error, void 0);
+  }
+  handleError(error, fallback) {
+    if (this.onError === "throw") {
+      throw error;
+    }
+    console.warn("[web-remarq cloud]", error);
+    return fallback;
+  }
+};
+
+// src/project-key.ts
+var PREFIX = "pk_";
+var KEY_LENGTH = 32;
+var ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+function generateProjectKey() {
+  const bytes = new Uint8Array(KEY_LENGTH);
+  crypto.getRandomValues(bytes);
+  let key = PREFIX;
+  for (let i = 0; i < KEY_LENGTH; i++) {
+    key += ALPHABET[bytes[i] % ALPHABET.length];
+  }
+  return key;
+}
+async function hashProjectKey(key) {
+  const data = new TextEncoder().encode(key);
+  const buf = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/index.ts
+function createCloudStorage(opts) {
+  return new CloudStorageAdapter(opts);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CloudStorageAdapter,
+  createCloudStorage,
+  generateProjectKey,
+  hashProjectKey
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/cloud-storage-adapter.ts","../src/project-key.ts"],"sourcesContent":["import type { StorageAdapter } from 'web-remarq'\nimport { CloudStorageAdapter } from './cloud-storage-adapter'\nimport type { CloudStorageOptions } from './types'\n\nexport { generateProjectKey, hashProjectKey } from './project-key'\nexport { CloudStorageAdapter } from './cloud-storage-adapter'\nexport type { CloudStorageOptions } from './types'\n\nexport function createCloudStorage(opts: CloudStorageOptions): StorageAdapter {\n  return new CloudStorageAdapter(opts)\n}\n","import { createClient, type SupabaseClient } from '@supabase/supabase-js'\nimport type {\n  Annotation,\n  AnnotationEvent,\n  AnnotationStatus,\n  AnnotationStore,\n  ElementFingerprint,\n  StorageAdapter,\n} from 'web-remarq'\nimport type { CloudStorageOptions } from './types'\n\ninterface AnnotationRow {\n  id: string\n  project_id?: string\n  route: string\n  viewport: string\n  viewport_bucket: number\n  fingerprint: ElementFingerprint\n  comment: string\n  status: AnnotationStatus\n  timestamp_ms: number\n  lifecycle?: AnnotationEvent[]\n  created_at?: string\n  updated_at?: string\n}\n\ntype AnnotationWriteRow = Omit<AnnotationRow, 'project_id' | 'created_at'>\n\nfunction rowToAnnotation(row: AnnotationRow): Annotation {\n  return {\n    id: row.id,\n    comment: row.comment,\n    fingerprint: row.fingerprint,\n    route: row.route,\n    viewport: row.viewport,\n    viewportBucket: row.viewport_bucket,\n    timestamp: row.timestamp_ms,\n    status: row.status,\n    lifecycle: row.lifecycle ?? [],\n  }\n}\n\nfunction annotationToRow(a: Annotation): AnnotationWriteRow {\n  // lifecycle is intentionally NOT written here — cloud-0.1.0 schema doesn't\n  // have a lifecycle column. Will be added in cloud-0.1.1 alongside SQL migration.\n  // Until then, lifecycle history doesn't survive across browser sessions for\n  // cloud users; migrateAnnotation synthesizes a created event on load.\n  return {\n    id: a.id,\n    route: a.route,\n    viewport: a.viewport,\n    viewport_bucket: a.viewportBucket,\n    fingerprint: a.fingerprint,\n    comment: a.comment,\n    status: a.status,\n    timestamp_ms: a.timestamp,\n    updated_at: new Date().toISOString(),\n  }\n}\n\nexport class CloudStorageAdapter implements StorageAdapter {\n  readonly isMemoryOnly = false\n  private client: SupabaseClient\n  private onError: 'throw' | 'memory-fallback'\n\n  constructor(opts: CloudStorageOptions) {\n    this.onError = opts.onError ?? 'throw'\n    this.client = createClient(opts.supabaseUrl, opts.supabaseAnonKey, {\n      global: {\n        headers: { 'x-remarq-project-key': opts.projectKey },\n      },\n      auth: { persistSession: false },\n    })\n  }\n\n  async load(): Promise<AnnotationStore> {\n    const { data, error } = await this.client\n      .from('annotations')\n      .select('*')\n      .order('timestamp_ms', { ascending: true })\n\n    if (error) {\n      return this.handleError<AnnotationStore>(error, { version: 1, annotations: [] })\n    }\n\n    const rows = (data ?? []) as AnnotationRow[]\n    return { version: 1, annotations: rows.map(rowToAnnotation) }\n  }\n\n  async save(annotation: Annotation): Promise<void> {\n    const row = annotationToRow(annotation)\n    const { error } = await this.client\n      .from('annotations')\n      .upsert(row, { onConflict: 'id' })\n    if (error) this.handleError<void>(error, undefined)\n  }\n\n  async remove(id: string): Promise<void> {\n    const { error } = await this.client.from('annotations').delete().eq('id', id)\n    if (error) this.handleError<void>(error, undefined)\n  }\n\n  async clear(): Promise<void> {\n    const { error } = await this.client\n      .from('annotations')\n      .delete()\n      .neq('id', '__never_matches__')\n    if (error) this.handleError<void>(error, undefined)\n  }\n\n  private handleError<T>(error: unknown, fallback: T): T {\n    if (this.onError === 'throw') {\n      throw error\n    }\n    console.warn('[web-remarq cloud]', error)\n    return fallback\n  }\n}\n","const PREFIX = 'pk_'\nconst KEY_LENGTH = 32\nconst ALPHABET = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'\n\nexport function generateProjectKey(): string {\n  const bytes = new Uint8Array(KEY_LENGTH)\n  crypto.getRandomValues(bytes)\n  let key = PREFIX\n  for (let i = 0; i < KEY_LENGTH; i++) {\n    key += ALPHABET[bytes[i] % ALPHABET.length]\n  }\n  return key\n}\n\nexport async function hashProjectKey(key: string): Promise<string> {\n  const data = new TextEncoder().encode(key)\n  const buf = await crypto.subtle.digest('SHA-256', data)\n  return Array.from(new Uint8Array(buf))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+import { StorageAdapter, AnnotationStore, Annotation } from 'web-remarq';
+
+interface CloudStorageOptions {
+    supabaseUrl: string;
+    supabaseAnonKey: string;
+    projectKey: string;
+    onError?: 'throw' | 'memory-fallback';
+}
+
+declare function generateProjectKey(): string;
+declare function hashProjectKey(key: string): Promise<string>;
+
+declare class CloudStorageAdapter implements StorageAdapter {
+    readonly isMemoryOnly = false;
+    private client;
+    private onError;
+    constructor(opts: CloudStorageOptions);
+    load(): Promise<AnnotationStore>;
+    save(annotation: Annotation): Promise<void>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    private handleError;
+}
+
+declare function createCloudStorage(opts: CloudStorageOptions): StorageAdapter;
+
+export { CloudStorageAdapter, type CloudStorageOptions, createCloudStorage, generateProjectKey, hashProjectKey };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { StorageAdapter, AnnotationStore, Annotation } from 'web-remarq';
+
+interface CloudStorageOptions {
+    supabaseUrl: string;
+    supabaseAnonKey: string;
+    projectKey: string;
+    onError?: 'throw' | 'memory-fallback';
+}
+
+declare function generateProjectKey(): string;
+declare function hashProjectKey(key: string): Promise<string>;
+
+declare class CloudStorageAdapter implements StorageAdapter {
+    readonly isMemoryOnly = false;
+    private client;
+    private onError;
+    constructor(opts: CloudStorageOptions);
+    load(): Promise<AnnotationStore>;
+    save(annotation: Annotation): Promise<void>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    private handleError;
+}
+
+declare function createCloudStorage(opts: CloudStorageOptions): StorageAdapter;
+
+export { CloudStorageAdapter, type CloudStorageOptions, createCloudStorage, generateProjectKey, hashProjectKey };

package/dist/index.js

@@ -0,0 +1,101 @@
+// src/cloud-storage-adapter.ts
+import { createClient } from "@supabase/supabase-js";
+function rowToAnnotation(row) {
+  var _a;
+  return {
+    id: row.id,
+    comment: row.comment,
+    fingerprint: row.fingerprint,
+    route: row.route,
+    viewport: row.viewport,
+    viewportBucket: row.viewport_bucket,
+    timestamp: row.timestamp_ms,
+    status: row.status,
+    lifecycle: (_a = row.lifecycle) != null ? _a : []
+  };
+}
+function annotationToRow(a) {
+  return {
+    id: a.id,
+    route: a.route,
+    viewport: a.viewport,
+    viewport_bucket: a.viewportBucket,
+    fingerprint: a.fingerprint,
+    comment: a.comment,
+    status: a.status,
+    timestamp_ms: a.timestamp,
+    updated_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var CloudStorageAdapter = class {
+  constructor(opts) {
+    this.isMemoryOnly = false;
+    var _a;
+    this.onError = (_a = opts.onError) != null ? _a : "throw";
+    this.client = createClient(opts.supabaseUrl, opts.supabaseAnonKey, {
+      global: {
+        headers: { "x-remarq-project-key": opts.projectKey }
+      },
+      auth: { persistSession: false }
+    });
+  }
+  async load() {
+    const { data, error } = await this.client.from("annotations").select("*").order("timestamp_ms", { ascending: true });
+    if (error) {
+      return this.handleError(error, { version: 1, annotations: [] });
+    }
+    const rows = data != null ? data : [];
+    return { version: 1, annotations: rows.map(rowToAnnotation) };
+  }
+  async save(annotation) {
+    const row = annotationToRow(annotation);
+    const { error } = await this.client.from("annotations").upsert(row, { onConflict: "id" });
+    if (error) this.handleError(error, void 0);
+  }
+  async remove(id) {
+    const { error } = await this.client.from("annotations").delete().eq("id", id);
+    if (error) this.handleError(error, void 0);
+  }
+  async clear() {
+    const { error } = await this.client.from("annotations").delete().neq("id", "__never_matches__");
+    if (error) this.handleError(error, void 0);
+  }
+  handleError(error, fallback) {
+    if (this.onError === "throw") {
+      throw error;
+    }
+    console.warn("[web-remarq cloud]", error);
+    return fallback;
+  }
+};
+
+// src/project-key.ts
+var PREFIX = "pk_";
+var KEY_LENGTH = 32;
+var ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+function generateProjectKey() {
+  const bytes = new Uint8Array(KEY_LENGTH);
+  crypto.getRandomValues(bytes);
+  let key = PREFIX;
+  for (let i = 0; i < KEY_LENGTH; i++) {
+    key += ALPHABET[bytes[i] % ALPHABET.length];
+  }
+  return key;
+}
+async function hashProjectKey(key) {
+  const data = new TextEncoder().encode(key);
+  const buf = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/index.ts
+function createCloudStorage(opts) {
+  return new CloudStorageAdapter(opts);
+}
+export {
+  CloudStorageAdapter,
+  createCloudStorage,
+  generateProjectKey,
+  hashProjectKey
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cloud-storage-adapter.ts","../src/project-key.ts","../src/index.ts"],"sourcesContent":["import { createClient, type SupabaseClient } from '@supabase/supabase-js'\nimport type {\n  Annotation,\n  AnnotationEvent,\n  AnnotationStatus,\n  AnnotationStore,\n  ElementFingerprint,\n  StorageAdapter,\n} from 'web-remarq'\nimport type { CloudStorageOptions } from './types'\n\ninterface AnnotationRow {\n  id: string\n  project_id?: string\n  route: string\n  viewport: string\n  viewport_bucket: number\n  fingerprint: ElementFingerprint\n  comment: string\n  status: AnnotationStatus\n  timestamp_ms: number\n  lifecycle?: AnnotationEvent[]\n  created_at?: string\n  updated_at?: string\n}\n\ntype AnnotationWriteRow = Omit<AnnotationRow, 'project_id' | 'created_at'>\n\nfunction rowToAnnotation(row: AnnotationRow): Annotation {\n  return {\n    id: row.id,\n    comment: row.comment,\n    fingerprint: row.fingerprint,\n    route: row.route,\n    viewport: row.viewport,\n    viewportBucket: row.viewport_bucket,\n    timestamp: row.timestamp_ms,\n    status: row.status,\n    lifecycle: row.lifecycle ?? [],\n  }\n}\n\nfunction annotationToRow(a: Annotation): AnnotationWriteRow {\n  // lifecycle is intentionally NOT written here — cloud-0.1.0 schema doesn't\n  // have a lifecycle column. Will be added in cloud-0.1.1 alongside SQL migration.\n  // Until then, lifecycle history doesn't survive across browser sessions for\n  // cloud users; migrateAnnotation synthesizes a created event on load.\n  return {\n    id: a.id,\n    route: a.route,\n    viewport: a.viewport,\n    viewport_bucket: a.viewportBucket,\n    fingerprint: a.fingerprint,\n    comment: a.comment,\n    status: a.status,\n    timestamp_ms: a.timestamp,\n    updated_at: new Date().toISOString(),\n  }\n}\n\nexport class CloudStorageAdapter implements StorageAdapter {\n  readonly isMemoryOnly = false\n  private client: SupabaseClient\n  private onError: 'throw' | 'memory-fallback'\n\n  constructor(opts: CloudStorageOptions) {\n    this.onError = opts.onError ?? 'throw'\n    this.client = createClient(opts.supabaseUrl, opts.supabaseAnonKey, {\n      global: {\n        headers: { 'x-remarq-project-key': opts.projectKey },\n      },\n      auth: { persistSession: false },\n    })\n  }\n\n  async load(): Promise<AnnotationStore> {\n    const { data, error } = await this.client\n      .from('annotations')\n      .select('*')\n      .order('timestamp_ms', { ascending: true })\n\n    if (error) {\n      return this.handleError<AnnotationStore>(error, { version: 1, annotations: [] })\n    }\n\n    const rows = (data ?? []) as AnnotationRow[]\n    return { version: 1, annotations: rows.map(rowToAnnotation) }\n  }\n\n  async save(annotation: Annotation): Promise<void> {\n    const row = annotationToRow(annotation)\n    const { error } = await this.client\n      .from('annotations')\n      .upsert(row, { onConflict: 'id' })\n    if (error) this.handleError<void>(error, undefined)\n  }\n\n  async remove(id: string): Promise<void> {\n    const { error } = await this.client.from('annotations').delete().eq('id', id)\n    if (error) this.handleError<void>(error, undefined)\n  }\n\n  async clear(): Promise<void> {\n    const { error } = await this.client\n      .from('annotations')\n      .delete()\n      .neq('id', '__never_matches__')\n    if (error) this.handleError<void>(error, undefined)\n  }\n\n  private handleError<T>(error: unknown, fallback: T): T {\n    if (this.onError === 'throw') {\n      throw error\n    }\n    console.warn('[web-remarq cloud]', error)\n    return fallback\n  }\n}\n","const PREFIX = 'pk_'\nconst KEY_LENGTH = 32\nconst ALPHABET = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'\n\nexport function generateProjectKey(): string {\n  const bytes = new Uint8Array(KEY_LENGTH)\n  crypto.getRandomValues(bytes)\n  let key = PREFIX\n  for (let i = 0; i < KEY_LENGTH; i++) {\n    key += ALPHABET[bytes[i] % ALPHABET.length]\n  }\n  return key\n}\n\nexport async function hashProjectKey(key: string): Promise<string> {\n  const data = new TextEncoder().encode(key)\n  const buf = await crypto.subtle.digest('SHA-256', data)\n  return Array.from(new Uint8Array(buf))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n","import type { StorageAdapter } from 'web-remarq'\nimport { CloudStorageAdapter } from './cloud-storage-adapter'\nimport type { CloudStorageOptions } from './types'\n\nexport { generateProjectKey, hashProjectKey } from './project-key'\nexport { CloudStorageAdapter } from './cloud-storage-adapter'\nexport type { CloudStorageOptions } from './types'\n\nexport function createCloudStorage(opts: CloudStorageOptions): StorageAdapter {\n  return new CloudStorageAdapter(opts)\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@web-remarq/cloud",
+  "version": "0.1.1",
+  "description": "Cloud storage adapter for web-remarq — Supabase-backed sync",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "sql",
+    "bin"
+  ],
+  "bin": {
+    "web-remarq-cloud": "./bin/gen-key.mjs"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DPostnik/web-remarq.git"
+  },
+  "homepage": "https://github.com/DPostnik/web-remarq",
+  "bugs": {
+    "url": "https://github.com/DPostnik/web-remarq/issues"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "web-remarq": ">=0.7.0",
+    "@supabase/supabase-js": ">=2.0.0"
+  },
+  "devDependencies": {
+    "@supabase/supabase-js": "^2.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}

package/sql/001_init.sql

@@ -0,0 +1,82 @@
+-- 001_init.sql
+
+-- digest() из pgcrypto. В Supabase живёт в схеме `extensions`.
+create extension if not exists pgcrypto;
+
+-- Projects: один project = один независимый scope аннотаций.
+-- secret_key_hash — sha256 от 'pk_<32 random chars>'. Никогда не храним plaintext.
+create table projects (
+  id uuid primary key default gen_random_uuid(),
+  name text not null,
+  origin text,  -- свободное поле (https://staging.example.com), не идентификатор
+  secret_key_hash text not null unique,
+  created_at timestamptz not null default now()
+);
+
+-- Helper: достаёт project_id по ключу из заголовка.
+-- SECURITY DEFINER + explicit search_path: иначе SELECT projects внутри функции
+-- рекурсивно идёт через RLS policy, которая снова зовёт эту функцию → stack overflow.
+-- `extensions` нужен чтобы найти digest() из pgcrypto.
+create or replace function current_project_id() returns uuid
+  language plpgsql stable
+  security definer
+  set search_path = public, extensions, pg_catalog
+as $$
+declare
+  key_header text;
+  key_hash text;
+  project uuid;
+begin
+  key_header := current_setting('request.headers', true)::json->>'x-remarq-project-key';
+  if key_header is null then return null; end if;
+  key_hash := encode(digest(key_header, 'sha256'), 'hex');
+  select id into project from projects where secret_key_hash = key_hash limit 1;
+  return project;
+end;
+$$;
+
+-- Annotations: формат зеркалит web-remarq Annotation тип.
+-- project_id заполняется default-ом из заголовка — клиент не должен его знать.
+-- RLS WITH CHECK дополнительно валидирует что default совпал с current_project_id().
+-- fingerprint целиком в JSONB — не нормализуем (нам этого не надо в MVP).
+create table annotations (
+  id text primary key,  -- web-remarq id (не uuid! shortid из клиента)
+  project_id uuid not null default current_project_id() references projects(id) on delete cascade,
+  route text not null,
+  viewport text not null,
+  viewport_bucket integer not null,
+  fingerprint jsonb not null,
+  comment text not null,
+  status text not null default 'pending',
+  timestamp_ms bigint not null,  -- web-remarq timestamp (ms)
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+create index annotations_project_route_idx on annotations(project_id, route);
+create index annotations_project_status_idx on annotations(project_id, status);
+
+-- RLS: client передаёт project key plaintext в заголовке `x-remarq-project-key`,
+-- мы проверяем sha256(key) == secret_key_hash через current_setting().
+-- Это безопасно потому что:
+-- (a) ключ передаётся только по HTTPS,
+-- (b) на сервере остаётся только хеш,
+-- (c) anon key Supabase ограничен RLS-политиками.
+
+alter table projects enable row level security;
+alter table annotations enable row level security;
+
+-- Projects: видны только самим себе (через ключ); insert/update — через service role (out of scope MVP).
+create policy projects_select on projects
+  for select using (id = current_project_id());
+
+-- Annotations: полный CRUD когда совпадает project_id.
+create policy annotations_select on annotations
+  for select using (project_id = current_project_id());
+create policy annotations_insert on annotations
+  for insert with check (project_id = current_project_id());
+create policy annotations_update on annotations
+  for update using (project_id = current_project_id())
+  with check (project_id = current_project_id());
+create policy annotations_delete on annotations
+  for delete using (project_id = current_project_id());

package/sql/README.md

@@ -0,0 +1,58 @@
+# Supabase setup for `@web-remarq/cloud`
+
+Run this once per Supabase project. Takes ~5 minutes.
+
+## 1. Apply the schema
+
+1. Open your Supabase project → **SQL Editor** → **New query**.
+2. Copy the entire contents of [`001_init.sql`](./001_init.sql) into the editor.
+3. Click **Run**. You should see `Success. No rows returned.`
+
+This creates two tables (`projects`, `annotations`), enables row-level security,
+and installs the `current_project_id()` helper that gates all access by the
+`x-remarq-project-key` header.
+
+## 2. Verify the schema
+
+In a new query, run:
+
+```sql
+select * from projects;
+select * from annotations;
+```
+
+Both should return zero rows (not an error). If either errors with
+`relation does not exist`, step 1 did not complete — re-run it.
+
+## 3. Generate a project key
+
+From your local machine:
+
+```sh
+npx @web-remarq/cloud gen-key --name "My App"
+```
+
+Optionally pass `--origin "https://staging.example.com"` to tag the project
+with a human-readable origin (free-form, not used for auth).
+
+The script prints three things:
+
+- The project key (`pk_...`) — your clients use this at runtime.
+- Its sha256 hash — what Supabase stores.
+- A ready-to-paste `insert` snippet.
+
+## 4. Register the project in Supabase
+
+1. Copy the printed `insert into projects ...` snippet.
+2. Paste it into the SQL Editor → **Run**.
+3. Confirm with `select id, name, origin, created_at from projects;` — your
+   project row should appear.
+
+## 5. Store the project key
+
+Save the printed `pk_...` value in a password manager (1Password, Bitwarden,
+etc.). It is **not recoverable** — only the hash is stored server-side. If you
+lose it, generate a new one and replace the row in `projects`.
+
+You are now ready to call `createCloudStorage({ projectKey: 'pk_...', ... })`
+from your app. See the package README for the runtime API.