@declarion/react 0.1.64 → 0.1.67

package/README.md

@@ -12,6 +12,38 @@ pnpm add @declarion/react
 pnpm add react react-dom
 ```
 
+## Subpath exports
+
+| Import | Purpose |
+|---|---|
+| `@declarion/react` | Main React entry — components, hooks, types |
+| `@declarion/react/styles.css` | Pre-compiled Tailwind output; import once at the SPA root |
+| `@declarion/react/vite` | Node-only Vite plugin — opt into client staleness handling at build time |
+
+## Vite plugin: build identity for client staleness handling
+
+The SDK ships with a tiny Vite plugin that emits `bundle-fingerprint.txt` next to `index.html` after every production build. The Declarion server reads it at boot and folds it into the build identity stamped on every `/api/*` response (`X-Declarion-Version`). The SDK's built-in version watcher detects drift on every API response, on focus/online/60s probe, and either silently invalidates the schema query (schema-only changes) or prompts the user to reload (asset/binary changes). Cross-tab coordination via `BroadcastChannel`.
+
+Add the plugin to your consumer app's `vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { declarionFingerprintPlugin } from "@declarion/react/vite";
+
+export default defineConfig({
+  plugins: [react(), declarionFingerprintPlugin()],
+});
+```
+
+That's it — there is no client API to wire by hand. The version watcher mounts itself inside `<App>`, the response-header observer is built into `apiFetch`, and the toast slot reuses the existing Sonner `<Toaster/>`. The plugin works in every Declarion deployment mode (local SDK link, npm-pinned, prebuilt prod image) since it runs at consumer build time regardless of where the SDK itself comes from.
+
+Consumers that haven't adopted the plugin yet degrade gracefully: the server logs once at boot, falls back to binary-only drift detection, and the rest of the system continues working — drift still gets detected, just classified more conservatively as "asset/binary" so the user gets a reload prompt rather than a silent invalidation.
+
+Browser support requires `BroadcastChannel` for cross-tab coordination — Chrome 54+, Firefox 38+, Safari 15.4+. In environments without it, in-tab detection still works; cross-tab fan-out is silently skipped.
+
+See [`docs/architecture.md`](https://github.com/disciplinedware/declarion/blob/main/docs/architecture.md) (section "Build identity & client staleness handling") for the full design rationale, fingerprint composition, RFC 7232 details (auth-variant ETag, weak-ETag handling), and the no-persistence invariant that prevents reload loops.
+
 ## License
 
 MIT. See `LICENSE`.

package/dist-lib/api/agents.d.ts

@@ -10,6 +10,7 @@ export type AgentContentBlock = {
 } | {
     type: "tool_result";
     id: string;
+    name?: string;
     output: unknown;
     is_error?: boolean;
 } | {
@@ -38,6 +39,14 @@ export type AgentContentBlock = {
 } | {
     type: "system";
     reason: string;
+} | {
+    type: "decision";
+    tool_use_id?: string;
+    tool_code: string;
+    decision: "approved" | "rejected";
+    decided_by?: string;
+    decided_at?: string;
+    note?: string;
 };
 export interface AgentMessage {
     id: string;
@@ -46,6 +55,7 @@ export interface AgentMessage {
     role: AgentRole;
     content: AgentContentBlock[];
     created_at: string;
+    streaming?: boolean;
 }
 export type AgentInvocationStatus = "proposed" | "pending_approval" | "approved" | "rejected" | "running" | "succeeded" | "failed" | "canceled" | "interrupted";
 export interface AgentToolInvocation {
@@ -62,13 +72,15 @@ export interface AgentToolInvocation {
         edits?: Record<string, unknown>;
     };
     result?: unknown;
-    audit_ref?: string;
+    audit_operation_id?: string;
+    reason?: string;
+    confidence?: number;
 }
 export type AgentConversationStatus = "active" | "canceling" | "interrupted" | "closed";
 export interface AgentConversation {
     id: string;
     tenant_id: string;
-    user_id: string;
+    created_by?: string;
     agent_code: string;
     agent_version?: string;
     title?: string;
@@ -84,9 +96,16 @@ export interface AgentConversation {
     catalog_snapshot?: unknown;
     active_instance?: string;
 }
-export declare function sendMessage(text: string, seq: number, conversationId?: string, context?: Record<string, unknown>): Promise<AgentMessage>;
+export declare function createConversation(input: {
+    agent_code?: string;
+    context?: Record<string, unknown>;
+}): Promise<AgentConversation>;
+export declare function sendMessage(text: string, conversationId: string, _seq?: number): Promise<AgentMessage>;
+export declare function sendElicitResponse(conversationId: string, _seq: number | undefined, toolUseId: string, data: Record<string, unknown>): Promise<AgentMessage>;
 export declare function approveInvocation(id: string, edits?: Record<string, unknown>): Promise<void>;
 export declare function rejectInvocation(id: string, note?: string): Promise<void>;
 export declare function cancelConversation(id: string): Promise<void>;
 export declare function listConversations(): Promise<AgentConversation[]>;
+export declare function rerunMessageTurn(conversationId: string): Promise<void>;
+export declare function listPendingInvocations(conversationId: string): Promise<AgentToolInvocation[]>;
 export declare function loadHistory(conversationId: string): Promise<AgentMessage[]>;

package/dist-lib/api/auth-redirect.d.ts

@@ -0,0 +1,3 @@
+export declare function sanitizeRedirectPath(value: string | null | undefined): string;
+export declare function loginPathForRedirectPath(value: string | null | undefined): string;
+export declare function loginPathForCurrentLocation(): string;

package/dist-lib/api/auth.d.ts

@@ -9,3 +9,17 @@ export declare function createTenant(code: string, name: string): Promise<Tenant
 export declare function logout(): Promise<void>;
 export declare function listSSOProviders(tenantCode?: string): Promise<SSOProvider[]>;
 export declare function ssoAuthorizeUrl(slug: string, tenantCode?: string, redirect?: string): string;
+/**
+ * Impersonation client surface. Each call dispatches through
+ * POST /api/actions/{code} like every other auth handler. The server
+ * sets / clears the impersonation cookies via the LoginResult
+ * HTTPCustomizer; the client receives the public response shape
+ * (user / tenant / expires_at) and reloads the auth context.
+ */
+export interface ImpersonationStartResponse extends LoginResponse {
+    impersonation_session_id: string;
+    session_expires_at: string;
+}
+export declare function impersonationStart(targetUserId: string, reason: string, durationMinutes?: number): Promise<ImpersonationStartResponse>;
+export declare function impersonationStop(): Promise<LoginResponse>;
+export declare function impersonationRevoke(sessionId: string): Promise<void>;

package/dist-lib/api/client.d.ts

@@ -1,9 +1,22 @@
+/** Signals that auth.refresh failed terminally (refresh cookie missing, token
+ *  expired/reused, session revoked). Callers MUST stop retrying and route the
+ *  user back to /login — retrying produces an infinite 401/4xx storm against
+ *  the rate-limited refresh endpoint. Distinct from generic network errors so
+ *  useSSE can branch on it. */
+export declare class RefreshDeadError extends Error {
+    status: number;
+    constructor(status: number);
+}
 export declare function ensureRefresh(): Promise<void>;
 type PersistentAuthFailureHandler = () => void;
 /** Replace the handler invoked on persistent 401. Intended for tests
  *  and non-browser consumers. Returns the previous handler so callers
  *  can restore it if needed. */
 export declare function setPersistentAuthFailureHandler(h: PersistentAuthFailureHandler): PersistentAuthFailureHandler;
+/** Returns the currently registered persistent-auth-failure handler. useSSE
+ *  reads this lazily so a setPersistentAuthFailureHandler() call from a test
+ *  is observed by the SSE retry loop without re-importing the module. */
+export declare function getPersistentAuthFailureHandler(): PersistentAuthFailureHandler;
 export declare function apiFetch<T>(path: string, options?: RequestInit): Promise<T>;
 export declare function callHandler<R = unknown>(code: string, args?: unknown): Promise<R>;
 export {};

package/dist-lib/api/events.d.ts

@@ -2,8 +2,25 @@ export type SSEEvent = {
     type: "entity_changed";
     entity: string;
     ids: string[];
+    objects?: Array<{
+        object_id?: string;
+        pk?: Record<string, string>;
+    }>;
     action: "created" | "updated" | "deleted" | "restored";
 } | {
     type: "session_refresh";
 };
+export declare const agentBus: EventTarget;
+export declare const AGENT_FRAME_EVENT = "agent-frame";
+export declare const AGENT_MESSAGE_CHANGED_EVENT = "agent-message-changed";
+export interface AgentFrameDetail {
+    convId: string;
+    kind: string;
+    turnId?: string;
+    payload?: Record<string, unknown>;
+}
+export declare function emitAgentFrame(detail: AgentFrameDetail): void;
+export declare class SSEAuthError extends Error {
+    constructor();
+}
 export declare function streamEvents(signal?: AbortSignal): AsyncGenerator<SSEEvent>;

package/dist-lib/components/agents/AgentChatPanel.d.ts

@@ -2,5 +2,6 @@ export interface AgentChatPanelProps {
     open: boolean;
     onClose: () => void;
     context?: string;
+    title?: string;
 }
-export declare function AgentChatPanel({ open, onClose, context }: AgentChatPanelProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AgentChatPanel({ open, onClose, context, title }: AgentChatPanelProps): import("react/jsx-runtime").JSX.Element | null;

package/dist-lib/components/fields/RichTextField.d.ts

@@ -0,0 +1,2 @@
+import type { FieldRendererProps } from "./index";
+export declare function RichTextField(props: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/fields/index.d.ts

@@ -2,6 +2,7 @@ import type { EntityField } from "../../types/schema";
 export type RefsMap = Record<string, Record<string, Record<string, unknown>>>;
 export interface FieldRendererProps {
     field: EntityField;
+    entityCode?: string;
     fieldName: string;
     value: unknown;
     mode: "display" | "edit";

package/dist-lib/components/file-widgets/CircleImage.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function CircleImage(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/DocumentCard.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function DocumentCard(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/FileList.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function FileList(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/Grid.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function Grid(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/ImageWidget.d.ts

@@ -0,0 +1,12 @@
+import { formatBytes } from "./upload";
+import type { FileWidgetProps } from "./types";
+export interface ImageWidgetVisualConfig {
+    shape: "square" | "circle" | "wide";
+    aspectRatio?: string;
+    width?: string;
+}
+export interface ImageWidgetInternalProps extends FileWidgetProps {
+    visual: ImageWidgetVisualConfig;
+}
+export declare function ImageWidget(props: ImageWidgetInternalProps): import("react/jsx-runtime").JSX.Element;
+export { formatBytes };

package/dist-lib/components/file-widgets/LabeledSlots.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function LabeledSlots(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/SquareImage.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function SquareImage(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/WideBanner.d.ts

@@ -0,0 +1,2 @@
+import type { FileWidgetProps } from "./types";
+export declare function WideBanner(props: FileWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/file-widgets/builtins.d.ts

@@ -0,0 +1 @@
+export declare function registerBuiltinFileWidgets(): void;

package/dist-lib/components/file-widgets/cropper.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+export interface CropperOptions {
+    aspectRatio?: number;
+    file: File;
+}
+export interface CropperResult {
+    blob: Blob;
+    filename: string;
+}
+export type ImageCropper = (opts: CropperOptions) => Promise<CropperResult>;
+export declare function setImageCropper(c: ImageCropper | null): void;
+export declare function getImageCropper(): ImageCropper;
+export declare function setCropperRenderer(fn: ((node: ReactNode) => void) | null): void;
+export declare function getCropperRenderer(): ((node: ReactNode) => void) | null;

package/dist-lib/components/file-widgets/draft-scope.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+export interface DraftEntry {
+    fileId: string;
+    discard: () => Promise<void> | void;
+}
+export interface FileDraftScopeApi {
+    registerDraft(entry: DraftEntry): void;
+    unregisterDraft(fileId: string): void;
+    hasDraft(fileId: string): boolean;
+    flushAllDrafts(): Promise<void>;
+    markCommitted(fileId: string): void;
+}
+export declare function FileDraftScope({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useFileDraftScope(): FileDraftScopeApi;
+export declare function useDraftRegistration(): {
+    register: (fileId: string, discard: () => Promise<void> | void) => void;
+    unregister: (fileId: string) => void;
+    markCommitted: (fileId: string) => void;
+    isDraft: (fileId: string) => boolean;
+};

package/dist-lib/components/file-widgets/helpers.d.ts

@@ -0,0 +1,12 @@
+import type { HydratedFile } from "./types";
+export interface FocalPoint {
+    x: number;
+    y: number;
+}
+export declare function resolveFileAltText(file: HydratedFile | null, alt: string | undefined, fallback: string): string;
+export declare function previewFileURL(file: HydratedFile): string | undefined;
+export declare function downloadFileURL(file: HydratedFile): string | undefined;
+export declare function preferredListThumbnailURL(file: HydratedFile | null, preferredDerivationKey?: string): string | undefined;
+export declare function readFocalPoint(file: HydratedFile | null): FocalPoint | null;
+export declare function focalPointObjectPosition(point: FocalPoint | null): string | undefined;
+export declare function withFocalPoint(file: HydratedFile, point: FocalPoint): HydratedFile;

package/dist-lib/components/file-widgets/host.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+import type { Entity } from "../../types/schema";
+import type { FileFieldDef, FileFieldValue } from "../../types/files";
+import type { RefsMap } from "../../components/fields";
+export declare function getEntityFileField(entity: Pick<Entity, "files">, fieldName: string): FileFieldDef | undefined;
+export declare function getFileFieldValue(record: Record<string, unknown>, fieldName: string): FileFieldValue;
+export declare function getSchemaFieldValue(entity: Pick<Entity, "fields" | "files">, record: Record<string, unknown>, fieldName: string): unknown;
+export declare function serializeSchemaFieldValue(entity: Pick<Entity, "fields" | "files">, fieldName: string, value: unknown): unknown;
+export declare function resolveSchemaFieldLabel(entity: Pick<Entity, "fields" | "files">, fieldName: string, entities?: Record<string, Entity>): string;
+export declare function renderSchemaField(props: {
+    entity: Pick<Entity, "fields" | "files">;
+    entityCode?: string;
+    fieldName: string;
+    record: Record<string, unknown>;
+    mode: "display" | "edit";
+    onChange?: (value: unknown) => void;
+    refs?: RefsMap;
+    disabled?: boolean;
+}): ReactNode;

package/dist-lib/components/file-widgets/index.d.ts

@@ -0,0 +1,16 @@
+export { SquareImage } from "./SquareImage";
+export { CircleImage } from "./CircleImage";
+export { WideBanner } from "./WideBanner";
+export { Grid } from "./Grid";
+export { DocumentCard } from "./DocumentCard";
+export { FileList } from "./FileList";
+export { LabeledSlots } from "./LabeledSlots";
+export { registerFileWidget, getFileWidget, hasFileWidget, __resetFileWidgetRegistryForTests, } from "./registry";
+export { getEntityFileField, getFileFieldValue, getSchemaFieldValue, serializeSchemaFieldValue, resolveSchemaFieldLabel, renderSchemaField, } from "./host";
+export { buildFileFieldPatch, buildFilesPayload, collectCommittedFileIds, } from "./payload";
+export { uploadFile, discardFile, validateClientSide, formatBytes, UploadError, } from "./upload";
+export { setImageCropper, getImageCropper, setCropperRenderer, getCropperRenderer, } from "./cropper";
+export type { ImageCropper, CropperOptions, CropperResult, } from "./cropper";
+export { FileDraftScope, useFileDraftScope, useDraftRegistration, } from "./draft-scope";
+export type { FileDraftScopeApi, DraftEntry, } from "./draft-scope";
+export type { FileFieldDef, FileFieldDisplay, FileFieldMode, FileWidget, FileWidgetProps, HydratedFile, UploadProgress, UploadedFile, } from "./types";

package/dist-lib/components/file-widgets/payload.d.ts

@@ -0,0 +1,21 @@
+import type { Entity } from "../../types/schema";
+import type { FileFieldDef, FileFieldValue } from "../../types/files";
+export interface FileSetItem {
+    file_id: string;
+    filename?: string;
+    slot?: string;
+    position?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface FileFieldPatch {
+    clear?: true;
+    set?: FileSetItem[];
+}
+export declare function buildFileFieldPatch(field: FileFieldDef, value: FileFieldValue): FileFieldPatch;
+export declare function buildFilesPayload(opts: {
+    entity: Pick<Entity, "files"> & Partial<Pick<Entity, "fields">>;
+    formData: Record<string, unknown>;
+    record: Record<string, unknown> | undefined;
+    isNew: boolean;
+}): Record<string, FileFieldPatch>;
+export declare function collectCommittedFileIds(payload: Record<string, FileFieldPatch>): string[];

package/dist-lib/components/file-widgets/registry.d.ts

@@ -0,0 +1,5 @@
+import type { FileWidget } from "./types";
+export declare function registerFileWidget(code: string, widget: FileWidget): void;
+export declare function getFileWidget(code: string): FileWidget | undefined;
+export declare function hasFileWidget(code: string): boolean;
+export declare function __resetFileWidgetRegistryForTests(): void;

package/dist-lib/components/file-widgets/types.d.ts

@@ -0,0 +1,15 @@
+import type { FileFieldDef, FileFieldDisplay, FileFieldMode, FileFieldValue, HydratedFile, UploadProgress, UploadedFile } from "../../types/files";
+export type { FileFieldDef, FileFieldDisplay, FileFieldMode, FileFieldValue, HydratedFile, UploadProgress, UploadedFile, };
+export interface FileWidgetProps {
+    field: FileFieldDef;
+    fieldName: string;
+    entityCode?: string;
+    value: FileFieldValue;
+    mode: "display" | "edit";
+    onChange?: (next: FileFieldValue) => void;
+    disabled?: boolean;
+    alt?: string;
+    uploadFieldCode?: string;
+    uploadSlotCode?: string;
+}
+export type FileWidget = React.ComponentType<FileWidgetProps>;

package/dist-lib/components/file-widgets/upload.d.ts

@@ -0,0 +1,25 @@
+import type { UploadProgress, UploadedFile } from "./types";
+export interface UploadOptions {
+    file: File;
+    entityCode?: string;
+    fieldCode?: string;
+    slotCode?: string;
+    onProgress?: (p: UploadProgress) => void;
+    signal?: AbortSignal;
+}
+export declare class UploadError extends Error {
+    code: string;
+    status: number;
+    constructor(status: number, code: string, message: string);
+}
+export interface UploadEnvelope {
+    status: string;
+    result: UploadedFile;
+}
+export declare function uploadFile(opts: UploadOptions): Promise<UploadedFile>;
+export declare function discardFile(fileId: string): Promise<void>;
+export declare function validateClientSide(file: File, accepts: string[] | undefined, maxBytes: number | undefined): {
+    code: string;
+    message: string;
+} | null;
+export declare function formatBytes(n: number): string;

package/dist-lib/components/file-widgets/value.d.ts

@@ -0,0 +1,4 @@
+import type { FileFieldValue, HydratedFile } from "./types";
+export declare function isHydratedFile(value: unknown): value is HydratedFile;
+export declare function singleFileFromValue(value: FileFieldValue): HydratedFile | null;
+export declare function fileArrayFromValue(value: FileFieldValue): HydratedFile[];

package/dist-lib/components/layout/ImpersonationBanner.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sticky top-of-viewport banner shown for the entire duration of an
+ * impersonation session (principle 8: "UI signals impersonation loudly").
+ * Never dismissable. Real user, target identity, expiry countdown, and
+ * an explicit "End session" button are always visible.
+ *
+ * Color is driven by the `--impersonation-accent` CSS variable in
+ * globals.css. The body[data-impersonation-destructive] flip is wired
+ * separately by ImpersonationFrame so the banner + frame stay in lockstep.
+ */
+export declare function ImpersonationBanner(): import("react/jsx-runtime").JSX.Element | null;

package/dist-lib/components/layout/ImpersonationFrame.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Fixed 4px viewport overlay frame that surrounds every route. Visible
+ * for the duration of an impersonation session (principle 8). The
+ * pointer-events:none guarantees the frame never blocks clicks.
+ *
+ * Color comes from --impersonation-accent (amber by default). When
+ * impersonation.allow_destructive=true, this component sets a body
+ * attribute that flips the variable to red across the banner, chip,
+ * and frame in lockstep (one CSS variable, no parallel state).
+ */
+export declare function ImpersonationFrame(): import("react/jsx-runtime").JSX.Element | null;

package/dist-lib/components/layout/ImpersonationStartModal.d.ts

@@ -0,0 +1,22 @@
+interface Props {
+    /** Open state controlled by the caller. */
+    open: boolean;
+    /** Target user the admin is about to impersonate. */
+    targetUserId: string;
+    targetUserLabel?: string;
+    /** Closes the modal without dispatching. Caller resets state. */
+    onClose: () => void;
+    /**
+     * Called after the start mutation succeeds. Useful for closing the
+     * modal and navigating; auth state is rehydrated by the hook itself.
+     */
+    onStarted?: () => void;
+}
+/**
+ * Reason modal for impersonation.start. Enforces a minimum reason
+ * length (server-side param impersonation.require_reason_min_length,
+ * default 10) before submitting. The "Duration" input is optional and
+ * is capped server-side by impersonation.max_duration_minutes.
+ */
+export declare function ImpersonationStartModal({ open, targetUserId, targetUserLabel, onClose, onStarted }: Props): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist-lib/components/layout/TenantChip.d.ts

@@ -4,6 +4,14 @@ export interface TenantChipProps {
     tenants: Tenant[];
     onSwitch: (tenant: Tenant) => void;
     busy?: boolean;
+    /**
+     * When true, the chip is disabled with a tooltip explaining why.
+     * Used during impersonation: cross-tenant targeting at start is
+     * supported, but mid-session tenant switching is undefined and
+     * locked (plan §"Cross-tenant impersonation").
+     */
+    locked?: boolean;
+    lockedReason?: string;
 }
 interface EnvTone {
     fg: string;
@@ -13,5 +21,5 @@ interface EnvTone {
     darkBg?: string;
 }
 export declare function envTone(env?: TenantEnv): EnvTone;
-export declare function TenantChip({ tenant, tenants, onSwitch, busy }: TenantChipProps): import("react/jsx-runtime").JSX.Element;
+export declare function TenantChip({ tenant, tenants, onSwitch, busy, locked, lockedReason }: TenantChipProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist-lib/components/list/QuickPeek.d.ts

@@ -1,16 +1,23 @@
 import { type ReactNode } from "react";
-import { type Action, type Screen, type EntityField } from "../../types/schema";
+import { type Action, type Entity, type EntityField, type Screen } from "../../types/schema";
 import type { RefsMap } from "../../components/fields";
-export interface QuickPeekFieldSpec {
+export interface QuickPeekRegularFieldSpec {
     key: string;
     label: string;
-    /** Entity field metadata; drives type-specific display + edit renderers. */
+    kind: "field";
     field: EntityField;
-    /** Read-only when the schema forbids edits, RBAC denies write, or the
-     *  field is primary/auto/computed/ref. */
     readOnly?: boolean;
 }
+export interface QuickPeekFileFieldSpec {
+    key: string;
+    label: string;
+    kind: "file";
+    readOnly?: boolean;
+}
+export type QuickPeekFieldSpec = QuickPeekRegularFieldSpec | QuickPeekFileFieldSpec;
 export interface QuickPeekProps<R extends Record<string, unknown> = Record<string, unknown>> {
+    entity: Pick<Entity, "fields" | "files">;
+    entityCode?: string;
     record: R;
     title: string;
     recordId?: string;
@@ -35,7 +42,7 @@ export interface QuickPeekProps<R extends Record<string, unknown> = Record<strin
     /** Fires once per explicit user commit — never on keystroke. */
     onSave?: (next: R) => void;
 }
-export declare function QuickPeek<R extends Record<string, unknown>>({ record, title, recordId, avatarName, fields, refs, screen, actions, executeAction, onClose, onOpen, onSave, }: QuickPeekProps<R>): import("react/jsx-runtime").JSX.Element;
+export declare function QuickPeek<R extends Record<string, unknown>>({ entity, entityCode, record, title, recordId, avatarName, fields, refs, screen, actions, executeAction, onClose, onOpen, onSave, }: QuickPeekProps<R>): import("react/jsx-runtime").JSX.Element;
 export interface QEFieldProps {
     label: string;
     children: ReactNode;

package/dist-lib/components/pages/SmartDetailPage.d.ts

@@ -1,5 +1,5 @@
 interface SmartDetailPageProps {
     screenCode: string;
 }
-export declare function SmartDetailPage({ screenCode }: SmartDetailPageProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function SmartDetailPage({ screenCode }: SmartDetailPageProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist-lib/components/pages/SmartListPage.d.ts

@@ -25,5 +25,5 @@ export declare function resolveDetailHref(list: {
 } | undefined, allScreens: Record<string, {
     route?: string;
 }> | undefined): string | null;
-export declare function SmartListPage({ screenCode }: SmartListPageProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function SmartListPage({ screenCode }: SmartListPageProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist-lib/components/primitives/Fields.d.ts

@@ -1,4 +1,4 @@
-import type { CSSProperties, InputHTMLAttributes, ReactNode } from "react";
+import type { ButtonHTMLAttributes, CSSProperties, InputHTMLAttributes, ReactNode } from "react";
 export type FieldLabelProps = {
     children?: ReactNode;
     required?: boolean;
@@ -25,13 +25,13 @@ export type SelectOption = {
     value: string;
     label: ReactNode;
 };
-export type SelectProps = {
+export type SelectProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" | "onChange"> & {
     value?: string;
     options: SelectOption[];
     onChange: (v: string) => void;
     placeholder?: string;
 };
-export declare function Select({ value, options, onChange, placeholder }: SelectProps): import("react/jsx-runtime").JSX.Element;
+export declare function Select({ value, options, onChange, placeholder, ...rest }: SelectProps): import("react/jsx-runtime").JSX.Element;
 export type DateInputProps = {
     value?: string | null;
     onChange?: (v: string) => void;

package/dist-lib/components/primitives/MenuItem.d.ts

@@ -7,5 +7,6 @@ export type MenuItemProps = {
     kbd?: ReactNode;
     active?: boolean;
     divider?: boolean;
+    "data-testid"?: string;
 };
-export declare function MenuItem({ icon, children, onClick, danger, kbd, active, divider }: MenuItemProps): import("react/jsx-runtime").JSX.Element;
+export declare function MenuItem({ icon, children, onClick, danger, kbd, active, divider, "data-testid": dataTestId }: MenuItemProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/shell/CommandPalette.d.ts

@@ -14,5 +14,6 @@ export interface CommandPaletteProps {
     navigation?: NavNode[];
     screens?: Record<string, Screen>;
     includeAI?: boolean;
+    aiName?: string;
 }
-export declare function CommandPalette({ open, onClose, onAction, mode, navigation, screens, includeAI, }: CommandPaletteProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function CommandPalette({ open, onClose, onAction, mode, navigation, screens, includeAI, aiName, }: CommandPaletteProps): import("react/jsx-runtime").JSX.Element | null;