@sparkelf/dsh-knowledge-base 0.1.4 → 0.1.20

package/lib/types/api.d.ts

@@ -12,6 +12,7 @@
  *
  * @module @sparkelf/dsh-knowledge-base/api
  */
+import type { VectorRetrievalConfig } from './embeddings.ts';
 /** Prefix the Host registers and the browser calls. */
 export declare const KB_API_PREFIX = "/knowledge-base/api";
 /** Method names the Host dispatches on. */
@@ -45,10 +46,14 @@ export declare const KB_API: {
     readonly list: "list";
     /** Read one file for the preview, without needing a conversation session. */
     readonly read: "read";
+    /** Resolve a kb://doc/<docId>/chunk/<chunkId> token to all page boxes. */
+    readonly chunk: "chunk";
     /** Rebuild the caller's visible tree from what DataOps resolves for them. */
     readonly viewsSync: "views.sync";
     /** Rescan the mounted tree and report its shape. */
     readonly index: "index";
+    /** Explicitly rebuild the whole optional vector index (requires confirmation). */
+    readonly vectorRebuild: "vector.rebuild";
     /**
      * Report the mounted tree's per-directory shape.
      *
@@ -239,6 +244,8 @@ export interface KnowledgeConfigView {
     host: string;
     /** Absolute path of the authoritative tree on the storage host. */
     actualRoot: string;
+    /** Local deployments: configured storage path (default `~/kb`). */
+    storageRoot?: string;
     /** Absolute path of the caller's view tree on the storage host. */
     viewRoot: string;
     /** Path where the view tree is mounted inside the container. */
@@ -256,6 +263,10 @@ export interface KnowledgeConfigView {
     storageProtocol?: 'nfs' | 'sshfs';
     /** SSHFS transport, present so the panel can show and edit what it will mount. */
     ssh?: KnowledgeSshView;
+    /** Optional hybrid retrieval configuration, safe to render (credential reference only). */
+    retrieval?: {
+        vector: VectorRetrievalConfig;
+    };
 }
 /** One transport field the panel may persist. */
 export interface KnowledgeConfigWrite {
@@ -345,6 +356,28 @@ export interface KnowledgeStatusView {
      * with that single name exactly as it did before hierarchy existed. Code that
      * assumed the path was present would break against such a backend.
      */
+    /** Backend DSH permission keys for this caller; used only to hide dead-end menus. */
+    permissions?: readonly string[];
+    /** Optional vector index coverage/progress. */
+    vector?: {
+        enabled: boolean;
+        provider?: string;
+        model?: string;
+        embeddedChunks: number;
+        totalChunks: number;
+        embeddedDocs: number;
+        totalDocs: number;
+        failed: number;
+        canManageVector?: boolean;
+        indexing: {
+            running: boolean;
+            total?: number;
+            done?: number;
+            embedded?: number;
+            failed?: number;
+            error?: string;
+        };
+    };
     caller?: {
         userId: string;
         label: string;
@@ -583,7 +616,7 @@ export interface KnowledgeTemplateSaveInput {
     id?: string;
 }
 /** Where one extraction task is in its lifecycle, as the Host reports it. */
-export type ExtractionStateView = 'pending' | 'running' | 'succeeded' | 'failed' | 'unsupported';
+export type ExtractionStateView = 'pending' | 'running' | 'succeeded' | 'failed' | 'unsupported' | 'already-markdown';
 /**
  * One extraction task.
  *
@@ -596,6 +629,8 @@ export interface ExtractionTaskView {
     relPath: string;
     /** Where the task is in its lifecycle. */
     state: ExtractionStateView;
+    /** Current Agentic RAG stage (parse/chunk/index/done), when running. */
+    step?: 'parse' | 'chunk' | 'index' | 'done';
     /** When the task was accepted, ISO-8601. */
     queuedAt: string;
     /** When the run started, ISO-8601. */

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

@@ -22,6 +22,8 @@
  *
  * @module @sparkelf/dsh-knowledge-base/client
  */
+import type { TreeClipboard } from './KnowledgeContextMenu.tsx';
+import type { FileTreeSort } from 'dsh-better-sidebar/src/client/file-tree-sort.ts';
 /**
  * Where a create or upload should land when the reader has not said otherwise.
  *
@@ -118,6 +120,29 @@ export interface KnowledgeCreateDialogProps {
     onClose: () => void;
     /** The directory the dialog should start in, from {@link defaultDestination}. */
     defaultPath: string;
+    /** Absolute mount root, for the upload tree (the same root the sidebar uses). */
+    root?: string;
+    /** Caller identity, so personal extraction rows can be addressed authoritatively. */
+    callerId?: string;
+    /** Real session key for the borrowed explorer; absent uses the KB placeholder. */
+    sessionId?: string;
+    /** Locale tag for tree dates and labels. */
+    locale?: string;
+    /** The same bucket labels the sidebar tree takes. */
+    bucketLabels?: Readonly<Record<string, string>>;
+    /** The same department code/name chain the sidebar tree takes. */
+    departmentPath?: {
+        codes: readonly string[];
+        names: readonly string[];
+    };
+    /** The same explorer ordering the sidebar tree takes. */
+    sort?: FileTreeSort;
+    isFavorite?: (relPath: string) => boolean;
+    onToggleFavorite?: (relPath: string, next: boolean) => void;
+    onShare?: (relPath: string, isDir: boolean) => void;
+    onClipboard?: (entry: TreeClipboard) => void;
+    hasClipboard?: boolean;
+    onPasteInto?: (directory: string) => void;
     /** Locale-bound copy resolver. */
     t: (key: string) => string;
     /**

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

@@ -21,8 +21,36 @@
  * a reader should rename. They are filtered with the `exclude` prop, which the host
  * applies to the listing -- so they never arrive rather than being hidden after the fact.
  *
+ * ## This bundle INLINES the explorer's source, which is why sort needs a sync step
+ *
+ * `FileTree` is imported as SOURCE (`dsh-better-sidebar/src/client/FileTree.tsx`), not as
+ * the package's built output, so its code is compiled into this plugin's bundle. Sorting
+ * lives in two places that this file depends on:
+ *
+ * - `file-tree-sort.ts` — the sort keys and comparators (a separate module, imported by
+ *   `FileTree.tsx`);
+ * - `listing-filter.ts` — the name-matching rule set, shared by the explorer and this
+ *   plugin's list view. It lives in the explorer package, not here, precisely so the two
+ *   surfaces cannot drift apart: `KnowledgeListing` imports it from there too, and there
+ *   is only ONE implementation of "substring, case-insensitive, keep the parent chain".
+ *   It also has to be synced, or the tree's `nameFilter` prop arrives with nothing to run;
+ * - `fs-tree.ts` — the HOST side that puts `mtimeMs`/`size` on each row;
+ * - `sidebar.module.css` / `locales.ts` — the visible row for "no file matched" and its
+ *   two strings.
+ *
+ * That means a change to those files reaches this bundle by COPYING THE SOURCE into the
+ * resolved package under `node_modules/.pnpm/@sparkelf+dsh-better-sidebar@.../` and
+ * rebuilding here. It does NOT arrive by reinstalling the dependency from npm, and the
+ * copy is LOST on a fresh `install` — at which point `sort` silently falls back to the
+ * published keys (no `mtime`, no `size`) and the menu's choices stop matching the data.
+ *
+ * The durable source of truth is the fork at `/root/projects/DSH-better-sidebar`,
+ * branch `sparkelf/kb-save-events`. Reinstalling the dependency therefore means: rebuild
+ * and publish from that branch, bump the dependency, and delete this note.
+ *
  * @module @sparkelf/dsh-knowledge-base/client
  */
+import type { FileTreeSort } from 'dsh-better-sidebar/src/client/file-tree-sort.ts';
 import type { UploadItem } from 'dsh-better-sidebar/src/client/upload.ts';
 import { type DepartmentPath } from './departmentFolders.ts';
 export interface KnowledgeFileTreeProps {
@@ -46,12 +74,33 @@ export interface KnowledgeFileTreeProps {
     busy: boolean;
     /** Bump to reload the visible set after a change made elsewhere. */
     refreshTick: number;
+    /**
+     * The caller's DataOps user id, when the page knows it.
+     *
+     * The tree renders the caller's VIEW, where `personal` hides the owner segment. The
+     * Host reads the AUTHORITATIVE tree, where that segment is required, so an extraction
+     * requested from a personal row must put the id back before it leaves the browser.
+     * Without it the Host answers `404 no such file` for a document the reader can see.
+     */
+    callerId?: string;
     /** Called after the explorer's own inline rename lands. */
     onPathRenamed?: (oldPath: string, newPath: string) => void;
     /** Called after the explorer's own delete lands. */
     onPathDeleted?: (path: string, isDir: boolean) => void;
     /** Whether the owning surface is on screen. */
     visible?: boolean;
+    /**
+     * Hide the explorer's root row. A destination picker draws its own root row so
+     * selecting the mount root is a click, not an expansion.
+     */
+    hideRoot?: boolean;
+    /**
+     * Tree-relative path to paint as selected. Used by the upload destination picker;
+     * `''` is the mount root (the picker draws that row itself).
+     */
+    selectedPath?: string;
+    /** Locale tag for row dates; absent uses the document language. */
+    locale?: string;
     /**
      * Say the three buckets in the reader's language.
      *
@@ -87,8 +136,102 @@ export interface KnowledgeFileTreeProps {
      * caller has no favourites store, which keeps the wrapper from touching the DOM at all.
      */
     isFavorite?: (relPath: string) => boolean;
+    /** Toggle the caller's favourite flag for one document. */
+    onToggleFavorite?: (relPath: string, next: boolean) => void;
     /** The favourites star's accessible name. */
     favoriteMarkLabel?: string;
+    /**
+     * Open the Share dialog for one row.
+     *
+     * The dialog itself lives on the page, not in this wrapper: it is a `Modal`, and the
+     * page already owns one for its own surfaces. This hook exists so the native menu can
+     * offer the entry without this component importing a dialog (which would mount a second
+     * one per tree instance and tie a page-level overlay to a widget's lifecycle).
+     */
+    onShare?: (relPath: string, isDir: boolean) => void;
+    /**
+     * What the cut/copy entries put on the clipboard.
+     *
+     * The clipboard belongs to the page: a copy from this tree has to paste on the table,
+     * and vice versa. Passing it in keeps ONE clipboard rather than a per-surface copy that
+     * would disagree about what "paste" means.
+     */
+    onClipboard?: (entry: {
+        entries: Array<{
+            relPath: string;
+            name: string;
+        }>;
+        cut: boolean;
+    }) => void;
+    /**
+     * Whether the clipboard currently holds anything.
+     *
+     * The Paste row is hidden rather than disabled while this is false: an entry that can
+     * never run in this state advertises an action the reader cannot take.
+     */
+    hasClipboard?: boolean;
+    /**
+     * Paste the clipboard into one directory (tree-relative, `''` for the root).
+     *
+     * The page performs the move/copy and clears the clipboard on a cut; this wrapper only
+     * reports where the click landed.
+     */
+    onPasteInto?: (directory: string) => void;
+    /**
+     * Called the moment an extraction is REQUESTED for one document, before it settles.
+     *
+     * Carries the path so the progress panel can show that document as queued straight away:
+     * a menu item that produces no visible change until a round trip finishes reads as a dead
+     * control. The panel treats this as a guess with a lifetime, and replaces it with the
+     * Host's own task as soon as one is reported.
+     */
+    onExtractionQueued?: (relPath: string) => void;
+    /**
+     * Called when an extraction request was refused or never completed.
+     *
+     * Exists because the menu used to discard the response: a refusal was indistinguishable
+     * from a success, so the reader had nothing to act on.
+     */
+    onExtractionFailed?: (relPath: string, reason: string) => void;
+    /**
+     * How to order the rows.
+     *
+     * Passed straight through to the explorer's own `sort` prop, so the ordering logic and
+     * its comparators stay in one place. Omitted keeps the explorer's default.
+     */
+    sort?: FileTreeSort;
+    /**
+     * Narrow the visible rows to names containing this text.
+     *
+     * Passed straight to the explorer, which applies the same rule set the listing view
+     * uses (`listing-filter.ts`) to the levels it has already loaded: typing therefore costs
+     * no request, a hit inside a collapsed folder keeps its parent chain visible, and
+     * expansion state is untouched so clearing the term restores what was on screen.
+     */
+    nameFilter?: string;
+}
+/**
+ * Add the knowledge actions to the explorer's native row menu.
+ *
+ * The installed explorer builds that menu internally and does not consume the
+ * `extraMenuItems` prop yet, so appending is done at the one place the menu is
+ * visible: after it opens. The clone keeps the menu's own row/typography classes;
+ * the handler closes the menu with Escape, exactly like choosing a native row.
+ *
+ * The contextmenu listener is a normal bubble-phase React handler that only records
+ * the row; it never prevents the explorer's own menu from opening.
+ */
+export interface KnowledgeTreeMenuAction {
+    id: string;
+    label: string;
+    when: (target: {
+        relPath: string;
+        isDir: boolean;
+    }) => boolean;
+    run: (target: {
+        relPath: string;
+        isDir: boolean;
+    }) => void;
 }
 /**
  * The knowledge tree, rendered by the product's file explorer.

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

@@ -15,16 +15,35 @@
  *
  * @module @sparkelf/dsh-knowledge-base/client
  */
+/** One document row, as the table renders it. */
+interface HomeRow {
+    /** Path relative to the mount point. */
+    relPath: string;
+    /** File name alone. */
+    name: string;
+    /** Directory the file sits in, for the Location column. */
+    location: string;
+    /** Last-modified instant in Unix ms, which is the tree's only timestamp. */
+    mtimeMs?: number;
+}
 /** Props for the Home surface. */
 export interface KnowledgeHomeProps {
     /** Locale-bound copy resolver. */
     t: (key: string) => string;
+    /** Real session key for the borrowed file explorer; absent uses its placeholder. */
+    sessionId?: string;
+    /** The same explorer ordering the sidebar tree takes. */
+    sort?: import('dsh-better-sidebar/src/client/file-tree-sort.ts').FileTreeSort;
     /** Locale tag, so dates match the reader's language. */
     locale?: string;
     /** Disabled when the tree is not mounted, so the cards cannot promise a tree. */
     mountPoint: string;
     /** Open one document in the preview. */
     onOpen: (path: string) => void;
+    /** The client context, used to open a Session from the new-document chooser. */
+    ctx?: unknown;
+    /** Authoritative storage root, used when a template is materialized for the agent. */
+    actualRoot?: string;
     /**
      * The caller's DataOps id, when the status route reported one.
      *
@@ -37,6 +56,25 @@ export interface KnowledgeHomeProps {
     departmentCode?: string;
     /** The caller's own department name; the code stands in when this is absent. */
     departmentName?: string;
+    /**
+     * Display names for the three buckets.
+     *
+     * The same map the file tree uses, so one vocabulary covers both surfaces: a folder
+     * called `personal` on disk reads as 「个人」 in the tree AND in this table's Location
+     * column. A second mapping table here is exactly the two-truths defect this reuses the
+     * tree's helper to avoid.
+     */
+    bucketLabels?: Readonly<Record<string, string>>;
+    /**
+     * The caller's organization chain, codes first and names aligned.
+     *
+     * Passed the same way the tree takes it, so a nested department path reads as
+     * 「部门/数据平台」 here instead of `department/data-platform`.
+     */
+    departmentPath?: {
+        codes: readonly string[];
+        names: readonly string[];
+    };
     /**
      * Whether the Host verified this caller may manage grants.
      *
@@ -96,6 +134,25 @@ export interface KnowledgeHomeProps {
         file: unknown;
         relativePath: string;
     }[]) => void;
+    /**
+     * Read the document rows for this mount.
+     *
+     * TEST SEAM, NOT AN EXTENSION POINT. It exists so a test can count how many times the
+     * table re-reads when `refreshTick` bumps -- the only way to tell "the table refreshed"
+     * apart from "a row happened to appear". It is optional and defaults to the real
+     * implementation below, so production behaviour is unchanged; do not use it as a hook
+     * for new features.
+     */
+    readHomeRows?: (mountPoint: string) => Promise<HomeRow[]>;
+    /**
+     * Re-read trigger.
+     *
+     * A file uploaded from anywhere in the panel changes what this table should list, and
+     * the panel already bumps one counter for exactly that. Without this the tree refreshed
+     * and the table did not, so a reader who had just uploaded a file could not find it --
+     * indistinguishable from the upload having failed.
+     */
+    refreshTick?: number;
     /**
      * Where a drop on this table lands, tree-relative.
      *
@@ -111,3 +168,4 @@ export interface KnowledgeHomeProps {
  * @returns The Home view.
  */
 export declare function KnowledgeHome(props: KnowledgeHomeProps): import("react").JSX.Element;
+export {};

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

@@ -125,6 +125,13 @@ export interface KnowledgeListingProps {
      * are already visible.
      */
     expandAll?: boolean;
+    /**
+     * Restrict the rows to these pinned paths and their ancestors.
+     *
+     * The pinned band is a list of pins, not a second copy of the whole tree: without
+     * this the band rendered every top-level entry and called all of them pinned.
+     */
+    pinnedPaths?: readonly string[];
     /**
      * The action offered when the tree genuinely holds no documents.
      *

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

@@ -0,0 +1,32 @@
+/**
+ * The Home surface's "New" chooser.
+ *
+ * A new document is not a file-manager operation here: it starts a conversation
+ * that writes the document. The dialog therefore asks what kind of artefact the
+ * reader wants and hands the prompt to the conversation surface, instead of
+ * asking for a file name and a directory the reader has not opened yet.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import type { ReactNode } from 'react';
+/** The document kinds the conversation can create. */
+export type NewDocumentKind = 'document' | 'spreadsheet' | 'presentation';
+/** Props for the chooser. */
+export interface KnowledgeNewDocumentDialogProps {
+    /** Whether the dialog is showing. */
+    open: boolean;
+    /** Close without choosing a type. */
+    onClose: () => void;
+    /** Start a conversation with the chosen prompt, caret after "一份". */
+    onCreate: (prompt: string, caretOffset: number) => void;
+    /** Open the conventional folder form instead. */
+    onNewFolder: () => void;
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+}
+/**
+ * Render the type chooser.
+ * @param props - open state and the two actions.
+ * @returns The dialog.
+ */
+export declare function KnowledgeNewDocumentDialog(props: KnowledgeNewDocumentDialogProps): ReactNode;

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

@@ -0,0 +1,69 @@
+/**
+ * The progress notification button and its panel.
+ *
+ * Uploading a document and extracting its text are two waits a reader cannot see
+ * otherwise: a dropped file looks like nothing happened until the bytes land, and a
+ * scanned PDF looks uploaded while its `.md` sibling is still being produced.
+ *
+ * This is the notification form of that information: a bell in the panel header whose
+ * badge counts the work still in flight, opening a panel that names every task. It
+ * replaces an earlier strip pinned to the panel's foot, which was too narrow -- file
+ * names were cut to a few characters ("中电信桂【2025】150号…"), which is exactly the
+ * detail a reader needs to tell two uploads apart.
+ *
+ * Only the PRESENTATION lives here. The upload rows come from the panel's own upload
+ * code and the extraction rows from `extract.status`; this module reads and retries,
+ * it does not own either data path.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import type { FailedExtractionView, OptimisticExtraction } from './progressRules.ts';
+import type { UploadTaskView } from './progressRules.ts';
+/** Props for the notification button and panel. */
+export interface KnowledgeProgressPopoverProps {
+    /** 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): polling a route whose answer can
+     * never be acted on costs a request per reader and buys nothing.
+     */
+    watchExtraction: boolean;
+    /** Called after a retry was accepted, so the caller can refresh its own views. */
+    onRetried?: (relPath: string) => void;
+    /**
+     * A counter the page bumps when extraction changed outside this panel's own polling.
+     *
+     * The panel polls only while it already knows about pending work, so an extraction
+     * queued from a context menu -- exactly the case where it knows about none -- would
+     * never appear. Watching a counter makes that one re-read reachable without adding a
+     * second timer.
+     */
+    refreshSignal?: number;
+    /**
+     * Documents the reader asked to extract that the Host has not reported yet.
+     *
+     * Drawn as a "queued" row so the click has a visible answer before the round trip
+     * finishes. Each entry is replaced by the Host's own task the moment `extract.status`
+     * mentions it, and expires on its own when it is never confirmed.
+     */
+    optimistic?: readonly OptimisticExtraction[];
+    /**
+     * Requests this page session saw refused before the Host created a task.
+     *
+     * `extract.retry` answers 404/403 before it enqueues anything, so the Host's snapshot
+     * never mentions those failures. Without these rows the panel would show an empty state
+     * right after the reader watched an extraction fail -- the exact silence this panel
+     * exists to remove. The page owns the store; this component only draws it.
+     */
+    failures?: readonly FailedExtractionView[];
+}
+/**
+ * The notification button and its progress panel.
+ * @param props - the upload batch, whether to watch extraction, and the copy resolver.
+ * @returns The button, plus the panel while it is open.
+ */
+export declare function KnowledgeProgressPopover(props: KnowledgeProgressPopoverProps): import("react").JSX.Element;

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

@@ -22,9 +22,10 @@
 /**
  * The settings surface of the management page.
  *
- * This page is now only the review switch: a DECISION about whether other people's
- * contributions take effect immediately, so it is a control and it needs write
- * access. The queue that decision governs and the trail of what it settled both
+ * This page carries the review switch and the shared vector-retrieval group: the
+ * switch is a DECISION about whether other people's contributions take effect
+ * immediately, so it needs write access; the vector group is the same component the
+ * DSH settings section renders, which keeps a profile without that slot usable. The queue that decision governs and the trail of what it settled both
  * moved to the Audit page, which is the surface an operator opens to get through
  * work; parking a worklist under a configuration switch made them scroll past the
  * setting to reach today's arrivals, and left two duplicate entry points pointing

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

@@ -32,8 +32,12 @@ export interface KnowledgeTemplatesProps {
     mountPoint?: string;
     /** The caller's id, so the destination default prefers their own folder. */
     callerId?: string;
+    /** Authoritative storage root, where a materialized template is readable by the agent. */
+    actualRoot?: string;
     /** Open a document once it has been created from a template. */
     onOpen?: (relPath: string) => void;
+    /** Start a conversation that references the materialized template file. */
+    onStartSession?: (prompt: string) => void;
 }
 /**
  * Render the template library.

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

@@ -0,0 +1,17 @@
+/**
+ * Shared "vector retrieval" settings group.
+ *
+ * One component owns the config/status reads, the save call and the rebuild poll so
+ * the DSH Settings section and the knowledge-base panel's own Settings page cannot
+ * drift. The group is deliberately self-loading: a profile that never mounts
+ * `settings.section` still gets the same controls because the panel renders this
+ * component directly.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Copy resolver; accepts both the DSH settings locale function and the panel one. */
+export type VectorSettingsT = (key: any) => string;
+/** One self-contained vector settings group. */
+export declare function VectorSettingsGroup({ t }: {
+    t: VectorSettingsT;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,22 @@
+/**
+ * The glyph the left sidebar renders for the 「工作流广场」 entry.
+ *
+ * A calendar outline rather than the knowledge-base document glyph: two entries with
+ * the same artwork would be indistinguishable on the rail. Sized by the sidebar and
+ * coloured by `currentColor`, so it follows the selected/idle row state.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Props the sidebar list passes to one entry. */
+export interface WorkflowMenuIconProps {
+    /** 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 workflow-plaza glyph.
+ * @param props - sidebar-supplied glyph size.
+ * @returns The calendar outline sized for the sidebar rail.
+ */
+export declare function WorkflowMenuIcon(props: WorkflowMenuIconProps): import("react").JSX.Element;

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

@@ -0,0 +1,33 @@
+/**
+ * Where a dropped file actually lands.
+ *
+ * The tree shows a reader a `personal` folder, but the authoritative tree stores every
+ * caller's documents under their own id (`personal/<owner>/<file>`) -- the owner segment
+ * is hidden from the view on purpose, because it is an implementation detail a reader
+ * never typed. The consequence is that a tree row labelled 「个人」 carries the path
+ * `personal`, and writing straight to it puts the file in `personal/` beside the owner
+ * directories, where no view will ever show it: the reader uploads, the progress row says
+ * "done", and the file is invisible.
+ *
+ * This module owns that translation so every drop entry point (the borrowed explorer, the
+ * plugin's own listing, the Home table) answers the same question the same way.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/**
+ * Resolve a view-relative directory into the authoritative path a write must use.
+ *
+ * A `personal` path gains the caller's id as its second segment, at whatever depth the
+ * drop names: the bucket row (`personal`), a folder inside it (`personal/specs`), or one
+ * nested deeper all resolve to the caller's own subtree. Everything else (`global`,
+ * `department/...`, `''` for the mount root) is already authoritative and passes through.
+ *
+ * A `personal` path with no caller id is REFUSED rather than passed through. Writing to
+ * `personal` without an owner is exactly the defect this function exists to prevent, so
+ * the refusal is explicit: `undefined` means "no safe destination", and the caller reports
+ * it instead of writing somewhere the reader cannot see.
+ * @param viewRelDir - the directory as the VIEW names it (what a tree row carries).
+ * @param callerId - the id the Host reports for the caller, when it is known.
+ * @returns The authoritative relative directory, or undefined when it cannot be resolved.
+ */
+export declare function resolveUploadDir(viewRelDir: string, callerId: string | undefined): string | undefined;

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

@@ -0,0 +1,43 @@
+/**
+ * Failures this browser session saw that the Host has no task for.
+ *
+ * A refused extraction never reaches `extract.status`: the Host answers 404 before it
+ * creates a queue entry, so the progress panel -- which reads only the Host's snapshot --
+ * could not show the one failure the reader just hit. This store is the panel's own
+ * memory of those refusals.
+ *
+ * It lives at module scope rather than in component state for one reason: the knowledge
+ * panel unmounts when the reader visits another destination, and a failure that vanished
+ * on navigation would be indistinguishable from one the feature never recorded. The
+ * store is per page load, which is the "this session" the reader means -- a reload is a
+ * new session, and the filesystem (not this array) remains the authority on disk.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import type { FailedExtractionView } from './progressRules.ts';
+/** Most failures kept; an unbounded array would grow for the life of the tab. */
+export declare const SESSION_FAILURE_LIMIT = 50;
+/**
+ * Record one refused extraction.
+ *
+ * Re-recording a path REPLACES its earlier reason and moves it to the end: a reader who
+ * retried and failed differently needs the newest reason, and the list reads newest-last.
+ * @param entry - the path, the raw reason, and when it was observed (defaults to now).
+ */
+export declare function rememberExtractionFailure(entry: {
+    relPath: string;
+    reason: string;
+    at?: number;
+}): void;
+/**
+ * Read the session's failures.
+ * @returns A copy, so a caller cannot mutate the store by accident.
+ */
+export declare function readExtractionFailures(): FailedExtractionView[];
+/**
+ * Drop one path's recorded failure, e.g. after a retry was accepted.
+ * @param relPath - the document whose failure is no longer current.
+ */
+export declare function forgetExtractionFailure(relPath: string): void;
+/** Clear every recorded failure. Exists for tests; no production path calls it. */
+export declare function clearExtractionFailures(): void;