@paikko/widget 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# @paikko/widget
+
+The consumer-installable paikko report widget. Mount it once in your app and
+users get a floating report button that captures the DOM, storage, client state,
+and provenance of what they were looking at, then POSTs a contract-valid
+`ReportBundle` to your paikko backend.
+
+The widget is backend-agnostic and store-agnostic: you configure where reports
+go (`endpoint`), which tenant they belong to (`projectKey`), where the review
+queue lives (`ticketsUrl`), and how to read your app's state (`getClientState`).
+
+## Install
+
+```bash
+npm install @paikko/widget @paikko/contract react
+```
+
+`react` is a peer dependency (>= 18.3.1). `@paikko/contract` carries the shared
+wire types/zod schemas and is required.
+
+> The widget ships raw TS/TSX source (its `exports` point at `./src`). With
+> Next.js, add it to `transpilePackages` so the host build transpiles it:
+>
+> ```js
+> // next.config.js
+> module.exports = { transpilePackages: ["@paikko/widget", "@paikko/contract"] };
+> ```
+
+## Usage
+
+Mount `<PaikkoProvider>` once, typically inside a `"use client"` island near the
+root of your app (the function-valued `getClientState` prop cannot cross the
+server/client boundary, so it must live in a client module):
+
+```tsx
+"use client";
+import { PaikkoProvider } from "@paikko/widget";
+import { getState } from "@/lib/store";
+
+export function PaikkoMount() {
+  return (
+    <PaikkoProvider
+      endpoint="http://localhost:8788/api/reports"
+      projectKey="my-app"
+      ticketsUrl="http://localhost:8788/tickets"
+      getClientState={getState}
+      reporter="anonymous"
+    />
+  );
+}
+```
+
+### `<PaikkoProvider>` props
+
+| Prop             | Type                               | Required | Description |
+|------------------|------------------------------------|----------|-------------|
+| `endpoint`       | `string`                           | yes      | Backend reports intake URL the bundle is POSTed to. May be cross-origin. |
+| `projectKey`     | `string \| null`                   | no       | Project/tenant key stamped onto every report (SaaS seam). Defaults to `null`. |
+| `apiKey`         | `string`                           | no       | Project **publishable** key (`pk_...`), sent as `x-paikko-key`. Required whenever the backend enforces auth (the default; off only with `PAIKKO_AUTH=disabled`). Public - never pass a secret key (`sk_...`). See the repo's `AUTH.md`. |
+| `ticketsUrl`     | `string`                           | no       | Absolute URL of the backend review queue. Renders a nav pill linking to it; omit to hide the pill. |
+| `getClientState` | `() => Record<string, unknown>`    | no       | Reader for your app's client state, snapshotted at report time. Pass your store's `getState` (or equivalent). Omit and client state is captured as `{}`. |
+| `reporter`       | `string`                           | no       | Who is filing the report. Defaults to `"anonymous"`. |
+| `enabled`        | `boolean`                          | no       | Whether to mount at all. **Defaults to dev-only** (`NODE_ENV !== "production"`), so the pills never ship to real users. Pass `true`/`false` to force it. |
+
+`PaikkoProvider` is the default export and also a named export. `ReportButton`,
+`PaikkoNav`, and the capture primitives are exported individually for hosts that
+want to compose the pieces themselves.
+
+## Environment & production (read this before deploying)
+
+paikko is a development/internal tool. Both the widget and the provenance plugin
+default to **dev-only** so nothing leaks into a production deploy, but there are
+two footguns worth knowing:
+
+- **Widget rendering.** `<PaikkoProvider>` renders only when `NODE_ENV !==
+  "production"` unless you pass `enabled`. To gate it from an env file, drive the
+  prop explicitly and put the flag in `.env.development` (loaded only by `next
+  dev`), **not** `.env.local` - Next loads `.env.local` in production builds too,
+  so a "dev" flag there silently enables the widget in prod:
+
+  ```tsx
+  <PaikkoProvider
+    enabled={process.env.NEXT_PUBLIC_PAIKKO_ENABLED === "true"}
+    endpoint="https://paikko.example.com/api/reports"
+    /* ... */
+  />
+  ```
+
+- **Provenance attributes.** The babel plugin no-ops when `NODE_ENV ===
+  "production"` by default, so `data-src` source paths never ship in prod HTML.
+  A JSON `.babelrc` cannot read env vars; if you need to force it on/off, use a
+  `.babelrc.js` and pass `{ enabled: process.env.NEXT_PUBLIC_PAIKKO_ENABLED ===
+  "true" }`. Clear `.next` / `node_modules/.cache` after changing this - a stale
+  babel cache keeps the old behavior.
+
+- **Cross-origin requests are safe.** The capture layer injects its
+  `x-paikko-trace` / `x-paikko-session` headers only on **same-origin** fetch/XHR
+  calls. Cross-origin requests (third-party CDNs, wasm, media) are still recorded
+  but their headers are left untouched, so paikko never trips a CORS preflight on
+  someone else's endpoint.
+
+## Provenance babel plugin (required)
+
+The widget's capture relies on a babel plugin that stamps source provenance onto
+your components at build time. Wire it into the consumer's babel config:
+
+- Plugin: `@paikko/widget/build/provenancePlugin`
+  (`packages/widget/src/build/provenancePlugin.cjs`)
+- Reference config: `examples/calculator/.babelrc`
+
+```json
+// .babelrc
+{
+  "presets": ["next/babel"],
+  "plugins": [
+    ["@paikko/widget/build/provenancePlugin", { "rootDir": "." }]
+  ]
+}
+```
+
+The `examples/calculator` app references the plugin by relative path
+(`../../packages/widget/src/build/provenancePlugin.cjs`) because it runs from
+inside this monorepo; a published consumer would use the package subpath shown
+above. The subpath resolves via the package `exports` map to
+`./src/build/provenancePlugin.cjs` (there is no literal `build/` dir); if your
+toolchain doesn't honor the exports map, fall back to the explicit path
+`./node_modules/@paikko/widget/src/build/provenancePlugin.cjs`.
+
+The plugin no-ops in production by default (see **Environment & production**), so
+the plain JSON `.babelrc` above is safe to commit - it emits provenance in dev
+and strips it from prod builds automatically.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@paikko/widget",
+  "version": "0.1.0",
+  "description": "paikko consumer report widget (PaikkoProvider, ReportButton, PaikkoNav, capture) + provenance plugin. Backend-agnostic: configurable endpoint, projectKey, ticketsUrl.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/willyt3hwhale/paikko.git",
+    "directory": "packages/widget"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./build/provenancePlugin": "./src/build/provenancePlugin.cjs"
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/build/provenancePlugin.cjs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@paikko/contract": "^0.1.0",
+    "html2canvas": "^1.4.1",
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.11",
+    "react": "^18.3.1",
+    "typescript": "^5.6.3"
+  }
+}

package/src/PaikkoNav.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+/**
+ * paikko `<PaikkoNav>` - a small global navigation pill that sits beside the
+ * `<ReportButton>` FAB and links to the review queue.
+ *
+ * It is mounted app-wide (alongside `<ReportButton>` in `<PaikkoProvider>`) so
+ * the user can reach the queue from anywhere. It is deliberately visually
+ * secondary to the Report FAB - an outlined dark pill rather than the solid
+ * primary fill - so Report stays the one-tap prominent action.
+ *
+ * Layout: the FAB lives at `right:20 bottom:20` (~78px wide). This pill sits
+ * just to its LEFT at `right:108 bottom:20`, clear of both the FAB and the
+ * report confirmation panel (which anchors at `right:20 bottom:76`).
+ *
+ * It is tagged `data-paikko-ui` so the capture controller ignores clicks on it
+ * (point-mode skips anything inside `[data-paikko-ui]`).
+ *
+ * The review UI now lives on the BACKEND origin (a separate deployment from the
+ * consumer app the widget is installed in), so the link target is a configurable
+ * `ticketsUrl` - typically an absolute URL like
+ * `https://api.example.com/tickets`. We render a plain `<a>` (not `next/link`)
+ * because the destination is cross-origin and because the widget must not depend
+ * on the host being a Next app. When `ticketsUrl` is omitted the pill is not
+ * rendered at all (an unconfigured nav is worse than no nav).
+ */
+import React from "react";
+
+export interface PaikkoNavProps {
+  /**
+   * Absolute URL of the backend review queue (e.g.
+   * `https://api.example.com/tickets`). Omit to hide the nav pill.
+   */
+  ticketsUrl?: string;
+  /** Pill label. Defaults to "Tickets". */
+  label?: string;
+}
+
+export function PaikkoNav({
+  ticketsUrl,
+  label = "Tickets",
+}: PaikkoNavProps): React.JSX.Element | null {
+  if (!ticketsUrl) return null;
+
+  return (
+    <div data-paikko-ui="nav" style={styles.root}>
+      <a
+        href={ticketsUrl}
+        data-paikko-ui="nav-link"
+        style={styles.pill}
+        aria-label="Review tickets"
+      >
+        {label}
+      </a>
+    </div>
+  );
+}
+
+const Z = 2147483000; // match the ReportButton stacking context
+
+const styles: Record<string, React.CSSProperties> = {
+  root: {
+    position: "fixed",
+    inset: 0,
+    pointerEvents: "none",
+    zIndex: Z,
+    fontFamily:
+      "system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif",
+  },
+  pill: {
+    position: "fixed",
+    right: 108, // just left of the FAB (right:20, ~78px wide) - never overlaps
+    bottom: 20,
+    pointerEvents: "auto",
+    display: "inline-flex",
+    alignItems: "center",
+    padding: "10px 16px",
+    borderRadius: 999,
+    // Outlined / lighter so it reads as secondary to the solid Report FAB.
+    border: "1px solid rgba(255,255,255,0.18)",
+    background: "rgba(17,24,39,0.85)",
+    color: "#e5e7eb",
+    fontSize: 14,
+    fontWeight: 600,
+    textDecoration: "none",
+    cursor: "pointer",
+    boxShadow: "0 6px 20px rgba(0,0,0,0.25)",
+    whiteSpace: "nowrap",
+  },
+};
+
+export default PaikkoNav;

package/src/PaikkoProvider.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+/**
+ * Client boundary that mounts the paikko `<ReportButton>` (and optional
+ * `<PaikkoNav>` pill) once for the whole host app.
+ *
+ * The host app's root layout is typically a server component, so the capture
+ * entry point has to be mounted inside a `"use client"` island. This is that
+ * island. The widget is backend-agnostic and store-agnostic:
+ *
+ *  - `endpoint` / `projectKey` configure where reports go and which tenant they
+ *    belong to (forwarded to `<ReportButton>`); the bundle is POSTed there
+ *    cross-origin.
+ *  - `ticketsUrl` configures the review-queue link (forwarded to `<PaikkoNav>`);
+ *    omit it to hide the nav pill.
+ *  - `getClientState` is supplied BY THE HOST APP - the provider does not import
+ *    any store. The host passes its own store's `getState` (or equivalent) so
+ *    the `clientState` artifact is captured from the host's app state at report
+ *    time. Omit it and client state is captured as `{}`.
+ */
+import React from "react";
+import { ReportButton } from "./ReportButton";
+import { PaikkoNav } from "./PaikkoNav";
+
+export interface PaikkoProviderProps {
+  /** Backend reports intake URL the bundle is POSTed to (may be cross-origin). */
+  endpoint: string;
+  /** Project/tenant key stamped onto every report (SaaS seam). */
+  projectKey?: string | null;
+  /**
+   * The project's PUBLISHABLE api key (pk_...), forwarded to `<ReportButton>` and
+   * sent as `x-paikko-key`. Required only when the backend enforces auth
+   * (enforced by default; off via PAIKKO_AUTH=disabled). Public key - never pass a secret (sk_...).
+   */
+  apiKey?: string;
+  /** Absolute URL of the backend review queue; omit to hide the nav pill. */
+  ticketsUrl?: string;
+  /** Reader for the host app's client state, snapshotted at report time. */
+  getClientState?: () => Record<string, unknown>;
+  /** Who is filing. Defaults to "anonymous" inside `<ReportButton>`. */
+  reporter?: string;
+  /**
+   * Whether to mount the widget at all. paikko is a development/internal tool, so
+   * by DEFAULT it renders only when `NODE_ENV !== "production"` - the pills never
+   * ship to real end-users unless you opt in. Pass `true`/`false` to force it
+   * (e.g. `enabled={process.env.NEXT_PUBLIC_PAIKKO_ENABLED === "true"}` to drive
+   * it from a dev-only env file like `.env.development`).
+   */
+  enabled?: boolean;
+}
+
+export function PaikkoProvider({
+  endpoint,
+  projectKey = null,
+  apiKey,
+  ticketsUrl,
+  getClientState,
+  reporter,
+  enabled,
+}: PaikkoProviderProps): React.JSX.Element | null {
+  const active =
+    enabled ?? process.env.NODE_ENV !== "production";
+  if (!active) return null;
+
+  return (
+    <>
+      <ReportButton
+        endpoint={endpoint}
+        projectKey={projectKey}
+        apiKey={apiKey}
+        getClientState={getClientState}
+        reporter={reporter}
+      />
+      <PaikkoNav ticketsUrl={ticketsUrl} />
+    </>
+  );
+}
+
+export default PaikkoProvider;