annotate-kit 0.1.0

package/dist/local.d.ts

@@ -0,0 +1,18 @@
+import { S as StorageAdapter } from './adapter-Cyqfwj6F.js';
+import './types-BLXmj4Oi.js';
+
+type LocalAdapterConfig = {
+    /** localStorage key holding all data (default 'annotate-kit'). */
+    storageKey?: string;
+    /** The single local user shown as author. */
+    me?: {
+        email?: string;
+        name?: string;
+        role?: string;
+    };
+    /** Storage backend (default globalThis.localStorage). Pass a mock for tests / non-browser envs. */
+    storage?: Storage;
+};
+declare function createLocalAdapter(config?: LocalAdapterConfig): StorageAdapter;
+
+export { type LocalAdapterConfig, createLocalAdapter };

package/dist/local.js

@@ -0,0 +1,115 @@
+// src/adapters/local.ts
+function createLocalAdapter(config = {}) {
+  const key = config.storageKey ?? "annotate-kit";
+  const me = config.me ?? { email: "you@local", name: "You" };
+  const store = config.storage ?? (typeof localStorage !== "undefined" ? localStorage : void 0);
+  const now = () => (/* @__PURE__ */ new Date()).toISOString();
+  const empty = () => ({ seq: 1, rows: [], settings: { enabled: true }, shots: {} });
+  const read = () => {
+    if (!store) return empty();
+    try {
+      const raw = store.getItem(key);
+      if (!raw) return empty();
+      const s = JSON.parse(raw);
+      return {
+        seq: typeof s.seq === "number" ? s.seq : 1,
+        rows: Array.isArray(s.rows) ? s.rows : [],
+        settings: s.settings && typeof s.settings.enabled === "boolean" ? s.settings : { enabled: true },
+        shots: s.shots && typeof s.shots === "object" ? s.shots : {}
+      };
+    } catch {
+      return empty();
+    }
+  };
+  const write = (s) => {
+    if (!store) return;
+    try {
+      store.setItem(key, JSON.stringify(s));
+    } catch {
+      throw new Error("annotate: local storage is full or unavailable \u2014 the change could not be saved");
+    }
+  };
+  const withUrls = (s) => s.rows.map((r) => ({ ...r, screenshot_url: r.screenshot_path ? s.shots[r.screenshot_path] ?? null : null }));
+  return {
+    async getAccess() {
+      return { enabled: read().settings.enabled, isAdmin: true, canUse: true, seeAll: true, me };
+    },
+    async setAccess(enabled) {
+      const s = read();
+      s.settings.enabled = enabled;
+      write(s);
+      return { message: enabled ? "Enabled" : "Disabled" };
+    },
+    async list() {
+      return withUrls(read()).sort((a, b) => b.id - a.id);
+    },
+    async save(input) {
+      const s = read();
+      const id = s.seq++;
+      s.rows.push({
+        ...input,
+        id,
+        status: "open",
+        created_by: me.email ?? "",
+        created_by_name: me.name ?? me.email ?? "",
+        created_by_role: me.role ?? null,
+        created_at: now(),
+        updated_at: now()
+      });
+      write(s);
+      return { id };
+    },
+    async update(patch) {
+      const s = read();
+      const { id, ...rest } = patch;
+      const row = s.rows.find((r) => r.id === id);
+      if (row) {
+        Object.assign(row, rest, { updated_at: now() });
+        write(s);
+      }
+    },
+    async remove(id) {
+      const s = read();
+      const row = s.rows.find((r) => r.id === id);
+      if (row?.screenshot_path) delete s.shots[row.screenshot_path];
+      s.rows = s.rows.filter((r) => r.id !== id);
+      write(s);
+    },
+    async addReply(id, note) {
+      const s = read();
+      const row = s.rows.find((r) => r.id === id);
+      if (row) {
+        const reply = { note: note.slice(0, 2e3), author: me.name ?? me.email ?? "", at: now() };
+        row.replies = [...Array.isArray(row.replies) ? row.replies : [], reply];
+        row.updated_at = now();
+        write(s);
+      }
+    },
+    async clearResolved() {
+      const s = read();
+      const before = s.rows.length;
+      for (const r of s.rows) if ((r.status === "done" || r.status === "dismissed") && r.screenshot_path) delete s.shots[r.screenshot_path];
+      s.rows = s.rows.filter((r) => r.status !== "done" && r.status !== "dismissed");
+      const referenced = new Set(s.rows.map((r) => r.screenshot_path).filter(Boolean));
+      for (const p of Object.keys(s.shots)) if (!referenced.has(p)) delete s.shots[p];
+      write(s);
+      return { message: `Cleared ${before - s.rows.length} resolved` };
+    },
+    async uploadScreenshot(file, _opts) {
+      const dataUrl = await new Promise((resolve, reject) => {
+        const fr = new FileReader();
+        fr.onload = () => resolve(String(fr.result));
+        fr.onerror = () => reject(fr.error ?? new Error("read failed"));
+        fr.readAsDataURL(file);
+      });
+      const s = read();
+      const path = `shot-${s.seq++}-${Date.now()}`;
+      s.shots[path] = dataUrl;
+      write(s);
+      return { path };
+    }
+  };
+}
+export {
+  createLocalAdapter
+};

package/dist/prompt.d.ts

@@ -0,0 +1,54 @@
+import { a as Annotation, d as AnnKind, e as AnnShape, f as AnnType, g as AnnPriority, h as AnnStatus, c as AnnVisibility } from './types-BLXmj4Oi.js';
+
+declare function buildDevPrompt(items: Annotation[], opts?: {
+    title?: string;
+    includeConsole?: boolean;
+    includeNetwork?: boolean;
+}): string;
+declare function buildDevContext(items: Annotation[]): {
+    total: number;
+    items: {
+        id: number;
+        page_route: string;
+        page_title: string;
+        kind: AnnKind;
+        shape_type: AnnShape | null;
+        type: AnnType;
+        priority: AnnPriority;
+        status: AnnStatus;
+        visibility: AnnVisibility;
+        element: {
+            selector: string | null;
+            text: string | null;
+        };
+        where: string[];
+        note: string;
+        author: string | null;
+        env: {
+            browser: string | null;
+            os: string | null;
+            device: string | null;
+            viewport: string | null;
+            url: string | null;
+        } | null;
+        replies: {
+            note: string;
+            author: string | null;
+            at: string | null;
+        }[];
+        console: {
+            level: string;
+            text: string;
+        }[];
+        network: {
+            method: string;
+            url: string;
+            status: number | null;
+            ms: number | null;
+        }[];
+        domSnapshot: string | null;
+        hasScreenshot: boolean;
+    }[];
+};
+
+export { buildDevContext, buildDevPrompt };

package/dist/prompt.js

@@ -0,0 +1,8 @@
+import {
+  buildDevContext,
+  buildDevPrompt
+} from "./chunk-G44KPHPN.js";
+export {
+  buildDevContext,
+  buildDevPrompt
+};

package/dist/rest.d.ts

@@ -0,0 +1,27 @@
+import { S as StorageAdapter } from './adapter-Cyqfwj6F.js';
+import './types-BLXmj4Oi.js';
+
+type RestEndpoints = {
+    access: string;
+    list: string;
+    create: string;
+    item: (id: number) => string;
+    replies: (id: number) => string;
+    clearResolved: string;
+    screenshots: string;
+};
+type RestAdapterConfig = {
+    /** Base URL of your annotations API, e.g. '/api/annotations' or 'https://api.example.com/annotations'. */
+    baseUrl: string;
+    /** Extra headers (e.g. Authorization). A function is re-evaluated per request, so tokens stay fresh. */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /** Cookie policy for requests (default 'same-origin'). Use 'include' for cross-origin cookies. */
+    credentials?: RequestCredentials;
+    /** Custom fetch implementation (default: global fetch). */
+    fetch?: typeof fetch;
+    /** Override any endpoint (absolute URL or relative to baseUrl). */
+    endpoints?: Partial<RestEndpoints>;
+};
+declare function createRestAdapter(config: RestAdapterConfig): StorageAdapter;
+
+export { type RestAdapterConfig, type RestEndpoints, createRestAdapter };

package/dist/rest.js

@@ -0,0 +1,63 @@
+// src/adapters/rest.ts
+function createRestAdapter(config) {
+  const base = config.baseUrl.replace(/\/+$/, "");
+  const doFetch = config.fetch ?? (typeof fetch !== "undefined" ? fetch : void 0);
+  if (!doFetch) throw new Error("annotate: no fetch available \u2014 pass config.fetch");
+  const ep = {
+    access: `${base}/access`,
+    list: base,
+    create: base,
+    item: (id) => `${base}/${encodeURIComponent(String(id))}`,
+    replies: (id) => `${base}/${encodeURIComponent(String(id))}/replies`,
+    clearResolved: `${base}/clear-resolved`,
+    screenshots: `${base}/screenshots`,
+    ...config.endpoints
+  };
+  async function baseHeaders() {
+    return typeof config.headers === "function" ? await config.headers() : config.headers ?? {};
+  }
+  async function req(url, opts) {
+    const headers = { ...await baseHeaders() };
+    if (opts?.json !== void 0) headers["content-type"] = "application/json";
+    const res = await doFetch(url, {
+      method: opts?.method ?? "GET",
+      credentials: config.credentials ?? "same-origin",
+      headers,
+      body: opts?.json !== void 0 ? JSON.stringify(opts.json) : opts?.body
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => res.statusText);
+      throw new Error(`annotate REST ${res.status}: ${detail.slice(0, 300)}`);
+    }
+    const text = await res.text();
+    if (!text) return void 0;
+    const ct = res.headers.get("content-type") || "";
+    return ct.includes("json") ? JSON.parse(text) : text;
+  }
+  return {
+    getAccess: () => req(ep.access),
+    setAccess: (enabled) => req(ep.access, { method: "PUT", json: { enabled } }),
+    list: () => req(ep.list).then((r) => r ?? []),
+    save: (input) => req(ep.create, { method: "POST", json: input }),
+    async update(patch) {
+      const { id, ...rest } = patch;
+      await req(ep.item(id), { method: "PATCH", json: rest });
+    },
+    async remove(id) {
+      await req(ep.item(id), { method: "DELETE" });
+    },
+    async addReply(id, note) {
+      await req(ep.replies(id), { method: "POST", json: { note } });
+    },
+    clearResolved: () => req(ep.clearResolved, { method: "POST" }),
+    async uploadScreenshot(file, opts) {
+      const fd = new FormData();
+      fd.append("file", file);
+      if (opts?.visibility) fd.append("visibility", opts.visibility);
+      return req(ep.screenshots, { method: "POST", body: fd });
+    }
+  };
+}
+export {
+  createRestAdapter
+};

package/dist/supabase.d.ts

@@ -0,0 +1,31 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import { S as StorageAdapter } from './adapter-Cyqfwj6F.js';
+import './types-BLXmj4Oi.js';
+
+type SupabaseAdapterConfig = {
+    client: SupabaseClient;
+    /** Table name (default 'annotations'). */
+    table?: string;
+    /** Private storage bucket for screenshots (default 'annotations'). */
+    bucket?: string;
+    /** Single-row global toggle table (default 'annotate_settings'). */
+    settingsTable?: string;
+    /** Signed-URL lifetime for screenshots, seconds (default 3600). */
+    signedUrlTtl?: number;
+    /** Max rows fetched per list() call (default 1000). Keeps polling bounded on busy projects. */
+    listLimit?: number;
+    /** Is the current viewer an admin? A boolean, or a predicate over the resolved user.
+     *  Default: true when the auth user's `app_metadata.role === 'admin'` or `app_metadata.annotate_admin === true`
+     *  (must match backend/supabase/migration.sql's annotate_is_admin()). */
+    isAdmin?: boolean | ((user: ResolvedUser) => boolean | Promise<boolean>);
+    /** Override how the current user is resolved (default: supabase.auth.getUser()). */
+    currentUser?: () => Promise<ResolvedUser | null>;
+};
+type ResolvedUser = {
+    email?: string;
+    name?: string;
+    role?: string;
+};
+declare function createSupabaseAdapter(config: SupabaseAdapterConfig): StorageAdapter;
+
+export { type ResolvedUser, type SupabaseAdapterConfig, createSupabaseAdapter };

package/dist/supabase.js

@@ -0,0 +1,143 @@
+// src/adapters/supabase.ts
+function createSupabaseAdapter(config) {
+  const client = config.client;
+  const table = config.table ?? "annotations";
+  const bucket = config.bucket ?? "annotations";
+  const settingsTable = config.settingsTable ?? "annotate_settings";
+  const ttl = config.signedUrlTtl ?? 3600;
+  const listLimit = config.listLimit ?? 1e3;
+  const urlCache = /* @__PURE__ */ new Map();
+  async function resolveUser() {
+    if (config.currentUser) return await config.currentUser() ?? {};
+    const { data } = await client.auth.getUser();
+    const u = data.user;
+    if (!u) return {};
+    const md = u.user_metadata ?? {};
+    const am = u.app_metadata ?? {};
+    return {
+      email: u.email ?? md.email,
+      name: md.full_name || md.name || u.email || void 0,
+      role: am.role || md.role || void 0
+    };
+  }
+  async function resolveIsAdmin(user) {
+    if (typeof config.isAdmin === "boolean") return config.isAdmin;
+    if (typeof config.isAdmin === "function") return !!await config.isAdmin(user);
+    const { data } = await client.auth.getUser();
+    const am = data.user?.app_metadata ?? {};
+    return am.role === "admin" || am.annotate_admin === true;
+  }
+  async function uid() {
+    const { data } = await client.auth.getUser();
+    if (!data.user?.id) throw new Error("annotate: must be signed in to upload a screenshot");
+    return data.user.id;
+  }
+  const err = (e) => {
+    if (e?.message) throw new Error(e.message);
+  };
+  async function signPaths(rows) {
+    const now = Date.now();
+    const need = [];
+    for (const r of rows) {
+      if (!r.screenshot_path) continue;
+      const hit = urlCache.get(r.screenshot_path);
+      if (hit && hit.exp - now > 6e4) r.screenshot_url = hit.url;
+      else need.push(r.screenshot_path);
+    }
+    if (need.length) {
+      const { data } = await client.storage.from(bucket).createSignedUrls(need, ttl);
+      const byPath = new Map((data ?? []).map((d) => [d.path, d.signedUrl]));
+      const exp = now + ttl * 1e3;
+      for (const r of rows) {
+        if (r.screenshot_path && !r.screenshot_url) {
+          const url = byPath.get(r.screenshot_path) ?? null;
+          if (url) urlCache.set(r.screenshot_path, { url, exp });
+          r.screenshot_url = url;
+        }
+      }
+    }
+  }
+  return {
+    async getAccess() {
+      const me = await resolveUser();
+      const isAdmin = await resolveIsAdmin(me);
+      let enabled = false;
+      try {
+        const { data } = await client.from(settingsTable).select("value").eq("key", "enabled").maybeSingle();
+        if (data && data.value != null) enabled = data.value === true || data.value === "true";
+      } catch {
+      }
+      return { enabled, isAdmin, canUse: enabled || isAdmin, seeAll: isAdmin, me };
+    },
+    async setAccess(enabled) {
+      const { error } = await client.from(settingsTable).upsert({ key: "enabled", value: enabled }, { onConflict: "key" });
+      err(error);
+      return { message: enabled ? "Enabled for all users" : "ADMIN-only" };
+    },
+    async list() {
+      const { data, error } = await client.from(table).select("*").order("id", { ascending: false }).limit(listLimit);
+      err(error);
+      const rows = data ?? [];
+      await signPaths(rows);
+      return rows;
+    },
+    async save(input) {
+      const { data, error } = await client.from(table).insert({ ...input, status: "open" }).select("id").single();
+      err(error);
+      return { id: data.id };
+    },
+    async update(patch) {
+      const { id, ...rest } = patch;
+      const { error } = await client.from(table).update(rest).eq("id", id);
+      err(error);
+    },
+    async remove(id) {
+      const { data } = await client.from(table).select("screenshot_path").eq("id", id).maybeSingle();
+      const { error } = await client.from(table).delete().eq("id", id);
+      err(error);
+      const path = data?.screenshot_path;
+      if (path) {
+        urlCache.delete(path);
+        const { error: se } = await client.storage.from(bucket).remove([path]);
+        if (se) console.warn("[annotate] screenshot delete failed", se.message);
+      }
+    },
+    async addReply(id, note) {
+      const { error } = await client.rpc("annotate_add_reply", { p_id: id, p_note: note });
+      err(error);
+    },
+    async clearResolved() {
+      const { data } = await client.from(table).select("id, screenshot_path").in("status", ["done", "dismissed"]);
+      const rows = data ?? [];
+      const ids = rows.map((r) => r.id);
+      const paths = rows.map((r) => r.screenshot_path).filter(Boolean);
+      if (ids.length) {
+        const { error } = await client.from(table).delete().in("id", ids);
+        err(error);
+      }
+      if (paths.length) {
+        paths.forEach((p) => urlCache.delete(p));
+        const { error: se } = await client.storage.from(bucket).remove(paths);
+        if (se) console.warn("[annotate] screenshot cleanup failed", se.message);
+      }
+      return { message: `Cleared ${ids.length} resolved` };
+    },
+    async uploadScreenshot(file, opts) {
+      const vis = opts?.visibility === "public" ? "public" : "private";
+      const rand = Math.random().toString(36).slice(2, 8);
+      const path = `${vis}/${await uid()}/${Date.now()}-${rand}.png`;
+      const { error } = await client.storage.from(bucket).upload(path, file, { contentType: file.type || "image/png", upsert: false });
+      err(error);
+      return { path };
+    },
+    subscribe(onChange) {
+      const channel = client.channel(`annotate:${table}:${Math.random().toString(36).slice(2, 8)}`).on("postgres_changes", { event: "*", schema: "public", table }, () => onChange()).subscribe();
+      return () => {
+        void client.removeChannel(channel);
+      };
+    }
+  };
+}
+export {
+  createSupabaseAdapter
+};

package/dist/types-BLXmj4Oi.d.ts

@@ -0,0 +1,93 @@
+type AnnType = 'change' | 'add' | 'remove' | 'bug' | 'style' | 'question';
+type AnnPriority = 'low' | 'med' | 'high';
+type AnnStatus = 'open' | 'in_progress' | 'done' | 'dismissed';
+type AnnKind = 'pin' | 'shape';
+type AnnShape = 'rect' | 'arrow' | 'circle' | 'freehand';
+type AnnVisibility = 'public' | 'private';
+type AnnReply = {
+    note: string;
+    author?: string;
+    at?: string;
+};
+type AnnPoint = {
+    x: number;
+    y: number;
+};
+type AnnMeta = {
+    browser?: string;
+    os?: string;
+    device?: string;
+    viewport?: string;
+    screen?: string;
+    dpr?: number;
+    url?: string;
+    ua?: string;
+};
+type AnnLog = {
+    level: string;
+    text: string;
+    at?: string;
+};
+type AnnNetLog = {
+    method: string;
+    url: string;
+    status?: number;
+    ms?: number;
+    ok?: boolean;
+    at?: string;
+};
+type Annotation = {
+    id: number;
+    page_route: string;
+    page_title: string;
+    target_selector: string;
+    target_text: string;
+    pos_x: number;
+    pos_y: number;
+    viewport_w: number;
+    viewport_h: number;
+    note: string;
+    type: AnnType;
+    priority: AnnPriority;
+    status: AnnStatus;
+    screenshot_path?: string | null;
+    screenshot_url?: string | null;
+    replies?: AnnReply[];
+    created_by?: string;
+    created_at?: string;
+    updated_at?: string;
+    kind?: AnnKind;
+    shape_type?: AnnShape | null;
+    x2?: number | null;
+    y2?: number | null;
+    points?: AnnPoint[] | null;
+    color?: string | null;
+    visibility?: AnnVisibility;
+    created_by_role?: string | null;
+    created_by_name?: string | null;
+    styles?: Record<string, string> | null;
+    el_context?: string[] | null;
+    meta?: AnnMeta | null;
+    console_logs?: AnnLog[] | null;
+    network_logs?: AnnNetLog[] | null;
+    dom_snapshot?: string | null;
+};
+type NewAnnotation = Omit<Annotation, 'id' | 'status' | 'created_at' | 'updated_at' | 'screenshot_url' | 'created_by' | 'created_by_role' | 'created_by_name'> & {
+    screenshot_path?: string | null;
+};
+type AnnotationPatch = {
+    id: number;
+} & Partial<Pick<Annotation, 'note' | 'status' | 'type' | 'priority'>>;
+type AnnotateAccess = {
+    enabled: boolean;
+    isAdmin: boolean;
+    canUse: boolean;
+    seeAll: boolean;
+    me?: {
+        email?: string;
+        name?: string;
+        role?: string;
+    };
+};
+
+export type { AnnotateAccess as A, NewAnnotation as N, Annotation as a, AnnotationPatch as b, AnnVisibility as c, AnnKind as d, AnnShape as e, AnnType as f, AnnPriority as g, AnnStatus as h };