@uselay/sdk 0.1.0 → 1.1.0

package/README.md

@@ -1,112 +1,279 @@
 # @uselay/sdk
 
-The feedback layer for React. Drop two components into your app and let teammates or users leave comments pinned to specific UI elements.
+The feedback layer for React. Drop one component into your app and let anyone point at what's wrong and say why — no more screenshots in Slack with "the thing on the right."
 
-## Install
+Comments are pinned to the exact DOM element, not a screenshot coordinate. Your team sees what was clicked, reads the comment, and understands the problem without a follow-up call.
+
+## Quick start
+
+### 1. Install
 
 ```bash
 npm install @uselay/sdk
 ```
 
-No CSS imports needed — styles are injected at runtime.
+No CSS imports needed. Styles are injected at runtime.
 
-## Quick start
+### 2. Wrap your app
 
 ```tsx
-import { LayProvider, LayToggle } from '@uselay/sdk';
+import { LayProvider } from '@uselay/sdk';
 
 function App() {
   return (
-    <LayProvider
-      config={{
-        projectId: 'your-project-id',
-        user: { id: 'user-1', name: 'Jane' },
-      }}
-    >
+    <LayProvider projectId="your-project-id">
       <YourApp />
-      <LayToggle />
     </LayProvider>
   );
 }
 ```
 
-Click the toggle, hover to highlight elements, click to pin a comment.
+Get your `projectId` from the [dashboard](https://uselay.com/dashboard). The toggle button and comment UI render automatically inside the provider.
+
+Want to identify who's commenting? Add the optional `user` prop:
+
+```tsx
+<LayProvider
+  projectId="your-project-id"
+  user={{ id: 'user-1', name: 'Jane' }}
+>
+  <YourApp />
+</LayProvider>
+```
+
+### 3. Press C
+
+Run your app and press `C` to enter comment mode. Hover to highlight elements. Click to pin a comment.
+
+## How it works
+
+1. **Enter comment mode** — Press `C` or click the toggle button. Elements highlight on hover.
+2. **Click an element** — A comment input anchors to your selection. The SDK generates a CSS selector and fingerprint to track it.
+3. **Write your comment** — Type what you see, or tap a starter chip.
+4. **AI enrichment runs** — Element metadata is captured and enriched with context, intent detection, and suggested actions.
+5. **Comment appears in the dashboard** — Grouped by page and element, with the AI context card and a viewport screenshot.
+6. **Your team understands what you mean** — The comment is attached to the element itself. Navigate, resolve, and archive from the dashboard.
 
 ## Configuration
 
-Pass a `config` object to `LayProvider`:
+All props are passed directly to `LayProvider`:
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `projectId` | `string` | *required* | Project ID from the Lay dashboard |
-| `user` | `{ id: string; name: string; avatar?: string }` | — | Comment author identity. Omit for anonymous. |
-| `userHash` | `string` | — | HMAC-SHA256 hash for verified identity (see below) |
-| `adapter` | `LayAdapter` | auto | Custom data adapter. Defaults to hosted backend. |
-| `apiUrl` | `string` | `https://uselay.com` | API base URL override |
-| `version` | `string` | — | Version tag. Changing this archives previous comments. |
-| `ai` | `boolean` | `true` | Enable AI enrichment on comments |
+| `user` | `{ id, name, avatar? }` | — | Comment author identity. Omit for anonymous. |
+| `userHash` | `string` | — | HMAC-SHA256 hash for verified identity. Use `identifyUser()` to generate. |
 | `mode` | `'review' \| 'support'` | dashboard setting | Override project mode |
 | `active` | `boolean` | dashboard setting | Override active state. `false` = widget hidden. |
-| `starterChips` | `StarterChip[]` | `["Visual bug", "Copy issue", "Love this"]` | Quick-feedback chips. `[]` to disable. |
+| `ai` | `boolean` | `true` | Enable AI enrichment on comments |
 | `screenshots` | `boolean` | `true` | Capture viewport screenshots on comment creation |
+| `starterChips` | `StarterChip[]` | `["Visual bug", "Copy issue", "Love this"]` | Quick-feedback chips. `[]` to disable. |
+| `version` | `string` | — | Version tag. Changing this archives previous comments. |
+| `adapter` | `LayAdapter` | hosted | Custom data adapter. Defaults to hosted backend. |
+| `apiUrl` | `string` | `https://uselay.com` | API base URL override |
+
+Most projects need only `projectId`.
+
+## Modes
+
+**Review** — Team feedback on prototypes and staging. Comments are threaded. AI generates element descriptions and fix suggestions. Best for staging URLs, design reviews, QA passes.
+
+```tsx
+<LayProvider projectId="..." mode="review">
+  <StagingApp />
+</LayProvider>
+```
+
+**Support** — End-user feedback on live sites. Comments are standalone. AI detects intent (bug report, confusion, feature request, praise). Best for production apps, beta programs, user research.
+
+```tsx
+<LayProvider projectId="..." mode="support">
+  <ProductionApp />
+</LayProvider>
+```
 
 ## Identified users
 
-For verified identity in production, hash the user ID server-side:
+Use `identifyUser` to verify commenter identity server-side. It returns spread-friendly props — `{ user, userHash }` for a valid user, or `{}` for null/undefined input.
 
 ```ts
-// Server (Next.js API route, Express, etc.)
-import { createUserHash } from '@uselay/sdk/server';
+import { identifyUser } from '@uselay/sdk/server';
 
 // Set LAY_SECRET_KEY in your environment (from dashboard → project settings)
-const hash = createUserHash(user.id);
+const identified = identifyUser(session?.user);
+// → { user: { id, name, avatar }, userHash: '...' }  or  {}
 ```
 
-Then pass both `user` and `userHash` to the provider:
+Spread the result into the provider:
 
 ```tsx
-<LayProvider config={{ projectId: '...', user, userHash: hash }}>
+<LayProvider projectId="..." {...identifyUser(session?.user)}>
+  <YourApp />
+</LayProvider>
 ```
 
-## Starter chips
+Never expose `LAY_SECRET_KEY` to the client. `identifyUser` must run on your server.
 
-Customize the quick-feedback chips:
+## Stable anchors
+
+Comments are pinned to DOM elements via CSS selectors. The SDK resolves elements in three layers:
+
+1. **`data-feedback-id`** — If present, always used. Most stable. Add to elements that receive frequent feedback.
+2. **CSS selector** — Generated from IDs, `data-testid`, semantic attributes. Skips auto-generated class names.
+3. **Element fingerprint** — Hash of tag, text, attributes, position. Used as fallback when the selector stops matching.
 
 ```tsx
-<LayProvider
-  config={{
-    projectId: '...',
-    starterChips: [
-      { label: 'Broken', value: 'This element is broken' },
-      { label: 'Wrong copy' },
-      { label: 'Looks great' },
-    ],
-  }}
->
+<button data-feedback-id="checkout-submit">Place Order</button>
 ```
 
-## Screenshots
-
-Viewport screenshots are captured automatically when a comment is created. Disable with `screenshots: false`.
+If a comment can't be resolved to any element, it appears in the Detached Comments panel in the dashboard.
 
 ## Custom adapter
 
 Implement the `LayAdapter` interface to use your own backend:
 
-```tsx
-import { LayProvider } from '@uselay/sdk';
+```ts
 import type { LayAdapter } from '@uselay/sdk';
 
 const myAdapter: LayAdapter = {
-  getComments: async (projectId, urlPath) => { /* ... */ },
-  addComment: async (comment) => { /* ... */ },
-  subscribe: (projectId, urlPath, callback) => { /* ... */ },
-  // ...
+  getConfig: async (projectId) => { /* ... */ },
+  getComments: async (projectId, urlPath, options) => { /* ... */ },
+  addComment: async (comment, options) => { /* ... */ },
+  updateComment: async (id, update, options) => { /* ... */ },
+  uploadScreenshot: async (projectId, commentId, blob, bounds, options) => { /* ... */ },
+  subscribe: (projectId, callback, options) => { /* return unsubscribe fn */ },
 };
+```
 
-<LayProvider config={{ projectId: '...', adapter: myAdapter }}>
+```tsx
+<LayProvider projectId="..." adapter={myAdapter}>
+  <YourApp />
+</LayProvider>
 ```
 
+The SDK also exports `createMemoryAdapter()` for testing and prototyping.
+
+## Keyboard shortcuts
+
+| Key | Action |
+|-----|--------|
+| `C` | Toggle comment mode |
+| `Escape` | Exit comment mode / dismiss input |
+
+Shortcuts are disabled when focus is inside an input, textarea, or contenteditable element.
+
+## Framework examples
+
+### Next.js App Router
+
+```tsx
+// app/layout.tsx
+import { identifyUser } from '@uselay/sdk/server';
+import { LayProvider } from '@uselay/sdk';
+
+export default async function RootLayout({ children }) {
+  const session = await auth();
+
+  return (
+    <html lang="en">
+      <body>
+        <LayProvider
+          projectId={process.env.NEXT_PUBLIC_LAY_PROJECT_ID!}
+          {...identifyUser(session?.user)}
+        >
+          {children}
+        </LayProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Next.js Pages Router
+
+```tsx
+// pages/_app.tsx
+import { identifyUser } from '@uselay/sdk/server';
+import { LayProvider } from '@uselay/sdk';
+
+export async function getServerSideProps({ req }) {
+  const session = await getSession(req);
+  return { props: { identified: identifyUser(session?.user) } };
+}
+
+export default function App({ Component, pageProps }) {
+  return (
+    <LayProvider
+      projectId={process.env.NEXT_PUBLIC_LAY_PROJECT_ID!}
+      {...pageProps.identified}
+    >
+      <Component {...pageProps} />
+    </LayProvider>
+  );
+}
+```
+
+### Vite + React
+
+```tsx
+// src/main.tsx
+import { LayProvider } from '@uselay/sdk';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <LayProvider projectId={import.meta.env.VITE_LAY_PROJECT_ID}>
+    <App />
+  </LayProvider>
+);
+```
+
+### Remix
+
+```tsx
+// app/root.tsx
+import { LayProvider } from '@uselay/sdk';
+import { identifyUser } from '@uselay/sdk/server';
+
+export async function loader({ request }) {
+  const user = await getUser(request);
+  return json({
+    layProjectId: process.env.LAY_PROJECT_ID,
+    ...identifyUser(user),
+  });
+}
+
+export default function Root() {
+  const { layProjectId, user, userHash } = useLoaderData();
+  return (
+    <html lang="en">
+      <body>
+        <LayProvider projectId={layProjectId!} user={user} userHash={userHash}>
+          <Outlet />
+        </LayProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Troubleshooting
+
+**Widget does not appear** — Check that `LayProvider` wraps your app with a valid `projectId`. The project must be active in the dashboard (or pass the `active` prop).
+
+**Comments disappear after deploy** — CSS selectors changed. Add `data-feedback-id` to critical elements. Detached comments appear in the Detached Comments panel.
+
+**AI context cards not showing** — Verify `ai` is not set to `false`. AI processing takes a few seconds after comment creation.
+
+**`identifyUser` throws "LAY_SECRET_KEY not set"** — Set the `LAY_SECRET_KEY` environment variable on your server. Never expose it client-side.
+
+**Widget re-renders frequently** — If you pass object props like `user` inline on every render, it creates a new reference each time. Define objects outside the component or use `useMemo`.
+
+## Next steps
+
+- Open the [dashboard](https://uselay.com/dashboard) and create your first project
+- Invite your team from project settings
+- Add `data-feedback-id` to your most important UI elements
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -31,8 +31,14 @@ interface ElementMetadata {
     device: string;
     fingerprint?: ElementFingerprint;
 }
+interface DeveloperTriage {
+    element_summary: string;
+    whats_happening: string;
+    likely_causes: string[];
+    where_to_look: string[];
+}
 interface AIContextReview {
-    ai_context_version: 2 | 3;
+    ai_context_version: 2 | 3 | 4;
     mode: 'review';
     category: 'visual' | 'accessibility' | 'layout' | 'copy' | 'interaction';
     /** v3: single interpretation sentence replacing suggestions + accessibility_issues */
@@ -46,12 +52,15 @@ interface AIContextReview {
     enriched_at: string;
 }
 interface AIContextSupport {
-    ai_context_version: 2 | 3;
+    ai_context_version: 2 | 3 | 4;
     mode: 'support';
     intent: 'confusion' | 'bug_report' | 'feature_request' | 'complaint' | 'question' | 'praise' | 'other';
     urgency: 'low' | 'medium' | 'high';
     summary: string;
-    suggested_response: string;
+    /** v4: developer triage for bug_report/confusion intents */
+    developer_triage?: DeveloperTriage | null;
+    /** @deprecated v3 only — removed in v4 */
+    suggested_response?: string;
     /** @deprecated v2 only — removed in v3 */
     confidence?: number;
     enriched_at: string;
@@ -115,6 +124,8 @@ interface LayAdapter {
 
 /** Project mode: review (team feedback) or support (end-user help) */
 type ProjectMode = 'review' | 'support';
+/** SDK connection status after attempting to validate the projectId */
+type ProjectStatus = 'loading' | 'valid' | 'not_found' | 'inactive';
 /** Starter chip for the Two-Speed Composer */
 interface StarterChip {
     /** Display label on the chip */
@@ -175,14 +186,19 @@ interface LayContextValue {
     dispatch: React.Dispatch<LayAction>;
     portalRoot: HTMLDivElement | null;
     mode: ProjectMode;
+    projectStatus: ProjectStatus;
     remoteConfigLoaded: boolean;
     detachedDomPaths: Set<string>;
     setDetachedDomPaths: React.Dispatch<React.SetStateAction<Set<string>>>;
+    /** Ref-stable callback for when the current user submits a comment. */
+    onCommentAddedRef: React.RefObject<((comment: Comment) => void) | undefined>;
 }
 interface LayProviderProps extends LayConfig {
     children: ReactNode;
+    /** Callback invoked when the current user successfully submits a comment. */
+    onCommentAdded?: (comment: Comment) => void;
 }
-declare function LayProvider({ children, projectId, user, userHash, adapter: customAdapter, apiUrl, version, ai, mode: modeProp, active: activeProp, starterChips, screenshots, }: LayProviderProps): react_jsx_runtime.JSX.Element;
+declare function LayProvider({ children, projectId, user, userHash, adapter: customAdapter, apiUrl, version, ai, mode: modeProp, active: activeProp, starterChips, screenshots, onCommentAdded, }: LayProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function LayToggle(): React.ReactPortal | null;
 
@@ -490,4 +506,4 @@ interface HostedAdapterOptions {
 }
 declare function createHostedAdapter(options?: string | HostedAdapterOptions): LayAdapter;
 
-export { type AIContext, AIContextCard, type AIContextReview, type AIContextSupport, type AdapterOptions, ArchivedThreadsPanel, type Author, type Comment, CommentActions, CommentAnchor, CommentDot, CommentDots, type CommentEvent, type CommentEventType, type CommentGroup, CommentItem, CommentLayer, type CommentStatus, CommentThread, type CommentUpdate, DetachedCommentsPanel, type ElementBounds, type ElementFingerprint, ElementHighlighter, type ElementMetadata, type LayAdapter, type LayConfig, type LayContextValue, LayProvider, LayToggle, type NewComment, type ProjectMode, type RemoteConfig, ReplyInput, type ResolveMethod, type ResolveResult, type StarterChip, type ThreadGroup, type ThreadItem, type Unsubscribe, captureElementMetadata, computeContrastRatio, createHostedAdapter, createMemoryAdapter, findByFingerprint, formatRelativeTime, generateDomPath, generateFingerprint, getGuestAuthor, isAIContextReview, isAIContextSupport, isCommentable, isGeneratedClassName, parseUserAgent, persistGuestName, resolveAuthor, resolveEffectiveBackground, resolveElement, saveGuestAuthor, scoreFingerprintMatch, summarizeDomPath, useCommentMode, useComments, useElementSelector, useLayContext };
+export { type AIContext, AIContextCard, type AIContextReview, type AIContextSupport, type AdapterOptions, ArchivedThreadsPanel, type Author, type Comment, CommentActions, CommentAnchor, CommentDot, CommentDots, type CommentEvent, type CommentEventType, type CommentGroup, CommentItem, CommentLayer, type CommentStatus, CommentThread, type CommentUpdate, DetachedCommentsPanel, type ElementBounds, type ElementFingerprint, ElementHighlighter, type ElementMetadata, type LayAdapter, type LayConfig, type LayContextValue, LayProvider, LayToggle, type NewComment, type ProjectMode, type ProjectStatus, type RemoteConfig, ReplyInput, type ResolveMethod, type ResolveResult, type StarterChip, type ThreadGroup, type ThreadItem, type Unsubscribe, captureElementMetadata, computeContrastRatio, createHostedAdapter, createMemoryAdapter, findByFingerprint, formatRelativeTime, generateDomPath, generateFingerprint, getGuestAuthor, isAIContextReview, isAIContextSupport, isCommentable, isGeneratedClassName, parseUserAgent, persistGuestName, resolveAuthor, resolveEffectiveBackground, resolveElement, saveGuestAuthor, scoreFingerprintMatch, summarizeDomPath, useCommentMode, useComments, useElementSelector, useLayContext };

package/dist/index.d.ts

@@ -31,8 +31,14 @@ interface ElementMetadata {
     device: string;
     fingerprint?: ElementFingerprint;
 }
+interface DeveloperTriage {
+    element_summary: string;
+    whats_happening: string;
+    likely_causes: string[];
+    where_to_look: string[];
+}
 interface AIContextReview {
-    ai_context_version: 2 | 3;
+    ai_context_version: 2 | 3 | 4;
     mode: 'review';
     category: 'visual' | 'accessibility' | 'layout' | 'copy' | 'interaction';
     /** v3: single interpretation sentence replacing suggestions + accessibility_issues */
@@ -46,12 +52,15 @@ interface AIContextReview {
     enriched_at: string;
 }
 interface AIContextSupport {
-    ai_context_version: 2 | 3;
+    ai_context_version: 2 | 3 | 4;
     mode: 'support';
     intent: 'confusion' | 'bug_report' | 'feature_request' | 'complaint' | 'question' | 'praise' | 'other';
     urgency: 'low' | 'medium' | 'high';
     summary: string;
-    suggested_response: string;
+    /** v4: developer triage for bug_report/confusion intents */
+    developer_triage?: DeveloperTriage | null;
+    /** @deprecated v3 only — removed in v4 */
+    suggested_response?: string;
     /** @deprecated v2 only — removed in v3 */
     confidence?: number;
     enriched_at: string;
@@ -115,6 +124,8 @@ interface LayAdapter {
 
 /** Project mode: review (team feedback) or support (end-user help) */
 type ProjectMode = 'review' | 'support';
+/** SDK connection status after attempting to validate the projectId */
+type ProjectStatus = 'loading' | 'valid' | 'not_found' | 'inactive';
 /** Starter chip for the Two-Speed Composer */
 interface StarterChip {
     /** Display label on the chip */
@@ -175,14 +186,19 @@ interface LayContextValue {
     dispatch: React.Dispatch<LayAction>;
     portalRoot: HTMLDivElement | null;
     mode: ProjectMode;
+    projectStatus: ProjectStatus;
     remoteConfigLoaded: boolean;
     detachedDomPaths: Set<string>;
     setDetachedDomPaths: React.Dispatch<React.SetStateAction<Set<string>>>;
+    /** Ref-stable callback for when the current user submits a comment. */
+    onCommentAddedRef: React.RefObject<((comment: Comment) => void) | undefined>;
 }
 interface LayProviderProps extends LayConfig {
     children: ReactNode;
+    /** Callback invoked when the current user successfully submits a comment. */
+    onCommentAdded?: (comment: Comment) => void;
 }
-declare function LayProvider({ children, projectId, user, userHash, adapter: customAdapter, apiUrl, version, ai, mode: modeProp, active: activeProp, starterChips, screenshots, }: LayProviderProps): react_jsx_runtime.JSX.Element;
+declare function LayProvider({ children, projectId, user, userHash, adapter: customAdapter, apiUrl, version, ai, mode: modeProp, active: activeProp, starterChips, screenshots, onCommentAdded, }: LayProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function LayToggle(): React.ReactPortal | null;
 
@@ -490,4 +506,4 @@ interface HostedAdapterOptions {
 }
 declare function createHostedAdapter(options?: string | HostedAdapterOptions): LayAdapter;
 
-export { type AIContext, AIContextCard, type AIContextReview, type AIContextSupport, type AdapterOptions, ArchivedThreadsPanel, type Author, type Comment, CommentActions, CommentAnchor, CommentDot, CommentDots, type CommentEvent, type CommentEventType, type CommentGroup, CommentItem, CommentLayer, type CommentStatus, CommentThread, type CommentUpdate, DetachedCommentsPanel, type ElementBounds, type ElementFingerprint, ElementHighlighter, type ElementMetadata, type LayAdapter, type LayConfig, type LayContextValue, LayProvider, LayToggle, type NewComment, type ProjectMode, type RemoteConfig, ReplyInput, type ResolveMethod, type ResolveResult, type StarterChip, type ThreadGroup, type ThreadItem, type Unsubscribe, captureElementMetadata, computeContrastRatio, createHostedAdapter, createMemoryAdapter, findByFingerprint, formatRelativeTime, generateDomPath, generateFingerprint, getGuestAuthor, isAIContextReview, isAIContextSupport, isCommentable, isGeneratedClassName, parseUserAgent, persistGuestName, resolveAuthor, resolveEffectiveBackground, resolveElement, saveGuestAuthor, scoreFingerprintMatch, summarizeDomPath, useCommentMode, useComments, useElementSelector, useLayContext };
+export { type AIContext, AIContextCard, type AIContextReview, type AIContextSupport, type AdapterOptions, ArchivedThreadsPanel, type Author, type Comment, CommentActions, CommentAnchor, CommentDot, CommentDots, type CommentEvent, type CommentEventType, type CommentGroup, CommentItem, CommentLayer, type CommentStatus, CommentThread, type CommentUpdate, DetachedCommentsPanel, type ElementBounds, type ElementFingerprint, ElementHighlighter, type ElementMetadata, type LayAdapter, type LayConfig, type LayContextValue, LayProvider, LayToggle, type NewComment, type ProjectMode, type ProjectStatus, type RemoteConfig, ReplyInput, type ResolveMethod, type ResolveResult, type StarterChip, type ThreadGroup, type ThreadItem, type Unsubscribe, captureElementMetadata, computeContrastRatio, createHostedAdapter, createMemoryAdapter, findByFingerprint, formatRelativeTime, generateDomPath, generateFingerprint, getGuestAuthor, isAIContextReview, isAIContextSupport, isCommentable, isGeneratedClassName, parseUserAgent, persistGuestName, resolveAuthor, resolveEffectiveBackground, resolveElement, saveGuestAuthor, scoreFingerprintMatch, summarizeDomPath, useCommentMode, useComments, useElementSelector, useLayContext };