@sidequest-007/dsh-atlas 1.0.9 → 1.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,266 @@
1
+ /**
2
+ * The session's Chat selector hook, structurally typed.
3
+ *
4
+ * `@deepseek-ai/dsh-client-ui-chat` is NOT one of this plugin's dependencies:
5
+ * the hook is a standard prop the renderer injects into every session-scoped
6
+ * slot, and adding a package dependency just to name its type would be
7
+ * backwards. Only the two selections the history feature performs are declared —
8
+ * which is also the honest contract, since everything else in the snapshot
9
+ * belongs to the ui-chat package.
10
+ */
11
+ export interface HistoryChatSelection {
12
+ /** The conversation's node keys, in render order. */
13
+ readonly order: readonly string[];
14
+ /** Node lookup; the shape read from each node is `history-frames.ts`'s concern. */
15
+ readonly nodes: {
16
+ get(key: string): unknown;
17
+ };
18
+ /**
19
+ * The streaming assistant step, or null when no step is currently streaming.
20
+ *
21
+ * NOT the "is a turn running" signal. A step that was aborted mid-flight keeps
22
+ * `status: 'running'` in this projection, so `partial` stays non-null on a
23
+ * settled session and the composer shows no Stop — measured on a fixture whose
24
+ * turn ends with `turn/end`, reason `aborted`. The shell's own answer is
25
+ * `useSession(s => s.running)`, which is what the gate below reads.
26
+ */
27
+ readonly partial: unknown | null;
28
+ }
29
+ /** The session's standard Chat selector hook. */
30
+ export interface HistoryChatHook {
31
+ <Selection>(selector: (snapshot: HistoryChatSelection) => Selection): Selection;
32
+ }
33
+ /** The subset of the session snapshot this feature reads. */
34
+ export interface HistorySessionSelection {
35
+ /** Whether a turn is currently in flight. */
36
+ readonly running?: boolean;
37
+ }
38
+ /** The session's standard selector hook. */
39
+ export interface HistorySessionHook {
40
+ <Selection>(selector: (snapshot: HistorySessionSelection) => Selection): Selection;
41
+ }
42
+ /**
43
+ * The standard props the history feature consumes beyond the input face.
44
+ *
45
+ * Declared as an interface rather than inline so the overlay props can intersect
46
+ * it, and so the inability to name the ui-chat package stays visible in one
47
+ * place instead of leaking into every signature.
48
+ */
49
+ export interface HistoryStandardProps {
50
+ /** The session's Chat snapshot hook, injected by the shell. */
51
+ readonly useChat: HistoryChatHook;
52
+ /**
53
+ * The session snapshot hook, whose `running` flag is the shell's own
54
+ * "a turn is in flight" answer (the same one that decides whether the
55
+ * composer offers Stop).
56
+ */
57
+ readonly useSession: HistorySessionHook;
58
+ }
59
+ /**
60
+ * Declare `useChat` on the session standard kit.
61
+ *
62
+ * `SessionStandardProps` is declared EMPTY on purpose — its own doc says each
63
+ * owning UI adapter merges the hooks it contributes — so ui-chat's chat hook is
64
+ * already merged into the props at runtime, while this program cannot see it
65
+ * without depending on that package. Augmenting the interface here is that
66
+ * documented mechanism used from the consumer side, and it is what makes the
67
+ * overlay's real props type-check instead of needing a cast.
68
+ */
69
+ declare module '@deepseek-ai/dsh-client-ui-slots' {
70
+ interface SessionStandardProps {
71
+ /** The session's Chat snapshot selector hook (contributed by ui-chat). */
72
+ readonly useChat: HistoryChatHook;
73
+ /**
74
+ * The session snapshot selector hook, whose `running` flag is the shell's
75
+ * own "a turn is in flight" answer (contributed by ui-session).
76
+ *
77
+ * Declared here for the same reason as `useChat`: the overlay's declared
78
+ * standard kit carries the hook at runtime, while this program cannot see
79
+ * the package that merges it, and the history walk needs the flag to tell
80
+ * a settled frame from one whose turn is still streaming.
81
+ */
82
+ readonly useSession: HistorySessionHook;
83
+ }
84
+ }
85
+ /** The cursor's phase: the composer at rest, roaming, or the palette open. */
86
+ export type HistoryPhase = 'idle' | 'roaming' | 'palette';
87
+ /** One resolved intent for a key event. */
88
+ export type HistoryIntent =
89
+ /** Enter the roaming selection state. */
90
+ {
91
+ readonly kind: 'enter';
92
+ }
93
+ /**
94
+ * Step the cursor one frame earlier/later.
95
+ *
96
+ * `quick` is the difference between the two features the user keeps separate:
97
+ * a bare arrow (`quick: false`) MOVES the roaming cursor so the user can look
98
+ * at a message, while the Ctrl/Cmd chord (`quick: true`) also carries the
99
+ * frame's text back into the composer so the user can reuse it. Both work in
100
+ * both phases, and this flag — not the phase — is what decides which of the
101
+ * two frame sets the step runs over (see A-19).
102
+ */
103
+ | {
104
+ readonly kind: 'step';
105
+ readonly direction: -1 | 1;
106
+ readonly page: boolean;
107
+ readonly quick: boolean;
108
+ }
109
+ /** Jump to the oldest frame or back to the draft. */
110
+ | {
111
+ readonly kind: 'edge';
112
+ readonly to: 'oldest' | 'draft';
113
+ }
114
+ /** Reuse the highlighted frame (or, on the draft slot, do nothing). */
115
+ | {
116
+ readonly kind: 'reuse';
117
+ }
118
+ /** Leave the roaming state, returning focus to the composer. */
119
+ | {
120
+ readonly kind: 'leave';
121
+ readonly consume: boolean;
122
+ }
123
+ /** Toggle the palette. */
124
+ | {
125
+ readonly kind: 'palette';
126
+ };
127
+ /** The facts about one key event this module needs. */
128
+ export interface KeyFacts {
129
+ readonly key: string;
130
+ readonly ctrlKey: boolean;
131
+ readonly metaKey: boolean;
132
+ readonly shiftKey: boolean;
133
+ readonly altKey: boolean;
134
+ /** Whether the event is currently composing (IME). */
135
+ readonly isComposing: boolean;
136
+ }
137
+ /** The environment facts that decide whether a gesture may run at all. */
138
+ export interface HistoryEnvironment {
139
+ /** The feature's enable switch. */
140
+ readonly enabled: boolean;
141
+ /** Whether the `@` menu is open (it owns the arrow keys then). */
142
+ readonly menuOpen: boolean;
143
+ /** Whether a modal dialog is open (it owns Escape then). */
144
+ readonly modalOpen: boolean;
145
+ /** Whether the current turn is still generating. */
146
+ readonly generating?: boolean;
147
+ /** Whether the event target is inside a text field this plugin does not own. */
148
+ readonly foreignEditor: boolean;
149
+ }
150
+ /**
151
+ * Whether a modifier state carries the palette chord: the command key, with or
152
+ * without Shift.
153
+ *
154
+ * Two documents in this repo disagree about the spelling — `docs/history-jump.md`
155
+ * §2 picks `Ctrl/Cmd+Shift+H` for being free of the browser and platform
156
+ * collisions that bare `Ctrl+H` (Chrome/Edge History) and `Cmd+H` (macOS "hide
157
+ * app") have, while the code shipped answering only the unshifted form. Both
158
+ * spellings now open the same panel, so neither document lies and the safer
159
+ * chord the design argued for actually works. `Alt` stays excluded: on Windows
160
+ * `AltGr` *is* `Ctrl+Alt`, so accepting it would fire while a user types a
161
+ * character.
162
+ * @param facts - the key event facts.
163
+ * @returns whether this event is the palette chord's modifier state.
164
+ */
165
+ export declare function isPaletteChord(facts: KeyFacts): boolean;
166
+ /**
167
+ * The platform command key label, for copy.
168
+ * @param platform - `navigator.platform`-ish string.
169
+ * @returns the label a user reads.
170
+ */
171
+ export declare function commandLabel(platform: string): string;
172
+ /**
173
+ * Resolve one key event into a history intent, or `undefined` to let it pass.
174
+ *
175
+ * The environment gates run FIRST and they gate everything: while the `@` menu
176
+ * or a modal owns the keyboard, this plugin does not merely decline the arrow
177
+ * keys — it declines `Escape` too, because a modal's own Escape handling is a
178
+ * bubbling listener that does not preventDefault, so a capture listener that
179
+ * acted first would close both.
180
+ * @param facts - the key event facts.
181
+ * @param phase - the current phase.
182
+ * @param env - the environment facts.
183
+ * @returns the intent, or undefined to let the event through untouched.
184
+ */
185
+ export declare function resolveIntent(facts: KeyFacts, phase: HistoryPhase, env: HistoryEnvironment): HistoryIntent | undefined;
186
+ /**
187
+ * Whether an intent must preventDefault.
188
+ *
189
+ * Leaving on an ordinary keystroke must not consume it: the user is typing, and
190
+ * the character has to reach the composer. Every other gesture is ours.
191
+ * @param intent - the resolved intent.
192
+ * @returns whether to consume the event.
193
+ */
194
+ export declare function consumes(intent: HistoryIntent): boolean;
195
+ /**
196
+ * Whether an intent leaves the roaming state on an ordinary keystroke.
197
+ *
198
+ * Such a keystroke must reach the composer with its normal meaning, so it is not
199
+ * consumed; Escape (also a `leave`) is ours and is consumed.
200
+ * @param intent - the resolved intent.
201
+ * @returns whether the event must be consumed.
202
+ */
203
+ export declare function isLeave(intent: HistoryIntent): intent is {
204
+ readonly kind: 'leave';
205
+ readonly consume: boolean;
206
+ };
207
+ /**
208
+ * Step a cursor move, WRAPPING at both ends of the walk.
209
+ *
210
+ * The slot space is `[draft, ...frames in reverse chronological order]`: index 0
211
+ * is the composer's own draft slot and index N is the OLDEST frame, so asking for
212
+ * something OLDER (`direction: -1`) moves to a HIGHER slot index. That ordering is
213
+ * what makes "keep pressing Ctrl+Up" walk backwards through history and "then
214
+ * press Ctrl+Down" walk forwards, ending on the draft the user started from.
215
+ *
216
+ * Wrapping used to be unconditional (A-17), and it still is for ESC roaming. A-21
217
+ * split the two features on this point: the user asked for Ctrl+↑/↓ to "去掉首尾
218
+ * 循环", because a chord that silently jumped from the oldest message back to the
219
+ * draft made the position hard to reason about — and since A-21 also resets the
220
+ * chord's position whenever the walk's starting point changes, a wrap would be the
221
+ * only way to reach a position the user did not travel to. So wrapping is now
222
+ * opt-in through `allowWrap`: roaming passes `true`, the chord `false`.
223
+ *
224
+ * The slot space still has `frameCount + 1` positions — the draft is a real
225
+ * position, not a boundary — and when wrapping is allowed stepping past either end
226
+ * lands on the other, so `stepSlot(0, -1, n, true)` is the newest frame and
227
+ * `stepSlot(n + 1, 1, n, true)` is `0` again.
228
+ *
229
+ * Callers must NOT treat "the wrapped result" as "the edge was reached": the
230
+ * walk's own paging contract (§5.4 / A-12) still owns the older edge, and only
231
+ * once paging can bring nothing more may a press wrap. `FrameCursor` enforces
232
+ * that ordering by attempting the page first and wrapping on the following press.
233
+ * @param current - the current slot index.
234
+ * @param direction - -1 for older, 1 for newer.
235
+ * @param frameCount - how many frames exist.
236
+ * @param allowWrap - true to wrap past either end (ESC roaming), false to stop at
237
+ * it (the Ctrl+↑/↓ chord, A-21).
238
+ * @returns the next slot index, inside `[0, frameCount]`.
239
+ */
240
+ export declare function stepSlot(current: number, direction: -1 | 1, frameCount: number, allowWrap: boolean): number;
241
+ /**
242
+ * Clamp a slot index into the walk, without wrapping.
243
+ *
244
+ * The companion to `stepSlot`, and the reason A-17 does not break A-12: a PAGED
245
+ * move must stop at the end of the walk (so "did the cursor move?" still answers
246
+ * the paging question), while a single step wraps. Also used to translate a
247
+ * would-be wrap into the edge it crossed.
248
+ * @param slot - the slot index to clamp.
249
+ * @param frameCount - how many frames exist.
250
+ * @returns the slot index inside `[0, frameCount]`.
251
+ */
252
+ export declare function clampSlot(slot: number, frameCount: number): number;
253
+ /**
254
+ * Convert a slot index into a frame index, or undefined for the draft slot.
255
+ * @param slot - the slot index.
256
+ * @param frameCount - how many frames exist.
257
+ * @returns the frame's index in the oldest-first frame array, or undefined.
258
+ */
259
+ export declare function frameAtSlot(slot: number, frameCount: number): number | undefined;
260
+ /**
261
+ * Convert a frame index into its slot index.
262
+ * @param frameIndex - index in the oldest-first frame array.
263
+ * @param frameCount - how many frames exist.
264
+ * @returns the slot index.
265
+ */
266
+ export declare function slotOfFrame(frameIndex: number, frameCount: number): number;
@@ -1,6 +1,20 @@
1
1
  import type { Context as ClientContext } from '@deepseek-ai/cordis';
2
+ import { type PickerEntry } from './FolderPicker.tsx';
2
3
  /** Required services: picker pipeline, session projection, carrier, Remote face, slots, and locale. */
3
4
  export declare const inject: string[];
5
+ /**
6
+ * The crumb strip for one absolute path: each ancestor of the location, outermost
7
+ * first, so the user can jump straight back up to any of them.
8
+ *
9
+ * Built from the PATH rather than taken from a backend: the plugin's own listing
10
+ * reports `parent` (one step) but not the whole ancestry, and a drive root is its
11
+ * own first crumb. Each crumb's `name` is the segment it represents, with the
12
+ * drive root keeping its full spelling so it is recognisable in the strip, and
13
+ * the POSIX root contributing a `/` crumb so it stays reachable.
14
+ * @param path - the canonical absolute path being listed.
15
+ * @returns one entry per ancestor, or `[]` for a path with no ancestors.
16
+ */
17
+ export declare function crumbsOf(path: string): readonly PickerEntry[];
4
18
  /**
5
19
  * Compose the @ mention surface.
6
20
  * @param ctx - client root context.
@@ -26,11 +26,43 @@ export declare const zh: {
26
26
  'section.usage': string;
27
27
  'section.relevance': string;
28
28
  'folder.outside': string;
29
- 'settings.folderOpen': string;
30
- 'settings.folderOpenDesc': string;
31
- 'settings.folderOpen.both': string;
32
- 'settings.folderOpen.sidebar': string;
33
- 'settings.folderOpen.native': string;
29
+ 'settings.historyJump': string;
30
+ 'settings.historyJumpDesc': string;
31
+ 'settings.historyGroup.shared': string;
32
+ 'settings.historyGroup.sharedDesc': string;
33
+ 'settings.historyGroup.roam': string;
34
+ 'settings.historyGroup.roamDesc': string;
35
+ 'settings.historyGroup.quick': string;
36
+ 'settings.historyGroup.quickDesc': string;
37
+ 'settings.historyJumpFrames': string;
38
+ 'settings.historyJumpFramesDesc': string;
39
+ 'settings.historyJumpFrames.message': string;
40
+ 'settings.historyJumpFrames.turn': string;
41
+ 'settings.historyJumpReuseMode': string;
42
+ 'settings.historyJumpReuseModeDesc': string;
43
+ 'settings.historyJumpReuseMode.replace': string;
44
+ 'settings.historyJumpReuseMode.append': string;
45
+ 'settings.historyJumpSmartFollow': string;
46
+ 'settings.historyJumpSmartFollowDesc': string;
47
+ 'history.jumpHint': string;
48
+ 'history.draftSlot': string;
49
+ 'history.steeringTag': string;
50
+ 'history.replyTag': string;
51
+ 'history.systemTag': string;
52
+ 'history.systemOnly': string;
53
+ 'history.empty': string;
54
+ 'history.position': string;
55
+ 'history.positionTurn': string;
56
+ 'history.roamLabel': string;
57
+ 'history.reuse': string;
58
+ 'history.edge': string;
59
+ 'history.offscreen': string;
60
+ 'history.paletteTitle': string;
61
+ 'history.paletteHint': string;
62
+ 'history.paletteFilter': string;
63
+ 'history.paletteEmpty': string;
64
+ 'history.paletteCount': string;
65
+ 'history.paletteAnswer': string;
34
66
  'time.now': string;
35
67
  'time.minutes': string;
36
68
  'time.hours': string;
@@ -124,6 +156,19 @@ export declare const zh: {
124
156
  'picker.cancel': string;
125
157
  'picker.open': string;
126
158
  'picker.error': string;
159
+ 'picker.up': string;
160
+ 'picker.drives': string;
161
+ 'picker.preset': string;
162
+ 'picker.group.presets': string;
163
+ 'picker.group.current': string;
164
+ 'picker.group.none': string;
165
+ 'picker.pathPlaceholder': string;
166
+ 'picker.filtering': string;
167
+ 'picker.noMatch': string;
168
+ 'picker.keys': string;
169
+ 'picker.refusal.outside': string;
170
+ 'picker.refusal.missing': string;
171
+ 'picker.refusal.notDirectory': string;
127
172
  };
128
173
  /** The `at-file` namespace key union. */
129
174
  export type AtFileKey = keyof typeof zh;
@@ -150,11 +195,43 @@ export declare const en: {
150
195
  'section.recent': string;
151
196
  'section.usage': string;
152
197
  'section.relevance': string;
153
- 'settings.folderOpen': string;
154
- 'settings.folderOpenDesc': string;
155
- 'settings.folderOpen.both': string;
156
- 'settings.folderOpen.sidebar': string;
157
- 'settings.folderOpen.native': string;
198
+ 'settings.historyJump': string;
199
+ 'settings.historyJumpDesc': string;
200
+ 'settings.historyGroup.shared': string;
201
+ 'settings.historyGroup.sharedDesc': string;
202
+ 'settings.historyGroup.roam': string;
203
+ 'settings.historyGroup.roamDesc': string;
204
+ 'settings.historyGroup.quick': string;
205
+ 'settings.historyGroup.quickDesc': string;
206
+ 'settings.historyJumpFrames': string;
207
+ 'settings.historyJumpFramesDesc': string;
208
+ 'settings.historyJumpFrames.message': string;
209
+ 'settings.historyJumpFrames.turn': string;
210
+ 'settings.historyJumpReuseMode': string;
211
+ 'settings.historyJumpReuseModeDesc': string;
212
+ 'settings.historyJumpReuseMode.replace': string;
213
+ 'settings.historyJumpReuseMode.append': string;
214
+ 'settings.historyJumpSmartFollow': string;
215
+ 'settings.historyJumpSmartFollowDesc': string;
216
+ 'history.jumpHint': string;
217
+ 'history.draftSlot': string;
218
+ 'history.steeringTag': string;
219
+ 'history.replyTag': string;
220
+ 'history.systemTag': string;
221
+ 'history.systemOnly': string;
222
+ 'history.empty': string;
223
+ 'history.position': string;
224
+ 'history.positionTurn': string;
225
+ 'history.roamLabel': string;
226
+ 'history.reuse': string;
227
+ 'history.edge': string;
228
+ 'history.offscreen': string;
229
+ 'history.paletteTitle': string;
230
+ 'history.paletteHint': string;
231
+ 'history.paletteFilter': string;
232
+ 'history.paletteEmpty': string;
233
+ 'history.paletteCount': string;
234
+ 'history.paletteAnswer': string;
158
235
  'folder.outside': string;
159
236
  'time.now': string;
160
237
  'time.minutes': string;
@@ -249,6 +326,19 @@ export declare const en: {
249
326
  'picker.cancel': string;
250
327
  'picker.open': string;
251
328
  'picker.error': string;
329
+ 'picker.up': string;
330
+ 'picker.drives': string;
331
+ 'picker.preset': string;
332
+ 'picker.group.presets': string;
333
+ 'picker.group.current': string;
334
+ 'picker.group.none': string;
335
+ 'picker.pathPlaceholder': string;
336
+ 'picker.filtering': string;
337
+ 'picker.noMatch': string;
338
+ 'picker.keys': string;
339
+ 'picker.refusal.outside': string;
340
+ 'picker.refusal.missing': string;
341
+ 'picker.refusal.notDirectory': string;
252
342
  };
253
343
  /** Locale namespace id registered under ctx.locale. */
254
344
  export declare const NS = "atlas";
@@ -25,6 +25,16 @@ export type ReferenceLink = {
25
25
  readonly kind: 'session';
26
26
  readonly sessionId: string;
27
27
  };
28
+ /**
29
+ * Is this mention body spelled with a handle that names a label rather than a
30
+ * resource? Callers that read a raw token (the chip decoder, the draft's own
31
+ * path resolver) must skip these: the scope inside a scoped plugin mention is
32
+ * part of the module name, and reading it as a path invents a file that no
33
+ * workspace holds (m05904).
34
+ * @param raw - the mention body, without its leading `@`.
35
+ * @returns true when the body is one of our inert handles.
36
+ */
37
+ export declare function isInertHandle(raw: string): boolean;
28
38
  /**
29
39
  * Decode one reference chip's raw label (its `title`) into the action it offers.
30
40
  *
@@ -107,6 +117,53 @@ export declare function absoluteFileAddress(path: string): string;
107
117
  * @returns the folder address this plugin's tab claims.
108
118
  */
109
119
  export declare function folderAddress(path: string): string;
120
+ /**
121
+ * What a folder tab is told to select when it opens.
122
+ *
123
+ * A folder tab is opened by ADDRESS, and an address is the tab's identity — a
124
+ * second open of the same folder must not open a second tab — so the thing to
125
+ * select cannot ride the address itself (it is not part of the folder's name,
126
+ * and the tab's own title reads the address). It rides the open options instead:
127
+ * `openResource(address, { params })` lands them on `tab.navigation.params`, a
128
+ * value the tab re-reads on every navigation. This plugin owns the `folder`
129
+ * resource type, so it also owns the shape of that value: {@link selectionOf} is
130
+ * the single reader of the key below.
131
+ */
132
+ export interface FolderSelectionParams {
133
+ /** The name (one path segment) of the child to select in the opened folder. */
134
+ readonly select?: string;
135
+ }
136
+ /**
137
+ * The folder a path LIVES IN, plus the name to select in it.
138
+ *
139
+ * "Click a reference twice and you get its owning folder, with the reference
140
+ * selected" — so this answers the pair, for a file and for a folder alike (a
141
+ * folder's own owning folder is its parent). Purely lexical on purpose: it must
142
+ * answer for a path whose neighbours are unknown, and the caller is the one that
143
+ * knows how to turn a relative answer into an absolute path.
144
+ * @param path - the reference path, either separator spelling.
145
+ * @returns the parent directory in canonical (forward-slash) spelling (`''` = the
146
+ * top of a relative path, `/` for the POSIX root, `E:/` for a drive root) and the
147
+ * segment to select there. The spelling is normalized for the same reason
148
+ * {@link folderAddress} normalizes it: the answer is compared against index keys
149
+ * and turned into an address, and both of those speak one spelling.
150
+ */
151
+ export declare function owningFolderOf(path: string): {
152
+ readonly dir: string;
153
+ readonly select: string;
154
+ };
155
+ /**
156
+ * The child one folder tab was told to select, or undefined when it was told
157
+ * nothing.
158
+ *
159
+ * Reads `unknown` rather than {@link FolderSelectionParams} because the value
160
+ * arrives from the product's navigation state, which this plugin does not own:
161
+ * a stale or foreign navigation must read as "nothing to select", never as a
162
+ * crash or as a wrong row.
163
+ * @param params - `tab.navigation.params`, as delivered.
164
+ * @returns the segment to select, or undefined.
165
+ */
166
+ export declare function selectionOf(params: unknown): string | undefined;
110
167
  /**
111
168
  * The folder one address names, or undefined when it is not ours.
112
169
  * @param address - a resource address.
@@ -9,8 +9,8 @@
9
9
  import type { RemoteResult, TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
10
10
  import type { SessionId } from '@deepseek-ai/dsh-session/types';
11
11
  import type { AtlasRuntimeInfo } from '../atlas.ts';
12
- import type { AtFileSettings, AtFileSettingsUpdate, ChatCandidate, DirectoryListing, GitChange, PluginCandidate, ReferenceInfo, SkillCandidate } from '../contract.ts';
13
- export type { DirectoryEntry, DirectoryListing, FileEntry, SkillCandidate, ChatCandidate, PluginCandidate, GitChange } from '../contract.ts';
12
+ import type { AtFileSettings, AtFileSettingsUpdate, BrowseListing, ChatCandidate, DirectoryListing, GitChange, PluginCandidate, RecentFolder, ReferenceInfo, SkillCandidate } from '../contract.ts';
13
+ export type { DirectoryEntry, DirectoryListing, FileEntry, SkillCandidate, ChatCandidate, PluginCandidate, GitChange, RecentFolder, RecentFolderReason } from '../contract.ts';
14
14
  /** The combined Remote namespace contribution (one package face). */
15
15
  export declare const AT_REMOTE: TypertRemoteContribution;
16
16
  declare module '@deepseek-ai/dsh-typert-protocol' {
@@ -20,7 +20,9 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
20
20
  inspect: (agentId: SessionId, targets: readonly string[], signal?: AbortSignal) => Promise<RemoteResult<readonly ReferenceInfo[]>>;
21
21
  getSettings: () => Promise<RemoteResult<AtFileSettings>>;
22
22
  updateSettings: (update: AtFileSettingsUpdate) => Promise<RemoteResult<AtFileSettings>>;
23
- list: (agentId: SessionId, path: string, signal?: AbortSignal) => Promise<RemoteResult<DirectoryListing>>;
23
+ list: (agentId: SessionId, path: string, include: string, signal?: AbortSignal) => Promise<RemoteResult<DirectoryListing>>;
24
+ browse: (agentId: SessionId, path: string, signal?: AbortSignal) => Promise<RemoteResult<BrowseListing>>;
25
+ recentFolders: (agentId: SessionId, signal?: AbortSignal) => Promise<RemoteResult<readonly RecentFolder[]>>;
24
26
  }
25
27
  /** The `atlas` namespace face (host half of the @ data-source seam). */
26
28
  interface TypertRemoteNamespace$61746c6173 {
@@ -37,7 +39,9 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
37
39
  'atFile/search': (agentId: SessionId, signal?: AbortSignal) => Promise<RemoteResult<readonly import('../contract.ts').FileEntry[]>>;
38
40
  'atFile/inspect': (agentId: SessionId, targets: readonly string[], signal?: AbortSignal) => Promise<RemoteResult<readonly ReferenceInfo[]>>;
39
41
  'atFile/external': (agentId: SessionId, signal?: AbortSignal) => Promise<RemoteResult<import('../contract.ts').ExternalAccessScope>>;
40
- 'atFile/list': (agentId: SessionId, path: string, signal?: AbortSignal) => Promise<RemoteResult<DirectoryListing>>;
42
+ 'atFile/list': (agentId: SessionId, path: string, include: string, signal?: AbortSignal) => Promise<RemoteResult<DirectoryListing>>;
43
+ 'atFile/browse': (agentId: SessionId, path: string, signal?: AbortSignal) => Promise<RemoteResult<BrowseListing>>;
44
+ 'atFile/recentFolders': (agentId: SessionId, signal?: AbortSignal) => Promise<RemoteResult<readonly RecentFolder[]>>;
41
45
  'atFile/getSettings': () => Promise<RemoteResult<AtFileSettings>>;
42
46
  'atFile/updateSettings': (update: AtFileSettingsUpdate) => Promise<RemoteResult<AtFileSettings>>;
43
47
  'atMention/listSkills': (agentId: SessionId, signal?: AbortSignal) => Promise<RemoteResult<readonly SkillCandidate[]>>;
@@ -0,0 +1,64 @@
1
+ /**
2
+ * The roaming cursor's shared state.
3
+ *
4
+ * The gesture and the readout used to be one component. They are now two: the
5
+ * key listener stays in `conversation.input.overlay` (it owns the keyboard), while
6
+ * the readout renders in `conversation.input.dock` so it stacks with `/goal` and
7
+ * `/todo` instead of floating over them. Two slot components are two React trees,
8
+ * so they cannot share state through props or context — this module is the seam.
9
+ *
10
+ * It is a `createSnapshotStore`, the same primitive the plugin already uses for
11
+ * its other cross-half state: a store whose snapshot identity changes only when
12
+ * the value does, which is what `useSyncExternalStore` needs to avoid a render
13
+ * loop. The store is created ONCE per plugin apply and injected into BOTH
14
+ * registrations, so the two halves are looking at one instance rather than at two
15
+ * module-level singletons (a second `apply` in the same page — which a reload or a
16
+ * second session shell can produce — must not have them fighting over one value).
17
+ */
18
+ /** What the readout needs in order to draw itself. */
19
+ export interface RoamView {
20
+ /** Whether the walk is active; false hides the readout entirely. */
21
+ readonly roaming: boolean;
22
+ /** The position line, already interpolated for the active locale. */
23
+ readonly count: string;
24
+ /** The highlighted frame's preview, or the draft's caption at slot 0. */
25
+ readonly preview: string;
26
+ /** Whether the walk is pressed against the oldest loaded frame. */
27
+ readonly edge: boolean;
28
+ /**
29
+ * The origin tag for the highlighted frame, already localized (A-20), or `''`
30
+ * for a normal user message.
31
+ *
32
+ * A system-initiated turn carries no prompt text in the outline, so before this
33
+ * the readout rendered an empty cell where the message should be and the user
34
+ * read that as a broken feature. The tag names the origin, and the caller pairs
35
+ * it with a fallback line when there is no message text to show.
36
+ */
37
+ readonly tag: string;
38
+ /**
39
+ * Whether the highlighted frame could not be scrolled to (A-26), or `false`
40
+ * when the page did move.
41
+ *
42
+ * Kept separate from `edge`: they answer different questions and only one of
43
+ * them is the walk's fault. `edge` says the walk ran out of loaded history;
44
+ * this says the frame is known but this build exposes no row to scroll to — a
45
+ * degraded build, not an exhausted history. Reporting the second as the first
46
+ * would tell the user their history ended when it did not.
47
+ */
48
+ readonly offscreen: boolean;
49
+ }
50
+ /** The store's public shape: a snapshot to read and a setter to publish. */
51
+ export interface RoamStore {
52
+ readonly subscribe: (listener: () => void) => () => void;
53
+ readonly getSnapshot: () => RoamView;
54
+ readonly set: (next: RoamView) => void;
55
+ }
56
+ /**
57
+ * Build one roaming store.
58
+ *
59
+ * Equality is by VALUE rather than by identity on purpose: the publisher builds a
60
+ * fresh object on every key press and every streamed token, and a store that
61
+ * republished on identity alone would re-render the readout for every token.
62
+ * @returns the store, seeded with the hidden view.
63
+ */
64
+ export declare function createRoamStore(): RoamStore;
@@ -215,6 +215,22 @@ export declare function categoryTag(kind: 'file' | 'folder' | 'skill' | 'chat' |
215
215
  export declare function backRow(t?: Translate): MentionCandidate;
216
216
  /** A non-pickable section divider row (e.g. 最近引用 / 全部匹配). */
217
217
  export declare function sectionHeaderRow(label: string): MentionCandidate;
218
+ /**
219
+ * A non-pickable row saying the workspace index could not be read.
220
+ *
221
+ * Without it a failed index and a query that genuinely matches nothing render the
222
+ * SAME menu: the file rows are simply absent, and the user is left to conclude the
223
+ * plugin is broken or that the file does not exist. Reported from Linux as "typing
224
+ * letters after @ shows nothing", which is exactly this collapse — the index fetch
225
+ * threw (a workspace on a mount the process cannot read, a session with no `cwd`)
226
+ * and the catch answered `[]`, which is indistinguishable from "no match".
227
+ *
228
+ * It is a reason row, not an error dialog: browsing still works, other categories
229
+ * still answer, and the row only says why the file rows are missing. It carries
230
+ * `browse-note` — the kind the browser already uses for "a fact you must read and
231
+ * cannot pick" — so the navigator needs no new case.
232
+ */
233
+ export declare function indexFailureRow(reason: string): MentionCandidate;
218
234
  /** Relative-time buckets, mirroring the sidebar workspace rows. */
219
235
  export interface RelativeTime {
220
236
  readonly unit: 'now' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Consumer-side declarations for the shared snapshot hooks this plugin reads.
3
+ *
4
+ * The framework's standard kit is declared EMPTY on purpose (`SessionStandardProps`,
5
+ * `GlobalStandardProps`): each owning UI adapter merges the selectors it
6
+ * contributes, so a plugin that renders into a slot receives them at runtime
7
+ * while a program that does not depend on those adapter packages cannot see
8
+ * them. This module is that documented mechanism used from the consumer side —
9
+ * the same move `history-keys.ts` makes for the conversation hooks.
10
+ *
11
+ * Only the fields this plugin actually reads are declared, and every shape is
12
+ * read-only: the plugin never writes a harness snapshot.
13
+ */
14
+ /** The one Session fact the settings section reads off the list snapshot. */
15
+ export interface SessionListEntryView {
16
+ /** Host-authoritative last update time, in epoch milliseconds. */
17
+ readonly updatedAt: number;
18
+ /** The Session's working directory, when the Host reports one. */
19
+ readonly cwd?: string;
20
+ }
21
+ /** The Session-list snapshot as this plugin reads it. */
22
+ export interface SessionsSnapshotView {
23
+ /** Sessions by identity. */
24
+ readonly byId: Readonly<Record<string, SessionListEntryView | undefined>>;
25
+ /** The Session the client currently shows, when one is selected. */
26
+ readonly current?: string;
27
+ }
28
+ /** A selector hook over the Session-list snapshot. */
29
+ export type SessionsSelectorHook = <Selection>(selector: (snapshot: SessionsSnapshotView) => Selection) => Selection;
30
+ declare module '@deepseek-ai/dsh-client-ui-slots' {
31
+ interface GlobalStandardProps {
32
+ /**
33
+ * The Session-list selector hook (contributed by ui-session).
34
+ *
35
+ * The Workspace hook beside it is already declared by a package this
36
+ * program loads, so only the Session one is added here.
37
+ */
38
+ readonly useSessions: SessionsSelectorHook;
39
+ }
40
+ }