@fallen-8/studio 0.0.32

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

@@ -0,0 +1,139 @@
+/**
+ * Hover help for every labeled field in the studio (feature studio-mutations-ux).
+ * ONE home per explanation: screens reference these keys via <Field helpKey=…> /
+ * help(key); no help copy is inlined at call sites. Keys are grouped by concept —
+ * shared concepts first, then per-screen one-offs.
+ */
+export declare const FIELD_HELP: {
+    readonly elementId: "Numeric id of an existing vertex or edge. Ids are assigned by the server and shown in every result table, the canvas, and the browser.";
+    readonly propertyId: "Name of a property (key), e.g. 'age' or 'name'. Properties are typed key-value pairs on a vertex or edge.";
+    readonly typedValue: "The value plus its .NET type. The type decides how the server parses, compares, and indexes the value — 42 as Int32 and \"42\" as String are different values.";
+    readonly indexId: "Unique name of an index on this instance. Registered indices are suggested live from the server; free typing still works.";
+    readonly edgePropertyId: "The edge's type, e.g. 'knows'. Fallen-8 groups a vertex's edges by type; traversals and degree lookups address edges by this name. Not one of the edge's key-value properties.";
+    readonly mutVertexLabel: "Optional label used to categorize the new vertex, e.g. 'person'. Labels drive filtering, statistics, and canvas coloring; leave empty for an unlabeled vertex.";
+    readonly mutCreationDate: "Optional creation timestamp stored on the element. Enter Unix seconds (e.g. 1713862800) or an ISO date/time, treated as UTC unless it carries an offset; empty stores 0 (epoch).";
+    readonly mutProperties: "Initial properties written atomically with the element in the same transaction. Add one row per property; each value is typed.";
+    readonly mutEdgeSource: "Id of the existing vertex the edge starts at (its outgoing side). The edge lands in this vertex's adjacency, grouped by the edge's type.";
+    readonly mutEdgeTarget: "Id of the existing vertex the edge points to (its incoming side).";
+    readonly mutEdgeLabel: "Optional category tag, orthogonal to the edge's type (the edge property id) — not a second copy of it. Leave empty unless it says something the type doesn't.";
+    readonly mutRemoveElement: "Id of the vertex or edge to delete. Deleting a vertex also deletes all of its edges. This cannot be undone.";
+    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 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.";
+    readonly scanOperator: "How each element's property value is compared against the literal, using the literal's type ordering.";
+    readonly fulltextQuery: "Search text for the fulltext index; results come back scored with highlights.";
+    readonly spatialElementId: "Id of the element to search around; the spatial index returns everything within the given distance of it.";
+    readonly spatialDistance: "Maximum distance from the reference element, in the spatial index's units.";
+    readonly rangeLeftLimit: "Lower bound of the index range scan (typed, like every literal).";
+    readonly rangeRightLimit: "Upper bound of the index range scan (typed, like every literal).";
+    readonly rangeIncludeLeft: "Whether elements exactly at the lower bound are included (≥ vs >).";
+    readonly rangeIncludeRight: "Whether elements exactly at the upper bound are included (≤ vs <).";
+    readonly vectorQuery: "The query embedding, as a JSON array or comma-separated floats. Its dimension must match the index dimension exactly.";
+    readonly vectorK: "How many nearest neighbours to return (top-k).";
+    readonly vectorKind: "Restrict matches to vertices, edges, or allow both ('any').";
+    readonly vectorLabelConstraint: "Optional label filter applied BEFORE top-k — you still get k results, all carrying this label.";
+    readonly scanResultType: "Restrict matches to vertices, edges, or return both.";
+    readonly scanLiteral: "The typed value each element's property is compared against.";
+    readonly indexQueryForm: "How to ask this index. The forms offered come from the index's server-reported capabilities (its type decides what it can answer).";
+    readonly indexContentElementId: "Id of the vertex or edge to add to / remove from the index.";
+    readonly indexContentKey: "The typed key the element is filed under — index lookups compare against exactly this value and type.";
+    readonly indexPluginType: "Index plugin to instantiate. The list comes from the server's plugin discovery. Only VectorIndex takes creation options (dimension, metric); SpatialIndex cannot be created over REST.";
+    readonly vectorDimension: "Fixed embedding dimension for the new vector index; every vector added later must have exactly this many components.";
+    readonly vectorMetric: "Similarity metric the vector index uses. Cosine/DotProduct: higher score is better; L2: lower is better.";
+    readonly vectorAddElementId: "Id of the vertex or edge this embedding belongs to.";
+    readonly vectorAddPropertyId: "Property on the element that holds the embedding; the index reads the vector from there (WAL-recoverable, the honest default).";
+    readonly vectorAddVector: "The embedding itself, pasted as a JSON array or comma-separated floats — stored only in the index, not on the element.";
+    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 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.";
+    readonly embeddingShowReserved: "Show the raw reserved properties ($embedding:… and $embeddingModel:…) in the plain property table. They are normally folded into the Embeddings tab.";
+    readonly semanticQuerySource: "Where the query vector comes from: paste a vector, or type text the embedding provider embeds once before the traversal starts (provider-gated).";
+    readonly semanticQueryVector: "The query vector elements are scored against, pasted as a JSON array or comma-separated floats. Embedded once, up front — the traversal itself runs no model.";
+    readonly semanticQueryText: "Query text the embedding provider embeds once before the traversal. Mutually exclusive with a pasted vector; needs the provider enabled (else the server 403s).";
+    readonly semanticEmbeddingName: "Which named element embedding to score against (default 'default'). Elements without it are simply not matched.";
+    readonly semanticMetric: "Similarity metric: Cosine/DotProduct (higher is closer) or L2 (lower is closer). Must suit the embeddings; bit-identical to the vector index's scoring.";
+    readonly semanticMinScore: "Declarative filter: keep only elements whose similarity is at least this (Cosine/DotProduct) or at most this (L2). Pure data — it compiles no C#.";
+    readonly vertexSlotMode: "How this vertex slot filters: match everything, a compiled C# fragment, or a semantic threshold against the request's semantic query (pure data — no C#). One owner per slot.";
+    readonly slotSemanticThreshold: "Vertices pass this slot when their embedding scores at least this (Cosine/DotProduct) or at most this (L2) against the semantic query. Vertices without the embedding never pass.";
+    readonly semanticCostBySimilarity: "Declarative cost (DIJKSTRA paths only): weight each vertex by similarity so the search prefers close vertices (Cosine cost = 1 − score; L2 = distance). Not available under DotProduct.";
+    readonly pathFrom: "Id of the vertex the path search starts from.";
+    readonly pathTo: "Id of the vertex the path search must reach.";
+    readonly pathAlgorithm: "Path plugin to use, e.g. BLS (breadth-first) or DIJKSTRA (cheapest paths by cost).";
+    readonly pathMaxDepth: "Maximum number of hops a path may have; caps the search space.";
+    readonly pathMaxResults: "Maximum number of paths returned (for Dijkstra: the K cheapest).";
+    readonly pathMaxWeight: "Upper bound on a path's total cost; paths weighing more are discarded.";
+    readonly connectScope: "Which canvas vertices are the start/end points: every vertex on the canvas, or only a subset you pick below. A shortest path (BLS) is searched for each unordered pair.";
+    readonly subgraphName: "Unique name the subgraph is registered under; used to fetch, recalculate, and delete it later.";
+    readonly subgraphFrom: "Optional name of an existing subgraph to search WITHIN instead of the whole graph (nesting).";
+    readonly patternType: "Step kind in the pattern sequence: Vertex matches a vertex, Edge one hop, VariableLengthEdge a min..max hop chain. Steps alternate vertex ↔ edge, starting with a vertex.";
+    readonly patternName: "Optional name for this pattern step; matched elements are reported under it in the result.";
+    readonly patternDirection: "Which way the edge step is followed from the previous vertex: outgoing, incoming, or either.";
+    readonly patternMinLength: "Minimum number of hops this variable-length step must take.";
+    readonly patternMaxLength: "Maximum number of hops this variable-length step may take (capped at 100).";
+    readonly analyticsAlgorithm: "Analytics plugin to run; the description under the picker explains what the selected one computes.";
+    readonly analyticsVertexLabel: "Only consider vertices with this label; empty runs on the whole graph.";
+    readonly analyticsEdgeProperty: "Only traverse edges of this type (their edge property id), e.g. 'knows'; empty traverses all edges.";
+    readonly analyticsDirection: "Edge direction the algorithm follows: in, out, or both. Empty keeps the algorithm's default.";
+    readonly analyticsMaxResults: "How many top-scored entries the server returns; the computation itself still runs over the whole (filtered) graph.";
+    readonly analyticsMaxIterations: "Iteration cap for iterative algorithms (e.g. PageRank rounds); empty keeps the algorithm's default.";
+    readonly analyticsTimeBudget: "Wall-clock budget in seconds; the run stops with partial results when it is exhausted (default 30).";
+    readonly analyticsDamping: "PageRank damping factor d (probability of following an edge vs. jumping anywhere); 0.85 is the classic choice.";
+    readonly analyticsEpsilon: "Convergence threshold on the total (L1-summed) score change between rounds; iteration stops once the sum falls below it.";
+    readonly analyticsWriteBack: "When checked, the run also stores each vertex's score as a property under the key below (asks for confirmation first).";
+    readonly analyticsWriteBackKey: "Property key the per-vertex scores are written to, e.g. 'analytics.pagerank'.";
+    readonly benchNodeCount: "Vertices to create IN THE ACTIVE NAMESPACE. The scale preset (100k × 10) builds ~1M edges — expect seconds of server work and real memory.";
+    readonly benchEdgesPerVertex: "Out-edges added PER VERTEX (total edges ≈ nodes × this).";
+    readonly benchDistribution: "How edge targets are drawn: uniform (flat, no hubs) or preferential (Barabási–Albert rich-get-richer — hubs emerge, analytics show structure).";
+    readonly benchIterations: "Timed passes over every edge of the currently loaded graph; more iterations tighten the median/stddev.";
+    readonly loadPath: "Server-side path of the save game to load — resolved on the machine the instance runs on, not in this browser.";
+    readonly exportVertexLabel: "Only export vertices with this label (their edges follow); empty exports all.";
+    readonly exportEdgeLabel: "Only export edges with this label; empty exports all.";
+    readonly exportEdgeType: "Only export edges of this type (their edge property id), e.g. 'knows'; combines with the edge label filter. Empty exports all.";
+    readonly instanceSwitcher: "The Fallen-8 instance every screen talks to. Register more instances on the Connect screen.";
+    readonly canvasRenderer: "The canvas projection, both WebGL: 2D (Sigma.js — pan/zoom, crisp labels) or 3D (three.js — orbit with the mouse, labels on hover). Styling, path overlays, and subgraph results work identically in both.";
+    readonly canvasLayout: "How vertices are placed. 2D: force (ForceAtlas2 physics, clusters emerge), circular ring, circle pack grouped by label, grid, or random. 3D: force (d3-force-3d) or DAG modes that layer the graph top-down / radially (cycles are tolerated, best-effort).";
+    readonly canvasNodeColor: "What decides a node's color: its label (the default) or a property whose key you type (seeded with the first property on the canvas, then editable). You don't hand-pick the colors: each distinct value gets a stable color from a fixed palette, unless every value is numeric, in which case nodes shade along a cyan→pink gradient. Missing or blank values render grey.";
+    readonly canvasNodeSize: "What decides a node's size: fixed, a numeric property whose key you type (min-max scaled), or the node's in-/out-/total degree counted over the edges currently on the canvas (expand neighbors and sizes update).";
+    readonly canvasNodeImage: "Property whose value renders AS the node: an http(s) or data URL loads that image; any other value (e.g. an emoji like 🦊) is drawn by the studio itself — emoticons need no hosting. Nodes without the property stay circles.";
+    readonly canvasEdgeColor: "What decides an edge's color: its label (default) or a property whose key you type (seeded with the first property on the canvas, then editable), with the same auto palette and cyan→pink numeric gradient rules as node colors, and missing values grey.";
+    readonly canvasEdgeWidth: "What decides an edge's width: fixed, or a numeric property whose key you type, min-max scaled into the width range. Edges without a numeric value keep the default width.";
+    readonly canvasNodeLabels: "Show vertex labels on the canvas (2D: always visible, 3D: on hover). Past 5,000 rendered elements labels are dropped automatically to protect the frame rate.";
+    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 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.";
+    readonly feedKeys: "Exact property keys to match (Enter or comma adds one). Only property events carry a key, so any keys filter hides creates and removes: the same caveat as the REST grammar.";
+    readonly feedCopyRest: "Copy the configured filter as the equivalent GET /changefeed query, ready for curl or a service. Credentials never go into the URL.";
+    readonly instanceName: "Display name for this connection, shown in the instance switcher.";
+    readonly instanceUrl: "Base URL of the Fallen-8 REST API, e.g. http://localhost:5000. Leave empty when the studio is served by the instance itself (same origin).";
+    readonly instanceApiKey: "API key for instances that require one; sent as a Bearer token on every request and kept in this browser only.";
+    readonly storedQuery: "A named, pre-compiled filter set registered under POST /storedquery. Invoking by name compiles nothing — the pinned artifact runs.";
+    readonly storedQueryName: "Unique name the query is registered under and later invoked by. Allowed: letters, digits, underscore, dash; max 128 characters.";
+    readonly storedQueryDescription: "Optional human-readable note shown next to the query in the library list.";
+    readonly pluginCategory: "What you are authoring: an algorithm plugin (invoked transparently by name through the path/subgraph/analytics endpoints) or a graph function (a stored read procedure invoked by name).";
+    readonly pluginContract: "Which algorithm interface the source implements: Path (IShortestPathAlgorithm), SubGraph (ISubGraphAlgorithm) or Analytics (IGraphAnalyticsAlgorithm). Functions have a single fixed contract.";
+    readonly pluginName: "Unique name the plugin is registered under and invoked by (per namespace). Must equal the type's PluginName in the source. Allowed: letters, digits, underscore, dash; max 128 characters.";
+    readonly pluginDescription: "Optional human-readable note shown next to the plugin in the registry list.";
+    readonly pluginParameters: "Call-time parameters passed to the graph function. Values are strings in v1 (the function parses what it needs).";
+    readonly confirmTyped: "Safety catch: type the target instance's name exactly to arm the destructive action. Nothing happens until it matches.";
+    readonly nlIntent: "Describe the filter in plain language; the assistant drafts a C# filter fragment from it, which you still review and commit yourself.";
+    readonly nlBackend: "Where natural-language-to-filter translation runs: a preset endpoint or a custom one.";
+    readonly nlPreset: "Pre-configured model endpoint to use.";
+    readonly nlEndpoint: "URL of the model API endpoint that translates your prompt into a filter fragment.";
+    readonly nlApi: "Wire protocol the endpoint speaks (which request/response shape to use).";
+    readonly nlModel: "Model identifier sent to the endpoint, e.g. a model name the API expects.";
+    readonly nlTemperature: "Sampling temperature; lower is more deterministic, which suits code generation.";
+    readonly nlApiKey: "Credential for the model endpoint. Sent only to that endpoint, never to the Fallen-8 instance.";
+};
+export type FieldHelpKey = keyof typeof FIELD_HELP;
+/** Accessor for odd call sites (checkbox labels, aria-labeled inputs, toggles). */
+export declare const help: (key: FieldHelpKey) => string;

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

@@ -0,0 +1,16 @@
+/** Compact human numbers for stat tiles (592134058.33 -> "592.1M"). */
+export declare function formatCompact(value: number): string;
+/** Full number with grouping, for exact values ("10,001,000"). */
+export declare function formatExact(value: 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.
+ */
+export declare const ABSENT = "-";
+/**
+ * A count the server may not have: grouped digits when it exists, the absent glyph when it does
+ * not. The absent case is real - a namespace the server catalogs but did not load reports
+ * null counts rather than zeros (feature namespace-startup-load) - and it must not render as
+ * "0", which would tell the operator a populated graph is empty.
+ */
+export declare function formatCountOrDash(value: number | null | undefined): string;

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

@@ -0,0 +1,37 @@
+import type { EdgeREST, VertexREST } from "../api/types";
+import type { InstanceConfig } from "../instances/types";
+/**
+ * Scans return bare id lists (FR-8); this hydrates them into elements. Missing ids (deleted
+ * between scan and hydration) are skipped, not errors.
+ *
+ * ONE batch read does most of the work: POST /graphelements/get answers a whole page of ids in a
+ * single request, and what it returns - id, label, properties, kind - is a COMPLETE VertexREST,
+ * because a vertex carries no adjacency in this API. Five hundred ids used to be twenty rounds of
+ * twenty-five requests.
+ *
+ * Edges are the exception and are still fetched one by one. The batch route omits an edge's
+ * endpoints deliberately (shipping every endpoint of every element would dominate a several-hundred
+ * element payload), and the canvas cannot draw an edge without them, so an id the batch reports as
+ * an edge is re-read through GET /graphelement/{id}. A result that is all vertices - which is what
+ * a scan or an analytics run usually produces - costs one request; one that is all edges costs one
+ * more than before. The rounds below keep the same width.
+ *
+ * Two properties the caller relies on: the result is in the order of the ids it passed (an edge is
+ * read later but still renders where it was scanned), and progress counts ATTEMPTS, so a page with
+ * a deleted id still reaches its total. An aborted signal stops the work rather than degrading it.
+ */
+export declare const HYDRATION_BATCH_SIZE = 25;
+export declare const HYDRATION_DEFAULT_CAP = 500;
+export interface HydrationProgress {
+    done: number;
+    total: number;
+}
+export declare function isEdge(element: VertexREST | EdgeREST): element is EdgeREST;
+export declare function hydrateElements(instance: InstanceConfig, ids: number[], options?: {
+    cap?: number;
+    onProgress?: (progress: HydrationProgress) => void;
+    signal?: AbortSignal;
+}): Promise<{
+    elements: (VertexREST | EdgeREST)[];
+    capped: boolean;
+}>;

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

@@ -0,0 +1,17 @@
+import type { IndexDescription } from "../api/types";
+/**
+ * The client side of the index-capability contract (feature index-workspace): which
+ * query forms the Query screen offers for an index. The server's /status inventory
+ * reports capabilities derived from the index's interfaces; this module narrows them to
+ * the families the UI knows and holds the fallback for servers predating the field.
+ */
+export type IndexCapability = "equality" | "range" | "fulltext" | "spatial" | "vector";
+export declare const ALL_CAPABILITIES: readonly IndexCapability[];
+/**
+ * The query forms to offer. Unknown index (free-form id, no inventory entry) or unknown
+ * third-party plugin on an old server: every form stays available. A mismatched form is
+ * NOT a server error — only the vector endpoint rejects; equality/range/fulltext/spatial
+ * answer EMPTY for an index they cannot serve — so the Query screen adds a hint next to
+ * an empty unknown-index result instead of pretending the server would have complained.
+ */
+export declare function indexCapabilities(index: IndexDescription | undefined | null): readonly IndexCapability[];

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

@@ -0,0 +1,42 @@
+/**
+ * fallen8-jsonl emitter (feature sample-graphs): builds interchange files the server's
+ * POST /bulk/import consumes. ONE emitter, two consumers — the sample build script
+ * (scripts/build-samples.ts) and the GitHub dependency card, which transforms an SBOM
+ * in the browser. The format contract (version 2: typed {type,value} pairs, strict
+ * fields, the System.Single[] embedding encoding) is owned by the server's
+ * JsonlGraphFormat; this module only mirrors it.
+ */
+export interface JsonlProperty {
+    type: string;
+    value: string;
+}
+export interface JsonlVertex {
+    id: number;
+    label?: string;
+    properties?: Record<string, JsonlProperty>;
+}
+export interface JsonlEdge {
+    id: number;
+    source: number;
+    target: number;
+    edgePropertyId: string;
+    label?: string;
+    properties?: Record<string, JsonlProperty>;
+}
+/** Fixed creationDate for deterministic dataset builds (2026-01-01T00:00:00Z). */
+export declare const SAMPLE_CREATION_DATE = 1767225600;
+/** The current fallen8-jsonl version; always stamped (System.Single[] is always available). */
+export declare const JSONL_FORMAT_VERSION = 2;
+/** Typed-pair constructors for the property types the datasets use. */
+export declare const prop: {
+    string: (value: string) => JsonlProperty;
+    int32: (value: number) => JsonlProperty;
+    double: (value: number) => JsonlProperty;
+    /** An embedding vector, rounded to 5 decimals (~1e-5 cosine error, much smaller files). */
+    singleArray: (vector: readonly number[]) => JsonlProperty;
+};
+/**
+ * Serializes a whole graph to an importable jsonl string: meta line (exact counts, always
+ * the current format version), then vertices, then edges.
+ */
+export declare function buildJsonlGraph(vertices: JsonlVertex[], edges: JsonlEdge[]): string;

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

@@ -0,0 +1,48 @@
+import type { CSSProperties } from "react";
+/**
+ * Studio-wide list limits — two INDEPENDENT ideas, both living here:
+ *
+ *  1. LIST_MAX_ROWS — a hard safety ceiling. No list ever renders more than this many rows (a
+ *     runaway-DOM guard). It is NOT a display cap you hit in normal use; on the rare occasion a
+ *     list is bigger, <ListCapNote> says so. Everything below the ceiling is always rendered and
+ *     reachable by scrolling.
+ *
+ *  2. SCROLL_ROWS — a per-list DISPLAY threshold, in ROWS. A list shorter than its threshold
+ *     renders at its natural height with NO scrollbar; once it grows past the threshold its
+ *     height is capped (to about that many rows) and a scrollbar appears, so you scroll through
+ *     everything. Applied purely in CSS: a `.scroll-list` wrapper reads the count from the
+ *     `--scroll-rows` custom property (see index.css and the `scrollRows` helper below).
+ *
+ * Tune the numbers here, not per call site.
+ */
+export declare const LIST_MAX_ROWS = 10000;
+/** Rows a list shows before it caps its height and scrolls. Add per-list entries as needed. */
+export declare const SCROLL_ROWS: {
+    /** Any list without a reason to differ. */
+    readonly default: 12;
+    /** Save-game registry (SaveGamesScreen). */
+    readonly saveGames: 15;
+    /** Registered instances (ConnectScreen). */
+    readonly instances: 8;
+    /** Namespaces (NamespacesPanel). */
+    readonly namespaces: 12;
+    /** Ingested documents (KnowledgeScreen). */
+    readonly documents: 12;
+    /** Integrations this instance's runtime ships (IntegrationsScreen): a short, curated list. */
+    readonly integrations: 8;
+    /** One run's diagnostics (IntegrationsScreen): a CSV with many bad rows can be long. */
+    readonly diagnostics: 10;
+};
+/**
+ * Slice {@link items} to the hard ceiling, reporting the true total so a call site can flag the
+ * (rare) truncation via <ListCapNote>. This is the ONLY place a list's rows are ever dropped.
+ */
+export declare function capList<T>(items: readonly T[], max?: number): {
+    shown: T[];
+    total: number;
+};
+/**
+ * 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.
+ */
+export declare function scrollRows(rows: number): CSSProperties;

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

@@ -0,0 +1,36 @@
+import type { IndexKeySpecification, LiteralSpecification, PropertySpecification } from "../api/types";
+/**
+ * Typed-literal editing (FR-9): everywhere the API takes
+ * { value | propertyValue, fullQualifiedTypeName } the UI offers these types instead of
+ * free-text JSON. Values always travel as strings; the server converts by type name.
+ */
+export declare const LITERAL_TYPES: readonly ["System.String", "System.Int32", "System.Int64", "System.Double", "System.Boolean", "System.DateTime"];
+export type LiteralTypeName = (typeof LITERAL_TYPES)[number];
+export interface TypedValue {
+    type: LiteralTypeName;
+    raw: string;
+}
+/** Validates the raw text for its declared type; returns an error message or null. */
+export declare function validateTypedValue(value: TypedValue): string | null;
+/** Normalizes the raw text into the canonical wire string for its type. */
+export declare function toWireValue(value: TypedValue): string;
+export declare function toLiteral(value: TypedValue): LiteralSpecification;
+export declare function toPropertySpec(propertyId: string, value: TypedValue): PropertySpecification;
+export declare function toIndexKey(value: TypedValue): IndexKeySpecification;
+/**
+ * Parses the optional creation-date input on the mutation forms into the wire value:
+ * a uint Unix timestamp in SECONDS. Empty keeps today's behaviour (0 = epoch); digits
+ * are taken as seconds verbatim; anything else must be ISO-shaped (YYYY-MM-DD…) and is
+ * treated as UTC unless it carries an explicit offset — Date.parse would otherwise read
+ * offset-less date-times as LOCAL time, storing a different value per browser timezone
+ * (and accept garbage like "12.5" as a date).
+ */
+export declare function parseCreationDate(raw: string): {
+    ok: true;
+    seconds: number;
+} | {
+    ok: false;
+    error: string;
+};
+/** Renders a property value received from the API for table display. */
+export declare function formatPropertyValue(value: unknown): string;

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

@@ -0,0 +1,10 @@
+/**
+ * Client mirror of the server's namespace-name rule (Fallen8Namespaces.IsValidName). Names
+ * are permissive — any case, spaces, punctuation, Unicode — because on-disk storage is keyed
+ * by an internal id, not the name; a name is only a display label, a map key, and a URL PATH
+ * SEGMENT (/ns/{name}/…, /q/{name}/…). That last role fixes the only hard limits: no "/" or
+ * "\" (an encoded slash can't round-trip through the server), no control characters, not
+ * "."/".." (path-traversal tokens), no leading/trailing whitespace, and a length cap.
+ */
+export declare const NAMESPACE_NAME_MAX = 63;
+export declare function isValidNamespaceName(name: string): boolean;

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

@@ -0,0 +1,37 @@
+import type { EdgeREST, VertexREST } from "../api/types";
+import type { InstanceConfig } from "../instances/types";
+/**
+ * 1-hop neighborhood fetch over the per-property adjacency routes (feature
+ * adjacency-preview) — the one home for "edge-id lists → hydrated edges + endpoint
+ * vertices", shared by the Canvas screen's expand-on-demand and the Browser screen's
+ * adjacency preview. The REST Edge DTO carries no property id; the per-property listings
+ * do, so the attribution happens here. Failed hydrations are skipped, not errors.
+ */
+/** Edge cap for the adjacency preview — a teaser, not the canvas working set. */
+export declare const PREVIEW_EDGE_CAP = 60;
+/** Edge cap for canvas expand-on-demand (pre-feature constant, unchanged). */
+export declare const EXPAND_EDGE_CAP = 200;
+export interface Neighborhood {
+    /** Hydrated endpoint vertices, minus skipNeighborIds and failed fetches. */
+    vertices: VertexREST[];
+    edges: EdgeREST[];
+    /** true when the cap cut off edges or endpoint vertices. */
+    truncated: boolean;
+}
+/**
+ * A vertex's adjacent edges plus their endpoint vertices. Self-loops appear once (the
+ * "out" attribution wins). The cap applies to edges and endpoint vertices alike.
+ */
+export declare function fetchVertexNeighborhood(instance: InstanceConfig, vertexId: number, options: {
+    cap: number;
+    skipNeighborIds?: ReadonlySet<number>;
+}): Promise<Neighborhood>;
+/**
+ * An edge's endpoint vertices plus EVERY edge between them, both directions — found by
+ * intersecting the endpoints' id lists (out(s)∩in(t) ∪ in(s)∩out(t)), never by hydrating
+ * a supernode's full edge set. The focus edge is always first in the result, even if the
+ * listings raced a mutation.
+ */
+export declare function fetchEdgeNeighborhood(instance: InstanceConfig, edge: EdgeREST, options: {
+    cap: number;
+}): Promise<Neighborhood>;

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

@@ -0,0 +1,12 @@
+import type { PatternSpecification } from "../api/types";
+/**
+ * Client-side pattern-sequence rules (FR-16), mirrored from the subgraph spec: the
+ * sequence alternates vertex ↔ edge starting with a vertex, a level-0 edge (sequence
+ * starting with an edge step) is also legal, VariableLengthEdge needs min ≤ max and the
+ * API caps max length at 100. The server's 400 is still surfaced if it disagrees.
+ */
+export declare const MAX_VARIABLE_EDGE_LENGTH = 100;
+/** Structural subset so both wire specs and builder drafts validate with one function. */
+type PatternStep = Pick<PatternSpecification, "type" | "minLength" | "maxLength">;
+export declare function validatePatternSequence(patterns: PatternStep[]): string | null;
+export {};

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

@@ -0,0 +1,11 @@
+/** Appended to a message about a change that only the next boot will act on. */
+export declare const TAKES_EFFECT_ON_RESTART = "takes effect on restart";
+/** The short chip beside a row whose stored value is not the value in force. */
+export declare const RESTART_PENDING_CHIP = "restart to apply";
+/**
+ * The banner summary. Deliberately "differs from what this instance started with" rather than "you
+ * changed this": appsettings.json reloads on change and nothing observes it, so this lights up when
+ * an operator hand-edits that file too, and blaming the reader for someone else's edit is worse than
+ * being vague.
+ */
+export declare function restartBannerSummary(count: number): string;

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

@@ -0,0 +1,95 @@
+/**
+ * Sample-graph loader (feature sample-graphs). Fetches a curated dataset just-in-time and
+ * ingests it: (optional wipe), POST /bulk/import, create the manifest's index recipes, hand
+ * the imported elements back for the canvas. No embedding work happens for baked datasets:
+ * the vectors are in the fallen8-jsonl file and a bound VectorIndex projects them on import.
+ *
+ * A sample may additionally carry DOCUMENTS (feature knowledge-demo), which adds three steps
+ * after index creation: seed the equality indexes, bind the semantic layer, then ingest the
+ * documents through the real /document pipeline. All three are conditional on their manifest
+ * field, so a document-free sample follows exactly the path it always did.
+ */
+import type { GraphREST, StatusREST } from "../api/types";
+import type { InstanceConfig } from "../instances/types";
+import type { SampleEmbeddingInfo, SampleManifestEntry, SamplesManifest } from "./samples";
+/**
+ * Where the datasets live. Default is SAME-ORIGIN /samples: the datasets ship with the app
+ * (Vite serves the repo samples/ in dev and copies it into wwwroot at build; the apiApp serves
+ * it), so the gallery shows the samples the app was built with, a newly added sample appears on
+ * rebuild without a GitHub round-trip, and it works offline. Override with VITE_F8_SAMPLES_BASE
+ * to point at a remote mirror (e.g. GitHub raw `.../<ref>/samples`) or a fork. No trailing slash.
+ */
+export declare function samplesBaseUrl(): string;
+export declare function fetchSamplesManifest(baseUrl: string, signal?: AbortSignal): Promise<SamplesManifest>;
+export type LoadStep = "wiping" | "fetching" | "importing" | "indexing" | "seeding" | "binding" | "ingesting" | "rendering";
+/** Progress sink; `detail` names the current document or seeding count when there is one. */
+export type LoadStepReporter = (step: LoadStep, detail?: string) => void;
+export interface LoadResult {
+    graph: GraphREST;
+    verticesCreated: number;
+    edgesCreated: number;
+    /** Index keys written by the seeding step (0 when the sample has no `indexSeeds`). */
+    tagsSeeded: number;
+    /** Documents that reached `indexed` (0 when the sample has no `documents`). */
+    documentsIngested: number;
+    /** Chunks those documents produced. */
+    chunksCreated: number;
+}
+/**
+ * Runs the full ingest. `wipeFirst` must be true when the graph is non-empty (import
+ * requires an empty target — the caller gates this behind a typed confirm). Steps are
+ * reported via onStep for a progress line.
+ */
+export declare function loadSampleGraph(instance: InstanceConfig, entry: SampleManifestEntry, baseUrl: string, options: {
+    wipeFirst: boolean;
+    onStep?: LoadStepReporter;
+}): Promise<LoadResult>;
+export type EmbeddingGate = {
+    kind: "not-embedded";
+} | {
+    kind: "ready";
+} | {
+    kind: "provider-off";
+} | {
+    kind: "mismatch";
+    detail: string;
+};
+/**
+ * Whether the sample's text-in features (semantic search, queryText) will work on this
+ * instance. Bring-your-own-vector always works (the vectors are in the file); this only
+ * gates TEXT-IN, which needs a provider whose identity matches the baked vectors.
+ */
+export declare function embeddingGate(embedding: SampleEmbeddingInfo | null, status: StatusREST | null): EmbeddingGate;
+/**
+ * Whether a sample that ingests DOCUMENTS can run on this instance (feature knowledge-demo).
+ * `blocking: false` means the sample still loads, just with less in it: NLP enrichment is
+ * additive, so a missing sidecar costs the entity network and nothing else.
+ */
+export type IngestionGate = {
+    kind: "not-needed";
+    blocking: false;
+} | {
+    kind: "ready";
+    blocking: false;
+} | {
+    kind: "nlp-off";
+    blocking: false;
+    detail: string;
+} | {
+    kind: "status-unknown";
+    blocking: true;
+    detail: string;
+} | {
+    kind: "ingestion-off";
+    blocking: true;
+    detail: string;
+} | {
+    kind: "provider-off";
+    blocking: true;
+    detail: string;
+} | {
+    kind: "docling-unreachable";
+    blocking: true;
+    detail: string;
+};
+export declare function ingestionGate(entry: SampleManifestEntry, status: StatusREST | null): IngestionGate;

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

@@ -0,0 +1,87 @@
+/**
+ * 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
+ * purely from this data. Adding a static sample is a script + manifest change — no UI
+ * code.
+ */
+import type { StyleConfig } from "../canvas/styleConfig";
+/** What a sample shows off, rendered as card badges. */
+export type SampleBadge = "canvas" | "path" | "analytics" | "semantic" | "spatial" | "knowledge";
+/** A POST /index recipe the loader creates right after import. */
+export interface SampleIndexRecipe {
+    uniqueId: string;
+    pluginType: string;
+    pluginOptions: Record<string, {
+        propertyId: string;
+        propertyValue: string;
+        fullQualifiedTypeName: string;
+    }>;
+}
+/**
+ * Fills an equality index from an imported property (feature knowledge-demo). Needed because
+ * `POST /index` does NOT backfill: a DictionaryIndex created after import is EMPTY, so a
+ * sample whose documents link against it would link nothing. The loader walks the imported
+ * vertices and issues one addToIndex per vertex carrying `propertyId`. A bound VectorIndex
+ * needs none of this (it projects existing embeddings), which is why only equality indexes
+ * appear here.
+ */
+export interface SampleIndexSeed {
+    /** An index the sample's `indexRecipes` created. */
+    indexId: string;
+    /** The vertex property whose value becomes the index key. Untagged vertices are skipped. */
+    propertyId: string;
+}
+/**
+ * A document the loader ingests LIVE through the real pipeline after the graph is imported
+ * (feature knowledge-demo). Deliberately not baked into the jsonl: the point is that docling
+ * conversion, embedding, NLP enrichment and structural linking actually run.
+ */
+export interface SampleDocument {
+    /** Same-origin asset path, e.g. "documents/nw-std-0417.md". */
+    file: string;
+    /** The document name recorded in the graph. */
+    name: string;
+    /** `text` posts to /document/text (no sidecar); `binary` uploads multipart to /document. */
+    kind: "text" | "binary";
+    /** Text documents only. */
+    format?: "markdown" | "plain";
+}
+/** Provenance of the dataset's precomputed vectors, compared against /status.embedding. */
+export interface SampleEmbeddingInfo {
+    name: string;
+    model: string;
+    dimension: number;
+    metric: string;
+}
+export interface SampleManifestEntry {
+    id: string;
+    title: string;
+    emoji: string;
+    pitch: string;
+    vertexCount: number;
+    edgeCount: number;
+    badges: SampleBadge[];
+    /** Suggested next steps, shown after a successful load. */
+    trySteps: string[];
+    /** Same-origin asset path, e.g. "samples/karate-club.jsonl". */
+    file: string;
+    /** Applied to the instance's canvas style config on load. */
+    styleConfig: Partial<StyleConfig>;
+    indexRecipes: SampleIndexRecipe[];
+    embedding: SampleEmbeddingInfo | null;
+    /**
+     * The three fields below are OPTIONAL on purpose: absent means the loader behaves exactly
+     * as it did before feature knowledge-demo, so the document-free samples are untouched.
+     */
+    /** Equality indexes to fill after import, because creation does not backfill. */
+    indexSeeds?: SampleIndexSeed[];
+    /** Documents ingested live after seeding, in this order. */
+    documents?: SampleDocument[];
+    /** The linking allowlist passed on every ingest; ids must come from `indexRecipes`. */
+    linkIndexIds?: string[];
+}
+export interface SamplesManifest {
+    version: 1;
+    samples: SampleManifestEntry[];
+}