@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.
@@ -5,8 +5,18 @@ import type { SessionLabelResolver } from './session-link.ts';
5
5
  import type { ReferenceOutcome } from './ReferenceLinks.tsx';
6
6
  /** What the session's overlay shares with the draft bridge. */
7
7
  export interface DraftLinksInjected {
8
- /** The action a click on this mention performs, or undefined when this build has none. */
9
- readonly actionFor: (link: ReferenceLink) => (() => ReferenceOutcome | Promise<ReferenceOutcome>) | undefined;
8
+ /**
9
+ * The action a click on this mention performs, or undefined when this build
10
+ * has none. `again` is true for the SECOND click on the same object, which is
11
+ * what makes a folder token in the composer answer exactly like the dock's own
12
+ * row (A-27): the first click opens it in the right Sidebar, the second hands
13
+ * it to the desktop's file manager.
14
+ */
15
+ readonly actionFor: (link: ReferenceLink, again?: boolean) => (() => ReferenceOutcome | Promise<ReferenceOutcome>) | undefined;
16
+ /** Whether the plugin's click ledger records this link as the last one opened. */
17
+ readonly repeatClick: (link: ReferenceLink) => boolean;
18
+ /** Record this click in that ledger, which flips: the same link again is a new first click. */
19
+ readonly noteClick: (link: ReferenceLink) => void;
10
20
  /** The dock's own inspection verdicts: the bridge never re-asks for the same path. */
11
21
  readonly hooks: {
12
22
  readonly referenceInfo: ReferenceInfoSource;
@@ -26,4 +36,4 @@ export type DraftLinksProps = PropsRuntime<'conversation.input.overlay'> & Injec
26
36
  * @param props - the injected opener and the dock's verdict source.
27
37
  * @returns nothing; this entry renders no DOM of its own.
28
38
  */
29
- export declare function DraftLinks({ actionFor, useReferenceInfo, resolveSession }: DraftLinksProps): null;
39
+ export declare function DraftLinks({ actionFor, repeatClick, noteClick, useReferenceInfo, resolveSession }: DraftLinksProps): null;
@@ -10,11 +10,34 @@
10
10
  * `directoryPicker/pick` is the NATIVE chooser, which a profile serving the
11
11
  * in-app browse capability refuses (`directory-picker/unavailable`).
12
12
  *
13
- * What CAN be borrowed is the backend both of those use:
14
- * `ctx.uiWorkspace.listDirectory` / `createDirectory` (the `directoryPicker`
15
- * namespace's browse verbs). This dialog is that backend with our own face: the
16
- * path line is editable, a row with a chevron walks into that folder, and 打开
17
- * confirms the folder the path line is showing.
13
+ * What CAN be borrowed is the backend both of those use: this plugin's own
14
+ * `atFile.browse` / `atFile.list` / `atFile.create` (see the wire face below).
15
+ *
16
+ * The list is ONE tree in TWO groups:
17
+ *
18
+ * 常用区外文件夹 (collapsed until asked for)
19
+ * ├ Projects → a jump outside the workspace
20
+ * └ …
21
+ * 当前文件夹 (open, and where the browsing happens)
22
+ * ├ ⬆ 上一级
23
+ * ├ Eason → Enter expands it in place, Ctrl+Enter adopts it
24
+ * └ …
25
+ *
26
+ * The path line and the list are two views of the SAME location and may not
27
+ * diverge: typing a path (or pressing Enter on it) re-roots the tree, and every
28
+ * way of moving — a crumb, a drive, the way up, a preset, an expanded folder —
29
+ * updates both.
30
+ *
31
+ * `Enter` and `Ctrl+Enter` are different verbs everywhere in this dialog, and
32
+ * the difference does not depend on which row happens to be current:
33
+ *
34
+ * Enter expand what can be expanded (a group, a folder with children);
35
+ * adopt what cannot (a folder without children)
36
+ * Ctrl+Enter adopt the current row — write the reference and close
37
+ *
38
+ * The cursor is tracked by ROW KEY rather than by index, so expanding a folder
39
+ * (which inserts rows) or filtering (which removes them) leaves it exactly where
40
+ * it was: the only thing that moves the current row is an arrow key.
18
41
  */
19
42
  import { type ReactNode } from 'react';
20
43
  import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
@@ -23,6 +46,18 @@ export interface PickerEntry {
23
46
  readonly name: string;
24
47
  readonly path: string;
25
48
  readonly hidden: boolean;
49
+ /**
50
+ * Whether this folder holds at least one child folder. Absent when the Host did
51
+ * not say (an older Host, or a probe that ran out of budget): the row then
52
+ * offers expansion and finds out on the way in.
53
+ */
54
+ readonly hasChildren?: boolean;
55
+ }
56
+ /** One offered folder the chooser can jump to without browsing (see the Host's `recentFolders`). */
57
+ export interface PickerPreset {
58
+ readonly path: string;
59
+ readonly name: string;
60
+ readonly reason: 'sibling' | 'parent' | 'child' | 'recent' | 'family';
26
61
  }
27
62
  /** One browse level: the folder itself, its ancestry, and its child folders. */
28
63
  export interface PickerListing {
@@ -31,6 +66,18 @@ export interface PickerListing {
31
66
  readonly crumbs: readonly PickerEntry[];
32
67
  readonly entries: readonly PickerEntry[];
33
68
  readonly truncated: boolean;
69
+ /** The drive roots, present exactly while the listing IS a drive root. */
70
+ readonly drives?: readonly string[];
71
+ /** The folder above, absent at a drive root (where `drives` takes its place). */
72
+ readonly parent?: string;
73
+ /** Why this level could not be listed, when it could not. */
74
+ readonly error?: 'outside' | 'missing' | 'notDirectory';
75
+ /**
76
+ * What the user actually typed, present only while it is DEEPER than `path`:
77
+ * `path` is the longest valid prefix of it that could be listed, and the rest is
78
+ * the needle the two groups filter by.
79
+ */
80
+ readonly requested?: string;
34
81
  }
35
82
  /** The open/closed share between the source's picker row and this dialog. */
36
83
  export interface FolderPickerSnapshot {
@@ -44,10 +91,14 @@ export interface FolderPickerSource {
44
91
  }
45
92
  /** What the session's shell shares with the dialog. */
46
93
  export interface FolderPickerInjected {
47
- /** One directory level from the product's picker backend; undefined starts at home. */
94
+ /** One directory level for a path being typed: the longest valid prefix plus its child folders. */
95
+ readonly browse: (path: string | undefined, signal: AbortSignal) => Promise<PickerListing>;
96
+ /** One directory level; `''` means the session workspace root, undefined means the drive root holding it. */
48
97
  readonly list: (path: string | undefined, signal: AbortSignal) => Promise<PickerListing>;
49
98
  /** Create one child folder and answer its absolute path. */
50
99
  readonly create: (path: string, name: string) => Promise<string>;
100
+ /** The folders worth offering before any browsing (ranked; possibly empty). */
101
+ readonly recent: (signal: AbortSignal) => Promise<readonly PickerPreset[]>;
51
102
  /** Adopt the folder the path line shows (inserts the reference and closes). */
52
103
  readonly confirm: (path: string) => void;
53
104
  /** Dismiss without adopting anything. */
@@ -63,4 +114,4 @@ export type FolderPickerProps = PropsRuntime<'conversation.input.overlay'> & Pro
63
114
  * @param props - the open state, the browse backend, and the adoption callbacks.
64
115
  * @returns the modal, or null while closed.
65
116
  */
66
- export declare function FolderPicker({ useFolderPicker, list, create, confirm, close, t }: FolderPickerProps): ReactNode;
117
+ export declare function FolderPicker({ useFolderPicker, browse, list, create, recent, confirm, close, t }: FolderPickerProps): ReactNode;
@@ -32,8 +32,13 @@ export declare const FOLDER_TAB_KIND = "atlas-folder";
32
32
  export declare function folderTabDefinition(t: (key: AtFileKey, params?: Record<string, string>) => string): SidebarRightTabDefinition;
33
33
  /** What the session's shell shares with the folder tab. */
34
34
  export interface FolderTabInjected {
35
- /** List one directory (one level); `''` means the session workspace root. */
36
- readonly list: (path: string, signal: AbortSignal) => Promise<DirectoryListing>;
35
+ /**
36
+ * List one directory (one level); `''` means the session workspace root.
37
+ * `include` names ONE child that must be present in the page: the entry cap is
38
+ * applied before the sort, so a huge folder can answer a page without the very
39
+ * row this tab has to select. `''` asks for no such guarantee.
40
+ */
41
+ readonly list: (path: string, signal: AbortSignal, include?: string) => Promise<DirectoryListing>;
37
42
  /** Open a file the way every other reference does. */
38
43
  readonly openFile: (path: string) => void;
39
44
  /** Hand a path to the OS file manager. */
@@ -0,0 +1,104 @@
1
+ import type { ReactElement } from 'react';
2
+ import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
3
+ import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
4
+ import type { RoamStore } from './roam-store.ts';
5
+ import { type HistoryStandardProps } from './history-keys.ts';
6
+ import type { AtFileSettingsSource } from './FilesDock.tsx';
7
+ import { NS } from './locales.ts';
8
+ /**
9
+ * The plugin's own structural view of one session projection face.
10
+ *
11
+ * Deliberately structural rather than imported from the api package: the overlay
12
+ * only ever needs `faceOf`, and narrowing it here keeps a client build whose face
13
+ * spells that differently degrading to the window-only walk rather than failing
14
+ * to typecheck against a version this package does not pin.
15
+ */
16
+ export interface ProjectionFace {
17
+ /** @param key - projection key. @returns its live value, or undefined. */
18
+ readonly faceOf: (key: string) => {
19
+ readonly getSnapshot: () => unknown;
20
+ readonly subscribe: (listener: () => void) => () => void;
21
+ };
22
+ }
23
+ /** How many slots `PageUp`/`PageDown` move while roaming. */
24
+ export declare const ROAM_PAGE_ROWS = 5;
25
+ /** Injected surface for the roaming overlay. */
26
+ export interface FrameCursorInjected {
27
+ /** The plugin's settings snapshot. */
28
+ readonly scope: AtFileSettingsSource;
29
+ /** The @ mention menu, whose open state suppresses the gesture. */
30
+ readonly menu?: SnapshotStore<{
31
+ readonly open: boolean;
32
+ }>;
33
+ /**
34
+ * Page the loaded window back until it covers a seq (A-05).
35
+ *
36
+ * Optional by design: an older client build has no such verb, and the walk
37
+ * then simply stops at the oldest LOADED frame — which is a supported
38
+ * degradation, not a broken feature.
39
+ */
40
+ readonly loadThrough?: (seq: number) => Promise<void>;
41
+ /**
42
+ * The session-wide `turnOutline` projection, as a live observable (A-13).
43
+ *
44
+ * This is what makes the walk's total agree with the page's own turn ruler: the
45
+ * projection folds the WHOLE log, while the Chat snapshot only holds the paged
46
+ * window. Reading it through the session face rather than through a slot prop
47
+ * is deliberate — `useProjection` is declared on `ChatViewInjected`, which the
48
+ * `conversation.view` slot alone receives, whereas this overlay is handed the
49
+ * session face directly.
50
+ *
51
+ * Optional by design: a client build without the projection keeps the
52
+ * window-only walk instead of failing to register the gesture.
53
+ */
54
+ readonly projections?: ProjectionFace;
55
+ /**
56
+ * Where the readout is published.
57
+ *
58
+ * The readout renders in the input dock (so it stacks with `/goal` and `/todo`)
59
+ * while this component owns the key listener, and two slot components are two
60
+ * React trees — hence a store rather than state. Optional so an injected
61
+ * `FrameCursor` in a spec that only cares about keys stays valid.
62
+ */
63
+ readonly roam?: RoamStore;
64
+ }
65
+ /**
66
+ * The overlay props.
67
+ *
68
+ * `input`, `inputActions` and `useChat` are NOT declared as injections: they are
69
+ * standard props the renderer spreads into every session-scoped slot, so listing
70
+ * them here would be a lie the registration site then has to satisfy. Only the
71
+ * plugin's own injections live in `FrameCursorInjected`.
72
+ */
73
+ export type FrameCursorProps = PropsRuntime<'conversation.input.overlay'> & InjectFace<FrameCursorInjected> & HistoryStandardProps & PropsLocale<typeof NS>;
74
+ /** Invisible overlay entry: the history roaming gesture. */
75
+ export declare function FrameCursor(props: FrameCursorProps): null;
76
+ /** Injected surface for the dock-hosted readout. */
77
+ export interface FrameReadoutInjected {
78
+ /** The store the overlay publishes the cursor into. */
79
+ readonly roam?: RoamStore;
80
+ }
81
+ /**
82
+ * The dock-hosted counterpart of `FrameCursorProps`, for the readout half.
83
+ *
84
+ * It deliberately does NOT take the Chat hook: the cursor is already computed by
85
+ * the overlay half, and recomputing the walk here would double the work for a
86
+ * value it would then have to keep in step. It reads the published store instead.
87
+ */
88
+ export type FrameReadoutProps = PropsRuntime<'conversation.input.dock'> & InjectFace<FrameReadoutInjected> & PropsLocale<typeof NS>;
89
+ /**
90
+ * The roaming readout, rendered above the composer.
91
+ *
92
+ * It lives in `conversation.input.dock` rather than in an overlay, which is what
93
+ * the user asked for: `/goal` and `/todo` are dock entries too, and the dock is a
94
+ * flex column, so the three STACK instead of covering one another. That is a
95
+ * structural guarantee — there is no z-index to get wrong and no geometry to
96
+ * measure — and it also means the readout shares the composer's width for free,
97
+ * which is what the retired card-measuring effect used to arrange by hand.
98
+ *
99
+ * It renders nothing at all while the walk is inactive, so the dock gains no
100
+ * permanent row when the feature is not in use.
101
+ * @param props - the dock slot props, carrying the injected store.
102
+ * @returns the readout strip, or null when not roaming.
103
+ */
104
+ export declare function FrameReadout(props: FrameReadoutProps): ReactElement | null;
@@ -0,0 +1,25 @@
1
+ import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
2
+ import { type HistoryFrame } from './history-frames.ts';
3
+ import type { HistoryStandardProps } from './history-keys.ts';
4
+ import type { AtFileSettingsSource } from './FilesDock.tsx';
5
+ import { NS } from './locales.ts';
6
+ /** Injected surface for the palette. */
7
+ export interface HistoryPaletteInjected {
8
+ /** The plugin's settings snapshot. */
9
+ readonly scope: AtFileSettingsSource;
10
+ }
11
+ /** The palette props; standard session props arrive spread onto the object. */
12
+ export type HistoryPaletteProps = PropsRuntime<'conversation.input.overlay'> & InjectFace<HistoryPaletteInjected> & HistoryStandardProps & PropsLocale<typeof NS>;
13
+ /**
14
+ * Whether a frame matches the palette's filter.
15
+ *
16
+ * The query is matched against the message's own text AND its turn's answer:
17
+ * "the one where we talked about X" is as often remembered by the reply as by
18
+ * the question. An empty query matches everything.
19
+ * @param frame - the frame.
20
+ * @param query - the collapsed, lower-cased query.
21
+ * @returns whether the frame should be listed.
22
+ */
23
+ export declare function matchesQuery(frame: HistoryFrame, query: string): boolean;
24
+ /** The history palette overlay. */
25
+ export declare function HistoryPalette(props: HistoryPaletteProps): import("react").JSX.Element | null;
@@ -19,7 +19,27 @@ export interface ReferenceLinksInjected {
19
19
  * the mention was sent — so the bridge marks that chip stale instead of
20
20
  * pretending the click opened something.
21
21
  */
22
- readonly actionFor: (link: ReferenceLink) => (() => ReferenceOutcome | Promise<ReferenceOutcome>) | undefined;
22
+ readonly actionFor: (link: ReferenceLink, again?: boolean) => (() => ReferenceOutcome | Promise<ReferenceOutcome>) | undefined;
23
+ /**
24
+ * Whether this click is the SECOND one on the same reference (A.16).
25
+ *
26
+ * The plugin answers this from its own ledger rather than from the event's
27
+ * `detail`, because `detail` is synthesized by the operating system's
28
+ * double-click interval: the user's ruling (`m02489`) is that the second
29
+ * meaning must not depend on clicking quickly, and a ledger is the only thing
30
+ * that can tell "the same object again" from "another click nearby" at any
31
+ * speed. See {@link noteClick} for when the ledger moves on.
32
+ */
33
+ readonly repeatClick: (link: ReferenceLink) => boolean;
34
+ /**
35
+ * Record that this reference has been clicked, and only after the action was
36
+ * actually resolved — an inert reference must not consume the sequence.
37
+ *
38
+ * Writing FLIPS the ledger rather than appending: a third click therefore means
39
+ * "open it" again, exactly like the first. Otherwise a user who clicked twice
40
+ * would be stuck in the second meaning with no way back to the first.
41
+ */
42
+ readonly noteClick: (link: ReferenceLink) => void;
23
43
  /**
24
44
  * Map one composer chip's label to a workspace-relative path.
25
45
  *
@@ -87,4 +107,4 @@ export declare function composerChipLink(host: Element, resolve?: (label: string
87
107
  */
88
108
  export declare function draftPathForLabel(draft: string, label: string): string | undefined;
89
109
  /** Invisible bridge: opens the reference chips the product renders on click. */
90
- export declare function ReferenceLinks({ actionFor, resolveLabel, useInput }: ReferenceLinksProps): null;
110
+ export declare function ReferenceLinks({ actionFor, resolveLabel, repeatClick, noteClick, useInput }: ReferenceLinksProps): null;
@@ -1,6 +1,6 @@
1
1
  /** Settings section for global and workspace-specific file filter rules. */
2
2
  import type { PropsLocale, PropsRuntime, InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
3
- import type { FileIgnoreRuleInput, FolderOpenTarget } from '../contract.ts';
3
+ import type { FileIgnoreRuleInput, FolderOpenTarget, HistoryFrameMode, HistoryReuseMode } from '../contract.ts';
4
4
  import type { AtFileSettingsSource } from './FilesDock.tsx';
5
5
  export type AtFileFilterScope = 'global' | 'workspace';
6
6
  /** Ephemeral settings navigation retained while the plugin stays mounted. */
@@ -20,6 +20,14 @@ export interface AtFileSectionInjected {
20
20
  setEnablePlugins: (enablePlugins: boolean) => Promise<void>;
21
21
  setIgnorePastedMentions: (ignore: boolean) => Promise<void>;
22
22
  setFolderOpen: (target: FolderOpenTarget) => Promise<void>;
23
+ /** Enable or disable the session history jump (palette + roaming). */
24
+ setHistoryJump: (enabled: boolean) => Promise<void>;
25
+ /** Choose the history frame granularity. */
26
+ setHistoryJumpFrames: (mode: HistoryFrameMode) => Promise<void>;
27
+ /** Choose how reusing a history message treats the current draft. */
28
+ setHistoryJumpReuseMode: (mode: HistoryReuseMode) => Promise<void>;
29
+ /** Choose whether the history walk follows the user's own scroll position. */
30
+ setHistoryJumpSmartFollow: (enabled: boolean) => Promise<void>;
23
31
  setIgnoreFiles: (ignoreFiles: readonly FileIgnoreRuleInput[]) => Promise<void>;
24
32
  setWorkspaceIgnoreFiles: (workspace: string, ignoreFiles: readonly FileIgnoreRuleInput[]) => Promise<void>;
25
33
  }
@@ -28,4 +36,4 @@ export type AtFileSectionProps = PropsRuntime<'settings.section'> & InjectFace<A
28
36
  /** Trim one legacy exact basename; retained for callers using the old helper. */
29
37
  export declare function parseIgnoreFile(value: string): string | undefined;
30
38
  /** Render the enable switch and scoped file-filter manager. */
31
- export declare function AtFileSection({ useScope, useSessions, useWorkspaces, viewState, setEnabled, setEnableSkills, setEnableChats, setEnablePlugins, setIgnorePastedMentions, setFolderOpen, setIgnoreFiles, setWorkspaceIgnoreFiles, t, }: AtFileSectionProps): import("react").JSX.Element;
39
+ export declare function AtFileSection({ useScope, useSessions, useWorkspaces, viewState, setEnabled, setEnableSkills, setEnableChats, setEnablePlugins, setIgnorePastedMentions, setFolderOpen, setHistoryJump, setHistoryJumpFrames, setHistoryJumpReuseMode, setHistoryJumpSmartFollow, setIgnoreFiles, setWorkspaceIgnoreFiles, t, }: AtFileSectionProps): import("react").JSX.Element;
@@ -0,0 +1,238 @@
1
+ /**
2
+ * The history frame index: the current session's user messages, in order, as the
3
+ * reusable "frames" the F1 palette lists and the F2 cursor walks.
4
+ *
5
+ * Everything here is derived from the Host's own authoritative Chat snapshot
6
+ * (`useChat`), which a session-scoped slot receives as a standard prop — so this
7
+ * feature adds NO wire endpoint and never reads file content. The DOM is used
8
+ * only to SCROLL to a frame's row, never to decide what the frames are: the row
9
+ * attributes the scroll looks for are absent from some shipped builds, and a
10
+ * missing attribute must degrade to "highlight without scrolling" rather than
11
+ * to a broken feature.
12
+ *
13
+ * A frame is one message the user can WALK to. In the default `'message'` mode
14
+ * that is every readable message of the session: the two kinds a user writes
15
+ * (`user`, and `steering` for an interjection claimed mid-turn) plus the
16
+ * assistant's own prose (`reply`). The question that produced the reply kind was
17
+ * "why does Up/Down stop on my input but never on the answer, the answer is a
18
+ * message too" — and it is: a reader scrolling back through a session wants to
19
+ * land on the answer as much as on the question.
20
+ *
21
+ * What still never becomes a frame: tool calls, injected context, and any node
22
+ * whose text is empty (a reply cancelled before its first token, a step that is
23
+ * pure tool plumbing). Those have no row worth stopping on.
24
+ *
25
+ * `'turn'` mode keeps its original meaning — one frame per turn, its opening
26
+ * prompt — because that is the coarse granularity a user asks for when a whole
27
+ * exchange should be one stop.
28
+ */
29
+ /** Which frame granularity the user chose. */
30
+ export type HistoryFrameMode = 'message' | 'turn';
31
+ /**
32
+ * One message the walk can stop on, projected from one Chat node.
33
+ *
34
+ * `reply` frames are the assistant's own prose: they are walkable but not
35
+ * reusable-by-chord, because the chord's answer to "reuse" is to put the text in
36
+ * the composer and an answer is not something the user wrote (see
37
+ * {@link isUserAuthored}).
38
+ */
39
+ export interface HistoryFrame {
40
+ /** The Chat node key; also the value of its row's `data-chat-anchor-key`. */
41
+ readonly key: string;
42
+ /** Durable seq, used for paging the window back to this frame. */
43
+ readonly seq: number;
44
+ /** The owning turn, or undefined when the node has no resolved turn. */
45
+ readonly turn: number | undefined;
46
+ /** Epoch ms of the source event. */
47
+ readonly time: number;
48
+ /** A normal user message, a mid-turn interjection, or the assistant's reply. */
49
+ readonly kind: 'user' | 'steering' | 'reply';
50
+ /**
51
+ * The message's original text: every text block of `content`, joined.
52
+ *
53
+ * This is the durable content, NOT the rendered DOM text, which is why a
54
+ * reused `@label` comes back as the reference token the user typed instead of
55
+ * as decoration the composer would no longer recognise.
56
+ */
57
+ readonly text: string;
58
+ /** A one-line preview for the palette row. */
59
+ readonly preview: string;
60
+ /** The turn's assistant answer, for the palette's second line (empty when none). */
61
+ readonly answer: string;
62
+ /** Whether the message carried non-text blocks (images/files) that will NOT be reused. */
63
+ readonly hasAttachment: boolean;
64
+ /**
65
+ * True when this frame came from the session-wide outline rather than from a
66
+ * loaded node, i.e. the message's row is NOT in the client window yet and
67
+ * {@link HistoryFrame.text} holds the outline's bounded preview instead of the
68
+ * original text.
69
+ *
70
+ * This exists because the readout's total must agree with the page's own turn
71
+ * ruler (`turnOutline` folds the WHOLE log; the loaded window is paged), and a
72
+ * walk that stopped at the window made the two disagree — the reported bug was
73
+ * "ruler has many ticks while the readout says 0 / 0". A consumer that needs
74
+ * the original text (a reuse) pages the window to {@link HistoryFrame.seq}
75
+ * first and lets the loaded frame replace this placeholder.
76
+ */
77
+ readonly unloaded: boolean;
78
+ /**
79
+ * The node's own `source.kind === 'user'` verdict, when the node carries a
80
+ * readable source. `undefined` means "no source to read", which is NOT the same
81
+ * as "not user-authored" — a node shape without a source is left to the other
82
+ * evidence rather than being silently excluded from the chord's frame set.
83
+ */
84
+ readonly authoredByUser?: boolean;
85
+ /**
86
+ * True when the TURN was started by the system/plugin rather than by the user,
87
+ * i.e. the roam bar must label it (A-20).
88
+ *
89
+ * This is deliberately SEPARATE from {@link HistoryFrame.authoredByUser}, even
90
+ * though the two agree on loaded frames. `authoredByUser` is a per-NODE verdict
91
+ * and can be `undefined` ("no source to read"); this flag is a per-TURN verdict
92
+ * that is always decided, because the roam bar has to say something either way.
93
+ * The evidence differs by where the frame came from:
94
+ * * a LOADED frame reads its node's `source.kind`;
95
+ * * an UNLOADED frame has no node, so its evidence is the outline itself: the
96
+ * projection records a turn's prompt ONLY for a human `user/message`
97
+ * (`session-turn-outline/projection.ts:110` returns early otherwise), so an
98
+ * empty prompt on an unloaded turn means the system started it. That is also
99
+ * why such a frame's text is empty and the bar used to render blank.
100
+ */
101
+ readonly systemInitiated: boolean;
102
+ }
103
+ /** The node shape read off the Chat snapshot; every field is optional because
104
+ * the snapshot is a cross-package value whose discriminant this plugin narrows
105
+ * itself rather than trusting. */
106
+ interface ChatNodeLike {
107
+ readonly kind?: unknown;
108
+ readonly data?: unknown;
109
+ readonly location?: unknown;
110
+ }
111
+ /** How many characters of a message the palette row shows. */
112
+ export declare const FRAME_PREVIEW_LENGTH = 120;
113
+ /** How many characters of an answer the palette row shows. */
114
+ export declare const FRAME_ANSWER_LENGTH = 90;
115
+ /**
116
+ * Collapse whitespace so a multi-line message becomes one readable row.
117
+ * @param text - the raw text.
118
+ * @returns the collapsed text.
119
+ */
120
+ export declare function collapse(text: string): string;
121
+ /**
122
+ * Truncate to a display length, appending an ellipsis when cut.
123
+ * @param text - already-collapsed text.
124
+ * @param limit - maximum characters.
125
+ * @returns the preview.
126
+ */
127
+ export declare function truncate(text: string, limit: number): string;
128
+ /**
129
+ * Read one node's text and whether it carries something a rewrite cannot restore.
130
+ *
131
+ * Only `text` blocks are reused. An `image` or `file` block is deliberately
132
+ * dropped — the composer's draft is a string, so there is nowhere to put it —
133
+ * and its presence is reported instead, so the palette can warn the user that
134
+ * the reuse is text-only rather than silently losing an attachment.
135
+ * @param data - the node's `data` payload.
136
+ * @returns the joined text and the attachment flag.
137
+ */
138
+ export declare function readContent(data: unknown): {
139
+ text: string;
140
+ hasAttachment: boolean;
141
+ };
142
+ /**
143
+ * Read the turn a node belongs to, when it has a resolved one.
144
+ *
145
+ * A node whose location is `unresolved` (typically injected context) has no
146
+ * turn and is not part of the conversation's own history.
147
+ * @param location - the node's `location`.
148
+ * @returns the turn number, or undefined.
149
+ */
150
+ export declare function readTurn(location: unknown): number | undefined;
151
+ /**
152
+ * One entry of the session-wide `turnOutline` projection, structurally narrowed.
153
+ *
154
+ * The value crosses the wire as projection data, so it is treated as untrusted:
155
+ * `turn` and `seq` are load-bearing (a frame cannot be counted or paged without
156
+ * them) and a damaged entry is dropped, while the previews are decorative and
157
+ * degrade to `''`.
158
+ */
159
+ export interface OutlineTurn {
160
+ /** The turn number. */
161
+ readonly turn: number;
162
+ /** The `turn/start` seq — the load-through target that pages this turn in. */
163
+ readonly seq: number;
164
+ /** The turn's first human prompt, as the outline's bounded preview. */
165
+ readonly prompt: string;
166
+ /** The turn's final assistant response, as the outline's bounded preview. */
167
+ readonly response: string;
168
+ }
169
+ /**
170
+ * Structurally narrow the `turnOutline` projection value into outline turns.
171
+ *
172
+ * This is the SAME projection the page's turn ruler renders
173
+ * (`ui-chat/src/client/chat/turn-rail-items.ts`), which is what makes the walk's
174
+ * total agree with the ruler's ticks. It folds the WHOLE log, including turns
175
+ * outside the client's paged event window — the whole reason the readout could
176
+ * say `0 / 0` while the ruler drew many marks is that this plugin only walked
177
+ * the loaded window.
178
+ * @param value - the projection value, treated as wire data.
179
+ * @returns the turns, ascending; a stable empty array when absent or malformed.
180
+ */
181
+ export declare function readOutlineTurns(value: unknown): readonly OutlineTurn[];
182
+ /**
183
+ * Build the reusable frames of one session, oldest first.
184
+ *
185
+ * `user`, `steering` and `assistant-step` nodes become frames. In `'turn'` mode
186
+ * only the first frame of each turn survives and the turn's later interjections
187
+ * and replies are folded away — that is the coarser granularity a user asks for
188
+ * when one stop per exchange is what they want; in the default `'message'` mode
189
+ * every interjection and every reply keeps its own frame, because each one is an
190
+ * independent thing the walk should be able to land on.
191
+ *
192
+ * `outline` extends the list past the loaded window with a frame per turn the
193
+ * window does not hold. Those frames are marked `unloaded` and carry the
194
+ * outline's bounded preview as their text, because the projection deliberately
195
+ * does not ship message bodies. Including them is what keeps the walk's total
196
+ * equal to the page's own turn ruler: without it a session whose window holds no
197
+ * user nodes reads `0 / 0` while the ruler shows a dozen marks, and the walk has
198
+ * nothing to step through.
199
+ * @param order - the Chat snapshot's render order (node keys).
200
+ * @param getNode - reads one node by key.
201
+ * @param mode - the configured frame granularity.
202
+ * @param outline - the `turnOutline` projection value.
203
+ * @returns the frames, oldest first.
204
+ */
205
+ export declare function buildFrames(order: readonly string[], getNode: (key: string) => ChatNodeLike | undefined, mode?: HistoryFrameMode, outline?: unknown): readonly HistoryFrame[];
206
+ /**
207
+ * Whether the log itself records that a human typed this frame's prompt.
208
+ *
209
+ * A-19 splits the two features by what they are FOR. The chord exists so a user
210
+ * can reuse something they WROTE, so a turn nobody typed — one the system started
211
+ * on its own — must not be reachable by it. Roaming exists so a user can READ
212
+ * around a message, so it keeps every frame.
213
+ *
214
+ * The signal is the outer `turnOutline` projection's own rule, not a guess: that
215
+ * unit folds a turn's prompt only when `source.kind === 'user'`
216
+ * (`session-turn-outline/src/projection.ts`), so a system-initiated turn keeps
217
+ * `prompt: ''`. A loaded frame is judged the same way from its node's `source`.
218
+ * @param frame - the frame.
219
+ * @returns whether a human wrote it.
220
+ */
221
+ export declare function isUserAuthored(frame: HistoryFrame): boolean;
222
+ /**
223
+ * The frames the quick chord may reuse: the user-authored ones, oldest first.
224
+ *
225
+ * Filtering happens BEFORE the walk wraps, so the chord's own first/last frame is
226
+ * the first/last thing it can actually reach — a system-initiated turn in the
227
+ * middle must not leave a position the chord can land on but not use.
228
+ * @param frames - every frame of the session, oldest first.
229
+ * @returns the user-authored subset, oldest first.
230
+ */
231
+ export declare function userAuthoredFrames(frames: readonly HistoryFrame[]): readonly HistoryFrame[];
232
+ /**
233
+ * Build a usage counter key that identifies one frame's message.
234
+ * @param frame - the frame.
235
+ * @returns the key.
236
+ */
237
+ export declare function frameKeyOf(frame: HistoryFrame): string;
238
+ export {};