@xemahq/ui-kernel 0.9.0 → 0.9.1

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>
+  );
+}

package/src/vista/surfaces/UrlSurface.tsx

@@ -0,0 +1,40 @@
+/**
+ * `SurfaceKind.Url` — a live external URL inside mock browser chrome.
+ *
+ * The chrome (traffic lights + address bar + reload) is `UrlPreviewChrome`,
+ * lifted out of the thin session workspace; the device bezel is the shared
+ * `PreviewDeviceFrame`. The frame itself is `sandbox="allow-scripts
+ * allow-forms"` and NEVER `allow-same-origin`: a previewed app runs in its own
+ * opaque origin and cannot reach the host's DOM, cookies or tokens.
+ */
+
+import { PreviewDeviceFrame } from '../../ui/primitives/preview-device-frame';
+import { UrlPreviewChrome } from '../../ui/primitives/url-preview-chrome';
+
+import type { VistaUrlPayload } from '../vista-payloads';
+import type { ReactElement } from 'react';
+
+export function UrlSurface({
+  url,
+  device = 'desktop',
+  reloadNonce,
+}: Readonly<VistaUrlPayload>): ReactElement {
+  return (
+    <UrlPreviewChrome url={url}>
+      <PreviewDeviceFrame device={device}>
+        <iframe
+          // Remounting on a nonce change is how a reload is requested without
+          // reaching into the frame (which we cannot do: it is cross-origin).
+          key={`${url}::${device}::${reloadNonce ?? 0}`}
+          title={`Preview of ${url}`}
+          src={url}
+          // NEVER add allow-same-origin — it would dissolve the origin boundary
+          // between the previewed app and the host.
+          sandbox="allow-scripts allow-forms"
+          loading="lazy"
+          style={{ height: '100%', width: '100%', border: 0 }}
+        />
+      </PreviewDeviceFrame>
+    </UrlPreviewChrome>
+  );
+}

package/src/vista/surfaces/blob-surfaces.tsx

@@ -0,0 +1,129 @@
+/**
+ * The binary-bodied first-party surfaces: `image`, `media`, `pdf`.
+ *
+ * Each accepts an already-resolved `url` OR a workspace `path` resolved through
+ * the host {@link VistaFileSource}.
+ *
+ * SECURITY — `pdf`: the bytes are frequently UNTRUSTED (user uploads,
+ * agent-produced artifacts). The PDF is painted onto a `<canvas>` by pdf.js
+ * (the shared `PdfPreview`) — NO iframe, NO script execution — never embedded
+ * in the browser's own viewer. `PdfPreview` is lazy-imported so pdf.js
+ * (~1.9 MB) stays out of any bundle that never opens a PDF; that dynamic import
+ * is the whole point of the `@xemahq/ui-kernel/pdf` subpath.
+ */
+import { Suspense, lazy, type ReactElement, type ReactNode } from 'react';
+
+import { VistaFileUrl } from '../vista-file-source';
+
+import type { VistaBlobPayload } from '../vista-payloads';
+
+const PdfPreview = lazy(() =>
+  import('../../pdf').then((m) => ({ default: m.PdfPreview })),
+);
+
+/** Render from an inline url, or resolve the path first. */
+function BlobBody({
+  payload,
+  render,
+}: Readonly<{
+  payload: VistaBlobPayload;
+  render: (url: string) => ReactNode;
+}>): ReactElement {
+  if (payload.url !== undefined) return <>{render(payload.url)}</>;
+  // `validateBlobPayload` guarantees exactly one of url/path.
+  return <VistaFileUrl path={payload.path as string} render={render} />;
+}
+
+export function ImageSurface(payload: VistaBlobPayload): ReactElement {
+  return (
+    <BlobBody
+      payload={payload}
+      render={(url) => (
+        <div
+          style={{
+            height: '100%',
+            display: 'grid',
+            placeItems: 'center',
+            padding: 16,
+            overflow: 'auto',
+          }}
+        >
+          <img
+            src={url}
+            alt={payload.alt ?? 'Preview'}
+            style={{ maxWidth: '100%', maxHeight: '100%', objectFit: 'contain' }}
+          />
+        </div>
+      )}
+    />
+  );
+}
+
+export function PdfSurface(payload: VistaBlobPayload): ReactElement {
+  return (
+    <BlobBody
+      payload={payload}
+      render={(url) => (
+        <Suspense
+          fallback={
+            <div
+              style={{
+                height: '100%',
+                display: 'grid',
+                placeItems: 'center',
+                fontSize: 12.5,
+                color: 'hsl(var(--ink-4))',
+              }}
+            >
+              Loading viewer…
+            </div>
+          }
+        >
+          <PdfPreview
+            url={url}
+            title={payload.alt ?? 'PDF preview'}
+            className="h-full w-full"
+          />
+        </Suspense>
+      )}
+    />
+  );
+}
+
+/**
+ * `media` — audio or video, chosen by `contentType`. The type is REQUIRED by the
+ * payload validator for this kind (see the registration): guessing between an
+ * `<audio>` and a `<video>` element from a URL would be a heuristic that fails
+ * on extension-less URLs.
+ */
+export function MediaSurface(payload: VistaBlobPayload): ReactElement {
+  const isAudio = (payload.contentType ?? '').startsWith('audio/');
+  return (
+    <BlobBody
+      payload={payload}
+      render={(url) => (
+        <div
+          style={{
+            height: '100%',
+            display: 'grid',
+            placeItems: 'center',
+            padding: 16,
+            background: 'hsl(var(--paper-sunk))',
+          }}
+        >
+          {isAudio ? (
+            // eslint-disable-next-line jsx-a11y/media-has-caption
+            <audio src={url} controls style={{ width: '100%', maxWidth: 520 }} />
+          ) : (
+            // eslint-disable-next-line jsx-a11y/media-has-caption
+            <video
+              src={url}
+              controls
+              style={{ maxWidth: '100%', maxHeight: '100%' }}
+            />
+          )}
+        </div>
+      )}
+    />
+  );
+}

package/src/vista/surfaces/elicitation-transport.spec.ts

@@ -0,0 +1,187 @@
+/**
+ * Guards the secure-elicitation transport — the ONE place a captured field
+ * value is read out of the `form` surface.
+ *
+ * These are the load-bearing proofs of Canopy §8.4: the value goes browser →
+ * service and the only thing that comes back out is `{ submitted, ref,
+ * connectionId }`. Runs under the host-web vitest mirror (this package carries
+ * no vitest dep).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  extractServiceMessage,
+  readElicitationStatus,
+  submitElicitationFields,
+  VistaFormSubmitError,
+} from './elicitation-transport';
+
+const SERVICE_ORIGIN = 'https://connector-gateway.example.test';
+const SUBMIT_URL = `${SERVICE_ORIGIN}/credential-elicitations/ref-1/submit`;
+const STATUS_URL = `${SERVICE_ORIGIN}/credential-elicitations/ref-1`;
+const SECRET = 'sk-live-DO-NOT-LEAK';
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function stubFetch(response: Response): ReturnType<typeof vi.fn> {
+  const fetchMock = vi.fn().mockResolvedValue(response);
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('submitElicitationFields', () => {
+  it('POSTs to the SERVICE origin directly — not a host-relative path', async () => {
+    const fetchMock = stubFetch(
+      jsonResponse(201, { data: { submitted: true, ref: 'ref-1', connectionId: 'conn-9' } }),
+    );
+
+    await submitElicitationFields({
+      submitUrl: SUBMIT_URL,
+      ref: 'ref-1',
+      accessToken: 'user-jwt',
+      fields: { apiKey: SECRET },
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(SUBMIT_URL);
+    expect(new URL(url).origin).toBe(SERVICE_ORIGIN);
+    expect(init.method).toBe('POST');
+    // The SUBJECT's own bearer — not a service token, not the agent's.
+    expect((init.headers as Record<string, string>).Authorization).toBe('Bearer user-jwt');
+  });
+
+  it('never hands a secret back to the caller, even when the service echoes it', async () => {
+    stubFetch(
+      jsonResponse(201, {
+        data: {
+          submitted: true,
+          ref: 'ref-1',
+          connectionId: 'conn-9',
+          // A hostile / careless service echoing the submission back.
+          fields: { apiKey: SECRET },
+          credentials: { apiKey: SECRET },
+        },
+      }),
+    );
+
+    const outcome = await submitElicitationFields({
+      submitUrl: SUBMIT_URL,
+      ref: 'ref-1',
+      accessToken: 'user-jwt',
+      fields: { apiKey: SECRET },
+    });
+
+    // The outcome is a FRESH object with exactly three keys.
+    expect(Object.keys(outcome).sort()).toEqual(['connectionId', 'ref', 'submitted']);
+    expect(outcome).toEqual({ submitted: true, ref: 'ref-1', connectionId: 'conn-9' });
+    expect(JSON.stringify(outcome)).not.toContain(SECRET);
+    expect(JSON.stringify(outcome)).not.toContain('apiKey');
+  });
+
+  it('round-trips a NON-secret field to the service body', async () => {
+    const fetchMock = stubFetch(
+      jsonResponse(201, { data: { submitted: true, ref: 'ref-1', connectionId: 'conn-9' } }),
+    );
+
+    await submitElicitationFields({
+      submitUrl: SUBMIT_URL,
+      ref: 'ref-1',
+      accessToken: 'user-jwt',
+      fields: { baseUrl: 'https://acme.example.com', apiKey: SECRET },
+    });
+
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(JSON.parse(init.body as string)).toEqual({
+      fields: { baseUrl: 'https://acme.example.com', apiKey: SECRET },
+    });
+  });
+
+  it('accepts a flat (un-enveloped) response body', async () => {
+    stubFetch(jsonResponse(200, { submitted: true, ref: 'ref-1', connectionId: 'conn-2' }));
+    await expect(
+      submitElicitationFields({ submitUrl: SUBMIT_URL, ref: 'ref-1', accessToken: 't', fields: {} }),
+    ).resolves.toEqual({ submitted: true, ref: 'ref-1', connectionId: 'conn-2' });
+  });
+
+  it("surfaces the backend's empty-schema 400 as a usable message", async () => {
+    stubFetch(
+      jsonResponse(400, {
+        statusCode: 400,
+        message:
+          'No credential form is declared for a connection to "ACME" — there is nothing to validate ' +
+          'the submitted values against, so they cannot be stored.',
+      }),
+    );
+
+    // An empty field schema submits an empty map; the SERVICE is the authority.
+    const promise = submitElicitationFields({
+      submitUrl: SUBMIT_URL,
+      ref: 'ref-1',
+      accessToken: 'user-jwt',
+      fields: {},
+    });
+
+    await expect(promise).rejects.toBeInstanceOf(VistaFormSubmitError);
+    await expect(promise).rejects.toThrow(/No credential form is declared/);
+  });
+
+  it('refuses a 2xx that does not report the elicitation as submitted', async () => {
+    stubFetch(jsonResponse(200, { data: { ref: 'ref-1' } }));
+    await expect(
+      submitElicitationFields({ submitUrl: SUBMIT_URL, ref: 'ref-1', accessToken: 't', fields: {} }),
+    ).rejects.toThrow(/did not report the elicitation as submitted/);
+  });
+});
+
+describe('readElicitationStatus', () => {
+  it('returns null while pending — an explicit "not yet", never a guess', async () => {
+    stubFetch(jsonResponse(200, { data: { ref: 'ref-1', status: 'pending', connectionId: null } }));
+    await expect(
+      readElicitationStatus({ statusUrl: STATUS_URL, ref: 'ref-1', accessToken: 't' }),
+    ).resolves.toBeNull();
+  });
+
+  it('settles on the service-reported submitted status', async () => {
+    stubFetch(
+      jsonResponse(200, { data: { ref: 'ref-1', status: 'submitted', connectionId: 'conn-3' } }),
+    );
+    await expect(
+      readElicitationStatus({ statusUrl: STATUS_URL, ref: 'ref-1', accessToken: 't' }),
+    ).resolves.toEqual({ submitted: true, ref: 'ref-1', connectionId: 'conn-3' });
+  });
+
+  it('GETs the service origin with the subject bearer', async () => {
+    const fetchMock = stubFetch(jsonResponse(200, { data: { ref: 'ref-1', status: 'pending' } }));
+    await readElicitationStatus({ statusUrl: STATUS_URL, ref: 'ref-1', accessToken: 'user-jwt' });
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(new URL(url).origin).toBe(SERVICE_ORIGIN);
+    expect(init.method).toBe('GET');
+    expect((init.headers as Record<string, string>).Authorization).toBe('Bearer user-jwt');
+  });
+});
+
+describe('extractServiceMessage', () => {
+  it('reads a string message, a message array, and a nested error message', () => {
+    expect(extractServiceMessage({ message: 'nope' }, 400)).toBe('nope');
+    expect(extractServiceMessage({ message: ['a', 'b'] }, 400)).toBe('a b');
+    expect(extractServiceMessage({ error: { message: 'deep' } }, 400)).toBe('deep');
+  });
+
+  it('never yields an empty string', () => {
+    expect(extractServiceMessage(null, 503)).toBe('The service rejected the submission (HTTP 503).');
+    expect(extractServiceMessage({ message: '' }, 500)).toBe(
+      'The service rejected the submission (HTTP 500).',
+    );
+  });
+});

package/src/vista/surfaces/elicitation-transport.ts

@@ -0,0 +1,175 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// The `form` surface's transport — browser → owning service, direct.
+//
+// This module is the ONLY code that ever reads a captured field value out of
+// the form surface, and it does exactly one thing with it: put it in the body
+// of a `fetch` to the ABSOLUTE service URL carried by the (already validated)
+// surface payload, bearing the SUBJECT's own JWT.
+//
+// Three properties make "the agent cannot receive the value" structural:
+//
+//   • the value is a PARAMETER, never a return: every exported function returns
+//     `VistaFormOutcome | null`, a closed scalar-only shape (see
+//     `../vista-form-host`). The values object is not reachable from any
+//     return, any thrown error, or any callback;
+//   • the response is PROJECTED, not passed through: `toOutcome` constructs a
+//     fresh object with exactly three keys, so a service that echoed a secret
+//     back could still not leak one through this boundary;
+//   • the URL is absolute and comes from the payload validator, which rejects
+//     anything that is not `http(s)://…` — there is no host-relative path, so
+//     the request cannot be aimed at the app's own BFF or the chat transport.
+//
+// Errors carry the SERVICE's message verbatim (that is how the backend's hard
+// 400 on an empty credential form becomes readable UI copy) and never the
+// request body.
+// ═══════════════════════════════════════════════════════════════════════════
+import type { VistaFormOutcome } from '../vista-form-host';
+
+/** A non-2xx answer from the owning service, carrying its message verbatim. */
+export class VistaFormSubmitError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'VistaFormSubmitError';
+  }
+}
+
+type UnknownRecord = Readonly<Record<string, unknown>>;
+
+function asRecord(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+/**
+ * Unwrap the platform `{ data: … }` envelope when present. Total: a flat body
+ * is returned as-is, so the transport works against either wire shape without
+ * a second code path.
+ */
+function unwrapEnvelope(body: unknown): UnknownRecord | null {
+  const record = asRecord(body);
+  if (record === null) return null;
+  const inner = asRecord(record.data);
+  return inner ?? record;
+}
+
+/**
+ * Best-effort extraction of the SERVICE's error message. Falls back to a
+ * status-derived sentence — never to an empty string, because an empty error is
+ * indistinguishable from success in the UI.
+ */
+export function extractServiceMessage(body: unknown, status: number): string {
+  const record = asRecord(body);
+  const candidate =
+    record === null
+      ? undefined
+      : (record.message ?? asRecord(record.error)?.message ?? record.error);
+  if (typeof candidate === 'string' && candidate.length > 0) return candidate;
+  if (Array.isArray(candidate)) {
+    const joined = candidate.filter((m): m is string => typeof m === 'string').join(' ');
+    if (joined.length > 0) return joined;
+  }
+  if (typeof body === 'string' && body.length > 0) return body;
+  return `The service rejected the submission (HTTP ${status}).`;
+}
+
+async function readBody(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type');
+  try {
+    if (contentType !== null && contentType.includes('application/json')) {
+      return await response.json();
+    }
+    return await response.text();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Project a service response onto {@link VistaFormOutcome}. Constructs a FRESH
+ * object with exactly three keys — nothing else from the response survives.
+ * Returns `null` when the service reports the elicitation is not settled.
+ */
+function toOutcome(body: unknown, ref: string): VistaFormOutcome | null {
+  const record = unwrapEnvelope(body);
+  if (record === null) return null;
+  const submitted =
+    record.submitted === true ||
+    (typeof record.status === 'string' && record.status === 'submitted');
+  if (!submitted) return null;
+  const connectionId =
+    typeof record.connectionId === 'string' && record.connectionId.length > 0
+      ? record.connectionId
+      : null;
+  return { submitted: true, ref, connectionId };
+}
+
+/** The `Authorization`/`Content-Type` pair every request here carries. */
+function authHeaders(accessToken: string, json: boolean): Record<string, string> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${accessToken}`,
+    Accept: 'application/json',
+  };
+  if (json) headers['Content-Type'] = 'application/json';
+  return headers;
+}
+
+/**
+ * POST the captured fields to the owning service.
+ *
+ * @throws {VistaFormSubmitError} on a non-2xx answer, carrying the service's
+ * own message so a hard 400 (e.g. "no credential form is declared") is what the
+ * user reads.
+ */
+export async function submitElicitationFields(args: {
+  readonly submitUrl: string;
+  readonly ref: string;
+  readonly accessToken: string;
+  readonly fields: Readonly<Record<string, string>>;
+}): Promise<VistaFormOutcome> {
+  const response = await fetch(args.submitUrl, {
+    method: 'POST',
+    headers: authHeaders(args.accessToken, true),
+    body: JSON.stringify({ fields: args.fields }),
+    credentials: 'omit',
+  });
+  const body = await readBody(response);
+  if (!response.ok) {
+    throw new VistaFormSubmitError(response.status, extractServiceMessage(body, response.status));
+  }
+  const outcome = toOutcome(body, args.ref);
+  if (outcome === null) {
+    throw new VistaFormSubmitError(
+      response.status,
+      'The service accepted the request but did not report the elicitation as submitted.',
+    );
+  }
+  return outcome;
+}
+
+/**
+ * Read the elicitation's current state. Used by the OAuth / app-install handoff,
+ * where completion happens in another window and the only signal available to
+ * this tab is the service's own record.
+ *
+ * Returns `null` while still pending — an explicit "not yet", never a guess.
+ */
+export async function readElicitationStatus(args: {
+  readonly statusUrl: string;
+  readonly ref: string;
+  readonly accessToken: string;
+}): Promise<VistaFormOutcome | null> {
+  const response = await fetch(args.statusUrl, {
+    method: 'GET',
+    headers: authHeaders(args.accessToken, false),
+    credentials: 'omit',
+  });
+  const body = await readBody(response);
+  if (!response.ok) {
+    throw new VistaFormSubmitError(response.status, extractServiceMessage(body, response.status));
+  }
+  return toOutcome(body, args.ref);
+}