uidex 0.2.4 → 0.3.0

package/dist/index.d.ts

@@ -1,78 +1,281 @@
-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 { StoreApi } from 'zustand/vanilla';
+import { IconNode } from 'lucide';
+
+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 Flow {
+    kind: "flow";
+    id: string;
+    loc: Location;
+    touches: string[];
+}
+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";
 }
-type FeedbackResult = {
-    ok: true;
+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;
+}>;
+type MetaEntityKind = Exclude<EntityKind, "route" | "flow">;
+declare function isMetaKind(kind: EntityKind): kind is MetaEntityKind;
+declare function entityKey(entity: Entity): string;
+declare class UnknownEntityKindError extends Error {
+    readonly kind: string;
+    constructor(kind: string);
+}
+declare function assertEntityKind(kind: string): asserts kind is EntityKind;
+
+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[];
+}
+declare function createRegistry(): Registry;
+
+interface KindStyleEntry {
+    icon: IconNode;
+    tone: string;
+    chip: string;
+    color: string;
+    label: string;
+}
+declare const KIND_STYLE: Record<EntityKind, KindStyleEntry>;
+
+declare function prettify(id: string): string;
+declare function displayName(entity: Entity, node?: Element | null): string;
+
+interface HighlightContext {
+    ref: EntityRef | null;
+    element: HTMLElement | null;
+    pinnedRef: EntityRef | null;
+    color: string | null;
+}
+
+type ThemePreference = "light" | "dark" | "auto";
+type ResolvedTheme = "light" | "dark";
+interface ViewStackEntry {
     id: string;
-    sequenceNumber: number;
+    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;
+} | {
+    type: "SET_SELECTION";
+    ref: EntityRef | null;
+} | {
+    type: "HOVER";
+    ref: EntityRef;
+    element: HTMLElement | null;
+    color?: string | null;
+} | {
+    type: "UNHOVER";
 } | {
-    ok: false;
-    error: string;
+    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;
+};
+interface SurfaceBindings {
+    mountInspector?: () => void;
+    destroyInspector?: () => void;
+    openActionsPopup?: () => void;
+    closePopup?: () => void;
+}
+interface HighlightBindings {
+    showOverlay?: (context: HighlightContext) => void;
+    hideOverlay?: () => void;
+    updateOverlay?: (context: HighlightContext) => void;
+}
+interface SessionBindings {
+    surface?: SurfaceBindings;
+    highlight?: HighlightBindings;
+}
+interface CreateSessionOptions extends Partial<SessionSnapshot> {
+    detectTheme?: () => ResolvedTheme;
+    /**
+     * Action implementations injected into the surface machine and its
+     * highlight child actor. Implementations may be closures that read from
+     * mutable refs filled in after `createSession` returns (e.g., the SDK's
+     * shell isn't available until `mount`).
+     */
+    bindings?: SessionBindings;
+}
+declare function resolveTheme(preference: ThemePreference, detect?: () => ResolvedTheme): ResolvedTheme;
+declare function createSession(options?: CreateSessionOptions): SessionStore;
+
+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;
+}
+declare function createConsoleCapture(options?: ConsoleCaptureOptions): ConsoleCapture;
+
+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;
+}
+declare function createNetworkCapture(options?: NetworkCaptureOptions): NetworkCapture;
+
+declare const nativeFetch: typeof fetch | undefined;
+declare function getNativeFetch(): typeof fetch | undefined;
+
 interface ConsoleLogEntry {
-    level: 'warn' | 'error';
+    level: "log" | "warn" | "error" | "info";
     message: string;
     timestamp: string;
 }
@@ -80,105 +283,657 @@ 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 IngestConfigEpic {
+    key: string;
+    summary: string;
+    status: string;
+}
+interface IngestConfig {
+    hasJira: boolean;
+    integrationId?: string;
+    epics?: IngestConfigEpic[];
+}
+/**
+ * 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>;
+}> {
+    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 CreateIngestOptions extends IngestOptions {
+    session?: SessionStore;
+}
+declare function createIngest(options?: CreateIngestOptions): Ingest;
+declare function resolveIngestOptions(explicit: IngestOptions | null | undefined, hasCloud: boolean): IngestOptions | null;
+
+interface SurfaceHost {
+    readonly hostEl: HTMLElement;
+    readonly shadowRoot: ShadowRoot;
+    readonly chromeEl: HTMLElement;
+    applyTheme(theme: ResolvedTheme): void;
+    destroy(): void;
+}
+interface SurfaceHostOptions {
+    mount: Element;
+    stylesheets?: string[];
+    initialTheme?: ResolvedTheme;
+}
+declare function createSurfaceHost(options: SurfaceHostOptions): SurfaceHost;
+
+type Cleanup$1 = () => void;
+interface Disposable {
+    destroy(): void;
+}
+interface CleanupStack {
+    add(cleanup: Cleanup$1 | Disposable | null | undefined): void;
+    drain(): void;
+}
 
-interface UidexOverlayProps {
-    target: HTMLElement | null;
+type CursorTooltipContent = {
+    entity: Entity;
+    node?: Element | null;
+} | string;
+interface CursorTooltip {
+    destroy(): void;
+    /** Present content for the current cursor position. */
+    update(content: CursorTooltipContent | null, cursor: {
+        x: number;
+        y: number;
+    } | null): void;
+}
+interface CursorTooltipDeps {
+    container: Element;
+    session: SessionStore;
+}
+declare function createCursorTooltip(deps: CursorTooltipDeps): CursorTooltip;
+
+interface OverlayShowOptions {
+    label?: string;
     color?: string;
-    borderStyle?: BorderStyle;
+    padding?: number;
+    borderStyle?: string;
     borderWidth?: number;
-    colors?: Record<string, string>;
+    fillOpacity?: number;
+}
+interface Overlay {
+    show(target: Element, options?: OverlayShowOptions): void;
+    hide(): void;
+    destroy(): void;
+    readonly isVisible: boolean;
+}
+interface OverlayDeps {
+    container: Element;
+}
+declare function createOverlay(deps: OverlayDeps): Overlay;
+
+interface InspectorMatch {
+    element: HTMLElement;
+    ref: EntityRef;
+    entity: Entity;
+    /** Display name resolved via `displayName(entity, element)`. */
+    label: string;
+}
+interface InspectorOptions {
+    session: SessionStore;
+    registry?: Registry;
+    resolve?: (target: Element) => InspectorMatch | null;
+    onHover?: (match: InspectorMatch | null, cursor: {
+        x: number;
+        y: number;
+    } | null) => void;
+    onSelect?: (match: InspectorMatch, cursor: {
+        x: number;
+        y: number;
+    }) => void;
+}
+interface Inspector {
+    mount(): void;
+    destroy(): void;
+}
+declare function defaultResolveMatch(target: Element, registry?: Registry): InspectorMatch | null;
+declare function resolveEntityElement(ref: EntityRef): HTMLElement | null;
+interface HighlightControllerLike {
+    show(ref: EntityRef, opts?: OverlayShowOptions): void;
+    hide(): void;
+}
+declare function createHighlightController(overlay: Overlay): HighlightControllerLike;
+declare function createInspector(options: InspectorOptions): Inspector;
+
+type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+interface MenuBarOptions {
+    container: Element;
+    session: SessionStore;
+    initialCorner?: Corner;
+    appTitle?: string;
+}
+interface MenuBar {
+    destroy(): void;
+    snapTo(corner: Corner): void;
+    snapToNearest(x: number, y: number): void;
+    readonly corner: Corner;
+    readonly root: HTMLElement;
 }
-declare function UidexOverlay({ target, color, borderStyle, borderWidth, colors, }: UidexOverlayProps): null;
+declare function createMenuBar(options: MenuBarOptions): MenuBar;
 
-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;
+interface ThemeDetector {
+    destroy(): void;
+    /** Resolve the current theme preference against the environment. */
+    readonly resolved: ResolvedTheme;
+}
+interface ThemeDetectorDeps {
+    session: SessionStore;
+    onResolve?: (theme: ResolvedTheme) => void;
+}
+declare function createThemeDetector(deps: ThemeDetectorDeps): ThemeDetector;
 
-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;
+interface CreateSurfaceShellOptions {
+    mount: Element;
+    registry: Registry;
+    session: SessionStore;
+    stylesheets?: string[];
+    initialCorner?: Corner;
+    appTitle?: string;
+    /**
+     * Additional inspector wiring. Hover is pre-wired to overlay + tooltip; pass
+     * `onSelect` (and `onAfterHover`) to extend behaviour without rebuilding the
+     * host.
+     */
+    inspector?: Pick<InspectorOptions, "onSelect"> & {
+        onAfterHover?: InspectorOptions["onHover"];
+    };
+}
+interface SurfaceShell {
+    host: SurfaceHost;
+    overlay: Overlay;
+    tooltip: CursorTooltip;
+    inspector: Inspector;
+    menuBar: MenuBar;
+    themeDetector: ThemeDetector;
+    cleanup: CleanupStack;
+    destroy(): void;
+}
+/**
+ * Builds the chrome bundle shared by `createUidex` and `createHeadless`:
+ * host + theme detector + overlay + cursor tooltip + inspector + menu bar.
+ * Returns a cleanup stack so callers can register their own teardown in LIFO
+ * order, then call `destroy()` once to drain the whole thing.
+ */
+declare function createSurfaceShell(options: CreateSurfaceShellOptions): SurfaceShell;
+
+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;
+}
+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" | "message-circle" | "chevron-down" | "target";
+interface DetailActionRunContext {
+    setLabel(next: string, durationMs?: number): void;
+}
+type DetailSection = {
+    id: "description";
+    text: string;
+} | {
+    id: "acceptance";
+    items: readonly string[];
+} | {
+    id: "scopes";
+    scopes: 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[];
+    unresolved: readonly string[];
+    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>>;
+}
+/**
+ * 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[];
+}
+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;
+    /** 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;
+    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;
+}
+declare class ViewValidationError extends Error {
+    constructor(message: string);
+}
+
+interface ActionsPopupHandle {
+    readonly element: HTMLElement;
+    open(actions: ShellAction[]): void;
+    close(): void;
+    isOpen(): boolean;
+    handleKey(e: KeyboardEvent): boolean;
+    destroy(): void;
+}
+
+declare const SURFACE_HOST_CLASS = "uidex-surface-host";
+declare const SURFACE_CONTAINER_CLASS = "uidex-container";
+declare const Z_BASE = 2147483644;
+declare const Z_OVERLAY = 2147483645;
+declare const Z_CHROME = 2147483646;
+declare const SURFACE_IGNORE_SELECTOR = ".uidex-surface-host,.uidex-container";
+
+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;
+}
+interface ViewRegistrarOptions {
+    session: SessionStore;
+    dev?: boolean;
+}
+declare function createViewRegistrar(options: ViewRegistrarOptions): ViewRegistrar;
+
+interface ViewStackOptions {
+    container: HTMLElement;
+    views: ViewRegistrar;
+    session: SessionStore;
+    registry: Registry;
+    cloud?: CloudAdapter | null;
+    sdkCloud: CloudAdapter;
+    highlight: HighlightController;
+    globalActions?: (ctx: ViewContext) => ShellAction[];
+    dev?: boolean;
+}
+interface ViewStack {
+    /**
+     * The actions popup belonging to the currently mounted stack shell, or
+     * `null` when the shell is not mounted. Exposed so the unified shadow-root
+     * keydown handler can intercept keys while the popup is open.
+     */
+    getActionsPopup(): ActionsPopupHandle | null;
+    destroy(): void;
+}
+declare function createViewStack(options: ViewStackOptions): ViewStack;
+
+declare const commandPaletteView: View;
+
+declare const componentDetailView: View;
+declare const featureDetailView: View;
+declare const regionDetailView: View;
+declare const widgetDetailView: View;
+declare const primitiveDetailView: View;
+declare const pageDetailView: View;
+
+declare const feedbackView: View;
+
+declare const flowDetailView: View;
+
+declare const DEFAULT_VIEWS: readonly [View, View, View, View, View, View, View, View, View, View, View, View];
+
+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;
+}
+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;
+}
+declare function createUidex(options?: CreateUidexOptions): Uidex;
 
-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 { type Cleanup, type CloudAdapter, type ConsoleCapture, type ConsoleEntry, type ConsoleLevel, type ConsoleLogEntry, type Corner, type CreateSessionOptions, type CreateSurfaceShellOptions, type CreateUidexOptions, type CursorTooltip, type CursorTooltipDeps, type CustomSurface, DEFAULT_VIEWS, type DetailAction, type DetailActionIcon, type DetailActionRunContext, type DetailSection, type DetailSubtitle, type DetailSurface, ENTITY_KINDS, type Element$1 as Element, type Entity, type EntityByKind, type EntityKind, type EntityRef, type Feature, type FeedbackExternalLink, type FeedbackPayload, type FeedbackResult, type FeedbackSuggestedTarget, type Flow, type FormField, type FormSubmit, type FormSubmitResult, type FormSurface, type FormValue, type HighlightController, type Ingest, type IngestConfig, type IngestConfigEpic, type IngestOptions, type Inspector, type InspectorMatch, type InspectorOptions, KIND_STYLE, type KindStyleEntry, type ListItem, type ListSurface, type Location, type MenuBar, type MenuBarOptions, type MetaEntityKind, type Metadata, type NetworkCapture, type NetworkEntry, type NetworkErrorEntry, type Overlay, type OverlayShowOptions, type Page, type Primitive, type Region, type Registry, type ResolvedTheme, type Route, SURFACE_CONTAINER_CLASS, SURFACE_HOST_CLASS, SURFACE_IGNORE_SELECTOR, type Scope, type SessionActions, type SessionSnapshot, type SessionState, type SessionStore, type ShellAction, type ShellHint, type SourceRef, type SurfaceHost, type SurfaceHostOptions, type SurfaceShell, type ThemeDetector, type ThemeDetectorDeps, type ThemePreference, type Uidex, UnknownEntityKindError, type View, type ViewContext, type ViewDirectory, type ViewPalette, type ViewPushTarget, type ViewRegistrar, type ViewRegistrarOptions, type ViewStack, type ViewStackEntry, type ViewStackOptions, type ViewSurface, ViewValidationError, type Viewport, type Widget, Z_BASE, Z_CHROME, Z_OVERLAY, assertEntityKind, commandPaletteView, componentDetailView, createConsoleCapture, createCursorTooltip, createHighlightController, createIngest, createInspector, createMenuBar, createNetworkCapture, createOverlay, createRegistry, createSession, createSurfaceHost, createSurfaceShell, createThemeDetector, createUidex, createViewRegistrar, createViewStack, defaultResolveMatch, displayName, entityKey, featureDetailView, feedbackView, flowDetailView, getNativeFetch, isMetaKind, nativeFetch, pageDetailView, prettify, primitiveDetailView, regionDetailView, resolveEntityElement, resolveIngestOptions, resolveTheme, widgetDetailView };