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

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

@@ -0,0 +1,87 @@
+/**
+ * Wire the knowledge base into the sidebar editor's save events.
+ *
+ * The knowledge base does not own the editor. Documents are shown in the host's own
+ * file window, and that window saves through its own route -- so a save never passes
+ * through a knowledge-base code path, and an audit trail written only from this
+ * plugin's routes would miss every edit made in the editor.
+ *
+ * The sidebar therefore accepts two registrations, both optional to it:
+ *
+ * - A **save actor** answers "who is acting right now". The knowledge base registers
+ *   one that reports the DataOps identity the Host resolved.
+ * - A **save listener** receives every successful save after the bytes landed.
+ *
+ * The knowledge base registers both. What it does with an event is deliberately
+ * duller than it could be: it posts the save to its own append-only audit route and
+ * forgets about it. Delivery is fire-and-forget, so a knowledge base that is down,
+ * slow, or misconfigured cannot turn a completed save into a failed one -- which is
+ * the whole reason the sidebar calls listeners without awaiting them.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/**
+ * Turn an absolute path back into a knowledge-base relative path.
+ *
+ * The sidebar reports absolute paths because that is what it edits. The audit route
+ * speaks the relative paths every other knowledge-base surface uses, so the mount
+ * point is stripped here rather than sending an absolute path the route would have
+ * to guess a root for.
+ * @param absolutePath - the path the sidebar saved.
+ * @param mountPoint - the knowledge root, absolute.
+ * @returns The relative path, or undefined when the save was outside the root.
+ */
+export declare function toKnowledgePath(absolutePath: string, mountPoint: string): string | undefined;
+/**
+ * Decide whether a save belongs to the knowledge base, and under which path.
+ *
+ * Two shapes show up in practice and both mean the same document:
+ *
+ * - The editor reports an absolute path when it edits outside a session workspace.
+ * - It reports a path relative to the session workspace (`kb/test-toc.md`) when the
+ *   document was reached through the workspace, which is the ordinary case here: the
+ *   knowledge view is linked into `/workspace/kb`.
+ *
+ * The knowledge root is reported by the page as its configured mount point, and the
+ * view is what the editor actually opens, so the mount point's last segment (`kb`)
+ * is the prefix that identifies knowledge-base saves in the relative shape. Matching
+ * on that segment rather than on the full absolute path is what makes the workspace
+ * route work at all.
+ * @param savedPath - the path the editor reported.
+ * @param mountPoint - the knowledge root as the page configured it.
+ * @returns The knowledge-base relative path, or undefined when the save is elsewhere.
+ */
+export declare function matchKnowledgeSave(savedPath: string, mountPoint: string): string | undefined;
+/**
+ * Register the knowledge base as a save actor and a save listener.
+ *
+ * Safe to call on a host without the extension: every access is optional and an
+ * absent service simply means nothing is registered. The returned disposer removes
+ * both registrations, so a plugin unload cannot leave a listener pointing at a
+ * closed page.
+ *
+ * @param ctx - the client context the page runs in.
+ * @param mountPoint - the knowledge root, used to keep saves outside it out of the trail.
+ * @returns A disposer, or a no-op when the sidebar service is absent.
+ */
+export declare function registerSaveAudit(ctx: unknown): () => void;
+/**
+ * Install the resolver that reports the knowledge root.
+ *
+ * The page is what knows the mount point (it comes from the Host's config), and the
+ * save listener needs it to tell a knowledge-base save from any other file's save.
+ * Passing a getter rather than a string keeps the registration alive across a mount
+ * point that arrives after the listener is installed.
+ * @param resolver - returns the current knowledge root, absolute.
+ */
+export declare function setMountPointResolver(resolver: () => string): void;
+/** Install the resolver the plugin's apply step owns. */
+export declare function setActorResolver(resolver: () => string | undefined): void;
+/**
+ * Publish the DataOps identity to the save-actor registration.
+ *
+ * The page resolves it through its own status call; the registration lives at plugin
+ * scope, so the value travels through here rather than being fetched twice.
+ * @param id - the caller id DataOps reported, or undefined when none is known.
+ */
+export declare function publishActor(id: string | undefined): void;

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

@@ -0,0 +1,81 @@
+/**
+ * Turning grants into the two "share" groups the Home tab shows.
+ *
+ * The split the reader cares about is DIRECTION: what has been shared with me, and what
+ * I have shared out. The grant data has no grantor field (the backend's `toSummary`
+ * omits it and the table has no `created_by`), so "who gave me this" cannot be answered
+ * from it. What CAN be answered is the audience side: which principal a grant names.
+ *
+ * Everything here is a pure function of the grant list plus the caller, which is what
+ * makes the two-way split testable without a browser.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** One grant, in the shape the Host relays. */
+export interface ShareGrant {
+    /** Stable row id. */
+    id: string;
+    /** Path relative to the knowledge mount point. */
+    relPath: string;
+    /** Whether the path is a file or a directory. */
+    kind: 'file' | 'directory';
+    /** Principal kind the grant names. */
+    principalType: 'user' | 'role' | 'department' | 'group';
+    /** Principal id within its kind. */
+    principalId: string;
+    /** Permission the grant confers. */
+    action: string;
+}
+/** A principal name lookup: id per kind, falling back to the id itself. */
+export type PrincipalNameOf = (kind: ShareGrant['principalType'], id: string) => string | undefined;
+/** Which group one grant belongs to. */
+export type ShareDirection = 'received' | 'given';
+/** One row of either group. */
+export interface ShareRow {
+    /** Stable row id, taken from the grant. */
+    id: string;
+    /** Path relative to the knowledge mount point. */
+    relPath: string;
+    /** File name alone, for the row's title. */
+    name: string;
+    /** Directory the path sits in, for the location column. */
+    location: string;
+    /** Principal kind the grant names. */
+    principalType: ShareGrant['principalType'];
+    /** The audience this grant names, resolved to a display name when possible. */
+    audience: string;
+    /** The permission the grant confers. */
+    action: string;
+}
+/**
+ * Whether a grant names the caller directly.
+ *
+ * Only a `user` grant can: a role, department or group is an audience the caller
+ * belongs to rather than the caller themselves, and treating it as "me" would let a
+ * department-wide grant read as a personal share.
+ * @param grant - the grant to test.
+ * @param callerId - the caller's own user id, when known.
+ * @returns True when the grant names this exact user.
+ */
+export declare function isOwnGrant(grant: ShareGrant, callerId: string | undefined): boolean;
+/**
+ * Split grants into the two directions the Home tab shows.
+ *
+ * The rule is deliberately simple and says only what the data supports: a grant that
+ * names the caller is "shared with me"; every other grant is "shared out". It does NOT
+ * claim the caller created the latter -- the grantor is not in this data at all -- so
+ * callers must word that group as an audience ("I shared to X"), never as a fact about
+ * who granted it.
+ *
+ * A grant naming the caller is excluded from the outgoing group even when it also
+ * appears there, so one document cannot look like it was shared to the reader and by
+ * the reader at the same time.
+ * @param grants - every grant the Host relayed.
+ * @param callerId - the caller's own user id, when known.
+ * @param nameOf - the principal directory lookup.
+ * @returns Both groups, each in the order the grants arrived.
+ */
+export declare function splitShareRelations(grants: readonly ShareGrant[], callerId: string | undefined, nameOf: PrincipalNameOf): {
+    received: ShareRow[];
+    given: ShareRow[];
+};

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

@@ -0,0 +1,49 @@
+/**
+ * The favourites store the tree's star column renders.
+ *
+ * A star is a document-level preference, so it lives beside `.pinned.json` and
+ * `.kb-tree-state.json` in the caller's own view directory rather than in browser
+ * storage: a reader who stars a report on one machine expects to find it starred on
+ * the next, and a browser profile is not the unit a knowledge base follows.
+ *
+ * The write path is deliberately the same shape as `useTreeState`'s. A reader who
+ * stars a few rows in a row makes one gesture per row, and writing through
+ * immediately would put a round trip behind each click; saves are therefore
+ * coalesced behind one timer, only one is ever on the wire, and the latest state
+ * always wins. The optimistic update exists because a star is a one-click
+ * affordance on the row the reader is looking at -- waiting for a round trip
+ * before it fills in makes the control feel broken when it is merely slow.
+ *
+ * Keeping this a separate hook rather than extending `useTreeState` is a
+ * consequence of the two having different payload shapes and different failure
+ * costs: a lost expansion collapses a folder, while a lost star loses the mark the
+ * reader was just told had been saved.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** What the hook exposes to the tree. */
+export interface FavoritesStore {
+    /** Relative paths of the starred rows, as the Host last answered. */
+    relPaths: readonly string[];
+    /** Whether one path is starred. */
+    has: (relPath: string) => boolean;
+    /**
+     * Star or unstar one path.
+     *
+     * Idempotent in the direction asked for, like `setPinned`: asking for the state
+     * that already holds writes nothing, so a double click cannot toggle a star back
+     * off by accident.
+     */
+    setFavorite: (relPath: string, favorite: boolean) => void;
+    /** Re-read from the Host. */
+    refresh: () => void;
+    /** Set when the last write was refused, so the surface can say why. */
+    error: string | undefined;
+}
+/**
+ * Read and write the caller's favourites.
+ * @param enabled - false while the mount point is unknown, which is the only state
+ *   where a favourites request would name a view that does not exist yet.
+ * @returns The store; `relPaths` is empty until the first read answers.
+ */
+export declare function useFavorites(enabled: boolean): FavoritesStore;

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

@@ -0,0 +1,171 @@
+/**
+ * Drag-and-drop upload: the part that can be decided without a browser.
+ *
+ * A drop needs three things settled before anything is uploaded: which directory the
+ * pointer is over, whether that directory may receive a drop, and the list of files
+ * (with their paths inside a dropped folder) that the drop carried. All three are
+ * answers about *data*, not about React state, so they live here and are tested
+ * directly instead of through a rendered tree.
+ *
+ * The module deliberately does not touch `DataTransfer`, `FileList` or `document`.
+ * The test runner has no DOM (measured: `DataTransfer`, `FileList` and `document` are
+ * all undefined, only `File` exists), and a module that reached for them could only be
+ * tested by faking the entire browser. It describes the two shapes it needs instead,
+ * and the component adapts a real event to them at the boundary. That is also what
+ * keeps the traversal order and the collision rules honest: they are pure functions of
+ * their inputs, so a test can assert them without a browser.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** A file plus the path it should occupy under the drop target. */
+export interface DroppedFile {
+    /** The browser's `File`, or anything carrying a name and a byte source. */
+    file: unknown;
+    /**
+     * Path relative to the directory the reader dropped onto.
+     *
+     * A single dropped file carries only its name. A file from a dropped folder carries
+     * the folder's segments too (`specs/2026/api.md`), which is what preserves the shape
+     * the reader saw in the file manager instead of flattening it.
+     */
+    relativePath: string;
+}
+/**
+ * What a directory row knows about itself, as far as a drop is concerned.
+ *
+ * The two flags are separate on purpose. `isDirectory` says what the row IS; `drops`
+ * says whether this surface accepts drops AT ALL right now (an upload already running,
+ * or a read-only caller). A file row is a directory the drop must ignore, while a
+ * disabled directory row is one that must also ignore it -- the reason differs but the
+ * answer does not, so `acceptsDrop()` is the single place that combines them.
+ */
+export interface DropTargetLike {
+    /** The directory an accepted drop uploads into, relative to the knowledge root. */
+    relativePath: string;
+    /** Whether the row names a folder rather than a document. */
+    isDirectory: boolean;
+    /** Whether this surface accepts drops at the moment (false while busy/read-only). */
+    drops: boolean;
+}
+/** The minimum a drop event must expose for this module to read it. */
+export interface DropEventLike {
+    /** Whether the event carries file payload; a text drag must not upload anything. */
+    hasFiles: boolean;
+    /** The pending file list, or undefined when the browser exposes none. */
+    files: readonly DroppedFile[] | undefined;
+}
+/** Why a drop produced no upload. Each case is a different thing to tell the reader. */
+export type DropRefusal = 
+/** The pointer was over a document, or outside any drop target. */
+'not-a-directory'
+/** A drop target was hit but it is not accepting drops right now. */
+ | 'disabled'
+/** The target accepted, but the drop carried no files (a text or link drag). */
+ | 'no-files';
+/** The verdict for one drop. */
+export type DropPlan = {
+    kind: 'upload';
+    directory: string;
+    files: DroppedFile[];
+} | {
+    kind: 'refuse';
+    reason: DropRefusal;
+};
+/**
+ * Whether this row may receive the drop that is being dragged over it.
+ *
+ * Used by `dragover` to decide `preventDefault` (which is what makes the browser show
+ * "copy" and allows the drop) and whether to paint the highlight. It answers `false`
+ * for a document row so a file dragged onto a file is refused rather than silently
+ * doing nothing, and `false` while the surface is busy so a second drop cannot start
+ * a competing upload.
+ * @param target - the row under the pointer, or undefined outside any row.
+ * @returns Whether the row would accept a drop.
+ */
+export declare function acceptsDrop(target: DropTargetLike | undefined): boolean;
+/**
+ * Decide what one drop should do.
+ *
+ * Kept separate from the event so the refusal cases stay distinguishable: "you dropped
+ * it on a document" and "you dragged text, not files" need different sentences, and a
+ * single `undefined` return would force the caller to guess which happened.
+ * @param target - the row under the pointer, or undefined outside any row.
+ * @param event - the drop's payload.
+ * @returns The upload to perform, or why it was refused.
+ */
+export declare function planDrop(target: DropTargetLike | undefined, event: DropEventLike): DropPlan;
+/**
+ * Normalise a path relative to the drop target.
+ *
+ * Browsers report a dropped folder's contents with either separator (the `File` API on
+ * Windows reports `\`, `webkitRelativePath` uses `/`), and a leading separator would
+ * make the joined path absolute and fail the server's containment check. Both are
+ * collapsed here so the server sees one form.
+ * @param raw - the path as the browser reported it.
+ * @returns The path with forward slashes and no leading separator.
+ */
+export declare function normalizeDropPath(raw: string): string;
+/**
+ * Join a drop target with one file's own path.
+ * @param directory - the target directory relative to the knowledge root, `''` for the root.
+ * @param relativePath - the file's path inside the drop, already normalised or not.
+ * @returns The target path relative to the knowledge root.
+ */
+export declare function dropTargetPath(directory: string, relativePath: string): string;
+/**
+ * Collapse a dropped list to one entry per destination.
+ *
+ * Dropping the same folder twice, or a folder plus one of its files, would otherwise
+ * send two writes to the same path: the first succeeds and the second is refused as
+ * "already exists", so the reader would be shown a failure for a file that is actually
+ * there. The FIRST occurrence wins because that is the one the browser enumerated
+ * first, and its bytes are the ones the reader saw at the top of the drag.
+ * @param files - the dropped files.
+ * @returns One entry per distinct destination path, in first-seen order.
+ */
+export declare function dedupeDropped(files: readonly DroppedFile[]): DroppedFile[];
+/**
+ * One line describing the outcome of a whole drop, or undefined when there is nothing
+ * worth saying (all files landed).
+ *
+ * The reader dropped N files and gets one message: naming each failure is unreadable,
+ * while "some failed" without a count is not actionable. Partial success therefore
+ * states both numbers and names the first few failures, because the next step (retry
+ * that one, rename it, ask for access) depends on WHICH file was refused.
+ * @param results - one outcome per attempted file, in order.
+ * @param maxNames - how many failing names to spell out before summarising the rest.
+ * @returns The sentence to show, or undefined when every file landed.
+ */
+export declare function summarizeDrop(results: readonly {
+    relativePath: string;
+    ok: boolean;
+}[], maxNames?: number): {
+    ok: number;
+    failed: string[];
+} | undefined;
+/**
+ * Whether a drag event carries files this surface could upload.
+ *
+ * `types` is the only part of a `DataTransfer` readable during `dragover`: the payload
+ * itself is protected until the drop, so this is what `dragover` must ask to decide
+ * whether to `preventDefault`. An internal row drag sets `text/plain` and the knowledge
+ * base's own MIME type but NOT `Files`, which is how an in-page move stays a move.
+ * @param types - `event.dataTransfer.types`.
+ * @returns Whether the drag is an external file payload.
+ */
+export declare function isFileDrag(types: readonly string[] | undefined): boolean;
+/**
+ * Read the files of a drop as the shape {@link planDrop} takes.
+ *
+ * `webkitGetAsEntry` is preferred because it is the only way a DROPPED FOLDER arrives:
+ * folders never appear in `dataTransfer.files`, so a plain file list silently drops them
+ * and the reader sees "nothing happened". The entry API must be read synchronously from
+ * the drop handler (the payload enters protected mode once the event dispatch ends), so
+ * entries are captured here first and traversed afterwards.
+ *
+ * Falls back to the flat file list when the entry API is missing or yields nothing
+ * usable, which is also the correct behaviour for a browser that only reports files.
+ * @param transfer - the drop's `dataTransfer`.
+ * @returns One entry per file, with paths relative to the drop target.
+ */
+export declare function readDroppedFiles(transfer: DataTransfer | undefined | null): Promise<DroppedFile[]>;

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

@@ -0,0 +1,64 @@
+/**
+ * The React shell around the drag-and-drop decisions.
+ *
+ * Everything that can be decided without a browser lives in `useFileDrop.ts` next to
+ * this file -- the target rules, the path joining, the de-duplication, the summary.
+ * What is left is the one thing that genuinely needs a component: which row is
+ * currently painted as the drop target.
+ *
+ * Kept in its own module for two reasons. The pure module must stay importable from a
+ * test that has no DOM (measured: the runner has `File`, but no `DataTransfer`,
+ * `FileList` or `document`), and importing React into it would make that impossible.
+ * And the component wiring is the part that has to wait for the in-flight edits to
+ * `KnowledgeFileTree.tsx` / `KnowledgeHome.tsx` to land, so it is kept separate rather
+ * than half-merged.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import type { DropEventLike, DropPlan, DropTargetLike } from './useFileDrop.ts';
+/** What a component gets back from {@link useFileDrop}. */
+export interface FileDropHandle {
+    /** The path of the row that should paint its drop highlight, or undefined. */
+    highlighted: string | undefined;
+    /**
+     * Call from a row's `onDragOver`.
+     *
+     * Returns whether the row accepts this drag, which the caller uses to decide
+     * `event.preventDefault()`: without it the browser refuses the drop outright.
+     * @param target - the row under the pointer.
+     * @returns Whether the row would accept the drop.
+     */
+    onDragOver: (target: DropTargetLike | undefined) => boolean;
+    /**
+     * Call from a row's `onDragEnter`.
+     *
+     * @param target - the row the pointer entered.
+     * @returns Whether the row would accept the drop.
+     */
+    onDragEnter: (target: DropTargetLike | undefined) => boolean;
+    /**
+     * Call from a row's `onDragLeave`, and from the surface's own `onDragLeave` for the
+     * case where the pointer left the panel entirely.
+     * @param target - the row the pointer left, if any.
+     */
+    onDragLeave: (target?: DropTargetLike | undefined) => void;
+    /**
+     * Call from a row's `onDrop`. Clears the highlight and returns what to upload.
+     * @param target - the row the pointer was over.
+     * @param event - the drop payload.
+     * @returns The upload to perform, or why nothing happens.
+     */
+    onDrop: (target: DropTargetLike | undefined, event: DropEventLike) => DropPlan;
+    /** Clear the highlight without a drop (Escape, or the drag leaving the window). */
+    reset: () => void;
+}
+/**
+ * Track the drag state for one drop surface.
+ *
+ * Note the enter/leave counter. A drag crossing from a row onto its own child fires
+ * `dragleave` on the parent BEFORE `dragenter` on the child, so clearing the highlight
+ * on every `dragleave` makes it flicker off and back on. Counting enter/leave pairs is
+ * what keeps it stable; the counter reaching zero is the real exit.
+ * @returns The handle a component wires into its rows.
+ */
+export declare function useFileDrop(): FileDropHandle;

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

@@ -0,0 +1,39 @@
+/**
+ * The pinned-path store the rail renders.
+ *
+ * Pins are a document-level preference, so they live in the caller's own view
+ * directory on the share rather than in browser storage; the Host owns that file
+ * and this hook only reads and writes it through the two routes. The optimistic
+ * update exists because toggling a pin is a one-click gesture on a menu the reader
+ * is looking at: waiting for a round trip before the row moves makes the control
+ * feel broken when it is merely slow. A failed write reloads from the Host rather
+ * than leaving the guess on screen.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** What the hook exposes to the rail. */
+export interface PinnedStore {
+    /** Pinned paths, in the order the Host returned them. */
+    relPaths: readonly string[];
+    /** Whether one path is pinned. */
+    has: (relPath: string) => boolean;
+    /**
+     * Add or remove one path.
+     *
+     * Idempotent in the direction asked for: pinning an already-pinned path leaves
+     * the list alone rather than toggling it off, so a double click cannot silently
+     * undo the first one.
+     */
+    setPinned: (relPath: string, pinned: boolean) => void;
+    /** Re-read from the Host. */
+    refresh: () => void;
+    /** Set when the last write was refused, so the surface can say why. */
+    error: string | undefined;
+}
+/**
+ * Read and write the caller's pins.
+ * @param enabled - false while the mount point is unknown, which is the only state
+ *   where a pin request would name a tree that does not exist yet.
+ * @returns The store.
+ */
+export declare function usePinnedPaths(enabled: boolean): PinnedStore;

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

@@ -0,0 +1,46 @@
+/**
+ * The set of folders the reader has open in the explorer, remembered across visits.
+ *
+ * Expansion is a document-level preference, so it lives beside `.pinned.json` and
+ * `.view-mode.json` in the caller's view directory rather than in browser storage: a
+ * reader who opens `department/platform` on one machine expects to find it open on the
+ * next, and a browser profile is not the unit a knowledge base follows.
+ *
+ * Two costs shape the implementation.
+ *
+ * The read is a Host round trip, so the tree renders collapsed first and expands once
+ * the answer lands. Rendering it collapsed is the honest initial state: it is exactly
+ * what a reader who never opened a folder sees, and the alternative -- holding the whole
+ * tree back until a preference resolves -- would trade a flicker for a blank panel.
+ *
+ * The write happens on every toggle, and a reader opening a deep path toggles once per
+ * level, so writing through immediately would put four round trips behind one gesture.
+ * Saves are therefore coalesced: the first toggle arms a timer, later toggles inside the
+ * window replace the pending payload, and the timer sends whatever the latest state is.
+ * A save still in flight when the reader keeps clicking leaves a dirty flag rather than
+ * queueing a second request, so the wire never carries more than one save at a time and
+ * the last state always wins.
+ *
+ * A failed write is not surfaced as a page error. This is a view preference whose worst
+ * outcome is a folder that comes back closed, and shouting at a reader for it would be
+ * worse than the outcome; the next successful save repairs it.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** What the hook exposes to the rail. */
+export interface TreeStateStore {
+    /** Absolute paths of the expanded folders, as the Host last answered. */
+    expanded: readonly string[];
+    /** Toggle one directory open or closed. */
+    toggle: (path: string) => void;
+    /** Set the whole set at once (a reveal, or a Host round trip). */
+    setExpanded: (paths: readonly string[]) => void;
+}
+/**
+ * Read and write the caller's expanded folders.
+ * @param enabled - false while the mount point is unknown, which is the only state
+ *   where there is no view directory holding the preference.
+ * @param root - the knowledge root, used to bound what is stored; '' while unknown.
+ * @returns The store; `expanded` is empty until the first read answers.
+ */
+export declare function useTreeState(enabled: boolean, root?: string): TreeStateStore;

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

@@ -0,0 +1,39 @@
+/**
+ * The list/grid preference the rail renders.
+ *
+ * A document-level preference stored beside the pins, for the same reason they are:
+ * a reader who switches to the grid on one machine expects it on the next. The
+ * optimistic update exists because the toggle is a one-click gesture on a control
+ * the reader is looking at, and waiting for a round trip before the layout changes
+ * makes it feel broken when it is merely slow. A failed write reloads from the Host
+ * rather than leaving the guess on screen.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/**
+ * Which layout the rail is showing.
+ *
+ * `explorer` renders the product's own file explorer (see `KnowledgeFileTree`), which is
+ * the tree a reader already knows from the workspace sidebar. It is a third option rather
+ * than a replacement because the two layouts answer different questions: the listing shows
+ * knowledge-base state the explorer has no concept of (whether a row is readable, its
+ * pinned mark, multi-select for a batch grant), while the explorer brings the affordances a
+ * file tree is expected to have (sort, inline rename, drag-and-drop, upload strip).
+ */
+export type ViewMode = 'list' | 'grid' | 'explorer';
+/** What the hook exposes to the rail. */
+export interface ViewModeStore {
+    /** The stored layout. */
+    mode: ViewMode;
+    /** Switch layouts, writing through to the Host. */
+    setMode: (mode: ViewMode) => void;
+    /** Set when the last write was refused, so the surface can say why. */
+    error: string | undefined;
+}
+/**
+ * Read and write the caller's layout preference.
+ * @param enabled - false while the mount point is unknown, which is the only state
+ *   where there is no view directory to hold the preference.
+ * @returns The store.
+ */
+export declare function useViewMode(enabled: boolean): ViewModeStore;