@opengeni/react 3.3.2 → 3.4.0

package/src/components/open-geni-links.tsx

@@ -0,0 +1,179 @@
+import type { OpenGeniClient, OpenGeniLinkTarget } from "@opengeni/sdk";
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+
+export type { OpenGeniLinkTarget };
+
+/**
+ * How the host opens one Opengeni object an agent linked in chat Markdown.
+ *
+ * - `{ href }` renders a real link (new tab) — use it for a host page URL.
+ * - `{ open }` renders a button that runs the action (download, open a panel,
+ *   client-side navigation) with loading and retry states.
+ * - `null` / `undefined` means "not handled here": the next resolver is asked,
+ *   and when none handles it the text renders as an unavailable reference —
+ *   never as a navigation that would 404 inside the host.
+ */
+export type OpenGeniLinkResolution =
+  | { href: string; open?: undefined }
+  | { open: () => void | Promise<void>; href?: undefined };
+
+export type OpenGeniLinkResolver = (
+  target: OpenGeniLinkTarget,
+) => OpenGeniLinkResolution | null | undefined;
+
+const OpenGeniLinkContext = createContext<OpenGeniLinkResolver | null>(null);
+
+/** First resolver that handles a target wins. */
+export function chainLinkResolvers(
+  ...resolvers: ReadonlyArray<OpenGeniLinkResolver | null | undefined>
+): OpenGeniLinkResolver | null {
+  const active = resolvers.filter((resolver): resolver is OpenGeniLinkResolver =>
+    Boolean(resolver),
+  );
+  if (active.length === 0) return null;
+  if (active.length === 1) return active[0]!;
+  return (target) => {
+    for (const resolver of active) {
+      const resolution = resolver(target);
+      if (resolution) return resolution;
+    }
+    return null;
+  };
+}
+
+/**
+ * Resolve Opengeni object links (`artifact:`, `sandbox:`, editable artifacts,
+ * Sites) for every {@link Markdown} body below. An inner provider is asked
+ * before an outer one, so a host can override a single kind and keep defaults.
+ */
+export function OpenGeniLinkProvider({
+  resolveLink,
+  children,
+}: {
+  resolveLink: OpenGeniLinkResolver | null | undefined;
+  children: ReactNode;
+}) {
+  const parent = useContext(OpenGeniLinkContext);
+  const value = useMemo(() => chainLinkResolvers(resolveLink, parent), [resolveLink, parent]);
+  return <OpenGeniLinkContext.Provider value={value}>{children}</OpenGeniLinkContext.Provider>;
+}
+
+/** The effective resolver from the nearest {@link OpenGeniLinkProvider}. */
+export function useOpenGeniLinkResolver(): OpenGeniLinkResolver | null {
+  return useContext(OpenGeniLinkContext);
+}
+
+// Every sandbox read the proxy forwards is bounded by the API's own maximum.
+const SANDBOX_DOWNLOAD_MAX_BYTES = 25 * 1024 * 1024;
+
+type SessionLinkClient = Partial<Pick<OpenGeniClient, "createFileDownloadUrl" | "fsRead">>;
+
+function saveBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = filename;
+  link.rel = "noopener";
+  document.body.append(link);
+  link.click();
+  link.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+
+function openUrl(url: string): void {
+  // A signed download URL is attachment-disposition; an anchor click keeps the
+  // page and survives popup blockers after the awaited URL request.
+  const link = document.createElement("a");
+  link.href = url;
+  link.rel = "noopener noreferrer";
+  link.target = "_blank";
+  document.body.append(link);
+  link.click();
+  link.remove();
+}
+
+function base64Bytes(content: string): Uint8Array<ArrayBuffer> {
+  const binary = atob(content);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
+/**
+ * Default resolver for a session conversation that talks to Opengeni through
+ * the normal SDK client (for example behind `createSessionProxyHandler`):
+ *
+ * - `artifact:<file>` downloads the retained file through a short-lived URL.
+ * - `sandbox:<path>` downloads when enabled by the host proxy capability.
+ *
+ * Editable artifacts and Sites have no default: they need a host surface
+ * (see `@opengeni/react/artifacts/*` and `@opengeni/react/sites`), so they stay
+ * unavailable until the host resolves them.
+ */
+export function sessionLinkResolver(input: {
+  client: SessionLinkClient;
+  workspaceId: string;
+  sessionId: string;
+  sandboxFiles?: boolean;
+}): OpenGeniLinkResolver {
+  const { client, workspaceId, sessionId } = input;
+  return (target) => {
+    if (target.kind === "file") {
+      if (target.workspaceId !== null && target.workspaceId !== workspaceId) return null;
+      if (typeof client.createFileDownloadUrl !== "function") return null;
+      return {
+        open: async () => {
+          const { url } = await client.createFileDownloadUrl!(workspaceId, target.fileId, {
+            sessionId,
+          });
+          openUrl(url);
+        },
+      };
+    }
+    if (target.kind === "sandbox-file") {
+      if (input.sandboxFiles === false) return null;
+      if (typeof client.fsRead !== "function") return null;
+      return {
+        open: async () => {
+          const file = await client.fsRead!(workspaceId, sessionId, {
+            path: target.path,
+            encoding: "base64",
+            maxBytes: SANDBOX_DOWNLOAD_MAX_BYTES,
+          });
+          if (file.truncated) throw new Error("File is too large to download here.");
+          const name = file.path.split(/[\\/]/u).at(-1) || "download";
+          const bytes =
+            file.encoding === "base64"
+              ? base64Bytes(file.content)
+              : new TextEncoder().encode(file.content);
+          saveBlob(new Blob([bytes], { type: "application/octet-stream" }), name);
+        },
+      };
+    }
+    return null;
+  };
+}
+
+/** An editable artifact or Site to open in a host-mounted viewer. */
+export type OpenGeniViewerTarget = Readonly<{
+  kind: "editable-artifact" | "site";
+  artifactId: string;
+  /** The link text the agent wrote, until the viewer loads the real title. */
+  title?: string | undefined;
+}>;
+
+/**
+ * "Open in host viewer": resolve agent links to editable artifacts and Sites
+ * in this workspace to `open(target)`, for example to mount
+ * `SessionArtifactViewer` beside the conversation. Other targets fall through.
+ */
+export function viewerLinkResolver(input: {
+  workspaceId: string;
+  open: (target: OpenGeniViewerTarget) => void;
+}): OpenGeniLinkResolver {
+  return (target) => {
+    if (target.kind !== "editable-artifact" && target.kind !== "site") return null;
+    if (target.workspaceId !== input.workspaceId) return null;
+    return { open: () => input.open({ kind: target.kind, artifactId: target.artifactId }) };
+  };
+}

package/src/components/openrouter-mark.tsx

@@ -0,0 +1,13 @@
+import type { SVGProps } from "react";
+
+/**
+ * Simple Icons, CC0; https://github.com/simple-icons/simple-icons
+ * Source: https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/openrouter.svg
+ */
+export function OpenRouterMark(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" {...props}>
+      <path d="M16.778 1.844v1.919q-.569-.026-1.138-.032-.708-.008-1.415.037c-1.93.126-4.023.728-6.149 2.237-2.911 2.066-2.731 1.95-4.14 2.75-.396.223-1.342.574-2.185.798-.841.225-1.753.333-1.751.333v4.229s.768.108 1.61.333c.842.224 1.789.575 2.185.799 1.41.798 1.228.683 4.14 2.75 2.126 1.509 4.22 2.11 6.148 2.236.88.058 1.716.041 2.555.005v1.918l7.222-4.168-7.222-4.17v2.176c-.86.038-1.611.065-2.278.021-1.364-.09-2.417-.357-3.979-1.465-2.244-1.593-2.866-2.027-3.68-2.508.889-.518 1.449-.906 3.822-2.59 1.56-1.109 2.614-1.377 3.978-1.466.667-.044 1.418-.017 2.278.02v2.176L24 6.014Z" />
+    </svg>
+  );
+}

package/src/components/opper-mark.tsx

@@ -0,0 +1,18 @@
+import type { SVGProps } from "react";
+
+/**
+ * Opper's mark (the leaf-and-star symbol of the opper.ai wordmark), redrawn
+ * as a single currentColor path on a square box.
+ * Source: https://opper.ai (header logo SVG).
+ */
+export function OpperMark(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg viewBox="-49.5 0 315 315" fill="currentColor" aria-hidden="true" {...props}>
+      <path
+        fillRule="evenodd"
+        clipRule="evenodd"
+        d="M159.78 315C71.53 315 0 244.49 0 157.5C0 -18.9499 159.78 0.650075 159.78 0.650075C159.78 87.2201 88.36 157.4 0.2 157.5C149.8 157.64 159.78 315 159.78 315ZM160.52 217.98C160.52 217.98 156.94 161.65 105.04 157.52C120.6 157.34 160.52 151.54 160.52 96.5601C160.52 151.54 200.44 157.34 216 157.52C164.1 161.63 160.52 217.98 160.52 217.98Z"
+      />
+    </svg>
+  );
+}

package/src/components/pierre-diff.tsx

@@ -7,9 +7,15 @@ import {
   Suspense,
   useEffect,
   useState,
+  useSyncExternalStore,
 } from "react";
 import { cn } from "../lib/cn";
 import { gitFileDiffToPatch } from "../lib/git-patch";
+import {
+  loadPierreDiffs,
+  pierreDiffsRevision,
+  subscribePierreDiffs,
+} from "../lib/pierre-diffs-loader";
 
 /** Pierre `PatchDiff` props subset we drive. */
 type PatchDiffComponent = ComponentType<{
@@ -50,10 +56,10 @@ export type PierreDiffProps = {
 
 // Lazy-load `@pierre/diffs/react` so Shiki + the worker pool stay off the
 // critical path (and out of an SSR bundle) until a diff is actually shown. The
-// dynamic specifier is static so the bundler can resolve + chunk it. If the
-// optional peer is absent the import rejects and we render `fallback`.
+// peer is loaded only through the host-registered loader (see
+// `enablePierreDiffs`); without one the load rejects and we render `fallback`.
 const LazyPatchDiff = lazy(async () => {
-  const mod = (await import("@pierre/diffs/react")) as unknown as {
+  const mod = (await loadPierreDiffs()) as {
     PatchDiff: PatchDiffComponent;
   };
   return { default: mod.PatchDiff };
@@ -78,6 +84,7 @@ export function PierreDiff({
   className,
 }: PierreDiffProps) {
   const [failed, setFailed] = useState(false);
+  const [ready, setReady] = useState(false);
   const [forcedColors, setForcedColors] = useState(false);
 
   // Pierre's rich renderer distinguishes additions/deletions primarily through
@@ -95,16 +102,29 @@ export function PierreDiff({
 
   // Probe the import once so a hard failure (peer missing) shows `fallback`
   // rather than a Suspense boundary that never resolves. Skipped when `plain`.
+  const loaderRevision = useSyncExternalStore(
+    subscribePierreDiffs,
+    pierreDiffsRevision,
+    pierreDiffsRevision,
+  );
   useEffect(() => {
     if (plain) return;
     let cancelled = false;
-    void import("@pierre/diffs/react").catch(() => {
-      if (!cancelled) setFailed(true);
-    });
+    setFailed(false);
+    // Mount the lazy renderer only after the peer loaded, so a missing peer
+    // never poisons React.lazy's cached result for the rest of the page.
+    loadPierreDiffs().then(
+      () => {
+        if (!cancelled) setReady(true);
+      },
+      () => {
+        if (!cancelled) setFailed(true);
+      },
+    );
     return () => {
       cancelled = true;
     };
-  }, [plain]);
+  }, [plain, loaderRevision]);
 
   if (plain || failed || forcedColors) {
     // `plain` opts out of highlighting; `failed` = `@pierre/diffs` not installed.
@@ -147,6 +167,9 @@ export function PierreDiff({
     "--diffs-light-bg": "var(--og-color-bg)",
     "--diffs-bg-buffer-override": "var(--og-color-surface-1)",
     "--diffs-bg-separator-override": "var(--og-color-surface-1)",
+    // Pierre's default (fg mixed 65% into bg) falls under 4.5:1 on the lifted
+    // graphite separator; quiet meta text keeps AA on every diff surface.
+    "--diffs-fg-number-override": "var(--og-color-fg-subtle)",
     "--diffs-addition-color-override": "var(--og-color-status-idle)",
     "--diffs-deletion-color-override": "var(--og-color-status-failed)",
     "--diffs-fg-number-addition-override": "var(--og-color-status-idle)",
@@ -168,15 +191,17 @@ export function PierreDiff({
   return (
     <div className={cn("min-w-0", className)} data-opengeni-pierre-diff style={pierreVars}>
       <Suspense fallback={loading ?? <DiffSkeleton />}>
-        {diff.map((file) => (
-          <div key={file.path} className="mb-2">
-            <LazyPatchDiff
-              patch={gitFileDiffToPatch(file)}
-              options={options}
-              {...(disableWorkerPool !== undefined ? { disableWorkerPool } : {})}
-            />
-          </div>
-        ))}
+        {ready
+          ? diff.map((file) => (
+              <div key={file.path} className="mb-2">
+                <LazyPatchDiff
+                  patch={gitFileDiffToPatch(file)}
+                  options={options}
+                  {...(disableWorkerPool !== undefined ? { disableWorkerPool } : {})}
+                />
+              </div>
+            ))
+          : (loading ?? <DiffSkeleton />)}
       </Suspense>
     </div>
   );

package/src/components/pierre-file.tsx

@@ -6,8 +6,14 @@ import {
   Suspense,
   useEffect,
   useState,
+  useSyncExternalStore,
 } from "react";
 import { cn } from "../lib/cn";
+import {
+  loadPierreDiffs,
+  pierreDiffsRevision,
+  subscribePierreDiffs,
+} from "../lib/pierre-diffs-loader";
 
 /** Pierre `File` props subset we drive — the single-file, syntax-highlighted view
  *  (Shiki), the read counterpart of `PatchDiff`. */
@@ -44,7 +50,7 @@ export type PierreFileProps = {
 // Lazy-load `@pierre/diffs/react`'s `File` so Shiki + the worker pool stay off the
 // critical path (and out of an SSR bundle) until a file is actually viewed.
 const LazyFile = lazy(async () => {
-  const mod = (await import("@pierre/diffs/react")) as unknown as { File: FileComponent };
+  const mod = (await loadPierreDiffs()) as { File: FileComponent };
   return { default: mod.File };
 });
 
@@ -65,18 +71,30 @@ export function PierreFile({
   className,
 }: PierreFileProps) {
   const [failed, setFailed] = useState(false);
+  const [ready, setReady] = useState(false);
 
   // Probe the import once so a hard failure (peer missing) shows `fallback`
   // rather than a Suspense boundary that never resolves.
+  const loaderRevision = useSyncExternalStore(
+    subscribePierreDiffs,
+    pierreDiffsRevision,
+    pierreDiffsRevision,
+  );
   useEffect(() => {
     let cancelled = false;
-    void import("@pierre/diffs/react").catch(() => {
-      if (!cancelled) setFailed(true);
-    });
+    setFailed(false);
+    loadPierreDiffs().then(
+      () => {
+        if (!cancelled) setReady(true);
+      },
+      () => {
+        if (!cancelled) setFailed(true);
+      },
+    );
     return () => {
       cancelled = true;
     };
-  }, []);
+  }, [loaderRevision]);
 
   const name = path.split("/").filter(Boolean).pop() ?? path;
 
@@ -108,6 +126,9 @@ export function PierreFile({
     "--diffs-light-bg": "var(--og-color-bg)",
     "--diffs-bg-buffer-override": "var(--og-color-surface-1)",
     "--diffs-bg-separator-override": "var(--og-color-surface-1)",
+    // Pierre's default (fg mixed 65% into bg) falls under 4.5:1 on the lifted
+    // graphite separator; quiet meta text keeps AA on every diff surface.
+    "--diffs-fg-number-override": "var(--og-color-fg-subtle)",
     "--diffs-font-size": "var(--og-code-font-size)",
     "--diffs-line-height": "var(--og-code-line-height)",
   } as CSSProperties;
@@ -117,11 +138,15 @@ export function PierreFile({
       <Suspense fallback={loading ?? <FileSkeleton />}>
         {/* `cacheKey` keys Pierre's worker-pool highlight cache on path+size so a
             re-select of the same file is instant but an edited file re-highlights. */}
-        <LazyFile
-          file={{ name, contents }}
-          options={options}
-          {...(disableWorkerPool !== undefined ? { disableWorkerPool } : {})}
-        />
+        {ready ? (
+          <LazyFile
+            file={{ name, contents }}
+            options={options}
+            {...(disableWorkerPool !== undefined ? { disableWorkerPool } : {})}
+          />
+        ) : (
+          (loading ?? <FileSkeleton />)
+        )}
       </Suspense>
     </div>
   );

package/src/components/preview-loading.tsx

@@ -0,0 +1,109 @@
+import { useEffect, useRef } from "react";
+import { paintPreviewLoading } from "../preview-loading-paint";
+
+/** Private loading surface: never receives or executes the unfinished fence. */
+export function PreviewLoading() {
+  const ref = useRef<HTMLCanvasElement>(null);
+  useEffect(() => {
+    const canvas = ref.current;
+    if (!canvas) return;
+    let ctx: CanvasRenderingContext2D | null;
+    try {
+      ctx = canvas.getContext("2d");
+    } catch {
+      return; // The CSS grid and status remain when canvas is unavailable.
+    }
+    if (!ctx) return;
+    const context = ctx;
+    const motion = window.matchMedia?.("(prefers-reduced-motion: reduce)");
+    let frame: number | undefined;
+    let time = 2;
+    let last: number | undefined;
+    let disposed = false;
+    // Without visibility observation, keep a static surface rather than doing
+    // unbounded work for previews that may be outside the viewport.
+    let visible = false;
+    const canAnimate = () => !disposed && visible && !document.hidden && motion?.matches === false;
+
+    function draw() {
+      const w = canvas!.clientWidth;
+      const h = canvas!.clientHeight;
+      if (!w || !h || document.hidden || disposed) return;
+      const d = Math.min(window.devicePixelRatio || 1, 2);
+      if (canvas!.width !== Math.round(w * d) || canvas!.height !== Math.round(h * d)) {
+        canvas!.width = Math.round(w * d);
+        canvas!.height = Math.round(h * d);
+      }
+      const style = getComputedStyle(canvas!);
+      const ink = style.getPropertyValue("--_og-preview-ink").trim() || "#9fdccd";
+      const glowColor = style.getPropertyValue("--_og-preview-glow").trim() || "#5fb8a3";
+      context.setTransform(d, 0, 0, d, 0, 0);
+      paintPreviewLoading(context, w, h, time, ink, glowColor);
+      canvas!.dataset.painted = "true";
+    }
+
+    function stop() {
+      if (frame !== undefined) window.cancelAnimationFrame(frame);
+      frame = undefined;
+      last = undefined;
+    }
+    function tick(stamp: number) {
+      frame = undefined;
+      if (!canAnimate()) return;
+      if (last !== undefined) time += Math.min((stamp - last) / 1000, 0.05);
+      last = stamp;
+      draw();
+      frame = window.requestAnimationFrame(tick);
+    }
+    function refresh() {
+      stop();
+      if (disposed || document.hidden || (!visible && intersection)) return;
+      draw();
+      if (canAnimate() && typeof window.requestAnimationFrame === "function") {
+        frame = window.requestAnimationFrame(tick);
+      }
+    }
+    const intersection =
+      typeof IntersectionObserver === "function"
+        ? new IntersectionObserver(([entry]) => {
+            visible = entry?.isIntersecting === true;
+            refresh();
+          })
+        : undefined;
+    intersection?.observe(canvas);
+    const resize = typeof ResizeObserver === "function" ? new ResizeObserver(refresh) : undefined;
+    resize?.observe(canvas);
+    // Observe only ancestors, not the document subtree. This also updates the
+    // static reduced-motion canvas when a host changes its local theme.
+    const theme =
+      typeof MutationObserver === "function" ? new MutationObserver(refresh) : undefined;
+    for (let ancestor = canvas.parentElement; ancestor; ancestor = ancestor.parentElement) {
+      theme?.observe(ancestor, {
+        attributes: true,
+        attributeFilter: ["class", "style", "data-og-theme"],
+      });
+    }
+    motion?.addEventListener?.("change", refresh);
+    document.addEventListener("visibilitychange", refresh);
+    window.addEventListener("resize", refresh);
+    // Old hosts get one still frame; observed surfaces wait until onscreen.
+    if (!intersection) draw();
+    return () => {
+      disposed = true;
+      stop();
+      intersection?.disconnect();
+      resize?.disconnect();
+      theme?.disconnect();
+      motion?.removeEventListener?.("change", refresh);
+      document.removeEventListener("visibilitychange", refresh);
+      window.removeEventListener("resize", refresh);
+    };
+  }, []);
+
+  return (
+    <div className="og-preview-loading">
+      <canvas ref={ref} aria-hidden="true" />
+      <span className="og-preview-loading-label">Preparing preview…</span>
+    </div>
+  );
+}

package/src/components/provider-recovery-notice.tsx

@@ -0,0 +1,49 @@
+import { Clock3Icon } from "lucide-react";
+
+import { cn } from "../lib/cn";
+import { providerRecoveryRetryingText, type ProviderRecoveryFacts } from "../lib/provider-recovery";
+
+export type ProviderRecoveryNoticeProps = {
+  /** From `currentProviderRecovery(session, events)`; renders nothing when null. */
+  recovery: ProviderRecoveryFacts | null | undefined;
+  /** Replaces the secondary line; `null` hides it. */
+  detail?: string | null | undefined;
+  className?: string | undefined;
+};
+
+export const PROVIDER_RECOVERY_NOTICE_DETAIL =
+  "Your message is saved. Opengeni keeps retrying automatically for a few minutes.";
+
+export const SANDBOX_WAIT_NOTICE_DETAIL =
+  "The turn continues automatically as soon as the sandbox is ready.";
+
+/**
+ * One calm, live status line while the same turn waits for an automatic retry
+ * after a transient provider failure. It replaces itself on every attempt
+ * instead of adding timeline rows, and disappears once the turn runs again.
+ */
+export function ProviderRecoveryNotice({
+  recovery,
+  detail,
+  className,
+}: ProviderRecoveryNoticeProps) {
+  if (!recovery) return null;
+  const secondary =
+    detail === undefined
+      ? recovery.sandboxWait
+        ? SANDBOX_WAIT_NOTICE_DETAIL
+        : PROVIDER_RECOVERY_NOTICE_DETAIL
+      : detail;
+  return (
+    <div
+      className={cn("flex items-start gap-2 text-og-sm text-og-fg-muted", className)}
+      data-og-provider-recovery=""
+    >
+      <Clock3Icon aria-hidden="true" className="mt-0.5 size-4 shrink-0" />
+      <div className="min-w-0" role="status" aria-live="polite">
+        <p className="font-medium text-og-fg">{providerRecoveryRetryingText(recovery)}</p>
+        {secondary ? <p className="mt-0.5 text-og-xs">{secondary}</p> : null}
+      </div>
+    </div>
+  );
+}

package/src/components/queue-item-content.ts

@@ -0,0 +1,14 @@
+/**
+ * One presentation rule for a queued item, shared by the full queue and the
+ * compact session-chrome dock so the two cannot drift. A turn with an empty
+ * prompt and timeline annotations is valid content; an item with neither is a
+ * malformed or legacy object that gets an explicit fallback, never a blank row.
+ */
+export type QueueItemContent = "text" | "annotations" | "unavailable";
+
+export const QUEUE_ITEM_CONTENT_UNAVAILABLE = "Content unavailable";
+
+export function queueItemContent(text: string, annotationCount: number): QueueItemContent {
+  if (text.length > 0) return "text";
+  return annotationCount > 0 ? "annotations" : "unavailable";
+}