@lumerahq/ui

React component library and utilities for building Lumera custom applications.

Installation

npm install @lumerahq/ui

Features

• Application Components - Agent chat surfaces, data tables, record sheets, and automation runner
• Data Table - Full-featured table with filtering, sorting, and pagination
• Bridge Module - Parent-iframe communication for embedded apps
• API Utilities - Lumera client with SQL, CRUD, file, and email operations
• Automation Runner - Start and monitor automation runs
• React Query Integration - Data fetching hooks

Usage

Styles

Import the package stylesheet once in the app entrypoint before rendering any @lumerahq/ui component:

import '@lumerahq/ui/styles.css';

This stylesheet is required for the shared Tailwind/shadcn theme variables, Inter font, and the agent chat's derived tokens and animations. It is not included automatically when importing from @lumerahq/ui/components, @lumerahq/ui/hooks, or @lumerahq/ui/lib.

The stylesheet defines theme tokens as CSS custom properties. Override them on :root, .dark, or a wrapper class to retheme the assistant without changing component code:

.my-assistant-theme {
  --brand: #2563eb;
  --primary: var(--brand);
  --ring: var(--brand);
  --primary-foreground: #ffffff;
  --background: #ffffff;
  --foreground: #111827;
  --card: #ffffff;
  --border: #d1d5db;
}

Components

import { AutomationRunner, DataTable, RecordSheet } from '@lumerahq/ui';

Record Audit Log

Build an app-native activity view from one globally ordered feed across up to 20 audited collections. Pass the same bare collection names used by record CRUD:

import { useRecordAuditLog, useRecordAuditLogSnapshot } from '@lumerahq/ui/hooks';

const audit = useRecordAuditLog({
  collections: ['invoices', 'payments'],
  recordId: selectedInvoiceId,
  event: 'updated',
});

const snapshot = useRecordAuditLogSnapshot({
  id: expandedEntry?.id,
  store: expandedEntry?.store,
  enabled: Boolean(expandedEntry?.has_snapshot),
});

The hook returns entries, current per-collection audit status, loading/error state, refresh, and cursor-based load-more state. Entries include stable collection and record identity fields plus event-scoped execution provenance (agent_id, session_id, request_id, run and causation ids) for links and custom rendering. The same recordId, agentId, sessionId, and causationId filters apply to every page and CSV export. Public helpers under @lumerahq/ui/lib support direct list/snapshot requests and a capped CSV export. A disabled collection can still have visible history; its status means only that future changes are not being captured.

changed_fields describes update events only. For created and deleted records, show the action itself and use the after or before snapshot for expanded detail. The actor identifies the human or service that initiated the work. The separate execution object identifies what performed this exact mutation, so a delegated agent write can retain both the human actor and the agent session that executed it. When a hook performs the mutation, execution.type and execution.id identify the hook while agent_id and session_id retain the upstream agent session, when present, and run_id retains an upstream automation or function run. Agent and session filters include these hook events. Webhook and anonymous app writes keep their distinct execution types instead of being reported as system work.

Agent Chat

AgentChat is the primary chat component as of 0.20. It renders a header with the agent's identity and activity, an empty state with suggested prompts, the transcript (reasoning line, grouped tool-step card, streamed markdown, error block with in-place Retry, compaction markers), and a composer with attachments, a per-turn Web search chip, and Stop. Use it for new chat UIs and move existing ones to it at the first opportunity. As of 0.20.1 AssistantChat, AssistantPage, and AssistantWidget are deprecated wrappers over it: existing apps get the new look without code changes, but the three will be removed in a later major, so migrate when you can. AssistantChat becomes AgentChat with the transport wrapped in withDataSync for onDataChange; AssistantPage becomes the page recipe below; AssistantWidget becomes the launcher recipe below.

import { useEffect, useMemo, useState } from 'react';
import {
  AgentChat,
  createLumeraAgentChatTransport,
  postReadyMessage,
  type AgentChatToolRenderer,
} from '@lumerahq/ui';
import '@lumerahq/ui/styles.css';

const toolRenderers: AgentChatToolRenderer[] = [
  {
    match: (tc) => tc.name === 'send_invoice',
    // "label · detail": the detail lands in the right-aligned mono column.
    summary: (tc) => {
      const input = tc.input as { invoiceId?: string };
      return `Sent invoice · ${input.invoiceId ?? ''}`.trim();
    },
    expandedView: (tc) => <pre>{tc.output ?? ''}</pre>,
  },
];

export function AppAssistant({ agentId }: { agentId: string }) {
  const transport = useMemo(() => createLumeraAgentChatTransport({ agentId }), [agentId]);
  // The host owns the session; New switches to a fresh one.
  const [sessionId, setSessionId] = useState(() => `session-${Date.now()}`);

  useEffect(() => {
    postReadyMessage();
  }, []);

  return (
    <div style={{ height: '100vh' }}>
      <AgentChat
        agentId={agentId}
        sessionId={sessionId}
        transport={transport}
        suggestions={['Summarize recent activity', 'Find records that need attention']}
        onNewChat={() => setSessionId(`session-${Date.now()}`)}
        features={{ attachments: true, webSearch: true }}
        renderers={{ toolRenderers }}
      />
    </div>
  );
}

The component fills its parent's height (min 360px). In an unsized parent it grows with the transcript, capped at the viewport height as a guard against unbounded growth. The cap does not account for content above the chat, so give the parent a height to fit it to the space it has. Colors, radii, and type come from the shared theme tokens (--primary, --radius, --font-sans, …). Pass accent (and accentForeground for text on a light accent) to recolour one chat, or override the tokens on :root, .dark, or a wrapper class to rebrand the whole app.

Keep the built-in header. It shows the agent's name and description, the Active/Idle dot, and New, and it tracks the runtime's state. Add controls with headerLeft and headerRight; set features.header: false only when the host chrome already provides all of that.

Session actions map to the runtime: New calls onNewChat (the host owns sessionId) and Retry on a failed turn uses transport.retry (POST /live/retry) to re-run it in place. The Web chip appears with features.webSearch and starts from the agent's configured web search setting, or webSearchDefault; the choice is sent per turn as web_search_enabled, and until one is known the field is omitted so the runtime keeps the agent's setting. When the runtime compacts context on its own mid-turn, the chat shows "Compacting context…" until it finishes and the transcript then carries a "Compacted" marker with the recap.

Deprecated in 0.20 (still exported, removed in a later major): ActivityStrip with ActivityStripItem / ActivityStripProps, encodeActivityLabels, summarizeActivityLabels, the appearance feature flag and AgentChatAppearance type, labels.emptyTitle, and statusText on custom Header renderers. AgentChat renders reasoning and tool steps itself, with its own reasoning line and tool-step card, and has one transcript appearance.

AgentChat does not list sessions itself; pair it with useAgentChatSessions() and SessionRail, and pass the chosen sessionId (page recipe below). sessionFilter on useAgentChatSessions scopes the visible session list and ignores a backend-selected active session that does not pass the predicate. It is a client-side presentation filter, not an authorization boundary.

Custom tool renderers are checked before the built-in renderer registry, so they can add support for custom tools or override how a built-in tool appears. A summary of the form Label · detail renders as a step row with the detail in the mono column; a leading emoji, if any, is dropped. Pass it to AgentChat as renderers={{ toolRenderers }}; the deprecated assistant surfaces take the same array through their toolRenderers prop.

Page: a session rail beside the chat

import { AgentChat, SessionRail, createLumeraAgentChatTransport, useAgentChatSessions } from '@lumerahq/ui';

export function AssistantRoute({ agentId }: { agentId: string }) {
  const transport = useMemo(() => createLumeraAgentChatTransport({ agentId }), [agentId]);
  const sessions = useAgentChatSessions({ agentId, transport, autoLoad: true });
  const [picked, setPicked] = useState<string>();
  const sessionId = picked ?? sessions.activeSessionId;
  const startNew = () => setPicked(`session-${Date.now()}`);

  return (
    <div className="flex h-screen">
      <SessionRail
        sessions={sessions.sessions}
        activeSessionId={sessionId}
        isLoading={sessions.isLoading}
        onSelect={setPicked}
        onNew={startNew}
        onRename={(id, name) => void sessions.renameSession(id, name)}
      />
      <AgentChat
        agentId={agentId}
        sessionId={sessionId}
        transport={transport}
        disabled={!sessionId}
        onNewChat={startNew}
        onTurnComplete={() => void sessions.loadSessions()}
        className="flex-1 rounded-none border-0 shadow-none"
      />
    </div>
  );
}

Launcher: a floating button that opens the chat

export function AssistantLauncher({ agentId }: { agentId: string }) {
  const transport = useMemo(() => createLumeraAgentChatTransport({ agentId }), [agentId]);
  const [open, setOpen] = useState(false);

  return (
    <>
      <button
        type="button"
        onClick={() => setOpen((value) => !value)}
        className="fixed right-5 bottom-5 rounded-full bg-foreground px-4 py-2 text-sm text-background"
      >
        {open ? 'Close' : 'Chat'}
      </button>
      {open && (
        <div className="fixed right-5 bottom-20 h-[min(640px,calc(100vh-7rem))] w-[440px] max-w-[calc(100vw-2.5rem)]">
          <AgentChat agentId={agentId} sessionId="support-current" transport={transport} />
        </div>
      )}
    </>
  );
}

API Utilities

import { pbSql, pbList, pbGet, pbCreate } from '@lumerahq/ui/lib';

// SQL queries
const result = await pbSql<{ id: string; name: string }>({
  sql: 'SELECT id, name FROM users WHERE active = true'
});

// CRUD operations
const items = await pbList<User>('users', { filter: JSON.stringify({ status: "active" }) });
const user = await pbGet<User>('users', 'user-id');

Shareable App Links

Always use getShareableAppUrl() for any URL a human will open (copy-link buttons, invite/share flows, email bodies, QR codes). Never use window.location.href — the app runs inside an iframe loaded from the backend's internal /_apps/{company}/{app}/ path, so window.location returns that iframe URL, not the Lumera shell URL in the user's browser tab. Sharing window.location.href produces broken links.

import { buildShareableAppUrl, getShareableAppUrl } from '@lumerahq/ui/lib';

// ✅ Correct
const shareUrl = getShareableAppUrl();
// -> https://your-company.lumerahq.dev/app/my-app/orders/123
// HashRouter apps retain their hash route:
// -> https://your-company.lumerahq.dev/app/my-app#/orders/123

// ✅ Correct for a different in-app route, such as an email/invite link
const invoiceUrl = buildShareableAppUrl('/invoices/123');
// Default template apps use hash routing; pass this when generating target links
// from a page where the current hash route cannot be detected.
const hashInvoiceUrl = buildShareableAppUrl('/invoices/123', {
  router: 'hash',
});

// ❌ WRONG — leaks the internal iframe URL
navigator.clipboard.writeText(window.location.href);
// -> https://your-company.lumerahq.dev/_apps/your-company/my-app/#/orders/123

Returns undefined until the bridge handshake completes; guard accordingly if you call it on first render.

File URLs

import { getDownloadUrl } from '@lumerahq/ui/lib';

const url = await getDownloadUrl(record.attachment.object_key);
// -> fresh presigned S3 URL suitable for links, new tabs, and iframe previews
//    (PDFs / images render inline; Content-Type is inferred when the stored
//    object metadata is missing or wrong).

Automation Runner

The helpers below call Lumera's Automation APIs directly. Use them only in existing legacy_direct internal apps or builder tooling. In a functions_only app, call a project-owned API/HTTP Function that authorizes the viewer and inputs, starts the Automation server-side, and exposes a viewer-scoped status route. Do not poll /api/automation-runs from the app browser.

import { createRun, pollRun } from '@lumerahq/ui/lib';

const run = await createRun({
  // Bare external ID; the current project scope is resolved automatically.
  automationId: 'process-data',
  inputs: { param: 'value' },
});

const result = await pollRun(run.id);

Standalone Development

For developing outside of a Lumera iframe, create a .env.local file:

cp .env.example .env.local
# Edit .env.local with your credentials

Get your auth token by running lumera login and copying from .lumera/credentials.json.

License

MIT