@fallen-8/studio 0.0.32

package/dist-lib/types/state/graphShape.d.ts

@@ -0,0 +1,37 @@
+import type { EmbeddingProviderStatsREST, GraphStatisticsREST } from "../api/types";
+import type { InstanceConfig } from "../instances/types";
+/** The reserved property-key prefix element embeddings are stored under (server contract). */
+export declare const EMBEDDING_PROPERTY_PREFIX = "$embedding:";
+/** The reserved prefix carrying an embedding's model stamp (server contract, paired with the above). */
+export declare const EMBEDDING_MODEL_PROPERTY_PREFIX = "$embeddingModel:";
+/**
+ * The per-instance graph-shape snapshot (feature studio-coverage): one react-query cache
+ * entry shared by every consumer. `enabled: false` — the endpoint is a budgeted O(V+E)
+ * pass behind a rate limiter, so ONLY the Graph shape panel's Compute button (refetch())
+ * ever triggers it; other screens just read whatever snapshot exists. This is the schema
+ * cache that closes gap G-3: label / property-key / index-id suggestions everywhere ids
+ * are free-form, with free-form input still working when no snapshot has been computed.
+ */
+export declare function useGraphShape(instance: InstanceConfig): import("@tanstack/react-query").UseQueryResult<NoInfer<GraphStatisticsREST | null>, Error>;
+export interface ShapeSuggestions {
+    vertexLabels: string[];
+    edgeLabels: string[];
+    propertyKeys: string[];
+    indexIds: string[];
+    /**
+     * Embedding names seen on the graph (feature element-embeddings): derived from the
+     * reserved "$embedding:<name>" property keys in the shape snapshot, since embeddings
+     * are stored as reserved properties. Empty until a shape is computed.
+     */
+    embeddingNames: string[];
+}
+/** Datalist feeds from a snapshot; all empty when none has been computed yet. */
+export declare function shapeSuggestions(shape: GraphStatisticsREST | null | undefined): ShapeSuggestions;
+/**
+ * The live embedding-provider state (feature embedding-out-of-box): read from the cheap,
+ * periodically-refreshed /status surface, with the graph-shape snapshot as fallback for
+ * servers predating the /status field. null = genuinely unknown (no answer yet, or an old
+ * server without a computed shape) — the UI treats that like "not confirmed enabled":
+ * text-in controls stay disabled while bring-your-own-vector paths always work.
+ */
+export declare function useEmbeddingProvider(instance: InstanceConfig): EmbeddingProviderStatsREST | null;

package/dist-lib/types/state/instanceStore.d.ts

@@ -0,0 +1,280 @@
+import { type UseBoundStore, type StoreApi } from "zustand";
+import type { BinaryOperatorName, EdgeREST, PathREST, PatternSpecification, PropertyREST, VertexREST } from "../api/types";
+import { type StyleConfig } from "../canvas/styleConfig";
+import { type SemanticDraft, type SemanticQueryDraft, type SlotMode } from "../lib/semantic";
+import type { TypedValue } from "../lib/literals";
+import type { IndexCapability } from "../lib/indexCapabilities";
+import { type FeedFilterDraft } from "./feedFilter";
+/**
+ * Per-instance workspace state (FR-1c), via a memoized store factory. Each instance id
+ * owns exactly one store persisted under its own local-storage key, so canvas contents,
+ * drafts, and result sets can never mix across instances - mixing is structurally
+ * unrepresentable, not merely discouraged.
+ */
+/** Scalar property snapshot for data-driven styling (studio-canvas-viz FR-11). */
+export type CanvasProps = Record<string, string | number | boolean>;
+export interface CanvasNode {
+    id: number;
+    label: string | null;
+    props?: CanvasProps;
+}
+export interface CanvasEdge {
+    id: number;
+    source: number;
+    target: number;
+    edgePropertyId: string | null;
+    /** The element's actual label (null when unset) - never a copy of edgePropertyId. */
+    label: string | null;
+    props?: CanvasProps;
+}
+/**
+ * The one display rule for an edge's name: the human-facing label when present, else the
+ * always-present type (edgePropertyId). Used by both canvases and the label color scale.
+ */
+export declare function edgeDisplayName(edge: Pick<CanvasEdge, "label" | "edgePropertyId">): string | null;
+/** Longest property string kept on the canvas snapshot (FR-11: styling never needs more). */
+export declare const CANVAS_PROP_MAX_STRING = 200;
+/** Scalars only — arrays/objects (e.g. embeddings) are style-less and must not bloat local storage. */
+export declare function snapshotProps(properties: PropertyREST[] | null | undefined): CanvasProps;
+export interface CanvasModel {
+    nodes: Record<number, CanvasNode>;
+    edges: Record<number, CanvasEdge>;
+}
+/**
+ * REST elements → canvas model, merge-only over an optional base. An edge can only
+ * render when both endpoints are present, so unhydrated endpoints get stub nodes —
+ * expand-on-demand and previews stay merge-only. Shared by mergeIntoCanvas and the
+ * adjacency preview (feature adjacency-preview).
+ */
+export declare function buildCanvasModel(vertices: VertexREST[], edges: EdgeREST[], base?: CanvasModel): CanvasModel;
+/**
+ * What the last "Show whole graph" load fetched vs the namespace's true counts (feature
+ * canvas-view-controls FR-3). Persisted alongside the canvas it describes, so the honest
+ * truncation notice survives leaving and returning; cleared with the canvas. Only set
+ * when something was actually truncated.
+ */
+export interface WholeGraphTruncation {
+    fetchedVertices: number;
+    fetchedEdges: number;
+    totalVertices: number;
+    totalEdges: number;
+}
+export interface ResultSet {
+    id: string;
+    title: string;
+    createdAt: number;
+    elementIds: number[];
+}
+/** Where a path/subgraph run takes its fragments from (concept spec §5.1). */
+export type FilterSource = "inline" | "stored";
+export interface PathDraft {
+    from: string;
+    to: string;
+    algorithm: string;
+    maxDepth: number;
+    maxResults: number;
+    maxPathWeight: number;
+    vertexFilter: string;
+    edgeFilter: string;
+    edgePropertyFilter: string;
+    vertexCost: string;
+    edgeCost: string;
+    filterSource: FilterSource;
+    storedQuery: string;
+    /** Declarative semantic-traversal block (feature element-embeddings). */
+    semantic: SemanticDraft;
+}
+export declare const DEFAULT_PATH_DRAFT: PathDraft;
+/**
+ * The Query screen's whole input form (feature index-workspace). Persisted per instance
+ * so leaving for the Canvas and coming back restores it exactly — results are re-run on
+ * demand (kept out of the lean persisted store). Reset via the screen's Clear button.
+ */
+export interface QueryDraft {
+    mode: "property" | "index";
+    /** Property-scan scope: one named "key" (typed operator) or "any" property (contains search). */
+    propertyScope: "key" | "any";
+    propertyId: string;
+    /** All-property search term (propertyScope === "any"): a case-insensitive substring. */
+    searchTerm: string;
+    /** All-property search label restrictor (propertyScope === "any"); empty scans every label. */
+    searchLabel: string;
+    indexId: string;
+    form: IndexCapability;
+    operator: BinaryOperatorName;
+    resultType: "Vertices" | "Edges" | "Both";
+    literal: TypedValue;
+    leftLimit: TypedValue;
+    rightLimit: TypedValue;
+    includeLeft: boolean;
+    includeRight: boolean;
+    fulltextQuery: string;
+    spatialElementId: string;
+    spatialDistance: string;
+    vectorText: string;
+    vectorK: string;
+    vectorKind: "any" | "vertex" | "edge";
+    vectorLabel: string;
+    vectorSource: "vector" | "text";
+    vectorSearchText: string;
+}
+export declare const DEFAULT_QUERY_DRAFT: QueryDraft;
+/**
+ * One pattern row of the subgraph builder: a pattern spec plus a stable list key and the
+ * step's vertex-slot state (feature subgraph-semantic-thresholds) — the slot MODE and the
+ * threshold as editable text (the wire `semanticMinScore` number is derived on build).
+ */
+export type SubgraphPatternDraft = Omit<PatternSpecification, "semanticMinScore"> & {
+    key: string;
+    /** Vertex steps only; edge steps ignore it. */
+    filterMode: SlotMode;
+    /** Threshold text for the semantic mode (parsed on build). */
+    semanticMinScore: string;
+};
+/** The Subgraph "create" form, persisted per instance so navigation never wipes it. */
+export interface SubgraphDraft {
+    name: string;
+    fromSubGraph: string;
+    /** The top-level vertex pre-filter slot's mode (one owner per slot, structural). */
+    vertexFilterMode: SlotMode;
+    /** The slot's fragment text — kept across mode switches so nothing is lost. */
+    vertexFilter: string;
+    /** The slot's threshold text for the semantic mode (parsed on build). */
+    vertexMinScore: string;
+    edgeFilter: string;
+    patterns: SubgraphPatternDraft[];
+    filterSource: FilterSource;
+    storedQuery: string;
+    /** The ONE semantic query per request every semantic threshold scores against. */
+    semanticQuery: SemanticQueryDraft;
+}
+export declare const DEFAULT_SUBGRAPH_DRAFT: SubgraphDraft;
+/** The Browser screen's lookup + bulk inputs, persisted per instance. */
+export interface BrowserDraft {
+    idInput: string;
+    lookupKind: "graphelement" | "vertex" | "edge";
+    maxElements: number;
+    bulkFilter: string;
+    detailTab: "properties" | "embeddings";
+}
+export declare const DEFAULT_BROWSER_DRAFT: BrowserDraft;
+/** The Analytics runner's algorithm pick + tuning inputs, persisted per instance. */
+export interface AnalyticsDraft {
+    algorithm: string;
+    vertexLabel: string;
+    edgePropertyId: string;
+    direction: string;
+    maxResults: string;
+    maxIterations: string;
+    timeBudget: string;
+    damping: string;
+    epsilon: string;
+    showWriteBack: boolean;
+    writeBack: boolean;
+    writeBackKey: string;
+}
+export declare const DEFAULT_ANALYTICS_DRAFT: AnalyticsDraft;
+/**
+ * The Canvas right-panel tool strip's inputs (feature canvas-find-connect), persisted per
+ * instance so leaving the canvas and returning restores the active tab and each tool's form.
+ * The Find result list, Connect found paths, and Connect picked-vertex ids are ephemeral session
+ * state (re-run on demand), exactly like every other result in the studio - only the inputs here
+ * persist.
+ */
+export interface CanvasToolsDraft {
+    /** Which right-panel tab is active: styling, element search, or path connecting. */
+    tab: "style" | "find" | "connect";
+    /** Find: the all-property contains term (fed to POST /scan/graph/properties). */
+    findTerm: string;
+    /** Find: optional exact-match label restrictor; empty searches every label. */
+    findLabel: string;
+    /** Find: restrict matches to vertices, edges, or both. */
+    findResultType: "Vertices" | "Edges" | "Both";
+    /** Connect: max hops per pairwise path search (maps to the path spec's maxDepth). */
+    connectMaxDepth: number;
+    /** Connect: use every canvas vertex, or only a picked subset, as the pair endpoints. */
+    connectScope: "all" | "pick";
+}
+export declare const DEFAULT_CANVAS_TOOLS_DRAFT: CanvasToolsDraft;
+/** One-shot navigation intent: "open Query with this index preselected" (cleared on consume). */
+export interface ScanPrefill {
+    indexId: string;
+}
+export interface WorkspaceState {
+    /** The Events panel's interest filter (feature studio-event-feed, see feedFilter.ts). */
+    feedFilter: FeedFilterDraft;
+    /** One-shot navigation intent: "open the Browser inspecting this element id". */
+    inspectPrefill: number | null;
+    canvasNodes: Record<number, CanvasNode>;
+    canvasEdges: Record<number, CanvasEdge>;
+    styleConfig: StyleConfig;
+    pathOverlay: PathREST | null;
+    wholeGraphTruncation: WholeGraphTruncation | null;
+    resultSets: ResultSet[];
+    pathDraft: PathDraft;
+    queryDraft: QueryDraft;
+    subgraphDraft: SubgraphDraft;
+    browserDraft: BrowserDraft;
+    analyticsDraft: AnalyticsDraft;
+    canvasToolsDraft: CanvasToolsDraft;
+    scanPrefill: ScanPrefill | null;
+    mergeIntoCanvas: (vertices: VertexREST[], edges: EdgeREST[]) => void;
+    removeFromCanvas: (kind: "node" | "edge", id: number) => void;
+    clearCanvas: () => void;
+    setWholeGraphTruncation: (truncation: WholeGraphTruncation | null) => void;
+    setStyleConfig: (patch: Partial<StyleConfig>) => void;
+    setPathOverlay: (path: PathREST | null) => void;
+    addResultSet: (title: string, elementIds: number[]) => void;
+    removeResultSet: (id: string) => void;
+    setPathDraft: (patch: Partial<PathDraft>) => void;
+    resetPathDraft: () => void;
+    setQueryDraft: (patch: Partial<QueryDraft>) => void;
+    resetQueryDraft: () => void;
+    setSubgraphDraft: (patch: Partial<SubgraphDraft>) => void;
+    resetSubgraphDraft: () => void;
+    setBrowserDraft: (patch: Partial<BrowserDraft>) => void;
+    resetBrowserDraft: () => void;
+    setAnalyticsDraft: (patch: Partial<AnalyticsDraft>) => void;
+    resetAnalyticsDraft: () => void;
+    setCanvasToolsDraft: (patch: Partial<CanvasToolsDraft>) => void;
+    setScanPrefill: (prefill: ScanPrefill | null) => void;
+    setFeedFilter: (patch: Partial<FeedFilterDraft>) => void;
+    setInspectPrefill: (id: number | null) => void;
+}
+type WorkspaceStore = UseBoundStore<StoreApi<WorkspaceState>>;
+/**
+ * Returns the one store belonging to this instance id + namespace (memoized). The
+ * "default" namespace keeps the pre-namespace key (`f8.workspace.<id>`) so an existing
+ * workspace is adopted as default's with no migration; other namespaces persist under
+ * `f8.workspace.<id>/<ns>` (feature graph-namespaces). Also accepts a pre-bound
+ * "<id>/<namespace>" compound as the first argument (the bound instance view's id, see
+ * useInstanceStore) — both call shapes resolve to the same canonical key. Registry ids
+ * never contain "/".
+ */
+export declare function getInstanceStore(instanceId: string, namespace?: string): WorkspaceStore;
+/**
+ * Drops a namespace's memoized store AND its persisted state (feature graph-namespaces):
+ * after a drop, a recreate, or a factory reset the old canvas/results would reference
+ * elements that no longer exist (or worse, ids now naming different elements).
+ */
+export declare function purgeInstanceStore(instanceId: string, namespace?: string): void;
+/** Purges EVERY namespace's workspace of one instance (the factory-reset blast radius). */
+export declare function purgeAllInstanceStores(instanceId: string): void;
+/**
+ * Moves a namespace's persisted workspace to its new name — rename is a pure address
+ * change, so canvas/drafts must follow. Both memoized stores are dropped (a store's
+ * persist key is baked in at creation), so the next access rehydrates from the moved state.
+ */
+export declare function migrateInstanceStore(instanceId: string, from: string, to: string): void;
+/**
+ * Drops every memoized store (persisted state untouched), so the next access recreates it
+ * against the CURRENT storage prefix. A store bakes its persist key in at creation
+ * (`workspaceStorageName`), and the memo map is keyed by scope alone, so a mount that
+ * changes `storageNamespace` (feature studio-embeddable) must clear the map or a colliding
+ * instance id + namespace would hand the new mount the previous one's live store - reading
+ * its graph data and writing to its key. Called from applyStudioConfig on every mount.
+ */
+export declare function dropMemoizedWorkspaceStores(): void;
+/** Test hook: same drop, named for its use at test setup. */
+export declare const resetInstanceStoresForTests: typeof dropMemoizedWorkspaceStores;
+export {};

package/dist-lib/types/state/integrations.d.ts

@@ -0,0 +1,25 @@
+import type { InstanceConfig } from "../instances/types";
+import type { IntegrationProvider } from "../api/types";
+/**
+ * The integrations capability of one instance (feature integrations), read from the one route that
+ * answers it: the provider catalog.
+ *
+ * There is no `/status` block to read, deliberately - the runtime is a separate deployable and the
+ * instance publishes nothing about it - so the catalog IS the probe. The interesting states are
+ * three: it answered (the screen works), it refused the capability (the screen and its rail entry
+ * are ABSENT), or the instance itself is unwell (that is the shell's business, not this screen's).
+ *
+ * A refusal is 403 on an instance with an API key configured and 401 on an open one, because the
+ * standing capability policy challenges before it forbids. Both mean the same thing here, and
+ * keying on one status code would hide the screen on secured instances only.
+ */
+export type IntegrationsCapability = "checking" | "available" | "absent" | "unreachable";
+export declare function useIntegrationProviders(instance: InstanceConfig | null): import("@tanstack/react-query").UseQueryResult<NoInfer<IntegrationProvider[] | null>, unknown>;
+/** Whether a failure is the capability being off rather than the instance being unwell. */
+export declare function isCapabilityRefusal(error: unknown): boolean;
+/** The capability verdict of a providers query, for the rail and for a deep link. */
+export declare function capabilityOf(query: {
+    isError: boolean;
+    isSuccess: boolean;
+    error: unknown;
+}): IntegrationsCapability;

package/dist-lib/types/state/liveFeed.d.ts

@@ -0,0 +1,37 @@
+import { type QueryClient } from "@tanstack/react-query";
+import type { InstanceConfig } from "../instances/types";
+import { type ChangeEvent } from "../api/changefeed";
+/**
+ * Live mode (feature change-feed, spec §3.7): ONE stream per ACTIVE instance, torn down
+ * on instance switch (FR-1c isolation), turning committed mutations into UI updates.
+ *
+ * Integration approach - targeted query invalidation, not hand-rolled cache surgery:
+ * every screen already reads through react-query keys scoped as [instance.id, ...], so
+ * invalidating the relevant keys (debounced against event bursts) makes every screen
+ * live without per-element cache merging. The canvas is the exception (it is a curated
+ * zustand store, not a query), so it gets the direct minimum: removed elements are
+ * dropped, and a created edge between two on-screen vertices is fetched and merged.
+ *
+ * Resync handling is mandatory, not optional: on ANY resync every query of the instance
+ * is invalidated (the same fetches the screens issued to render initially); for reason
+ * trim/tabulaRasa/load every held element id is invalid, so the canvas state is cleared.
+ */
+export type LiveFeedStatus = "off" | "connecting" | "live" | "unavailable";
+export interface LiveFeedContext {
+    instance: InstanceConfig;
+    queryClient: QueryClient;
+    /** Invalidation debounce window against event bursts (default 300ms). */
+    debounceMs?: number;
+}
+export interface LiveFeedHandlers {
+    onEvent: (event: ChangeEvent) => void;
+    onResync: (event: ChangeEvent) => void;
+    dispose: () => void;
+}
+/**
+ * Builds the event handlers for one instance's stream. Exported separately from the
+ * hook so the semantics are unit-testable without a component tree.
+ */
+export declare function createLiveFeedHandlers(ctx: LiveFeedContext): LiveFeedHandlers;
+export declare function bumpFeedGeneration(): void;
+export declare function useLiveChangeFeed(instance: InstanceConfig | null): LiveFeedStatus;

package/dist-lib/types/state/scopeKey.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The ONE per-instance-per-namespace scope rule, shared by the workspace store
+ * (instanceStore) and the event feed (eventFeed): accepts a pre-bound compound
+ * "<id>/<namespace>" or an (id, namespace) pair, and collapses the reserved "default"
+ * namespace onto the bare instance id - so a pre-namespace workspace is adopted as
+ * default's with no migration (feature graph-namespaces). Registry ids never contain "/".
+ */
+export declare function scopeKey(instanceId: string, namespace?: string): string;

package/dist-lib/types/state/status.d.ts

@@ -0,0 +1,21 @@
+import type { InstanceConfig } from "../instances/types";
+/**
+ * The shared /status cache entry. Same query key as the AppShell health probe, so every
+ * consumer reads one cache row and rides its periodic refresh; /status is the cheap
+ * discovery surface (available plugins + live index inventory — feature
+ * studio-index-discovery), unlike the budgeted Graph-shape pass in graphShape.ts.
+ */
+export declare function useStatus(instance: InstanceConfig): import("@tanstack/react-query").UseQueryResult<NoInfer<import("../api/types").StatusREST | null>, Error>;
+/**
+ * The instance's configuration (features instance-config and writable-instance-config): the setting
+ * inventory, the semantic providers and the observability posture behind the Connect Configuration
+ * section. Fallen-8-level, so it is keyed by the RAW instance id (not per namespace) and API-key
+ * gated server-side.
+ *
+ * Pass poll: false while the operator has unsaved edits. The panel is an editor now, and a ten second
+ * refetch would otherwise replace the value under a half-typed field: the poll exists so model
+ * residency updates on its own, which is never worth losing someone's input over.
+ */
+export declare function useConfig(instance: InstanceConfig, options?: {
+    poll?: boolean;
+}): import("@tanstack/react-query").UseQueryResult<NoInfer<import("../api/types").ConfigREST | null>, Error>;