uidex 0.3.0 → 0.5.0

package/dist/headless/index.d.cts

@@ -33,11 +33,16 @@ interface Route {
     path: string;
     page: string;
 }
+interface FlowStep {
+    entityId: string;
+    action?: string;
+}
 interface Flow {
     kind: "flow";
     id: string;
     loc: Location;
     touches: string[];
+    steps: FlowStep[];
 }
 interface Page extends EntityWithMetaBase {
     kind: "page";
@@ -62,6 +67,26 @@ type EntityByKind<K extends EntityKind> = Extract<Entity, {
     kind: K;
 }>;
 
+interface ReportRecord {
+    id: string;
+    entity?: string;
+    reporter?: {
+        id?: string;
+        email?: string;
+        name?: string;
+    };
+    title?: string;
+    body: string;
+    type: string;
+    severity: string;
+    status: string;
+    labels?: string[];
+    url: string;
+    route?: string;
+    pageTitle?: string;
+    screenshot?: string;
+    createdAt: string;
+}
 interface Registry {
     add(entity: Entity): void;
     get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
@@ -69,6 +94,17 @@ interface Registry {
     query(predicate: (entity: Entity) => boolean): Entity[];
     byScope(scope: Scope): Entity[];
     touchedBy(flowId: string): Entity[];
+    setReports(kind: EntityKind, id: string, reports: readonly ReportRecord[]): void;
+    getReports(kind: EntityKind, id: string): readonly ReportRecord[];
+    listReportKeys(): readonly string[];
+    archiveReport?: (reportId: string, reason?: string) => void | Promise<void>;
+    onReportsChange(cb: () => void): () => void;
+}
+
+interface UserIdentity {
+    id: string;
+    name?: string;
+    avatar?: string;
 }
 
 type ThemePreference = "light" | "dark" | "auto";
@@ -87,89 +123,60 @@ interface SessionSnapshot {
     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.
+     * Identity for the local user. Set once at session creation; gates realtime
+     * features (cursor labels, presence) and auto-populates report attribution.
      */
-    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;
+    user: UserIdentity | null;
+}
+type SessionState = SessionSnapshot;
+
+interface NavigationState {
+    stack: ViewStackEntry[];
 }
-interface SessionState extends SessionSnapshot {
-    actions: SessionActions;
+interface NavigationActions {
+    push(entry: ViewStackEntry): void;
+    pop(): void;
+    replace(entry: ViewStackEntry): void;
+    clear(): void;
+    reset(stack: ViewStackEntry[]): void;
 }
+type NavigationStore = StoreApi<NavigationState> & {
+    nav: NavigationActions;
+};
 
-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";
-} | {
-    type: "PIN";
-    ref?: EntityRef;
-} | {
-    type: "UNPIN";
-} | {
-    type: "SET_THEME";
-    theme: ThemePreference;
-    resolvedTheme: ResolvedTheme;
-} | {
-    type: "SET_INGEST";
-    active: boolean;
+type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
+interface ModeSnapshot {
+    mode: SurfaceMode;
+    inspectorActive: boolean;
+}
+interface ModeTransitions {
+    openPalette(): void;
+    openInspector(): void;
+    closeInspector(): void;
+    toggleInspector(): void;
+    enterViewing(initialStack: ViewStackEntry[]): void;
+    dismiss(): void;
+    popOrTransition(): void;
+    pushView(entry: ViewStackEntry): void;
+}
+type ModeStore = StoreApi<ModeSnapshot> & {
+    transition: ModeTransitions;
 };
 
+interface HighlightActions {
+    hover(ref: EntityRef, element?: HTMLElement | null, color?: string | null): void;
+    unhover(): void;
+    pin(ref?: EntityRef): void;
+    unpin(): void;
+}
 type SessionStore = StoreApi<SessionState> & {
-    send(event: SurfaceEvent): void;
+    readonly nav: NavigationStore;
+    readonly mode: ModeStore;
+    readonly highlight: HighlightActions;
+    select(ref: EntityRef | null): void;
+    setTheme(theme: ThemePreference, resolved?: ResolvedTheme): void;
+    setIngest(active: boolean): void;
 };
 
 interface OverlayShowOptions {
@@ -179,6 +186,7 @@ interface OverlayShowOptions {
     borderStyle?: string;
     borderWidth?: number;
     fillOpacity?: number;
+    backdrop?: boolean;
 }
 
 type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";

package/dist/headless/index.d.ts

@@ -33,11 +33,16 @@ interface Route {
     path: string;
     page: string;
 }
+interface FlowStep {
+    entityId: string;
+    action?: string;
+}
 interface Flow {
     kind: "flow";
     id: string;
     loc: Location;
     touches: string[];
+    steps: FlowStep[];
 }
 interface Page extends EntityWithMetaBase {
     kind: "page";
@@ -62,6 +67,26 @@ type EntityByKind<K extends EntityKind> = Extract<Entity, {
     kind: K;
 }>;
 
+interface ReportRecord {
+    id: string;
+    entity?: string;
+    reporter?: {
+        id?: string;
+        email?: string;
+        name?: string;
+    };
+    title?: string;
+    body: string;
+    type: string;
+    severity: string;
+    status: string;
+    labels?: string[];
+    url: string;
+    route?: string;
+    pageTitle?: string;
+    screenshot?: string;
+    createdAt: string;
+}
 interface Registry {
     add(entity: Entity): void;
     get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
@@ -69,6 +94,17 @@ interface Registry {
     query(predicate: (entity: Entity) => boolean): Entity[];
     byScope(scope: Scope): Entity[];
     touchedBy(flowId: string): Entity[];
+    setReports(kind: EntityKind, id: string, reports: readonly ReportRecord[]): void;
+    getReports(kind: EntityKind, id: string): readonly ReportRecord[];
+    listReportKeys(): readonly string[];
+    archiveReport?: (reportId: string, reason?: string) => void | Promise<void>;
+    onReportsChange(cb: () => void): () => void;
+}
+
+interface UserIdentity {
+    id: string;
+    name?: string;
+    avatar?: string;
 }
 
 type ThemePreference = "light" | "dark" | "auto";
@@ -87,89 +123,60 @@ interface SessionSnapshot {
     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.
+     * Identity for the local user. Set once at session creation; gates realtime
+     * features (cursor labels, presence) and auto-populates report attribution.
      */
-    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;
+    user: UserIdentity | null;
+}
+type SessionState = SessionSnapshot;
+
+interface NavigationState {
+    stack: ViewStackEntry[];
 }
-interface SessionState extends SessionSnapshot {
-    actions: SessionActions;
+interface NavigationActions {
+    push(entry: ViewStackEntry): void;
+    pop(): void;
+    replace(entry: ViewStackEntry): void;
+    clear(): void;
+    reset(stack: ViewStackEntry[]): void;
 }
+type NavigationStore = StoreApi<NavigationState> & {
+    nav: NavigationActions;
+};
 
-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";
-} | {
-    type: "PIN";
-    ref?: EntityRef;
-} | {
-    type: "UNPIN";
-} | {
-    type: "SET_THEME";
-    theme: ThemePreference;
-    resolvedTheme: ResolvedTheme;
-} | {
-    type: "SET_INGEST";
-    active: boolean;
+type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
+interface ModeSnapshot {
+    mode: SurfaceMode;
+    inspectorActive: boolean;
+}
+interface ModeTransitions {
+    openPalette(): void;
+    openInspector(): void;
+    closeInspector(): void;
+    toggleInspector(): void;
+    enterViewing(initialStack: ViewStackEntry[]): void;
+    dismiss(): void;
+    popOrTransition(): void;
+    pushView(entry: ViewStackEntry): void;
+}
+type ModeStore = StoreApi<ModeSnapshot> & {
+    transition: ModeTransitions;
 };
 
+interface HighlightActions {
+    hover(ref: EntityRef, element?: HTMLElement | null, color?: string | null): void;
+    unhover(): void;
+    pin(ref?: EntityRef): void;
+    unpin(): void;
+}
 type SessionStore = StoreApi<SessionState> & {
-    send(event: SurfaceEvent): void;
+    readonly nav: NavigationStore;
+    readonly mode: ModeStore;
+    readonly highlight: HighlightActions;
+    select(ref: EntityRef | null): void;
+    setTheme(theme: ThemePreference, resolved?: ResolvedTheme): void;
+    setIngest(active: boolean): void;
 };
 
 interface OverlayShowOptions {
@@ -179,6 +186,7 @@ interface OverlayShowOptions {
     borderStyle?: string;
     borderWidth?: number;
     fillOpacity?: number;
+    backdrop?: boolean;
 }
 
 type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";