@pragma-sh/scratchpad 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @pragma-sh/scratchpad
+
+Interactive components for Pragma scratchpads. Part of [Pragma](https://github.com/pragma-sh/pragma) — a desktop workspace for
+running persistent, worktree-scoped coding agents.
+
+The browser-safe API bundled into an agent-authored MDX scratchpad: ask the user
+a question, review a diff, show live agent progress, and prompt the attached
+agent back. Re-exports `@pragma-sh/sdk`.
+
+```mdx
+import { AskQuestion } from "@pragma-sh/scratchpad/ui";
+
+<AskQuestion question="Which auth strategy?" options={[{ label: "JWT" }]} />
+```
+
+Components render against the desktop's theme variables, so they follow whatever
+theme the user has set. Presentational primitives live under
+`@pragma-sh/scratchpad/ui/primitives`.
+
+Docs: <https://pragma-app.sh/docs/user-guide/scratchpads>
+
+## License
+
+AGPL-3.0-only. See [LICENSE](https://github.com/pragma-sh/pragma/blob/main/LICENSE).

package/dist/index.cjs

@@ -0,0 +1,96 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __reExport = (target, mod, secondTarget) => {
+  var keys = __getOwnPropNames(mod);
+  for (let key of keys)
+    if (!__hasOwnProp.call(target, key) && key !== "default")
+      __defProp(target, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (secondTarget) {
+    for (let key of keys)
+      if (!__hasOwnProp.call(secondTarget, key) && key !== "default")
+        __defProp(secondTarget, key, {
+          get: __accessProp.bind(mod, key),
+          enumerable: true
+        });
+    return secondTarget;
+  }
+};
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  scratchpadBridge: () => scratchpadBridge,
+  promptAgent: () => promptAgent
+});
+module.exports = __toCommonJS(exports_src);
+__reExport(exports_src, require("@pragma-sh/sdk"), module.exports);
+function bridge() {
+  const value = globalThis.pragmaScratchpad;
+  if (!value) {
+    throw new Error("@pragma-sh/scratchpad can only prompt agents inside a Pragma scratchpad");
+  }
+  return value;
+}
+function scratchpadBridge() {
+  return bridge();
+}
+async function promptAgent(text, options = {}) {
+  const value = text.trim();
+  if (!value)
+    return false;
+  const host = bridge();
+  const firstResult = await host.promptAgent(value);
+  if (firstResult === "sent")
+    return true;
+  if (firstResult === "cancelled")
+    return false;
+  const attach = () => host.requestAgentAttachment();
+  const customResult = await options.onMissingAgent?.({ text: value, attach });
+  const attached = options.onMissingAgent ? customResult === true : await attach();
+  if (!attached)
+    return false;
+  const retryResult = await host.promptAgent(value);
+  if (retryResult === "sent")
+    return true;
+  if (retryResult === "cancelled")
+    return false;
+  throw new Error("Selected agent tab is no longer available");
+}

package/dist/index.d.cts

@@ -0,0 +1,46 @@
+export * from "@pragma-sh/sdk";
+/** Status rendered by scratchpad progress components. */
+type ScratchpadAgentStatus = "running" | "attention" | "done" | "cleared";
+/** One attached or explicitly tracked agent tab. */
+interface ScratchpadAgentProgress {
+	tabId: string;
+	title?: string;
+	agent?: string;
+	status: ScratchpadAgentStatus;
+}
+/** Read-only host rendering of one worktree-scoped whiteboard. */
+interface ScratchpadWhiteboardSnapshot {
+	id: string;
+	title: string;
+	version: number;
+	dataUrl: string;
+}
+/** Host bridge installed only inside a rendered Pragma scratchpad. */
+interface ScratchpadBridge {
+	/** Delivers text, or reports a missing attachment or reader cancellation. */
+	promptAgent(text: string): Promise<"sent" | "missing-agent" | "cancelled">;
+	requestAgentAttachment(): Promise<boolean>;
+	subscribeAgentProgress(tabIds: readonly string[], listener: (progress: readonly ScratchpadAgentProgress[]) => void): () => void;
+	/** Returns a fresh PNG only when the board changed since `knownVersion`. */
+	getWhiteboardSnapshot(id: string, knownVersion?: number, dark?: boolean): Promise<ScratchpadWhiteboardSnapshot | null>;
+	/** Opens the board in the host's interactive editor when available. */
+	openWhiteboard?(id: string): Promise<void>;
+}
+/** Context passed when a scratchpad action has no attached agent tab. */
+interface MissingAgentContext {
+	text: string;
+	attach(): Promise<boolean>;
+}
+/** Options for {@link promptAgent}. */
+interface PromptAgentOptions {
+	onMissingAgent?: (context: MissingAgentContext) => void | boolean | Promise<void | boolean>;
+}
+/** Returns scratchpad host bridge for UI bindings. */
+declare function scratchpadBridge(): ScratchpadBridge;
+/**
+* Sends text to attached agent tab. Missing attachment opens host picker by default;
+* `onMissingAgent` can replace that behavior for one call. Returns false when
+* user cancels sending or attachment without delivering a message.
+*/
+declare function promptAgent(text: string, options?: PromptAgentOptions): Promise<boolean>;
+export { scratchpadBridge, promptAgent, ScratchpadWhiteboardSnapshot, ScratchpadBridge, ScratchpadAgentStatus, ScratchpadAgentProgress, PromptAgentOptions, MissingAgentContext };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+export * from "@pragma-sh/sdk";
+/** Status rendered by scratchpad progress components. */
+type ScratchpadAgentStatus = "running" | "attention" | "done" | "cleared";
+/** One attached or explicitly tracked agent tab. */
+interface ScratchpadAgentProgress {
+	tabId: string;
+	title?: string;
+	agent?: string;
+	status: ScratchpadAgentStatus;
+}
+/** Read-only host rendering of one worktree-scoped whiteboard. */
+interface ScratchpadWhiteboardSnapshot {
+	id: string;
+	title: string;
+	version: number;
+	dataUrl: string;
+}
+/** Host bridge installed only inside a rendered Pragma scratchpad. */
+interface ScratchpadBridge {
+	/** Delivers text, or reports a missing attachment or reader cancellation. */
+	promptAgent(text: string): Promise<"sent" | "missing-agent" | "cancelled">;
+	requestAgentAttachment(): Promise<boolean>;
+	subscribeAgentProgress(tabIds: readonly string[], listener: (progress: readonly ScratchpadAgentProgress[]) => void): () => void;
+	/** Returns a fresh PNG only when the board changed since `knownVersion`. */
+	getWhiteboardSnapshot(id: string, knownVersion?: number, dark?: boolean): Promise<ScratchpadWhiteboardSnapshot | null>;
+	/** Opens the board in the host's interactive editor when available. */
+	openWhiteboard?(id: string): Promise<void>;
+}
+/** Context passed when a scratchpad action has no attached agent tab. */
+interface MissingAgentContext {
+	text: string;
+	attach(): Promise<boolean>;
+}
+/** Options for {@link promptAgent}. */
+interface PromptAgentOptions {
+	onMissingAgent?: (context: MissingAgentContext) => void | boolean | Promise<void | boolean>;
+}
+/** Returns scratchpad host bridge for UI bindings. */
+declare function scratchpadBridge(): ScratchpadBridge;
+/**
+* Sends text to attached agent tab. Missing attachment opens host picker by default;
+* `onMissingAgent` can replace that behavior for one call. Returns false when
+* user cancels sending or attachment without delivering a message.
+*/
+declare function promptAgent(text: string, options?: PromptAgentOptions): Promise<boolean>;
+export { scratchpadBridge, promptAgent, ScratchpadWhiteboardSnapshot, ScratchpadBridge, ScratchpadAgentStatus, ScratchpadAgentProgress, PromptAgentOptions, MissingAgentContext };

package/dist/index.js

@@ -0,0 +1,38 @@
+// src/index.ts
+export * from "@pragma-sh/sdk";
+function bridge() {
+  const value = globalThis.pragmaScratchpad;
+  if (!value) {
+    throw new Error("@pragma-sh/scratchpad can only prompt agents inside a Pragma scratchpad");
+  }
+  return value;
+}
+function scratchpadBridge() {
+  return bridge();
+}
+async function promptAgent(text, options = {}) {
+  const value = text.trim();
+  if (!value)
+    return false;
+  const host = bridge();
+  const firstResult = await host.promptAgent(value);
+  if (firstResult === "sent")
+    return true;
+  if (firstResult === "cancelled")
+    return false;
+  const attach = () => host.requestAgentAttachment();
+  const customResult = await options.onMissingAgent?.({ text: value, attach });
+  const attached = options.onMissingAgent ? customResult === true : await attach();
+  if (!attached)
+    return false;
+  const retryResult = await host.promptAgent(value);
+  if (retryResult === "sent")
+    return true;
+  if (retryResult === "cancelled")
+    return false;
+  throw new Error("Selected agent tab is no longer available");
+}
+export {
+  scratchpadBridge,
+  promptAgent
+};