@xemahq/ui-kernel 0.9.0 → 0.9.2

package/src/vista/surfaces/FilesSurface.tsx

@@ -0,0 +1,202 @@
+/**
+ * `SurfaceKind.Files` — the grouped file browser, and the pinned first tab of
+ * every file-backed Vista panel.
+ *
+ * Moved out of the thin session workspace (`WorkspaceFileBrowser` +
+ * `workspace-model`'s grouping/extension helpers) so the Design-System-Builder
+ * file tab, the session workspace, and any agent-opened `files` surface draw the
+ * SAME browser. Grouped by folder with a caption header; each row is a
+ * colour-coded extension tile + filename + change badges. Clicking a row opens
+ * the file as its own tab through {@link useVistaOpen}.
+ */
+import { ChevronRight, Folder } from 'lucide-react';
+
+
+import { fileSurface } from '../vista-model';
+import { useVistaOpen } from '../vista-open-state';
+import { fileExtMeta, groupFilesByFolder } from './file-surface-utils';
+
+import type { VistaFileEntry, VistaFilesPayload } from '../vista-payloads';
+import type { ReactElement } from 'react';
+
+export function FilesSurface({
+  files,
+}: Readonly<VistaFilesPayload>): ReactElement {
+  const open = useVistaOpen();
+  const groups = groupFilesByFolder(files);
+  if (groups.length === 0) {
+    return (
+      <div
+        style={{
+          height: '100%',
+          display: 'grid',
+          placeItems: 'center',
+          fontSize: 12.5,
+          color: 'hsl(var(--ink-4))',
+        }}
+      >
+        No files in the workspace yet.
+      </div>
+    );
+  }
+  return (
+    <div style={{ height: '100%', overflowY: 'auto', padding: '14px 12px' }}>
+      {groups.map((group) => (
+        <section key={group.dir || 'root'} style={{ marginBottom: 16 }}>
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: 6,
+              padding: '0 8px 8px',
+            }}
+          >
+            <Folder size={12} style={{ color: 'hsl(var(--ink-4))' }} />
+            <span
+              className="cap"
+              style={{ fontSize: 9.5, letterSpacing: '0.07em' }}
+            >
+              {group.dir ? group.dir.replaceAll('/', ' / ') : 'Root'}
+            </span>
+          </div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 1 }}>
+            {group.files.map((file) => (
+              <FileRow
+                key={file.path}
+                file={file}
+                onOpen={
+                  open === null
+                    ? null
+                    : () => {
+                        open(fileSurface(file.path));
+                      }
+                }
+              />
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  );
+}
+
+function FileRow({
+  file,
+  onOpen,
+}: Readonly<{
+  file: VistaFileEntry;
+  onOpen: (() => void) | null;
+}>): ReactElement {
+  const name = file.path.split('/').pop() ?? file.path;
+  const meta = fileExtMeta(name);
+  const changed = file.add !== undefined || file.del !== undefined;
+  const body = (
+    <>
+      <span
+        style={{
+          width: 28,
+          height: 28,
+          borderRadius: 8,
+          flexShrink: 0,
+          display: 'grid',
+          placeItems: 'center',
+          background: `color-mix(in oklch, ${meta.color} 13%, transparent)`,
+          border: `1px solid color-mix(in oklch, ${meta.color} 26%, transparent)`,
+        }}
+      >
+        <span
+          className="mono"
+          style={{
+            fontSize: 8,
+            fontWeight: 700,
+            color: meta.color,
+            letterSpacing: '0.02em',
+          }}
+        >
+          {meta.tag}
+        </span>
+      </span>
+      <span style={{ flex: 1, minWidth: 0 }}>
+        <span
+          style={{
+            display: 'block',
+            fontSize: 13,
+            fontWeight: 500,
+            color: 'hsl(var(--ink))',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {name}
+        </span>
+        {changed && (
+          <span
+            className="mono"
+            style={{ fontSize: 10, color: 'hsl(var(--ink-4))' }}
+          >
+            changed
+          </span>
+        )}
+      </span>
+      {changed && (
+        <span style={{ display: 'inline-flex', gap: 6, flexShrink: 0 }}>
+          {file.add !== undefined && file.add > 0 && (
+            <span
+              className="mono"
+              style={{ fontSize: 10.5, color: 'hsl(var(--success))' }}
+            >
+              +{file.add}
+            </span>
+          )}
+          {file.del !== undefined && file.del > 0 && (
+            <span
+              className="mono"
+              style={{
+                fontSize: 10.5,
+                color: 'hsl(var(--destructive, var(--danger)))',
+              }}
+            >
+              −{file.del}
+            </span>
+          )}
+        </span>
+      )}
+      {onOpen !== null && (
+        <ChevronRight
+          size={13}
+          style={{ color: 'hsl(var(--ink-4))', flexShrink: 0, opacity: 0.6 }}
+        />
+      )}
+    </>
+  );
+
+  const rowStyle = {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 11,
+    width: '100%',
+    padding: '8px 9px',
+    borderRadius: 9,
+    textAlign: 'left',
+  } as const;
+
+  if (onOpen === null) {
+    return <div style={rowStyle}>{body}</div>;
+  }
+  return (
+    <button
+      type="button"
+      onClick={onOpen}
+      style={{ ...rowStyle, transition: 'background 140ms ease' }}
+      onMouseEnter={(e) => {
+        e.currentTarget.style.background = 'hsl(var(--paper-elev))';
+      }}
+      onMouseLeave={(e) => {
+        e.currentTarget.style.background = 'transparent';
+      }}
+    >
+      {body}
+    </button>
+  );
+}

package/src/vista/surfaces/FormSurface.tsx

@@ -0,0 +1,363 @@
+/**
+ * `SurfaceKind.Form` — the secure-elicitation surface (Canopy §8.4).
+ *
+ * The agent asks for a credential it must never see. This surface renders the
+ * connector's ONBOARDING form (or, for `oauth2` / `app_install`, the consent
+ * link), captures the values in local state, and POSTs them BROWSER → OWNING
+ * SERVICE with the SUBJECT's own JWT. The agent learns only
+ * `{ submitted, ref }`.
+ *
+ * ── What makes the value unreachable from the agent ─────────────────────────
+ *   • the only outbound channel is `host.onOutcome(VistaFormOutcome)`, whose
+ *     type has three scalar members and no place a value could be assigned;
+ *   • the values live in this component's `useState`; the single reader is
+ *     `submitElicitationFields`, which takes them as a parameter and returns an
+ *     outcome — the values are not reachable from any return or any throw;
+ *   • the payload has NO URL authority. The exact endpoints are derived from
+ *     the trusted elicitation API base URL supplied by `VistaFormHost`;
+ *   • secret fields are DECLARED (`spec.isSecret`) and render write-only; the
+ *     surface holds no cache and no read path repopulates them.
+ *
+ * Nothing here is provider-aware. Whether the flow is a field form or an OAuth
+ * handoff is decided by the payload the owning service produced.
+ */
+import {
+  AlertTriangle,
+  CheckCircle2,
+  ExternalLink,
+  Loader2,
+  ShieldCheck,
+} from 'lucide-react';
+import {
+  useCallback,
+  useEffect,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+import {
+  readElicitationStatus,
+  resolveTrustedElicitationEndpoints,
+  resolveTrustedElicitationLaunchUrl,
+  submitElicitationFields,
+  VistaFormSubmitError,
+} from './elicitation-transport';
+import { SchemaForm } from '../../ui/capture/schema-form';
+import { captureValuesToStringMap } from '../../ui/capture/submit-values';
+import { useSchemaValidation } from '../../ui/capture/use-schema-validation';
+import { cn } from '../../ui/cn';
+import { Button } from '../../ui/primitives/button';
+import {
+  useVistaFormHost,
+  type VistaFormOutcome,
+} from '../vista-form-context';
+
+import type { CaptureValues } from '../../ui/capture/field-spec';
+import type { VistaFormPayload } from '../vista-payloads';
+
+/** Explicit lifecycle. No implicit "maybe submitted" state. */
+enum FormPhase {
+  Editing = 'editing',
+  Working = 'working',
+  Settled = 'settled',
+}
+
+export function FormSurface(payload: Readonly<VistaFormPayload>): ReactElement {
+  const host = useVistaFormHost();
+  const [values, setValues] = useState<CaptureValues>({});
+  const [phase, setPhase] = useState<FormPhase>(FormPhase.Editing);
+  const [serviceError, setServiceError] = useState<string | null>(null);
+  const [showFieldErrors, setShowFieldErrors] = useState(false);
+  const [outcome, setOutcome] = useState<VistaFormOutcome | null>(null);
+  const { errors, isValid } = useSchemaValidation(payload.fields, values);
+  let transportConfigurationError: string | null = null;
+  let launchUrl: string | undefined;
+  if (host !== null) {
+    try {
+      // Validate the trust anchor before retrieving a bearer token or accepting
+      // a submit action. The transport repeats this check at the fetch boundary.
+      resolveTrustedElicitationEndpoints(
+        host.elicitationApiBaseUrl,
+        payload.ref,
+      );
+      if (payload.launch !== undefined) {
+        launchUrl = resolveTrustedElicitationLaunchUrl(
+          host.elicitationApiBaseUrl,
+          payload.launch.path,
+        );
+      }
+    } catch (error) {
+      transportConfigurationError =
+        error instanceof Error
+          ? error.message
+          : 'The trusted elicitation service is not configured safely.';
+    }
+  }
+
+  const settle = useCallback(
+    (next: VistaFormOutcome): void => {
+      // The values are dropped the moment the elicitation settles: nothing in
+      // this component may outlive the submission holding secret material.
+      setValues({});
+      setOutcome(next);
+      setPhase(FormPhase.Settled);
+      host?.onOutcome(next);
+    },
+    [host],
+  );
+
+  const failed = useCallback((error: unknown): void => {
+    setServiceError(
+      error instanceof VistaFormSubmitError || error instanceof Error
+        ? error.message
+        : 'The submission could not be completed.',
+    );
+    setPhase(FormPhase.Editing);
+  }, []);
+
+  const handleSubmit = useCallback((): void => {
+    if (host === null) return;
+    setShowFieldErrors(true);
+    if (!isValid) return;
+    setServiceError(null);
+    setPhase(FormPhase.Working);
+    // The values object is a PARAMETER here and nowhere else. It is never
+    // returned, logged, or handed to a callback.
+    void host
+      .getAccessToken()
+      .then((accessToken) =>
+        submitElicitationFields({
+          apiBaseUrl: host.elicitationApiBaseUrl,
+          ref: payload.ref,
+          accessToken,
+          fields: captureValuesToStringMap(payload.fields, values),
+        }),
+      )
+      .then(settle, failed);
+  }, [host, isValid, payload.fields, payload.ref, settle, failed, values]);
+
+  const handleCheckStatus = useCallback((): void => {
+    if (host === null) return;
+    setServiceError(null);
+    setPhase(FormPhase.Working);
+    void host
+      .getAccessToken()
+      .then((accessToken) =>
+        readElicitationStatus({
+          apiBaseUrl: host.elicitationApiBaseUrl,
+          ref: payload.ref,
+          accessToken,
+        }),
+      )
+      .then((next) => {
+        if (next === null) {
+          setServiceError(
+            'Not completed yet — finish the steps in the other window, then check again.',
+          );
+          setPhase(FormPhase.Editing);
+          return;
+        }
+        settle(next);
+      }, failed);
+  }, [host, payload.ref, settle, failed]);
+
+  // The consent/install window is a separate browsing context, so the only
+  // signal this tab gets is the user returning to it. Re-checking on focus is
+  // an event, not a timer — there is no polling loop and no timeout.
+  const isLaunch = payload.launch !== undefined;
+  useEffect(() => {
+    if (!isLaunch || phase === FormPhase.Settled || host === null) return;
+    const onFocus = (): void => handleCheckStatus();
+    globalThis.addEventListener?.('focus', onFocus);
+    return () => globalThis.removeEventListener?.('focus', onFocus);
+    // `handleCheckStatus` is stable per (host, payload) and re-subscribing on a
+    // phase change is intended: a settled surface stops listening.
+  }, [isLaunch, phase, host, handleCheckStatus]);
+
+  if (host === null) {
+    return (
+      <Shell heading={payload.heading} purpose={payload.purpose}>
+        <Notice tone="error" title="This form cannot be submitted here">
+          No form host is mounted for this panel, so there is no way to sign the
+          request as you. Open the request from a surface that provides one.
+        </Notice>
+      </Shell>
+    );
+  }
+
+  if (transportConfigurationError !== null) {
+    return (
+      <Shell heading={payload.heading} purpose={payload.purpose}>
+        <Notice
+          tone="error"
+          title="The secure service is not configured safely"
+        >
+          {transportConfigurationError}
+        </Notice>
+      </Shell>
+    );
+  }
+
+  if (phase === FormPhase.Settled && outcome !== null) {
+    return (
+      <Shell heading={payload.heading} purpose={payload.purpose}>
+        <div className="flex items-start gap-2 rounded-md border border-rule bg-paper-elev p-3">
+          <CheckCircle2 className="mt-0.5 h-4 w-4 shrink-0 text-primary" />
+          <div className="space-y-0.5">
+            <p className="text-body-1 font-medium text-ink">Submitted.</p>
+            <p className="text-caption text-ink-3">
+              The value went straight to the service and was never shown to the
+              agent
+              {outcome.connectionId === null
+                ? '.'
+                : `. Connection ${outcome.connectionId} is ready.`}
+            </p>
+          </div>
+        </div>
+      </Shell>
+    );
+  }
+
+  const working = phase === FormPhase.Working;
+
+  return (
+    <Shell heading={payload.heading} purpose={payload.purpose}>
+      {payload.launch !== undefined ? (
+        <>
+          {payload.launch.hint !== undefined && (
+            <p className="text-body-1 text-ink-3">{payload.launch.hint}</p>
+          )}
+          <div className="flex flex-wrap items-center gap-2">
+            <Button
+              onClick={() => {
+                // `launchUrl` was derived from the host trust anchor above; the
+                // payload contributes only a validated same-origin path.
+                globalThis.open(launchUrl, '_blank', 'noopener,noreferrer');
+              }}
+              className="gap-1.5"
+              disabled={working}
+            >
+              <ExternalLink className="h-4 w-4" />
+              {payload.launch.label}
+            </Button>
+            <Button
+              variant="outline"
+              onClick={handleCheckStatus}
+              disabled={working}
+            >
+              {working && <Loader2 className="mr-1 h-4 w-4 animate-spin" />}
+              I&apos;ve finished — check
+            </Button>
+          </div>
+        </>
+      ) : (
+        <>
+          {payload.fields.length === 0 && (
+            <Notice tone="warn" title="No form fields were declared">
+              This connector declares no onboarding form. Submitting will ask
+              the service, which is the authority on whether that is allowed.
+            </Notice>
+          )}
+          <SchemaForm
+            fields={payload.fields}
+            values={values}
+            onChange={setValues}
+            disabled={working}
+            {...(showFieldErrors ? { errors } : {})}
+          />
+          <div className="flex items-center gap-2">
+            <Button onClick={handleSubmit} disabled={working}>
+              {working && <Loader2 className="mr-1 h-4 w-4 animate-spin" />}
+              {payload.submitLabel ?? 'Submit securely'}
+            </Button>
+          </div>
+        </>
+      )}
+
+      {serviceError !== null && (
+        <Notice tone="error" title="The service rejected this">
+          {serviceError}
+        </Notice>
+      )}
+    </Shell>
+  );
+}
+
+function Shell({
+  heading,
+  purpose,
+  children,
+}: Readonly<{
+  heading?: string;
+  purpose: string;
+  children: ReactNode;
+}>): ReactElement {
+  return (
+    <div className="h-full overflow-auto">
+      <div className="mx-auto max-w-2xl space-y-4 p-6">
+        <div className="space-y-1">
+          <h2 className="text-subtitle font-semibold text-ink">
+            {heading ?? 'Secure request'}
+          </h2>
+          {purpose.length > 0 && (
+            <p className="text-body-1 text-ink-2">{purpose}</p>
+          )}
+          <p className="flex items-center gap-1.5 text-caption text-ink-3">
+            <ShieldCheck className="h-3.5 w-3.5" />
+            Sent straight to the service with your own sign-in. The agent never
+            sees what you type.
+          </p>
+        </div>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+function Notice({
+  tone,
+  title,
+  children,
+}: Readonly<{
+  tone: 'error' | 'warn';
+  title: string;
+  children: ReactNode;
+}>): ReactElement {
+  return (
+    <div
+      role="alert"
+      className={cn(
+        'flex items-start gap-2 rounded-md border p-3',
+        tone === 'error'
+          ? 'border-destructive/40 bg-destructive/10'
+          : 'border-rule bg-paper-elev',
+      )}
+    >
+      <AlertTriangle
+        className={cn(
+          'mt-0.5 h-4 w-4 shrink-0',
+          tone === 'error' ? 'text-destructive' : 'text-ink-3',
+        )}
+      />
+      <div className="space-y-0.5">
+        <p
+          className={cn(
+            'text-body-1 font-medium',
+            tone === 'error' ? 'text-destructive' : 'text-ink',
+          )}
+        >
+          {title}
+        </p>
+        <p
+          className={cn(
+            'text-body-1',
+            tone === 'error' ? 'text-destructive/90' : 'text-ink-3',
+          )}
+        >
+          {children}
+        </p>
+      </div>
+    </div>
+  );
+}

package/src/vista/surfaces/HtmlSurface.tsx

@@ -0,0 +1,43 @@
+/**
+ * `SurfaceKind.Html` — the "render anything, safely" surface.
+ *
+ * It draws through the promoted {@link CustomUiFrame}: an opaque-origin,
+ * `allow-scripts`-only sandbox iframe with a `<meta>` CSP of
+ * `default-src 'none'; script-src <pinned>; style-src 'unsafe-inline';
+ * base-uri 'none'; form-action 'none'`.
+ *
+ * Two forms, one frame:
+ *   • `{ document }` — untrusted, agent-authored HTML. `script-src 'none'`, and
+ *     the frame is mounted with {@link NO_CUSTOM_UI_INTENTS}: it can render, and
+ *     it can do NOTHING else. This is what an agent's `html` tab uses.
+ *   • `{ compiledOutput, integrity }` — a server-compiled, SRI-pinned chunk.
+ *     `script-src '<sha384-…>'` executes exactly those bytes and nothing else.
+ *
+ * A surface that wants intents (App Forge's runtime views) mounts
+ * `CustomUiFrame` directly with its own closed set; the generic `html` TAB
+ * deliberately grants none — an agent-authored document must not be able to
+ * drive the host.
+ */
+
+import { NO_CUSTOM_UI_INTENTS } from '../html/custom-ui-intents';
+import { CustomUiFrame } from '../html/CustomUiFrame';
+
+import type { VistaHtmlPayload } from '../vista-payloads';
+import type { ReactElement } from 'react';
+
+export function HtmlSurface(payload: VistaHtmlPayload): ReactElement {
+  const content =
+    'document' in payload
+      ? { document: payload.document }
+      : { compiledOutput: payload.compiledOutput, integrity: payload.integrity };
+  const styleCss = 'document' in payload ? undefined : payload.styleCss;
+  return (
+    <CustomUiFrame
+      content={content}
+      intents={NO_CUSTOM_UI_INTENTS}
+      title="Rendered view"
+      className="h-full p-2"
+      {...(styleCss === undefined ? {} : { styleCss })}
+    />
+  );
+}

package/src/vista/surfaces/TableSurface.tsx

@@ -0,0 +1,99 @@
+/**
+ * `SurfaceKind.Table` — generic columns + rows, the universal "show me
+ * structured records" surface.
+ *
+ * Presentation only: no sorting model, no paging, no cell semantics. A cell
+ * value that is not a primitive is JSON-serialised rather than dropped, so a
+ * nested value is visible instead of silently blank.
+ */
+import type { VistaTablePayload } from '../vista-payloads';
+import type { ReactElement } from 'react';
+
+
+function cellText(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'object') {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+
+export function TableSurface({
+  columns,
+  rows,
+}: Readonly<VistaTablePayload>): ReactElement {
+  return (
+    <div style={{ height: '100%', overflow: 'auto' }}>
+      <table
+        style={{
+          width: '100%',
+          borderCollapse: 'collapse',
+          fontSize: 12.5,
+        }}
+      >
+        <thead>
+          <tr>
+            {columns.map((column) => (
+              <th
+                key={column}
+                style={{
+                  position: 'sticky',
+                  top: 0,
+                  textAlign: 'left',
+                  padding: '8px 12px',
+                  background: 'hsl(var(--paper-elev))',
+                  borderBottom: '1px solid hsl(var(--rule))',
+                  color: 'hsl(var(--ink-3))',
+                  fontWeight: 600,
+                  whiteSpace: 'nowrap',
+                }}
+              >
+                {column}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row, rowIndex) => (
+            <tr
+              // Rows carry no identity in the generic contract; position is the
+              // only stable key available.
+               
+              key={rowIndex}
+            >
+              {columns.map((column, columnIndex) => (
+                <td
+                  key={column}
+                  style={{
+                    padding: '7px 12px',
+                    borderBottom: '1px solid hsl(var(--rule) / 0.6)',
+                    color: 'hsl(var(--ink-2))',
+                    verticalAlign: 'top',
+                  }}
+                >
+                  {cellText(row[columnIndex])}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      {rows.length === 0 && (
+        <div
+          style={{
+            padding: 24,
+            textAlign: 'center',
+            fontSize: 12.5,
+            color: 'hsl(var(--ink-4))',
+          }}
+        >
+          No rows.
+        </div>
+      )}
+    </div>
+  );
+}