feedly-widget 0.1.0

package/dist/hooks/useAnnotations.d.ts

@@ -0,0 +1,30 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Anchor, Annotation, AnnotationStatus, AnnotationType, ShapeData, TesterRef } from '../types';
+type Args = {
+    supabase: SupabaseClient;
+    projectId: string;
+    testerId: string | null;
+    isAdmin: boolean;
+};
+export declare function useAnnotations({ supabase, projectId, testerId, isAdmin }: Args): {
+    annotations: Annotation[];
+    testers: TesterRef[];
+    loading: boolean;
+    save: (type: AnnotationType, shape: ShapeData, comment: string, anchor: Anchor | null, noteOffset: {
+        x: number;
+        y: number;
+    } | null) => Promise<Annotation | null>;
+    remove: (id: string) => Promise<boolean>;
+    updateShape: (id: string, shape: ShapeData) => Promise<boolean>;
+    updateComment: (id: string, comment: string, noteOffset: {
+        x: number;
+        y: number;
+    } | null) => Promise<boolean>;
+    setStatus: (annotationId: string, newStatus: AnnotationStatus, comment?: string) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+};
+export {};

package/dist/hooks/useAnnotationsList.d.ts

@@ -0,0 +1,21 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Annotation } from '../types';
+type Args = {
+    supabase: SupabaseClient;
+    projectId: string;
+    testerId: string | null;
+    isAdmin: boolean;
+    enabled: boolean;
+};
+export type AnnotationsByPage = {
+    pagePath: string;
+    pageUrl: string;
+    items: Annotation[];
+}[];
+export declare function useAnnotationsList({ supabase, projectId, testerId, isAdmin, enabled, }: Args): {
+    annotations: Annotation[];
+    grouped: AnnotationsByPage;
+    loading: boolean;
+    refresh: () => Promise<void>;
+};
+export {};

package/dist/hooks/useFlows.d.ts

@@ -0,0 +1,34 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Flow, FlowStep } from '../types';
+export type PersistedReplay = {
+    flowId: string;
+    stepIndex: number;
+    projectId: string;
+};
+export declare function loadReplayState(projectId: string): PersistedReplay | null;
+export declare function saveReplayState(s: PersistedReplay): void;
+export declare function clearReplayState(): void;
+export type PersistedRecording = {
+    projectId: string;
+    steps: FlowStep[];
+    startedAt: number;
+};
+export declare function loadRecordingState(projectId: string): PersistedRecording | null;
+export declare function saveRecordingState(s: PersistedRecording): void;
+export declare function clearRecordingState(): void;
+type Args = {
+    supabase: SupabaseClient;
+    projectId: string;
+    testerId: string | null;
+    isAdmin: boolean;
+    enabled: boolean;
+};
+export declare function useFlows({ supabase, projectId, testerId, isAdmin, enabled }: Args): {
+    flows: Flow[];
+    loading: boolean;
+    save: (steps: FlowStep[], name?: string) => Promise<Flow | null>;
+    remove: (id: string) => Promise<boolean>;
+    fetchOne: (flowId: string) => Promise<Flow | null>;
+    refresh: () => Promise<void>;
+};
+export {};

package/dist/hooks/useInvite.d.ts

@@ -0,0 +1,9 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+type State = 'checking' | 'allowed' | 'blocked';
+export declare function useInvite({ supabase, projectId, enabled, recheckKey, }: {
+    supabase: SupabaseClient;
+    projectId: string;
+    enabled: boolean;
+    recheckKey?: string | null;
+}): State;
+export {};

package/dist/hooks/useLocation.d.ts

@@ -0,0 +1,6 @@
+type Location = {
+    href: string;
+    pathname: string;
+};
+export declare function useLocation(): Location;
+export {};

package/dist/hooks/useSession.d.ts

@@ -0,0 +1,8 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Project } from '../types';
+type SessionState = {
+    loading: boolean;
+    project: Project | null;
+};
+export declare function useSession(supabase: SupabaseClient, projectId: string): SessionState;
+export {};

package/dist/hooks/useTester.d.ts

@@ -0,0 +1,16 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { StoredTesterIdentity } from '../types';
+export declare function useTester(supabase: SupabaseClient, projectId: string): {
+    register: (name: string, email?: string) => Promise<StoredTesterIdentity | null>;
+    sendCrossDeviceLink: (email: string) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    claimAdmin: () => Promise<void>;
+    signOut: () => void;
+    identity: StoredTesterIdentity | null;
+    isAdmin: boolean;
+    initializing: boolean;
+};

package/dist/hooks/useUnseen.d.ts

@@ -0,0 +1,9 @@
+import type { Annotation } from '../types';
+export declare function useUnseen({ projectId, annotations, currentTesterId, }: {
+    projectId: string;
+    annotations: Annotation[];
+    currentTesterId: string | null;
+}): {
+    hasUnseen: boolean;
+    markSeen: () => void;
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { FeedlyAPI } from './types';
+declare const Feedly: FeedlyAPI;
+export default Feedly;
+export { Feedly };
+export type { FeedlyInitOptions, FeedlyAPI } from './types';

package/dist/lib/anchor.d.ts

@@ -0,0 +1,27 @@
+import type { Anchor, Annotation, ShapeData } from '../types';
+export declare function computeSelector(el: Element): string;
+export type DeepHit = {
+    kind: 'parent';
+    el: Element;
+} | {
+    kind: 'iframe';
+    iframe: HTMLIFrameElement;
+    inner: Element;
+} | {
+    kind: 'blocked-iframe';
+} | null;
+export declare function findElementDeep(vx: number, vy: number): DeepHit;
+export declare function findElementUnderViewportPoint(vx: number, vy: number): Element | null;
+export type BuildAnchorResult = {
+    ok: true;
+    anchor: Anchor | null;
+} | {
+    ok: false;
+    reason: 'blocked-iframe';
+};
+export declare function tryBuildAnchor(shape: ShapeData): BuildAnchorResult;
+export declare function buildAnchor(shape: ShapeData): Anchor | null;
+export declare function isAnchorBroken(anchor: Anchor | null): boolean;
+export declare function resolveAnchoredShape(annotation: Annotation): ShapeData;
+export declare function isAnchorFixed(anchor: Anchor | null): boolean;
+export declare function anchorIframe(anchor: Anchor | null): HTMLIFrameElement | null;

package/dist/lib/broadcast.d.ts

@@ -0,0 +1,21 @@
+export declare function annotationsTopic(projectId: string): string;
+export declare function testersTopic(projectId: string): string;
+export declare const BROADCAST_EVENT = "feedly";
+export type AnnotationBroadcast = {
+    t: 'ann';
+    op: 'insert' | 'update';
+    id: string;
+    page_path: string;
+} | {
+    t: 'ann';
+    op: 'delete';
+    id: string;
+} | {
+    t: 'ann';
+    op: 'clear';
+};
+export type TesterBroadcast = {
+    t: 'tester';
+    op: 'update';
+    id: string;
+};

package/dist/lib/colors.d.ts

@@ -0,0 +1,2 @@
+export declare const TESTER_COLORS: readonly ["#E8593C", "#1D9E75", "#7F77DD", "#D4537E", "#378ADD", "#BA7517", "#639922", "#888780"];
+export declare function pickColor(existingTesterCount: number): string;

package/dist/lib/screenCapture.d.ts

@@ -0,0 +1,10 @@
+import type { BBox } from '../types';
+export declare function stopCapture(): void;
+export declare function highFidelitySupported(): boolean;
+export declare function bboxNeedsHighFidelity(bbox: BBox): boolean;
+export type HighFidelityResult = {
+    dataUrl: string;
+} | null;
+export declare function captureViaScreenShare(bbox: BBox, opts?: {
+    allowScroll?: boolean;
+}): Promise<HighFidelityResult>;

package/dist/lib/shape.d.ts

@@ -0,0 +1,16 @@
+import type { Point, ShapeData } from '../types';
+export declare function smoothPath(points: Point[]): string;
+export declare function bboxFromPoints(points: Point[]): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export declare function bboxOf(shape: ShapeData): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export declare function anchorOf(shape: ShapeData): Point;
+export declare function translateShape(shape: ShapeData, dx: number, dy: number): ShapeData;

package/dist/lib/snapshot.d.ts

@@ -0,0 +1,37 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+export declare const BUCKET = "feedback-snapshots";
+type CaptureArgs = {
+    supabase: SupabaseClient;
+    projectId: string;
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    shouldProceed?: () => boolean;
+};
+export type CaptureResult = {
+    path: string;
+    viewport: {
+        vw: number;
+        vh: number;
+        dpr: number;
+    };
+    capturedAt: string;
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        pads: {
+            l: number;
+            t: number;
+            r: number;
+            b: number;
+        };
+    };
+};
+export declare function captureAnnotationSnapshot(args: CaptureArgs): Promise<CaptureResult | null>;
+export declare function snapshotPublicUrl(supabase: SupabaseClient, path: string): string;
+export {};

package/dist/lib/softNavigation.d.ts

@@ -0,0 +1,21 @@
+type Args = {
+    /** id of the widget host element so we can detach + re-attach across swaps */
+    hostId: string;
+};
+export declare function installHistoryListeners(): void;
+export declare function installSoftNavigation({ hostId }: Args): () => void;
+export declare function uninstallSoftNavigation(): void;
+/** Subscribe a listener to soft-navigation events. Returns an unsubscribe fn. */
+export declare function onSoftNavigate(handler: () => void): () => void;
+/**
+ * Programmatically navigate to a URL. Prefers soft-navigation (no full
+ * page reload, widget state preserved) when `installSoftNavigation` has
+ * been called; otherwise falls back to a real navigation.
+ *
+ * Used by Flow replay: when the dev picks a flow recorded on a different
+ * page, we take them there first.
+ */
+export declare function navigateTo(url: string): Promise<void>;
+/** Returns true when same-origin URL matches the current location's URL. */
+export declare function urlsMatchSamePage(a: string, b: string): boolean;
+export {};

package/dist/lib/storage.d.ts

@@ -0,0 +1,6 @@
+import type { StoredTesterIdentity } from '../types';
+export declare function loadIdentity(projectId: string): StoredTesterIdentity | null;
+export declare function saveIdentity(identity: StoredTesterIdentity): void;
+export declare function clearIdentity(): void;
+export declare function savePinIntent(projectId: string, annotationId: string): void;
+export declare function consumePinIntent(projectId: string): string | null;

package/dist/lib/supabase.d.ts

@@ -0,0 +1,10 @@
+import { type SupabaseClient } from '@supabase/supabase-js';
+export declare function getDeviceId(): string;
+export declare function getSupabase(url: string, anonKey: string): SupabaseClient;
+export declare function resetSupabase(): void;
+export declare function sendMagicLink(supabase: SupabaseClient, email: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/lib/tech.d.ts

@@ -0,0 +1,3 @@
+import type { TechDetails } from '../types';
+export declare function captureTechDetails(): TechDetails;
+export declare function generateDummyTicket(): string;

package/dist/types.d.ts

@@ -0,0 +1,194 @@
+export type FeedlyInitOptions = {
+    projectId: string;
+    /** Override the Supabase URL (otherwise baked in at build time). */
+    supabaseUrl?: string;
+    /** Override the Supabase anon key (otherwise baked in at build time). */
+    supabaseAnonKey?: string;
+    /**
+     * Intercept same-origin link clicks and swap page content without a full
+     * reload, so the widget UI (F button, toolbar, comment list) stays mounted
+     * across navigations. Default false — only safe to enable on apps that
+     * don't already have their own SPA router (Next.js, React Router, etc.).
+     */
+    smoothNavigation?: boolean;
+    /**
+     * Production mode: render nothing for visitors who haven't been invited.
+     * The widget will only mount for devices that have either (a) opened a
+     * `?feedly_invite=<token>` URL at least once OR (b) already have a tester
+     * identity in localStorage from a prior redemption.
+     *
+     * Default false (every visitor on a session_active project sees the F —
+     * the right thing for closed alpha/dev). Set to true before going live.
+     */
+    requireInvite?: boolean;
+    /**
+     * z-index for the pins-only layer. Pins sit at this level: above the
+     * host page's normal content but below any positioned element with a
+     * higher z-index — modals, dropdowns, toasts, sticky headers, etc.
+     *
+     * Default `0`. This works for every modal library out there because
+     * they all use a positive z-index for their overlay (Tailwind UI = 50,
+     * Bootstrap = 1050, Material UI = 1300, Ant Design = 1000, Headless UI
+     * portals = 50, etc.). At z-index 0 the pins are above unstyled body
+     * content but below anything explicitly stacked above zero.
+     *
+     * Override only if you specifically want pins to render over certain
+     * positioned page content (e.g., a sticky header at z-10 that you'd
+     * rather pins float on top of).
+     *
+     * The rest of the widget UI (F button, toolbar, sticky notes, drawing
+     * SVG, spotlight) stays at the max-z-index UI layer and is always on
+     * top — including over modals.
+     */
+    pinsZIndex?: number;
+};
+export type FeedlyAPI = {
+    init: (opts: FeedlyInitOptions) => void;
+    destroy: () => void;
+};
+export type AnnotationType = 'circle' | 'arrow' | 'rectangle';
+export type ShapeData = {
+    kind: 'circle';
+    path: string;
+    bbox: BBox;
+} | {
+    kind: 'arrow';
+    from: Point;
+    to: Point;
+} | {
+    kind: 'rectangle';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type Point = {
+    x: number;
+    y: number;
+};
+export type BBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type Tester = {
+    id: string;
+    project_id: string;
+    name: string;
+    device_id: string;
+    color: string;
+    is_admin?: boolean;
+    email?: string | null;
+    auth_user_id?: string | null;
+    created_at?: string;
+};
+export type TesterRef = {
+    id: string;
+    name: string;
+    color: string;
+};
+export type Project = {
+    id: string;
+    name: string;
+    session_active: boolean;
+};
+export type Anchor = {
+    selector: string;
+    origin: Point;
+    iframeContent?: {
+        innerSelector: string;
+    };
+};
+export type AnnotationStatus = 'open' | 'fixed' | 'confirmed' | 'reopened';
+export type TechDetails = {
+    user_agent: string;
+    platform: string;
+    language: string;
+    page_title: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    screen: {
+        width: number;
+        height: number;
+    };
+    device_pixel_ratio: number;
+    browser?: {
+        name: string;
+        version: string;
+    };
+    os?: {
+        name: string;
+        version: string;
+    };
+};
+export type StatusHistoryEntry = {
+    from: AnnotationStatus;
+    to: AnnotationStatus;
+    by_tester_id: string;
+    by_tester_name: string;
+    by_tester_color: string;
+    at: string;
+    comment: string | null;
+};
+export type Annotation = {
+    id: string;
+    project_id: string;
+    tester_id: string;
+    page_url: string;
+    page_path: string;
+    type: AnnotationType;
+    shape_data: ShapeData;
+    comment: string | null;
+    created_at: string;
+    anchor: Anchor | null;
+    status: AnnotationStatus;
+    status_history: StatusHistoryEntry[];
+    tech_details: TechDetails | null;
+    jira_ticket: string | null;
+    note_offset: Point | null;
+    snapshot_path: string | null;
+    snapshot_bbox: (BBox & {
+        pads?: {
+            l: number;
+            t: number;
+            r: number;
+            b: number;
+        };
+    }) | null;
+    snapshot_viewport: {
+        vw: number;
+        vh: number;
+        dpr: number;
+    } | null;
+    snapshot_captured_at: string | null;
+    tester?: TesterRef;
+};
+export type StoredTesterIdentity = {
+    id: string;
+    name: string;
+    color: string;
+    projectId: string;
+};
+export type FlowStep = {
+    step: number;
+    page_url: string;
+    page_path: string;
+    action: 'click';
+    element_selector: string;
+    element_text: string;
+    ts: number;
+    note: string | null;
+    annotation: null;
+};
+export type Flow = {
+    id: string;
+    project_id: string;
+    tester_id: string;
+    name: string;
+    steps: FlowStep[];
+    created_at: string;
+    tester?: TesterRef;
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "feedly-widget",
+  "version": "0.1.0",
+  "description": "Visual feedback annotation widget. Drop into any web app and let testers annotate live.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/feedly-widget.cjs.js",
+  "module": "./dist/feedly-widget.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/feedly-widget.es.js",
+      "require": "./dist/feedly-widget.cjs.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.45.0",
+    "modern-screenshot": "^4.7.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "autoprefixer": "^10.4.19",
+    "postcss": "^8.4.39",
+    "tailwindcss": "^3.4.7",
+    "typescript": "^5.5.4",
+    "vite": "^5.3.5"
+  }
+}