@autono/pinbox-toolbar 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @autono/pinbox-toolbar
+
+The embeddable feedback toolbar: a vanilla web component (Shadow DOM isolation, zero runtime deps).
+
+Two build artifacts from one `src/`, both emitted by **tsdown** — there is no Vite build here. `tsdown.config.ts` exports an **array of two configs**, not one config with two formats: with `fixedExtension: false` an iife output would also be named `.js` and collide with the ESM entries, and a multi-entry iife build cannot share chunks.
+
+- `dist/toolbar.iife.js` — script-tag embed for any stack; served from a **versioned** CDN path (never latest-only). The entry point is `Pinbox.init({ endpoint })`, same as every other install path.
+- ESM build for bundlers — one entry per `exports` subpath.
+
+```html
+<script src="https://cdn.example.com/@autono/pinbox-toolbar@0.0.0/toolbar.iife.js"></script>
+<script>
+  Pinbox.init({ endpoint: "http://127.0.0.1:4319" });
+</script>
+```
+
+**The iife entry is `src/iife.ts`, not `src/index.ts`, and that is load-bearing.** An iife bundle assigns the entry module's *namespace* to `globalName`, so an entry exporting a `Pinbox` object yields `Pinbox.Pinbox.init(…)` on the host page. `src/iife.ts` re-exports the intended surface flat and exists for this bundle alone — it is absent from the ESM entry list and from `exports`, whose shapes are separate published contracts. `src/build.test.ts` evaluates the built bundle in a happy-dom realm and asserts both that `Pinbox.init` is callable and that `Pinbox.Pinbox` does not exist, because after the first publish this is a breaking change to a public API.
+
+Chunking is part of the published contract: because the wrappers share `src/index.ts`, rolldown hoists the custom-element registration into a shared chunk and `dist/index.js` becomes a re-export shim. `sideEffects` must therefore stay the glob `./dist/*.js` — naming only the shim would let bundlers tree-shake the dev plugins' bare `import "@autono/pinbox-toolbar"` away, silently. `src/build.test.ts` bundles that bare import with Vite and fails if the shape changes.
+
+The `./vite` and `./next` subpath exports are dev-server *plugins for the consumer's* bundler. Vite is therefore an **optional peerDependency** with a deliberately wide range — it is their Vite, not ours, and pinning it would break installs. Pinbox itself has no Vite dependency.
+
+Subpath exports (split into a separate package only if one ever needs independent versioning):
+
+- `./react`, `./vue`, `./svelte` — thin wrappers; frameworks are **optional peerDependencies** and stay external, so nothing framework-shaped is bundled into `dist/index.js`.
+- `./vite`, `./next` — dev-server plugins that auto-inject the toolbar in dev and ensure the hub is running. Dev-only; excluded from prod builds.
+
+`./next` is a **separate plugin, not a re-export of `./vite`**, and Vite's own docs are the reason: `transformIndexHtml` "won't be called if you are using a framework that has custom handling of entry files (for example SvelteKit)." Next has no equivalent public hook for injecting a script tag into every dev page from `next.config`, so `withPinbox()` does only the half it can do honestly — keeping the hub daemon alive during `next dev`. The client-side mount is spelled out as a TODO in `src/plugins/next.ts` rather than faked.
+
+Both plugin files are **guest-rule code** (`AGENTS.md`): they are evaluated inside the consumer's toolchain, and both the `vite` and `next` bins carry a `#!/usr/bin/env node` shebang, so they land on Node even when launched with Bun. They use the Node/Bun shared subset (`node:*`) deliberately — do not "fix" them.
+
+## Realtime, offline, attachments
+
+- **Realtime** — `src/transport.ts` speaks the frozen WS protocol (`hello → catch-up → events`) against `GET /ws`, authenticating at upgrade only via the `pinbox.token.<token>` subprotocol, because a browser cannot set headers on an upgrade. It reconnects with jittered 1s→30s backoff and replays from its persisted cursor, so a dropped socket costs no events. Either side of an excluding protocol window closes `4400` with a clear upgrade message; a bad token closes `4401`.
+- **Offline mirror** — `src/transport/mirror.ts` keeps the cursor, the last-known pin list, and an outbox of pins drawn while offline in `localStorage`, namespaced per endpoint. Reconnect reconciles on one rule: **the hub wins on status, the client wins on new pins**. Storage writes never throw upward — private mode or a full quota degrades the mirror, never the toolbar.
+- **Attachments** — screenshots are cropped and webp-encoded **in the browser** (`createImageBitmap` → `OffscreenCanvas` → `convertToBlob`), POSTed to `/attachments`, and the pin then carries the returned **path — never bytes**. Capture is best-effort by design: with no `html2canvas`-class dependency allowed, `src/screenshot.ts` resolves `null` wherever the environment cannot capture, and the pin ships with structured capture alone.
+
+The toolbar's copies of the `ws-protocol.ts` wire constants are mirrored, not imported (core is a **type-only** dependency here — that is what keeps the runtime zero-dependency, and fallow's `allowTypeOnly` enforces it). `e2e/toolbar.test.ts` drives this transport against a real `pinbox serve`, so drift between the two copies fails the build.
+
+`demo/` is the manual harness: `bun run demo` starts a hub plus a fixture page and prints the URL. Its README carries the checklist the automated tests cannot cover (real canvas pixels, a real browser).
+
+**This package deliberately declares no `engines` field, and must not gain one.** It is the sole exception to the repo-wide `"engines": { "bun": ">=1.3.0" }` rule. The toolbar is browser code: Bun builds it here, but consumers install it into their own toolchain — a Vite/React app on npm under Node, most often. Declaring a Bun engine would make those installs warn, and refuse outright under `engine-strict`, for a package that never executes on a server runtime at all.
+
+Key behaviors (see spec): targeting adapters (`dom` hit-testing | `anchor` attributes for sandboxed-iframe hosts), move pins with before/after rects, live status badges over WS with the accept/reopen verification step, localStorage offline mirror with reconnect reconciliation, copy-as-markdown fallback, `Pinbox.init({ getToken })` auth passthrough — the toolbar never renders a login.

package/dist/index-ZR3JBQu-.d.ts

@@ -0,0 +1,206 @@
+import { Attachment, Pin, PinInput, ThreadMessage } from "@autono/pinbox-core/schema";
+//#region src/capture.d.ts
+/**
+ * The full browser shapes. `Pin["target"]`/`Pin["env"]` are optional at v1 (core
+ * schema.ts §"widened in place") because a terminal `pinbox pin` has no browser to
+ * measure. A capture is the opposite case: it always has a window, so it always
+ * produces every field. Narrowing here is what keeps every capture-side consumer
+ * free of optional chaining — the widening only reaches code that reads pins back.
+ */
+type MaybeTarget = NonNullable<Pin["target"]>;
+type MaybeEnv = NonNullable<Pin["env"]>;
+/** The named keys become present-and-defined; everything else keeps its optionality. */
+type Concrete<T, K extends keyof T> = T & { [P in K]-?: NonNullable<T[P]>; };
+type BrowserTarget = Concrete<MaybeTarget, "url" | "selector" | "tag" | "rect" | "fixed">;
+type BrowserEnv = Concrete<MaybeEnv, "viewport" | "browser" | "os" | "colorScheme">;
+/** What a targeting adapter produces for a chosen element: the pin schema shapes. */
+interface CaptureResult {
+  target: BrowserTarget;
+  env: BrowserEnv;
+}
+//#endregion
+//#region src/state.d.ts
+type UiStatus = "open" | "waiting" | "replied" | "resolved" | "verify";
+interface Draft {
+  target: CaptureResult;
+  placedAt: {
+    x: number;
+    y: number;
+  };
+}
+interface ToolbarState {
+  pins: Pin[];
+  threads: Map<string, ThreadMessage[]>;
+  draft: Draft | null;
+  mode: "idle" | "placing";
+  activePinId: string | null;
+  inboxOpen: boolean;
+  connection: "connecting" | "live" | "offline" | "incompatible";
+  /** Outbox-queued pin ids (offline creates) — flagged "queued" in the UI until the flush. */
+  queuedIds: ReadonlySet<string>;
+}
+interface Store {
+  get(): ToolbarState;
+  /** Render subscribes once; every update() notifies each subscriber exactly once. */
+  subscribe(fn: (state: ToolbarState) => void): () => void;
+  update(patch: Partial<ToolbarState>): void;
+  /** Placement click: sets the draft and leaves placing mode. Client-only — no hub call. */
+  place(draft: Draft): void;
+  /** Abandoned draft: cleared without touching pins; nothing ever reached the hub. */
+  discardDraft(): void;
+  /** First comment submitted: the hub-created Pin replaces the draft and becomes active. */
+  commitDraft(pin: Pin): void;
+}
+declare function createStore(): Store;
+/** Replace-by-id upsert; new pins append. */
+declare function upsertPin(store: Store, pin: Pin): void;
+/** Append to the pin's thread, deduping by message id (REST echo vs WS event). */
+declare function appendThreadMessage(store: Store, message: ThreadMessage): void;
+/**
+ * Wire events mutate the store: pin.created upserts;
+ * pin.resolved / pin.verified / pin.linked replace the payload Pin;
+ * thread.message appends — payloads are the full post-mutation objects.
+ */
+declare function applyHubEvent(store: Store, event: {
+  seq: number;
+  eventType: string;
+  at: string;
+  payload: unknown;
+}): void;
+/**
+ * Wire-status → UI-status mapping:
+ * resolved + no verification ⇒ "verify" (accept/reopen prompt);
+ * resolved + verification ⇒ "resolved";
+ * open + empty thread or last message human ⇒ "waiting";
+ * open + last message agent|mirror ⇒ "replied".
+ * The prototype's WORKING/APPLIED chips need an event vocabulary the hub does not emit — excluded here.
+ */
+declare function deriveUiStatus(pin: Pin, thread: ThreadMessage[]): UiStatus;
+//#endregion
+//#region src/element.d.ts
+declare const BaseElement: typeof HTMLElement;
+declare class PinboxToolbarElement extends BaseElement {
+  #private;
+  static readonly tagName = "pinbox-toolbar";
+  readonly store: Store;
+  /** Card → transport seam (wired by #startTransport once a config exists). */
+  readonly actions: {
+    send?: (pinId: string | "draft", text: string) => void;
+    verify?: (pinId: string, outcome: "accepted" | "reopened") => void;
+    resolve?: (pinId: string) => void;
+  };
+  /** Programmatic path (Pinbox.init). The snippet path reads hub/token attributes. */
+  configure(config: PinboxConfig): void;
+  get config(): PinboxConfig | null;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+}
+//#endregion
+//#region src/transport/mirror.d.ts
+interface StorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+//#endregion
+//#region src/transport/rest.d.ts
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+declare class HubError extends Error {
+  readonly code: string;
+  readonly status: number;
+  readonly hint: string | undefined;
+  constructor(code: string, message: string, status: number, hint?: string);
+}
+//#endregion
+//#region src/transport.d.ts
+/** The browser WebSocket surface the transport needs — injectable for tests. */
+interface WebSocketLike {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: (() => void) | null;
+  onmessage: ((ev: {
+    data: string;
+  }) => void) | null;
+  onclose: ((ev: {
+    code: number;
+  }) => void) | null;
+  onerror: (() => void) | null;
+}
+interface SchedulerLike {
+  setTimeout(fn: () => void, ms: number): unknown;
+  clearTimeout(id: unknown): void;
+}
+interface HubEvent {
+  seq: number;
+  eventType: string;
+  at: string;
+  payload: unknown;
+}
+type ConnectionState = "connecting" | "live" | "offline" | "incompatible";
+interface TransportOptions {
+  endpoint: string;
+  token: string;
+  /** Default localStorage; injectable for tests. */
+  storage?: StorageLike;
+  /** Injectable for tests. */
+  webSocket?: (url: string, protocols: string[]) => WebSocketLike;
+  onEvent(e: HubEvent): void;
+  onConnection(state: ConnectionState): void;
+  /** Reconciled pin lists: fresh `listPins()` after each reconnect (hub wins on status). */
+  onPins?(pins: Pin[]): void;
+  /** Queued outbox localIds whenever the set changes — the UI flags them as pending sync. */
+  onOutbox?(localIds: string[]): void;
+  /** Test seam; default global fetch. */
+  fetchFn?: FetchLike;
+  /** Test seam standing in for fake timers; default global setTimeout/clearTimeout. */
+  scheduler?: SchedulerLike;
+}
+declare class HubTransport {
+  #private;
+  /** Stable per install, persisted (`pinbox:<endpoint>:consumer`). */
+  readonly consumerId: string;
+  constructor(opts: TransportOptions);
+  /** Last-known pin list — the offline read-only render seed. */
+  mirrorPins(): Pin[];
+  /** Optimistic pins for the queued outbox — offline reloads render + flag them. */
+  outboxPins(): Pin[];
+  /** Last-known thread for a pin — the offline read-only thread render seed.
+   * Empty for a pin whose thread was never fetched while connected. */
+  mirrorThread(pinId: string): ThreadMessage[];
+  /** hello → buffer live frames → apply catch-up → drain buffer. */
+  connect(): void;
+  close(): void;
+  listPins(): Promise<Pin[]>;
+  /** Offline ⇒ queued in the outbox, optimistic local pin (client wins on new pins). */
+  createPin(input: PinInput): Promise<Pin>;
+  /** Mirrored on every success, served from the mirror when the hub is unreachable —
+   * an offline reload renders read-only threads instead of empty ones. Any other
+   * hub error (auth, not-found) surfaces: the mirror is a fallback, not a mask. */
+  getThread(pinId: string): Promise<ThreadMessage[]>;
+  reply(pinId: string, text: string, attachments?: Attachment[]): Promise<ThreadMessage>;
+  resolve(pinId: string, note?: string): Promise<Pin>;
+  verify(pinId: string, outcome: "accepted" | "reopened"): Promise<Pin>;
+}
+//#endregion
+//#region src/index.d.ts
+interface PinboxConfig {
+  /** Hub base URL. */
+  endpoint: string;
+  /** Local dev: injected by the dev plugin. */
+  token?: string;
+  /** Cloud: the host app supplies (spec: auth passthrough). */
+  getToken?: () => Promise<string>;
+  /** Default "dom"; "anchor" for sandboxed cross-origin iframe hosts (Task 7). */
+  targeting?: "dom" | "anchor";
+  /** Anchor mode attribute, default "data-pb-anchor". */
+  anchorAttribute?: string;
+  /** Reserved; the realtime topic is fixed server-side. */
+  project?: string;
+}
+/** Register <pinbox-toolbar>; no-op outside a browser or when already defined. */
+declare function defineToolbarElement(): void;
+declare const Pinbox: {
+  init(config: PinboxConfig): PinboxToolbarElement;
+};
+//#endregion
+export { applyHubEvent as _, HubEvent as a, upsertPin as b, WebSocketLike as c, PinboxToolbarElement as d, Draft as f, appendThreadMessage as g, UiStatus as h, ConnectionState as i, HubError as l, ToolbarState as m, PinboxConfig as n, HubTransport as o, Store as p, defineToolbarElement as r, TransportOptions as s, Pinbox as t, StorageLike as u, createStore as v, CaptureResult as x, deriveUiStatus as y };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { _ as applyHubEvent, a as HubEvent, b as upsertPin, c as WebSocketLike, d as PinboxToolbarElement, f as Draft, g as appendThreadMessage, h as UiStatus, i as ConnectionState, l as HubError, m as ToolbarState, n as PinboxConfig, o as HubTransport, p as Store, r as defineToolbarElement, s as TransportOptions, t as Pinbox, u as StorageLike, v as createStore, x as CaptureResult, y as deriveUiStatus } from "./index-ZR3JBQu-.js";
+export { type CaptureResult, type ConnectionState, type Draft, HubError, type HubEvent, HubTransport, Pinbox, PinboxConfig, PinboxToolbarElement, type StorageLike, type Store, type ToolbarState, type TransportOptions, type UiStatus, type WebSocketLike, appendThreadMessage, applyHubEvent, createStore, defineToolbarElement, deriveUiStatus, upsertPin };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as HubError, c as createStore, i as HubTransport, l as deriveUiStatus, n as defineToolbarElement, o as appendThreadMessage, r as PinboxToolbarElement, s as applyHubEvent, t as Pinbox, u as upsertPin } from "./src-BoLg81_j.js";
+export { HubError, HubTransport, Pinbox, PinboxToolbarElement, appendThreadMessage, applyHubEvent, createStore, defineToolbarElement, deriveUiStatus, upsertPin };

package/dist/options-CNqXqkp9.d.ts

@@ -0,0 +1,14 @@
+//#region src/plugins/options.d.ts
+/** User-facing plugin options. Every field is optional. */
+interface PinboxPluginOptions {
+  /** Explicit hub base URL. When set, `.pinbox/server.json` discovery is skipped entirely. */
+  hub?: string;
+  /** Directory containing `.pinbox/server.json`. Defaults to `process.cwd()`. */
+  projectRoot?: string;
+  /** Spawn `pinbox serve` when no healthy hub is found. Defaults to true. */
+  spawnDaemon?: boolean;
+  /** Hard off switch: the plugin becomes fully inert. Defaults to false. */
+  disabled?: boolean;
+}
+//#endregion
+export { PinboxPluginOptions as t };

package/dist/options-DSrJgbJh.js

@@ -0,0 +1,169 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+//#region src/plugins/daemon.ts
+const DEFAULT_PROBE_TIMEOUT_MS = 750;
+const SPAWN_WAIT_MS = 1e4;
+const POLL_INTERVAL_MS = 250;
+function warn(message) {
+	console.warn(`[pinbox] ${message}`);
+}
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+function hubUrlForPort(port) {
+	return `http://127.0.0.1:${port}`;
+}
+/**
+* Read the port the hub daemon advertises in `<projectRoot>/.pinbox/server.json`.
+*
+* That file holds the PORT ONLY — `{ "port": number }`. The auth token and pid live in the XDG
+* state dir at 0600 and are deliberately never written into the repo, so there is nothing secret
+* to read here. Returns undefined when the file is missing, unreadable, or malformed.
+*/
+function readServerPort(projectRoot) {
+	try {
+		const raw = readFileSync(join(projectRoot, ".pinbox", "server.json"), "utf8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		const port = parsed["port"];
+		if (typeof port !== "number" || !Number.isInteger(port) || port <= 0 || port > 65535) return;
+		return port;
+	} catch {
+		return;
+	}
+}
+/**
+* Read the hub bearer token from the XDG state dir — the secret half `readServerPort` skips.
+*
+* XDG PARITY with packages/cli/src/paths.ts, which computes the state dir as
+* `${XDG_STATE_HOME ?? ~/.local/state}/pinbox/<sha256(physical project path).slice(0, 12)>`.
+* The CLI hashes with Bun.CryptoHasher over `pwd -P`; this guest-rule file must reach the same
+* 12-hex id via the node: shared subset — `node:crypto` createHash over `realpathSync`.
+* daemon.test.ts asserts the parity by building its fixture the CLI way.
+*
+* Returns undefined on ANY failure (no env, no file, garbled JSON, non-string token) — a missing
+* token degrades the toolbar, it must never break the consumer's dev server.
+*/
+function readHubToken(projectRoot) {
+	try {
+		let physical;
+		try {
+			physical = realpathSync(projectRoot);
+		} catch {
+			physical = projectRoot;
+		}
+		const id = createHash("sha256").update(physical).digest("hex").slice(0, 12);
+		const xdg = process.env["XDG_STATE_HOME"];
+		const home = process.env["HOME"];
+		const stateHome = xdg !== void 0 && xdg !== "" ? xdg : home !== void 0 && home !== "" ? join(home, ".local", "state") : void 0;
+		if (stateHome === void 0) return void 0;
+		const raw = readFileSync(join(stateHome, "pinbox", id, "hub.json"), "utf8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		const token = parsed["token"];
+		return typeof token === "string" && token.length > 0 ? token : void 0;
+	} catch {
+		return;
+	}
+}
+/** `GET <url>/health`. Resolves false on any error, non-2xx, or timeout. Never throws. */
+async function probeHub(url, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS) {
+	try {
+		return (await fetch(`${url}/health`, { signal: AbortSignal.timeout(timeoutMs) })).ok;
+	} catch {
+		return false;
+	}
+}
+/** Explicit hub wins; otherwise re-read the port file (the daemon may have just written it). */
+function currentHubUrl(options) {
+	if (options.hub !== void 0) return options.hub;
+	const port = readServerPort(options.projectRoot);
+	return port === void 0 ? void 0 : hubUrlForPort(port);
+}
+/**
+* Spawn `pinbox serve` DETACHED, unref'd, with stdio ignored, so it outlives this dev server.
+*
+* The daemon is ADOPTED, never OWNED: no teardown is registered anywhere in this module. Editing
+* `vite.config.ts` restarts the dev server in-process, and the OLD server's close handlers fire
+* AFTER the new `configureServer` — any teardown we registered would kill the hub we just
+* started. Deduping is done purely by the out-of-process health probe; the daemon owns its own
+* idle-exit lifecycle.
+*/
+function spawnDaemon(projectRoot) {
+	try {
+		const child = spawn("pinbox", ["serve"], {
+			cwd: projectRoot,
+			detached: true,
+			stdio: "ignore"
+		});
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Resolve a hub URL, adopting a running daemon when possible and spawning one otherwise.
+*
+* Never throws and never registers teardown: a dead hub degrades the toolbar, it must never break
+* the consumer's dev server. On failure it logs one concise warning and returns undefined.
+*/
+async function ensureHub(options) {
+	if (options.disabled) return void 0;
+	try {
+		const existing = currentHubUrl(options);
+		if (existing !== void 0 && await probeHub(existing)) return {
+			url: existing,
+			adopted: true
+		};
+		if (!options.spawnDaemon) {
+			warn("no running hub found and spawnDaemon is disabled — toolbar not injected.");
+			return;
+		}
+		if (!spawnDaemon(options.projectRoot)) {
+			warn("could not start `pinbox serve` — toolbar not injected.");
+			return;
+		}
+		const deadline = Date.now() + SPAWN_WAIT_MS;
+		while (Date.now() < deadline) {
+			await sleep(POLL_INTERVAL_MS);
+			const url = currentHubUrl(options);
+			if (url !== void 0 && await probeHub(url)) return {
+				url,
+				adopted: false
+			};
+		}
+		warn(`hub did not become healthy within ${SPAWN_WAIT_MS / 1e3}s — toolbar not injected.`);
+		return;
+	} catch {
+		warn("hub discovery failed — toolbar not injected.");
+		return;
+	}
+}
+//#endregion
+//#region src/plugins/options.ts
+/** Virtual module the injected inline script imports. */
+const VIRTUAL_ID = "virtual:pinbox-toolbar";
+/** Rollup/Vite convention: a leading NUL marks the id as owned by this plugin. */
+const RESOLVED_VIRTUAL_ID = "\0virtual:pinbox-toolbar";
+/** Strip trailing slashes so callers can append `/health` unconditionally. */
+function normalizeHub(hub) {
+	const trimmed = hub.trim().replace(/\/+$/, "");
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+/** Apply defaults. Never throws; unknown/empty values fall back to the documented default. */
+function resolveOptions(options) {
+	return {
+		hub: options?.hub === void 0 ? void 0 : normalizeHub(options.hub),
+		projectRoot: options?.projectRoot ?? process.cwd(),
+		spawnDaemon: options?.spawnDaemon ?? true,
+		disabled: options?.disabled ?? false
+	};
+}
+//#endregion
+export { readHubToken as a, ensureHub as i, VIRTUAL_ID as n, resolveOptions as r, RESOLVED_VIRTUAL_ID as t };

package/dist/plugins/next.d.ts

@@ -0,0 +1,31 @@
+import { t as PinboxPluginOptions } from "../options-CNqXqkp9.js";
+//#region src/plugins/next.d.ts
+/**
+ * Structural stand-in for Next's `NextConfig`.
+ *
+ * We deliberately do NOT depend on `next` — it is an enormous dependency to pull in just for a
+ * type, and pinning it would constrain which Next versions consumers may use. An index signature
+ * is enough: we return the caller's object unchanged, so its own type `T` is what survives.
+ */
+interface NextConfigLike {
+  [key: string]: unknown;
+}
+/**
+ * Wrap a `next.config` object so the pinbox hub is running during development.
+ *
+ *     // next.config.ts
+ *     import { withPinbox } from "@autono/pinbox-toolbar/next";
+ *     export default withPinbox({ reactStrictMode: true });
+ *
+ * Returns the SAME config value it was given (never a clone), so it composes with other `withX`
+ * wrappers in any order. The only effect is the side effect below.
+ *
+ * The hub check is fire-and-forget: `next.config` is evaluated synchronously here and `ensureHub`
+ * can take up to ~10s when it has to spawn the daemon. Blocking on it would stall every `next dev`
+ * start, and `ensureHub` never throws or rejects, so nothing can escape into the consumer's build.
+ * A future phase may instead export an async config function so the resolved hub URL can be
+ * threaded into `env` at config time — see the TODO.
+ */
+declare function withPinbox<T extends NextConfigLike>(config?: T, options?: PinboxPluginOptions): T;
+//#endregion
+export { NextConfigLike, withPinbox };

package/dist/plugins/next.js

@@ -0,0 +1,31 @@
+import { i as ensureHub, r as resolveOptions } from "../options-DSrJgbJh.js";
+//#region src/plugins/next.ts
+/** `next dev` / `next build` set NODE_ENV themselves; bracket access is required by house tsconfig. */
+function isDevelopment() {
+	return process.env["NODE_ENV"] !== "production";
+}
+/**
+* Wrap a `next.config` object so the pinbox hub is running during development.
+*
+*     // next.config.ts
+*     import { withPinbox } from "@autono/pinbox-toolbar/next";
+*     export default withPinbox({ reactStrictMode: true });
+*
+* Returns the SAME config value it was given (never a clone), so it composes with other `withX`
+* wrappers in any order. The only effect is the side effect below.
+*
+* The hub check is fire-and-forget: `next.config` is evaluated synchronously here and `ensureHub`
+* can take up to ~10s when it has to spawn the daemon. Blocking on it would stall every `next dev`
+* start, and `ensureHub` never throws or rejects, so nothing can escape into the consumer's build.
+* A future phase may instead export an async config function so the resolved hub URL can be
+* threaded into `env` at config time — see the TODO.
+*/
+function withPinbox(config, options) {
+	const resolved = resolveOptions(options);
+	const nextConfig = config ?? {};
+	if (resolved.disabled || !isDevelopment()) return nextConfig;
+	ensureHub(resolved);
+	return nextConfig;
+}
+//#endregion
+export { withPinbox };

package/dist/plugins/vite.d.ts

@@ -0,0 +1,11 @@
+import { t as PinboxPluginOptions } from "../options-CNqXqkp9.js";
+import { Plugin } from "vite";
+//#region src/plugins/vite.d.ts
+/**
+ * Inject the pinbox toolbar into the dev page and make sure the hub daemon is running.
+ *
+ * Dev only: `apply: "serve"` is the sole production-exclusion mechanism (see below).
+ */
+declare function pinbox(options?: PinboxPluginOptions): Plugin;
+//#endregion
+export { pinbox as default, pinbox };

package/dist/plugins/vite.js

@@ -0,0 +1,98 @@
+import { a as readHubToken, i as ensureHub, n as VIRTUAL_ID, r as resolveOptions, t as RESOLVED_VIRTUAL_ID } from "../options-DSrJgbJh.js";
+//#region src/plugins/snippet.ts
+/**
+* Build the module source injected into the dev page.
+*
+* The returned code imports the toolbar element for its side effect (custom element registration),
+* then appends a single `<pinbox-toolbar>` to `document.body` pointed at `hubUrl`. Re-running it
+* after an HMR update is a no-op: the existing element is reused and only its `hub`/`token`
+* attributes are refreshed (a token that disappeared is removed, never left stale).
+*
+* The bare `import "@autono/pinbox-toolbar"` below is a SIDE-EFFECT import — it registers the
+* custom element and binds no name. That is why package.json declares
+* `"sideEffects": ["./dist/*.js"]` rather than `false`: under a blanket `false`, a bundler is
+* entitled to drop this import entirely and `<pinbox-toolbar>` would never be defined, so the
+* toolbar would silently never mount with nothing logged. Do not "simplify" that field back.
+*
+* The glob — not the single `./dist/index.js` it started as — is load-bearing too. Which emitted
+* FILE carries the top-level `defineToolbarElement()` call is decided by tsdown's chunking: once
+* the wrapper entries (react/vue/svelte) joined the ESM build they began sharing code with
+* src/index.ts, so rolldown hoisted that module body into a hash-named chunk and left
+* `dist/index.js` a re-export shim. An allowlist naming only index.js then covered nothing, and
+* this import was dropped for real. `src/build.test.ts` bundles this exact import with Vite and
+* asserts `customElements.define` survives, because statting dist/ cannot see that class of break.
+*/
+function buildBootstrap(hubUrl, token) {
+	const hub = JSON.stringify(hubUrl);
+	return `// pinbox dev toolbar — injected by @autono/pinbox-toolbar (dev only)
+import "@autono/pinbox-toolbar";
+
+const TAG = ${JSON.stringify("pinbox-toolbar")};
+const HUB = ${hub};
+const TOKEN = ${token === void 0 ? "null" : JSON.stringify(token)};
+
+function mount() {
+  let el = document.querySelector(TAG);
+  if (!el) {
+    el = document.createElement(TAG);
+    document.body.appendChild(el);
+  }
+  el.setAttribute("hub", HUB);
+  if (TOKEN === null) el.removeAttribute("token");
+  else el.setAttribute("token", TOKEN);
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", mount, { once: true });
+} else {
+  mount();
+}
+`;
+}
+//#endregion
+//#region src/plugins/vite.ts
+const PLUGIN_NAME = "pinbox";
+/**
+* Inject the pinbox toolbar into the dev page and make sure the hub daemon is running.
+*
+* Dev only: `apply: "serve"` is the sole production-exclusion mechanism (see below).
+*/
+function pinbox(options) {
+	const resolved = resolveOptions(options);
+	if (resolved.disabled) return { name: PLUGIN_NAME };
+	let hubPromise;
+	function hub() {
+		hubPromise ??= ensureHub(resolved);
+		return hubPromise;
+	}
+	return {
+		name: PLUGIN_NAME,
+		apply: "serve",
+		async configureServer() {
+			await hub();
+		},
+		resolveId(id) {
+			if (id === "virtual:pinbox-toolbar") return RESOLVED_VIRTUAL_ID;
+			return null;
+		},
+		async load(id) {
+			if (id !== "\0virtual:pinbox-toolbar") return null;
+			const status = await hub();
+			if (status === void 0) return "// pinbox: hub unavailable, toolbar not mounted.\nexport {};\n";
+			return buildBootstrap(status.url, readHubToken(resolved.projectRoot));
+		},
+		transformIndexHtml: {
+			order: "pre",
+			handler() {
+				return [{
+					tag: "script",
+					attrs: { type: "module" },
+					children: `import ${JSON.stringify(VIRTUAL_ID)};`,
+					injectTo: "body"
+				}];
+			}
+		}
+	};
+}
+//#endregion
+export { pinbox as default, pinbox };

package/dist/react.d.ts

@@ -0,0 +1,11 @@
+import { n as PinboxConfig } from "./index-ZR3JBQu-.js";
+import { ReactElement } from "react";
+//#region src/react.d.ts
+/**
+ * `<PinboxToolbar endpoint="http://127.0.0.1:4242" />` — forwards the config ONCE on
+ * mount and removes the element on unmount. The element does not support live
+ * reconfiguration; remount with a `key` to change endpoints.
+ */
+declare function PinboxToolbar(props: PinboxConfig): ReactElement;
+//#endregion
+export { PinboxToolbar };

package/dist/react.js

@@ -0,0 +1,28 @@
+import { n as defineToolbarElement, r as PinboxToolbarElement } from "./src-BoLg81_j.js";
+import { createElement, useEffect, useRef } from "react";
+//#region src/react.ts
+/**
+* `<PinboxToolbar endpoint="http://127.0.0.1:4242" />` — forwards the config ONCE on
+* mount and removes the element on unmount. The element does not support live
+* reconfiguration; remount with a `key` to change endpoints.
+*/
+function PinboxToolbar(props) {
+	const host = useRef(null);
+	const config = useRef(props);
+	config.current = props;
+	useEffect(() => {
+		defineToolbarElement();
+		const el = document.createElement(PinboxToolbarElement.tagName);
+		el.configure(config.current);
+		host.current?.appendChild(el);
+		return () => {
+			el.remove();
+		};
+	}, []);
+	return createElement("div", {
+		ref: host,
+		style: { display: "contents" }
+	});
+}
+//#endregion
+export { PinboxToolbar };