@fallen-8/studio 0.0.37 → 0.0.39

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

@@ -0,0 +1,174 @@
+import type { EdgeREST, VectorSearchResultREST, VertexREST } from "../api/types";
+import type { InstanceConfig } from "../instances/types";
+import type { CanvasEdge, CanvasNode } from "../state/instanceStore";
+/**
+ * Pure logic for the Canvas "Interact" tab (feature canvas-interact): filters build a MATCH SET
+ * over the canvas vertices, and two view-only verbs (expand, remove) apply to it. Kept DOM-free
+ * so every decision below is unit-tested without a render.
+ *
+ * The verbs are also the single home for expand-on-demand: the Detail panel's "Expand neighbors"
+ * runs `expandVertices` over one id, the tab runs it over the match set. See
+ * features/open/canvas-interact/spec.md.
+ */
+/**
+ * The most candidates a DATABASE-degree evaluation will sweep. Two requests per candidate, so the
+ * cap is about bounding a click, not about correctness; above it the run is refused rather than
+ * partially evaluated, and the cheap filters are the narrowing tool. One tuning home.
+ */
+export declare const DEGREE_SWEEP_CAP = 1000;
+/**
+ * The most matched vertices one Expand may sweep. A single vertex's expand is already several
+ * requests (both adjacency listings, then every edge and endpoint), so this is the difference
+ * between a click and a thousand-request storm.
+ */
+export declare const EXPAND_SWEEP_CAP = 100;
+/** How many vertices are expanded (or degree-probed) concurrently in one batched round. */
+export declare const INTERACT_BATCH_SIZE = 8;
+/** Which edges a degree comparison counts. */
+export type DegreeSource = "database" | "canvas";
+export type DegreeDirection = "in" | "out" | "total";
+export type DegreeOp = "over" | "under";
+export type SemanticDirection = "closer" | "farther";
+/**
+ * The filters that need no server round trip, so they evaluate live on every render: label and
+ * property read the canvas snapshot, and on-canvas degree counts the edges actually loaded.
+ * A field is INACTIVE when empty, which is why the degree value is a string - "" has to mean
+ * "not filtering", and 0 is a legitimate threshold.
+ */
+export interface CheapFilters {
+    label: string;
+    propKey: string;
+    propTerm: string;
+    degreeSource: DegreeSource;
+    degreeDirection: DegreeDirection;
+    degreeOp: DegreeOp;
+    /** The comparison value as typed; "" (or unparseable) leaves the degree filter inactive. */
+    degreeValue: string;
+}
+/** A degree filter that is actually on: parsed, and known to be the canvas-counted source. */
+export interface ActiveDegree {
+    direction: DegreeDirection;
+    op: DegreeOp;
+    value: number;
+}
+/**
+ * The degree filter as a number, or null when it is not filtering at all. A blank or
+ * unparseable value is inactive rather than 0: typing "over 0" is a real filter and must not be
+ * what an empty box means.
+ */
+export declare function activeDegree(filters: CheapFilters): ActiveDegree | null;
+/** Whether any cheap filter is on, which is what makes an empty match set meaningful. */
+export declare function anyCheapActive(filters: CheapFilters): boolean;
+/** `over` and `under` are strict, so "over 50" excludes a vertex of exactly 50. */
+export declare function compareDegree(degree: number, op: DegreeOp, value: number): boolean;
+/**
+ * The canvas vertices surviving every ACTIVE cheap filter, AND-composed.
+ *
+ * A stub vertex (merged as an edge's unloaded endpoint: no `props`, null label) matches no label
+ * and no property filter, because nothing was ever read about it - but an on-canvas degree filter
+ * counts its loaded edges like any other vertex's, since that is a fact about the view rather
+ * than about the element.
+ *
+ * On-canvas degree delegates to the style engine's `visibleDegrees`, which is what degree-based
+ * node sizing already reads: one home for counting the view's edges.
+ */
+export declare function matchCheap(nodes: CanvasNode[], edges: CanvasEdge[], filters: CheapFilters): CanvasNode[];
+/** The ids whose fetched degree satisfies the comparison; an id with no score is not matched. */
+export declare function applyDegree(degrees: ReadonlyMap<number, number>, op: DegreeOp, value: number): Set<number>;
+/** What a semantic threshold decided, including how much of the input it could not judge. */
+export interface SemanticVerdict {
+    matched: Set<number>;
+    /** Candidates the search returned no score for. They match NOTHING, in either direction. */
+    unscored: number;
+}
+/**
+ * The candidates a semantic threshold keeps, oriented by the search's own metric.
+ *
+ * `higherIsBetter` comes from the server (Cosine/DotProduct: higher is closer; L2: lower is), and
+ * the threshold is in that metric's RAW units - the client never re-derives a similarity.
+ *
+ * A candidate the result carries no score for is UNSCORED and matches neither direction. It has
+ * no embedding, or it fell outside the search window, and either way nothing measured it: "I
+ * could not look" must never become "it is far", least of all in front of a bulk remove.
+ */
+export declare function applySemantic(candidateIds: number[], result: VectorSearchResultREST | null, direction: SemanticDirection, threshold: number): SemanticVerdict;
+/** How far a batched sweep has got, for the panel's progress line. */
+export interface SweepProgress {
+    done: number;
+    total: number;
+}
+/** A degree sweep's answer: what it read, and what it could NOT read. */
+export interface DegreeSweepResult {
+    degrees: Map<number, number>;
+    /**
+     * Candidates whose degree the server would not answer. They are absent from `degrees`, so they
+     * match nothing - and the caller must SAY so, because "0 of 500 match" is otherwise
+     * indistinguishable from "500 vertices measured and none qualified".
+     */
+    unreadable: number;
+}
+/**
+ * Every candidate's DATABASE degree in one direction, batched and abortable.
+ *
+ * `total` costs both requests per vertex; a direction costs one. A vertex whose degree cannot be
+ * read is left OUT of the map rather than recorded as 0, so it fails the comparison instead of
+ * being swept up by "under x" by a bulk remove - and it is COUNTED, which is the half that makes
+ * the rule honest rather than merely safe (the semantic filter's unscored count is the precedent).
+ */
+export declare function degreeSweep(instance: InstanceConfig, ids: number[], options: {
+    direction: DegreeDirection;
+    signal?: AbortSignal;
+    onProgress?: (progress: SweepProgress) => void;
+}): Promise<DegreeSweepResult>;
+/** What an expand sweep actually did, which is never assumed to be "all of it". */
+export interface ExpandOutcome {
+    /** Vertices the sweep ATTEMPTED (its progress position), failures included. */
+    attempted: number;
+    /** Vertices whose neighborhood came back and was merged. `expanded + failed === attempted`. */
+    expanded: number;
+    total: number;
+    /** True when the canvas element ceiling stopped the sweep before the last vertex. */
+    stoppedAtCeiling: boolean;
+    cancelled: boolean;
+    /**
+     * Vertices whose neighborhood fetch threw. NOTE the honest limitation: the neighborhood
+     * primitive swallows per-request HTTP failures and returns empty arrays, so a vertex whose
+     * adjacency the server refused looks exactly like a vertex with no neighbors. This counts only
+     * what reaches us as an exception (a malformed answer), which is why the panel never presents
+     * it as "everything that went wrong" - and why an ABORT is handled by discarding its batch
+     * rather than by counting it here, since an aborted fetch does not throw out of the primitive
+     * either.
+     */
+    failed: number;
+    /**
+     * Vertices where the per-vertex edge cap cut the neighborhood short, so the canvas holds only
+     * part of what they touch. Reported, because the alternative is a hub that looks fully expanded.
+     */
+    truncated: number;
+}
+/**
+ * Expand a set of vertices: one hop each, merged as every batch lands.
+ *
+ * The one home for expand-on-demand. `onMerge` is called per batch rather than once at the end,
+ * so a long sweep grows the canvas visibly and a cancel keeps what already landed. `skip` is
+ * re-read per batch through `liveElementCount`/`skipIds` callbacks rather than captured once,
+ * because each merge changes what the next batch would re-fetch.
+ *
+ * The sweep stops when the canvas reaches `elementCeiling` and SAYS so (`stoppedAtCeiling`), the
+ * same honesty as the whole-graph truncation notice - silently expanding half a match set would
+ * look identical to a graph that simply has fewer neighbors. The signal reaches the fetches
+ * themselves, so a cancel stops issuing requests rather than only stopping the next batch.
+ */
+export declare function expandVertices(instance: InstanceConfig, ids: number[], options: {
+    /** Ids not to re-hydrate, re-read before each batch (the live canvas). */
+    skipIds: () => ReadonlySet<number>;
+    /** Current canvas element count, re-read before each batch. */
+    liveElementCount?: () => number;
+    /** Stop once the canvas holds this many elements. Omitted = no ceiling. */
+    elementCeiling?: number;
+    onMerge: (vertices: VertexREST[], edges: EdgeREST[]) => void;
+    onProgress?: (progress: SweepProgress) => void;
+    signal?: AbortSignal;
+    /** Per-vertex edge cap; defaults to the standing expand cap. */
+    cap?: number;
+}): Promise<ExpandOutcome>;

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

@@ -20,7 +20,7 @@ export declare const FIELD_HELP: {
     readonly lookupKind: "What the id refers to: vertex, edge, or graphelement (either — the server figures out which).";
     readonly maxElements: "Upper bound on how many elements the bulk view loads from GET /graph. Keep it modest on big graphs — this is a browser, not an export (use JSONL export for that).";
     readonly bulkFilter: "Client-side filter over the loaded elements: matches an exact id or a substring of the label.";
-    readonly scanKind: "Property scan walks all elements (no index needed); 'ask an index' picks a registered index and offers the query forms its type answers.";
+    readonly scanKind: "Property scan walks all elements (no index needed); 'ask an index' picks a registered index and offers the query forms its type answers; 'semantic search' types words instead, and the embedding provider turns them into the query vector.";
     readonly propertyScope: "Specific key: scan one named property with an operator and typed literal. Any property: a case-insensitive substring search across EVERY property value (numbers and dates included, compared as text) - a cold, un-indexed full-graph discovery scan.";
     readonly searchTerm: "The substring to look for across every property value, case-insensitively. An element matches when any of its values contains it.";
     readonly searchLabel: "Optional: restrict the search to elements with exactly this label. Leave empty to search every label.";
@@ -50,6 +50,8 @@ export declare const FIELD_HELP: {
     readonly vectorBindEmbeddingName: "Optional: bind this vector index to a named element embedding. A bound index maintains itself as a projection of that embedding — you write embeddings on the elements and the index follows; explicit vector-adds are rejected. Leave empty for a raw (bring-your-own-vector) index.";
     readonly vectorModel: "Optional model-identity string this index expects its vectors to come from (e.g. 'bge-micro-v2#384#Cosine'). The embedding provider refuses to write mismatched vectors; a search whose provider identity differs answers 409. Diagnostic only for a raw index.";
     readonly embeddingSearchText: "Search text. The embedding provider embeds it once (server-side), then runs kNN — you never handle the vector. Needs the provider enabled on this instance.";
+    readonly semanticIndexId: "The vector index the search ranks against. The list is narrowed to the indices that report the vector family, since only they hold vectors to rank; one bound to an embedding name projects that embedding off your elements and maintains itself.";
+    readonly semanticBindEmbedding: "Required here, unlike on the Indexes screen: this index exists so a typed query can rank the embeddings ALREADY on your elements, and only a bound index projects them. Name the embedding they carry ('default' unless you chose otherwise). An unbound index would hold nothing until you pasted vectors into it by hand.";
     readonly embeddingName: "Name of the embedding to read/write on this element, e.g. 'default'. Letters, digits, underscore, dash; max 64 chars. Different names hold independent vectors (and may differ in dimension).";
     readonly embeddingVectorPaste: "The embedding vector, pasted as a JSON array or comma-separated floats. The element is the source of truth; any vector index bound to this name updates automatically on save.";
     readonly embeddingText: "Text to embed onto this element via the server's embedding provider (stored with a model-identity stamp). Needs the provider enabled; otherwise paste a vector.";
@@ -108,6 +110,13 @@ export declare const FIELD_HELP: {
     readonly canvasEdgeLabels: "Show edge-container names on edges (2D: always visible, 3D: on hover). Subject to the same 5,000-element degrade threshold as node labels.";
     readonly canvasEdgeArrows: "Draw arrowheads pointing at each edge's target vertex, making direction visible in both 2D and 3D.";
     readonly saveGameDeleteFiles: "Also delete the checkpoint's files on the server's disk, not just its registry entry. The data is then unrecoverable.";
+    readonly interactLabel: "Match only vertices carrying exactly this label. A vertex the canvas holds only as an edge's endpoint has no label read yet, so it never matches a label filter.";
+    readonly interactProperty: "Match vertices carrying this property key; add a term to require the value to contain it (case-insensitive). This reads the canvas snapshot, which holds scalars only and caps strings at 200 characters, so a term that occurs only past that cap will not match. The Find tab is the server-side search.";
+    readonly interactDegreeSource: "Which edges the degree counts. 'the database' asks the server for the vertex's true degree, one small request per candidate, so it needs Preview. 'edges on canvas' counts only the edges currently loaded: instant, and the number you see, but a vertex you never expanded reads 0 there whatever the database knows.";
+    readonly interactDegree: "Keep vertices whose degree is strictly over (or under) this number, counted in the chosen direction. Leave the number empty to switch the filter off; 0 is a real bound, not 'off'.";
+    readonly interactSemantic: "Keep vertices whose stored embedding is closer (or farther) than a threshold from this text. The provider embeds the text once, then the bound vector index ranks your elements. The threshold is in the index metric's RAW units, exactly as the search reports them: with Cosine/DotProduct a higher score is closer, with L2 a lower one is.";
+    readonly interactDegreeUnreadable: "Vertices whose degree the server would not answer (deleted since they landed on the canvas, or an instance that stopped answering). They are left OUT of the match set rather than counted as 0, so 'under x' cannot sweep up a vertex nobody measured, and they are counted here so a shrunken match set is never mistaken for a measurement.";
+    readonly interactSemanticUnscored: "A canvas vertex the search returned no score for (no embedding stored, or outside the search window) matches NEITHER direction, and the preview counts it. Nothing measured it, so calling it 'far' would remove vertices on no evidence.";
     readonly feedKinds: "Event kinds to show and count. Dimensions combine like the REST filter grammar: AND across dimensions, OR within one. Resync events are exempt and always shown, because they mean continuity was lost.";
     readonly feedElements: "Restrict to vertex or edge events: the elements dimension of the REST filter grammar.";
     readonly feedLabels: "Exact, case-sensitive labels to match (Enter or comma adds one). An element without a label never matches a labels filter, the same rule the server applies.";

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

@@ -0,0 +1,69 @@
+import type { FileLimits } from "../api/types";
+/**
+ * Whether a job's files fit what THIS instance accepts, checked at pick time (feature
+ * integration-file-transport).
+ *
+ * This module is the only place in Studio allowed to reason about file ceilings, and it holds no
+ * numbers of its own. Every ceiling arrives from `GET /integrations/limits` already reconciled with
+ * the proxy's transport bound, so there is one number per question and nothing to combine. That
+ * matters because the version this replaced had a ceiling of its own, about 384 MiB, which sat
+ * BELOW the instance's: jobs the instance would have accepted were refused in the browser, and no
+ * amount of configuration could fix it.
+ *
+ * The corollary is the rule for the unknown case. An instance too old to serve the route, or one
+ * whose integrations capability is off, leaves the limits undefined, and then NOTHING is checked
+ * and nothing is guessed: the send goes ahead and the instance refuses it if it must. A default
+ * substituted here would be the same bug again.
+ */
+/** Enough of a file to check it, whichever transport carries it later. */
+export interface SizedFile {
+    name: string;
+    size: number;
+}
+/**
+ * The ceilings, or their absence. Absence has three spellings and they all mean the same thing
+ * here: the query has not answered yet, it failed, or the instance answered with no body.
+ */
+export type MaybeLimits = FileLimits | null | undefined;
+/**
+ * What one file setting is being asked to hold, and what the rest of the job already holds.
+ *
+ * Generic over the incoming type, so a caller passing real `File` handles gets `File`s back with no
+ * cast. That is not cosmetic: it is what makes "this only ever filters, it never constructs" a fact
+ * the compiler holds rather than a comment somebody has to keep true.
+ */
+export interface StagingRequest<T extends SizedFile = SizedFile> {
+    /** The ceilings this instance published, or absent when they could not be read. */
+    limits: MaybeLimits;
+    /** The files being added to ONE file setting, in the order they were picked. */
+    incoming: T[];
+    /** What that setting already holds. Kept whatever this verdict says. */
+    staged?: SizedFile[];
+    /** What every OTHER file setting of the same job holds: the total and the count are job-wide. */
+    elsewhere?: SizedFile[];
+    /** True when the setting declares `multiple`, so its files are read as ONE claimed set. */
+    claimedSet?: boolean;
+}
+export interface StagingVerdict<T extends SizedFile = SizedFile> {
+    /** The incoming files that may be staged, in pick order. */
+    accepted: T[];
+    /** One message for the setting's problem channel, or null when there is nothing to say. */
+    problem: string | null;
+}
+/**
+ * The refusal that keeps a set out of the tab before it is ever sent.
+ *
+ * Granularity differs between the three ceilings on purpose. A file over the per-file ceiling is
+ * individually too big, so it is refused individually and its siblings still stage. A broken TOTAL
+ * or COUNT is a property of the whole job, so no single file is at fault and none of the incoming
+ * batch is accepted: picking some arbitrary prefix that fits would drop the tail on a decision the
+ * person picking never made, and for a claimed set it would silently split the set.
+ */
+export declare function checkStaging<T extends SizedFile>(request: StagingRequest<T>): StagingVerdict<T>;
+/**
+ * What the form says when it could not read the ceilings. Its job is to stop someone reading the
+ * absence of refusals as approval, without naming a number Studio does not know.
+ */
+export declare const LIMITS_UNKNOWN_NOTE: string;
+/** The ceilings in one line, for the form to state up front rather than only when refusing. */
+export declare function describeLimits(limits: MaybeLimits): string;

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

@@ -2,6 +2,14 @@
 export declare function formatCompact(value: number): string;
 /** Full number with grouping, for exact values ("10,001,000"). */
 export declare function formatExact(value: number): string;
+/**
+ * A size in bytes, in binary units up to GiB ("0 B", "512 B", "1.5 KiB", "5.8 GiB").
+ *
+ * GiB and not MiB because two callers need it: a save-game registry, and the refusal that tells
+ * someone their several gibibytes of files are over the ceiling. Reporting that in mebibytes is arithmetic
+ * the reader should not have to do while being told no.
+ */
+export declare function formatBytes(bytes: number): string;
 /**
  * The one glyph this UI renders for a value the server does not have, so a row cannot mix two
  * spellings of "absent" in one table and read as two different states.

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

@@ -41,8 +41,22 @@ export declare function capList<T>(items: readonly T[], max?: number): {
     shown: T[];
     total: number;
 };
+/**
+ * How tall ONE row is, in rem, for a list whose rows are not a single line. The cap is a row
+ * COUNT, so it needs a height per row to work with; the CSS default (2.5rem, see index.css) is a
+ * one-line table row, and a list of wrapped prose hits that ceiling several rows early and scrolls
+ * a list far shorter than its threshold. Add an entry only for a list that reads that way.
+ */
+export declare const SCROLL_ROW_REM: {
+    /**
+     * Available integrations (IntegrationsScreen): each row is a sentence describing what the
+     * integration reads, and it wraps to three or four lines on a narrow window.
+     */
+    readonly integrations: 5;
+};
 /**
  * Inline style that tells a `.scroll-list` wrapper how many rows to show before it caps its
- * height and scrolls. Custom CSS properties need the cast; this keeps it in one place.
+ * height and scrolls, and optionally how tall to assume one row is (see {@link SCROLL_ROW_REM};
+ * omitted, the CSS default applies). Custom CSS properties need the cast; this keeps it in one place.
  */
-export declare function scrollRows(rows: number): CSSProperties;
+export declare function scrollRows(rows: number, rowRem?: number): CSSProperties;

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

@@ -0,0 +1,26 @@
+import type { ChatProviderStatsREST, EmbeddingProviderStatsREST } from "../api/types";
+/**
+ * How Studio names the model backend that serves a request (feature model-providers).
+ *
+ * Two kinds of label, and the distinction is the feature:
+ * - AMBIENT ("requests will go to X") reads the polled /status block, which describes the
+ *   CURRENT configuration. {@link chatAmbientLabel} is named so a call site cannot use it by
+ *   accident where a per-call answer belongs.
+ * - PER-CALL reads the `backend` field carried on that call's own response. A draft produced
+ *   under one backend must keep saying so after the operator switches, so nothing per-call may
+ *   be derived from here.
+ *
+ * Neither function invents a name it cannot know: an absent field yields a sentence saying the
+ * value is absent, never a plausible default.
+ */
+/**
+ * The ambient chat destination: `"{backend} · {model}"`, or the reason there is no pair to show.
+ * `undefined` means /status has not answered yet, which is a different thing from chat being off.
+ */
+export declare function chatAmbientLabel(chat: ChatProviderStatsREST | null | undefined): string;
+/**
+ * The embedding function's identity as a reader recognises it: `modelName[@modelVersion]`.
+ * A provider that reports no model name is described by its dimension instead, because that is
+ * the one property of the vector space still known to be true.
+ */
+export declare function embeddingStamp(provider: EmbeddingProviderStatsREST): string;

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

@@ -25,6 +25,7 @@ export interface Neighborhood {
 export declare function fetchVertexNeighborhood(instance: InstanceConfig, vertexId: number, options: {
     cap: number;
     skipNeighborIds?: ReadonlySet<number>;
+    signal?: AbortSignal;
 }): Promise<Neighborhood>;
 /**
  * An edge's endpoint vertices plus EVERY edge between them, both directions — found by

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

@@ -0,0 +1,49 @@
+import type { EmbeddingProviderStatsREST, PropertySpecification } from "../api/types";
+/**
+ * What a NEW vector index is created with, in one place: two screens create one (the Indexes
+ * screen's create panel and the Query screen's semantic on-ramp, feature
+ * semantic-search-onramp) and the numbers are not a preference. A bound index whose dimension
+ * or metric disagrees with the model writing into it is refused on every later embed and every
+ * later search, so the provider is the authority and guessing it twice is how the two copies
+ * would drift.
+ */
+/**
+ * Fallbacks for a server that reports no usable provider. Not a recommendation: a shape the
+ * engine accepts, so the form has something to submit while saying (at the call site) that
+ * these are defaults rather than the instance's own numbers.
+ */
+export declare const VECTOR_INDEX_FALLBACK: {
+    readonly dimension: "384";
+    readonly metric: "Cosine";
+};
+export interface VectorIndexDefaults {
+    /** The provider is on AND names a dimension, so its numbers are the authoritative ones. */
+    providerReady: boolean;
+    dimension: string;
+    metric: string;
+}
+/** The dimension + metric a new vector index should default to on this instance. */
+export declare function vectorIndexDefaults(provider: EmbeddingProviderStatsREST | null | undefined): VectorIndexDefaults;
+/** The engine's own bounds on a vector index's dimension (VectorIndex.Initialize). */
+export declare const VECTOR_DIMENSION_RANGE: {
+    readonly min: 1;
+    readonly max: 4096;
+};
+/**
+ * Whether this dimension is one the engine will take. The number input's `min`/`max` are not
+ * enough on their own: neither attribute blocks an EMPTY field, and neither is consulted at all
+ * unless the button is a submit. An empty value travels as `propertyValue: ""` against
+ * `System.Int32`, which the server cannot convert, so the round trip is spent to be told so.
+ */
+export declare function isValidVectorDimension(dimension: string): boolean;
+/**
+ * The `pluginOptions` of POST /index for a vector index. Options travel as typed literals
+ * (vector-index README §creation), and embeddingName/model are emitted only when set, so a raw
+ * index keeps exactly the two-option shape (pinned by index-management.test.tsx).
+ */
+export declare function vectorIndexPluginOptions(options: {
+    dimension: string;
+    metric: string;
+    embeddingName?: string;
+    model?: string;
+}): Record<string, PropertySpecification>;

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

@@ -0,0 +1,19 @@
+/**
+ * The engine's own ceiling on a kNN `k`, mirrored client-side.
+ *
+ * ONE home, because every caller of `/scan/index/vector` and `/embedding/search` has to agree with
+ * the server or the request is refused outright: `VectorIndex.MaxK` is 1024 and
+ * `VectorIndex.TryNearestNeighbors` rejects anything above it, which the embedding controller
+ * turns into a 400 AFTER the provider has already embedded the query text. So a k picked from some
+ * other quantity does not degrade, it fails, and it fails having spent a model call.
+ *
+ * That is not hypothetical: the canvas Interact tab first shipped this asking for the canvas
+ * element cap (20,000) worth of neighbours, which made its semantic filter unusable on every real
+ * instance while every mocked test passed.
+ */
+export declare const MAX_K = 1024;
+/**
+ * A kNN window that cannot exceed the engine's ceiling, for a caller who wants "as many as I might
+ * need" rather than a number a person typed. `wanted` is what the caller would ideally ask for.
+ */
+export declare function boundedK(wanted: number): number;

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

@@ -98,13 +98,23 @@ export interface PathDraft {
     semantic: SemanticDraft;
 }
 export declare const DEFAULT_PATH_DRAFT: PathDraft;
+/** The Query screen's three ways of asking (feature index-workspace / semantic-search-onramp). */
+export declare const QUERY_MODES: readonly ["property", "index", "semantic"];
+export type QueryMode = (typeof QUERY_MODES)[number];
 /**
  * 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";
+    /**
+     * "semantic" is text-in kNN (feature semantic-search-onramp): its own mode rather than a
+     * source toggle inside the index mode's vector form, because a capability reachable only
+     * after picking the right index is one nobody finds. It shares the kNN parameters below
+     * with that form - same question, different query source - but NOT the index, which is
+     * drawn from a different set (see semanticIndexId).
+     */
+    mode: QueryMode;
     /** Property-scan scope: one named "key" (typed operator) or "any" property (contains search). */
     propertyScope: "key" | "any";
     propertyId: string;
@@ -113,6 +123,13 @@ export interface QueryDraft {
     /** All-property search label restrictor (propertyScope === "any"); empty scans every label. */
     searchLabel: string;
     indexId: string;
+    /**
+     * The semantic mode's index, kept apart from `indexId` because the two modes choose from
+     * different sets: every registered index there, only the ones that can rank a vector here.
+     * Sharing one field meant picking a vector index for a semantic search silently replaced the
+     * operator's index-mode selection AND the query form that went with it.
+     */
+    semanticIndexId: string;
     form: IndexCapability;
     operator: BinaryOperatorName;
     resultType: "Vertices" | "Edges" | "Both";
@@ -124,14 +141,23 @@ export interface QueryDraft {
     fulltextQuery: string;
     spatialElementId: string;
     spatialDistance: string;
+    /** The pasted query vector (index mode, vector form); the semantic mode never uses it. */
     vectorText: string;
     vectorK: string;
     vectorKind: "any" | "vertex" | "edge";
     vectorLabel: string;
-    vectorSource: "vector" | "text";
+    /** The query text of the semantic mode, embedded once server-side. */
     vectorSearchText: string;
 }
 export declare const DEFAULT_QUERY_DRAFT: QueryDraft;
+/**
+ * Rehydrates a persisted Query draft. Text-in kNN used to be a `vectorSource` toggle INSIDE the
+ * index mode's vector form; feature semantic-search-onramp made it its own mode, so a draft
+ * written by an older build is LIFTED rather than dropped: the text, k, kind and label are the
+ * same question asked the same way, and only the route to the form changed. The stale key is
+ * stripped instead of spread through, so nothing carries a field this build has no meaning for.
+ */
+export declare function migrateQueryDraft(persisted: Partial<QueryDraft> | undefined): 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
@@ -194,9 +220,17 @@ export declare const DEFAULT_ANALYTICS_DRAFT: AnalyticsDraft;
  * state (re-run on demand), exactly like every other result in the studio - only the inputs here
  * persist.
  */
+/**
+ * The tabs of the canvas tool strip, in strip order. ONE home for the ids: the strip renders them
+ * and the persisted `canvasToolsDraft.tab` is validated against them on rehydration.
+ */
+export declare const CANVAS_TABS: readonly ["style", "find", "connect", "interact"];
+export type CanvasTab = (typeof CANVAS_TABS)[number];
+/** Guard for the untrusted source of a canvas tab id: persisted storage. */
+export declare const isCanvasTab: (value: unknown) => value is CanvasTab;
 export interface CanvasToolsDraft {
-    /** Which right-panel tab is active: styling, element search, or path connecting. */
-    tab: "style" | "find" | "connect";
+    /** Which right-panel tab is active: styling, element search, path connecting, or interacting. */
+    tab: CanvasTab;
     /** Find: the all-property contains term (fed to POST /scan/graph/properties). */
     findTerm: string;
     /** Find: optional exact-match label restrictor; empty searches every label. */
@@ -207,6 +241,25 @@ export interface CanvasToolsDraft {
     connectMaxDepth: number;
     /** Connect: use every canvas vertex, or only a picked subset, as the pair endpoints. */
     connectScope: "all" | "pick";
+    /**
+     * Interact (feature canvas-interact): the filter rows that build the match set the tab's two
+     * verbs act on. Every one is INACTIVE when blank - which is why the two numeric thresholds are
+     * strings, since 0 is a legitimate degree bound and "" has to mean "not filtering" - and with
+     * none of them active the match set is every canvas vertex, i.e. "expand all".
+     */
+    interactLabel: string;
+    interactPropKey: string;
+    interactPropTerm: string;
+    /** Which edges the degree comparison counts: the database's answer, or the loaded ones. */
+    interactDegreeSource: "database" | "canvas";
+    interactDegreeDirection: "in" | "out" | "total";
+    interactDegreeOp: "over" | "under";
+    interactDegreeValue: string;
+    interactSemanticText: string;
+    interactSemanticIndexId: string;
+    interactSemanticDirection: "closer" | "farther";
+    /** The threshold in the metric's RAW units, as typed (blank = the filter is off). */
+    interactSemanticThreshold: string;
 }
 export declare const DEFAULT_CANVAS_TOOLS_DRAFT: CanvasToolsDraft;
 /** One-shot navigation intent: "open Query with this index preselected" (cleared on consume). */
@@ -269,6 +322,8 @@ export interface WorkspaceState {
     scanPrefill: ScanPrefill | null;
     mergeIntoCanvas: (vertices: VertexREST[], edges: EdgeREST[]) => void;
     removeFromCanvas: (kind: "node" | "edge", id: number) => void;
+    /** Removes a SET of vertices (and their incident edges) in one write - see the implementation. */
+    removeManyFromCanvas: (ids: readonly number[]) => void;
     clearCanvas: () => void;
     setWholeGraphTruncation: (truncation: WholeGraphTruncation | null) => void;
     setStyleConfig: (patch: Partial<StyleConfig>) => void;

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

@@ -1,5 +1,5 @@
 import type { InstanceConfig } from "../instances/types";
-import type { IntegrationProvider } from "../api/types";
+import type { FileLimits, IntegrationProvider } from "../api/types";
 /**
  * The integrations capability of one instance (feature integrations), read from the one route that
  * answers it: the provider catalog.
@@ -15,8 +15,28 @@ import type { IntegrationProvider } from "../api/types";
  */
 export type IntegrationsCapability = "checking" | "available" | "absent" | "unreachable";
 export declare function useIntegrationProviders(instance: InstanceConfig | null): import("@tanstack/react-query").UseQueryResult<NoInfer<IntegrationProvider[] | null>, unknown>;
+/**
+ * What a job may carry on this instance (feature integration-file-transport). Read once per
+ * instance and held for the session: the ceilings come from configuration, so they change when the
+ * instance is redeployed and never while a screen is open.
+ *
+ * It fails softly on purpose. An instance too old to serve the route answers 404, and a form that
+ * cannot read the ceilings must check NOTHING rather than fall back to a number of its own - see
+ * `lib/fileLimits.ts`, which is the only place allowed to interpret the absence.
+ */
+export declare function useIntegrationLimits(instance: InstanceConfig | null): import("@tanstack/react-query").UseQueryResult<NoInfer<FileLimits | null>, unknown>;
 /** Whether a failure is the capability being off rather than the instance being unwell. */
 export declare function isCapabilityRefusal(error: unknown): boolean;
+/**
+ * The href for a provider's documentation link, or null when there is nothing safe to link.
+ *
+ * The runtime refuses anything but an absolute http(s) URL when it builds its catalog, so this is
+ * the second half of that check rather than the only one: the descriptor arrives over the network
+ * from a deployable Studio does not ship with, and a `javascript:` href here would run in the
+ * operator's browser. Anything else is dropped silently - the row simply carries no link, which is
+ * the same state as a provider that declares no documentation.
+ */
+export declare function docsHref(provider: Pick<IntegrationProvider, "docsUrl">): string | null;
 /** The capability verdict of a providers query, for the rail and for a deep link. */
 export declare function capabilityOf(query: {
     isError: boolean;

package/dist-lib/{typescript-LNGesWYR.js → typescript-BqWn12P7.js}

@@ -1,4 +1,4 @@
-import { m as s } from "./index-BQbFjItv.js";
+import { m as s } from "./index-CGOXemLg.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-BuD_-6ib.js → xml-BkH9m6gQ.js}

@@ -1,4 +1,4 @@
-import { m as r } from "./index-BQbFjItv.js";
+import { m as r } from "./index-CGOXemLg.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-DCzPbyTS.js → yaml-DURIwCnM.js}

@@ -1,4 +1,4 @@
-import { m as l } from "./index-BQbFjItv.js";
+import { m as l } from "./index-CGOXemLg.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.37",
+  "version": "0.0.39",
   "description": "F8 Studio - browser frontend for Fallen-8 instances, and its graph canvas as a standalone component",
   "license": "MIT",
   "author": "Henning Rauch",