@mastra/playground-ui 68.0.0-alpha.2 → 68.0.0

package/dist/src/domains/chat/tools/badges/knowledge-body-range.d.ts

@@ -0,0 +1,12 @@
+/** What part of a page a Knowledge call read or wrote: a short tag for the collapsed row, a sentence for the body. */
+export interface BodyExtent {
+    row: string | undefined;
+    summary: string;
+}
+/**
+ * Which part of the body a `knowledge_read` result holds, from the call's arguments and its page. A whole
+ * body has no row tag; undefined when the result is not a body read at all (a notes-only read, a scope listing).
+ */
+export declare function readExtent(output: Record<string, unknown>, args: Record<string, unknown>): BodyExtent | undefined;
+/** Which lines a `knowledge_page` write replaced, from its `range` argument; undefined for a whole-body write. */
+export declare function writeExtent(args: Record<string, unknown>): BodyExtent | undefined;

package/dist/src/domains/chat/tools/badges/knowledge-tool-badge.d.ts

@@ -9,8 +9,11 @@ export interface KnowledgeCard {
     detail?: string;
     body: ReactNode;
 }
-/** What each Knowledge tool's settled result says, or null when the shape isn't one we know. */
-export declare function knowledgeCard(toolName: string, input: unknown, output: unknown): KnowledgeCard | null;
+/**
+ * What each Knowledge tool's settled result says, or null when the shape isn't one we know.
+ * A failed call (`errorText` set) gets a card naming what it tried and the error it got.
+ */
+export declare function knowledgeCard(toolName: string, input: unknown, output: unknown, errorText?: string): KnowledgeCard | null;
 export interface KnowledgeToolBadgeProps extends Omit<ToolApprovalRequest, 'toolCalled'> {
     card: KnowledgeCard;
     metadata?: MessageMetadata;

package/dist/src/domains/chat/tools/badges/mcp-input-request-badge.d.ts

@@ -0,0 +1,18 @@
+import type { McpInputRequestPayload } from '../mcp-input-request';
+import type { OpenInputRequest } from './use-deferred-input-request';
+/** A call the run is parked on: answering resumes the run, like any other suspended tool. */
+export declare function ForegroundMcpInputRequest({ toolCallId, payload, readOnly, isNetwork, }: {
+    toolCallId: string;
+    payload: McpInputRequestPayload;
+    readOnly?: boolean;
+    /** A network run resumes through its own route, which can't carry these answers yet. */
+    isNetwork?: boolean;
+}): import("react").JSX.Element;
+/**
+ * A deferred call whose background task waits on the question. The agent's turn already ended, so
+ * the answer goes to the task directly and the chat stays free for other messages meanwhile.
+ */
+export declare function DeferredMcpInputRequest({ backgroundTaskId, request, }: {
+    backgroundTaskId: string;
+    request: OpenInputRequest;
+}): import("react").JSX.Element;

package/dist/src/domains/chat/tools/badges/tool-badge.d.ts

@@ -1,3 +1,4 @@
+import type { McpInputRequestPayload } from '../mcp-input-request';
 import type { MessageMetadata } from '../..';
 import type { ToolApprovalRequest } from './tool-approval-badge';
 import type { ActivityStatus } from '../../../../ds/components/ai/activity';
@@ -17,5 +18,7 @@ export interface ToolBadgeProps extends Omit<ToolApprovalRequest, 'toolCalled'>
     backgroundTaskId?: string;
     /** `running` while the part holds a deferred call's placeholder; `completed`/`failed` once it holds the result. */
     backgroundTaskStatus?: string;
+    /** The MCP task question the call is waiting on, if it is. */
+    mcpInputRequest?: McpInputRequestPayload;
 }
-export declare const ToolBadge: ({ toolName, args, result, metadata, toolOutput, toolCallId, toolApprovalMetadata, suspendPayload, isNetwork, toolCalled: toolCalledProp, withoutArgs, status, backgroundTaskId, backgroundTaskStatus, }: ToolBadgeProps) => import("react").JSX.Element;
+export declare const ToolBadge: ({ toolName, args, result, metadata, toolOutput, toolCallId, toolApprovalMetadata, suspendPayload, isNetwork, toolCalled: toolCalledProp, withoutArgs, status, backgroundTaskId, backgroundTaskStatus, mcpInputRequest, }: ToolBadgeProps) => import("react").JSX.Element;

package/dist/src/domains/chat/tools/badges/use-deferred-input-request.d.ts

@@ -0,0 +1,44 @@
+import type { McpInputRequestPayload, McpInputResumeData } from '../mcp-input-request';
+export declare const backgroundTaskQueryKey: (backgroundTaskId: string) => readonly ['background-task', string];
+export interface OpenInputRequest {
+    payload: McpInputRequestPayload;
+    /** The suspension being answered; the server refuses an answer to an older one. */
+    suspendedAt?: string | Date;
+}
+/**
+ * The MCP input request a deferred call's background task is suspended on, if any. The task is read
+ * once (so a reloaded chat still sees an open request) and then followed over the task's event
+ * stream, whose events are folded into the same cache entry the task chip polls.
+ */
+export declare function useDeferredInputRequest(backgroundTaskId: string, enabled: boolean): OpenInputRequest | undefined;
+/** Answers a deferred call's suspended background task, fenced on the suspension that was shown. */
+export declare function useResumeBackgroundTask(backgroundTaskId: string): import("@tanstack/react-query").UseMutationResult<{
+    id: string;
+    status: 'pending' | 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled' | 'timed_out';
+    toolName: string;
+    toolCallId: string;
+    args: {
+        [x: string]: unknown;
+    };
+    agentId: string;
+    threadId?: string | undefined;
+    resourceId?: string | undefined;
+    runId: string;
+    result?: unknown | undefined;
+    error?: {
+        message: string;
+        stack?: string | undefined;
+    } | undefined;
+    createdAt: string;
+    startedAt?: string | undefined;
+    completedAt?: string | undefined;
+    retryCount: number;
+    maxRetries: number;
+    timeoutMs: number;
+    suspendPayload?: unknown | undefined;
+    suspendedAt?: string | undefined;
+}, Error, {
+    resumeData: McpInputResumeData;
+    suspendedAt?: string | Date;
+}, unknown>;
+export declare const resumeErrorMessage: (error: Error) => string;

package/dist/src/domains/chat/tools/badges/use-mcp-task-progress.d.ts

@@ -1,3 +1,4 @@
+import type { McpInputRequestPayload } from '../mcp-input-request';
 import type { ActivityStatus } from '../../../../ds/components/ai/activity';
 export type McpTaskStatus = 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
 /** What `@mastra/mcp`'s client writes to a task-backed tool's output stream (`MCPTaskProgress`). */
@@ -21,7 +22,11 @@ export interface McpTaskView extends McpTaskProgress {
  *
  * A deferred call (one running as a Mastra background task) settles its part with a placeholder
  * long before the task ends, so its end is never inferred here: the background task says when.
+ *
+ * While the call is suspended on the task's input request, the request names the task, so the chip
+ * reads `input_required` even on a reloaded card with no progress.
  */
-export declare function useMcpTaskProgress(result: unknown, status: ActivityStatus, { deferred }?: {
+export declare function useMcpTaskProgress(result: unknown, status: ActivityStatus, { deferred, request }?: {
     deferred?: boolean;
+    request?: McpInputRequestPayload;
 }): McpTaskView | undefined;

package/dist/src/domains/chat/tools/connect-prompt-tool.d.ts

@@ -1,6 +1,10 @@
+import type { MessageMetadata } from '../messages/message-metadata';
 export { CONNECT_PROMPT_TOOL_NAME } from './connect-prompt-tool-id';
 export interface ConnectPromptToolProps {
+    toolName: string;
+    toolCallId: string;
     output: unknown;
+    metadata?: MessageMetadata;
     /** Historical rendering: show the card but suppress the connect action. */
     readOnly?: boolean;
 }
@@ -11,5 +15,10 @@ export interface ConnectPromptToolProps {
  * the mounted `/connect` routes, drives the OAuth flow in a popup through the
  * server's launch gate (which verifies this browser owns the pending session
  * before redirecting to the vendor), and polls until the connection settles.
+ *
+ * The tool pauses the agent run while the card is up. Once the connection
+ * settles, the card resumes the paused call with the outcome — connected, or
+ * the reason it failed — so the agent continues from the tool's result rather
+ * than a chat message.
  */
-export declare const ConnectPromptTool: ({ output, readOnly }: ConnectPromptToolProps) => import("react").JSX.Element | null;
+export declare const ConnectPromptTool: ({ toolName, toolCallId, output, metadata, readOnly, }: ConnectPromptToolProps) => import("react").JSX.Element | null;

package/dist/src/domains/chat/tools/mcp-input-request-tool.d.ts

@@ -0,0 +1,18 @@
+import type { McpInputRequestPayload, McpInputResumeData } from './mcp-input-request';
+export interface McpInputRequestToolProps {
+    payload: McpInputRequestPayload;
+    /** Sends the answers; the request stays open (and answerable again) if the returned promise rejects. */
+    onSubmit: (resumeData: McpInputResumeData) => void | Promise<unknown>;
+    isSubmitting?: boolean;
+    /** Why the last answer didn't go through. */
+    error?: string;
+    /** History view: show the question without answering it. */
+    readOnly?: boolean;
+    /** Why the request can't be answered here, shown with the questions. */
+    notice?: string;
+}
+/**
+ * The questions an MCP server asked while a tool call's task waits. Every request key needs an answer
+ * before the call can continue, so answers are held until the last one is given, then sent together.
+ */
+export declare function McpInputRequestTool({ payload, onSubmit, isSubmitting, error, readOnly, notice, }: McpInputRequestToolProps): import("react").JSX.Element;

package/dist/src/domains/chat/tools/mcp-input-request.d.ts

@@ -0,0 +1,40 @@
+import type { MessageMetadata, SuspendedToolMetadata } from '../messages/message-metadata';
+/** An embedded request an MCP server sent while its task waits (`{ method, params }`). */
+export interface McpInputRequest {
+    method: string;
+    params?: Record<string, unknown>;
+}
+/** What `@mastra/mcp` suspends a task-backed tool call with (`MCPInputRequestSuspendPayload`). */
+export interface McpInputRequestPayload {
+    type: 'mcp-input-request';
+    serverName: string;
+    toolName: string;
+    taskId: string;
+    createdAt: string;
+    /** When the call suspended; new each time the same task asks again, unlike `createdAt`. */
+    requestedAt?: string;
+    requests: Record<string, McpInputRequest>;
+}
+export type McpInputAction = 'accept' | 'decline' | 'cancel';
+export interface McpInputResponse {
+    action: McpInputAction;
+    content?: Record<string, unknown>;
+}
+/** Resume data answering every request key (`MCPInputRequestResumeData`). */
+export interface McpInputResumeData {
+    inputResponses: Record<string, McpInputResponse>;
+}
+export declare function isMcpInputRequest(payload: unknown): payload is McpInputRequestPayload;
+/** More questions at once than any real task asks; the server decides these, so Studio bounds them. */
+export declare const MAX_INPUT_REQUESTS = 20;
+export declare const MAX_REQUEST_MESSAGE_LENGTH = 2000;
+export declare const MAX_INPUT_REQUESTS_SIZE: number;
+/** Whether the server sent more than Studio draws: too many questions, a huge message, or huge params. */
+export declare function inputRequestTooLarge(payload: McpInputRequestPayload): boolean;
+/**
+ * This call's own suspension. Saved entries are keyed by call id, but a live run keys them by tool
+ * name (two calls of one tool share that key), so the entry's own `toolCallId` decides.
+ */
+export declare function findSuspension(metadata: MessageMetadata | undefined, toolCallId: string): SuspendedToolMetadata | undefined;
+/** The MCP input request this call is suspended on, if it is. */
+export declare function suspendedMcpInputRequest(metadata: MessageMetadata | undefined, toolCallId: string): McpInputRequestPayload | undefined;

package/dist/src/domains/chat/tools/tool-card-kind.d.ts

@@ -2,7 +2,7 @@ import type { MessageMetadata, SuspendedToolMetadata, ToolApprovalMetadata } fro
 import type { ToolPartFields } from '../messages/renderers/tool-part';
 import type { ActivityStatus } from '../../../ds/components/ai/activity';
 /** Which card draws a call. Decided once, shared by the dispatcher and the fold. */
-export type ToolCardKind = 'hidden' | 'observation' | 'ask_user' | 'connect_prompt' | 'submit_plan' | 'background' | 'agent' | 'workflow' | 'file_tree' | 'sandbox' | 'code_mode' | 'mcp_app' | 'knowledge' | 'plain';
+export type ToolCardKind = 'hidden' | 'observation' | 'ask_user' | 'connect_prompt' | 'submit_plan' | 'mcp_input_request' | 'background' | 'agent' | 'workflow' | 'file_tree' | 'sandbox' | 'code_mode' | 'mcp_app' | 'knowledge' | 'plain';
 export interface ToolCardContext {
     metadata?: MessageMetadata;
     mcpAppTools?: Record<string, unknown>;
@@ -14,6 +14,8 @@ export interface ToolInteraction {
 export declare const isAgentCall: (metadata: MessageMetadata | undefined, toolName: string) => boolean;
 export declare const isWorkflowCall: (metadata: MessageMetadata | undefined, toolName: string) => boolean;
 export declare const isSettledState: (state: string | undefined) => boolean;
+/** A call running as a Mastra background task. An awaited call's part also names its task, but holds the final result. */
+export declare const isDeferredCall: (backgroundTaskId: string | undefined, backgroundTaskStatus: string | undefined) => boolean;
 /** A call neither settled nor carried by a live run reads as idle, so stale history never shimmers. */
 export declare function badgeStatus(state: string | undefined, chatRunning: boolean): ActivityStatus;
 export declare const codeModeCall: (input: unknown, output: unknown) => {
@@ -24,4 +26,4 @@ export declare const codeModeCall: (input: unknown, output: unknown) => {
 export declare function toolInteraction(metadata: MessageMetadata | undefined, toolName: string, toolCallId: string): ToolInteraction;
 /** Tools the transcript never draws: working memory updates and task tools (shown in the docked task list). */
 export declare function isHiddenTool(toolName: string): boolean;
-export declare function toolCardKind({ toolName, toolCallId, input, output, state }: ToolPartFields, { metadata, mcpAppTools }: ToolCardContext): ToolCardKind;
+export declare function toolCardKind({ toolName, toolCallId, input, output, state, backgroundTaskId, backgroundTaskStatus }: ToolPartFields, { metadata, mcpAppTools }: ToolCardContext): ToolCardKind;

package/dist/src/domains/chat/tools/tool-card.d.ts

@@ -27,4 +27,4 @@ export interface ToolCardProps {
 }
 /** Its own workflow run scope, so a streaming workflow result can drive a live graph inside the card. */
 export declare const ToolCard: (props: ToolCardProps) => import("react").JSX.Element;
-export declare const ToolCardInner: ({ toolName, input, output, modelOutput, backgroundTaskId, backgroundTaskStatus, toolCallId, state, errorText, metadata, dataParts, readOnly, }: ToolCardProps) => import("react").JSX.Element | null;
+export declare const ToolCardInner: ({ toolName, input, output, modelOutput, backgroundTaskId, backgroundTaskStatus, toolCallId, state, errorText, metadata, dataParts, readOnly, }: ToolCardProps) => import("react").JSX.Element;

package/dist/src/domains/connect/types.d.ts

@@ -103,6 +103,22 @@ export interface ConnectPromptPayload {
     type: 'connect-prompt';
     requestedProvider?: string;
     providers: ConnectPromptProvider[];
+    /** Outcome for the model once a paused prompt resumes, e.g. "Linear connected successfully." */
+    message?: string;
+    /** Why the connection failed, when a paused prompt resumed without one. */
+    error?: string;
 }
+/**
+ * What the card resumes a paused `request_connection` call with once the
+ * connection settles: `active`, or `failed` with the reason the card showed.
+ */
+export type ConnectPromptResume = {
+    provider: string;
+    status: 'active';
+} | {
+    provider: string;
+    status: 'failed';
+    error: string;
+};
 /** Narrows an arbitrary tool output to a connect-prompt payload. */
 export declare function isConnectPromptPayload(output: unknown): output is ConnectPromptPayload;

package/dist/src/domains/dashboards/components/dashboard-renderer.d.ts

@@ -1,12 +1,14 @@
 import type { DashboardDefinition } from '@mastra/client-js';
 import type { DashboardScope, OnDashboardDrilldown } from '../lib/definition';
-import type { AnyWidgetKind } from '../widget-kind';
+import type { AnyWidgetKind, DashboardExpand } from '../widget-kind';
 export type DashboardRendererProps = {
     definition: DashboardDefinition;
     /** Which widgets, views and columns show: `org` spans several projects, `project` is one. */
     scope: DashboardScope;
     /** Opens a drilldown; each host routes to its own Traces or Logs page. */
     onDrilldown?: OnDashboardDrilldown;
+    /** Where chart cards expand to, e.g. the host's query page; see `DashboardExpand`. */
+    expand?: DashboardExpand;
     /** Kinds beyond the built-in ones; a kind of the same name replaces the built-in. */
     kinds?: AnyWidgetKind[];
     className?: string;
@@ -16,4 +18,4 @@ export type DashboardRendererProps = {
  * owns the range and filters. Each widget is checked and rendered on its own: one that fails to
  * parse, query or render shows its own error, and the rest of the dashboard still renders.
  */
-export declare function DashboardRenderer({ definition, scope, onDrilldown, kinds, className }: DashboardRendererProps): import("react").JSX.Element;
+export declare function DashboardRenderer({ definition, scope, onDrilldown, expand, kinds, className, }: DashboardRendererProps): import("react").JSX.Element;

package/dist/src/domains/dashboards/hooks/use-widget-views.d.ts

@@ -1,13 +1,14 @@
 import type { DashboardWidget, DashboardWidgetView } from '@mastra/client-js';
 import type { DrilldownScope } from '../../metrics/drilldown';
 import type { OnDashboardDrilldown } from '../lib/definition';
-import type { ResolvedView } from '../widget-kind';
+import type { DashboardExpand, ResolvedView } from '../widget-kind';
 export type Views<Options> = readonly [ResolvedView<Options>, ...ResolvedView<Options>[]];
 /**
  * The open view of a widget, `defaultIndex` until one is picked, and the card title for it
- * (`title`, and `titleMenu` with several views) to spread into `ChartCard`.
+ * (`title`, and `titleMenu` with several views, or an expand link with `expand`) to spread into
+ * `ChartCard`.
  */
-export declare function useViewMenu<Options>(widget: DashboardWidget, views: Views<Options>, defaultIndex?: number): {
+export declare function useViewMenu<Options>(widget: DashboardWidget, views: Views<Options>, defaultIndex?: number, expand?: DashboardExpand): {
     view: ResolvedView<Options>;
     index: number;
     heading: import("../lib/chrome").ViewHeading;

package/dist/src/domains/dashboards/index.d.ts

@@ -16,4 +16,4 @@ export type { DashboardScope, OnDashboardDrilldown } from './lib/definition';
 export { buildRequest } from './lib/requests';
 export type { DashboardPageContext, DashboardRequest } from './lib/requests';
 export { defineWidgetKind } from './widget-kind';
-export type { AnyWidgetKind, ResolvedView, WidgetKind, WidgetKindProps } from './widget-kind';
+export type { AnyWidgetKind, DashboardExpand, ResolvedView, WidgetKind, WidgetKindProps } from './widget-kind';

package/dist/src/domains/dashboards/kinds/scores/scores-widget.d.ts

@@ -1,3 +1,3 @@
 import type { WidgetKindProps } from '../../widget-kind';
 import type { ScoresOptions } from './options';
-export declare function ScoresWidget({ widget, views }: WidgetKindProps<ScoresOptions>): import("react").JSX.Element;
+export declare function ScoresWidget({ widget, views, expand }: WidgetKindProps<ScoresOptions>): import("react").JSX.Element;

package/dist/src/domains/dashboards/lib/chrome.d.ts

@@ -1,7 +1,8 @@
 import type { DashboardWidget, DashboardWidgetView } from '@mastra/client-js';
 import type { ChartCardProps } from '../../metrics/components/chart-card';
-/** What a widget's card shows as its title: `title`, and `titleMenu` with several views. */
-export type ViewHeading = Pick<ChartCardProps, 'title' | 'titleMenu'>;
+import type { DashboardExpand } from '../widget-kind';
+/** What a widget's card shows as its title: `title`, and `titleMenu` with several views or an expand link. */
+export type ViewHeading = Pick<ChartCardProps, 'title' | 'titleMenu' | 'href' | 'LinkComponent'>;
 export declare const unsupportedMessage: (fields: string[], names?: Record<string, string>) => string;
 /** A view's value in the card's menu: its label in kebab case (`Token usage` → `token-usage`), or its position when unlabelled or blank. */
 export declare const viewValue: (label: string | undefined, index: number) => string;
@@ -9,6 +10,7 @@ export declare const viewValue: (label: string | undefined, index: number) => st
 export declare const viewLabel: (label: string | undefined, index: number) => string;
 /**
  * The card title for the open view: the widget's title for a single view; with several, the open
- * view's label, as a menu of every view (as the metrics cards switch views).
+ * view's label, as a menu of every view (as the metrics cards switch views). With somewhere to
+ * expand to, the widget's title links there instead.
  */
-export declare function viewTitle(widget: DashboardWidget, views: readonly DashboardWidgetView[], index: number, onChoose: (index: number) => void): ViewHeading;
+export declare function viewTitle(widget: DashboardWidget, views: readonly DashboardWidgetView[], index: number, onChoose: (index: number) => void, expand?: DashboardExpand): ViewHeading;

package/dist/src/domains/dashboards/widget-kind.d.ts

@@ -1,6 +1,7 @@
 import type { DashboardWidget, DashboardWidgetView } from '@mastra/client-js';
 import type { ComponentType } from 'react';
 import type { z } from 'zod/v4';
+import type { ChartCardProps } from '../metrics/components/chart-card';
 import type { DashboardScope, OnDashboardDrilldown } from './lib/definition';
 /** A view whose options passed its kind's schema. */
 export type ResolvedView<Options> = DashboardWidgetView & {
@@ -12,6 +13,17 @@ export type WidgetKindProps<Options> = {
     views: [ResolvedView<Options>, ...ResolvedView<Options>[]];
     scope: DashboardScope;
     onDrilldown?: OnDashboardDrilldown;
+    /** Where a chart card expands to; see `DashboardExpand`. */
+    expand?: DashboardExpand;
+};
+/**
+ * Where a chart widget expands to (a host's query page), as the Gateway Overview's cards do: the card
+ * shows its title with an expand icon linking there, in place of its views menu, on its first view.
+ * `href` returns `undefined` for a widget with nowhere to go; that card keeps its menu.
+ */
+export type DashboardExpand = {
+    href: (widget: DashboardWidget) => string | undefined;
+    LinkComponent: NonNullable<ChartCardProps['LinkComponent']>;
 };
 /**
  * One kind of widget, self-contained: the renderer only looks it up by name, checks each view's

package/dist/src/domains/knowledge/components/KnowledgePageCard.d.ts

@@ -0,0 +1,23 @@
+export interface KnowledgePageCardProps {
+    name: string;
+    /** `Page`, `Scope` or a scope's display label. */
+    kind: string;
+    /** Where the page is addressed, e.g. `org:acme#policies/refunds`. */
+    pageRef?: string;
+    /** Where the page sits, from its root scope down. */
+    path?: string;
+    /** Already formatted (`1000+` when the server capped the count); left out when unknown or zero. */
+    childCount?: string;
+    /** Left out when unknown or both zero. */
+    links?: {
+        in: number;
+        out: number;
+    };
+    /** Of `links`, how many go to pages the graph doesn't draw. */
+    notShown?: number;
+}
+/**
+ * What the explorer's graph tooltip says about a page: name, kind and ref, children, links. The graph's
+ * dots and the hover cards on page links in chat both draw it.
+ */
+export declare function KnowledgePageCard({ name, kind, pageRef, path, childCount, links, notShown }: KnowledgePageCardProps): import("react").JSX.Element;

package/dist/src/domains/knowledge/components/KnowledgePageExplorer.d.ts

@@ -36,6 +36,16 @@ export interface KnowledgeExplorerQueryState<T> {
     isError: boolean;
     error: Error | null;
 }
+export interface KnowledgeExplorerPageLinks {
+    edges: Array<{
+        fromPageId: string;
+        toPageId: string;
+        kind: 'body' | 'note';
+        count: number;
+    }>;
+    pages: KnowledgePagePayload[];
+    truncated: boolean;
+}
 /** One request for a tree level: `parentId: null` for the root scopes. */
 export interface KnowledgeExplorerTreeRequest {
     parentId: string | null;
@@ -58,6 +68,23 @@ export interface KnowledgeExplorerSource {
     };
     /** Tree levels, one result per request in order (e.g. `useQueries`). Enables the lazily loaded tree and child pages. */
     useTreeLevels?: (requests: KnowledgeExplorerTreeRequest[]) => Array<KnowledgeExplorerQueryState<KnowledgeExplorerTreeLevel>>;
+    /**
+     * Pages a link reaches, by id or `[[ref]]` (`scope#path`), one result per entry in order (e.g.
+     * `useQueries`). Lets the focused page draw links to pages the graph hasn't loaded; without it only
+     * links to loaded pages are drawn. A key the host can't resolve should come back as an error.
+     */
+    useLinkedPages?: (keys: string[]) => Array<KnowledgeExplorerQueryState<KnowledgeExplorerPageDetail>>;
+    /**
+     * Exact links into and out of each page (by `[[ref]]` or note mention), counted over the whole store, for
+     * the pages the graph draws. Without it, or when it errors (a server with no link index answers 501), the
+     * graph counts only the links between pages it has loaded.
+     */
+    useLinkCounts?: (pageIds: string[]) => KnowledgeExplorerQueryState<Record<string, {
+        in: number;
+        out: number;
+    }>>;
+    /** One page's links with the pages at their other ends; fetched for the page under the pointer. Null disables it. */
+    usePageLinks?: (pageId: string | null) => KnowledgeExplorerQueryState<KnowledgeExplorerPageLinks>;
     /** A page's recent activity, newest first. */
     useActivity?: (pageId: string) => KnowledgeExplorerQueryState<KnowledgeExplorerActivity>;
 }
@@ -70,6 +97,8 @@ export interface KnowledgePageExplorerProps {
     view: KnowledgeExplorerView;
     onViewChange: (view: KnowledgeExplorerView) => void;
 }
+/** Links of the selected page drawn at most in each direction; the rest are counted. */
+export declare const FOCUS_LINK_CAP = 20;
 /**
  * Search, the page tree, and either the page graph or the selected page, kept in sync on one selection.
  * Wide screens show the tree beside the graph or the page; below `lg` one toggle picks tree, graph or page.

package/dist/src/domains/knowledge/components/KnowledgePageGraph.d.ts

@@ -1,12 +1,38 @@
 import type { KnowledgePageEdge, KnowledgePagePayload, KnowledgeScopeGrantPayload } from '../pageTypes';
 export interface KnowledgePageGraphProps {
     pages: KnowledgePagePayload[];
-    /** Mention edges between pages; parent edges are derived from `pages`. */
+    /** Mention and body-link edges between pages; parent edges are derived from `pages`. */
     edges: KnowledgePageEdge[];
     pinnedIds?: readonly string[];
     /** Access grants between scopes, drawn from each principal scope to the scope it reaches. */
     grants?: readonly KnowledgeScopeGrantPayload[];
     selectedPageId?: string | null;
+    /** The page the layout centres on when none is selected, drawn like a focused page without the ring. */
+    centerId?: string | null;
+    /** Per page, links into and out of it that the graph doesn't draw; shown as `→in out→` on full circles. */
+    hiddenLinks?: ReadonlyMap<string, {
+        in: number;
+        out: number;
+    }>;
+    /** Every link between pages, drawn or not: hovering a page draws its own, and tooltips count them. */
+    knownLinks?: readonly KnowledgePageEdge[];
+    /** Pages the focus links to or from that the hierarchy doesn't reach: drawn close around the focus. */
+    nearIds?: ReadonlySet<string>;
+    /** False while the pages the selected page needs are loading: the graph keeps its last layout until they are in. */
+    settled?: boolean;
+    /** Exact links into and out of pages, from the store; they replace the counts taken from `knownLinks`. */
+    exactLinkCounts?: ReadonlyMap<string, {
+        in: number;
+        out: number;
+    }>;
+    /** Links fetched for the page under the pointer: drawn on hover, never counted or laid out. */
+    fetchedLinks?: readonly KnowledgePageEdge[];
+    /** The page under the pointer, or null: a host can fetch that page's links. */
+    onHover?: (pageId: string | null) => void;
+    /** Write each dot's total of links in and out inside it. */
+    showCounts?: boolean;
+    /** The pointer rests on a dot or stand-in: a host can load what it stands for. */
+    onPreview?: (page: KnowledgePagePayload) => void;
     /** A page that wasn't selected was clicked, tapped, or activated with Enter or Space: select it. */
     onSelect: (page: KnowledgePagePayload) => void;
     /** The already-selected page was clicked, tapped, or activated again: open it. Without it, that only reselects. */

package/dist/src/domains/knowledge/components/KnowledgePageTree.d.ts

@@ -9,7 +9,8 @@ export declare const KNOWLEDGE_TREE_ROOT = "";
  *
  * A host that loads the tree a level at a time passes `mayHaveChildren` (so unloaded pages still offer
  * a chevron), listens to `onExpandedChange` to load the opened levels, and passes `loadMore` for
- * levels with more children to fetch.
+ * levels with more children to fetch. A page's `childCount`, when the server sends one, shows beside
+ * its name. Selecting a page with children also opens it.
  */
 export declare function KnowledgePageTree({ pages, pinnedIds, selectedPageId, onSelect, initiallyExpanded, mayHaveChildren, onExpandedChange, loadMore, 'aria-label': ariaLabel, }: {
     pages: KnowledgePagePayload[];

package/dist/src/domains/knowledge/lib/circleText.d.ts

@@ -0,0 +1,2 @@
+/** The text with any word wider than the circle cut short with an ellipsis, so words never break mid-way. */
+export declare function fitWords(text: string, maxChars: number): string;

package/dist/src/domains/knowledge/lib/fitViewport.d.ts

@@ -0,0 +1,67 @@
+import type { Viewport } from '@xyflow/react';
+/** How far Fit view may zoom out to frame a ring of linked pages, which the readable floor would crop. */
+export declare const RING_MIN_ZOOM = 0.15;
+interface FitInput {
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    width: number;
+    height: number;
+    /** Fit view on a focus with an outer ring of linked pages: frame all of it, below the readable floor if need be. */
+    ring?: boolean;
+    /** The focus (or the layout's centre): what stays centred when a floor stops the fit. */
+    anchor?: {
+        position: {
+            x: number;
+            y: number;
+        };
+        width?: number;
+        height?: number;
+    };
+}
+/**
+ * The viewport that frames `bounds`. Zoom stops at the readable floor, so what is cropped is the edge, not
+ * the page being looked at; only Fit view, with an outer ring, goes lower so the whole ring shows.
+ */
+export declare function fitViewport({ bounds, width, height, ring, anchor }: FitInput): Viewport;
+/** Margin around the drawn nodes on the first view, as a share of the pane. */
+export declare const INITIAL_FIT_PADDING = 0.05;
+/** The first view never zooms in past the pages' own size, however few there are. */
+export declare const INITIAL_FIT_MAX_ZOOM = 1;
+/** How long after the first view the graph keeps refitting as pages arrive, unless the user acts first. */
+export declare const INITIAL_SETTLE_MS = 3000;
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * The first view of a graph: every drawn node in the pane with a small margin, never zoomed in past what
+ * fits, and clear of `legend` (the box, in pane pixels, an overlay covers at the top left). When the plain
+ * fit would put a node under the legend, the pane is fitted again beside it or below it, whichever keeps
+ * the pages larger.
+ */
+export declare function fitAllViewport({ bounds, nodes, width, height, legend, }: {
+    bounds: Rect;
+    nodes: Rect[];
+    width: number;
+    height: number;
+    legend?: {
+        right: number;
+        bottom: number;
+    };
+}): Viewport;
+/** How long a view change animates: the same as the layout's own transition, and none under reduced motion. */
+export declare const fitDuration: (motion: boolean) => 0 | 700;
+/** How close to the pane's edge a refocused page may sit before the view moves to bring it in. */
+export declare const NUDGE_PADDING = 24;
+/**
+ * How far to move the view along one axis so a page at `start` (screen position) of `size` stays inside a
+ * pane of `extent`, with padding. Zero when it already is; centred when it can't fit with the padding.
+ */
+export declare function nudgeAxis(start: number, size: number, extent: number): number;
+export {};