inverse-interface 0.0.0-stage → 0.1.0

package/LICENSE

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

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# inverse-interface
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The open runtime for [Inverse Interface](https://www.inverse.at/docs/interface): record what people do in your web app as semantic events, ask for their consent first, and turn a session into an intent package your coding agent can act on. MIT, zero dependencies, plain ESM. No build step needed.
+
+## Free anywhere vs metered
+
+| Runs free, anywhere (this package) | Metered, via the hosted API |
+| --- | --- |
+| The recorder, redaction, the consent prompt, the room link, the `interface-event.v1` and `intent.v1` formats, and the heuristic `buildIntent()` | Hosted sessions (`capture_session`), hosted intent packages (`intent_package`), rooms, answered asks and proposals |
+
+You need no Inverse account to use this package. Metering happens only on Inverse's servers, when a billable artifact is produced. The hosted API accepts events from anywhere, including your own recorder, so nothing here is "unlocked" by a license.
+
+## Quickstart: the script tag
+
+```html
+<script src="https://www.inverse.at/v1-0.1.0.js" integrity="sha384-…" crossorigin="anonymous"></script>
+<script>Inverse.capture({ key: "pk_live_…", task: "Sign up and create a project" });</script>
+```
+
+`/v1.js` always serves the latest 1.x. Pin `/v1-<version>.js` with its `integrity` hash, listed at [inverse.at/docs/interface](https://www.inverse.at/docs/interface). The `pk_` key is publishable, and the API accepts it only from your project's allowlisted domains.
+
+```js
+Inverse.on("event", (e) => console.log(e.kind, e.target));
+Inverse.on("end", (pkg) => console.log(pkg)); // intent.v1 from the hosted API
+const capture = await Inverse.capture({ key, task, solo: true }); // null if they chose "Not now"
+await capture?.end();
+Inverse.room({ url: "https://your-app.com" }); // open an Inverse room around a URL
+```
+
+## npm
+
+```sh
+npm i inverse-interface
+```
+
+```js
+import { createRecorder } from "inverse-interface/recorder";
+import { buildIntent } from "inverse-interface/intent";
+
+const events = [];
+const recorder = createRecorder({ emit: (e) => events.push({ ...e, session: "local" }) }).start();
+// later: no network, no account
+console.log(buildIntent(events, { task: "Check out" }));
+```
+
+| Import | What it is |
+| --- | --- |
+| `inverse-interface/recorder` | `createRecorder({ emit })` → `start()`, `stop()`, `pause(on)`. Navigation (including SPA history), clicks with accessible label, role and short selector, form submits, errors, rage clicks (3+ in 600ms), dead clicks (no DOM change or navigation within 1s), scroll depth (25/50/75/100). |
+| `inverse-interface/consent` | `createConsent({ app })` → `ask()`, `showIndicator({ onPause, onStop })`. A shadow-DOM prompt with equal Allow and Not now buttons, remembered for the site. |
+| `inverse-interface/client` | `createClient({ key })` for the hosted API, and the page-level `capture`, `room` and `on`. |
+| `inverse-interface/intent` | `buildIntent(events, { task })` → `intent.v1`. Deterministic, local. |
+| `inverse-interface/schema` | `eventErrors`, `redactEvent`, `intentErrors` and the JSON Schemas. |
+
+## Bring your own events
+
+Already capture sessions some other way? Send `interface-event.v1` events with a secret key and get an intent package back. Inverse doesn't need to have captured them.
+
+```sh
+curl https://www.inverse.at/v1/intent-packages \
+  -H "Authorization: Bearer sk_live_…" -H "Content-Type: application/json" \
+  -d '{"task":"Check out","events":[{"v":1,"t":1793491200000,"session":"s1","kind":"click","path":"/cart","target":{"label":"Pay","role":"button"}}]}'
+```
+
+## Privacy
+
+- **Consent first.** Nothing is recorded until the person chooses Allow. Every batch carries the consent record, and the API rejects events without it.
+- **Never input values.** The recorder never reads `.value`, nor the text of fields or editable content. A submit says that a form was sent, not what was in it.
+- **Redaction at source.** It skips `input[type=password]`, payment fields (`autocomplete="cc-*"`), and everything inside `[data-inverse-redact]`. Only the path is kept, never the query string or hash. The client redacts again with `redactEvent`, and so does the server.
+- **Who sees it:** the team that runs the app and their coding agent, as "Speaker A". A persistent indicator lets the person pause or stop at any time.
+
+Docs: [inverse.at/docs/interface](https://www.inverse.at/docs/interface)

package/browser.js

@@ -0,0 +1,3 @@
+// The script build (public/v1.js): esbuild bundles this as an IIFE with the global `Inverse`.
+export { capture, room, on } from "./client.js";
+export const version = "0.1.0";

package/client.d.ts

@@ -0,0 +1,25 @@
+import type { RecordedEvent } from "./recorder.js";
+import type { SavedConsent } from "./consent.js";
+export const ORIGIN: string;
+export const MAX_EVENTS: number, MAX_BYTES: number, BEACON_BYTES: number, FLUSH_MS: number;
+export type Session = { id: string; link?: string; upload?: string };
+export function batches<T>(events: T[], maxEvents?: number, maxBytes?: number): T[][];
+export function roomLink(url: string, origin?: string): string;
+export type Client = {
+  readonly session: Session | null;
+  start(options?: { task?: string; mode?: "live" | "solo"; meta?: Record<string, unknown> }): Promise<Session>;
+  push(event: RecordedEvent): void;
+  flush(options?: { beacon?: boolean }): Promise<void>;
+  end(): Promise<unknown>;
+};
+export function createClient(options: {
+  key: string;
+  origin?: string;
+  consent: () => SavedConsent | null;
+  fetch?: typeof fetch;
+  beacon?: (url: string, body: string) => boolean;
+}): Client;
+export function on(type: "consent" | "session" | "event" | "end" | "error", fn: (data: any) => void): () => void;
+export function room(options?: { url?: string; origin?: string }): string;
+export type Capture = { session: Session | null; pause(on?: boolean): void; end(): Promise<unknown> };
+export function capture(options: { key: string; task?: string; solo?: boolean; origin?: string; app?: string; meta?: Record<string, unknown> }): Promise<Capture | null>;

package/client.js

@@ -0,0 +1,147 @@
+/*
+ * inverse-interface/client: sends recorded events to the hosted Inverse API (metered there, never here).
+ * Inverse.capture() = consent first, then a session, then the recorder, batched every few seconds and
+ * flushed with sendBeacon when the page goes away. Inverse.room() opens an Inverse room around a URL.
+ */
+import { createRecorder } from "./recorder.js";
+import { createConsent, consentPayload } from "./consent.js";
+import { redactEvent } from "./schema.js";
+
+export const ORIGIN = "https://www.inverse.at";
+export const MAX_EVENTS = 500, MAX_BYTES = 256 * 1024, BEACON_BYTES = 60 * 1024, FLUSH_MS = 5000;
+const size = (x) => new TextEncoder().encode(JSON.stringify(x)).length;
+
+/** Splits events into batches of ≤ maxEvents and ≤ maxBytes of JSON (1 KB kept for the envelope). Oversized single events are dropped. */
+export function batches(events, maxEvents = MAX_EVENTS, maxBytes = MAX_BYTES) {
+  const out = [], room = maxBytes - 1024;
+  let batch = [], bytes = 0;
+  for (const e of events) {
+    const n = size(e) + 1;
+    if (n > room) continue;
+    if (batch.length >= maxEvents || bytes + n > room) out.push(batch), (batch = []), (bytes = 0);
+    batch.push(e);
+    bytes += n;
+  }
+  if (batch.length) out.push(batch);
+  return out;
+}
+
+/** A link that opens an Inverse room around `url` (the landing page's paste-a-URL flow). */
+export const roomLink = (url, origin = ORIGIN) => `${origin}/?url=${encodeURIComponent(url)}`;
+
+/** createClient({ key, origin }) → { start, push, flush, end }. `key` is a publishable pk_… key. */
+/** The session id a solo capture link carries, if this page was opened from one. */
+export function linkedSession(href = globalThis.location?.href) {
+  try {
+    const id = href ? new URL(href).searchParams.get("inverse_session") : null;
+    return id && /^ses_[a-z0-9]{24}$/.test(id) ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+export function createClient({ key, origin = ORIGIN, consent, fetch = globalThis.fetch.bind(globalThis), beacon = globalThis.navigator?.sendBeacon?.bind(globalThis.navigator) }) {
+  let session = null, queue = [];
+  const call = async (path, body, opts = {}) => {
+    const res = await fetch(origin + path, { method: "POST", keepalive: opts.keepalive, headers: { authorization: `Bearer ${key}`, "content-type": "application/json" }, body: JSON.stringify(body ?? {}) });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) throw Object.assign(new Error(json.error ?? `Inverse ${res.status}`), { status: res.status });
+    return json;
+  };
+  const client = {
+    get session() {
+      return session;
+    },
+    /** Joins the session a solo capture link names (`?inverse_session=ses_…`), else POST /v1/sessions → { id, link?, upload }. */
+    async start({ task, mode = "live", meta, join = linkedSession() } = {}) {
+      session = join ? { id: join, mode: "solo", task } : await call("/v1/sessions", { task, mode, meta });
+      return session;
+    },
+    push(event) {
+      queue.push(event);
+    },
+    /** Sends what's queued. With `{ beacon: true }` (page going away) it uses sendBeacon, keyed by ?key= since beacons carry no headers. */
+    async flush({ beacon: away = false } = {}) {
+      const grant = consentPayload(consent());
+      if (!session || !queue.length || !grant) return;
+      const events = queue.splice(0).map((e) => redactEvent({ ...e, session: session.id })); // redacted again here and on the server
+      const upload = session.upload ?? `/v1/sessions/${session.id}/events`;
+      for (const batch of batches(events, MAX_EVENTS, away ? BEACON_BYTES : MAX_BYTES)) {
+        const body = { consent: grant, events: batch };
+        // A text/plain beacon needs no CORS preflight; the API reads the body as JSON either way.
+        if (away && beacon?.(`${origin}${upload}?key=${encodeURIComponent(key)}`, JSON.stringify(body))) continue;
+        await call(upload, body, { keepalive: away }).catch((e) => (away ? undefined : (queue.unshift(...batch), Promise.reject(e))));
+      }
+    },
+    /** Flushes, then POST /v1/sessions/:id/end, which builds the intent package on the server. */
+    async end() {
+      if (!session) return null;
+      await client.flush();
+      const result = await call(`/v1/sessions/${session.id}/end`);
+      session = null;
+      return result;
+    },
+  };
+  return client;
+}
+
+// ── The page-level API (window.Inverse in the script build) ──
+
+const listeners = new Map();
+const fire = (type, data) => listeners.get(type)?.forEach((fn) => fn(data));
+
+/** Inverse.on("consent" | "session" | "event" | "end" | "error", fn) → unsubscribe. */
+export function on(type, fn) {
+  if (!listeners.has(type)) listeners.set(type, new Set());
+  listeners.get(type).add(fn);
+  return () => listeners.get(type).delete(fn);
+}
+
+/** Inverse.room({ url }): opens an Inverse room around `url` (default: this page) in a new tab, and returns the link. */
+export function room({ url = globalThis.location?.href, origin = ORIGIN } = {}) {
+  const link = roomLink(url, origin);
+  globalThis.open?.(link, "_blank", "noopener");
+  return link;
+}
+
+/**
+ * Inverse.capture({ key, task, solo, origin, app }) → Promise<{ session, pause, end } | null>.
+ * Asks for consent first; resolves null when the person says Not now. `solo` makes a solo (unmoderated) session.
+ */
+export async function capture({ key, task, solo = false, origin = ORIGIN, app, meta } = {}) {
+  if (!/^pk_(test|live)_/.test(key ?? "")) throw new Error("Inverse.capture needs a publishable key (pk_test_… or pk_live_…)");
+  const consent = createConsent({ app });
+  const allowed = await consent.ask();
+  fire("consent", { granted: allowed });
+  if (!allowed) return null;
+  const client = createClient({ key, origin, consent: consent.get });
+  try {
+    fire("session", await client.start({ task, mode: solo ? "solo" : "live", meta }));
+  } catch (e) {
+    fire("error", e);
+    return null;
+  }
+  const recorder = createRecorder({ emit: (e) => (client.push(e), fire("event", e)) });
+  const report = (e) => fire("error", e);
+  const timer = setInterval(() => client.flush().catch(report), FLUSH_MS);
+  const away = () => void client.flush({ beacon: true });
+  const hidden = () => document.visibilityState === "hidden" && away();
+  addEventListener("pagehide", away);
+  document.addEventListener("visibilitychange", hidden);
+  const stop = () => {
+    recorder.stop();
+    clearInterval(timer);
+    removeEventListener("pagehide", away);
+    document.removeEventListener("visibilitychange", hidden);
+    consent.remove();
+  };
+  const end = async () => {
+    stop();
+    const result = await client.end().catch((e) => (report(e), null));
+    fire("end", result);
+    return result;
+  };
+  consent.showIndicator({ onPause: (p) => recorder.pause(p), onStop: () => void end() });
+  recorder.start();
+  return { session: client.session, pause: (p = true) => recorder.pause(p), end };
+}

package/consent.d.ts

@@ -0,0 +1,15 @@
+export type SavedConsent = { answer: "allow" | "no"; at: number };
+export type ConsentPayload = { granted: true; at: number; scope: string[] };
+type Store = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+export const CONSENT_KEY: string;
+export const SCOPE: string[];
+export function loadConsent(storage: Store | null | undefined): SavedConsent | null;
+export function saveConsent(storage: Store | null | undefined, answer: "allow" | "no" | null, at?: number): SavedConsent | null;
+export function consentPayload(saved: SavedConsent | null): ConsentPayload | null;
+export type Consent = {
+  get(): SavedConsent | null;
+  ask(force?: boolean): Promise<boolean>;
+  showIndicator(handlers?: { onPause?: (paused: boolean) => void; onStop?: () => void }): void;
+  remove(): void;
+};
+export function createConsent(options?: { app?: string; win?: Window; storage?: Store | null }): Consent;

package/consent.js

@@ -0,0 +1,110 @@
+/*
+ * inverse-interface/consent: a plain-language ask in its own shadow DOM, then a small indicator with Pause.
+ * Nothing is recorded before someone says Allow. The answer is remembered for this site (localStorage is per origin).
+ */
+
+export const CONSENT_KEY = "inverse:interface:consent";
+export const SCOPE = ["navigation", "clicks", "submits", "errors", "scroll"];
+
+/** The saved answer, `{ answer: "allow" | "no", at }`, or null when never asked or unreadable. */
+export function loadConsent(storage) {
+  try {
+    const saved = JSON.parse(storage?.getItem(CONSENT_KEY) ?? "null");
+    return saved?.answer === "allow" || saved?.answer === "no" ? { answer: saved.answer, at: Number(saved.at) || 0 } : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveConsent(storage, answer, at = Date.now()) {
+  try {
+    if (answer) storage?.setItem(CONSENT_KEY, JSON.stringify({ answer, at }));
+    else storage?.removeItem(CONSENT_KEY);
+  } catch {}
+  return answer ? { answer, at } : null;
+}
+
+/** The consent block every event batch carries. */
+export const consentPayload = (saved) => (saved?.answer === "allow" ? { granted: true, at: saved.at, scope: SCOPE } : null);
+
+const CSS = `
+:host{all:initial}
+*{box-sizing:border-box;font:14px/1.5 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
+.card,.pill{position:fixed;z-index:2147483647;right:16px;bottom:16px;color:#0a0a0a;background:#fff;border:1px solid #0001;box-shadow:0 14px 32px -16px #111a2c80}
+.card{width:min(24rem,calc(100vw - 32px));border-radius:16px;padding:16px;animation:in .18s ease-out}
+.pill{display:flex;align-items:center;gap:8px;border-radius:999px;padding:4px 4px 4px 12px;font-size:12px}
+p{margin:0 0 8px}.t{font-weight:600}b{font:inherit;font-weight:600}.s{font-size:12px;color:#525252}
+.row{display:grid;grid-template-columns:1fr 1fr;gap:6px;margin-top:12px}
+button{cursor:pointer;border:0;border-radius:999px;background:#f0f0f0;color:inherit;padding:8px 12px;font-weight:500;min-height:32px}
+.pill button{font-size:12px;padding:4px 10px;min-height:28px}
+button:hover{background:#e5e5e5}button:focus-visible{outline:2px solid #2563eb;outline-offset:2px}
+.dot{width:8px;height:8px;border-radius:50%;background:#16a34a}.dot.off{background:#a3a3a3}
+@media (pointer:coarse){button{min-height:44px}}
+@media (prefers-color-scheme:dark){.card,.pill{color:#fafafa;background:#171717;border-color:#fff2}.s{color:#a3a3a3}button{background:#262626}button:hover{background:#333}}
+@media (prefers-reduced-motion:reduce){.card{animation:none}}
+@keyframes in{from{opacity:0;transform:translateY(8px)}}`;
+
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+/**
+ * createConsent({ app }) → { ask(): Promise<boolean>, get(), showIndicator({ onPause, onStop }), remove() }.
+ * `app` names the site in the copy ("Acme"); it defaults to the hostname.
+ */
+export function createConsent({ app, win = globalThis.window, storage = (() => { try { return win.localStorage; } catch { return null; } })() } = {}) {
+  const name = esc(app ?? win.location.hostname);
+  let host;
+  const mount = (html) => {
+    host?.remove();
+    host = win.document.createElement("div");
+    host.setAttribute("data-inverse-redact", ""); // the recorder never records its own UI
+    const root = host.attachShadow({ mode: "open" });
+    root.innerHTML = `<style>${CSS}</style>${html}`;
+    win.document.body.append(host);
+    return root;
+  };
+  return {
+    get: () => loadConsent(storage),
+    /** Resolves true when allowed. Asks only when never answered; a remembered "Not now" resolves false. */
+    ask(force = false) {
+      const saved = loadConsent(storage);
+      if (saved && !force) return Promise.resolve(saved.answer === "allow");
+      const before = win.document.activeElement;
+      const root = mount(`<section class="card" role="dialog" aria-modal="false" aria-labelledby="t" aria-describedby="d">
+<p class="t" id="t">Let ${name}'s team see how you use this page?</p>
+<div id="d"><p>Where you click and which pages you visit become notes the team can use to fix what gets in your way.</p>
+<p class="s"><b>Captured:</b> pages you visit, the buttons and links you click, that a form was sent, errors, and how far you scroll.</p>
+<p class="s"><b>Never captured:</b> what you type, passwords, payment details, or your screen.</p>
+<p class="s">The team that runs this app and their coding agent see it, as &ldquo;Speaker A&rdquo;. You can pause any time.</p></div>
+<div class="row"><button data-a="allow">Allow</button><button data-a="no">Not now</button></div></section>`);
+      return new Promise((resolve) => {
+        const answer = (a) => {
+          saveConsent(storage, a);
+          host.remove();
+          before?.focus?.({ preventScroll: true });
+          resolve(a === "allow");
+        };
+        root.querySelectorAll("button").forEach((b) => (b.onclick = () => answer(b.dataset.a)));
+        root.querySelector("section").onkeydown = (e) => e.key === "Escape" && answer("no");
+        root.querySelector("button").focus({ preventScroll: true });
+      });
+    },
+    /** The persistent indicator: a dot, what's happening, Pause/Resume, and Stop (remembered as "Not now"). */
+    showIndicator({ onPause, onStop } = {}) {
+      const root = mount(`<div class="pill" role="status" aria-live="polite"><span class="dot" aria-hidden="true"></span><span class="m">Sharing clicks with ${name}</span><button data-a="pause">Pause</button><button data-a="stop">Stop</button></div>`);
+      let paused = false;
+      root.querySelector('[data-a="pause"]').onclick = (e) => {
+        paused = !paused;
+        e.currentTarget.textContent = paused ? "Resume" : "Pause";
+        root.querySelector(".dot").classList.toggle("off", paused);
+        root.querySelector(".m").textContent = paused ? "Paused. Nothing is shared." : `Sharing clicks with ${app ?? win.location.hostname}`;
+        onPause?.(paused);
+      };
+      root.querySelector('[data-a="stop"]').onclick = () => {
+        saveConsent(storage, "no");
+        host.remove();
+        onStop?.();
+      };
+    },
+    remove: () => host?.remove(),
+  };
+}

package/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./recorder.js";
+export * from "./consent.js";
+export * from "./client.js";
+export * from "./schema.js";
+export * from "./intent.js";

package/index.js

@@ -0,0 +1,5 @@
+export * from "./recorder.js";
+export * from "./consent.js";
+export * from "./client.js";
+export * from "./schema.js";
+export * from "./intent.js";

package/intent.d.ts

@@ -0,0 +1,11 @@
+import type { Intent, InterfaceEvent } from "./schema.js";
+export type { Intent, InterfaceEvent } from "./schema.js";
+
+export declare function classify(line: string): "friction" | "request" | "question" | "praise" | null;
+/** 0 → "Speaker A", 25 → "Speaker Z", 26 → "Speaker AA". */
+export declare function aliasLabel(index: number): string;
+/** interface-event.v1[] → intent.v1. Deterministic heuristics; `quality.billable` is the zero-rating gate. */
+export declare function buildIntent(
+  events: readonly unknown[] | InterfaceEvent[],
+  options?: { task?: string; id?: string; session?: string | null; now?: number },
+): Intent;

package/intent.js

@@ -0,0 +1,146 @@
+// The pure intent builder: interface-event.v1[] → intent.v1. Deterministic heuristics, no dependencies, runs anywhere.
+// ponytail: keyword and event-pattern rules only; the hosted LLM pass for goal, outcome and friction comes later
+// (docs/interaction-primitives-plan.md, weeks 3-4) and will refine this package, not replace the format.
+import { eventErrors, redactEvent } from "./schema.js";
+
+// Same rules as inverse-embed's room classifier (context.js `classify`); a parity test keeps them in step.
+const RULES = [
+  ["friction", /\b(can[’']?t|cannot|doesn[’']?t work|does not work|not working|won[’']?t|stuck|broken|confus\w*|ugh|bug)\b/i],
+  ["request", /\b(can you|could you|should|i want|i[’']?d like|add|wish)\b/i],
+  ["question", /\?|\b(how|why|where|can i)\b/i],
+  ["praise", /\b(love|nice|great|wow|awesome|amazing)\b/i],
+];
+/** A said line → "friction" | "request" | "question" | "praise" | null. First match wins. */
+export const classify = (line) => RULES.find(([, re]) => re.test(line))?.[0] ?? null;
+
+/** 0 → "Speaker A", 25 → "Speaker Z", 26 → "Speaker AA". */
+export function aliasLabel(index) {
+  let letters = "";
+  for (let n = index + 1; n > 0; n = Math.floor((n - 1) / 26)) letters = String.fromCharCode(65 + ((n - 1) % 26)) + letters;
+  return `Speaker ${letters}`;
+}
+
+const DONE = /^(done|complete|completed|achieved|success|succeeded)$/i;
+const GAVE_UP = /^(abandon|abandoned|failed|gave_up|give_up|skipped|cancel|cancelled|canceled)$/i;
+const FRICTION_EVENTS = new Set(["error", "rage_click", "dead_click"]);
+const MERGE_MS = 30_000; // repeats of the same friction within this window are one item with more evidence
+const CAP = { timeline: 1_000, signals: 500, friction: 200 };
+
+const label = (e) => e.target?.label || e.target?.selector || e.target?.role || "";
+const quoteOf = (s) => (s.length > 80 ? `${s.slice(0, 77)}…` : s);
+function describe(e) {
+  const d = e.data ?? {};
+  switch (e.kind) {
+    case "navigate": return e.path || "page";
+    case "error": return `${typeof d.message === "string" ? d.message.slice(0, 200) : "error"}${e.path ? ` (on ${e.path})` : ""}`;
+    case "scroll_depth": return `${Number(d.depth) || 0}%`;
+    case "reaction": return String(d.emoji ?? d.expression ?? "reaction").slice(0, 40);
+    case "task": return `${e.text ?? "task"}${typeof d.status === "string" ? ` (${d.status})` : ""}`;
+    case "say": case "custom": return e.text ?? (typeof d.command === "string" ? d.command : e.kind);
+    default: return label(e) || e.path || e.kind;
+  }
+}
+// FNV-1a: a stable id from the events, so the same input always builds the same package.
+function hash(text) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 0x01000193);
+  return (h >>> 0).toString(36);
+}
+
+/**
+ * interface-event.v1[] → intent.v1. Invalid events are skipped; the rest are redacted again and read in time order.
+ * `evidence` holds indexes into the array you passed. `quality.billable` is false (zero-rated) when the session is under
+ * 60s, has fewer than 5 meaningful events, or holds no task, signals or friction.
+ */
+export function buildIntent(input, { task, id, session, now = Date.now() } = {}) {
+  const events = (Array.isArray(input) ? input : [])
+    .map((e, i) => (eventErrors(e).length ? null : { ...redactEvent(e), i }))
+    .filter(Boolean)
+    .sort((a, b) => a.t - b.t || a.i - b.i);
+
+  // Aliases in first-appearance order: an agent sees "Speaker A", never a name. No `by` (solo capture) is one person.
+  const aliases = new Map();
+  const who = (e) => {
+    const key = e.by ?? "";
+    if (!aliases.has(key)) aliases.set(key, { alias: aliasLabel(aliases.size), events: 0 });
+    return aliases.get(key);
+  };
+
+  const timeline = [], signals = [], friction = [], open = new Map();
+  const rub = (kind, at, text, i, quote) => {
+    const key = `${kind}|${text}`, last = open.get(key);
+    if (last && at - last.seen <= MERGE_MS) {
+      last.seen = at;
+      if (last.item.evidence.length < 50) last.item.evidence.push(i);
+      return;
+    }
+    const item = { at, kind, text, evidence: [i], ...(quote ? { quote } : {}) };
+    friction.push(item);
+    open.set(key, { item, seen: at });
+  };
+  const goalFromEvents = events.find((e) => e.kind === "task" && e.text)?.text;
+  const goal = (typeof task === "string" && task.trim().slice(0, 500)) || goalFromEvents;
+  let ended = null; // "done" | "abandon": the last explicit task status
+
+  for (const e of events) {
+    const p = who(e), by = p.alias, text = describe(e), d = e.data ?? {};
+    p.events++;
+    timeline.push({ at: e.t, by, kind: e.kind, text });
+    if (e.kind === "say" && e.text) {
+      const kind = d.feedback === true ? "feedback" : classify(e.text);
+      if (kind) signals.push({ kind, by, text: e.text, at: e.t });
+      if (kind === "friction") rub("said", e.t, "Said something isn't working", e.i, quoteOf(e.text));
+    } else if (e.kind === "custom" && typeof d.command === "string") {
+      signals.push({ kind: "command", by, text, at: e.t });
+    } else if (e.kind === "rage_click") rub("rage_click", e.t, `Clicked "${label(e) || "something"}" again and again`, e.i);
+    else if (e.kind === "dead_click") rub("dead_click", e.t, `Clicked "${label(e) || "something"}" and nothing happened`, e.i);
+    else if (e.kind === "error") rub("error", e.t, `Error: ${text}`, e.i);
+    else if (e.kind === "task" && typeof d.status === "string") {
+      if (DONE.test(d.status)) ended = "done";
+      else if (GAVE_UP.test(d.status)) {
+        ended = "abandon";
+        rub("abandoned", e.t, `Gave up on: ${e.text ?? goal ?? "the task"}`, e.i);
+      }
+    }
+  }
+
+  const meaningful = events.filter((e) => e.kind !== "scroll_depth");
+  let outcome = "unknown";
+  if (ended === "done") outcome = "achieved";
+  else if (ended === "abandon") outcome = "abandoned";
+  else if (goal && meaningful.length) {
+    // Unfinished: friction among the last three things they did, with no submit after it, reads as giving up.
+    const hurt = meaningful.findLastIndex((e) => FRICTION_EVENTS.has(e.kind) || (e.kind === "say" && e.text && classify(e.text) === "friction"));
+    if (hurt >= 0 && hurt >= meaningful.length - 3 && !meaningful.slice(hurt + 1).some((e) => e.kind === "submit")) {
+      outcome = "abandoned";
+      const last = meaningful.at(-1);
+      rub("abandoned", last.t, `Left without finishing: ${goal}`, last.i);
+    } else if (meaningful.some((e) => e.kind === "submit")) outcome = "partial";
+  }
+
+  const span = events.length ? events.at(-1).t - events[0].t : 0;
+  const found = (goal ? 1 : 0) + signals.length + friction.length;
+  const reasons = [
+    ...(span < 60_000 ? ["Session shorter than 60s"] : []),
+    ...(meaningful.length < 5 ? ["Fewer than 5 meaningful events"] : []),
+    ...(found ? [] : ["No task, signals or friction found"]),
+  ];
+  const score = Math.round((0.3 * Math.min(1, span / 300_000) + 0.3 * Math.min(1, meaningful.length / 25) + 0.4 * Math.min(1, found / 5)) * 100) / 100;
+  const sessionId = session ?? events[0]?.session ?? null;
+
+  return {
+    schema: "intent.v1",
+    id: id ?? `ipk_${hash(JSON.stringify([sessionId, events.map(({ i: _i, ...e }) => e)]))}`,
+    session: sessionId,
+    ...(goal ? { task: goal } : {}),
+    generatedAt: now,
+    outcome,
+    ...(goal ? { goal } : {}),
+    friction: friction.slice(0, CAP.friction),
+    signals: signals.slice(0, CAP.signals),
+    timeline: timeline.slice(-CAP.timeline),
+    participants: [...aliases.values()],
+    quality: { score, billable: reasons.length === 0, reasons },
+    confidence: score >= 0.6 ? "medium: heuristics only" : "low: heuristics only",
+  };
+}

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "inverse-interface",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Open runtime for Inverse Interface: a privacy-first semantic recorder, consent prompt, intent builder and client for the hosted API. Runs anywhere, free.",
+  "type": "module",
+  "exports": {
+    ".": { "types": "./index.d.ts", "default": "./index.js" },
+    "./recorder": { "types": "./recorder.d.ts", "default": "./recorder.js" },
+    "./consent": { "types": "./consent.d.ts", "default": "./consent.js" },
+    "./client": { "types": "./client.d.ts", "default": "./client.js" },
+    "./intent": { "types": "./intent.d.ts", "default": "./intent.js" },
+    "./schema": { "types": "./schema.d.ts", "default": "./schema.js" }
+  },
+  "files": ["index.js", "index.d.ts", "recorder.js", "recorder.d.ts", "consent.js", "consent.d.ts", "client.js", "client.d.ts", "intent.js", "intent.d.ts", "schema.js", "schema.d.ts", "browser.js", "README.md", "LICENSE"],
+  "license": "MIT",
+  "sideEffects": false,
+  "homepage": "https://www.inverse.at/docs/interface",
+  "keywords": ["inverse", "session", "intent", "consent", "agents", "analytics"]
+}

package/recorder.d.ts

@@ -0,0 +1,14 @@
+export type InterfaceTarget = { label?: string; role?: string; selector?: string };
+export type RecordedEvent = { v: 1; t: number; kind: string; path: string; target?: InterfaceTarget; data?: Record<string, unknown> };
+export const RAGE_CLICKS: number, RAGE_MS: number, DEAD_MS: number, SCROLL_MILESTONES: number[];
+export function sensitive(el: Element): boolean;
+export function redacted(el: Element): boolean;
+export function role(el: Element): string | undefined;
+export function label(el: Element, doc?: Document): string | undefined;
+export function selector(el: Element): string;
+export function target(el: Element): InterfaceTarget;
+export function rageDetector(count?: number, ms?: number): (key: string, t: number) => boolean;
+export function isDead(clickAt: number, lastChangeAt: number, now: number): boolean;
+export function milestones(percent: number, seen: Set<number>): number[];
+export type Recorder = { start(): Recorder; stop(): void; pause(on?: boolean): void };
+export function createRecorder(options: { emit: (event: RecordedEvent) => void; win?: Window }): Recorder;

package/recorder.js

@@ -0,0 +1,147 @@
+/*
+ * inverse-interface/recorder: semantic DOM events (interface-event.v1) without the content.
+ * Redaction happens here, at the source: it never reads `.value`, never reads text from fields or editable
+ * content, and skips password fields, payment fields (autocomplete="cc-*") and [data-inverse-redact] subtrees.
+ * Only the path is recorded, never the query string or hash (they can hold tokens).
+ */
+
+export const RAGE_CLICKS = 3, RAGE_MS = 600, DEAD_MS = 1000, SCROLL_MILESTONES = [25, 50, 75, 100];
+const LABEL_MAX = 80, MESSAGE_MAX = 200;
+
+/** A node that must never be recorded: a password or payment field, or marked with data-inverse-redact. */
+export function sensitive(el) {
+  const attr = (n) => el.getAttribute?.(n);
+  return attr("data-inverse-redact") != null || (el.tagName === "INPUT" && attr("type")?.toLowerCase() === "password") || /^cc-/i.test(attr("autocomplete") ?? "");
+}
+
+/** True when the node or any ancestor is sensitive. */
+export function redacted(el) {
+  for (let n = el; n; n = n.parentElement) if (sensitive(n)) return true;
+  return false;
+}
+
+const ROLES = { A: "link", BUTTON: "button", SELECT: "combobox", TEXTAREA: "textbox", SUMMARY: "button", FORM: "form", OPTION: "option" };
+const INPUT_ROLES = { checkbox: "checkbox", radio: "radio", range: "slider", submit: "button", button: "button", reset: "button", search: "searchbox" };
+export const role = (el) => el.getAttribute?.("role") || (el.tagName === "INPUT" ? INPUT_ROLES[el.getAttribute("type")?.toLowerCase()] ?? "textbox" : ROLES[el.tagName]) || undefined;
+
+/** Text is only taken from elements whose text is a label (links, buttons, tabs), and never when they hold a field. */
+const TEXT_ROLES = new Set(["link", "button", "tab", "menuitem", "option", "checkbox", "radio", "switch"]);
+const clip = (s, n = LABEL_MAX) => (s = s?.replace(/\s+/g, " ").trim()) ? s.slice(0, n) : undefined;
+
+/** The accessible label: aria-label, aria-labelledby, a <label for>, title/alt, then text for label-like roles. Never a value. */
+export function label(el, doc = el.ownerDocument) {
+  const attr = (n) => el.getAttribute?.(n);
+  const by = attr("aria-labelledby")?.split(/\s+/).map((id) => doc?.getElementById(id)).filter((n) => n && !redacted(n));
+  const forLabel = el.id && doc?.querySelector?.(`label[for="${globalThis.CSS?.escape?.(el.id) ?? el.id}"]`);
+  return clip(attr("aria-label")) ?? clip(by?.map((n) => n.textContent).join(" ")) ?? (forLabel && !forLabel.querySelector("input,textarea,select,[contenteditable]") ? clip(forLabel.textContent) : undefined) ?? clip(attr("title") ?? attr("alt")) ??
+    (TEXT_ROLES.has(role(el)) && el.tagName !== "INPUT" && !el.querySelector?.("input,textarea,select,[contenteditable]") ? clip(el.textContent) : undefined);
+}
+
+/** A short selector: tag#id, tag[data-testid], or tag.first-class. */
+export function selector(el) {
+  const tag = el.tagName.toLowerCase(), id = el.getAttribute("id"), test = el.getAttribute("data-testid"), cls = el.getAttribute("class")?.trim().split(/\s+/)[0];
+  return (id ? `${tag}#${id}` : test ? `${tag}[data-testid="${test}"]` : cls ? `${tag}.${cls}` : tag).slice(0, 100);
+}
+
+export const target = (el) => {
+  const t = { label: label(el), role: role(el), selector: selector(el) };
+  for (const k in t) if (t[k] === undefined) delete t[k];
+  return t;
+};
+
+/** Rage clicks: `click(key, t)` is true once per burst, when the same target gets RAGE_CLICKS clicks within RAGE_MS. */
+export function rageDetector(count = RAGE_CLICKS, ms = RAGE_MS) {
+  let key, times = [], fired = false;
+  return (k, t) => {
+    if (k !== key) (key = k), (times = []), (fired = false);
+    times = [...times.filter((x) => t - x < ms), t];
+    if (times.length < count) return (fired = false);
+    return fired ? false : (fired = true);
+  };
+}
+
+/** A dead click: nothing in the page changed (DOM or path) between the click and DEAD_MS after it. */
+export const isDead = (clickAt, lastChangeAt, now) => lastChangeAt < clickAt && now - clickAt >= DEAD_MS;
+
+/** Scroll milestones newly reached at `percent`, given the ones already seen (mutated). */
+export function milestones(percent, seen) {
+  const hit = SCROLL_MILESTONES.filter((m) => percent >= m && !seen.has(m));
+  hit.forEach((m) => seen.add(m));
+  return hit;
+}
+
+const DEAD_ROLES = new Set(["link", "button", "tab", "menuitem"]);
+const CLICKABLE = "a,button,input,select,textarea,summary,label,[role],[onclick],[tabindex]";
+
+/**
+ * createRecorder({ emit }) → { start, stop, pause(on = true) }.
+ * `emit(event)` gets `{ v: 1, t, kind, path, target?, data? }`; the client adds `session`.
+ */
+export function createRecorder({ emit, win = globalThis.window }) {
+  const doc = win.document;
+  let paused = false, path = null, lastChange = 0, seen = new Set(), off = [];
+  const rage = rageDetector();
+  const send = (kind, extra) => !paused && emit({ v: 1, t: Date.now(), kind, path: win.location.pathname, ...extra });
+  const listen = (on, type, fn, opts) => (on.addEventListener(type, fn, opts), off.push(() => on.removeEventListener(type, fn, opts)));
+  const navigate = () => {
+    if (win.location.pathname === path) return;
+    path = win.location.pathname;
+    lastChange = Date.now();
+    seen = new Set();
+    send("navigate");
+  };
+  const onClick = (e) => {
+    const raw = e.target?.nodeType === 1 ? e.target : e.target?.parentElement;
+    if (!raw || redacted(raw)) return;
+    const hit = raw.closest(CLICKABLE), t = target(hit ?? raw), at = Date.now();
+    send("click", { target: t });
+    if (rage(t.selector + (t.label ?? ""), at)) send("rage_click", { target: t });
+    // Dead clicks only on links and buttons: a click on text or into a field changing nothing is normal.
+    if (hit && DEAD_ROLES.has(t.role)) setTimeout(() => isDead(at, lastChange, Date.now()) && send("dead_click", { target: t }), DEAD_MS);
+  };
+  const onSubmit = (e) => e.target && !redacted(e.target) && send("submit", { target: target(e.target) });
+  const onError = (e) => send("error", { data: { message: clip(e.message || "Script error", MESSAGE_MAX) } });
+  const onRejection = (e) => send("error", { data: { message: clip(String(e.reason?.message ?? e.reason), MESSAGE_MAX), unhandled: true } });
+  let queued = false;
+  const onScroll = () => {
+    if (queued) return;
+    queued = true;
+    win.requestAnimationFrame(() => {
+      queued = false;
+      const h = doc.documentElement.scrollHeight;
+      for (const m of milestones(h ? Math.round(((win.scrollY + win.innerHeight) / h) * 100) : 100, seen)) send("scroll_depth", { data: { percent: m } });
+    });
+  };
+  return {
+    start() {
+      if (off.length) return this;
+      const observer = new win.MutationObserver(() => (lastChange = Date.now()));
+      observer.observe(doc.documentElement, { subtree: true, childList: true, attributes: true, characterData: true });
+      off.push(() => observer.disconnect());
+      for (const method of ["pushState", "replaceState"]) {
+        const original = win.history[method];
+        win.history[method] = function (...args) {
+          const result = original.apply(this, args);
+          navigate();
+          return result;
+        };
+        off.push(() => (win.history[method] = original));
+      }
+      listen(win, "popstate", navigate);
+      listen(doc, "click", onClick, true);
+      listen(doc, "submit", onSubmit, true);
+      listen(win, "error", onError);
+      listen(win, "unhandledrejection", onRejection);
+      listen(win, "scroll", onScroll, { passive: true });
+      navigate();
+      return this;
+    },
+    stop() {
+      off.splice(0).forEach((fn) => fn());
+      path = null;
+    },
+    pause(on = true) {
+      paused = on;
+    },
+  };
+}

package/schema.d.ts

@@ -0,0 +1,51 @@
+export type EventKind = "navigate" | "click" | "input" | "submit" | "error" | "rage_click" | "dead_click" | "scroll_depth" | "say" | "reaction" | "task" | "custom";
+/** interface-event.v1: one thing a person did. Never carries a value typed into an input. */
+export type InterfaceEvent = {
+  v: 1;
+  /** ms since epoch */
+  t: number;
+  session: string;
+  kind: EventKind;
+  target?: { label?: string; role?: string; selector?: string };
+  /** Pathname only; query and hash are dropped. */
+  path?: string;
+  /** ≤500 chars, only on say, task and custom. */
+  text?: string;
+  /** ≤2KB; value-like keys are dropped. */
+  data?: Record<string, unknown>;
+  /** An alias, never a name. */
+  by?: string;
+};
+export type Outcome = "achieved" | "partial" | "abandoned" | "unknown";
+export type SignalKind = "question" | "friction" | "praise" | "request" | "command" | "feedback";
+export type Friction = { at: number; kind: string; text: string; evidence: number[]; quote?: string };
+/** intent.v1: what happened in a session, shaped for an agent. Every `by` and `alias` is "Speaker A"…, never a name. */
+export type Intent = {
+  schema: "intent.v1";
+  id: string;
+  session: string | null;
+  task?: string;
+  generatedAt: number;
+  outcome: Outcome;
+  goal?: string;
+  friction: Friction[];
+  signals: { kind: SignalKind; by: string; text: string; at: number }[];
+  timeline: { at: number; by: string; kind: string; text: string }[];
+  participants: { alias: string; events: number }[];
+  quality: { score: number; billable: boolean; reasons: string[] };
+  confidence: string;
+};
+
+export declare const EVENT_KINDS: EventKind[];
+export declare const TEXT_KINDS: EventKind[];
+export declare const OUTCOMES: Outcome[];
+export declare const SIGNAL_KINDS: SignalKind[];
+export declare const LIMITS: { text: number; data: number; label: number; role: number; selector: number; path: number; by: number; session: number };
+/** `[]` when the event is well-formed interface-event.v1, else what's wrong. */
+export declare function eventErrors(event: unknown): string[];
+/** The event as it may be stored: known fields only, capped, query/hash and value-like data dropped. Call after `eventErrors` passes. */
+export declare function redactEvent(event: InterfaceEvent): InterfaceEvent;
+/** `[]` when the package is well-formed intent.v1. */
+export declare function intentErrors(pkg: unknown): string[];
+export declare const eventJsonSchema: Record<string, unknown>;
+export declare const intentJsonSchema: Record<string, unknown>;

package/schema.js

@@ -0,0 +1,137 @@
+// The open formats: `interface-event.v1` (what a person did) and `intent.v1` (what an agent gets).
+// Plain validators with no dependencies, so the recorder, the Inverse API and anyone else check the same rules.
+
+export const EVENT_KINDS = ["navigate", "click", "input", "submit", "error", "rage_click", "dead_click", "scroll_depth", "say", "reaction", "task", "custom"];
+export const TEXT_KINDS = ["say", "task", "custom"]; // the only kinds that carry free text
+export const OUTCOMES = ["achieved", "partial", "abandoned", "unknown"];
+export const SIGNAL_KINDS = ["question", "friction", "praise", "request", "command", "feedback"];
+export const LIMITS = { text: 500, data: 2048, label: 120, role: 40, selector: 200, path: 2000, by: 40, session: 64 };
+
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const str = (v, max) => (typeof v === "string" ? v.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "").slice(0, max) : undefined);
+const num = (v) => typeof v === "number" && Number.isFinite(v);
+
+// Keys that could carry what someone typed, a secret or a contact detail. Dropped wherever they appear in `data`.
+const VALUE_KEY = /value|password|passwd|secret|token|card|cc-|cvc|cvv|ssn|email|phone|iban/i;
+function scrub(v, depth = 0) {
+  if (depth > 4) return undefined;
+  if (Array.isArray(v)) return v.slice(0, 50).map((x) => scrub(x, depth + 1)).filter((x) => x !== undefined);
+  if (isObj(v)) {
+    const out = {};
+    for (const [k, x] of Object.entries(v)) {
+      if (VALUE_KEY.test(k)) continue;
+      const s = scrub(x, depth + 1);
+      if (s !== undefined) out[k.slice(0, 64)] = s;
+    }
+    return out;
+  }
+  if (typeof v === "string") return str(v, LIMITS.text);
+  return typeof v === "number" || typeof v === "boolean" || v === null ? v : undefined;
+}
+
+/** `[]` when the event is a well-formed interface-event.v1, else what's wrong. Extra or oversize fields are `redactEvent`'s job. */
+export function eventErrors(e) {
+  if (!isObj(e)) return ["event must be an object"];
+  const errors = [];
+  if (e.v !== 1) errors.push("v must be 1");
+  if (!num(e.t)) errors.push("t must be a number (ms)");
+  if (typeof e.session !== "string" || !e.session || e.session.length > LIMITS.session) errors.push("session must be a string of 1-64 chars");
+  if (!EVENT_KINDS.includes(e.kind)) errors.push(`kind must be one of ${EVENT_KINDS.join(", ")}`);
+  if (e.target !== undefined && !isObj(e.target)) errors.push("target must be an object");
+  if (e.data !== undefined && !isObj(e.data)) errors.push("data must be an object");
+  for (const k of ["path", "text", "by"]) if (e[k] !== undefined && typeof e[k] !== "string") errors.push(`${k} must be a string`);
+  return errors;
+}
+
+/**
+ * The event as it may be stored: only known fields, capped, and never a value someone typed. `text` survives only on
+ * say/task/custom; a path loses its query and hash (they often carry emails and tokens); `data` loses value-like keys
+ * and is dropped above 2KB. Run it on both sides (recorder and server): redaction is defense in depth.
+ */
+export function redactEvent(e) {
+  const out = { v: 1, t: e.t, session: String(e.session).slice(0, LIMITS.session), kind: e.kind };
+  if (isObj(e.target)) {
+    const target = {};
+    for (const k of ["label", "role", "selector"]) {
+      const s = str(e.target[k], LIMITS[k]);
+      if (s) target[k] = s;
+    }
+    if (Object.keys(target).length) out.target = target;
+  }
+  const path = str(e.path, LIMITS.path)?.split(/[?#]/)[0];
+  if (path) out.path = path;
+  const text = TEXT_KINDS.includes(e.kind) ? str(e.text, LIMITS.text) : undefined;
+  if (text) out.text = text;
+  if (isObj(e.data)) {
+    const data = scrub(e.data);
+    if (Object.keys(data).length && JSON.stringify(data).length <= LIMITS.data) out.data = data;
+  }
+  const by = str(e.by, LIMITS.by);
+  if (by) out.by = by;
+  return out;
+}
+
+/** `[]` when `pkg` is a well-formed intent.v1. */
+export function intentErrors(pkg) {
+  if (!isObj(pkg)) return ["intent must be an object"];
+  const errors = [];
+  const need = (ok, message) => ok || errors.push(message);
+  need(pkg.schema === "intent.v1", 'schema must be "intent.v1"');
+  need(typeof pkg.id === "string" && pkg.id.startsWith("ipk_"), "id must start with ipk_");
+  need(pkg.session === null || typeof pkg.session === "string", "session must be a string or null");
+  need(num(pkg.generatedAt), "generatedAt must be a number");
+  need(OUTCOMES.includes(pkg.outcome), `outcome must be one of ${OUTCOMES.join(", ")}`);
+  need(Array.isArray(pkg.friction) && pkg.friction.every((f) => isObj(f) && num(f.at) && typeof f.kind === "string" && typeof f.text === "string" && Array.isArray(f.evidence)), "friction must be [{ at, kind, text, evidence }]");
+  need(Array.isArray(pkg.signals) && pkg.signals.every((s) => isObj(s) && SIGNAL_KINDS.includes(s.kind) && typeof s.text === "string" && num(s.at)), "signals must be [{ kind, by, text, at }]");
+  need(Array.isArray(pkg.timeline), "timeline must be an array");
+  need(Array.isArray(pkg.participants), "participants must be an array");
+  const q = pkg.quality;
+  need(isObj(q) && num(q.score) && q.score >= 0 && q.score <= 1 && typeof q.billable === "boolean" && Array.isArray(q.reasons), "quality must be { score 0..1, billable, reasons }");
+  need(typeof pkg.confidence === "string", "confidence must be a string");
+  return errors;
+}
+
+const S = (max) => ({ type: "string", maxLength: max });
+/** JSON Schema (2020-12) for interface-event.v1. */
+export const eventJsonSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://www.inverse.at/schemas/interface-event.v1.json",
+  title: "interface-event.v1",
+  type: "object",
+  required: ["v", "t", "session", "kind"],
+  additionalProperties: false,
+  properties: {
+    v: { const: 1 },
+    t: { type: "number", description: "ms since epoch" },
+    session: { type: "string", minLength: 1, maxLength: LIMITS.session },
+    kind: { enum: EVENT_KINDS },
+    target: { type: "object", additionalProperties: false, properties: { label: S(LIMITS.label), role: S(LIMITS.role), selector: S(LIMITS.selector) }, description: "Never a value from an input" },
+    path: { ...S(LIMITS.path), description: "Pathname only; query and hash are dropped" },
+    text: { ...S(LIMITS.text), description: "Only on say, task and custom" },
+    data: { type: "object", description: "≤2KB; value-like keys are dropped" },
+    by: { ...S(LIMITS.by), description: "An alias, never a name" },
+  },
+};
+/** JSON Schema (2020-12) for intent.v1. */
+export const intentJsonSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://www.inverse.at/schemas/intent.v1.json",
+  title: "intent.v1",
+  type: "object",
+  required: ["schema", "id", "session", "generatedAt", "outcome", "friction", "signals", "timeline", "participants", "quality", "confidence"],
+  properties: {
+    schema: { const: "intent.v1" },
+    id: { type: "string", pattern: "^ipk_" },
+    session: { type: ["string", "null"] },
+    task: { type: "string" },
+    goal: { type: "string" },
+    generatedAt: { type: "number" },
+    outcome: { enum: OUTCOMES },
+    friction: { type: "array", items: { type: "object", required: ["at", "kind", "text", "evidence"], properties: { at: { type: "number" }, kind: { type: "string" }, text: { type: "string" }, evidence: { type: "array", items: { type: "integer" } }, quote: { type: "string" } } } },
+    signals: { type: "array", items: { type: "object", required: ["kind", "by", "text", "at"], properties: { kind: { enum: SIGNAL_KINDS }, by: { type: "string" }, text: { type: "string" }, at: { type: "number" } } } },
+    timeline: { type: "array", items: { type: "object", required: ["at", "by", "kind", "text"], properties: { at: { type: "number" }, by: { type: "string" }, kind: { type: "string" }, text: { type: "string" } } } },
+    participants: { type: "array", items: { type: "object", required: ["alias", "events"], properties: { alias: { type: "string" }, events: { type: "integer" } } } },
+    quality: { type: "object", required: ["score", "billable", "reasons"], properties: { score: { type: "number", minimum: 0, maximum: 1 }, billable: { type: "boolean" }, reasons: { type: "array", items: { type: "string" } } } },
+    confidence: { type: "string" },
+  },
+};