@unnoodle/browser 0.1.0

package/README.md

@@ -0,0 +1,403 @@
+# @unnoodle/browser
+
+> Embed AI context assistance into any web application.
+
+[![npm version](https://img.shields.io/npm/v/@unnoodle/browser)](https://www.npmjs.com/package/@unnoodle/browser)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@unnoodle/browser)](https://bundlephobia.com/package/@unnoodle/browser)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## What is it?
+
+`@unnoodle/browser` is a lightweight, framework-agnostic SDK that adds a floating AI assistant button to your web application. It automatically collects runtime context (current route, page title, environment) and sends it to the Unnoodle API to surface intelligent suggestions.
+
+- Zero React / framework dependency
+- Shadow DOM — completely isolated from your app's CSS
+- < 50kb minified
+- Works with Next.js, React, Vue, Svelte, or plain HTML
+
+---
+
+## Installation
+
+```bash
+npm install @unnoodle/browser
+# or
+pnpm add @unnoodle/browser
+# or
+yarn add @unnoodle/browser
+```
+
+---
+
+## Quick Start
+
+```ts
+import { Unnoodle } from "@unnoodle/browser";
+
+Unnoodle.init({
+  apiKey: process.env.NEXT_PUBLIC_UNNOODLE_API_KEY,
+  context: "engineering",
+});
+```
+
+That's it. A floating button appears in the bottom-right corner. Click it or press **⌘U** (macOS) / **Ctrl+U** (Windows/Linux) to open the panel.
+
+> **Where is my API key?** Log in to your workspace → Settings → API Key.
+
+---
+
+## Full Configuration
+
+A starter config file is included in the package as `unnoodle.config.ts`. Copy it into your project root and fill in your values.
+
+```ts
+import { Unnoodle } from "@unnoodle/browser";
+
+Unnoodle.init({
+  // Required: workspace API key (Settings → API Key in your workspace)
+  apiKey: process.env.NEXT_PUBLIC_UNNOODLE_API_KEY,
+
+  // Required: context slug to load — created automatically if new
+  context: "engineering",
+
+  // Optional: target environment (default: "prod")
+  environment: "dev",
+
+  // Optional: override API base URL (default: https://api.unnoodle.com)
+  baseUrl: "http://localhost:8080",
+
+  // Optional: provide an auth token at request time
+  getAuthToken: () => localStorage.getItem("auth_token"),
+
+  // Optional: theme customization
+  theme: {
+    primaryColor: "#6366f1",
+    borderRadius: "12px",
+  },
+
+  // Optional: attach additional metadata to every request
+  customMetadata: () => ({
+    userId: window.__APP_USER_ID,
+    plan: "enterprise",
+  }),
+});
+```
+
+---
+
+## Programmatic Control
+
+```ts
+import { Unnoodle } from "@unnoodle/browser";
+
+// Open the panel manually (e.g. from your own help button)
+Unnoodle.open();
+
+// Close the panel
+Unnoodle.close();
+
+// Remove the widget entirely (useful in SPAs)
+Unnoodle.destroy();
+```
+
+The individual named exports (`openUnnoodle`, `closeUnnoodle`, `destroyUnnoodle`) are still available for tree-shaking.
+
+---
+
+## Framework Examples
+
+### React / Next.js (App Router)
+
+Root layouts in Next.js App Router are **Server Components** and run on the
+server where `document` does not exist. You must call `initUnnoodle()` from a
+separate `"use client"` component rendered inside the layout body.
+
+**Step 1 — install the package**
+
+```bash
+npm install @unnoodle/browser
+# or
+pnpm add @unnoodle/browser
+```
+
+**Step 2 — create a thin client component** (e.g. `components/UnnoodleInit.tsx`)
+
+```tsx
+"use client";
+import { useEffect } from "react";
+import { initUnnoodle } from "@unnoodle/browser";
+
+export function UnnoodleInit({
+  apiKey,
+  context,
+}: {
+  apiKey: string;
+  context: string;
+}) {
+  useEffect(() => {
+    initUnnoodle({ apiKey, context });
+  }, [apiKey, context]);
+
+  return null; // renders nothing — side-effect only
+}
+```
+
+**Step 3 — render it inside your layout body**
+
+```tsx
+// app/layout.tsx — stays a Server Component, no "use client" needed here
+import { UnnoodleInit } from "../components/UnnoodleInit";
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <UnnoodleInit
+          apiKey={process.env.NEXT_PUBLIC_UNNOODLE_API_KEY!}
+          context="engineering"
+        />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+> **Why not `"use client"` on the layout directly?**  
+> Next.js App Router layouts that render `<html>` and `<head>` must be Server
+> Components. Adding `"use client"` would cause a build error. The thin wrapper
+> component is the standard pattern recommended by the Next.js team.
+
+### React / Next.js (Pages Router)
+
+```tsx
+// pages/_app.tsx
+import { useEffect } from "react";
+import { Unnoodle } from "@unnoodle/browser";
+
+export default function App({ Component, pageProps }) {
+  useEffect(() => {
+    Unnoodle.init({
+      apiKey: process.env.NEXT_PUBLIC_UNNOODLE_API_KEY,
+      context: "engineering",
+    });
+  }, []);
+
+  return <Component {...pageProps} />;
+}
+```
+
+### Vue 3
+
+```ts
+// main.ts
+import { createApp } from "vue";
+import App from "./App.vue";
+import { Unnoodle } from "@unnoodle/browser";
+
+const app = createApp(App);
+app.mount("#app");
+
+Unnoodle.init({
+  apiKey: process.env.VITE_UNNOODLE_API_KEY,
+  context: "engineering",
+});
+```
+
+### Plain HTML / CDN
+
+```html
+<script type="module">
+  import { Unnoodle } from "https://cdn.unnoodle.com/browser/latest/index.js";
+  Unnoodle.init({
+    apiKey: "pk_live_xxxxx",
+    context: "engineering",
+  });
+</script>
+```
+
+---
+
+## Plugin System (Advanced)
+
+The SDK includes an internal plugin interface for advanced use cases. Plugins can intercept the context collection, response rendering, and error handling lifecycle.
+
+```ts
+import { initUnnoodle, type UnnoodlePlugin } from "@unnoodle/browser";
+
+const analyticsPlugin: UnnoodlePlugin = {
+  name: "analytics",
+  onContextCollected: (ctx) => ({
+    ...ctx,
+    sessionId: getSessionId(),
+  }),
+  onResponse: (response) => {
+    trackEvent("unnoodle_response", { hasActions: !!response.actions?.length });
+  },
+  onError: (err) => {
+    reportError(err);
+  },
+};
+
+Unnoodle.init({
+  apiKey: process.env.NEXT_PUBLIC_UNNOODLE_API_KEY,
+  context: "engineering",
+  _plugins: [analyticsPlugin],
+});
+```
+
+> Note: `_plugins` is prefixed with `_` to indicate it's an advanced internal API. It may be promoted to a stable API in a future major version.
+
+---
+
+## API Reference
+
+### `Unnoodle.init(config: UnnoodleConfig): void`
+
+Initializes and mounts the widget. Safe to call in SSR environments — no-ops if `document` is unavailable.
+
+Also available as the named export `initUnnoodle()` for tree-shaking.
+
+### `openUnnoodle(): void`
+
+Programmatically opens the panel.
+
+### `closeUnnoodle(): void`
+
+Programmatically closes the panel.
+
+### `destroyUnnoodle(): void`
+
+Tears down the widget, removes DOM elements, and cleans up all event listeners.
+
+---
+
+## `UnnoodleConfig` Interface
+
+| Property             | Type                            | Required | Default                    | Description                                                     |
+| -------------------- | ------------------------------- | -------- | -------------------------- | --------------------------------------------------------------- |
+| `apiKey`             | `string`                        | ✅       | —                          | Workspace API key (`pk_live_…`). Get it from Settings → API Key |
+| `context`            | `string`                        | ✅       | —                          | Context slug to load (auto-created if new)                      |
+| `environment`        | `"dev" \| "staging" \| "prod"`  |          | `"prod"`                   | Target environment                                              |
+| `baseUrl`            | `string`                        |          | `https://api.unnoodle.com` | API base URL override                                           |
+| `getAuthToken`       | `() => string \| null`          |          | —                          | Returns current user's auth token                               |
+| `theme.primaryColor` | `string`                        |          | `#6366f1`                  | Button and panel accent color                                   |
+| `theme.borderRadius` | `string`                        |          | `12px`                     | Panel corner radius                                             |
+| `customMetadata`     | `() => Record<string, unknown>` |          | —                          | Additional context metadata                                     |
+| `_plugins`           | `UnnoodlePlugin[]`              |          | —                          | Internal plugin hooks                                           |
+
+---
+
+## Security
+
+- Auth tokens are resolved at request time and never stored
+- All API communication uses HTTPS
+- No secrets are bundled in the SDK
+- Shadow DOM prevents CSS bleed-in and bleed-out
+- The SDK fails silently on misconfiguration — it will never crash the host app
+
+---
+
+## Product Memory — Developer API (V2)
+
+The V2 Product Memory sub-system ships as part of the package and is exported for advanced SDK consumers. These modules work in any browser environment and have no React/framework dependency.
+
+### `StateWatcher`
+
+Attaches a `MutationObserver` to any DOM element and fires a typed `StateDiff` callback when meaningful changes are detected.
+
+```ts
+import { StateWatcher, type StateDiff } from "@unnoodle/browser";
+
+const watcher = new StateWatcher();
+const btn = document.getElementById("submit-btn")!;
+
+watcher.watch(btn, (diff: StateDiff) => {
+  console.log(diff.type); // "text" | "attribute" | "structure"
+  console.log(diff.before); // value before the change
+  console.log(diff.after); // value after the change
+  console.log(diff.attribute); // attribute name (only when type === "attribute")
+});
+
+// Clean up
+watcher.unwatch();
+```
+
+**Behaviour:**
+
+- Changes are debounced for 500 ms — rapid mutations produce a single callback.
+- `style` attribute mutations are filtered out (noise filter).
+- Text changes (`textContent` assignments) are classified as `type: "text"`.
+- Attribute changes (class, disabled, aria-\*) are classified as `type: "attribute"`.
+- Child element additions/removals are classified as `type: "structure"`.
+- `unwatch()` cancels any pending callback and disconnects the observer.
+
+### `inferMeaning(diff, el)`
+
+Rule-based semantic label inference from a `StateDiff`.
+
+```ts
+import { StateWatcher, inferMeaning } from "@unnoodle/browser";
+
+const watcher = new StateWatcher();
+
+watcher.watch(document.getElementById("submit-btn")!, (diff) => {
+  const meaning = inferMeaning(diff, document.getElementById("submit-btn")!);
+  // "Loading state" | "Error state" | "Disabled state" | … | null
+  if (meaning) {
+    console.log("Detected state:", meaning);
+  }
+});
+```
+
+**Inferred labels:**
+
+| Trigger                                             | Label                         |
+| --------------------------------------------------- | ----------------------------- |
+| Text contains "loading" / "submitting" / "saving"   | `"Loading state"`             |
+| Text contains "error" / "failed" / "invalid"        | `"Error state"`               |
+| Text contains "success" / "saved" / "done"          | `"Success state"`             |
+| Class `"loading"` / `"spinner"` / `"pending"` added | `"Loading state"`             |
+| Class `"disabled"` / `"inactive"` added             | `"Disabled state"`            |
+| Class `"error"` / `"invalid"` / `"danger"` added    | `"Error state"`               |
+| Class `"active"` / `"selected"` / `"open"` added    | `"Active state"`              |
+| Class `"collapsed"` / `"hidden"` added              | `"Collapsed state"`           |
+| `disabled` attribute added                          | `"Disabled state"`            |
+| `aria-expanded` → `"true"`                          | `"Expanded state"`            |
+| `aria-expanded` → `"false"`                         | `"Collapsed state"`           |
+| `aria-busy` → `"true"`                              | `"Loading state"`             |
+| `aria-label` changed                                | `"Label changed to: <value>"` |
+| Structure change or unknown                         | `null`                        |
+
+### `LiveRenderer`
+
+Highlights a live DOM element with a fixed-position ring (useful for showing which element a stored ProductMemory state belongs to).
+
+```ts
+import { LiveRenderer } from "@unnoodle/browser";
+
+const renderer = new LiveRenderer();
+
+// Highlight an element
+renderer.show(document.getElementById("submit-btn")!);
+// → scrolls element into view + draws violet highlight ring
+
+// Remove highlight
+renderer.hide();
+```
+
+Calling `hide()` before `show()` is safe. Calling `show()` twice replaces the previous ring.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+---
+
+## License
+
+MIT © [Unnoodle](https://unnoodle.com)