@sparkelf/dsh-knowledge-base 0.0.0-stage → 0.1.1

package/lib/types/client/KnowledgeListing.d.ts

@@ -0,0 +1,174 @@
+/**
+ * A directory listing with the modification time each entry carries.
+ *
+ * The row is the file explorer's own row from `dsh-better-sidebar`, copied from
+ * `src/client/FileTree.tsx` (`FileRow`/`DirRow`) and `src/client/sidebar.module.css`
+ * (`.explorerRow`): the same `div[role=button]`, the same 14px glyph, the same
+ * ellipsised name, the same trailing modified time that yields its right edge to
+ * the same hover-revealed `@` reference button, and the same `depth * 22 + 6`
+ * indent. A reader sees that tree in this window's right sidebar, so a second
+ * design beside it reads as bolted on -- which is why this is a copy rather than
+ * a re-drawing.
+ *
+ * What the borrowed tree cannot carry is why this list exists. Its host entry
+ * shape (`FsEntry`: name, path, isDir, hidden, isSymlink, broken) has no
+ * timestamp, so a row built from it can never show when a document last changed;
+ * and its rows decide visibility from a shared curated store rather than from
+ * per-user grants. This panel reads the same directories through the plugin's own
+ * route, which stats each child, and its row carries a right-click into the grant
+ * form the tree has no place for.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import { type ReactNode } from 'react';
+/** Props for the listing panel. */
+export interface KnowledgeListingProps {
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /** Called with a chosen path so the page can show its preview. */
+    onOpen: (path: string) => void;
+    /** Re-read trigger, so a rescan from elsewhere refreshes this too. */
+    refreshTick?: number;
+    /** Locale tag, so dates match the reader's language. */
+    locale?: string;
+    /**
+     * Open the permission surface for one path.
+     *
+     * Exists because the borrowed tree's context menu is built inside it with no way
+     * to add a row, so the grant entry lives here instead: this is the plugin's own
+     * listing, where a right-click can mean what the knowledge base needs it to mean.
+     */
+    onGrant?: (path: string) => void;
+    /**
+     * Insert one row's reference into the conversation draft.
+     *
+     * The borrowed tree reveals this affordance on hover; the listing mirrors that so
+     * a reader gets the same `@` action from either tree.
+     */
+    onReference?: (path: string, isDir: boolean) => void;
+    /**
+     * Pin or unpin one row.
+     *
+     * Omitted by a caller that has no pin store, which is how the search results list
+     * stays free of an action that would only make sense inside the tree.
+     */
+    onPin?: (path: string, pinned: boolean) => void;
+    /** Whether one path is currently pinned, so the row can mark it. */
+    isPinned?: (path: string) => boolean;
+    /**
+     * Star or unstar one row.
+     *
+     * Omitted by a caller with no favourites store, which is how the search results list
+     * stays free of an entry that would only make sense inside the tree. A folder is
+     * favoured the same way a file is: the star marks a row, not a document.
+     */
+    onFavorite?: (path: string, favorite: boolean) => void;
+    /** Whether one path is currently favourited, so the row can draw its star. */
+    isFavorite?: (path: string) => boolean;
+    /**
+     * The path a paste would land in, given the row this menu was opened on.
+     *
+     * A directory row pastes INTO itself; a file row pastes beside itself. Kept a
+     * callback rather than derived in the menu because only the listing knows whether a
+     * row is the tree's root, which has no parent to paste beside.
+     */
+    pasteTargetFor?: (relPath: string, isDir: boolean) => string | null;
+    /**
+     * Upload external files dropped onto a directory row.
+     *
+     * Distinct from the row-to-row move handled above: a file dragged in from the
+     * desktop carries no `KB_DRAG_MIME`, so it is the only case this callback serves.
+     * Omitted by a read-only caller, which keeps the rows from accepting a drop that
+     * would then be refused on the Host.
+     * @param relPath - the directory the files were dropped onto.
+     * @param files - the dropped files with paths relative to that directory.
+     */
+    onUpload?: (relPath: string, files: readonly {
+        file: unknown;
+        relativePath: string;
+    }[]) => void;
+    /**
+     * Called after a menu-driven delete or paste succeeded.
+     *
+     * Both change paths this component is currently holding -- a delete removes one, a
+     * paste adds one and empties another -- so the page has to reload rather than the
+     * component guessing which levels moved.
+     */
+    onTreeChanged?: () => void;
+    /**
+     * Called after a rename succeeded, so the page reloads the tree.
+     *
+     * The listing cannot reload itself: it reads through `refreshTick`, which the page
+     * owns, and a rename changes the paths this component is currently holding.
+     */
+    onRenamed?: () => void;
+    /**
+     * Render one row's action as "unpin" rather than "pin".
+     *
+     * The pinned band lists paths that are already pinned, so every row there offers
+     * the opposite action; deriving it from a flag keeps one row shape for both bands.
+     */
+    unpinOnly?: boolean;
+    /**
+     * Narrow the tree to rows whose name contains this text.
+     *
+     * Filtering happens over the rows already read, so it costs no request: the tree
+     * section header's search is the in-place narrowing, while the rail's field is the
+     * cross-directory search. A filter that matched nothing read as an empty tree, so
+     * the two empty states are kept apart.
+     */
+    filter?: string;
+    /**
+     * Start with every directory expanded.
+     *
+     * Used by the pinned band, where a pinned folder is only useful if its contents
+     * are already visible.
+     */
+    expandAll?: boolean;
+    /**
+     * The action offered when the tree genuinely holds no documents.
+     *
+     * Distinct from a filter that matched nothing: an empty tree wants a way to make
+     * a document, while an unmatched filter wants a different search term.
+     */
+    emptyAction?: ReactNode;
+    /**
+     * Move one entry into a directory, or pin it when the target is the pin band.
+     *
+     * Omitted by a caller that must stay read-only, which is how the search results
+     * list keeps its rows free of a gesture the Host would refuse there.
+     */
+    onMove?: (from: string, toDirectory: string) => void;
+    /**
+     * The layout to render. `list` is the tree; `grid` is the document cards.
+     *
+     * Defaults to the tree so a caller that does not persist a preference behaves
+     * exactly as it did before the card view existed.
+     */
+    viewMode?: 'list' | 'grid';
+    /**
+     * Enter multi-select. A callback rather than internal state because the batch
+     * bar's actions are the host's (they move and pin through the same routes a
+     * single drag uses), so the selection has to be visible to it.
+     */
+    onSelectionChange?: (paths: readonly string[]) => void;
+    /** The current selection, so a batch action can act on it. */
+    selection?: readonly string[];
+}
+/**
+ * The drag payload's MIME type.
+ *
+ * Exported because the drop target that pins is NOT in this component: the pin
+ * band lives in the panel, and the two have to agree on the name of the thing
+ * being carried. The native drag payload is used rather than lifted React state
+ * for exactly that reason -- it crosses the component boundary the gesture
+ * crosses, without the panel having to hold a second copy of the tree's state.
+ */
+export declare const KB_DRAG_MIME = "application/x-dsh-kb-path";
+/**
+ * Render the listing for the mount's top level, and one level per expanded
+ * directory.
+ * @param props - copy resolver and the open callback.
+ * @returns The listing panel.
+ */
+export declare function KnowledgeListing(props: KnowledgeListingProps): import("react").JSX.Element;

package/lib/types/client/KnowledgeLoading.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The loading state, as a book whose page turns.
+ *
+ * The knowledge base is a library of documents, so a turning page says what is
+ * happening in the product's own terms rather than with a generic spinner. The
+ * animation is CSS and inline SVG: no animation library, because this plugin ships
+ * as one bundled file and a dependency would grow it and add a supply-chain surface
+ * for a decoration.
+ *
+ * The motion is a real 3D turn rather than a sequence of drawn frames: the leaf is a
+ * zero-thickness plane inside a `perspective` container, rotated about the spine with
+ * `rotateY`. That keeps the whole effect to two keyframes and makes the direction of
+ * travel read correctly at any moment, which a frame sequence does not.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Props for the loading surface. */
+export interface KnowledgeLoadingProps {
+    /**
+     * What is being loaded, in the reader's language.
+     *
+     * Optional because a card or a table cell may have no label of its own; the
+     * animation then stands alone and the accessible name falls back to the shared
+     * loading sentence.
+     */
+    label?: string;
+    /**
+     * Accessible name for the animation itself.
+     *
+     * Required rather than derived: the animation is decorative, so it must either be
+     * hidden from assistive technology or carry a name, and hiding it silently would
+     * leave a screen-reader user with no announcement that anything is loading.
+     */
+    announce?: string;
+}
+/**
+ * Render the book-turning loading animation.
+ * @param props - the optional label and the accessible announcement.
+ * @returns The centred loading surface.
+ */
+export declare function KnowledgeLoading(props: KnowledgeLoadingProps): import("react").JSX.Element;

package/lib/types/client/KnowledgeMenuIcon.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The glyph the left sidebar renders for the knowledge-base entry.
+ *
+ * `sidebar.panellist` is a list of icon buttons, so this component receives only a
+ * size and never renders a surface. The page the entry selects is a separate
+ * component registered against the `main` key.
+ *
+ * The glyph is the product's own icon component rather than a local path: the rail
+ * sits directly beside the other panel icons, and a hand-drawn stroke read visibly
+ * heavier than its neighbours. Using the product icon keeps the rail uniform and
+ * lets the size the sidebar passes through unchanged.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Props the sidebar list passes to one entry. */
+export interface KnowledgeMenuIconProps {
+    /** Glyph edge length in pixels, chosen by the sidebar for its current width. */
+    size?: number;
+    /** Whether this entry is the selected panel. */
+    active?: boolean;
+}
+/**
+ * Render the knowledge-base glyph.
+ * @param props - sidebar-supplied glyph size.
+ * @returns The product icon sized for the sidebar rail.
+ */
+export declare function KnowledgeMenuIcon(props: KnowledgeMenuIconProps): import("react").JSX.Element;

package/lib/types/client/KnowledgePanel.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The knowledge-base management page.
+ *
+ * Selected by the left-sidebar entry and rendered into the `main` slot, so it
+ * replaces the conversation area. The page carries its own master-detail layout:
+ * the rail holds a menu above the knowledge tree, and the content region shows
+ * whichever surface the rail selected (a file preview, permissions, or indexing).
+ *
+ * The tree is this package's own listing rather than the file component from
+ * `dsh-better-sidebar`. That component renders icon and name only and builds its
+ * context menu internally, so it has nowhere to show whether a row is readable and
+ * nowhere to add a grant entry, while the actions its menu does offer (rename,
+ * delete, upload) edit a shared curated store rather than deciding who may see a
+ * document. The one thing worth keeping from it is the `@`-reference action, reused
+ * through its own helper so both trees insert the same reference.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/**
+ * The session binding the page scopes its file tree with.
+ *
+ * It is a subscribable observable rather than a plain value because the session it
+ * names appears only after a Workspace is chosen, which regularly happens after
+ * this page has already mounted.
+ */
+export interface SessionSource {
+    /** Current binding; `key` is the session id, absent before a session exists. */
+    getSnapshot: () => {
+        key?: unknown;
+    };
+    /** Subscribe to changes; returns the unsubscribe function. */
+    subscribe: (listener: () => void) => () => void;
+}
+/** Values the `main` slot injects into the page. */
+export interface KnowledgePanelInjected {
+    /** Locale-bound copy for this package's namespace. */
+    t: (key: string) => string;
+    /** Locale tag the slot bound for this namespace, so dates match the reader. */
+    locale?: string;
+    /** Source of the session the file tree resolves its scope from. */
+    sessionSource: SessionSource;
+    /**
+     * The client context, needed by the borrowed tree's `@` helper.
+     *
+     * That helper resolves the workspace root and the conversation input service
+     * itself, so it needs the context rather than the values it reads from it.
+     */
+    ctx: unknown;
+}
+/** Props the page receives. */
+export interface KnowledgePanelProps extends Partial<KnowledgePanelInjected> {
+}
+/**
+ * Render the knowledge-base management page.
+ * @param props - injected locale copy and the current session id.
+ * @returns The master-detail page.
+ */
+export declare function KnowledgePanel(props: KnowledgePanelProps): import("react").JSX.Element;

package/lib/types/client/KnowledgePermissionOverview.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The permissions surface: one grant table, read two ways.
+ *
+ * A grant says "this principal may do this action to this path". That is the right
+ * shape to STORE and the wrong shape to AUDIT: an administrator asking "what does
+ * 张三 have" and "who can see 制度.md" is asking two questions that one
+ * row-per-grant layout cannot answer without being read line by line.
+ *
+ * So the page has one body and two readings of it. The tabs switch which question
+ * is being asked; both render the same loaded grants, so the two can never
+ * disagree. No second endpoint exists because there is no second truth.
+ *
+ * The tables are the page's own body rather than a summary above one. An earlier
+ * version stacked both readings as bulleted lists and *also* drew a third,
+ * row-per-principal table underneath: three renderings of one payload, so the
+ * reader had to work out which of the three was authoritative before reading any
+ * of them. Two tabs over one table removes that question.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/KnowledgePermissionOverview
+ */
+import type { GrantView, KnowledgeGrantSubjectType } from '../api.ts';
+import { type RoleSummary } from './roleSummary.ts';
+/** Which reading of the grant table the tabs are showing. */
+export type OverviewTab = 'person' | 'role' | 'resource';
+/** Copy for the overview, supplied by the caller's locale record. */
+export interface OverviewCopy {
+    tabByPerson: string;
+    tabByRole: string;
+    tabByResource: string;
+    empty: string;
+    /** Empty state per view, so "nobody is directly granted" is not shown for a role. */
+    emptyByPerson: string;
+    emptyByRole: string;
+    emptyByResource: string;
+    /** Where a principal's access comes from. */
+    sourceDirect: string;
+    /** Format "inherited via role X": `{role}` is replaced by the role code. */
+    sourceViaRole: (role: string) => string;
+    /** Shown when the user directory could not be read, so inheritance is unknowable. */
+    sourceUnavailable: string;
+    /** Word for a permission set that could not be fully determined. */
+    actionsUnknown: string;
+    actionsUnknownHint: string;
+    /** Column headers unique to the three views. */
+    colAccount: string;
+    colSource: string;
+    /** "{count} member(s)". */
+    roleMemberCount: (count: number) => string;
+    /** Pager copy, shared with the audit table's wording. */
+    pagerPrev: string;
+    pagerNext: string;
+    pagerStatus: (page: number, pageCount: number, total: number) => string;
+    pageSizeLabel: string;
+    pageSizeOption: (size: number) => string;
+    pathsHeld: (count: number) => string;
+    rolesHeld: string;
+    actionsHeld: string;
+    builtInRoles: string;
+    noActions: string;
+    /** Accessible name for the tab strip, for readers who arrive at it by keyboard. */
+    tabsLabel: string;
+    /** Stat-card labels: the four numbers the page leads with. */
+    statPrincipals: string;
+    statResources: string;
+    statGrants: string;
+    statRoles: string;
+    /** Shared column headers, person reading. */
+    colPrincipal: string;
+    colKind: string;
+    colPermission: string;
+    colResources: string;
+    colExpiry: string;
+    colActions: string;
+    /** Shared column headers, resource reading. */
+    colResource: string;
+    colHolders: string;
+    colKindOfResource: string;
+    revoke: string;
+    revokeBusy: string;
+    expiryNever: string;
+    kindFile: string;
+    kindDirectory: string;
+    /** Formats "N grants · M paths" under a person's name. */
+    grantsUnit: (count: number) => string;
+    resourcesUnit: (count: number) => string;
+    /**
+     * Resolves a principal kind and an action to its localized word.
+     *
+     * Supplied as callbacks rather than as a keyed map so this component never
+     * reaches into the locale record itself: a caller with its own wording (a test,
+     * another surface) can pass its own, and the type checker still enforces that
+     * every kind and action the table can print has a word.
+     */
+    kindLabel: (kind: KnowledgeGrantSubjectType) => string;
+    actionLabel: (action: string) => string;
+}
+/** Props the parent panel supplies. */
+export interface KnowledgePermissionOverviewProps {
+    /** The grant table already loaded by the permissions page. */
+    grants: readonly GrantView[];
+    /** Display names by `principalType:principalId`. */
+    labels?: Readonly<Record<string, string>>;
+    /**
+     * The DataOps account directory, when the caller could read it.
+     *
+     * Absent means the same as an unavailable read: inheritance cannot be attributed, and
+     * the page says so instead of listing accounts that look like they hold nothing.
+     */
+    directory?: {
+        kind: 'available';
+        users: ReadonlyArray<{
+            id: string;
+            label: string;
+            username?: string;
+            roleCodes?: string[];
+        }>;
+    } | {
+        kind: 'unavailable';
+        reason: string;
+    };
+    /** Built-in role summaries, so the person view can explain what a role means. */
+    roles?: readonly RoleSummary[];
+    /** Locale copy. */
+    copy: OverviewCopy;
+    /**
+     * Asks the parent to confirm revoking the grants one row covers.
+     *
+     * The confirmation lives in the parent because it is a dialog, and a dialog in
+     * the middle of a table's row renderer would make the table responsible for
+     * ownership of the overlay. This component says *what* to revoke; the parent
+     * decides whether to ask first and then performs it.
+     */
+    onRevoke: (grants: GrantView[], label: string) => void;
+    /** Disables every revoke control while a write is in flight. */
+    busy?: boolean;
+}
+/**
+ * Render the permission overview as stat cards over a three-tab table.
+ *
+ * THREE views, not two, because the old pair answered different questions under one
+ * heading: "by person" listed ROLE grants, so the only rows were 管理员 and 超级管理员
+ * and a reader concluding "these are the people with access" was reading the page
+ * correctly and being told something false. A role is not a person.
+ *
+ * @param props - grants, labels, directory, role summaries, copy and the revoke hook.
+ */
+export declare function KnowledgePermissionOverview(props: KnowledgePermissionOverviewProps): import("react").JSX.Element;

package/lib/types/client/KnowledgePermissions.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The permissions surface of the management page.
+ *
+ * This view reads and writes grants through the DSH Host, which forwards them to
+ * the DataOps backend. It deliberately holds no policy of its own: the backend's
+ * authorization resolves the principal, checks the caller's permission keys, and
+ * enforces what a grant means. The page only presents the result, so a rule
+ * change lands in one place.
+ *
+ * The page leads with its table. A grant list is what an operator opens this
+ * surface to read, so the data is the body of the page and the two things that
+ * CHANGE it -- creating a grant, revoking one -- are raised into dialogs. A form
+ * parked above the table would push the answer below the fold to make room for
+ * the question.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import { type ReactNode } from 'react';
+/** Props for the permissions surface. */
+export interface KnowledgePermissionsProps {
+    /**
+     * Publishes this page's primary control to the panel header.
+     *
+     * The header is the only band at the top of the page, so a page-level action has
+     * to be handed up rather than drawn in a second title row.
+     */
+    onAction?: (action: ReactNode) => void;
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /** Mount point the grants are scoped to. */
+    mountPoint: string;
+    /** Path the user selected, when the surface opened from a file row. */
+    initialPath?: string;
+    /**
+     * Changes when a row's context menu picks a new path.
+     *
+     * The form's path field is seeded from `initialPath` once; without a signal that
+     * the seed changed, a second right-click would leave the field on the first path.
+     */
+    reloadToken?: number;
+}
+/**
+ * Render the permission editor.
+ * @param props - copy resolver and the mount point grants are scoped to.
+ * @returns The permission surface.
+ */
+export declare function KnowledgePermissions(props: KnowledgePermissionsProps): import("react").JSX.Element;

package/lib/types/client/KnowledgeProgressPanel.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The progress strip at the bottom of the knowledge base panel.
+ *
+ * Uploading a document and extracting its text are two waits a reader cannot see
+ * otherwise: the drop appears to do nothing until the bytes land, and a scanned PDF
+ * looks uploaded while its `.md` sibling is still being produced. Both are reported
+ * here, in one place, at the bottom of the surface the reader is already looking at.
+ *
+ * It is a resident strip rather than a toast on purpose. A toast is gone before a slow
+ * parse finishes, and the reader's next question ("did it work?") has nowhere to go;
+ * this stays until the work is done and then folds to one line so it stops taking
+ * space without taking the record away.
+ *
+ * Nothing here is persisted. A refresh loses the history, which is the right trade: the
+ * files themselves are on disk, and a stale "uploading 40%" from yesterday would be a
+ * lie the reader cannot clear.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** One file's upload, as the strip shows it. */
+export interface UploadTaskView {
+    /** The file's path relative to the drop target: the name the reader dropped. */
+    name: string;
+    /** The tree-relative directory it is landing in, `''` for the mount root. */
+    dir: string;
+    /** Where this file is in its own lifecycle. */
+    state: 'waiting' | 'uploading' | 'done' | 'failed';
+    /** Why it failed, in the Host's own words. */
+    reason?: string;
+}
+/** Props for the progress strip. */
+export interface KnowledgeProgressPanelProps {
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /** The batch currently uploading, oldest first; empty when nothing is in flight. */
+    uploads: readonly UploadTaskView[];
+    /**
+     * Whether to read extraction progress at all.
+     *
+     * False on a surface that cannot extract (no mount, or a caller without write
+     * access): polling a route whose answer can never be acted on is a request per
+     * reader that buys nothing.
+     */
+    watchExtraction: boolean;
+    /** Called after a retry was accepted, so the caller can refresh its own views. */
+    onRetried?: (relPath: string) => void;
+}
+/**
+ * Render the bottom progress strip.
+ * @param props - the upload batch, whether to watch extraction, and the copy resolver.
+ * @returns The strip, or nothing when there is no work to show.
+ */
+export declare function KnowledgeProgressPanel(props: KnowledgeProgressPanelProps): import("react").JSX.Element | null;

package/lib/types/client/KnowledgeReferencePicker.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The `@`-mention picker: choose which conversation a knowledge file goes into.
+ *
+ * The explorer row's `@` button used to answer `if (sessionId === undefined) return`
+ * -- a page with no conversation open simply dropped the click, so the button looked
+ * broken. But "no conversation open" is exactly the state this page is in most of the
+ * time: it is a management surface, not a chat. The reference still has to land
+ * somewhere, so the click now asks where.
+ *
+ * Two things are deliberately borrowed rather than invented:
+ *
+ * The insertion itself is `referenceInChat`, the same contract the sidebar explorer
+ * and the viewer's selection popup call. That function owns the whole policy this
+ * dialog must not re-derive: which workspace root the mention is relative to, the
+ * chip spelling for files versus folders, the quoted form for paths with spaces, and
+ * the "degrade to a logged no-op" behaviour when a service is missing. Building a
+ * second insertion path here would be the one way to make the two surfaces disagree.
+ *
+ * The session list and the navigation are the host's own services, resolved lazily
+ * through `ctx.get` rather than injected: this dialog is mounted whether or not the
+ * user has ever opened a conversation, and a page that cannot see `uiSession` must
+ * still render (it would show an empty list, not crash).
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Props for the picker. */
+export interface KnowledgeReferencePickerProps {
+    /** Whether the dialog is showing. */
+    open: boolean;
+    /** Close without referencing anything. */
+    onClose: () => void;
+    /** Absolute path of the entry the `@` button was pressed on. */
+    path: string;
+    /** Whether that entry is a directory (a folder mention rather than a file chip). */
+    isDir: boolean;
+    /**
+     * Every entry a multi-row selection asked to reference.
+     *
+     * Present only when the `@` button was pressed with several rows selected; the
+     * single-row case keeps using `path`/`isDir`. Each entry carries its own `isDir`
+     * because a selection may mix folders and documents, and the mention spelling
+     * differs between them.
+     *
+     * This is one dialog for both cases on purpose: "where should this go" is the same
+     * question whether one row or five are being referenced, and a second batch-only
+     * dialog would be a second place for the insertion contract to drift.
+     */
+    targets?: readonly {
+        path: string;
+        isDir: boolean;
+    }[];
+    /** The client context; both the draft insert and the service lookups need it. */
+    ctx: unknown;
+    /** Locale-bound copy for this package's namespace. */
+    t: (key: string) => string;
+    /** Locale tag, so a session's timestamp reads in the reader's language. */
+    locale?: string;
+    /**
+     * The conversation the host currently has selected, read at call time.
+     *
+     * The New Session flow creates a conversation asynchronously and does not return
+     * its id, so the only way to name it afterwards is to ask the page's own session
+     * binding -- the same observable the file tree is scoped by. Reading it lazily
+     * rather than as a prop is what makes it current by the time the draft is ready.
+     */
+    selectedSessionId?: () => string | undefined;
+    /**
+     * Called once a reference was actually inserted, with the session that received it.
+     *
+     * The dialog closes itself either way; this exists so the page can report which
+     * conversation the file went to, which is the only feedback a reader gets when the
+     * target tab is not the one they were looking at.
+     */
+    onReferenced?: (sessionId: string) => void;
+}
+/**
+ * The `@`-mention session picker.
+ * @param props - the entry to reference and the dialog's state.
+ * @returns The dialog, or null while closed.
+ */
+export declare function KnowledgeReferencePicker(props: KnowledgeReferencePickerProps): import("react").JSX.Element;