@fallen-8/studio 0.0.35 → 0.0.36

package/dist-lib/types/components/DurabilityNotice.d.ts

@@ -4,15 +4,30 @@ import type { DurabilityREST } from "../api/types";
  *
  * The engine has published this on /status for a while and a machine already acts on it - the
  * integrations runtime refuses to delete anything while it is unhealthy - but nothing showed it to
- * the person watching. That was the gap: "a client writes into a degraded log and nobody watching a
- * dashboard finds out" was the failure this signal existed to prevent, and it stopped one hop short.
+ * the person watching. That was the gap the signal exists to close: "a client writes into a
+ * degraded log and nobody watching finds out". It is rendered by the app shell, so it reaches that
+ * person on whatever screen they are on rather than on one they had to think to open.
  *
- * Deliberately SILENT when everything is fine. A dashboard that always carries a green durability
- * badge trains people to stop reading it, and the three states worth interrupting for are all
- * exceptional: the log is degraded (commits are landing in memory only), the last recovery was
- * truncated (the graph is a prefix of history, so anything reconciling against it is reasoning from
- * incomplete data), or the last checkpoint dropped indexes (they are gone after the next load).
+ * Deliberately SILENT when everything is fine. A banner that is always there stops being read, and
+ * the three states worth interrupting for are all exceptional: the log is degraded (commits are
+ * landing in memory only), the last recovery was truncated (the graph is a prefix of history, so
+ * anything reconciling against it is reasoning from incomplete data), or the last checkpoint
+ * dropped indexes (they are gone after the next load).
  */
+/** One thing worth interrupting for: what is wrong, and what it means for this graph. */
+export interface DurabilityProblem {
+    title: string;
+    detail: string;
+}
+/**
+ * The three exceptional states, as prose - and the ONE home for "is durability worth saying
+ * something about", which the shell also asks (an empty namespace whose recovery was truncated
+ * gets this warning instead of the first-run welcome; see AppShell).
+ *
+ * Absent is not healthy: an older server simply does not report, and saying nothing is honest,
+ * whereas rendering "durable" from missing data would be an invention.
+ */
+export declare function durabilityProblems(durability: DurabilityREST | null | undefined): DurabilityProblem[];
 export declare function DurabilityNotice({ durability }: {
     durability: DurabilityREST | null | undefined;
 }): import("react").JSX.Element | null;

package/dist-lib/types/components/FileDropzone.d.ts

@@ -10,8 +10,13 @@ import { type ReactNode } from "react";
  * what that screen needs it to mean.
  */
 export declare function FileDropzone(props: {
-    /** Called with the dropped file. */
-    onFile: (file: File) => void;
+    /** Called with the dropped files, in the order the browser reported them, and never with none. */
+    onFiles: (files: File[]) => void;
+    /**
+     * Takes every file of one drop rather than the first. A source handed over as a SET of files
+     * needs it: without it the rest of the drop is silently ignored, which reads as a lost file.
+     */
+    multiple?: boolean;
     /** Greys the target out and refuses drops, for a screen that is not ready to take one. */
     disabled?: boolean;
     /** What the target says when nothing is being dragged over it. */

package/dist-lib/types/components/Stat.d.ts

@@ -1,5 +1,5 @@
 /**
- * One labeled stat cell (Dashboard counts, benchmark results, Graph shape numbers, and
+ * One labeled stat cell (benchmark results, Graph shape numbers, and
  * value tiles fed user/algorithm-controlled strings such as the embedding model id or an
  * analytics statistic key). Both lines truncate with a full-value title so an unbounded
  * label or value can never overflow the fixed-width tile.

package/dist-lib/types/delegate/nl/useNlRun.d.ts

@@ -1,3 +1,4 @@
+import type { NlAssistConfig } from "./config";
 /**
  * Run lifecycle shared by both NL panels (the delegate editor's and the plugin editor's).
  * It exists because the two panels had the same two defects in duplicate:
@@ -22,3 +23,9 @@ export declare function useNlRun(): {
  * the original hang was reported.
  */
 export declare function useElapsedSeconds(active: boolean): number;
+/**
+ * Informational-only reachability read (nl-assist-ux FR-2), shared by both NL panels: custom mode
+ * probes the configured endpoint, instance mode reports nothing (its reachability is the instance
+ * connection itself, shown on Connect). Never gates generation.
+ */
+export declare function useReachabilityProbe(configured: boolean, isInstance: boolean, effective: NlAssistConfig): boolean | null;

package/dist-lib/types/firstrun/FirstRunOverlay.d.ts

@@ -1,10 +1,43 @@
+import type { NamespaceSignals } from "../app/namespaceSignals";
 /**
- * Manual-replay overlay (feature studio-first-run). Renders the SAME <FirstRunShow> the
- * Dashboard auto-shows, on top of the current screen, from beat 1. Radix Dialog gives the focus
- * trap, Escape-to-close, and focus restore for free. Closing never touches the dismissed flag.
+ * The first-run show's ONE host (feature studio-first-run), rendered once by the app shell. Radix
+ * Dialog gives the focus trap, Escape-to-close, and focus restore for free.
+ *
+ * It opens on two paths, and the difference is entirely in what closing means:
+ *
+ * - **auto** - the operator is on a screen ABOUT a graph and that graph was empty WHEN THEY
+ *   ARRIVED at the namespace (see the `arrival` latch: emptiness is live, arrival is not), and
+ *   they have not dismissed the show for it. Closing by ANY route (Close, Escape, the scrim,
+ *   "Explore on my own") records the dismissal; an auto-opening modal that came back on the next
+ *   navigation would be unusable. The memory is per namespace and re-armed the moment that
+ *   namespace is seen non-empty, so a graph that genuinely empties later shows the intro again the
+ *   next time you arrive at it.
+ * - **replay** - the rail's Intro button, available at any time regardless of the connection
+ *   state, the graph being empty, or the dismissal. Closing it leaves the flag alone UNLESS the
+ *   auto path is armed for this namespace, in which case closing counts for both (see `armed`).
  *
  * The show creates NOTHING: its handoff buttons only navigate (to the Sample gallery or the
  * import screen) or dismiss. The unit-test graph endpoint is deliberately never wired in (see
  * CLAUDE.md); newcomers reach a populated graph through the curated Sample gallery.
  */
-export declare function FirstRunOverlay(): import("react").JSX.Element;
+export declare function FirstRunOverlay({ signals, connected, onGraphScreen, }: {
+    /** The active namespace's shell-level signals - what decides the auto path. */
+    signals: NamespaceSignals;
+    /**
+     * Whether the active instance answered AND authorized. /status reports real counts to an
+     * unauthorized caller too, so without this an instance that rejected the credential would greet
+     * the operator with a walkthrough on top of the "rejected the credential" guard.
+     */
+    connected: boolean;
+    /**
+     * Whether the current route is a namespace-scoped screen (`/q/{ns}/…`).
+     *
+     * The auto path is deliberately silent on the Fallen-8-level screens - Connect, Save games,
+     * Integrations. The walkthrough is about a GRAPH, and those three are where you wire one up:
+     * registering an instance, naming namespaces, restoring a checkpoint, pointing an integration at
+     * a system. Interrupting that with a modal is not onboarding, it is an ambush, and the very
+     * first thing a newcomer does after connecting is click a rail entry - which lands them on a
+     * scoped screen, where the show opens with nothing half-finished behind it.
+     */
+    onGraphScreen: boolean;
+}): import("react").JSX.Element;

package/dist-lib/types/firstrun/FirstRunShow.d.ts

@@ -5,12 +5,12 @@
  *
  * It CREATES NOTHING: it renders a hardcoded mock as SVG and animates it with CSS. It issues no
  * network request of its own. Only the handoff buttons perform a real action, on click, through
- * the injected handlers - so the auto-show (rendered inline by the Dashboard on an empty graph)
- * and the manual replay (rendered by <FirstRunOverlay>) are the SAME component with the same
- * contract; only the entry point differs. Prev/Next/dots let a viewer step through at their pace.
+ * the injected handlers - so the auto-show (opened for a newcomer on an empty namespace) and the
+ * manual replay (the rail's Intro button) are the SAME component with the same contract, hosted by
+ * the same <FirstRunOverlay>; only the entry point differs. Prev/Next/dots let a viewer step through at their pace.
  */
 export interface FirstRunShowProps {
-    /** "auto" = inline empty-state on the Dashboard; "replay" = manual overlay. Used only for labels. */
+    /** "auto" = a newcomer on an empty namespace; "replay" = the rail's Intro. Used only for labels. */
     variant: "auto" | "replay";
     /** Dismiss into the app (auto: remember dismissal; replay: close the overlay). */
     onExplore: () => void;

package/dist-lib/types/instances/registry.d.ts

@@ -70,8 +70,7 @@ export declare function useActiveInstance(): InstanceConfig | null;
 /**
  * The active instance plus its per-namespace workspace store - the preamble every connected
  * screen needs (the AppShell connection gate guarantees an active instance, hence the non-null).
- * The returned instance is NAMESPACE-BOUND (feature graph-namespaces): its API calls address
- * /ns/{activeNamespace}/… explicitly, and the workspace store is keyed per namespace so
+ * The instance is bound per `boundInstance`, and the workspace store is keyed per namespace so
  * results, drafts and canvas state never cross namespaces.
  */
 export declare function useInstanceStore(): {
@@ -81,3 +80,10 @@ export declare function useInstanceStore(): {
         <U>(selector: (state: import("../state/instanceStore").WorkspaceState) => U): U;
     } & import("zustand").StoreApi<import("../state/instanceStore").WorkspaceState>;
 };
+/**
+ * The bound active instance for SHELL-level consumers, or null when no instance is active.
+ * `useInstanceStore` is this plus the workspace store, but it asserts an instance because it is
+ * only ever called from a screen behind the connection gate; the shell itself (the durability
+ * banner, the first-run auto-show) renders before that gate and must tolerate "none".
+ */
+export declare function useBoundInstance(): InstanceConfig | null;

package/dist-lib/types/lib/embeddingProperties.d.ts

@@ -1,5 +1,27 @@
 /** A property is reserved (embedding state) when it uses either embedding prefix. */
 export declare function isReservedEmbeddingProperty(propertyId: string): boolean;
+/**
+ * The element's own properties first, engine-written embedding state last, order otherwise
+ * preserved. For a TRUNCATED preview (the element table's properties cell), which is the only
+ * place this matters: a reserved marker is bookkeeping the operator did not write and cannot edit
+ * here, so spending the character budget on it before their own data is backwards.
+ *
+ * It was not hypothetical. On a graph with embeddings, `$embeddingModel:default=bge-m3#1024#Cosine`
+ * is ~44 of the ~80 available characters, and the REST egress emits properties in no guaranteed
+ * order - so a movie row rendered as "year=2010, $embeddingModel:default=…, plot=A thief who
+ * steals…" with `title=` cut off entirely, and the published semantic-search screenshot showed no
+ * film title in any of its ten rows.
+ */
+export declare function userPropertiesFirst<T extends {
+    propertyId: string;
+}>(properties: T[]): T[];
+/**
+ * The stored vector as the Query screen's vector box wants it: the WHOLE bracketed list, where
+ * previewVector deliberately gives four components and a dimension. Both shapes the REST egress
+ * can send are accepted (a Single[] array, or the bracketed string form). Null when the value is
+ * not a vector at all.
+ */
+export declare function vectorQueryText(value: unknown): string | null;
 /** A one-line preview of a stored vector value. The REST egress sends Single[] values as
  * the bracketed string form (see AGraphElement.FormatPropertyValue), so both shapes are
  * truncated — a 1024-dim embedding must never dump raw into the table. */

package/dist-lib/types/lib/findSimilar.d.ts

@@ -0,0 +1,21 @@
+import type { EdgeREST, IndexDescription, VertexREST } from "../api/types";
+import type { ScanPrefill } from "../state/instanceStore";
+/**
+ * "Find elements like this one", composed entirely on the client (feature element-similarity-search).
+ *
+ * There is no element-as-query mode anywhere in the product: `/embedding/search` takes text and
+ * `/scan/index/vector` takes a vector, so the only way to ask "what is like THIS" is to read the
+ * element's own stored embedding and search with it. That read is free - the vector is already in
+ * the element's properties, which the caller has already fetched.
+ *
+ * The searchable index is the one BOUND to that embedding name. An unbound index holds vectors that
+ * exist nowhere else, so it cannot be expected to contain this element at all, and a bound index of
+ * a different name projects different vectors. No bound index means the gesture has nowhere to run,
+ * which is a reason to show rather than a button to grey out silently.
+ */
+export interface SimilarSearch {
+    prefill: ScanPrefill;
+    embeddingName: string;
+}
+/** Every embedding this element carries that a bound vector index actually projects. */
+export declare function similarSearchesFor(element: VertexREST | EdgeREST, indices: IndexDescription[] | null | undefined, isEdge: boolean): SimilarSearch[];

package/dist-lib/types/lib/pollIntervals.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The poll cadence shared by every observer of an instance's two cheap discovery routes:
+ * `/status` (the connection probe, the durability banner, the Instances row health cell) and
+ * `/ns` (the namespace inventory, read by the switcher, NamespacesPanel and the namespace-recover
+ * screen). All of them key their query on `[instanceId, "status"]` or `[instanceId, "namespaces"]`,
+ * and TanStack times `refetchInterval` PER OBSERVER: two observers of one key with two different
+ * intervals do not give each consumer its own poll rate, they refresh the shared row on the union
+ * of both cadences, so neither consumer gets the interval it declared and the shorter one sets the
+ * floor for both. One constant removes the possibility.
+ *
+ * Tune the number here, not per call site.
+ */
+export declare const STATUS_POLL_MS = 15000;

package/dist-lib/types/lib/samples.d.ts

@@ -1,7 +1,7 @@
 /**
  * Sample-graph manifest types (feature sample-graphs): the contract between the build
  * script (scripts/build-samples.ts, which writes public/samples/index.json) and the
- * Dashboard's Sample graphs section, which renders the card grid and runs the loader
+ * Samples screen, which renders the card grid and runs the loader
  * purely from this data. Adding a static sample is a script + manifest change — no UI
  * code.
  */

package/dist-lib/types/screens/IntegrationsScreen.d.ts

@@ -7,8 +7,9 @@
  * needed its own component would be a contract failure rather than a UI task, and the agent that
  * writes the fourth integration cannot write a React component for it anyway.
  *
- * There is no schedule, no run history and no saved job list here, because the runtime keeps none:
- * timing belongs to whoever wants the data, and a Studio-side copy would be a second home for a
- * decision this screen cannot judge. Submitting is a one-shot action.
+ * Submitting STARTS a run and does not wait for it: the runtime answers a run id, and this screen
+ * then watches that run - the phase it is in, and its report once it ends. That is not a run history
+ * (the boundary is on IntegrationRunState), so there is no schedule, no list of past runs and no
+ * saved job list here; timing belongs to whoever wants the data.
  */
 export declare function IntegrationsScreen(): import("react").JSX.Element;

package/dist-lib/types/screens/SamplesScreen.d.ts

@@ -1,7 +1,7 @@
 /**
- * Samples (feature sample-graphs): the one-click demo gallery, promoted from the Dashboard
- * to its own rail entry so every card spans the full width and carries its "what you can
- * test" steps, with a tag bar to filter by capability. Namespace-scoped — a load replaces
+ * Samples (feature sample-graphs): the one-click demo gallery. It has its own rail entry so every
+ * card spans the full width and carries its "what you can test" steps, with a tag bar to filter
+ * by capability. Namespace-scoped - a load replaces
  * the active namespace's graph (SampleGraphsPanel owns the loader + typed-confirm wipe).
  */
 export declare function SamplesScreen(): import("react").JSX.Element;

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

@@ -199,12 +199,41 @@ 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;
+    /**
+     * A query vector to search WITH, in the bracketed form the vector box parses. Set by the
+     * "find similar" gesture, which reads it off the source element's own stored embedding: the
+     * search surface takes a vector, never an element id, so the element-as-query gesture is
+     * composed on this side rather than asked of the server.
+     */
+    vectorText?: string;
+    /**
+     * The element the vector came from, so it can be dropped from its own results. There is no
+     * self-exclusion anywhere in the engine or the REST contract, so an unfiltered search returns
+     * the source element at rank 1 every time.
+     */
+    sourceElementId?: number;
+    /**
+     * The source element's label, inherited as the search constraint. Not a convenience: several
+     * entity kinds embed as little more than their identifier, so an unconstrained similarity
+     * search over such a graph ranks identifier-shaped noise against real matches.
+     */
+    label?: string;
+    kind?: "any" | "vertex" | "edge";
 }
 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;
+    /**
+     * The integration identity whose run this instance is watching, or null.
+     *
+     * PERSISTED, unlike the one-shot prefills, and that is the point: a run outlives the request that
+     * started it and can take hours, so reopening the screen - or reloading the page - has to re-attach
+     * to it rather than lose it. The identity is enough to re-find the run, because the runtime keys its
+     * slot by exactly that.
+     */
+    integrationWatch: string | null;
     canvasNodes: Record<number, CanvasNode>;
     canvasEdges: Record<number, CanvasEdge>;
     styleConfig: StyleConfig;
@@ -240,6 +269,7 @@ export interface WorkspaceState {
     setScanPrefill: (prefill: ScanPrefill | null) => void;
     setFeedFilter: (patch: Partial<FeedFilterDraft>) => void;
     setInspectPrefill: (id: number | null) => void;
+    setIntegrationWatch: (instanceId: string | null) => void;
 }
 type WorkspaceStore = UseBoundStore<StoreApi<WorkspaceState>>;
 /**

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

@@ -4,8 +4,27 @@ import type { InstanceConfig } from "../instances/types";
  * 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.
+ *
+ * Accepts null and then asks nothing: the shell-level readers (the durability banner, the
+ * first-run auto-show) render outside the connection gate, so "no instance yet" is a state they
+ * pass through rather than an assertion they can make.
+ *
+ * Pass poll: true to drive the shared row on a timer. Exactly one caller does - the app shell,
+ * on the same 15s cadence as its instance health probe - because the durability banner is a
+ * warning nobody goes looking for: it has to arrive while the operator is on some other screen.
+ * Every other observer rides that refresh through the shared cache row and asks for nothing.
+ *
+ * Polling implies `retry: 0`, matching the health probe, and that pairing is load-bearing rather
+ * than tidy: on a server that predates namespaces the bound view collapses to the raw instance, so
+ * this row and the probe become the SAME query key. react-query takes `retry` from whichever
+ * observer initiated the current fetch, so without this the probe's deliberate fail-fast became a
+ * coin flip against a default of three retries - and for the ~7s of backoff that won, a dead
+ * instance still read "online" with the nav unlocked. There is no point retrying a 15s poll anyway;
+ * the next tick is the retry.
  */
-export declare function useStatus(instance: InstanceConfig): import("@tanstack/react-query").UseQueryResult<NoInfer<import("../api/types").StatusREST | null>, Error>;
+export declare function useStatus(instance: InstanceConfig | null, options?: {
+    poll?: boolean;
+}): 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

package/dist-lib/{typescript-oqqsXxrY.js → typescript-CmUu7z19.js}

@@ -1,4 +1,4 @@
-import { m as s } from "./index-B9b5xEwe.js";
+import { m as s } from "./index-CQF9rZdm.js";
 var c = Object.defineProperty, a = Object.getOwnPropertyDescriptor, p = Object.getOwnPropertyNames, g = Object.prototype.hasOwnProperty, l = (t, e, o, i) => {
   if (e && typeof e == "object" || typeof e == "function")
     for (let n of p(e))

package/dist-lib/{xml-pmqwhaBA.js → xml-BID2APnO.js}

@@ -1,4 +1,4 @@
-import { m as r } from "./index-B9b5xEwe.js";
+import { m as r } from "./index-CQF9rZdm.js";
 var m = Object.defineProperty, c = Object.getOwnPropertyDescriptor, l = Object.getOwnPropertyNames, d = Object.prototype.hasOwnProperty, p = (t, e, o, i) => {
   if (e && typeof e == "object" || typeof e == "function")
     for (let n of l(e))

package/dist-lib/{yaml-DN1I59zm.js → yaml-CpQ-mN6F.js}

@@ -1,4 +1,4 @@
-import { m as l } from "./index-B9b5xEwe.js";
+import { m as l } from "./index-CQF9rZdm.js";
 var i = Object.defineProperty, c = Object.getOwnPropertyDescriptor, u = Object.getOwnPropertyNames, s = Object.prototype.hasOwnProperty, d = (n, e, r, o) => {
   if (e && typeof e == "object" || typeof e == "function")
     for (let t of u(e))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fallen-8/studio",
-  "version": "0.0.35",
+  "version": "0.0.36",
   "description": "F8 Studio - browser frontend for Fallen-8 instances, and its graph canvas as a standalone component",
   "license": "MIT",
   "author": "Henning Rauch",

package/dist-lib/types/screens/DashboardScreen.d.ts

@@ -1,13 +0,0 @@
-/**
- * Dashboard (FR-2/3/4): the status overview for the active namespace — vertex/edge counts
- * and memory, from /status. It is deliberately lean: the sample gallery, the persistence/
- * administration actions, the stored-query library, the plugin registry, and the instance
- * configuration (semantic providers, observability) each have their own home (Samples, Save
- * games, Query, Plugins, and the Connect Configuration section).
- *
- * On an empty, not-yet-dismissed namespace this is also the home of the first-run show
- * (feature studio-first-run): instead of three zeroed tiles a newcomer gets an animated,
- * read-only walkthrough that creates nothing. It is dismissed per namespace and re-armed the
- * moment the namespace is seen non-empty, so a returning user is never nagged.
- */
-export declare function DashboardScreen(): import("react").JSX.Element;