uidex 0.2.4 → 0.4.0

package/dist/react/index.d.ts

@@ -1,78 +1,227 @@
-type BorderStyle = 'solid' | 'dashed' | 'dotted';
-type LabelPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-type ButtonPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-interface UidexDefaults {
-    color?: string;
-    borderStyle?: BorderStyle;
-    borderWidth?: number;
-}
-interface UidexConfig {
-    defaults?: UidexDefaults;
-    colors?: Record<string, string>;
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType, ReactElement } from 'react';
+import { StoreApi } from 'zustand/vanilla';
+
+declare const ENTITY_KINDS: readonly ["route", "page", "feature", "widget", "region", "element", "primitive", "flow"];
+type EntityKind = (typeof ENTITY_KINDS)[number];
+type Scope = string;
+interface Location {
+    file: string;
+    line?: number;
+    column?: number;
 }
-type UidexKind = 'block' | 'component' | 'primitive';
-interface UidexLocation {
-    filePath: string;
-    line: number;
-    kind: UidexKind;
-    doc?: string;
-    scopes?: string[];
+interface EntityRef {
+    kind: EntityKind;
+    id: string;
 }
-type UidexMap = Record<string, UidexLocation[]>;
-interface PrimitiveEntry {
-    name: string;
-    filePath: string;
-    scope: string;
-    composes: string[];
-    usedBy: string[];
-    kind: 'primitive';
-}
-interface UidexPage {
-    dir: string;
-    content: string;
+interface Metadata {
+    name?: string;
     description?: string;
-    componentIds: string[];
-    rootId?: string;
+    acceptance?: string[];
+    notes?: string;
+    composes?: EntityRef[];
+    flows?: readonly string[];
+    features?: string[];
+    widgets?: string[];
 }
-interface UidexFeature {
-    dir: string;
-    content: string;
-    description?: string;
-    componentIds: string[];
+interface EntityWithMetaBase {
+    id: string;
+    loc?: Location;
+    scopes?: Scope[];
+    meta?: Metadata;
 }
-interface KeyboardShortcut {
-    key: string;
-    ctrlKey?: boolean;
-    shiftKey?: boolean;
-    altKey?: boolean;
-    metaKey?: boolean;
+interface Route {
+    kind: "route";
+    path: string;
+    page: string;
 }
-interface IngestConfig {
-    endpoint: string;
-    apiKey: string;
-    environment?: string;
-    appVersion?: string;
-    reporter?: {
-        email?: string;
-        name?: string;
-    };
-    metadata?: Record<string, string>;
-    captureConsole?: boolean;
-    captureNetwork?: boolean;
+interface FlowStep {
+    entityId: string;
+    action?: string;
 }
-type FeedbackResult = {
-    ok: true;
+interface Flow {
+    kind: "flow";
     id: string;
-    sequenceNumber: number;
+    loc: Location;
+    touches: string[];
+    steps: FlowStep[];
+}
+interface Page extends EntityWithMetaBase {
+    kind: "page";
+}
+interface Feature extends EntityWithMetaBase {
+    kind: "feature";
+}
+interface Widget extends EntityWithMetaBase {
+    kind: "widget";
+}
+interface Region extends EntityWithMetaBase {
+    kind: "region";
+}
+interface Element$1 extends EntityWithMetaBase {
+    kind: "element";
+}
+interface Primitive extends EntityWithMetaBase {
+    kind: "primitive";
+}
+type Entity = Route | Page | Feature | Widget | Region | Element$1 | Primitive | Flow;
+type EntityByKind<K extends EntityKind> = Extract<Entity, {
+    kind: K;
+}>;
+
+interface Registry {
+    add(entity: Entity): void;
+    get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
+    list<K extends EntityKind>(kind: K): ReadonlyArray<EntityByKind<K>>;
+    query(predicate: (entity: Entity) => boolean): Entity[];
+    byScope(scope: Scope): Entity[];
+    touchedBy(flowId: string): Entity[];
+}
+
+type ThemePreference = "light" | "dark" | "auto";
+type ResolvedTheme = "light" | "dark";
+interface ViewStackEntry {
+    id: string;
+    ref: EntityRef | null;
+}
+interface SessionSnapshot {
+    hover: EntityRef | null;
+    selection: EntityRef | null;
+    stack: ViewStackEntry[];
+    /** Sticky overlay highlight. Set by "Highlight Element" actions; cleared on Esc. */
+    pinnedHighlight: EntityRef | null;
+    inspectorActive: boolean;
+    theme: ThemePreference;
+    resolvedTheme: ResolvedTheme;
+    ingestActive: boolean;
+}
+interface SessionActions {
+    hover(ref: EntityRef | null): void;
+    select(ref: EntityRef | null): void;
+    /**
+     * Append a view onto the view stack. Pure: never resolves defaults.
+     */
+    pushStack(entry: ViewStackEntry): void;
+    /**
+     * Remove the top entry from the view stack. No-op when the stack is empty.
+     */
+    popStack(): void;
+    /**
+     * Empty the view stack.
+     */
+    clearStack(): void;
+    /**
+     * Open a view by id. If `ref` is omitted, the current `selection` is captured;
+     * pass `null` explicitly to open the view with no ref context. Thin wrapper
+     * around `pushStack`.
+     */
+    openView(id: string, ref?: EntityRef | null): void;
+    /**
+     * Clear the entire view stack. Thin wrapper around `clearStack`.
+     */
+    closeView(): void;
+    setInspectorActive(active: boolean): void;
+    toggleInspector(): void;
+    /** Pin the overlay to `ref` until `clearPinnedHighlight` is called. */
+    pinHighlight(ref: EntityRef): void;
+    clearPinnedHighlight(): void;
+    setTheme(theme: ThemePreference, resolved?: ResolvedTheme): void;
+    setIngest(active: boolean): void;
+}
+interface SessionState extends SessionSnapshot {
+    actions: SessionActions;
+}
+
+type SurfaceEvent = {
+    type: "TOGGLE_INSPECTOR";
+} | {
+    type: "OPEN_PALETTE";
+} | {
+    type: "PUSH_VIEW";
+    entry: ViewStackEntry;
+} | {
+    type: "POP_VIEW";
+} | {
+    type: "CLOSE";
+} | {
+    type: "ESC";
+} | {
+    type: "CMD_K";
+} | {
+    type: "SELECT";
+    ref: EntityRef | null;
+    entry: ViewStackEntry;
 } | {
-    ok: false;
-    error: string;
+    type: "SET_SELECTION";
+    ref: EntityRef | null;
+} | {
+    type: "HOVER";
+    ref: EntityRef;
+    element: HTMLElement | null;
+    color?: string | null;
+} | {
+    type: "UNHOVER";
+} | {
+    type: "PIN";
+    ref?: EntityRef;
+} | {
+    type: "UNPIN";
+} | {
+    type: "SET_THEME";
+    theme: ThemePreference;
+    resolvedTheme: ResolvedTheme;
+} | {
+    type: "SET_INGEST";
+    active: boolean;
 };
-type UidexTheme = 'dark' | 'light' | 'auto';
-type FeedbackType = 'bug' | 'feature' | 'improvement' | 'question';
-type FeedbackSeverity = 'low' | 'medium' | 'high' | 'critical';
+
+type SessionStore = StoreApi<SessionState> & {
+    send(event: SurfaceEvent): void;
+};
+
+type ConsoleLevel = "warn" | "error";
+interface ConsoleEntry {
+    level: ConsoleLevel;
+    message: string;
+    timestamp: string;
+}
+interface ConsoleCaptureOptions {
+    limit?: number;
+    target?: Console;
+    now?: () => Date;
+}
+interface ConsoleCapture {
+    start(): void;
+    stop(): void;
+    readonly isActive: boolean;
+    entries(): readonly ConsoleEntry[];
+    clear(): void;
+}
+
+interface NetworkEntry {
+    method: string;
+    url: string;
+    status: number;
+    timestamp: string;
+    error?: string;
+}
+interface NetworkCaptureOptions {
+    limit?: number;
+    target?: {
+        fetch?: typeof fetch;
+    };
+    now?: () => Date;
+}
+interface NetworkCapture {
+    start(): void;
+    stop(): void;
+    readonly isActive: boolean;
+    entries(): readonly NetworkEntry[];
+    clear(): void;
+}
+
 interface ConsoleLogEntry {
-    level: 'warn' | 'error';
+    level: "log" | "warn" | "error" | "info";
     message: string;
     timestamp: string;
 }
@@ -80,105 +229,530 @@ interface NetworkErrorEntry {
     url: string;
     method: string;
     status: number | null;
-    statusText: string;
+    statusText: string | null;
     timestamp: string;
 }
-interface FeedbackReport {
-    type: FeedbackType;
-    severity: FeedbackSeverity;
+interface Viewport {
+    width: number;
+    height: number;
+}
+interface SourceRef {
+    filePath: string;
+    line: number;
+}
+interface FeedbackSuggestedTarget {
+    integrationId: string;
+    targetConfig: Record<string, unknown>;
+}
+interface FeedbackPayload {
+    type: "bug" | "feature" | "improvement" | "question";
+    severity: "low" | "medium" | "high" | "critical";
     title?: string;
     description: string;
     componentId: string;
-    element: string | null;
-    sources: {
-        filePath: string;
-        line: number;
-    }[];
+    element?: string | null;
+    sources?: SourceRef[];
     url: string;
     path: string;
-    route: string | null;
-    timestamp: string;
-    pageTitle: string;
-    pageDescription?: string;
-    locale: string;
-    sessionId: string;
-    viewport: {
-        width: number;
-        height: number;
-    };
-    screen: {
-        width: number;
-        height: number;
-    };
-    userAgent: string;
-    screenshot?: string;
+    route?: string | null;
+    pageTitle?: string;
+    sessionId?: string;
     reporterEmail?: string;
     reporterName?: string;
+    timestamp: string;
+    viewport: Viewport;
+    screen: Viewport;
+    userAgent: string;
+    locale?: string;
     environment?: string;
     appVersion?: string;
-    metadata?: Record<string, string>;
     consoleLogs?: ConsoleLogEntry[];
     networkErrors?: NetworkErrorEntry[];
-    gitBranch?: string;
-    gitCommit?: string;
-    contextId?: string;
-}
-interface GitContext {
-    branch: string;
-    commit?: string;
-}
-
-interface UidexDevtoolsProps {
-    components?: UidexMap;
-    pages?: UidexPage[];
-    features?: UidexFeature[];
-    uiComponents?: PrimitiveEntry[];
-    config?: UidexConfig;
-    buttonPosition?: ButtonPosition;
-    /** Theme for the devtools widget. Default: 'auto'. */
-    theme?: UidexTheme;
-    disabled?: boolean;
-    onSelect?: (id: string) => void;
-    /** Keyboard shortcut to toggle inspect mode. Default: Shift+Cmd+U. Set to false to disable. */
-    inspectShortcut?: KeyboardShortcut | false;
-    /** Ingest configuration for submitting feedback to a server. */
-    ingest?: IngestConfig;
-    /** Called after feedback submission with the report and result. */
-    onSubmit?: (report: FeedbackReport, result: FeedbackResult) => void;
-}
-declare function UidexDevtools({ components, pages, features, uiComponents, config, buttonPosition, theme, disabled, onSelect, inspectShortcut, ingest, onSubmit, }: UidexDevtoolsProps): null;
-
-type DataProps = 'components' | 'pages' | 'features' | 'uiComponents';
-declare function createUidexDevtools(data: {
-    components: UidexMap;
-    pages?: UidexPage[];
-    features?: UidexFeature[];
-    uiComponents?: PrimitiveEntry[];
-}): {
-    (props: Omit<UidexDevtoolsProps, DataProps>): null;
-    displayName: string;
-};
+    metadata?: Record<string, string>;
+    screenshot?: string;
+    suggestedTarget?: FeedbackSuggestedTarget;
+}
+interface FeedbackExternalLink {
+    ok: boolean;
+    url?: string;
+    key?: string;
+    error?: string;
+}
+interface FeedbackResult {
+    id: string;
+    sequenceNumber: number;
+    externalLink?: FeedbackExternalLink;
+}
+interface IngestConfigIssue {
+    id: string;
+    key: string;
+    summary: string;
+    issueType: string;
+}
+interface IngestConfig {
+    hasJira: boolean;
+    integrationId?: string;
+    parentIssues?: IngestConfigIssue[];
+}
+/**
+ * Generic so third-party adapters (e.g. `uidex-cloud`) can plug in their own
+ * payload/result/integration shapes. SDK-bundled `cloud()` returns the
+ * defaulted form. `ViewContext.cloud` uses the fully-open variant; consumers
+ * that need the SDK shape narrow with `as CloudAdapter`.
+ */
+interface CloudAdapter<TPayload = FeedbackPayload, TResult = FeedbackResult, TIntegrations = {
+    getConfig(): Promise<IngestConfig>;
+    /**
+     * Synchronous read of the eagerly-fetched config. Returns `null` until the
+     * initial fetch resolves; views that need a sync answer (e.g. detail
+     * actions deciding whether to surface a Jira button) read this.
+     */
+    getCachedConfig(): IngestConfig | null;
+}> {
+    readonly feedback: {
+        submit(payload: TPayload): Promise<TResult>;
+    };
+    readonly integrations: TIntegrations;
+}
+
+interface IngestOptions {
+    captureConsole?: boolean;
+    captureNetwork?: boolean;
+    consoleLimit?: number;
+    networkLimit?: number;
+    consoleTarget?: ConsoleCaptureOptions["target"];
+    networkTarget?: NetworkCaptureOptions["target"];
+    now?: () => Date;
+}
+interface Ingest {
+    start(): void;
+    stop(): void;
+    readonly isActive: boolean;
+    readonly console: ConsoleCapture | null;
+    readonly network: NetworkCapture | null;
+}
 
-interface UidexOverlayProps {
-    target: HTMLElement | null;
+interface OverlayShowOptions {
+    label?: string;
     color?: string;
-    borderStyle?: BorderStyle;
+    padding?: number;
+    borderStyle?: string;
     borderWidth?: number;
-    colors?: Record<string, string>;
+    fillOpacity?: number;
+    backdrop?: boolean;
 }
-declare function UidexOverlay({ target, color, borderStyle, borderWidth, colors, }: UidexOverlayProps): null;
 
-declare function registerComponents(components: UidexMap): void;
-declare function getComponents(): UidexMap | null;
-declare function registerPages(pages: UidexPage[]): void;
-declare function getPages(): UidexPage[] | null;
-declare function registerFeatures(features: UidexFeature[]): void;
-declare function getFeatures(): UidexFeature[] | null;
-declare function registerGitContext(ctx: GitContext): void;
+type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
 
-declare function classNames(...classes: (string | undefined | null | false)[]): string;
-declare function getContrastColor(hexColor: string): string;
-declare function hexToRgba(hex: string, alpha: number): string;
-declare function resolveColor(color: string | undefined, colorMap?: Record<string, string>): string | undefined;
+type ViewSurface = ListSurface | DetailSurface | FormSurface | CustomSurface;
+interface ListSurface {
+    kind: "list";
+    id: string;
+    items: readonly ListItem[];
+    onSelect?(item: ListItem): void;
+    emptyLabel?: string;
+    defaultHighlight?: string;
+    filter?(item: ListItem, query: string): boolean;
+}
+interface ListItem {
+    value: string;
+    label: string;
+    subtitle?: string;
+    group?: string;
+    shortcut?: string;
+    /**
+     * When highlighted, the shell calls `ctx.highlight.show(preview)`.
+     * Cleared on unhighlight or view unmount.
+     */
+    preview?: EntityRef;
+    /** Renders a kind chip on the left. `entity.kind` drives icon + color. */
+    entityChip?: {
+        entity: Entity;
+        node?: Element | null;
+    };
+    /**
+     * Optional leading-icon factory used for non-entity rows (e.g. a palette
+     * "Feedback" command). Called per-render so the returned Node is fresh.
+     * The shell wraps whatever is returned in a rounded-square tile.
+     */
+    leading?: () => Node;
+    /** Raw data attribute tag appended to the row (for test/e2e hooks). */
+    tag?: string;
+    /** Contextual actions surfaced in the footer popup when this row is highlighted. */
+    actions?: readonly ShellAction[];
+}
+interface DetailSurface {
+    kind: "detail";
+    entityKind: EntityKind;
+    /** Registry lookup failed — renders the "not found" placeholder. */
+    notFound?: EntityRef;
+    /** Entity display name, rendered as the heading. */
+    title?: string;
+    subtitle?: DetailSubtitle;
+    actions?: readonly DetailAction[];
+    sections?: readonly DetailSection[];
+}
+interface DetailSubtitle {
+    rawId: string;
+    extra?: string;
+}
+interface DetailActionBase {
+    id: string;
+    label: string;
+    icon?: DetailActionIcon;
+    ariaLabel?: string;
+    hint?: string;
+    intent?: ShellActionIntent;
+}
+type DetailAction = (DetailActionBase & {
+    copy: string;
+}) | (DetailActionBase & {
+    scrollTo: string;
+}) | (DetailActionBase & {
+    push: {
+        id: string;
+        ref?: EntityRef | null;
+    };
+}) | (DetailActionBase & {
+    navigate: EntityRef;
+}) | (DetailActionBase & {
+    highlight: EntityRef;
+}) | (DetailActionBase & {
+    run: (ctx: DetailActionRunContext) => void | Promise<void>;
+});
+type DetailActionIcon = "copy" | "camera" | "message-circle-warning" | "chevron-down" | "highlighter" | "ticket-plus" | "view";
+interface DetailActionRunContext {
+    setLabel(next: string, durationMs?: number): void;
+}
+interface ResolvedFlowStep {
+    ordinal: number;
+    entity: Entity;
+    action?: string;
+}
+type DetailSection = {
+    id: "description";
+    text: string;
+} | {
+    id: "acceptance";
+    items: readonly string[];
+} | {
+    id: "composes";
+    label: string;
+    entities: readonly Entity[];
+    filterable?: boolean;
+} | {
+    id: "used-by";
+    label: string;
+    entities: readonly Entity[];
+    filterable?: boolean;
+} | {
+    id: "flows";
+    flows: readonly Flow[];
+    filterable?: boolean;
+} | {
+    id: "touches";
+    entities: readonly Entity[];
+    filterable?: boolean;
+} | {
+    id: "steps";
+    steps: readonly ResolvedFlowStep[];
+    filterable?: boolean;
+} | {
+    id: "routes";
+    paths: readonly string[];
+    filterable?: boolean;
+};
+interface FormSurface {
+    kind: "form";
+    id: string;
+    fields: readonly FormField[];
+    submit: FormSubmit;
+    initial?: Record<string, FormValue>;
+    /**
+     * Optional Standard Schema (Zod v4, Valibot, ArkType, etc.) run against the
+     * collected form values before `submit.onSubmit`. On failure, issues are
+     * routed to the matching `<FieldError>` and submission is skipped.
+     */
+    schema?: StandardSchemaV1<Record<string, unknown>>;
+    /**
+     * Promise resolving to a base64 screenshot data URL. When provided, the
+     * form renderer shows a thumbnail preview above the fields.
+     */
+    screenshotPreview?: Promise<string | null>;
+}
+/**
+ * Minimal StandardSchemaV1 surface — kept inline so the SDK doesn't need a
+ * type-level dep on any specific validator package.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+type StandardSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardSchemaIssue>;
+};
+interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }>;
+}
+interface FormSubmit {
+    label: string;
+    onSubmit: (values: Record<string, FormValue>) => FormSubmitResult | void | Promise<FormSubmitResult | void>;
+}
+type FormSubmitResult = {
+    status: "success";
+    message?: string;
+    link?: {
+        url: string;
+        label?: string;
+    };
+    resetFields?: readonly string[];
+} | {
+    status: "error";
+    message: string;
+    /** Per-field error messages keyed by field `name`. */
+    fieldErrors?: Record<string, string>;
+};
+type FormValue = string | boolean;
+interface FormFieldBase {
+    name: string;
+    label: string;
+}
+type FormField = (FormFieldBase & {
+    kind: "select";
+    options: readonly {
+        value: string;
+        label: string;
+    }[];
+    required?: boolean;
+    value?: string;
+}) | (FormFieldBase & {
+    kind: "text";
+    placeholder?: string;
+    required?: boolean;
+    value?: string;
+}) | (FormFieldBase & {
+    kind: "email";
+    placeholder?: string;
+    required?: boolean;
+    value?: string;
+}) | (FormFieldBase & {
+    kind: "textarea";
+    placeholder?: string;
+    required?: boolean;
+    rows?: number;
+    value?: string;
+}) | (FormFieldBase & {
+    kind: "checkbox";
+    value?: boolean;
+});
+interface CustomSurface {
+    kind: "custom";
+    render: (ctx: ViewContext, root: HTMLElement) => Cleanup | void;
+}
+
+interface ViewPalette {
+    label: string;
+    group?: string;
+    /**
+     * Leading-icon factory rendered as a rounded-square tile on the palette
+     * row. Called fresh per render (so a returned SVG isn't reparented).
+     */
+    icon?: () => Node;
+    shortcut?: string;
+}
+interface ViewDirectory {
+    list(): readonly View[];
+    recents(): readonly EntityRef[];
+    favorites(): readonly EntityRef[];
+}
+interface ViewPushTarget {
+    id: string;
+    ref?: EntityRef | null;
+}
+interface HighlightController {
+    show(ref: EntityRef, opts?: OverlayShowOptions): void;
+    hide(): void;
+}
+interface ViewContext {
+    ref: EntityRef | null;
+    registry: Registry;
+    cloud: CloudAdapter<unknown, unknown, unknown> | null;
+    sdkCloud: CloudAdapter;
+    views: ViewDirectory;
+    /** Push a view onto the stack. Unregistered ids are a no-op. */
+    push: (target: ViewPushTarget) => void;
+    /** Pop the top view off the stack. No-op when the stack is empty. */
+    pop: () => void;
+    /** Clear the entire view stack. */
+    close: () => void;
+    /** Resolve the first view matching `ref` and push it onto the stack. */
+    navigate: (ref: EntityRef) => void;
+    /** Pin the overlay to `ref` until the user presses Esc. */
+    pinHighlight: (ref: EntityRef) => void;
+    /** Toggle favorite status for an entity ref. */
+    toggleFavorite: (ref: EntityRef) => void;
+    /** Check if an entity ref is favorited. */
+    isFavorite: (ref: EntityRef) => boolean;
+    /** Shell-owned search input. The shell dispatches its value into the active surface. */
+    searchInput: HTMLInputElement;
+    /** Drives the Surface's singleton overlay from inside a custom surface. */
+    highlight: HighlightController;
+    /** Snapshot of the current view stack (top-most last). */
+    getStack: () => readonly ViewStackEntry[];
+}
+interface ShellHint {
+    key: string;
+    label: string;
+}
+type ShellActionIntent = {
+    kind: "push";
+    viewId: string;
+    refKind?: EntityKind;
+} | {
+    kind: "pop";
+} | {
+    kind: "close";
+} | {
+    kind: "navigate";
+    refKind?: EntityKind;
+} | {
+    kind: "external";
+    describe: string;
+};
+interface ShellAction {
+    id: string;
+    label: string;
+    shortcut?: string;
+    icon?: () => Node;
+    perform: () => void | Promise<void>;
+    intent?: ShellActionIntent;
+}
+type Cleanup = () => void;
+interface View {
+    id: string;
+    matches?: (ref: EntityRef) => boolean;
+    palette?: ViewPalette;
+    title?: string | ((ctx: ViewContext) => string);
+    /** Show the shell search input when this view is on top. Default: true. */
+    searchable?: boolean;
+    hints?: ShellHint[] | ((ctx: ViewContext) => ShellHint[]);
+    actions?: (ctx: ViewContext) => ShellAction[];
+    /**
+     * Element focused when this view becomes the top of the stack. The shell
+     * falls back to the first focusable element in the host when omitted, or
+     * when the declared target has been removed from the host.
+     */
+    focusTarget?: (root: HTMLElement, ctx: ViewContext) => HTMLElement | null;
+    surface: (ctx: ViewContext) => ViewSurface;
+}
+
+interface PaletteShortcut {
+    /** The key value (e.g. "k", "j", ";"). Matched case-insensitively. */
+    key: string;
+    /** Require Cmd (Mac) / Ctrl (Win/Linux). Default: true. */
+    mod?: boolean;
+    /** Require Shift. Default: false. */
+    shift?: boolean;
+}
+
+interface ViewRegistrar {
+    register(view: View): void;
+    unregister(id: string): void;
+    list(): readonly View[];
+    get(id: string): View | undefined;
+    findMatch(ref: EntityRef): View | null;
+    navigate(ref: EntityRef): void;
+    recents(): readonly EntityRef[];
+    favorites(): readonly EntityRef[];
+    toggleFavorite(ref: EntityRef): void;
+    isFavorite(ref: EntityRef): boolean;
+}
+
+interface CreateUidexOptions {
+    theme?: ThemePreference;
+    resolvedTheme?: ResolvedTheme;
+    stylesheets?: string[];
+    initialCorner?: Corner;
+    /** Shown as a label at the start of the menu bar. */
+    appTitle?: string;
+    cloud?: CloudAdapter | null;
+    dev?: boolean;
+    /** Register bundled default views. Defaults to `true`. */
+    defaultViews?: boolean;
+    /** Additional views to register (after defaults). */
+    views?: readonly View[];
+    /**
+     * Override ingest behaviour. When `cloud` is non-null, ingest auto-enables
+     * (both console and network capture). Pass `null` to disable entirely, or
+     * an options object to override either channel.
+     */
+    ingest?: IngestOptions | null;
+    /** Keyboard shortcut for the command palette. Defaults to Cmd+K / Ctrl+K. */
+    shortcut?: PaletteShortcut;
+}
+interface Uidex {
+    mount(target?: Element): void;
+    unmount(): void;
+    readonly registry: Registry;
+    readonly session: SessionStore;
+    readonly views: ViewRegistrar;
+    readonly cloud: CloudAdapter | null;
+    readonly ingest: Ingest | null;
+    readonly shadowRoot: ShadowRoot | null;
+}
+
+interface UidexProviderProps {
+    /**
+     * Pre-built uidex instance (e.g. the `uidex` export from `uidex.gen.ts`).
+     * When provided, `projectKey`, `cloud`, and `config` are ignored.
+     */
+    instance?: Uidex;
+    projectKey?: string;
+    cloud?: CloudAdapter | null;
+    config?: Omit<CreateUidexOptions, "cloud">;
+    children?: ReactNode;
+}
+declare function UidexProvider({ instance: externalInstance, projectKey, cloud, config, children, }: UidexProviderProps): react_jsx_runtime.JSX.Element;
+
+declare class UidexContextError extends Error {
+    constructor(hookName: string);
+}
+declare function useUidex(): Uidex;
+
+interface UidexMountProps {
+    className?: string;
+}
+declare function UidexMount({ className }: UidexMountProps): react_jsx_runtime.JSX.Element;
+
+interface ReactViewDef {
+    id: string;
+    matches?: (ref: EntityRef) => boolean;
+    palette?: ViewPalette;
+    component: ComponentType<{
+        ctx: ViewContext;
+    }>;
+}
+declare function createReactView(def: ReactViewDef): View;
+
+interface KindChipProps {
+    kind: EntityKind;
+    label?: string;
+    withKindName?: boolean;
+    className?: string;
+}
+declare function KindChip({ kind, label, withKindName, className, }: KindChipProps): ReactElement;
 
-export { type BorderStyle, type ButtonPosition, type FeedbackReport, type FeedbackResult, type FeedbackSeverity, type FeedbackType, type IngestConfig, type KeyboardShortcut, type LabelPosition, type PrimitiveEntry, type UidexConfig, type UidexDefaults, UidexDevtools, type UidexDevtoolsProps, type UidexFeature, type UidexLocation, type UidexMap, UidexOverlay, type UidexOverlayProps, type UidexPage, classNames, createUidexDevtools, getComponents, getContrastColor, getFeatures, getPages, hexToRgba, registerComponents, registerFeatures, registerGitContext, registerPages, resolveColor };
+export { KindChip, type KindChipProps, type ReactViewDef, UidexContextError, UidexMount, type UidexMountProps, UidexProvider, type UidexProviderProps, createReactView, useUidex };