@sidequest-007/dsh-atlas 1.0.0

package/lib/invariant.js

@@ -0,0 +1,13 @@
+// src/invariant.ts
+var PACKAGE_NAME = "@sidequest-007/dsh-atlas";
+var name = "dsh-atlas-invariant";
+var inject = ["invariants"];
+var install = () => {
+};
+var apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+export {
+  apply,
+  inject,
+  name
+};
+//# sourceMappingURL=invariant.js.map

package/lib/types/abort.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cancellation versus failure, stated once.
+ *
+ * The plugin cancels its own work all the time: the browser aborts a superseded
+ * menu search on every keystroke, and the Host aborts the expansions of a turn
+ * the user stopped. Those cancellations surface as ordinary catchable errors
+ * (`gateway/cancelled`, `AbortError`), and reporting them as failures is noise
+ * that hides the real ones — so every containment site asks this first.
+ */
+/**
+ * Whether a caught error is the cancellation of the plugin's own request.
+ *
+ * The caller's own signal is the authority: when the request the plugin handed
+ * down was aborted, whatever came back is that abort. An `AbortError` name is
+ * honoured too, because a layer may re-throw the reason detached from the
+ * signal. Message text is deliberately NOT sniffed — a real failure whose text
+ * happens to say "cancelled" must still be reported.
+ * @param error - the caught value.
+ * @param signal - the signal the plugin handed down, when it has one.
+ * @returns true when this is the plugin's own cancellation.
+ */
+export declare function isCancellation(error: unknown, signal?: AbortSignal): boolean;

package/lib/types/atlas.d.ts

@@ -0,0 +1,181 @@
+/**
+ * The `@` data-source seam — one contract, validated per half.
+ *
+ * ATLAS defines the capability (this file), third-party plugins provide it, and
+ * the `@` menu is the single consumer, the same three-layer split the official
+ * `dsh-shell` seam uses. A provider hands over a declaration plus its callbacks;
+ * it never hands over its data, and this registry never reaches for anything the
+ * provider did not explicitly declare.
+ *
+ * The seam has two halves because DSH plugins do: the browser half answers
+ * `list` while the menu is open, and the Host half answers `resolve` when a
+ * committed reference is turned into model-visible text. A plugin may register
+ * either half; `id` ties them together. Registration IS the authorization — a
+ * plugin that never registers is invisible here.
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+/** One selectable row a provider offers to the menu. */
+export interface AtlasItem {
+    /** Provider-owned id, handed back to `resolve` verbatim; token-safe. */
+    readonly id: string;
+    /** Menu title. */
+    readonly title: string;
+    /** One-line preview shown in the list only; never injected on its own. */
+    readonly preview?: string;
+    /** Compact right-hand badge (severity, count, status). */
+    readonly badge?: string;
+}
+/** What a provider learns about the call it is answering. */
+export interface AtlasCallContext {
+    readonly sessionId: SessionId;
+    /**
+     * The answered session's workspace directory, when the Host knows it. A
+     * provider that reaches outside the conversation (the built-in `@git` source
+     * runs Git there) must not guess it.
+     */
+    readonly cwd?: string;
+    /** Superseded when the query changes or the menu closes. */
+    readonly signal: AbortSignal;
+}
+/**
+ * One registered data source.
+ *
+ * `list` runs while the menu is open and must stay cheap; `resolve` runs once,
+ * after the user commits, and may be expensive. `scopes` and `testedOn` are the
+ * governance layer the framework does not provide: what the provider will reach
+ * for, and which DSH versions it has actually been proven on.
+ */
+/**
+ * What a provider's `open` may report back.
+ *
+ * `'gone'` says the item's target no longer exists — the menu then draws the
+ * mention's chip as stale rather than as a link, which is the honest answer to a
+ * click that could not open anything. `'opened'`, or no return value at all,
+ * means the click did its thing.
+ */
+export type AtlasOpenOutcome = 'opened' | 'gone';
+export interface AtlasProvider {
+    /** The `@<id>` handle; unique across providers. */
+    readonly id: string;
+    readonly display: string;
+    /** Browser half: candidates for the open menu. Required when registering a `list` half. */
+    list?(query: string, ctx: AtlasCallContext): Promise<readonly AtlasItem[]>;
+    /**
+     * Browser half: open ONE of this provider's items for the user — the click
+     * action of a committed `@atlas:<id>/<item>` mention in an already sent
+     * message. Optional, and deliberately the provider's own business: an item id
+     * means whatever the provider says it means, so the menu never interprets one
+     * (a `@git` item happens to be a workspace path, a `@docs` item would be a
+     * URL). A provider without this callback contributes an inert chip that is
+     * never drawn as clickable.
+     *
+     * Returning `'gone'` is how a provider tells the menu its item no longer
+     * exists, so the chip can be drawn stale instead of as a live link. Anything
+     * else (including the usual `void`) means the click did its thing.
+     */
+    open?(item: string, ctx: AtlasCallContext): AtlasOpenOutcome | void | Promise<AtlasOpenOutcome | void>;
+    /** Host half: the model-visible text for one committed item. */
+    resolve?(item: AtlasItem, ctx: AtlasCallContext): Promise<string>;
+    /** What this provider reaches for; `[]` means it reaches nothing external. */
+    readonly scopes: readonly string[];
+    /** DSH versions this provider was verified against. */
+    readonly testedOn: readonly string[];
+}
+/** One accepted provider, with the registry's own verdict attached. */
+export interface AtlasRegistration {
+    readonly id: string;
+    readonly display: string;
+    readonly scopes: readonly string[];
+    readonly testedOn: readonly string[];
+    /**
+     * Whether the running DSH version appears in `testedOn`. False also when the
+     * runtime version is unknown: an unproven claim must never read as proven.
+     */
+    readonly verified: boolean;
+    readonly provider: AtlasProvider;
+}
+/** The running Harness facts the registry needs for its version gate. */
+export interface AtlasRuntimeInfo {
+    /** The DSH version of this session, when the Host could report it. */
+    readonly dshVersion?: string;
+}
+/** Which half a registry instance accepts. */
+export interface AtlasHalf {
+    /** Require and keep `list` (the browser/menu half). */
+    readonly list: boolean;
+    /**
+     * Keep the optional `open` callback (the browser/menu half only). Optional so
+     * an existing registry keeps its meaning: absent means a declaration carrying
+     * `open` is refused rather than silently never called.
+     */
+    readonly open?: boolean;
+    /** Require and keep `resolve` (the Host/injection half). */
+    readonly resolve: boolean;
+}
+/**
+ * The handle the seam publishes as `ctx.get('atlas')`.
+ *
+ * Both halves publish this same shape, so a provider author writes one
+ * declaration either way — which callbacks it must carry depends on the half it
+ * is registering into, and the registry says so by throwing.
+ */
+export interface AtlasSeam {
+    /**
+     * Accept one provider declaration for the half this handle belongs to.
+     * @param candidate - the declaration.
+     * @returns the disposer that withdraws it.
+     */
+    register(candidate: unknown): () => void;
+}
+/**
+ * Validate one candidate declaration, naming the first field that fails.
+ * @param candidate - the value handed to `register`.
+ * @param half - which callbacks this registry requires.
+ * @returns the same value typed as a provider.
+ */
+export declare function validateAtlasDeclaration(candidate: unknown, half: AtlasHalf): AtlasProvider;
+/**
+ * Validate one item a provider returned.
+ * @param item - the value from `list`.
+ * @returns the same value typed as an item.
+ */
+export declare function validateAtlasItem(item: unknown): AtlasItem;
+/**
+ * The `@` seam's registry: accepts declarations for one half, enforces the
+ * governance rules, and hands the accepted providers to that half's consumer.
+ */
+export declare class AtlasRegistry {
+    private readonly registrations;
+    private readonly readRuntime;
+    private readonly half;
+    /**
+     * @param readRuntime - the running Harness facts used by the version gate;
+     *   accepted as a thunk (read at verdict time) or as a plain record.
+     * @param half - which callbacks this instance requires (defaults to both).
+     */
+    constructor(readRuntime?: (() => AtlasRuntimeInfo) | AtlasRuntimeInfo, half?: AtlasHalf);
+    /**
+     * Accept one provider declaration.
+     * @param candidate - the declaration handed over by a plugin.
+     * @returns the disposer that withdraws it.
+     */
+    register(candidate: unknown): () => void;
+    /** Every accepted provider, in registration order. */
+    entries(): readonly AtlasRegistration[];
+    /**
+     * One accepted provider by handle.
+     * @param id - the provider handle.
+     * @returns the registration, or undefined when nothing claimed it.
+     */
+    get(id: string): AtlasRegistration | undefined;
+    /**
+     * Re-read the version verdict for one stored registration.
+     *
+     * The verdict is deliberately not a snapshot: the browser learns the running
+     * version asynchronously and a plugin may register before it lands, so a
+     * registration made a moment too early must not stay unverified forever.
+     * @param entry - the stored registration.
+     * @returns the same registration with the current verdict.
+     */
+    private judge;
+}

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

@@ -0,0 +1,21 @@
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ReferenceInfoSource } from './FilesDock.tsx';
+import type { ReferenceLink } from './reference-links.ts';
+import type { ReferenceOutcome } from './ReferenceLinks.tsx';
+/** What the session's overlay shares with the draft bridge. */
+export interface DraftLinksInjected {
+    /** The action a click on this mention performs, or undefined when this build has none. */
+    readonly actionFor: (link: ReferenceLink) => (() => ReferenceOutcome | Promise<ReferenceOutcome>) | undefined;
+    /** The dock's own inspection verdicts: the bridge never re-asks for the same path. */
+    readonly hooks: {
+        readonly referenceInfo: ReferenceInfoSource;
+    };
+}
+/** Overlay entry props: the composer runtime face plus the opener and the verdicts. */
+export type DraftLinksProps = PropsRuntime<'conversation.input.overlay'> & InjectFace<DraftLinksInjected>;
+/**
+ * Invisible bridge: opens the reference token a composer click lands in.
+ * @param props - the injected opener and the dock's verdict source.
+ * @returns nothing; this entry renders no DOM of its own.
+ */
+export declare function DraftLinks({ actionFor, useReferenceInfo }: DraftLinksProps): null;

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

@@ -0,0 +1,75 @@
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { AtFileSettings, ReferenceInfo } from '../contract.ts';
+import type { ReferenceLink } from './reference-links.ts';
+import type { MentionKind } from './source.ts';
+export interface AtFileSettingsSnapshot {
+    readonly value: AtFileSettings;
+}
+export type AtFileSettingsSource = ObservableSnapshot<AtFileSettingsSnapshot>;
+/** Snapshot of the host-inspected reference facts (existence, kind, size). */
+export interface ReferenceInfoSnapshot {
+    readonly value: readonly ReferenceInfo[];
+}
+export type ReferenceInfoSource = ObservableSnapshot<ReferenceInfoSnapshot>;
+/** Injected business face: open one mention, inspect the draft's references, and the live sources. */
+export interface AtFileDockInjected {
+    /**
+     * Open one mention of the draft (the same action a click on the sent-message
+     * chip performs, so both surfaces behave alike).
+     */
+    onOpen: (link: ReferenceLink) => void;
+    /** Ask the Host for existence, kind, and size of the draft's path references. */
+    requestInspect: (targets: readonly string[]) => void;
+    hooks: {
+        scope: AtFileSettingsSource;
+        referenceInfo: ReferenceInfoSource;
+    };
+}
+/** Approximate bytes per token for text files (the dock's cost hint). */
+export declare const BYTES_PER_TOKEN = 4;
+/** References heavier than this many tokens are flagged in the dock. */
+export declare const COST_WARN_TOKENS = 8000;
+/**
+ * Approximate context cost of one reference, or undefined when there is nothing
+ * to price (missing path, directory, or a file whose size is unknown).
+ * @param info - the host-inspected facts for this reference, when available.
+ * @returns the token estimate and whether it exceeds the warning threshold.
+ */
+export declare function referenceCost(info: ReferenceInfo | undefined): {
+    readonly tokens: number;
+    readonly warn: boolean;
+} | undefined;
+/**
+ * Compact token count for the dock badge (`820`, `1.2k`).
+ * @param tokens - the estimated token count.
+ * @returns the badge text.
+ */
+export declare function formatTokenCount(tokens: number): string;
+/** Full dock entry props: InputZone owner share + session standard kit + injected face + locale seat. */
+export type AtFileDockProps = PropsRuntime<'conversation.input.dock'> & InjectFace<AtFileDockInjected> & PropsLocale<'atlas'>;
+/** One parsed mention token in the draft, with its span for precise removal. */
+export interface DraftMention {
+    readonly kind: Exclude<MentionKind, 'category' | 'back'>;
+    /** Stable removal key (the token start index). */
+    readonly key: number;
+    /** Display label. */
+    readonly label: string;
+    /** Workspace-relative path for file/dir rows (inspection and open action). */
+    readonly relative?: string;
+    /** The click action's target, for rows this build can open. */
+    readonly link?: ReferenceLink;
+    readonly start: number;
+    readonly end: number;
+}
+/** Parse the draft's mention tokens in order, deduplicating by kind + span. */
+export declare function draftMentions(draft: string): readonly DraftMention[];
+/** Draft text with one token span removed. */
+export declare function withoutToken(draft: string, start: number, end: number): string;
+/**
+ * Render the referenced-item rows; null while the draft has no mention tokens
+ * or the settings switch is off.
+ * @param props - runtime (input currency + actions), inject, and locale shares.
+ * @returns the dock strip, or null.
+ */
+export declare function FilesDock({ input, inputActions, onOpen, requestInspect, useScope, useReferenceInfo, t }: AtFileDockProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,66 @@
+/**
+ * The folder chooser dialog: a modal picker over the product's own browse
+ * backend.
+ *
+ * Why not the product's dialog itself: `BrowseDirectoryFlow` is not a service, it
+ * is a component filling the workspace picker's PRIVATE child slots
+ * (`conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`),
+ * and rendering a slot belongs to the entry that declared it — a plugin can
+ * neither declare the same hole nor render someone else's. And
+ * `directoryPicker/pick` is the NATIVE chooser, which a profile serving the
+ * in-app browse capability refuses (`directory-picker/unavailable`).
+ *
+ * What CAN be borrowed is the backend both of those use:
+ * `ctx.uiWorkspace.listDirectory` / `createDirectory` (the `directoryPicker`
+ * namespace's browse verbs). This dialog is that backend with our own face: the
+ * path line is editable, a row with a chevron walks into that folder, and 打开
+ * confirms the folder the path line is showing.
+ */
+import { type ReactNode } from 'react';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/** One row of a browse level, as the product's picker backend reports it. */
+export interface PickerEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly hidden: boolean;
+}
+/** One browse level: the folder itself, its ancestry, and its child folders. */
+export interface PickerListing {
+    readonly path: string;
+    readonly home: string;
+    readonly crumbs: readonly PickerEntry[];
+    readonly entries: readonly PickerEntry[];
+    readonly truncated: boolean;
+}
+/** The open/closed share between the source's picker row and this dialog. */
+export interface FolderPickerSnapshot {
+    /** Set while the dialog is open; the token the pick will replace travels with it. */
+    readonly value: unknown | null;
+}
+/** Read-only observable face the dialog subscribes to. */
+export interface FolderPickerSource {
+    getSnapshot(): FolderPickerSnapshot;
+    subscribe(listener: () => void): () => void;
+}
+/** What the session's shell shares with the dialog. */
+export interface FolderPickerInjected {
+    /** One directory level from the product's picker backend; undefined starts at home. */
+    readonly list: (path: string | undefined, signal: AbortSignal) => Promise<PickerListing>;
+    /** Create one child folder and answer its absolute path. */
+    readonly create: (path: string, name: string) => Promise<string>;
+    /** Adopt the folder the path line shows (inserts the reference and closes). */
+    readonly confirm: (path: string) => void;
+    /** Dismiss without adopting anything. */
+    readonly close: () => void;
+    readonly hooks: {
+        readonly folderPicker: FolderPickerSource;
+    };
+}
+/** The dialog's props: the overlay seat, this plugin's copy, and the shell's face. */
+export type FolderPickerProps = PropsRuntime<'conversation.input.overlay'> & PropsLocale<'atlas'> & InjectFace<FolderPickerInjected>;
+/**
+ * Render the folder chooser while one is requested.
+ * @param props - the open state, the browse backend, and the adoption callbacks.
+ * @returns the modal, or null while closed.
+ */
+export declare function FolderPicker({ useFolderPicker, list, create, confirm, close, t }: FolderPickerProps): ReactNode;

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

@@ -0,0 +1,50 @@
+/**
+ * The folder tab: one directory, one level, in the right Sidebar.
+ *
+ * Why a type of this plugin's own: a `dsh-resource://file/…` address is claimed
+ * by the file viewers, and a directory makes them answer `"…" is a directory`;
+ * the built-in `files` tab is a page (a tree rooted at the session workspace)
+ * that claims no address at all. So a folder click has nowhere to go in the
+ * shipped product, and this tab is that destination — for a workspace folder and
+ * for an out-of-workspace one alike, because the Host gates the listing with the
+ * same rule it uses for a reference.
+ *
+ * The body walks on its own: a directory row descends in this tab, a file row
+ * opens the file's own viewer, and the header carries the way back up plus the
+ * OS opener. Nothing here reads a file — `atFile/list` returns names and kinds.
+ */
+import { type ReactNode } from 'react';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SidebarRightTabDefinition } from '@deepseek-ai/dsh-client-ui-sidebar-right/client';
+import type { DirectoryListing } from '../contract.ts';
+import type { AtFileKey } from './locales.ts';
+import { childOf } from './model.ts';
+/** This type's identity in the tab registry, and the key its body registers under. */
+export declare const FOLDER_TAB_ID = "dsh-atlas/folder";
+/** The tab kind this plugin owns. */
+export declare const FOLDER_TAB_KIND = "atlas-folder";
+/**
+ * The folder tab's registry definition: it claims every address of our own
+ * `folder` resource type, so nothing else can be asked to open one.
+ * @param t - namespace-bound translate for the chip title.
+ * @returns the definition to register.
+ */
+export declare function folderTabDefinition(t: (key: AtFileKey, params?: Record<string, string>) => string): SidebarRightTabDefinition;
+/** What the session's shell shares with the folder tab. */
+export interface FolderTabInjected {
+    /** List one directory (one level); `''` means the session workspace root. */
+    readonly list: (path: string, signal: AbortSignal) => Promise<DirectoryListing>;
+    /** Open a file the way every other reference does. */
+    readonly openFile: (path: string) => void;
+    /** Hand a path to the OS file manager. */
+    readonly openNative: (path: string) => void;
+}
+/** The folder tab's props: the tab seat, the copy seat, and the shell's face. */
+export type FolderTabProps = PropsRuntime<'sidebar.right.pane.tab'> & PropsLocale<'atlas'> & InjectFace<FolderTabInjected>;
+export { childOf };
+/**
+ * Render one directory's contents.
+ * @param props - the tab's live info, the Host listing call, and the openers.
+ * @returns the folder's rows, or the reason it could not be listed.
+ */
+export declare function FolderTab({ useTabInfo, list, openFile, openNative, t }: FolderTabProps): ReactNode;

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

@@ -0,0 +1,96 @@
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { InputTriggerCandidate, MenuState, TriggerGuard } from '@deepseek-ai/dsh-client-ui-input-trigger/client';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { AtFileSettingsSource } from './FilesDock.tsx';
+/** Controller surface required by the completion bridge. */
+export interface MentionNavigationController {
+    readonly menu: SnapshotStore<MenuState>;
+    track(draft: string, caret: number, guard: TriggerGuard, draftRev: number): void;
+    /** Close the menu without a pick (used to force a refresh). */
+    dismiss(): void;
+}
+/** Injected controller for the current session. */
+export interface MentionNavigatorInjected {
+    readonly controller: MentionNavigationController;
+    readonly hooks: {
+        scope: AtFileSettingsSource;
+    };
+    readonly sessionId: string;
+    /** Toggle one group header's collapse state (chat:/skill: keys). */
+    readonly toggleGroup: (key: string) => void;
+    /** Synchronously rebuild rows for a category query from settled caches. */
+    readonly rebuildRows: (sessionId: string, query: string) => readonly InputTriggerCandidate[] | undefined;
+    /**
+     * A message was submitted. The Host records referenced external paths in its
+     * ledger during the send, so any cached out-of-workspace scope is now suspect.
+     */
+    readonly onSend?: () => void;
+}
+/** Overlay entry props: session input state/actions plus the trigger controller. */
+export type MentionNavigatorProps = PropsRuntime<'conversation.input.overlay'> & InjectFace<MentionNavigatorInjected>;
+/** Input facts needed to validate a menu-time completion. */
+export interface MentionNavigationInput {
+    readonly draft: string;
+    readonly draftRev: number;
+    readonly phase: 'plain' | 'adjudicating' | 'claimed' | 'submitting';
+}
+/** The group row currently highlighted in the @ menu, if any. */
+export declare function highlightedGroup(menu: MenuState): {
+    key: string;
+    index: number;
+} | undefined;
+/** The group row at a menu index, or undefined. */
+export declare function groupAt(menu: MenuState, index: number): {
+    key: string;
+} | undefined;
+/** Whether the row at index is the back-to-categories row. */
+export declare function backRowAt(menu: MenuState, index: number): boolean;
+/** The category row at index (its draft prefix), or undefined. */
+export declare function categoryRowAt(menu: MenuState, index: number): {
+    prefix: string;
+} | undefined;
+/** Whether a menu item is a section header (category/back/group) rather than a result leaf. */
+export declare function isHeaderRow(item: {
+    mentionKind?: string;
+} | undefined): boolean;
+/**
+ * The index of the first result leaf in the atlas group (skipping every
+ * section header), or -1 when the menu has no result rows yet.
+ */
+export declare function firstLeafIndex(menu: MenuState): number;
+/**
+ * The row a freshly settled query's default highlight belongs on.
+ *
+ * A query that uniquely names a category — a shortcut letter (F/D/S/C/P) or an
+ * English prefix (fi/fo/sk/ch/pl) — is an explicit "I want this category"
+ * intent, so the highlight goes to that category's own row: the gray hint row
+ * the source pins on top, whose pick enters `@<category>:`. Landing on the
+ * first result leaf instead would make Enter insert whichever most-used entry
+ * happens to contain the typed letter, which is the opposite of what typing a
+ * category shortcut asks for. Every other query keeps the best-match behavior
+ * and lands on the first result leaf.
+ * @param menu - the live menu state.
+ * @returns the row index, or -1 when no row qualifies yet.
+ */
+export declare function defaultHighlightIndex(menu: MenuState): number;
+/**
+ * Rows one PageUp/PageDown covers when the list cannot be measured.
+ *
+ * jsdom implements no layout, and a browser can be asked before the list has one:
+ * a fixed page is better than a division by zero, and eight rows is what the menu
+ * shows at its usual height anyway.
+ */
+export declare const PAGE_ROWS = 8;
+/**
+ * How many rows one page covers in the open menu.
+ *
+ * Measured from the live list rather than assumed, so a taller window pages
+ * further and a short one does not jump past what the user can see.
+ * @param box - the menu's scrolling listbox, or null when it is not rendered.
+ * @returns the row count of one page (at least one).
+ */
+export declare function pageStep(box: Element | null): number;
+/** Whether this is a plain Enter: no IME ownership, no modifier, not already handled. */
+export declare function isPlainEnter(event: Pick<KeyboardEvent, 'key' | 'keyCode' | 'defaultPrevented' | 'isComposing' | 'altKey' | 'ctrlKey' | 'metaKey' | 'shiftKey'>): boolean;
+/** Invisible overlay entry: folds group headers and keeps category rows in the menu. */
+export declare function MentionNavigator({ controller, useInput, inputActions, toggleGroup, sessionId, rebuildRows, onSend }: MentionNavigatorProps): null;

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

@@ -0,0 +1,16 @@
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { MenuState } from '@deepseek-ai/dsh-client-ui-input-trigger/client';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+/** The attribute this overlay sets on an icon slot it covers. */
+export declare const HOST_ATTRIBUTE = "data-dsh-atlas-menu-icon-host";
+/** What the session's overlay shares with the menu layer. */
+export interface MenuIconsInjected {
+    /** The trigger controller's menu store: the rows, their order, and the open state. */
+    readonly hooks: {
+        readonly menu: SnapshotStore<MenuState>;
+    };
+}
+/** Overlay entry props: the composer runtime face plus the menu store. */
+export type MenuIconsProps = PropsRuntime<'conversation.input.overlay'> & InjectFace<MenuIconsInjected>;
+/** The glyph layer. */
+export declare function MenuIcons({ useMenu }: MenuIconsProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,85 @@
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import { type ReferenceLink } from './reference-links.ts';
+/** The attribute this bridge sets on a chip it can open (hover affordance hook). */
+export declare const LINK_ATTRIBUTE = "data-dsh-atlas-link";
+/** The attribute this bridge sets on a chip whose target is gone (stale styling hook). */
+export declare const MISSING_ATTRIBUTE = "data-dsh-atlas-missing";
+/** What a click on one reference did, as far as the chip is concerned. */
+export type ReferenceOutcome = 'opened' | 'gone';
+/** What the session's overlay shares with the bridge. */
+export interface ReferenceLinksInjected {
+    /**
+     * The action a click on this mention performs, or undefined when this build
+     * has none (an unknown provider, a provider that declared no `open`, a
+     * session with no client scope). The same answer drives the hover affordance,
+     * so a chip is never drawn as clickable unless clicking really does something.
+     *
+     * The outcome is what the chip has to show: a reference whose target no longer
+     * exists is a normal state — the user deleted or renamed the file long after
+     * the mention was sent — so the bridge marks that chip stale instead of
+     * pretending the click opened something.
+     */
+    readonly actionFor: (link: ReferenceLink) => (() => ReferenceOutcome | Promise<ReferenceOutcome>) | undefined;
+    /**
+     * Map one composer chip's label to a workspace-relative path.
+     *
+     * A source that inserts chips may label them with a bare file name (the
+     * sidebar plugin does: the chip shows `@index.ts` while it serializes to
+     * `@src/client/index.ts`), so a bare name is resolved through the plugin's own
+     * index before the click. `undefined` means the label alone cannot name one
+     * file (two indexed paths answer to it), and the bridge then falls back to the
+     * draft — never to a guess.
+     */
+    readonly resolveLabel: (label: string) => string | undefined;
+}
+/** Overlay entry props: the chat overlay's runtime face plus the opener. */
+export type ReferenceLinksProps = PropsRuntime<'conversation.input.overlay'> & InjectFace<ReferenceLinksInjected>;
+/**
+ * The openable mention of one chip element, or undefined.
+ *
+ * A `<button>` chip means the framework passed its reference actions and wires
+ * the click itself; acting as well would open the resource twice. A chip of any
+ * other kind (session, folder, skill-slash, command) is not ours to open.
+ * @param chip - the chip element.
+ * @returns the decoded action, or undefined when the bridge must not act.
+ */
+export declare function chipLink(chip: Element): ReferenceLink | undefined;
+/** The visual body of a composer chip inside its host element. */
+export declare function composerChipBody(host: Element): Element;
+/**
+ * The openable mention of one composer chip, or undefined.
+ *
+ * The label is the chip body's `title` (the framework renders the visible `@` as
+ * a separate marker span, and uses a domain icon instead for some sources), with
+ * the host's own text as the fallback. A label that is not a mention of ours — a
+ * slash chip (`/skill`), an empty label, a provider handle — stays inert, exactly
+ * as an inert sent chip does.
+ *
+ * Unlike a draft TOKEN, this is not checked against the Host first: the label is
+ * another source's display text, not necessarily a workspace spelling the dock
+ * inspected. `dsh-better-sidebar`, which inserts these chips, labels a chip with
+ * the file's BASENAME while its serialization keeps the full relative path, so
+ * the caller resolves a bare name through the plugin's own index before the
+ * click, and the click itself discovers a vanished target the way a sent chip
+ * does — the action reports `gone` and the chip is marked stale.
+ * @param host - one `[data-composer-chip]` host element.
+ * @param resolve - maps one chip label to a workspace-relative path.
+ * @returns the decoded mention, or undefined when the bridge must not act.
+ */
+export declare function composerChipLink(host: Element, resolve?: (label: string) => string | undefined): ReferenceLink | undefined;
+/**
+ * The one draft token a bare chip label names, or undefined.
+ *
+ * A chip's full reference lives in its Lexical node, not in the DOM — but the
+ * DRAFT keeps exactly what that source serializes (the whole mention), so a
+ * label the index could not place is still recoverable when the draft holds
+ * precisely one token with that basename. Two candidates mean the label cannot
+ * say which one is meant, and the answer is then undefined: an inert chip beats
+ * opening the wrong file.
+ * @param draft - the composer's draft text.
+ * @param label - the chip's visible label.
+ * @returns the workspace-relative path the draft spells, or undefined.
+ */
+export declare function draftPathForLabel(draft: string, label: string): string | undefined;
+/** Invisible bridge: opens the reference chips the product renders on click. */
+export declare function ReferenceLinks({ actionFor, resolveLabel, useInput }: ReferenceLinksProps): null;