paseo-form-render 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 quickwind
+
+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,114 @@
-# Temporary Holding Version
+# Paseo Form Render
 
-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.
+Interactive forms, dashboards, and metrics rendering plugin for Paseo conversations.
+
+## Features
+
+- **Interactive Forms in Chat**: Renders structured forms directly in the timeline from ````pfr-form```` code fences.
+- **Rich Component Catalog**:
+  - `Card`: Container with title, description, and child items
+  - `Metric`: Key-value statistics display
+  - `Input`: Text input with placeholders and required validation
+  - `Select`: Dropdown selection menus with customizable options
+  - `Toggle`: Boolean switches
+  - `Button`: Submit and action buttons with custom payloads
+- **Provider Agnostic**:
+  - Fully compatible with **Devin**, **Claude**, **Antigravity**, **Gemini**, and OpenAI providers.
+  - Automatically injects protocol instructions on agent initialization.
+- **Full Mobile & Hermes Compatibility**:
+  - 100% pure React Native UI primitives (`View`, `Text`, `TextInput`, `Pressable`, `Switch`).
+  - Zero external runtime dependencies in the client bundle.
+  - Rigorously tested against the React Native Hermes JavaScript engine on iOS and Android.
+- **Self-healing Forms**:
+  - Invalid `pfr-form` blocks show a precise error list (offending node, missing fields, allowed values, "did you mean" hints, JSON line/column).
+  - The agent is automatically asked to re-send a corrected block, up to a configurable number of times in a row.
+  - An **Ask agent to fix** button on the error box requests a fix manually (ignores the retry limit).
+  - Setting: **Paseo Form Render > Maximum retries** in the plugin settings (0-5, default 2; 0 turns automatic fixes off).
+  - Known limitations:
+    - A message sent within a few milliseconds of the agent finishing (by a script, another plugin, or an orchestrating agent) can race the automatic fix request. Paseo's `send` interrupts a running turn and has no "send only if idle" option, so in that race the fix may cancel the other message's turn. The plugin re-checks that the agent is idle right before sending, which narrows the window; messages typed by a person are not affected in practice.
+    - Not used yet: sending the fix with `activeTurnBehavior: "steer"` would add it to a running turn instead of cancelling that turn, but the agent then handles an unrelated fix request in the middle of another reply, and providers without steering support (ACP-based ones such as Copilot, Cursor, Kimi) fall back to interrupting anyway.
+    - Each assistant message is checked on its own, as the client renders it. A provider that splits one `pfr-form` fence across several messages gets a (misleading) JSON error and a fix request.
+- **Prefer forms** (on by default): the **Paseo Form Render > Prefer forms** plugin setting adds a "Required usage" section to the injected prompt, so agents must ask for choices, parameters, and confirmations with an `pfr-form` block instead of plain text. Turn it off to keep the weaker default wording, which only says agents can use forms. Applies to agents created after the change.
+- **Non-blocking `/form-demo`**:
+  - Pushes sample forms directly via daemon RPC without triggering model thinking turns or consuming API quota.
+
+## Slash Commands
+
+- `/form [task]`: Instruct the active agent to adopt the `pfr-form` protocol for interactive questionnaires or parameter collection.
+- `/form-demo`: Display a demonstration interactive configuration form in the conversation timeline without calling the model.
+
+## Installation
+
+### From npm
+```bash
+paseo plugin add npm:paseo-form-render
+```
+
+That is the whole install. Paseo fetches the package and compiles the TypeScript sources with its
+own bundler, so the plugin ships no build artifacts and has no runtime dependencies.
+
+### From Local Directory
+```bash
+paseo plugin add /path/to/paseo-form-render
+```
+
+### From Offline Package
+Unpack `paseo-form-render-<version>-offline.zip` and run:
+```bash
+paseo plugin add /path/to/extracted-folder
+```
+Or register in `~/.paseo/config.json`:
+```json
+{
+  "plugins": {
+    "paseo-form-render": {
+      "source": "directory",
+      "path": "/path/to/paseo-form-render",
+      "enabled": true
+    }
+  }
+}
+```
+
+## Development & Packaging
+
+The npm package is the primary release channel: the tarball ships the TypeScript sources plus
+`paseo-plugin.json` (the negated `files` pattern keeps the `*.test.ts` files out), and Paseo compiles
+them itself. Releases run from the **Publish** workflow by hand (Actions tab → Publish → Run workflow,
+or `gh workflow run Publish -f version=0.1.1`): it checks the version against `package.json`, re-runs
+typecheck and the unit tests, publishes with the `NPM_TOKEN` secret, then pushes the `v<version>` tag
+and opens the GitHub release. Pass `dry_run` to verify without publishing.
+
+Nothing runs automatically — this repository is private, so Actions minutes are billed. CI (unit +
+e2e on three platforms) and the Snyk scan are manual too.
+
+```bash
+# Typecheck and run test suites
+npm run typecheck
+npm test
+
+# Inspect exactly what the npm tarball would contain
+npm pack --dry-run
+
+# Build offline archive (outputs to ./dist by default)
+npm run pack:offline
+
+# Or specify a custom output directory
+npm run pack:offline -- /path/to/dist
+# or: DIST_DIR=/path/to/dist npm run pack:offline
+
+# End-to-end tests against a real Paseo daemon (Linux, macOS, Windows; Node 22+)
+npm ci --prefix e2e
+npx --prefix e2e playwright install chromium   # once, for the browser UI checks
+npm run e2e            # or: node e2e/run.mjs --all --repeat 2   (--no-ui: skip the browser)
+```
+
+The e2e harness lives in `e2e/` with its own dependencies and is not part of the plugin package; see
+[`e2e/README.md`](e2e/README.md). Besides the auto-fix protocol it checks the client UI (rendered
+forms, the error box and its "Ask agent to fix" button, the settings screen) in the daemon's web UI
+with headless Chromium and saves screenshots. CI (`.github/workflows/ci.yml`) runs the unit tests and
+the e2e suite on Linux, macOS and Windows.
+
+## License
+
+MIT

package/client/container.tsx

@@ -0,0 +1,286 @@
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import React, { useMemo, useState } from "react";
+import { View, Text, StyleSheet, Pressable, Platform } from "react-native";
+import { formatIssues } from "../shared/form-errors";
+import { buildFixMessage } from "../shared/form-fix";
+import { parseFormBlock, parseMessageContent, type ParsedBlock } from "../shared/parser";
+import { PfrFormView } from "./renderer";
+import { HostMarkdown } from "./host-markdown";
+import { PfrRpcProvider, type PfrRpcFn } from "./rpc-bridge";
+
+export interface MessageContainerProps {
+  text: string;
+  theme: PluginHostProps["theme"];
+  agentId?: string;
+  rpc?: PfrRpcFn;
+  onSubmit: (formattedMessage: string) => Promise<void> | void;
+}
+
+export interface FormBlockViewProps {
+  rawJson: string;
+  blockNumber: number;
+  theme: PluginHostProps["theme"];
+  agentId?: string;
+  rpc?: PfrRpcFn;
+  onSubmit: (formattedMessage: string) => Promise<void> | void;
+}
+
+interface FormErrorBoxProps {
+  block: ParsedBlock;
+  blockNumber: number;
+  theme: PluginHostProps["theme"];
+  onSubmit: MessageContainerProps["onSubmit"];
+}
+
+interface BlockErrorBoundaryProps {
+  fallbackText?: string;
+  children: React.ReactNode;
+}
+
+interface BlockErrorBoundaryState {
+  hasError: boolean;
+  errorMessage: string;
+}
+
+// ES5 class component for Hermes compatibility (Hermes throws syntax error on ES6 `class` keyword).
+const BlockErrorBoundary: React.ComponentClass<BlockErrorBoundaryProps, BlockErrorBoundaryState> = function (
+  this: any,
+  props: BlockErrorBoundaryProps
+) {
+  (React.Component as any).call(this, props);
+  this.state = { hasError: false, errorMessage: "" };
+} as any;
+BlockErrorBoundary.prototype = Object.create(React.Component.prototype);
+BlockErrorBoundary.prototype.constructor = BlockErrorBoundary;
+(BlockErrorBoundary as any).getDerivedStateFromError = function (error: any): BlockErrorBoundaryState {
+  const msg = error instanceof Error ? error.message : String(error);
+  return { hasError: true, errorMessage: msg };
+};
+BlockErrorBoundary.prototype.componentDidCatch = function (error: any, info: any) {
+  console.warn("[paseo-form-render] Block render failed:", error, info?.componentStack);
+};
+BlockErrorBoundary.prototype.render = function (this: any) {
+  if (this.state.hasError) {
+    return (
+      <View style={[styles.errorBox, { borderColor: "#ef4444", backgroundColor: "#fee2e2" }]}>
+        <Text style={[styles.errorTitle, { color: "#dc2626" }]}>
+          [UI Render Error]
+        </Text>
+        <Text style={[styles.errorDetail, { color: "#991b1b" }]}>
+          {this.state.errorMessage}
+        </Text>
+        {this.props.fallbackText ? (
+          <View style={styles.rawJsonBox}>
+            <Text style={[styles.rawJsonText, { color: "#1f2937" }]}>
+              {this.props.fallbackText}
+            </Text>
+          </View>
+        ) : null}
+      </View>
+    );
+  }
+  return this.props.children;
+};
+
+const FormErrorBox: React.FC<FormErrorBoxProps> = ({ block, blockNumber, theme, onSubmit }) => {
+  const [status, setStatus] = useState<"idle" | "sending" | "sent">("idle");
+  const errors = block.errors ?? [];
+
+  const askAgentToFix = async () => {
+    setStatus("sending");
+    try {
+      await onSubmit(buildFixMessage([{ issues: errors, blockNumber }]));
+      setStatus("sent");
+    } catch (e) {
+      setStatus("idle");
+    }
+  };
+
+  return (
+    <View
+      style={[
+        styles.errorBox,
+        {
+          backgroundColor: theme.colors.surface2,
+          borderColor: theme.colors.statusDanger,
+        },
+      ]}
+    >
+      <Text style={[styles.errorTitle, { color: theme.colors.statusDanger }]}>
+        [pfr-form Syntax Error]
+      </Text>
+      {formatIssues(errors).map((line, i) => (
+        <Text key={i} style={[styles.errorDetail, { color: theme.colors.statusDanger }]}>
+          {line}
+        </Text>
+      ))}
+      <View
+        style={[
+          styles.rawJsonBox,
+          {
+            backgroundColor: theme.colors.surface1,
+          },
+        ]}
+      >
+        <Text
+          style={[
+            styles.rawJsonText,
+            {
+              color: theme.colors.foreground,
+            },
+          ]}
+        >
+          {block.rawJson}
+        </Text>
+      </View>
+      {status === "sent" ? (
+        <Text style={[styles.sentText, { color: theme.colors.statusSuccess }]}>
+          ✓ Fix requested; the agent will reply with a corrected form
+        </Text>
+      ) : (
+        <Pressable
+          disabled={status !== "idle"}
+          style={[
+            styles.fixButton,
+            { backgroundColor: theme.colors.accent },
+            status !== "idle" && { opacity: 0.5 },
+          ]}
+          onPress={askAgentToFix}
+        >
+          <Text style={[styles.fixButtonText, { color: theme.colors.accentForeground }]}>
+            {status === "sending" ? "Sending…" : "Ask agent to fix"}
+          </Text>
+        </Pressable>
+      )}
+    </View>
+  );
+};
+
+export const FormBlockView: React.FC<FormBlockViewProps> = ({
+  rawJson,
+  blockNumber,
+  theme,
+  agentId,
+  rpc,
+  onSubmit,
+}) => {
+  const block = useMemo(() => parseFormBlock(rawJson), [rawJson]);
+
+  return (
+    <PfrRpcProvider rpc={rpc}>
+      {block.error ? (
+        <FormErrorBox
+          block={block}
+          blockNumber={blockNumber}
+          theme={theme}
+          onSubmit={onSubmit}
+        />
+      ) : block.form ? (
+        <PfrFormView
+          form={block.form}
+          theme={theme}
+          agentId={agentId}
+          onSubmit={onSubmit}
+        />
+      ) : null}
+    </PfrRpcProvider>
+  );
+};
+
+export const MessageContainer: React.FC<MessageContainerProps> = ({ text, theme, agentId, rpc, onSubmit }) => {
+  const blocks = parseMessageContent(text);
+
+  return (
+    <PfrRpcProvider rpc={rpc}>
+      <View style={styles.container} testID="assistant-message">
+        {blocks.map((block, idx) => {
+          if (block.type === "text" && block.content) {
+            return (
+              <BlockErrorBoundary key={idx} fallbackText={block.content}>
+                <HostMarkdown
+                  text={block.content}
+                  theme={theme}
+                />
+              </BlockErrorBoundary>
+            );
+          }
+
+          if (block.type === "form") {
+            if (block.error) {
+              return (
+                <BlockErrorBoundary key={idx} fallbackText={block.rawJson ?? ""}>
+                  <FormErrorBox
+                    block={block}
+                    blockNumber={blocks.slice(0, idx).filter((b) => b.type === "form").length + 1}
+                    theme={theme}
+                    onSubmit={onSubmit}
+                  />
+                </BlockErrorBoundary>
+              );
+            }
+
+            if (block.form) {
+              return (
+                <BlockErrorBoundary key={idx} fallbackText={block.rawJson ?? ""}>
+                  <PfrFormView
+                    form={block.form}
+                    theme={theme}
+                    agentId={agentId}
+                    onSubmit={onSubmit}
+                  />
+                </BlockErrorBoundary>
+              );
+            }
+          }
+
+          return null;
+        })}
+      </View>
+    </PfrRpcProvider>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    gap: 8,
+    width: "100%",
+    ...(Platform.OS === "web" ? { userSelect: "text" as const } : {}),
+  },
+  errorBox: {
+    borderWidth: 1,
+    borderRadius: 6,
+    padding: 12,
+    gap: 6,
+    marginVertical: 4,
+  },
+  errorTitle: {
+    fontSize: 13,
+    fontWeight: "600",
+  },
+  errorDetail: {
+    fontSize: 12,
+  },
+  fixButton: {
+    borderRadius: 6,
+    paddingHorizontal: 16,
+    paddingVertical: 8,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  fixButtonText: {
+    fontSize: 13,
+    fontWeight: "600",
+  },
+  sentText: {
+    fontSize: 12,
+    fontWeight: "600",
+  },
+  rawJsonBox: {
+    padding: 8,
+    borderRadius: 4,
+  },
+  rawJsonText: {
+    fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }),
+    fontSize: 11,
+  },
+});

package/client/host-markdown.tsx

@@ -0,0 +1,24 @@
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import * as hostUi from "@getpaseo/plugin/client/ui";
+import React from "react";
+import { MarkdownText } from "./markdown";
+
+type HostMarkdownComponent = React.ComponentType<{ children: string }>;
+
+// Newer hosts export `Markdown` from the plugin UI module; it renders with the host's own
+// typography, links, code highlighting and selection. Older hosts lack it, so fall back to
+// the built-in mini renderer. Look it up per render so a missing export never throws.
+function getHostMarkdown(): HostMarkdownComponent | undefined {
+  const candidate = (hostUi as { Markdown?: unknown }).Markdown;
+  return typeof candidate === "function" || (typeof candidate === "object" && candidate !== null)
+    ? (candidate as HostMarkdownComponent)
+    : undefined;
+}
+
+export function HostMarkdown({
+  text,
+  theme,
+}: Pick<PluginHostProps, "theme"> & { text: string }) {
+  const Host = getHostMarkdown();
+  return Host ? <Host>{text}</Host> : <MarkdownText text={text} theme={theme} />;
+}