@fallen-8/studio 0.0.32

package/dist-lib/types/delegate/snippets.d.ts

@@ -0,0 +1,25 @@
+import type { DelegateKind } from "../api/types";
+/**
+ * Snippet library (FR-22), mirroring the prototype's set. Each entry names the kinds it
+ * fits; the NL assist reuses the matching entries as required few-shot examples
+ * (nl-assist spec FR-26.5).
+ */
+export interface Snippet {
+    title: string;
+    description: string;
+    kinds: DelegateKind[];
+    code: string;
+}
+export declare const SNIPPET_LIBRARY: Snippet[];
+export declare function snippetsForKind(kind: DelegateKind): Snippet[];
+/**
+ * Rewrites a fragment's parameter identifier to the slot's parameter name so inserting
+ * "Label match" into an EdgeFilter yields `return (e) => e.Label == ...`. Every fragment
+ * shown to the user or the NL model must go through this - a `v` example in a `ge` slot
+ * is exactly the mismatch that made phi4-mini wrap the idiom in an inline-invoked lambda
+ * (field failure, 2026-07-17). It only rewrites identifier-with-dot occurrences (plus the
+ * parameter list), so keep fragment string literals free of `v.`/`e.`/`ge.`/`p.` and
+ * dot-less parameter references out of cross-kind fragments.
+ */
+export declare function rewriteParameterName(code: string, parameterName: string): string;
+export declare function snippetCodeFor(snippet: Snippet, parameterName: string): string;

package/dist-lib/types/embed/F8GraphCanvas.d.ts

@@ -0,0 +1,37 @@
+import { type Ref } from "react";
+import { type ElementRef, type F8GraphCanvasHandle } from "../canvas/GraphCanvas";
+import { type StyleConfig } from "../canvas/styleConfig";
+import type { CanvasEdge, CanvasNode } from "../state/instanceStore";
+import type { PathREST } from "../api/types";
+import { type ThemeTokens } from "../app/studioConfig";
+/**
+ * The component-level embed (feature studio-embeddable): Studio's graph canvas as a
+ * standalone, data-in/callback-out component for host pages that want an interactive graph
+ * without mounting all of Studio. This prop shape is the FROZEN public contract - changing
+ * `CanvasNode`/`CanvasEdge`/`StyleConfig`/`ElementRef` in a breaking way breaks hosts, which
+ * is why it stays the minimal surface GraphCanvas actually reads (internal-only props such
+ * as the adjacency-preview emphasis set are deliberately not part of it).
+ */
+export interface F8GraphCanvasProps {
+    nodes: Record<number, CanvasNode>;
+    edges: Record<number, CanvasEdge>;
+    /** Style rules + renderer choice; defaults to Studio's canvas defaults. */
+    config?: StyleConfig;
+    /** A path result to spotlight (members highlighted, the rest dimmed). */
+    pathOverlay?: PathREST | null;
+    /** Transient node spotlight (the "eclipse" corona). */
+    highlight?: ElementRef | null;
+    onSelect?: (ref: ElementRef | null) => void;
+    /** Token overrides for this embed; anything omitted keeps Studio's dark defaults. */
+    theme?: Partial<ThemeTokens>;
+    /**
+     * Camera handle (feature canvas-host-controls): `fitToView`, `getCameraRatio`,
+     * `setCameraRatio`. Optional like everything else here, and attaching it changes no rendering.
+     */
+    ref?: Ref<F8GraphCanvasHandle>;
+}
+/**
+ * Renders inside its own `.f8-studio` scope root, so the canvas styling works on a page
+ * that never mounted the Studio shell. Sized by the host: the wrapper fills its parent.
+ */
+export declare function F8GraphCanvas({ nodes, edges, config, pathOverlay, highlight, onSelect, theme, ref, }: F8GraphCanvasProps): import("react").JSX.Element;

package/dist-lib/types/embed/canvas.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The canvas-only export surface, published as the package subpath `./canvas`. This is the
+ * ONE home for what a canvas host may import; the whole-Studio entry (index.ts) re-exports
+ * this list rather than repeating it, so the two entries can never drift.
+ *
+ * Why a second entry exists: importing the canvas from the main entry drags the app shell's
+ * module graph (the Monaco editor above all) into the host's bundle. A host that wants a
+ * graph and nothing else imports `@fallen-8/studio/canvas` and pays for the graph only -
+ * scripts/check-lib-artifact.mjs fails the build if the editor leaks back in.
+ */
+export { F8GraphCanvas, type F8GraphCanvasProps } from "./F8GraphCanvas";
+export type { ElementRef, F8GraphCanvasHandle } from "../canvas/GraphCanvas";
+export { DEFAULT_STYLE_CONFIG } from "../canvas/styleConfig";
+export type { StyleConfig } from "../canvas/styleConfig";
+export type { CanvasEdge, CanvasNode } from "../state/instanceStore";
+export type { PathREST } from "../api/types";
+export type { ThemeTokens } from "../app/studioConfig";
+/**
+ * The documented default magnitudes. A host that computes its own sizes (say, scaling with
+ * its container) needs to know what it is scaling FROM, so the defaults are part of the
+ * contract rather than private constants.
+ */
+export { EDGE_LABEL_SIZE_DEFAULT, EDGE_WIDTH_DEFAULT, EDGE_WIDTH_RANGE, LABEL_SIZE_DEFAULT, NODE_SIZE_DEFAULT, NODE_SIZE_RANGE, PATH_EDGE_MIN_WIDTH, PATH_NODE_MIN_SIZE, } from "../canvas/styleEngine";

package/dist-lib/types/embed/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The whole-Studio export surface (feature studio-embeddable). What a host may import is
+ * exactly what is re-exported here - the packaging phase turns this module into the library
+ * entry point, so anything not on this list is internal. Spec:
+ * features/done/studio-embeddable/spec.md.
+ *
+ * The canvas half of the surface is NOT repeated here: ./canvas owns it (and is published as
+ * the package's "./canvas" subpath for hosts that want the graph without the app shell), so
+ * the two entries cannot drift.
+ */
+export { mountStudio, F8Studio } from "../app/mount";
+export type { StudioConfig } from "../app/studioConfig";
+export type { InstanceAuth, InstanceConfig } from "../instances/types";
+export * from "./canvas";

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

@@ -0,0 +1,10 @@
+/**
+ * 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 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;

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

@@ -0,0 +1,22 @@
+/**
+ * The first-run show (feature studio-first-run): a short, mostly-passive, code-driven animated
+ * walkthrough of Fallen-8's five core capabilities (graph, path, analytics, subgraph, vectors)
+ * on the canned {@link MOCK_GRAPH}, ending on an opt-in handoff.
+ *
+ * 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.
+ */
+export interface FirstRunShowProps {
+    /** "auto" = inline empty-state on the Dashboard; "replay" = manual overlay. Used only for labels. */
+    variant: "auto" | "replay";
+    /** Dismiss into the app (auto: remember dismissal; replay: close the overlay). */
+    onExplore: () => void;
+    /** Jump to the Sample gallery (the newcomer's path from empty to a populated, curated graph). */
+    onBrowseSamples: () => void;
+    /** Point the user at the JSONL import location. */
+    onImport: () => void;
+}
+export declare function FirstRunShow({ variant, onExplore, onBrowseSamples, onImport }: FirstRunShowProps): import("react").JSX.Element;

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

@@ -0,0 +1,23 @@
+/**
+ * The first-run show's beats (feature studio-first-run). One line of real-text caption per beat
+ * (never baked into an image), an endpoint shown as text only, and a story tie-in drawn from the
+ * "Asymmetric Cyber Warfare" mock graph. All copy is concise and uses no em dashes.
+ *
+ * Beats run at 10s each so a newcomer can read each one; the show is skippable and steppable
+ * (Prev/Next/dots), so the length is a comfortable ceiling, not a wait.
+ */
+export type BeatId = "bloom" | "path" | "rank" | "subgraph" | "semantic";
+export interface Beat {
+    id: BeatId;
+    /** Short label for the progress dots / navigation. */
+    title: string;
+    caption: string;
+    /** The real REST endpoint, shown as monospace text only (the show never calls it). */
+    endpoint?: string;
+    /** A one-line story tie-in for this beat. */
+    note?: string;
+    durationMs: number;
+}
+export declare const BEATS: readonly Beat[];
+/** Stable reference for the timeline hook's effect dependency. */
+export declare const BEAT_DURATIONS: readonly number[];

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

@@ -0,0 +1,38 @@
+/**
+ * First-run show state (feature studio-first-run).
+ *
+ * `dismissed` remembers, per bound namespace key (`<instanceId>/<ns>`), that the newcomer
+ * dismissed the auto-show so a returning user is not nagged on a graph that has simply stayed
+ * empty. It is cleared the moment the namespace is observed non-empty, so the show auto-shows
+ * again if the graph genuinely empties later. Only this map is persisted.
+ *
+ * `replayOpen` is the transient manual-replay overlay flag (never persisted): the persistent
+ * rail control opens the same <FirstRunShow> from anywhere, ignoring `dismissed`.
+ */
+export interface FirstRunState {
+    dismissed: Record<string, boolean>;
+    replayOpen: boolean;
+    /** Auto-show path only: remember the newcomer dismissed the show for this namespace. */
+    dismiss: (key: string) => void;
+    /** Re-arm the auto-show for a namespace once it is seen non-empty (called on populate). */
+    clearIfPopulated: (key: string) => void;
+    openReplay: () => void;
+    closeReplay: () => void;
+}
+export declare const useFirstRun: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<FirstRunState>, "setState" | "persist"> & {
+    setState(partial: FirstRunState | Partial<FirstRunState> | ((state: FirstRunState) => FirstRunState | Partial<FirstRunState>), replace?: false | undefined): unknown;
+    setState(state: FirstRunState | ((state: FirstRunState) => FirstRunState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<FirstRunState, {
+            dismissed: Record<string, boolean>;
+        }, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: FirstRunState) => void) => () => void;
+        onFinishHydration: (fn: (state: FirstRunState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<FirstRunState, {
+            dismissed: Record<string, boolean>;
+        }, unknown>>;
+    };
+}>;

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

@@ -0,0 +1,56 @@
+/**
+ * The first-run show's canned mock graph (feature studio-first-run): "Asymmetric Cyber Warfare".
+ *
+ * A tiny, story-driven graph: an elite threat actor weaponizes a compromised supply-chain tool
+ * to strike multiple targets, while a SOC and its analyst defend. Six entities, five directed
+ * relationships. It tells the graph pitch in one glance: the full blast radius of a compromise
+ * is a single native traversal here, versus brittle multi-table joins in a relational store.
+ *
+ * This is the show's ASSET SEAM: pure, hardcoded data drawn as SVG by <FirstRunShow>. It is
+ * never the user's data and is never read from or written to the engine. The same graph ships
+ * as a loadable sample (scripts/samples/cyberWarfare.ts); a designer who later produces a
+ * Lottie/.riv can replace the code animation behind this boundary without touching the
+ * empty-state detection or the replay wiring.
+ *
+ * Positions are laid out by hand in the viewBox so the attack fans out left-to-right and the
+ * defenders sit below. `rank` is a precomputed mock PageRank (0..1) that drives the analytics
+ * beat's sizing; `emoji` is the node glyph.
+ */
+export interface MockVertex {
+    id: number;
+    label: string;
+    emoji: string;
+    x: number;
+    y: number;
+    rank: number;
+}
+export interface MockEdge {
+    id: string;
+    source: number;
+    target: number;
+    label: string;
+}
+export interface MockGraph {
+    viewBox: string;
+    vertices: readonly MockVertex[];
+    edges: readonly MockEdge[];
+    /** Path beat: the highlighted route (the attack's blast radius), as an ordered vertex-id list. */
+    path: readonly number[];
+    /** Subgraph beat: the member vertex ids; member edges are those with both endpoints inside. */
+    subgraph: readonly number[];
+    /** Semantic beat: the query point, the "nearest" vertices, and the neighbor expanded into. */
+    semantic: {
+        query: {
+            x: number;
+            y: number;
+        };
+        nearest: readonly number[];
+        expandFrom: number;
+        expandTo: number;
+    };
+}
+export declare const MOCK_GRAPH: MockGraph;
+/** Whether an edge lies on the highlighted path (directed, consecutive), for the path beat. */
+export declare function isPathEdge(edge: MockEdge, path: readonly number[]): boolean;
+/** Whether an edge is inside the subgraph (both endpoints are members), for the subgraph beat. */
+export declare function isSubgraphEdge(edge: MockEdge, subgraph: readonly number[]): boolean;

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

@@ -0,0 +1,35 @@
+export interface Timeline {
+    /** The active beat index while playing, or null once the show has settled on the handoff. */
+    beat: number | null;
+    /** True once the show has settled: it finished playing, was skipped, or reduced-motion. */
+    resting: boolean;
+    /** True while the tab is hidden (motion is held so the show never runs past unseen). */
+    paused: boolean;
+    /** True while auto-advancing; manual navigation turns it off, Replay turns it back on. */
+    autoplay: boolean;
+    /** Step to the next beat (or the handoff after the last one). Pauses autoplay. */
+    next: () => void;
+    /** Step to the previous beat. Pauses autoplay. */
+    prev: () => void;
+    /** Jump directly to a beat by index. Pauses autoplay. */
+    goTo: (index: number) => void;
+    /** Jump straight to the handoff. Pauses autoplay. */
+    skip: () => void;
+    /** Restart from beat 0 and resume auto-advancing. */
+    replay: () => void;
+}
+/**
+ * Drives the first-run show's beat sequence (feature studio-first-run). Advances one beat at a
+ * time on `durations`, settling on the handoff (index === beatCount) after the last beat.
+ *
+ * - Auto-advances only while `autoplay` is on. Any manual navigation (next/prev/goTo/skip) turns
+ *   autoplay off so the timer never yanks the view while the user is exploring; Replay turns it
+ *   back on from the top.
+ * - Pauses while the tab is hidden (`visibilitychange`) so the show never plays unseen; on return
+ *   the current beat's timer restarts from full (pausing, not to-the-millisecond resume).
+ * - Under `reducedMotion` it opens already settled on the handoff with autoplay off (no motion),
+ *   yet the user can still step through the beats manually (the CSS neutralizes their motion).
+ *
+ * `durations` must be a stable reference (a module constant) - it is an effect dependency.
+ */
+export declare function useBeatTimeline(beatCount: number, durations: readonly number[], reducedMotion: boolean): Timeline;

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

@@ -0,0 +1,7 @@
+/**
+ * Tracks the OS "reduce motion" preference (feature studio-first-run). Guards against a
+ * missing `matchMedia` (jsdom under vitest) by reading `false` there, and subscribes so a
+ * live preference change re-renders. In reduced-motion the show renders its rested final
+ * state instead of autoplaying.
+ */
+export declare function useReducedMotion(): boolean;

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

@@ -0,0 +1,83 @@
+import type { InstanceConfig } from "./types";
+/**
+ * Global instance registry (FR-1a) + the single active instance (FR-1b).
+ * Persisted in local storage; per-instance workspace state lives elsewhere
+ * (state/instanceStore.ts) keyed by instance id (FR-1c).
+ */
+export declare const DEFAULT_NAMESPACE = "default";
+export interface RegistryState {
+    instances: InstanceConfig[];
+    activeId: string | null;
+    /** The active namespace per instance id (feature graph-namespaces); absent = "default". */
+    activeNamespaces: Record<string, string>;
+    /**
+     * Whether an instance's server supports namespaces (probed via GET /ns): true/false once
+     * known, absent while unknown. A pre-namespace server (false) gets UNBOUND instances —
+     * bare paths — so the previous release keeps working instead of 404ing on /ns/default.
+     */
+    namespaceSupport: Record<string, boolean>;
+    addInstance: (instance: Omit<InstanceConfig, "id">) => InstanceConfig;
+    updateInstance: (id: string, patch: Partial<Omit<InstanceConfig, "id">>) => void;
+    removeInstance: (id: string) => void;
+    setActive: (id: string) => void;
+    setActiveNamespace: (instanceId: string, namespace: string) => void;
+    setNamespaceSupport: (instanceId: string, supported: boolean) => void;
+}
+/**
+ * The data-plane endpoint injected by config.js (feature standalone-ui): a classic
+ * `<script src="/config.js">` sets `window.__F8_CONFIG__` before this module evaluates, so a
+ * standalone Studio build can be pointed at any REST origin at container start. Absent or empty
+ * means same-origin (the all-in-one default). Read through normalizeBaseUrl so a trailing slash in
+ * F8_API_URL cannot corrupt buildUrl concatenation, and as a function (not an inline const) so it
+ * stays unit-testable after the global is set.
+ */
+export declare function configuredApiUrl(): string;
+/** The instance the app is served from - always available, never removable by accident. */
+export declare const SAME_ORIGIN_INSTANCE: InstanceConfig;
+export declare function isManagedInstance(id: string): boolean;
+export declare const useRegistry: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<RegistryState>, "setState" | "persist"> & {
+    setState(partial: RegistryState | Partial<RegistryState> | ((state: RegistryState) => RegistryState | Partial<RegistryState>), replace?: false | undefined): unknown;
+    setState(state: RegistryState | ((state: RegistryState) => RegistryState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<RegistryState, {
+            instances: InstanceConfig[];
+            activeId: string | null;
+            activeNamespaces: Record<string, string>;
+        }, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: RegistryState) => void) => () => void;
+        onFinishHydration: (fn: (state: RegistryState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<RegistryState, {
+            instances: InstanceConfig[];
+            activeId: string | null;
+            activeNamespaces: Record<string, string>;
+        }, unknown>>;
+    };
+}>;
+/**
+ * Re-point and re-hydrate the registry after a mount set its StudioConfig (feature
+ * studio-embeddable). The store is created at module import, before any config exists, so a
+ * host mount re-runs persistence against the (possibly prefixed) storage key; `merge` above
+ * then injects the host's managed instances and applies its activeInstanceId/namespace knobs.
+ * The standalone mount runs this too, with the default config it is a no-op re-hydration.
+ */
+export declare function applyStudioConfigToRegistry(): Promise<void>;
+/** The active instance's active namespace (feature graph-namespaces); "default" until set. */
+export declare function useActiveNamespace(): string;
+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
+ * results, drafts and canvas state never cross namespaces.
+ */
+export declare function useInstanceStore(): {
+    instance: InstanceConfig;
+    store: {
+        (): import("../state/instanceStore").WorkspaceState;
+        <U>(selector: (state: import("../state/instanceStore").WorkspaceState) => U): U;
+    } & import("zustand").StoreApi<import("../state/instanceStore").WorkspaceState>;
+};

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

@@ -0,0 +1,49 @@
+/**
+ * Instance registry model (FR-1a).
+ *
+ * Auth is intentionally a discriminated union (feature web-ui, lightweight auth): the
+ * Fallen-8 apiApp accepts its static API key either in a header (default X-Api-Key) or as
+ * an RFC 6750-shaped `Authorization: Bearer <key>`.
+ *
+ * `bearer` is the host-embed arm (feature studio-embeddable): the token comes from a
+ * host-supplied provider callback, so lifetime and refresh stay the host's job and no
+ * long-lived secret ever reaches Studio. The callback makes it non-serializable BY DESIGN -
+ * bearer instances arrive via StudioConfig as managed instances and are never persisted.
+ * Being async, it resolves only at the transport choke points (client.ts
+ * resolveAuthHeaders); the sync authHeaders keeps serving the standalone kinds.
+ */
+export type InstanceAuth = {
+    kind: "none";
+} | {
+    kind: "apiKey";
+    key: string;
+    useBearer?: boolean;
+    header?: string;
+} | {
+    kind: "bearer";
+    getToken: () => Promise<string>;
+};
+export interface InstanceConfig {
+    id: string;
+    name: string;
+    /** Base URL without a trailing slash; "" means the origin the app is served from. */
+    baseUrl: string;
+    auth: InstanceAuth;
+    /**
+     * The ADDRESSED namespace (feature graph-namespaces): when set, every namespace-scoped
+     * request goes to /ns/{namespace}/… — explicitly, "default" included. Never persisted on
+     * the registry record; useInstanceStore() binds it from the active-namespace state, so a
+     * bound view of the instance flows to the screens' API calls.
+     */
+    namespace?: string;
+}
+export declare function normalizeBaseUrl(url: string): string;
+export declare function describeEndpoint(instance: InstanceConfig): string;
+/**
+ * A cross-origin instance is one whose baseUrl resolves to a different origin than the page the
+ * Studio is served from. It matters for diagnostics (feature standalone-ui): when such an
+ * instance's /status probe fails at the fetch layer, a missing CORS allow-list entry on the data
+ * plane is indistinguishable from "server down", so the Connect screen surfaces a CORS hint for
+ * exactly these. Same-origin ("") is never cross-origin.
+ */
+export declare function isCrossOriginInstance(baseUrl: string): boolean;

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

@@ -0,0 +1,7 @@
+/**
+ * The one canvas element cap (feature canvas-view-controls): the upper bound on elements
+ * fetched into the canvas working set PER KIND, since `GET /graph?maxElements=` caps
+ * vertices and edges independently (the server clamps each to 100,000). Used by the
+ * sample-graph loaders and the Canvas screen's "Show whole graph" load.
+ */
+export declare const CANVAS_ELEMENT_CAP = 20000;

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

@@ -0,0 +1,55 @@
+import type { EdgeREST, PathREST } from "../api/types";
+/**
+ * Pure logic for the Canvas "Connect" tab (feature canvas-find-connect): pairwise shortest-path
+ * discovery over the canvas vertices, and the selective add/remove bookkeeping that keeps the
+ * canvas honest. Kept DOM-free so every decision below is unit-tested without a render.
+ *
+ * BLS expands frontiers over incoming AND outgoing edges, so a->b finds the same connection as
+ * b->a; Connect therefore runs ONE query per UNORDERED pair (lower id as source), never both
+ * directions. See features/open/canvas-find-connect/spec.md.
+ */
+/**
+ * The most pairs a single Connect run will search. Above this the run is refused, not silently
+ * truncated: a partial pairwise sweep would report "no path" for pairs it never tried, which is
+ * a lie. 500 pairs is ~32 vertices in all-scope. One tuning home.
+ */
+export declare const CONNECT_PAIR_CAP = 500;
+/** How many pair path-searches run concurrently in one batched round (bounds in-flight fetches). */
+export declare const CONNECT_BATCH_SIZE = 8;
+/** The canvas element ids at the moment a Connect run starts - the baseline every path is diffed against. */
+export interface CanvasBaseline {
+    nodes: Set<number>;
+    edges: Set<number>;
+}
+/** The vertices and edges a path would introduce over the run baseline (its endpoints excluded). */
+export interface IntroducedSets {
+    nodeIds: Set<number>;
+    edgeIds: Set<number>;
+}
+/**
+ * Every unordered pair of the given vertex ids as `[lowId, highId]`, in ascending, deterministic
+ * order. Duplicate ids collapse and self-pairs are excluded, so N distinct ids yield exactly
+ * N*(N-1)/2 pairs.
+ */
+export declare function buildPairs(vertexIds: number[]): [number, number][];
+/** How many unordered pairs `vertexCount` DISTINCT vertices produce (N*(N-1)/2, never negative). */
+export declare function pairCount(vertexCount: number): number;
+/**
+ * What a path would ADD to the canvas: its vertices and edges minus everything already in the
+ * baseline. A pair's endpoints are baseline vertices by construction, so a direct-edge path
+ * introduces just the edge; a multi-hop path introduces its intermediate vertices and hop edges.
+ */
+export declare function introducedSets(path: PathREST, baseline: CanvasBaseline): IntroducedSets;
+/**
+ * What actually LEAVES the canvas when `target` is retracted: the elements it introduced that no
+ * OTHER still-added path also introduced. A shared intermediate therefore survives until its last
+ * claiming path is removed. `others` must exclude `target` itself (pass the remaining added paths).
+ */
+export declare function removalSet(target: IntroducedSets, others: IntroducedSets[]): IntroducedSets;
+/**
+ * Canvas edges synthesized from a path's hops (id, endpoints, type). The same shape the Path
+ * screen's overlay builds; label/props are null here because a path element carries only the
+ * edge's type, not its full property set (a later real merge fills them in). The caller filters
+ * these to the ids it actually wants to add.
+ */
+export declare function synthesizeEdges(path: PathREST): EdgeREST[];

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

@@ -0,0 +1,6 @@
+/** A property is reserved (embedding state) when it uses either embedding prefix. */
+export declare function isReservedEmbeddingProperty(propertyId: string): boolean;
+/** 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. */
+export declare function previewVector(value: unknown): string;