@xemahq/ui-kernel 0.9.1 → 0.9.2

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

@@ -12,11 +12,15 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
   extractServiceMessage,
   readElicitationStatus,
+  resolveTrustedElicitationEndpoints,
+  resolveTrustedElicitationLaunchUrl,
   submitElicitationFields,
   VistaFormSubmitError,
+  VistaFormTransportConfigError,
 } from './elicitation-transport';
 
 const SERVICE_ORIGIN = 'https://connector-gateway.example.test';
+const API_BASE_URL = `${SERVICE_ORIGIN}/credential-elicitations`;
 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';
@@ -39,14 +43,128 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
+describe('trusted elicitation endpoint resolution', () => {
+  it('derives exact status and submit paths from the host trust anchor', () => {
+    expect(resolveTrustedElicitationEndpoints(API_BASE_URL, 'ref-1')).toEqual({
+      statusUrl: STATUS_URL,
+      submitUrl: SUBMIT_URL,
+    });
+  });
+
+  it.each([
+    ['relative', '/credential-elicitations'],
+    ['network-path', '//evil.example/credential-elicitations'],
+    ['scheme confusion', 'javascript:https://trusted.example'],
+    [
+      'authority confusion',
+      'https://trusted.example@evil.example/credential-elicitations',
+    ],
+    [
+      'query',
+      'https://trusted.example/credential-elicitations?next=https://evil.example',
+    ],
+    [
+      'fragment',
+      'https://trusted.example/credential-elicitations#https://evil.example',
+    ],
+    [
+      'path traversal',
+      'https://trusted.example/credential-elicitations/../evil',
+    ],
+    [
+      'encoded path traversal',
+      'https://trusted.example/credential-elicitations/%2e%2e/evil',
+    ],
+  ])('rejects %s base URL input', (_label, apiBaseUrl) => {
+    expect(() =>
+      resolveTrustedElicitationEndpoints(apiBaseUrl, 'ref-1'),
+    ).toThrow(VistaFormTransportConfigError);
+  });
+
+  it('requires HTTPS for a non-local service', () => {
+    expect(() =>
+      resolveTrustedElicitationEndpoints(
+        'http://api.example.test/credential-elicitations',
+        'ref-1',
+        'http://host.example.test:8080',
+      ),
+    ).toThrow(/Insecure elicitation HTTP/);
+  });
+
+  it('permits explicit loopback and same-host HTTP development', () => {
+    expect(
+      resolveTrustedElicitationEndpoints(
+        'http://localhost:3010/credential-elicitations',
+        'ref-1',
+        'http://localhost:8080',
+      ).statusUrl,
+    ).toBe('http://localhost:3010/credential-elicitations/ref-1');
+    expect(
+      resolveTrustedElicitationEndpoints(
+        'http://192.168.1.20:3010/credential-elicitations',
+        'ref-1',
+        'http://192.168.1.20:8080',
+      ).statusUrl,
+    ).toBe('http://192.168.1.20:3010/credential-elicitations/ref-1');
+  });
+
+  it.each(['.', '..', '../steal', 'a/b', '%2e%2e', 'réf'])(
+    'rejects unsafe ref %s before URL construction',
+    (ref) => {
+      expect(() =>
+        resolveTrustedElicitationEndpoints(API_BASE_URL, ref),
+      ).toThrow(VistaFormTransportConfigError);
+    },
+  );
+
+  it('keeps launch paths on the trusted origin and rejects authority/traversal', () => {
+    expect(
+      resolveTrustedElicitationLaunchUrl(
+        API_BASE_URL,
+        '/oauth/acme/authorize?flow=1',
+      ),
+    ).toBe(`${SERVICE_ORIGIN}/oauth/acme/authorize?flow=1`);
+
+    for (const path of [
+      'https://evil.example/steal',
+      '//evil.example/steal',
+      '/oauth/../steal',
+      '/oauth/%2e%2e/steal',
+      '/oauth\\..\\steal',
+      '/oauth/start#https://evil.example',
+    ]) {
+      expect(() =>
+        resolveTrustedElicitationLaunchUrl(API_BASE_URL, path),
+      ).toThrow(VistaFormTransportConfigError);
+    }
+  });
+
+  it('does not call fetch when the trusted base or ref is invalid', async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+    await expect(
+      submitElicitationFields({
+        apiBaseUrl:
+          'https://trusted.example@evil.example/credential-elicitations',
+        ref: '../steal',
+        accessToken: 'user-jwt',
+        fields: { apiKey: SECRET },
+      }),
+    ).rejects.toBeInstanceOf(VistaFormTransportConfigError);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
 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' } }),
+      jsonResponse(201, {
+        data: { submitted: true, ref: 'ref-1', connectionId: 'conn-9' },
+      }),
     );
 
     await submitElicitationFields({
-      submitUrl: SUBMIT_URL,
+      apiBaseUrl: API_BASE_URL,
       ref: 'ref-1',
       accessToken: 'user-jwt',
       fields: { apiKey: SECRET },
@@ -57,8 +175,11 @@ describe('submitElicitationFields', () => {
     expect(url).toBe(SUBMIT_URL);
     expect(new URL(url).origin).toBe(SERVICE_ORIGIN);
     expect(init.method).toBe('POST');
+    expect(init.redirect).toBe('error');
     // 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');
+    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 () => {
@@ -76,26 +197,36 @@ describe('submitElicitationFields', () => {
     );
 
     const outcome = await submitElicitationFields({
-      submitUrl: SUBMIT_URL,
+      apiBaseUrl: API_BASE_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(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' } }),
+      jsonResponse(201, {
+        data: { submitted: true, ref: 'ref-1', connectionId: 'conn-9' },
+      }),
     );
 
     await submitElicitationFields({
-      submitUrl: SUBMIT_URL,
+      apiBaseUrl: API_BASE_URL,
       ref: 'ref-1',
       accessToken: 'user-jwt',
       fields: { baseUrl: 'https://acme.example.com', apiKey: SECRET },
@@ -108,10 +239,25 @@ describe('submitElicitationFields', () => {
   });
 
   it('accepts a flat (un-enveloped) response body', async () => {
-    stubFetch(jsonResponse(200, { submitted: true, ref: 'ref-1', connectionId: 'conn-2' }));
+    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' });
+      submitElicitationFields({
+        apiBaseUrl: API_BASE_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 () => {
@@ -126,7 +272,7 @@ describe('submitElicitationFields', () => {
 
     // An empty field schema submits an empty map; the SERVICE is the authority.
     const promise = submitElicitationFields({
-      submitUrl: SUBMIT_URL,
+      apiBaseUrl: API_BASE_URL,
       ref: 'ref-1',
       accessToken: 'user-jwt',
       fields: {},
@@ -139,35 +285,67 @@ describe('submitElicitationFields', () => {
   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: {} }),
+      submitElicitationFields({
+        apiBaseUrl: API_BASE_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 } }));
+    stubFetch(
+      jsonResponse(200, {
+        data: { ref: 'ref-1', status: 'pending', connectionId: null },
+      }),
+    );
     await expect(
-      readElicitationStatus({ statusUrl: STATUS_URL, ref: 'ref-1', accessToken: 't' }),
+      readElicitationStatus({
+        apiBaseUrl: API_BASE_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' } }),
+      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' });
+      readElicitationStatus({
+        apiBaseUrl: API_BASE_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 fetchMock = stubFetch(
+      jsonResponse(200, { data: { ref: 'ref-1', status: 'pending' } }),
+    );
+    await readElicitationStatus({
+      apiBaseUrl: API_BASE_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');
+    expect(init.redirect).toBe('error');
+    expect((init.headers as Record<string, string>).Authorization).toBe(
+      'Bearer user-jwt',
+    );
   });
 });
 
@@ -175,11 +353,15 @@ 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');
+    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(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

@@ -3,8 +3,8 @@
 //
 // 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.
+// of a `fetch` to an endpoint derived from the HOST-CONFIGURED trusted
+// elicitation-service base URL, bearing the SUBJECT's own JWT.
 //
 // Three properties make "the agent cannot receive the value" structural:
 //
@@ -15,15 +15,17 @@
 //   • 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.
+//   • the payload carries only an opaque ref. It has NO network authority. This
+//     module validates the host-configured base URL and derives the exact
+//     status/submit paths before a bearer token or field value reaches fetch.
 //
 // 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';
+import { isValidVistaFormRef } from '../vista-payloads';
+
+import type { VistaFormOutcome } from '../vista-form-context';
 
 /** A non-2xx answer from the owning service, carrying its message verbatim. */
 export class VistaFormSubmitError extends Error {
@@ -36,6 +38,19 @@ export class VistaFormSubmitError extends Error {
   }
 }
 
+/** Invalid trusted-host transport configuration or unsafe path input. */
+export class VistaFormTransportConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'VistaFormTransportConfigError';
+  }
+}
+
+export interface TrustedElicitationEndpoints {
+  readonly statusUrl: string;
+  readonly submitUrl: string;
+}
+
 type UnknownRecord = Readonly<Record<string, unknown>>;
 
 function asRecord(value: unknown): UnknownRecord | null {
@@ -69,7 +84,9 @@ export function extractServiceMessage(body: unknown, status: number): string {
       : (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(' ');
+    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;
@@ -108,7 +125,10 @@ function toOutcome(body: unknown, ref: string): VistaFormOutcome | null {
 }
 
 /** The `Authorization`/`Content-Type` pair every request here carries. */
-function authHeaders(accessToken: string, json: boolean): Record<string, string> {
+function authHeaders(
+  accessToken: string,
+  json: boolean,
+): Record<string, string> {
   const headers: Record<string, string> = {
     Authorization: `Bearer ${accessToken}`,
     Accept: 'application/json',
@@ -117,6 +137,146 @@ function authHeaders(accessToken: string, json: boolean): Record<string, string>
   return headers;
 }
 
+function browserOrigin(): string | undefined {
+  return typeof globalThis.location === 'undefined'
+    ? undefined
+    : globalThis.location.origin;
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  return (
+    hostname === 'localhost' ||
+    hostname.endsWith('.localhost') ||
+    hostname === '127.0.0.1' ||
+    hostname === '[::1]'
+  );
+}
+
+/**
+ * Parse the host's deploy-time trust anchor. It must be a canonical absolute
+ * HTTP(S) URL without credentials/query/fragment. HTTPS is mandatory except
+ * for loopback or same-host HTTP when the page itself is also served over HTTP.
+ */
+function trustedApiBaseUrl(
+  raw: string,
+  activeBrowserOrigin: string | undefined,
+): URL {
+  if (raw.length === 0 || raw.trim() !== raw) {
+    throw new VistaFormTransportConfigError(
+      'The trusted elicitation API base URL is empty or contains whitespace.',
+    );
+  }
+
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new VistaFormTransportConfigError(
+      'The trusted elicitation API base URL must be absolute.',
+    );
+  }
+
+  if (
+    (url.protocol !== 'https:' && url.protocol !== 'http:') ||
+    url.username.length > 0 ||
+    url.password.length > 0 ||
+    url.search.length > 0 ||
+    url.hash.length > 0
+  ) {
+    throw new VistaFormTransportConfigError(
+      'The trusted elicitation API base URL must use HTTP(S) and contain no credentials, query, or fragment.',
+    );
+  }
+
+  const canonicalPath =
+    url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
+  const canonical = `${url.origin}${canonicalPath}`;
+  const suppliedWithoutOneTrailingSlash = raw.endsWith('/')
+    ? raw.slice(0, -1)
+    : raw;
+  if (suppliedWithoutOneTrailingSlash !== canonical) {
+    throw new VistaFormTransportConfigError(
+      'The trusted elicitation API base URL must be canonical and contain no traversal or ambiguous path.',
+    );
+  }
+
+  if (url.protocol === 'http:' && !isLoopbackHostname(url.hostname)) {
+    let page: URL | null = null;
+    if (activeBrowserOrigin !== undefined) {
+      try {
+        page = new URL(activeBrowserOrigin);
+      } catch {
+        page = null;
+      }
+    }
+    if (
+      page === null ||
+      page.protocol !== 'http:' ||
+      page.hostname !== url.hostname
+    ) {
+      throw new VistaFormTransportConfigError(
+        'Insecure elicitation HTTP is allowed only on loopback or the same host as an HTTP development page.',
+      );
+    }
+  }
+
+  return new URL(canonical);
+}
+
+/**
+ * Derive the only two authenticated endpoints from trusted host configuration
+ * plus one opaque path segment. Calling this directly remains safe even if a
+ * caller bypasses the surface-payload validator.
+ */
+export function resolveTrustedElicitationEndpoints(
+  apiBaseUrl: string,
+  ref: string,
+  activeBrowserOrigin: string | undefined = browserOrigin(),
+): TrustedElicitationEndpoints {
+  if (!isValidVistaFormRef(ref)) {
+    throw new VistaFormTransportConfigError(
+      'The elicitation reference is not a valid opaque base64url path segment.',
+    );
+  }
+  const base = trustedApiBaseUrl(apiBaseUrl, activeBrowserOrigin)
+    .toString()
+    .replace(/\/$/, '');
+  const statusUrl = `${base}/${ref}`;
+  return { statusUrl, submitUrl: `${statusUrl}/submit` };
+}
+
+/**
+ * Resolve an unauthenticated launch path under the SAME trusted service origin.
+ * Absolute/network-path URLs and dot-segment traversal fail closed.
+ */
+export function resolveTrustedElicitationLaunchUrl(
+  apiBaseUrl: string,
+  path: string,
+  activeBrowserOrigin: string | undefined = browserOrigin(),
+): string {
+  const base = trustedApiBaseUrl(apiBaseUrl, activeBrowserOrigin);
+  if (
+    !path.startsWith('/') ||
+    path.startsWith('//') ||
+    path.includes('\\') ||
+    path.includes('#')
+  ) {
+    throw new VistaFormTransportConfigError(
+      'The elicitation launch target must be a root-relative service path.',
+    );
+  }
+  const resolved = new URL(path, `${base.origin}/`);
+  if (
+    resolved.origin !== base.origin ||
+    `${resolved.pathname}${resolved.search}` !== path
+  ) {
+    throw new VistaFormTransportConfigError(
+      'The elicitation launch path contains traversal or an ambiguous encoding.',
+    );
+  }
+  return resolved.toString();
+}
+
 /**
  * POST the captured fields to the owning service.
  *
@@ -125,20 +285,30 @@ function authHeaders(accessToken: string, json: boolean): Record<string, string>
  * user reads.
  */
 export async function submitElicitationFields(args: {
-  readonly submitUrl: string;
+  readonly apiBaseUrl: string;
   readonly ref: string;
   readonly accessToken: string;
   readonly fields: Readonly<Record<string, string>>;
 }): Promise<VistaFormOutcome> {
-  const response = await fetch(args.submitUrl, {
+  const { submitUrl } = resolveTrustedElicitationEndpoints(
+    args.apiBaseUrl,
+    args.ref,
+  );
+  const response = await fetch(submitUrl, {
     method: 'POST',
     headers: authHeaders(args.accessToken, true),
     body: JSON.stringify({ fields: args.fields }),
     credentials: 'omit',
+    // A 307/308 could otherwise replay the credential body to a different
+    // origin. Authenticated elicitation endpoints must never redirect.
+    redirect: 'error',
   });
   const body = await readBody(response);
   if (!response.ok) {
-    throw new VistaFormSubmitError(response.status, extractServiceMessage(body, response.status));
+    throw new VistaFormSubmitError(
+      response.status,
+      extractServiceMessage(body, response.status),
+    );
   }
   const outcome = toOutcome(body, args.ref);
   if (outcome === null) {
@@ -158,18 +328,26 @@ export async function submitElicitationFields(args: {
  * Returns `null` while still pending — an explicit "not yet", never a guess.
  */
 export async function readElicitationStatus(args: {
-  readonly statusUrl: string;
+  readonly apiBaseUrl: string;
   readonly ref: string;
   readonly accessToken: string;
 }): Promise<VistaFormOutcome | null> {
-  const response = await fetch(args.statusUrl, {
+  const { statusUrl } = resolveTrustedElicitationEndpoints(
+    args.apiBaseUrl,
+    args.ref,
+  );
+  const response = await fetch(statusUrl, {
     method: 'GET',
     headers: authHeaders(args.accessToken, false),
     credentials: 'omit',
+    redirect: 'error',
   });
   const body = await readBody(response);
   if (!response.ok) {
-    throw new VistaFormSubmitError(response.status, extractServiceMessage(body, response.status));
+    throw new VistaFormSubmitError(
+      response.status,
+      extractServiceMessage(body, response.status),
+    );
   }
   return toOutcome(body, args.ref);
 }

package/src/vista/surfaces/file-surface-utils.ts

@@ -0,0 +1,62 @@
+import type { VistaFileEntry } from '../vista-payloads';
+
+interface FileExtMeta {
+  readonly color: string;
+  readonly tag: string;
+}
+
+const EXT_META: Readonly<Record<string, FileExtMeta>> = {
+  ts: { color: 'hsl(var(--info))', tag: 'TS' },
+  tsx: { color: 'hsl(var(--info))', tag: 'TSX' },
+  js: { color: 'hsl(var(--warning))', tag: 'JS' },
+  jsx: { color: 'hsl(var(--warning))', tag: 'JSX' },
+  json: { color: 'hsl(var(--ink-3))', tag: 'JSON' },
+  md: { color: 'hsl(var(--p-people))', tag: 'MD' },
+  css: { color: 'hsl(var(--p-sales))', tag: 'CSS' },
+  html: { color: 'hsl(var(--p-sales))', tag: 'HTML' },
+  yaml: { color: 'hsl(var(--ink-3))', tag: 'YAML' },
+  yml: { color: 'hsl(var(--ink-3))', tag: 'YAML' },
+};
+
+export function fileExtMeta(name: string): FileExtMeta {
+  if (/\.test\.[tj]sx?$/.test(name) || /\.spec\.[tj]sx?$/.test(name)) {
+    return { color: 'hsl(var(--success))', tag: 'TEST' };
+  }
+  const ext = name.split('.').pop() ?? '';
+  return (
+    EXT_META[ext] ?? {
+      color: 'hsl(var(--ink-4))',
+      tag: (ext || 'FILE').toUpperCase().slice(0, 4),
+    }
+  );
+}
+
+export interface VistaFileGroup {
+  readonly dir: string;
+  readonly files: readonly VistaFileEntry[];
+}
+
+function compareDirs(a: string, b: string): number {
+  if (a === '') return -1;
+  if (b === '') return 1;
+  return a.localeCompare(b);
+}
+
+export function groupFilesByFolder(
+  files: readonly VistaFileEntry[],
+): VistaFileGroup[] {
+  const groups = new Map<string, VistaFileEntry[]>();
+  for (const file of files) {
+    const slash = file.path.lastIndexOf('/');
+    const dir = slash < 0 ? '' : file.path.slice(0, slash);
+    const bucket = groups.get(dir);
+    if (bucket) bucket.push(file);
+    else groups.set(dir, [file]);
+  }
+  return [...groups.keys()].sort(compareDirs).map((dir) => ({
+    dir,
+    files: [...(groups.get(dir) ?? [])].sort((a, b) =>
+      a.path.localeCompare(b.path),
+    ),
+  }));
+}