feedtack 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trillium Smith
+
+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

@@ -0,0 +1,134 @@
+# feedtack
+
+> Click anywhere. Drop a pin. Get a payload a developer can act on.
+
+**feedtack** is a drop-in React feedback overlay. Non-technical stakeholders click anywhere on a page, leave a comment, and feedtack emits a structured JSON payload so complete that an LLM can attempt a first-pass fix before consuming developer hours.
+
+## Install
+
+```bash
+npm install feedtack
+# or
+pnpm add feedtack
+```
+
+## Quick start
+
+```tsx
+import { FeedtackProvider } from 'feedtack/react'
+import { ConsoleAdapter } from 'feedtack'
+
+export default function App() {
+  return (
+    <FeedtackProvider
+      adapter={new ConsoleAdapter()}
+      currentUser={{ id: 'u1', name: 'Trillium', role: 'admin' }}
+    >
+      <YourApp />
+    </FeedtackProvider>
+  )
+}
+```
+
+## Production — webhook adapter
+
+```tsx
+import { FeedtackProvider } from 'feedtack/react'
+import { WebhookAdapter } from 'feedtack'
+
+const adapter = new WebhookAdapter({
+  submitUrl: 'https://your-app.com/api/feedtack',
+  updateUrl: 'https://your-app.com/api/feedtack/update', // optional
+  loadFeedback: async (filter) => {
+    const res = await fetch(`/api/feedtack?pathname=${filter?.pathname ?? ''}`)
+    return res.json()
+  },
+})
+
+export default function App() {
+  return (
+    <FeedtackProvider
+      adapter={adapter}
+      currentUser={{ id: 'u1', name: 'Alice', role: 'designer', avatarUrl: '/alice.jpg' }}
+      hotkey="p"        // default: Shift+P
+      adminOnly         // only show button to users with role === 'admin'
+      onError={console.error}
+    >
+      <YourApp />
+    </FeedtackProvider>
+  )
+}
+```
+
+## Custom adapter
+
+```ts
+import type { FeedtackAdapter } from 'feedtack'
+
+class MySupabaseAdapter implements FeedtackAdapter {
+  async submit(payload) { /* POST to supabase */ }
+  async reply(feedbackId, reply) { /* insert reply */ }
+  async resolve(feedbackId, resolution) { /* update resolved */ }
+  async archive(feedbackId, userId) { /* insert archive record */ }
+  async loadFeedback(filter) { /* select from supabase */ }
+}
+```
+
+## The payload
+
+Every pin emits a versioned JSON payload:
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "id": "ft_01j...",
+  "timestamp": "2026-04-09T13:42:00.000Z",
+  "submittedBy": { "id": "u1", "name": "Alice", "role": "designer" },
+  "comment": "This button doesn't do anything",
+  "sentiment": "dissatisfied",
+  "pins": [{
+    "index": 1,
+    "color": "#ef4444",
+    "x": 420, "y": 812,
+    "xPct": 29.2, "yPct": 78.4,
+    "target": {
+      "selector": "#submit-btn",
+      "best_effort": false,
+      "tagName": "BUTTON",
+      "textContent": "Place Order",
+      "attributes": { "id": "submit-btn", "disabled": "true" },
+      "boundingRect": { "x": 420, "y": 812, "width": 200, "height": 44 }
+    }
+  }],
+  "page": { "url": "https://app.example.com/checkout", "pathname": "/checkout", "title": "Checkout" },
+  "viewport": { "width": 1440, "height": 900, "scrollX": 0, "scrollY": 812, "devicePixelRatio": 2 },
+  "device": { "userAgent": "Mozilla/5.0...", "platform": "MacIntel", "touchEnabled": false }
+}
+```
+
+## `useFeedtack` hook
+
+```tsx
+import { useFeedtack } from 'feedtack/react'
+
+function MyButton() {
+  const { activatePinMode, isPinModeActive } = useFeedtack()
+  return <button onClick={activatePinMode}>{isPinModeActive ? 'Cancel' : 'Give Feedback'}</button>
+}
+```
+
+## What feedtack does NOT do
+
+- LLM triage or routing (downstream concern — feedtack emits, others act)
+- Developer dashboard or inbox
+- Screenshot annotation
+
+## ICEBOX
+
+- Script tag CDN distribution
+- Next.js plugin
+- `allowedCaptures` config for scoping DOM access
+
+## License
+
+MIT

package/dist/adapter-DvQFXmyi.d.ts

@@ -0,0 +1,125 @@
+declare const SCHEMA_VERSION = "1.0.0";
+interface FeedtackUser {
+    /** Unique identifier — used for attribution across pins, replies, resolutions, archives */
+    id: string;
+    /** Display name shown in threads */
+    name: string;
+    /** Controls UI access, e.g. 'admin' | 'designer' | 'stakeholder' | 'partner' */
+    role: string;
+    /** Shown in reply threads next to name */
+    avatarUrl?: string;
+    /** Reserved for future notification use */
+    email?: string;
+}
+interface FeedtackBoundingRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface FeedtackPinTarget {
+    /** CSS selector path to the clicked element */
+    selector: string;
+    /** True when no stable selector was found — downstream consumers should not rely on selector for automated targeting */
+    best_effort: boolean;
+    tagName: string;
+    /** Trimmed text content of the element, max 200 chars */
+    textContent: string;
+    attributes: Record<string, string>;
+    boundingRect: FeedtackBoundingRect;
+}
+interface FeedtackPin {
+    /** 1-based index within the session */
+    index: number;
+    /** Hex color chosen by user from the fixed palette */
+    color: string;
+    /** Document-relative X coordinate (clientX + scrollX) */
+    x: number;
+    /** Document-relative Y coordinate (clientY + scrollY) */
+    y: number;
+    /** X as percentage of document width */
+    xPct: number;
+    /** Y as percentage of document height */
+    yPct: number;
+    target: FeedtackPinTarget;
+}
+interface FeedtackPageMeta {
+    url: string;
+    pathname: string;
+    title: string;
+}
+interface FeedtackViewportMeta {
+    width: number;
+    height: number;
+    scrollX: number;
+    scrollY: number;
+    devicePixelRatio: number;
+}
+interface FeedtackDeviceMeta {
+    userAgent: string;
+    platform: string;
+    touchEnabled: boolean;
+}
+type FeedtackSentiment = 'satisfied' | 'dissatisfied' | null;
+interface FeedtackPayload {
+    schemaVersion: string;
+    /** Unique feedback ID, e.g. ft_01j... */
+    id: string;
+    /** ISO 8601 UTC */
+    timestamp: string;
+    submittedBy: FeedtackUser;
+    comment: string;
+    sentiment: FeedtackSentiment;
+    /** At least one pin required */
+    pins: FeedtackPin[];
+    page: FeedtackPageMeta;
+    viewport: FeedtackViewportMeta;
+    device: FeedtackDeviceMeta;
+}
+interface FeedtackReply {
+    id: string;
+    feedbackId: string;
+    author: FeedtackUser;
+    body: string;
+    /** ISO 8601 UTC */
+    timestamp: string;
+}
+interface FeedtackResolution {
+    feedbackId: string;
+    resolvedBy: FeedtackUser;
+    /** ISO 8601 UTC */
+    timestamp: string;
+}
+interface FeedtackArchive {
+    feedbackId: string;
+    archivedBy: FeedtackUser;
+    /** ISO 8601 UTC */
+    timestamp: string;
+}
+interface FeedbackItem {
+    payload: FeedtackPayload;
+    replies: FeedtackReply[];
+    resolutions: FeedtackResolution[];
+    archives: FeedtackArchive[];
+}
+interface FeedtackFilter {
+    url?: string;
+    pathname?: string;
+    userId?: string;
+}
+
+/** Plugin contract — implement this interface to create a custom feedtack backend */
+interface FeedtackAdapter {
+    /** Submit new feedback payload */
+    submit(payload: FeedtackPayload): Promise<void>;
+    /** Post a reply to an existing feedback item */
+    reply(feedbackId: string, reply: Omit<FeedtackReply, 'id' | 'feedbackId'>): Promise<void>;
+    /** Mark a feedback item as resolved */
+    resolve(feedbackId: string, resolution: Omit<FeedtackResolution, 'feedbackId'>): Promise<void>;
+    /** Archive a feedback item for a specific user */
+    archive(feedbackId: string, userId: string): Promise<void>;
+    /** Load persisted feedback items, optionally filtered */
+    loadFeedback(filter?: FeedtackFilter): Promise<FeedbackItem[]>;
+}
+
+export { type FeedtackAdapter as F, SCHEMA_VERSION as S, type FeedtackPayload as a, type FeedtackReply as b, type FeedtackResolution as c, type FeedtackFilter as d, type FeedbackItem as e, type FeedtackPinTarget as f, type FeedtackDeviceMeta as g, type FeedtackPageMeta as h, type FeedtackViewportMeta as i, type FeedtackArchive as j, type FeedtackBoundingRect as k, type FeedtackPin as l, type FeedtackSentiment as m, type FeedtackUser as n };

package/dist/chunk-VSVTP7O5.js

@@ -0,0 +1,105 @@
+// src/types/payload.ts
+var SCHEMA_VERSION = "1.0.0";
+
+// src/capture/target.ts
+function getCSSSelector(element) {
+  const parts = [];
+  let current = element;
+  while (current && current !== document.body) {
+    let selector = current.tagName.toLowerCase();
+    const parent = current.parentElement;
+    if (parent) {
+      const siblings = Array.from(parent.children).filter(
+        (c) => c.tagName === current.tagName
+      );
+      if (siblings.length > 1) {
+        const index = siblings.indexOf(current) + 1;
+        selector += `:nth-of-type(${index})`;
+      }
+    }
+    parts.unshift(selector);
+    current = current.parentElement;
+  }
+  return parts.join(" > ");
+}
+function getTargetMeta(element) {
+  const id = element.getAttribute("id");
+  const testId = element.getAttribute("data-testid");
+  let selector;
+  let best_effort;
+  if (id) {
+    selector = `#${id}`;
+    best_effort = false;
+  } else if (testId) {
+    selector = `[data-testid="${testId}"]`;
+    best_effort = false;
+  } else {
+    selector = getCSSSelector(element);
+    best_effort = true;
+  }
+  const rect = element.getBoundingClientRect();
+  const attrs = {};
+  for (const attr of Array.from(element.attributes)) {
+    attrs[attr.name] = attr.value;
+  }
+  return {
+    selector,
+    best_effort,
+    tagName: element.tagName,
+    textContent: (element.textContent ?? "").trim().slice(0, 200),
+    attributes: attrs,
+    boundingRect: {
+      x: rect.x,
+      y: rect.y,
+      width: rect.width,
+      height: rect.height
+    }
+  };
+}
+
+// src/capture/meta.ts
+function getViewportMeta() {
+  return {
+    width: window.innerWidth,
+    height: window.innerHeight,
+    scrollX: window.scrollX,
+    scrollY: window.scrollY,
+    devicePixelRatio: window.devicePixelRatio
+  };
+}
+function getPageMeta() {
+  return {
+    url: window.location.href,
+    pathname: window.location.pathname,
+    title: document.title
+  };
+}
+function getDeviceMeta() {
+  return {
+    userAgent: navigator.userAgent,
+    platform: navigator.platform,
+    touchEnabled: navigator.maxTouchPoints > 0
+  };
+}
+function getPinCoords(event) {
+  const x = event.clientX + window.scrollX;
+  const y = event.clientY + window.scrollY;
+  const docWidth = document.documentElement.scrollWidth;
+  const docHeight = document.documentElement.scrollHeight;
+  return {
+    x,
+    y,
+    xPct: Number((x / docWidth * 100).toFixed(2)),
+    yPct: Number((y / docHeight * 100).toFixed(2))
+  };
+}
+
+export {
+  SCHEMA_VERSION,
+  getCSSSelector,
+  getTargetMeta,
+  getViewportMeta,
+  getPageMeta,
+  getDeviceMeta,
+  getPinCoords
+};

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { F as FeedtackAdapter, a as FeedtackPayload, b as FeedtackReply, c as FeedtackResolution, d as FeedtackFilter, e as FeedbackItem, f as FeedtackPinTarget, g as FeedtackDeviceMeta, h as FeedtackPageMeta, i as FeedtackViewportMeta } from './adapter-DvQFXmyi.js';
+export { j as FeedtackArchive, k as FeedtackBoundingRect, l as FeedtackPin, m as FeedtackSentiment, n as FeedtackUser, S as SCHEMA_VERSION } from './adapter-DvQFXmyi.js';
+
+/** Development adapter — logs all operations to the browser console */
+declare class ConsoleAdapter implements FeedtackAdapter {
+    submit(payload: FeedtackPayload): Promise<void>;
+    reply(feedbackId: string, reply: Omit<FeedtackReply, 'id' | 'feedbackId'>): Promise<void>;
+    resolve(feedbackId: string, resolution: Omit<FeedtackResolution, 'feedbackId'>): Promise<void>;
+    archive(feedbackId: string, userId: string): Promise<void>;
+    loadFeedback(_filter?: FeedtackFilter): Promise<FeedbackItem[]>;
+}
+
+interface WebhookAdapterConfig {
+    /** URL to POST new feedback payloads to */
+    submitUrl: string;
+    /** URL to POST reply/resolve/archive state updates to */
+    updateUrl?: string;
+    /** Required: async function that returns persisted feedback items */
+    loadFeedback: (filter?: FeedtackFilter) => Promise<FeedbackItem[]>;
+}
+/** Production adapter — POSTs feedback as JSON to a webhook endpoint */
+declare class WebhookAdapter implements FeedtackAdapter {
+    private config;
+    constructor(config: WebhookAdapterConfig);
+    private post;
+    submit(payload: FeedtackPayload): Promise<void>;
+    reply(feedbackId: string, reply: Omit<FeedtackReply, 'id' | 'feedbackId'>): Promise<void>;
+    resolve(feedbackId: string, resolution: Omit<FeedtackResolution, 'feedbackId'>): Promise<void>;
+    archive(feedbackId: string, userId: string): Promise<void>;
+    loadFeedback(filter?: FeedtackFilter): Promise<FeedbackItem[]>;
+}
+
+/** Build shortest unique CSS selector for an element */
+declare function getCSSSelector(element: Element): string;
+/** Capture DOM target metadata at the clicked element */
+declare function getTargetMeta(element: Element): FeedtackPinTarget;
+
+declare function getViewportMeta(): FeedtackViewportMeta;
+declare function getPageMeta(): FeedtackPageMeta;
+declare function getDeviceMeta(): FeedtackDeviceMeta;
+declare function getPinCoords(event: MouseEvent): {
+    x: number;
+    y: number;
+    xPct: number;
+    yPct: number;
+};
+
+export { ConsoleAdapter, FeedbackItem, FeedtackAdapter, FeedtackDeviceMeta, FeedtackFilter, FeedtackPageMeta, FeedtackPayload, FeedtackPinTarget, FeedtackReply, FeedtackResolution, FeedtackViewportMeta, WebhookAdapter, type WebhookAdapterConfig, getCSSSelector, getDeviceMeta, getPageMeta, getPinCoords, getTargetMeta, getViewportMeta };

package/dist/index.js

@@ -0,0 +1,80 @@
+import {
+  SCHEMA_VERSION,
+  getCSSSelector,
+  getDeviceMeta,
+  getPageMeta,
+  getPinCoords,
+  getTargetMeta,
+  getViewportMeta
+} from "./chunk-VSVTP7O5.js";
+
+// src/adapters/ConsoleAdapter.ts
+var ConsoleAdapter = class {
+  async submit(payload) {
+    console.log("[feedtack] submit", payload);
+  }
+  async reply(feedbackId, reply) {
+    console.log("[feedtack] reply", { feedbackId, reply });
+  }
+  async resolve(feedbackId, resolution) {
+    console.log("[feedtack] resolve", { feedbackId, resolution });
+  }
+  async archive(feedbackId, userId) {
+    console.log("[feedtack] archive", { feedbackId, userId });
+  }
+  async loadFeedback(_filter) {
+    console.log("[feedtack] loadFeedback \u2014 ConsoleAdapter returns empty array");
+    return [];
+  }
+};
+
+// src/adapters/WebhookAdapter.ts
+var WebhookAdapter = class {
+  constructor(config) {
+    this.config = config;
+  }
+  async post(url, body) {
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      });
+    } catch (err) {
+      throw new Error(`[feedtack] Network error: ${err.message}`);
+    }
+    if (!response.ok) {
+      throw new Error(`[feedtack] Webhook responded with ${response.status}`);
+    }
+  }
+  async submit(payload) {
+    await this.post(this.config.submitUrl, payload);
+  }
+  async reply(feedbackId, reply) {
+    const url = this.config.updateUrl ?? this.config.submitUrl;
+    await this.post(url, { type: "reply", feedbackId, ...reply });
+  }
+  async resolve(feedbackId, resolution) {
+    const url = this.config.updateUrl ?? this.config.submitUrl;
+    await this.post(url, { type: "resolve", feedbackId, ...resolution });
+  }
+  async archive(feedbackId, userId) {
+    const url = this.config.updateUrl ?? this.config.submitUrl;
+    await this.post(url, { type: "archive", feedbackId, userId });
+  }
+  async loadFeedback(filter) {
+    return this.config.loadFeedback(filter);
+  }
+};
+export {
+  ConsoleAdapter,
+  SCHEMA_VERSION,
+  WebhookAdapter,
+  getCSSSelector,
+  getDeviceMeta,
+  getPageMeta,
+  getPinCoords,
+  getTargetMeta,
+  getViewportMeta
+};

package/dist/react/index.d.ts

@@ -0,0 +1,26 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { F as FeedtackAdapter, n as FeedtackUser } from '../adapter-DvQFXmyi.js';
+
+interface FeedtackProviderProps {
+    children: React.ReactNode;
+    adapter: FeedtackAdapter;
+    currentUser: FeedtackUser;
+    /** Keyboard shortcut to toggle pin mode. Default: 'p' (Shift+P) */
+    hotkey?: string;
+    /** Only show the activation button for users whose role is in this list */
+    adminOnly?: boolean;
+    onError?: (err: Error) => void;
+}
+declare function FeedtackProvider({ children, adapter, currentUser, hotkey, adminOnly, onError }: FeedtackProviderProps): react_jsx_runtime.JSX.Element;
+
+interface FeedtackContextValue {
+    activatePinMode: () => void;
+    deactivatePinMode: () => void;
+    isPinModeActive: boolean;
+}
+
+/** Hook for host app to programmatically control feedtack */
+declare function useFeedtack(): FeedtackContextValue;
+
+export { FeedtackProvider, useFeedtack };

package/dist/react/index.js

@@ -0,0 +1,557 @@
+import {
+  SCHEMA_VERSION,
+  getDeviceMeta,
+  getPageMeta,
+  getPinCoords,
+  getTargetMeta,
+  getViewportMeta
+} from "../chunk-VSVTP7O5.js";
+
+// src/react/FeedtackProvider.tsx
+import { useCallback, useEffect, useRef, useState } from "react";
+
+// src/react/context.ts
+import { createContext, useContext } from "react";
+var FeedtackContext = createContext(null);
+function useFeedtackContext() {
+  const ctx = useContext(FeedtackContext);
+  if (!ctx) throw new Error("useFeedtack must be used inside <FeedtackProvider>");
+  return ctx;
+}
+
+// src/ui/styles.ts
+var FEEDTACK_STYLES = `
+  #feedtack-root * {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+    font-family: system-ui, -apple-system, sans-serif;
+    line-height: 1.5;
+  }
+
+  .feedtack-btn {
+    position: fixed;
+    bottom: 24px;
+    right: 24px;
+    z-index: 2147483640;
+    background: #1a1a1a;
+    color: #fff;
+    border: none;
+    border-radius: 8px;
+    padding: 8px 14px;
+    font-size: 13px;
+    font-weight: 500;
+    cursor: pointer;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.25);
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    transition: background 0.15s;
+  }
+
+  .feedtack-btn:hover {
+    background: #333;
+  }
+
+  .feedtack-btn.active {
+    background: #2563eb;
+  }
+
+  .feedtack-crosshair * {
+    cursor: crosshair !important;
+  }
+
+  .feedtack-pin-marker {
+    position: absolute;
+    z-index: 2147483641;
+    width: 24px;
+    height: 24px;
+    border-radius: 50% 50% 50% 0;
+    transform: rotate(-45deg) translate(-50%, -50%);
+    border: 2px solid rgba(255,255,255,0.8);
+    box-shadow: 0 2px 6px rgba(0,0,0,0.3);
+    cursor: pointer;
+    pointer-events: all;
+  }
+
+  .feedtack-pin-badge {
+    position: absolute;
+    top: -4px;
+    right: -4px;
+    width: 10px;
+    height: 10px;
+    background: #f59e0b;
+    border-radius: 50%;
+    border: 1.5px solid #fff;
+  }
+
+  .feedtack-color-picker {
+    display: flex;
+    gap: 6px;
+    padding: 8px;
+    background: #fff;
+    border-radius: 8px;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+    position: fixed;
+    bottom: 72px;
+    right: 24px;
+    z-index: 2147483641;
+  }
+
+  .feedtack-color-swatch {
+    width: 20px;
+    height: 20px;
+    border-radius: 50%;
+    border: 2px solid transparent;
+    cursor: pointer;
+    transition: transform 0.1s;
+  }
+
+  .feedtack-color-swatch.selected {
+    border-color: #1a1a1a;
+    transform: scale(1.15);
+  }
+
+  .feedtack-form {
+    position: absolute;
+    z-index: 2147483642;
+    background: #fff;
+    border-radius: 10px;
+    box-shadow: 0 4px 20px rgba(0,0,0,0.18);
+    padding: 16px;
+    width: 280px;
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+  }
+
+  .feedtack-form textarea {
+    width: 100%;
+    border: 1.5px solid #e5e7eb;
+    border-radius: 6px;
+    padding: 8px;
+    font-size: 13px;
+    resize: vertical;
+    min-height: 80px;
+    outline: none;
+  }
+
+  .feedtack-form textarea:focus {
+    border-color: #2563eb;
+  }
+
+  .feedtack-form textarea.error {
+    border-color: #ef4444;
+  }
+
+  .feedtack-error-msg {
+    font-size: 12px;
+    color: #ef4444;
+  }
+
+  .feedtack-sentiment {
+    display: flex;
+    gap: 8px;
+  }
+
+  .feedtack-sentiment button {
+    flex: 1;
+    padding: 6px 10px;
+    border: 1.5px solid #e5e7eb;
+    border-radius: 6px;
+    background: #fff;
+    font-size: 12px;
+    cursor: pointer;
+    transition: all 0.1s;
+  }
+
+  .feedtack-sentiment button.selected {
+    border-color: #2563eb;
+    background: #eff6ff;
+    color: #2563eb;
+  }
+
+  .feedtack-form-actions {
+    display: flex;
+    gap: 8px;
+    justify-content: flex-end;
+  }
+
+  .feedtack-btn-cancel {
+    padding: 6px 12px;
+    border: 1.5px solid #e5e7eb;
+    border-radius: 6px;
+    background: #fff;
+    font-size: 13px;
+    cursor: pointer;
+  }
+
+  .feedtack-btn-submit {
+    padding: 6px 12px;
+    border: none;
+    border-radius: 6px;
+    background: #2563eb;
+    color: #fff;
+    font-size: 13px;
+    font-weight: 500;
+    cursor: pointer;
+  }
+
+  .feedtack-btn-submit:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  .feedtack-thread {
+    position: absolute;
+    z-index: 2147483642;
+    background: #fff;
+    border-radius: 10px;
+    box-shadow: 0 4px 20px rgba(0,0,0,0.18);
+    padding: 16px;
+    width: 300px;
+    max-height: 400px;
+    overflow-y: auto;
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+  }
+
+  .feedtack-loading {
+    position: fixed;
+    bottom: 70px;
+    right: 24px;
+    font-size: 12px;
+    color: #6b7280;
+    z-index: 2147483640;
+  }
+`;
+
+// src/ui/colors.ts
+var PIN_PALETTE = [
+  "#ef4444",
+  // red
+  "#3b82f6",
+  // blue
+  "#22c55e",
+  // green
+  "#f59e0b",
+  // amber
+  "#a855f7",
+  // purple
+  "#ec4899"
+  // pink
+];
+
+// src/react/FeedtackProvider.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function generateId() {
+  return `ft_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
+}
+function getAnchoredPosition(x, y) {
+  const FORM_WIDTH = 290;
+  const FORM_HEIGHT = 220;
+  const EDGE = 300;
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+  const clientX = x - window.scrollX;
+  const clientY = y - window.scrollY;
+  const left = clientX > vw - EDGE ? void 0 : clientX + 16;
+  const right = clientX > vw - EDGE ? vw - clientX + 16 : void 0;
+  const top = clientY > vh - EDGE ? void 0 : clientY + 16;
+  const bottom = clientY > vh - EDGE ? vh - clientY + FORM_HEIGHT : void 0;
+  return { left, right, top, bottom };
+}
+function FeedtackProvider({ children, adapter, currentUser, hotkey = "p", adminOnly = false, onError }) {
+  const [isPinModeActive, setIsPinModeActive] = useState(false);
+  const [pendingPins, setPendingPins] = useState([]);
+  const [selectedColor, setSelectedColor] = useState(PIN_PALETTE[0]);
+  const [showForm, setShowForm] = useState(false);
+  const [comment, setComment] = useState("");
+  const [sentiment, setSentiment] = useState(null);
+  const [commentError, setCommentError] = useState(false);
+  const [submitting, setSubmitting] = useState(false);
+  const [feedbackItems, setFeedbackItems] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [openThreadId, setOpenThreadId] = useState(null);
+  const [replyBody, setReplyBody] = useState("");
+  const rootRef = useRef(null);
+  useEffect(() => {
+    if (document.getElementById("feedtack-styles")) return;
+    const style = document.createElement("style");
+    style.id = "feedtack-styles";
+    style.textContent = FEEDTACK_STYLES;
+    document.head.appendChild(style);
+    return () => {
+      style.remove();
+    };
+  }, []);
+  useEffect(() => {
+    const root = document.createElement("div");
+    root.id = "feedtack-root";
+    document.body.appendChild(root);
+    rootRef.current = root;
+    return () => {
+      root.remove();
+    };
+  }, []);
+  useEffect(() => {
+    setLoading(true);
+    adapter.loadFeedback({ pathname: window.location.pathname }).then(setFeedbackItems).catch((err) => onError?.(err)).finally(() => setLoading(false));
+  }, [adapter, onError]);
+  const activatePinMode = useCallback(() => setIsPinModeActive(true), []);
+  const deactivatePinMode = useCallback(() => {
+    setIsPinModeActive(false);
+    setPendingPins([]);
+    setShowForm(false);
+    setComment("");
+    setSentiment(null);
+    setCommentError(false);
+  }, []);
+  useEffect(() => {
+    if (isPinModeActive) {
+      document.documentElement.classList.add("feedtack-crosshair");
+    } else {
+      document.documentElement.classList.remove("feedtack-crosshair");
+    }
+    return () => document.documentElement.classList.remove("feedtack-crosshair");
+  }, [isPinModeActive]);
+  useEffect(() => {
+    const handler = (e) => {
+      if (e.key === hotkey.toUpperCase() && e.shiftKey) {
+        setIsPinModeActive((prev) => !prev);
+      }
+      if (e.key === "Escape") {
+        deactivatePinMode();
+        setOpenThreadId(null);
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [hotkey, deactivatePinMode]);
+  const handlePageClick = useCallback((e) => {
+    if (!isPinModeActive) return;
+    const target = e.target;
+    if (target.closest("#feedtack-root") || target.closest(".feedtack-form") || target.closest(".feedtack-color-picker")) return;
+    e.preventDefault();
+    e.stopPropagation();
+    const coords = getPinCoords(e);
+    const targetMeta = getTargetMeta(target);
+    setPendingPins((prev) => [...prev, {
+      color: selectedColor,
+      ...coords,
+      target: targetMeta
+    }]);
+    setShowForm(true);
+  }, [isPinModeActive, selectedColor]);
+  useEffect(() => {
+    document.addEventListener("click", handlePageClick, true);
+    return () => document.removeEventListener("click", handlePageClick, true);
+  }, [handlePageClick]);
+  const handleSubmit = async () => {
+    if (!comment.trim()) {
+      setCommentError(true);
+      return;
+    }
+    setSubmitting(true);
+    const payload = {
+      schemaVersion: SCHEMA_VERSION,
+      id: generateId(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      submittedBy: currentUser,
+      comment: comment.trim(),
+      sentiment,
+      pins: pendingPins.map((p, i) => ({ ...p, index: i + 1 })),
+      page: getPageMeta(),
+      viewport: getViewportMeta(),
+      device: getDeviceMeta()
+    };
+    try {
+      await adapter.submit(payload);
+      setFeedbackItems((prev) => [...prev, { payload, replies: [], resolutions: [], archives: [] }]);
+      deactivatePinMode();
+    } catch (err) {
+      onError?.(err);
+    } finally {
+      setSubmitting(false);
+    }
+  };
+  const handleReply = async (feedbackId) => {
+    if (!replyBody.trim()) return;
+    try {
+      await adapter.reply(feedbackId, {
+        author: currentUser,
+        body: replyBody.trim(),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      setFeedbackItems((prev) => prev.map(
+        (item) => item.payload.id === feedbackId ? { ...item, replies: [...item.replies, { id: generateId(), feedbackId, author: currentUser, body: replyBody.trim(), timestamp: (/* @__PURE__ */ new Date()).toISOString() }] } : item
+      ));
+      setReplyBody("");
+    } catch (err) {
+      onError?.(err);
+    }
+  };
+  const handleResolve = async (feedbackId) => {
+    try {
+      await adapter.resolve(feedbackId, { resolvedBy: currentUser, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+      setFeedbackItems((prev) => prev.map(
+        (item) => item.payload.id === feedbackId ? { ...item, resolutions: [...item.resolutions, { feedbackId, resolvedBy: currentUser, timestamp: (/* @__PURE__ */ new Date()).toISOString() }] } : item
+      ));
+    } catch (err) {
+      onError?.(err);
+    }
+  };
+  const handleArchive = async (feedbackId) => {
+    try {
+      await adapter.archive(feedbackId, currentUser.id);
+      setFeedbackItems((prev) => prev.map(
+        (item) => item.payload.id === feedbackId ? { ...item, archives: [...item.archives, { feedbackId, archivedBy: currentUser, timestamp: (/* @__PURE__ */ new Date()).toISOString() }] } : item
+      ));
+      setOpenThreadId(null);
+    } catch (err) {
+      onError?.(err);
+    }
+  };
+  const isArchivedForUser = (item) => item.archives.some((a) => a.archivedBy.id === currentUser.id);
+  const hasUnread = (item) => item.replies.length > 0;
+  const firstPin = pendingPins[0];
+  const formPos = firstPin ? getAnchoredPosition(firstPin.x, firstPin.y) : {};
+  const showButton = !adminOnly || currentUser.role === "admin";
+  return /* @__PURE__ */ jsxs(FeedtackContext.Provider, { value: { activatePinMode, deactivatePinMode, isPinModeActive }, children: [
+    children,
+    showButton && /* @__PURE__ */ jsxs(
+      "button",
+      {
+        className: `feedtack-btn${isPinModeActive ? " active" : ""}`,
+        onClick: () => isPinModeActive ? deactivatePinMode() : activatePinMode(),
+        title: "Toggle feedback pin mode",
+        children: [
+          "Drop Pin [Shift+",
+          hotkey.toUpperCase(),
+          "]"
+        ]
+      }
+    ),
+    isPinModeActive && /* @__PURE__ */ jsx("div", { className: "feedtack-color-picker", children: PIN_PALETTE.map((color) => /* @__PURE__ */ jsx(
+      "button",
+      {
+        className: `feedtack-color-swatch${selectedColor === color ? " selected" : ""}`,
+        style: { background: color },
+        onClick: () => setSelectedColor(color),
+        title: color
+      },
+      color
+    )) }),
+    pendingPins.map((pin, i) => /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "feedtack-pin-marker",
+        style: {
+          background: pin.color,
+          left: pin.x,
+          top: pin.y,
+          position: "absolute"
+        }
+      },
+      i
+    )),
+    showForm && /* @__PURE__ */ jsxs("div", { className: "feedtack-form", style: { position: "fixed", ...formPos }, children: [
+      /* @__PURE__ */ jsx(
+        "textarea",
+        {
+          className: commentError ? "error" : "",
+          placeholder: "What's the issue? (required)",
+          value: comment,
+          onChange: (e) => {
+            setComment(e.target.value);
+            setCommentError(false);
+          },
+          autoFocus: true
+        }
+      ),
+      commentError && /* @__PURE__ */ jsx("span", { className: "feedtack-error-msg", children: "Comment is required" }),
+      /* @__PURE__ */ jsxs("div", { className: "feedtack-sentiment", children: [
+        /* @__PURE__ */ jsx(
+          "button",
+          {
+            className: sentiment === "satisfied" ? "selected" : "",
+            onClick: () => setSentiment(sentiment === "satisfied" ? null : "satisfied"),
+            children: "\u{1F60A} Satisfied"
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "button",
+          {
+            className: sentiment === "dissatisfied" ? "selected" : "",
+            onClick: () => setSentiment(sentiment === "dissatisfied" ? null : "dissatisfied"),
+            children: "\u{1F61E} Dissatisfied"
+          }
+        )
+      ] }),
+      /* @__PURE__ */ jsxs("div", { className: "feedtack-form-actions", children: [
+        /* @__PURE__ */ jsx("button", { className: "feedtack-btn-cancel", onClick: deactivatePinMode, children: "Cancel" }),
+        /* @__PURE__ */ jsx("button", { className: "feedtack-btn-submit", onClick: handleSubmit, disabled: submitting, children: submitting ? "Sending\u2026" : "Submit" })
+      ] })
+    ] }),
+    !loading && feedbackItems.filter((item) => !isArchivedForUser(item)).map((item) => {
+      const firstItemPin = item.payload.pins[0];
+      const unread = hasUnread(item);
+      return /* @__PURE__ */ jsx(
+        "div",
+        {
+          className: "feedtack-pin-marker",
+          style: {
+            background: firstItemPin.color,
+            left: firstItemPin.x,
+            top: firstItemPin.y,
+            position: "absolute",
+            cursor: "pointer"
+          },
+          onClick: () => setOpenThreadId(openThreadId === item.payload.id ? null : item.payload.id),
+          children: unread && /* @__PURE__ */ jsx("div", { className: "feedtack-pin-badge" })
+        },
+        item.payload.id
+      );
+    }),
+    openThreadId && (() => {
+      const item = feedbackItems.find((i) => i.payload.id === openThreadId);
+      if (!item) return null;
+      const pin = item.payload.pins[0];
+      const pos = getAnchoredPosition(pin.x, pin.y);
+      return /* @__PURE__ */ jsxs("div", { className: "feedtack-thread", style: { position: "fixed", ...pos }, children: [
+        /* @__PURE__ */ jsx("strong", { style: { fontSize: 13 }, children: item.payload.submittedBy.name }),
+        /* @__PURE__ */ jsx("p", { style: { fontSize: 13 }, children: item.payload.comment }),
+        item.replies.map((r) => /* @__PURE__ */ jsxs("div", { style: { borderTop: "1px solid #f3f4f6", paddingTop: 8 }, children: [
+          /* @__PURE__ */ jsx("span", { style: { fontSize: 12, fontWeight: 600 }, children: r.author.name }),
+          /* @__PURE__ */ jsx("p", { style: { fontSize: 12 }, children: r.body })
+        ] }, r.id)),
+        /* @__PURE__ */ jsx(
+          "textarea",
+          {
+            placeholder: "Reply\u2026",
+            value: replyBody,
+            onChange: (e) => setReplyBody(e.target.value),
+            style: { width: "100%", fontSize: 12, padding: 6, borderRadius: 6, border: "1px solid #e5e7eb", marginTop: 4 }
+          }
+        ),
+        /* @__PURE__ */ jsxs("div", { style: { display: "flex", gap: 6, flexWrap: "wrap" }, children: [
+          /* @__PURE__ */ jsx("button", { className: "feedtack-btn-submit", style: { fontSize: 12, padding: "4px 10px" }, onClick: () => handleReply(openThreadId), children: "Reply" }),
+          /* @__PURE__ */ jsx("button", { className: "feedtack-btn-cancel", style: { fontSize: 12 }, onClick: () => handleResolve(openThreadId), children: "Mark Resolved" }),
+          /* @__PURE__ */ jsx("button", { className: "feedtack-btn-cancel", style: { fontSize: 12 }, onClick: () => handleArchive(openThreadId), children: "Archive" }),
+          /* @__PURE__ */ jsx("button", { className: "feedtack-btn-cancel", style: { fontSize: 12 }, onClick: () => setOpenThreadId(null), children: "Close" })
+        ] })
+      ] });
+    })(),
+    loading && /* @__PURE__ */ jsx("div", { className: "feedtack-loading", children: "Loading feedback\u2026" })
+  ] });
+}
+
+// src/react/useFeedtack.ts
+function useFeedtack() {
+  return useFeedtackContext();
+}
+export {
+  FeedtackProvider,
+  useFeedtack
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "feedtack",
+  "version": "0.0.1",
+  "description": "Click anywhere. Drop a pin. Get a payload a developer can act on.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Trillium Smith",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/trillium/feedtack"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "packageManager": "pnpm@9.0.0",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "prepublishOnly": "pnpm test && pnpm build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.4.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "eslint": "^9.0.0",
+    "jsdom": "^25.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^2.0.0"
+  }
+}