@uselay/sdk 1.0.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;

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;