@acryldev/blends-frame 0.0.0-stage → 0.1.6

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.
Files changed (92) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +105 -2
  3. package/cordis.patch.yml +3 -0
  4. package/lib/app-generation.d.ts +38 -0
  5. package/lib/app-generation.js +101 -0
  6. package/lib/app-generation.js.map +1 -0
  7. package/lib/app-plugins.d.ts +145 -0
  8. package/lib/app-reload.d.ts +74 -0
  9. package/lib/app-snapshot.d.ts +40 -0
  10. package/lib/app-urls.d.ts +17 -0
  11. package/lib/applied-live.d.ts +43 -0
  12. package/lib/auto-save.d.ts +63 -0
  13. package/lib/branch-chats.d.ts +37 -0
  14. package/lib/client.js +50401 -0
  15. package/lib/client.js.map +1 -0
  16. package/lib/contract.d.ts +414 -0
  17. package/lib/git-sync.d.ts +52 -0
  18. package/lib/github-connect.d.ts +44 -0
  19. package/lib/graph-contract.d.ts +85 -0
  20. package/lib/graph-inspect.d.ts +16 -0
  21. package/lib/index.d.ts +186 -0
  22. package/lib/index.js +4060 -0
  23. package/lib/index.js.map +1 -0
  24. package/lib/outward-guard.d.ts +45 -0
  25. package/lib/plain.d.ts +26 -0
  26. package/lib/plugin-graph.d.ts +38 -0
  27. package/lib/real-chats.d.ts +42 -0
  28. package/lib/registry.d.ts +73 -0
  29. package/lib/selection-context.d.ts +118 -0
  30. package/lib/tool-call-guard.d.ts +104 -0
  31. package/lib/types/client/AppSection.d.ts +10 -0
  32. package/lib/types/client/BlendsFrame.d.ts +52 -0
  33. package/lib/types/client/FileView.d.ts +8 -0
  34. package/lib/types/client/FilesView.d.ts +17 -0
  35. package/lib/types/client/GitView.d.ts +18 -0
  36. package/lib/types/client/GraphView.d.ts +22 -0
  37. package/lib/types/client/LeftPanel.d.ts +71 -0
  38. package/lib/types/client/NameYourApp.d.ts +10 -0
  39. package/lib/types/client/PluginsSection.d.ts +17 -0
  40. package/lib/types/client/RegistryView.d.ts +11 -0
  41. package/lib/types/client/RemoteSync.d.ts +17 -0
  42. package/lib/types/client/RightPanel.d.ts +45 -0
  43. package/lib/types/client/SelectionChip.d.ts +59 -0
  44. package/lib/types/client/SettingsExpand.d.ts +6 -0
  45. package/lib/types/client/SettingsLauncher.d.ts +9 -0
  46. package/lib/types/client/ShareChooser.d.ts +21 -0
  47. package/lib/types/client/ShortcutsRow.d.ts +15 -0
  48. package/lib/types/client/TerminalView.d.ts +7 -0
  49. package/lib/types/client/TurnSaveFooter.d.ts +18 -0
  50. package/lib/types/client/app-reload.d.ts +28 -0
  51. package/lib/types/client/branch-chats.d.ts +71 -0
  52. package/lib/types/client/branches.d.ts +23 -0
  53. package/lib/types/client/canvas/AppCanvas.d.ts +25 -0
  54. package/lib/types/client/canvas/app-canvas.d.ts +59 -0
  55. package/lib/types/client/canvas/picker.d.ts +27 -0
  56. package/lib/types/client/chat-draft.d.ts +15 -0
  57. package/lib/types/client/chat-saves.d.ts +28 -0
  58. package/lib/types/client/chats.d.ts +182 -0
  59. package/lib/types/client/desktop-app.d.ts +65 -0
  60. package/lib/types/client/feedback.d.ts +21 -0
  61. package/lib/types/client/frame-state.d.ts +34 -0
  62. package/lib/types/client/frame-view.d.ts +35 -0
  63. package/lib/types/client/fuzzy.d.ts +23 -0
  64. package/lib/types/client/git-sync.d.ts +39 -0
  65. package/lib/types/client/graph-api.d.ts +11 -0
  66. package/lib/types/client/graph-canvas.d.ts +63 -0
  67. package/lib/types/client/graph-link.d.ts +21 -0
  68. package/lib/types/client/graph-model.d.ts +23 -0
  69. package/lib/types/client/graph-styles.d.ts +3 -0
  70. package/lib/types/client/highlight.d.ts +15 -0
  71. package/lib/types/client/index.d.ts +23 -0
  72. package/lib/types/client/panel-resize.d.ts +29 -0
  73. package/lib/types/client/plain-failure.d.ts +10 -0
  74. package/lib/types/client/plugins-navigator.d.ts +81 -0
  75. package/lib/types/client/registry-api.d.ts +21 -0
  76. package/lib/types/client/registry-list.d.ts +18 -0
  77. package/lib/types/client/selection.d.ts +56 -0
  78. package/lib/types/client/settings-fullscreen.d.ts +13 -0
  79. package/lib/types/client/sidebar-opens.d.ts +36 -0
  80. package/lib/types/client/snapshot.d.ts +11 -0
  81. package/lib/types/client/styles.d.ts +3 -0
  82. package/lib/types/client/switch-request.d.ts +18 -0
  83. package/lib/types/client/tab-sizing.d.ts +31 -0
  84. package/lib/types/client/tabs.d.ts +139 -0
  85. package/lib/types/client/theme-switch.d.ts +27 -0
  86. package/lib/types/client/tools.d.ts +15 -0
  87. package/lib/types/client/versions.d.ts +34 -0
  88. package/lib/types/client/view-state.d.ts +42 -0
  89. package/lib/types/contract.d.ts +414 -0
  90. package/lib/types/graph-contract.d.ts +85 -0
  91. package/lib/types/graph-inspect.d.ts +16 -0
  92. package/package.json +126 -4
@@ -0,0 +1,71 @@
1
+ /** The left panel: the app's branches, each with what is open on it, then the versions of the checked-out branch, and where the app runs. */
2
+ import { type FeedbackNoteView, type FrameState } from '../contract.ts';
3
+ import { type FrameTabs } from './tabs.ts';
4
+ import { type VersionsPort } from './versions.ts';
5
+ import { type BranchesApi } from './branches.ts';
6
+ import type { BranchChatsPort } from './branch-chats.ts';
7
+ import type { SwitchRequests } from './switch-request.ts';
8
+ import type { GitSyncPort } from './git-sync.ts';
9
+ import { type FeedbackApi } from './feedback.ts';
10
+ /** A chat on the branch, as the left panel lists it. */
11
+ export interface ChatRow {
12
+ readonly id: string;
13
+ readonly title: string;
14
+ readonly current: boolean;
15
+ /** When the chat last changed (ms since the epoch); absent when DSH did not say. */
16
+ readonly updatedAt?: number;
17
+ }
18
+ /** The chats the frame knows (DSH's sessions), and opening one in the right panel. */
19
+ export interface ChatsPort {
20
+ getSnapshot(): readonly ChatRow[];
21
+ subscribe(listener: () => void): () => void;
22
+ open(id: string): void;
23
+ /** A new chat on the checked-out branch, shown at once; undefined without DSH's sessions service. */
24
+ create(): Promise<string | undefined>;
25
+ /** "+ then Chat": a chat of its own on the checked-out branch (the one on screen is reused while it has no turn). */
26
+ startChat(): Promise<{
27
+ readonly id: string;
28
+ readonly made: boolean;
29
+ } | undefined>;
30
+ /** Show the checked-out branch's chat for the base tab: its newest open chat that has no tab of its own, else a new one. */
31
+ openPrimary(exclude: ReadonlySet<string>): void;
32
+ /** Open a chat of the checked-out branch from History: a closed chat becomes open, as a tab of its own, and is shown. */
33
+ show(id: string): void;
34
+ /** Close a chat (its tab's x); when it is on screen the view moves to `prefer`, else to the base tab's chat, else to a new chat. */
35
+ closeChat(id: string, tabbed: ReadonlySet<string>, prefer?: string): void;
36
+ }
37
+ /** Feedback from users: the notes, and handing one to an agent (the chat's composer). */
38
+ export interface FeedbackPort {
39
+ readonly api: FeedbackApi;
40
+ /** @returns false when there is no chat to hand it to. */
41
+ hand(note: FeedbackNoteView): Promise<boolean>;
42
+ }
43
+ /** The left panel's branch calls: New, and moving to an existing branch with the state re-read and the app page reloaded. */
44
+ export interface BranchesPort {
45
+ readonly api: BranchesApi;
46
+ readonly changed: () => Promise<void>;
47
+ /** Switch the app's folder to a branch, read the frame state again and reload the app page; rejects with the Host's reason. */
48
+ readonly switchTo: (name: string) => Promise<void>;
49
+ }
50
+ export interface LeftPanelProps {
51
+ readonly state: FrameState;
52
+ /** Read the frame state now (the unsaved count may have changed since the last poll); undefined when the Host could not be read. */
53
+ readonly readState: () => Promise<FrameState | undefined>;
54
+ readonly chats: ChatsPort;
55
+ readonly versions: VersionsPort;
56
+ /** The right panel's tabs: the branch lists its open agents and terminals, and a click shows one. */
57
+ readonly tabs: FrameTabs;
58
+ readonly feedback: FeedbackPort;
59
+ readonly branches: BranchesPort;
60
+ /** Which branch each chat was opened on (DSH keeps none; the Host records it). */
61
+ readonly branchChats: BranchChatsPort;
62
+ /** A chat of another branch asked for from the chat's History: the switch is offered here, with the same guard as a click on the panel's own rows. */
63
+ readonly switchRequests: SwitchRequests;
64
+ /** Show a right panel tab (opening the panel when it is closed). */
65
+ readonly showTab: (id: string) => void;
66
+ /** Told the newest version's label ("v7"), for the top bar. */
67
+ readonly onVersionLabel: (label: string | undefined) => void;
68
+ /** The branch's remote: the versions header's ↑/↓ chips send the versions there and bring its new ones in (the Git tab's Push and Pull). */
69
+ readonly gitSync: GitSyncPort;
70
+ }
71
+ export declare function LeftPanel({ state, readState, chats, versions, tabs, feedback, branches, branchChats, switchRequests, showTab, onVersionLabel, gitSync }: LeftPanelProps): import("react").JSX.Element;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * The first start of a desktop product asks one thing, in the app's own window: "Name your app" (app-storage.md, "What the person sees"). The product's
3
+ * name for its starting app is offered and selected, so Enter keeps it and typing replaces it. Once the person answers, the app is named and this never
4
+ * shows again; Settings > App renames it later. Drawn in the frame's overlay, over the frame, in the look of its Settings dialog.
5
+ */
6
+ import type { DesktopApp } from './desktop-app.ts';
7
+ export interface NameYourAppInjected {
8
+ readonly app: DesktopApp;
9
+ }
10
+ export declare function NameYourApp({ app }: NameYourAppInjected): import("react").JSX.Element | null;
@@ -0,0 +1,17 @@
1
+ /** The Plugins page of Settings: search, the groups as chips, and one row per plugin with who made it, its state and its switch. */
2
+ import { type GraphViewInjected } from './GraphView.tsx';
3
+ import { type NavigatorPlugin } from './plugins-navigator.ts';
4
+ import type { RegistryApi } from './registry-api.ts';
5
+ export interface PluginsSectionInjected {
6
+ /** Every plugin of the app and the frame, read fresh. */
7
+ readonly loadPlugins: () => Promise<readonly NavigatorPlugin[]>;
8
+ /** What the Graph view reads and does; absent, the page has no Graph tab. */
9
+ readonly graph?: GraphViewInjected;
10
+ /** The public registry, adding a plugin from it, and whether this computer can share to GitHub. */
11
+ readonly registry: RegistryApi;
12
+ }
13
+ /** What the Settings shell hands a section: `close` leaves Settings (View source shows the file in the frame, behind the dialog). */
14
+ export interface PluginsSectionOwner {
15
+ readonly close?: () => void;
16
+ }
17
+ export declare function PluginsSection({ loadPlugins, graph, registry, close }: PluginsSectionInjected & PluginsSectionOwner): import("react").JSX.Element;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * The Registry tab of Settings > Plugins: the public Cordis plugin registry, searchable, with one button to add a plugin to this app. Plain words;
3
+ * the address, compatibility and the tool's own messages are behind "Details". Nothing is added without the person's yes (the question names whose code it is).
4
+ */
5
+ import type { RegistryApi } from './registry-api.ts';
6
+ export interface RegistryViewProps {
7
+ readonly api: RegistryApi;
8
+ /** The app's plugin list changed (a plugin was added): read it again. */
9
+ readonly onAdded: () => void;
10
+ }
11
+ export declare function RegistryView({ api, onAdded }: RegistryViewProps): import("react").JSX.Element;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The branch against its remote, with Pull and Push and the line the last one said. Two faces on one hook: the Git tab's remote row, and the
3
+ * compact chips on the left panel's versions header (`↑2` / `↓1` / `✓`, with the line as a brief toast). Read again whenever `revision` changes;
4
+ * the first read asks the remote (a fetch), later ones read the local refs, and each push or pull asks it anyway. A push sends the person's
5
+ * versions under their name, so Push first asks what it will send and where ("Push 2 versions to origin/main (github.com/ana/notes)?"), with
6
+ * Cancel as the default, and sends only that.
7
+ */
8
+ import { type GitSyncPort } from './git-sync.ts';
9
+ export interface RemoteSyncProps {
10
+ readonly sync: GitSyncPort;
11
+ readonly root: string;
12
+ readonly revision: string;
13
+ }
14
+ /** The Git tab's row. */
15
+ export declare function RemoteSync({ sync, root, revision }: RemoteSyncProps): import("react").JSX.Element;
16
+ /** The versions header's chips; nothing when the branch has no remote. */
17
+ export declare function RemoteChips({ sync, root, revision }: RemoteSyncProps): import("react").JSX.Element;
@@ -0,0 +1,45 @@
1
+ /**
2
+ * The right panel (docs/design/blends-frame-mockup.html): everything the person works with, as tabs opened with +. Agents: the chat (DSH's
3
+ * conversation with the model the person connected) and Claude Code, Codex or Pi as they are, TUIs in a PTY. Tools: a terminal, Files (fuzzy
4
+ * search, a file opens as its own tab) and Git. There is no Browser: the canvas is the browser. The chat has History at its top left.
5
+ */
6
+ import { type ReactNode } from 'react';
7
+ import type { FrameState } from '../contract.ts';
8
+ import type { ChatsPort } from './LeftPanel.tsx';
9
+ import { type BranchChatsPort } from './branch-chats.ts';
10
+ import type { SwitchRequests } from './switch-request.ts';
11
+ import { type FrameTabs } from './tabs.ts';
12
+ import type { FrameTools } from './tools.ts';
13
+ import { type VersionsPort } from './versions.ts';
14
+ import type { GitSyncPort } from './git-sync.ts';
15
+ export interface RightPanelProps {
16
+ readonly chats: ChatsPort;
17
+ readonly tabs: FrameTabs;
18
+ readonly tools: FrameTools;
19
+ readonly versions: VersionsPort;
20
+ readonly gitSync: GitSyncPort;
21
+ readonly state: FrameState | undefined;
22
+ /** Which branch each chat was opened on, for the history's rows. */
23
+ readonly branchChats: BranchChatsPort;
24
+ /** Where a chat of another branch is asked for: the left panel offers the switch first. */
25
+ readonly switchRequests: SwitchRequests;
26
+ readonly renderConversation: () => ReactNode;
27
+ /** DSH's right sidebar (the `rightbar` slot) at the given width. Always mounted, so DSH's panel is there to open; shown only on its tab. */
28
+ readonly renderDetails: (width: number) => ReactNode;
29
+ /** Whether DSH's right sidebar is open, as it reports through the layout; it opens and closes its tab here. */
30
+ readonly details: {
31
+ subscribe(listener: () => void): () => void;
32
+ getSnapshot(): boolean;
33
+ };
34
+ readonly sidebar: SidebarPort;
35
+ }
36
+ /** DSH's right sidebar as the Panel tab drives it. */
37
+ export interface SidebarPort {
38
+ /** Collapse it (DSH's own collapse), when the person closes its tab. */
39
+ close(): void;
40
+ /** Expand it (DSH's own expand), when the person picks its tab. */
41
+ expand(): void;
42
+ /** Hear each page opened in it. @returns the disposer. */
43
+ onOpened(listener: () => void): () => void;
44
+ }
45
+ export declare function RightPanel({ chats, tabs, tools, versions, gitSync, state, branchChats, switchRequests, renderConversation, renderDetails, details, sidebar }: RightPanelProps): import("react").JSX.Element;
@@ -0,0 +1,59 @@
1
+ /**
2
+ * The chip inside the chat composer for the element picked in the app (docs/design/blends-frame-mockup.html, scenario 2): "Selected: ..." at the
3
+ * left of the input row, the person's placeholder after it. DSH has no slot on the input row itself, so the chip rides its `conversation.input.overlay`
4
+ * seat inside the composer card, and the frame moves the editor and its placeholder right by the chip's width while the pick is there. The context
5
+ * reaches the agent on the next message through the send hook, which writes the element's page and selector into the draft at the moment the
6
+ * composer sends, so the person's own text stays exactly as they typed it.
7
+ */
8
+ import type { SelectedElement } from './selection.ts';
9
+ export interface SelectionChipInjected {
10
+ readonly selection: {
11
+ get(): SelectedElement | undefined;
12
+ subscribe(listener: () => void): () => void;
13
+ };
14
+ clear(): void;
15
+ /** Hand the pick to the frame's Host just before the person's own send; the message itself is sent untouched. */
16
+ send(): void;
17
+ /** Return the keyboard to the composer, the way the frame's feedback hand-off does. */
18
+ focus(): void;
19
+ }
20
+ export type SelectionChipProps = SelectionChipInjected;
21
+ /** The mockup's gap between the chip and the input text. */
22
+ export declare const CHIP_GAP = 8;
23
+ /** The custom property the editor carries while a chip is shown: the first line's indent (./styles.ts reads it). */
24
+ export declare const CHIP_INSET_PROPERTY = "--acrylBlendsChipInset";
25
+ /** Where the chip sits inside the composer card, and how far the draft's text moves right to make room for it. */
26
+ export interface ChipGeometry {
27
+ /** The chip's left, in the overlay anchor's coordinates. */
28
+ readonly left: number;
29
+ /** The chip's top, in the overlay anchor's coordinates. */
30
+ readonly top: number;
31
+ /** The editor's and placeholder's left inset while the chip is shown. */
32
+ readonly textInset: number;
33
+ }
34
+ /**
35
+ * The chip's box and the draft's inset for one layout.
36
+ * @param editor - the contenteditable's box, in viewport coordinates.
37
+ * @param anchor - the composer's overlay anchor (the chip's containing block), in viewport coordinates.
38
+ * @param chip - the chip's size.
39
+ * @param lineHeight - the editor's line height.
40
+ * @param paddingLeft - the editor's left pad before the chip.
41
+ * @param paddingTop - the editor's top pad before the chip.
42
+ * @returns the chip's position and the draft's new left inset; the chip is vertically centered on the first line.
43
+ */
44
+ export declare function chipGeometry(editor: {
45
+ readonly left: number;
46
+ readonly top: number;
47
+ }, anchor: {
48
+ readonly left: number;
49
+ readonly top: number;
50
+ }, chip: {
51
+ readonly width: number;
52
+ readonly height: number;
53
+ }, lineHeight: number, paddingLeft: number, paddingTop: number): ChipGeometry;
54
+ /**
55
+ * Whether one DOM event is a send gesture of the chat composer. Only the composer card counts, so the rest of the page keeps its own keys
56
+ * and clicks; an open trigger menu owns Enter because the person is picking a reference or a command, not sending.
57
+ */
58
+ export declare function isSendGesture(event: Event): boolean;
59
+ export declare function SelectionChip({ selection, clear, send, focus }: SelectionChipProps): import("react").JSX.Element | null;
@@ -0,0 +1,6 @@
1
+ /**
2
+ * The expand button in DSH's Settings header (its `settings.action` list, next to "Open configuration file" and the close button): the window fills the
3
+ * browser window, and a second click, a double click on the header, or Esc brings it back. The choice is remembered by the browser. While the Graph is
4
+ * full screen on top, Esc leaves the Graph first (its handler runs before this one).
5
+ */
6
+ export declare function SettingsExpand(): import("react").JSX.Element;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * The top bar's gear. DSH's Settings (`dsh-client-ui-settings-general`) is a modal that renders inside its own `sidebar.settings` slot, opened by
3
+ * whatever fills that slot's `settings.launcher`; the frame renders the slot in its top bar and fills the launcher with this gear, so the gear opens
4
+ * DSH's real Settings and nothing else. The Desktop's Settings... menu item reaches the same launcher through a window event.
5
+ */
6
+ import type { PropsRuntime } from '@acryldev/ui/frame';
7
+ /** The window event the Desktop's Settings... menu item sends (`plugins/desktop/frame.ts`, `openFrameSettings`); keep the string in step. */
8
+ export declare const OPEN_SETTINGS_EVENT = "acryl:open-settings";
9
+ export declare function SettingsLauncher({ settingsOpen, openSettings, settingsShortcut }: PropsRuntime<'settings.launcher'>): import("react").JSX.Element;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Share a plugin, in plain words: four places it can go (this computer, my GitHub privately, my GitHub publicly, the public registry), one question before
3
+ * anything is sent with Cancel as the default, and a short answer after. Git, repositories, licenses and topics are behind a "Details" toggle.
4
+ * It owns only what the person is looking at; the sharing itself is `plugin.share`, the packed copy `plugin.actions.save`, both from the Host.
5
+ */
6
+ import type { GithubReadiness, SavedPluginResult, SharedPluginView } from '../contract.ts';
7
+ import { type NavigatorPlugin } from './plugins-navigator.ts';
8
+ import type { GithubConnectApi } from './registry-api.ts';
9
+ export interface ShareChooserProps {
10
+ readonly plugin: NavigatorPlugin;
11
+ /** Whether this computer can share to GitHub; read once when the chooser opens. */
12
+ readonly readGithub: () => Promise<GithubReadiness>;
13
+ /** Connect GitHub from here (GitHub's browser sign-in); without it the note shows the Terminal command only. */
14
+ readonly connectGithub?: GithubConnectApi;
15
+ /** Copy a text; false when the browser refuses. */
16
+ readonly copy: (text: string) => Promise<boolean>;
17
+ readonly onSaved: (saved: SavedPluginResult) => void;
18
+ readonly onShared: (shared: SharedPluginView) => void;
19
+ readonly onClose: () => void;
20
+ }
21
+ export declare function ShareChooser({ plugin, readGithub, connectGithub, copy, onSaved, onShared, onClose }: ShareChooserProps): import("react").JSX.Element;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Settings > General's short list of shortcuts (docs/design/blends-frame-mockup.html: "General, with a short list of shortcuts"): the keys that are
3
+ * set, read from DSH's shortcut service, and the frame's own Find a file. Changing a key is DSH's "Edit shortcuts" dialog; the IDE's full Shortcuts
4
+ * section is not part of the frame.
5
+ */
6
+ import type { ShortcutCatalogEntry, Shortcuts } from '@acryldev/ui/frame';
7
+ export interface ShortcutsRowInjected {
8
+ readonly shortcuts: Shortcuts;
9
+ }
10
+ export declare function shortcutList(catalog: readonly ShortcutCatalogEntry[]): {
11
+ readonly id: string;
12
+ readonly label: string;
13
+ readonly keys: readonly string[];
14
+ }[];
15
+ export declare function ShortcutsRow({ shortcuts }: ShortcutsRowInjected): import("react").JSX.Element;
@@ -0,0 +1,7 @@
1
+ /** A terminal or PTY agent tab's screen: the live session moved into the panel while the tab is shown, moved out (not ended) when it is not. */
2
+ import type { TerminalRegistry } from '@acryldev/workspace/ui';
3
+ export interface TerminalViewProps {
4
+ readonly terminals: TerminalRegistry;
5
+ readonly terminalId: string;
6
+ }
7
+ export declare function TerminalView({ terminals, terminalId }: TerminalViewProps): import("react").JSX.Element;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * The line under a chat answer that changed the app: "edited src/routes.ts, src/board.ts · saved as v7" (docs/design/blends-frame-mockup.html,
3
+ * scenario 2). DSH draws it in the `conversation.chat.turnTail` slot, before the answer's action row, once per completed turn.
4
+ */
5
+ import { ChatSavesStore } from './chat-saves.ts';
6
+ /** The turn as the slot hands it over: the number the Host saved it under, and whether it has ended. */
7
+ export interface TurnSaveFooterProps {
8
+ readonly sessionId: string;
9
+ readonly turn: {
10
+ readonly turn: number;
11
+ readonly status: 'open' | 'closed' | 'unknown';
12
+ readonly end?: {
13
+ readonly time?: number;
14
+ };
15
+ };
16
+ readonly chatSaves: ChatSavesStore;
17
+ }
18
+ export declare function TurnSaveFooter({ sessionId, turn, chatSaves }: TurnSaveFooterProps): import("react").JSX.Element | null;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * The app's code, as the Host runs it (`../app-reload.ts`): the page asks the Host to answer when it changes and reloads the canvas when a new
3
+ * generation of the app is up, so a version gone back to, a file the chat wrote or a line typed in an editor shows without a click. The ask is held by the
4
+ * Host until something changes (a long poll), so there is no timer to wait on. A load the Host refused (a syntax error) leaves the canvas as it is and
5
+ * is kept here for the bar to say.
6
+ */
7
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
8
+ /** What the bar shows: why the app was not loaded again, or nothing. */
9
+ export interface AppReloadSnapshot {
10
+ readonly error: string | undefined;
11
+ }
12
+ export declare class AppReloadStore {
13
+ /** Called when the app's code was loaded again: the canvas reloads. */
14
+ private readonly onReloaded;
15
+ private readonly fetchImpl;
16
+ private readonly delay;
17
+ private snapshot;
18
+ private readonly listeners;
19
+ constructor(
20
+ /** Called when the app's code was loaded again: the canvas reloads. */
21
+ onReloaded: () => void, fetchImpl?: FetchLike, delay?: (ms: number, signal: AbortSignal) => Promise<void>);
22
+ getSnapshot(): AppReloadSnapshot;
23
+ subscribe(listener: () => void): () => void;
24
+ /** Follow the Host until `signal` aborts: the first answer says where the app is, each later one is a change. */
25
+ run(signal: AbortSignal): Promise<void>;
26
+ private setError;
27
+ }
28
+ export {};
@@ -0,0 +1,71 @@
1
+ /**
2
+ * Which branch each chat belongs to, and which chats are open, as the Host remembers them, and the frame's copy: the one source of truth for both.
3
+ * DSH knows no branches. A chat is recorded once - when the frame makes it, or when it is first seen with a turn - and never moved by a later switch.
4
+ * A chat is open while it has a tab or is on screen; the left panel lists only the open ones and the rest wait in the chat's History.
5
+ */
6
+ import { type BranchChatsView } from '../contract.ts';
7
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
8
+ export interface BranchChatsApi {
9
+ /** The recorded map and open chats. @throws when the Host does not answer it. */
10
+ read(): Promise<BranchChatsView>;
11
+ /** Record a chat's branch. @throws when the Host refuses it (the caller tries again later). */
12
+ assign(id: string, branch: string): Promise<void>;
13
+ /** Open or close one chat. @throws when the Host refuses it. */
14
+ setOpen(id: string, open: boolean): Promise<void>;
15
+ /** Decide which chats are open, when the Host has no decision yet. @throws when the Host refuses it. */
16
+ initOpen(ids: readonly string[]): Promise<void>;
17
+ }
18
+ export declare function createBranchChatsApi(fetcher?: FetchLike): BranchChatsApi;
19
+ /** The map as the panels read it: a chat id to the branch it was opened on, and the chats that are open. */
20
+ export interface BranchChatsPort {
21
+ getSnapshot(): Readonly<Record<string, string>>;
22
+ /** The chats that are open; empty until the Host's decision is known (`isOpenKnown`). */
23
+ getOpen(): ReadonlySet<string>;
24
+ /** Whether the open chats are decided; until then every chat counts as open. */
25
+ isOpenKnown(): boolean;
26
+ subscribe(listener: () => void): () => void;
27
+ }
28
+ export declare class BranchChatsStore implements BranchChatsPort {
29
+ private readonly api;
30
+ private chats;
31
+ /** The open chats; undefined until the Host's list is read, and while the Host has none (nobody decided yet). */
32
+ private open;
33
+ private readonly pending;
34
+ private readonly listeners;
35
+ private loaded;
36
+ constructor(api: BranchChatsApi);
37
+ getSnapshot(): Readonly<Record<string, string>>;
38
+ getOpen(): ReadonlySet<string>;
39
+ /** Whether the open chats are decided (by the Host's record, or by `initOpen`): until then the frame lists and opens nothing by it. */
40
+ isOpenKnown(): boolean;
41
+ isOpen(id: string): boolean;
42
+ subscribe(listener: () => void): () => void;
43
+ /** Whether the Host's map has been read: until then a chat that looks unrecorded may only be one the frame has not heard about. */
44
+ isLoaded(): boolean;
45
+ /** Read what the Host remembers; a failed read keeps the map the frame has and is tried again by the next call. */
46
+ load(): Promise<void>;
47
+ /**
48
+ * Put every chat that is not recorded yet on `branch`, the checked-out one when it was first seen. The map shows the assignment at once (the
49
+ * panel lists the chat under its branch while the Host write runs); a refused write is dropped so the next look tries again.
50
+ */
51
+ adopt(ids: readonly string[], branch: string): void;
52
+ /**
53
+ * Decide which chats are open, when the Host has no decision (and this page none): the set shows at once and is written once. A set already
54
+ * known is kept, so a second page or a second call changes nothing.
55
+ */
56
+ initOpen(ids: readonly string[]): void;
57
+ /** Open or close one chat: shown at once, written to the Host; a write the Host refuses puts the chat back as it was. */
58
+ setOpen(id: string, open: boolean): void;
59
+ private publish;
60
+ }
61
+ /**
62
+ * Chat history as the History list shows it (mockup scenario 5): one group per branch, the checked-out branch first and the others by name,
63
+ * each keeping the rows' own order; a chat no branch was recorded for yet comes last, under no name.
64
+ */
65
+ export declare function historyGroups<Row extends {
66
+ readonly id: string;
67
+ }>(rows: readonly Row[], assignments: Readonly<Record<string, string>>, checkedOut: string | undefined): {
68
+ readonly branch: string | undefined;
69
+ readonly rows: readonly Row[];
70
+ }[];
71
+ export {};
@@ -0,0 +1,23 @@
1
+ /**
2
+ * The left panel's branch calls to the Host - a new branch ("New"), and moving to an existing one - and what a click on a branch row means.
3
+ * A switch never throws the person's work away: with unsaved files the panel asks first and offers a save point.
4
+ */
5
+ import { type FrameBranch } from '../contract.ts';
6
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
7
+ export interface BranchesApi {
8
+ /** Rejects with the Host's reason (a taken name, a name git refuses). */
9
+ create(name: string): Promise<void>;
10
+ /** Move the app's folder to an existing local branch. Rejects with the Host's reason (git's own line). */
11
+ switchTo(name: string): Promise<void>;
12
+ }
13
+ /** What a click on a branch row does. */
14
+ export type BranchClick = 'toggle' | 'switch' | 'ask';
15
+ /**
16
+ * The current branch opens or closes what is running on it; another branch is switched to, and with unsaved files the person is asked first
17
+ * (save a point, or cancel). Only a state that says zero unsaved files switches at once: a state that could not count them asks.
18
+ */
19
+ export declare function branchClick(branch: FrameBranch, unsaved: number | undefined): BranchClick;
20
+ /** The version's subject when a switch saves the person's work first. */
21
+ export declare function saveBeforeSwitchMessage(name: string): string;
22
+ export declare function createBranchesApi(fetcher?: FetchLike): BranchesApi;
23
+ export {};
@@ -0,0 +1,25 @@
1
+ /** The centre: the app's own page in one frame. A navigation or a reload mounts a NEW frame; a frame is never re-pointed (section 30). */
2
+ import type { SelectedElement } from '../selection.ts';
3
+ import type { AppCanvasState } from './app-canvas.ts';
4
+ export interface AppCanvasProps {
5
+ readonly canvas: AppCanvasState;
6
+ /** The frame's select control is on: clicks in the app pick an element instead of acting on the app. */
7
+ readonly picking?: boolean;
8
+ /** One element was picked. */
9
+ readonly onPick?: (element: SelectedElement) => void;
10
+ /** Escape left the picker. */
11
+ readonly onCancel?: () => void;
12
+ /** The pick belongs to a page the canvas no longer shows: the frame lets the selection go with it. */
13
+ readonly onStaleSelection?: () => void;
14
+ /** The element the chat has selected: outlined while it is on the page shown. */
15
+ readonly selected?: SelectedElement | undefined;
16
+ }
17
+ /** The page a loaded app document shows; undefined while the frame is still the browser's initial about:blank. */
18
+ export declare function appPage(doc: {
19
+ readonly location: {
20
+ readonly href: string;
21
+ readonly pathname: string;
22
+ readonly search: string;
23
+ };
24
+ }): string | undefined;
25
+ export declare function AppCanvas({ canvas, picking, onPick, onCancel, onStaleSelection, selected }: AppCanvasProps): import("react").JSX.Element | null;
@@ -0,0 +1,59 @@
1
+ /**
2
+ * The app page the canvas shows, and the calls a person or the agent may make on it (docs/plans/ide-host-inversion.md section 31, boundary A).
3
+ *
4
+ * The canvas is a value, not a surface: the React component renders whatever this state says, and a navigation or a reload is a new address or a
5
+ * new attempt, which makes a NEW frame. A frame is never re-pointed at another address - that is what let a late load from an earlier address pass
6
+ * for this one's answer and replace a live app page (section 30) - and nothing here reloads on its own: only `navigate` and `reload`, which only a
7
+ * person or the door calls.
8
+ */
9
+ /** The key the door publishes `{ windowId }` on the page's window (plugins/acryl-door/src/page/index.ts, `PAGE_KEY`). */
10
+ export declare const DOOR_PAGE_KEY: symbol;
11
+ export interface AppCanvasView {
12
+ /** The absolute address of the app's own page, or undefined when the Host serves none. */
13
+ readonly address: string | undefined;
14
+ /** How many reloads were asked for; each mounts a fresh frame at the same address. */
15
+ readonly attempt: number;
16
+ /** The last load the component saw, with whether the document was readable (a same-origin app page always is). */
17
+ readonly loaded: {
18
+ readonly address: string;
19
+ readonly readable: boolean;
20
+ } | undefined;
21
+ }
22
+ export interface AppCanvas {
23
+ /** The address the canvas shows, absolute; undefined when the Host serves no app. */
24
+ address(): string | undefined;
25
+ /** Point the canvas at a path on the frame's origin. Called by a person or the door, never by the frame itself. */
26
+ navigate(path: string): void;
27
+ /** Reload the app page. Called by a person or the door. */
28
+ reload(): void;
29
+ /** Called after every change of address, attempt or load. */
30
+ subscribe(listener: () => void): () => void;
31
+ /** The door's page window id of the canvas page, when its script has published one. */
32
+ pageWindow(): string | undefined;
33
+ }
34
+ /** The canvas as the frame renders it; one instance per client plugin lifetime. */
35
+ export declare class AppCanvasState implements AppCanvas {
36
+ private addressValue;
37
+ private attemptValue;
38
+ private loadedValue;
39
+ private frame;
40
+ private snapshot;
41
+ private readonly listeners;
42
+ /** Set once, from the Host's answer: the app's own page. */
43
+ setAddress(address: string | undefined): void;
44
+ address(): string | undefined;
45
+ navigate(path: string): void;
46
+ reload(): void;
47
+ attempt(): number;
48
+ /** The component hands its frame over, so `pageWindow` reads the live page. */
49
+ attach(frame: HTMLIFrameElement | null): void;
50
+ /** The component reports a load; subscribers see the address it was for. */
51
+ reportLoad(address: string, readable: boolean): void;
52
+ pageWindow(): string | undefined;
53
+ /** The live app page's window, when the canvas has one: the frame's view contract reaches the page through it. */
54
+ contentWindow(): Window | undefined;
55
+ /** The identity `useSyncExternalStore` compares. */
56
+ getSnapshot(): AppCanvasView;
57
+ subscribe(listener: () => void): () => void;
58
+ private emit;
59
+ }
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The frame's element picker over the app canvas (docs/design/blends-frame-mockup.html, scenario 2). The app's page is same-origin under
3
+ * `/app`, so the frame reads and decorates the app's own document: the element under the pointer is outlined, a click picks it and does
4
+ * nothing else, and Escape leaves the picker.
5
+ */
6
+ import { type SelectedElement } from '../selection.ts';
7
+ export interface CanvasPickerHandlers {
8
+ /** One element was clicked while picking. */
9
+ onPick(element: SelectedElement): void;
10
+ /** Escape left the picker; the frame turns its select control off. */
11
+ onCancel(): void;
12
+ }
13
+ /**
14
+ * Attach the picker to one app document.
15
+ * @param doc - the app page's document, same-origin with the frame.
16
+ * @param handlers - what a click and Escape mean to the frame.
17
+ * @returns a disposer that removes every listener and the outline, and restores the app's cursor.
18
+ */
19
+ export declare function attachPicker(doc: Document, handlers: CanvasPickerHandlers): () => void;
20
+ /**
21
+ * Mark the element the chat has selected (scenario 2: the picked card stays outlined while it is the selection). The mark follows the element as the
22
+ * page scrolls or resizes, and is gone when the element is.
23
+ * @param doc - the app page's document.
24
+ * @param selector - the selection's selector ({@link SelectedElement.selector}).
25
+ * @returns a disposer that removes the mark and its listeners.
26
+ */
27
+ export declare function markSelected(doc: Document, selector: string): () => void;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Writing into the chat's composer: DSH's conversation input for a session (`conversation.input.for(scope).setDraft`), the same seam
3
+ * `@acryl/ui`'s `acrylChat.notice` uses. The services are read at the call and checked, so a page without a chat answers false.
4
+ */
5
+ import type { Context } from '@deepseek-ai/cordis';
6
+ /** Put `text` in the composer of chat `sessionId` and focus it. @returns false when this page holds no composer for that chat. */
7
+ export declare function draftInChat(ctx: Context, sessionId: string, text: string): boolean;
8
+ /**
9
+ * Attach one browser file to a chat's composer as DSH's own draft attachment, so the composer shows it and sending includes it.
10
+ * @param ctx - the frame's client context.
11
+ * @param sessionId - the chat to attach it to.
12
+ * @param file - the browser file (an image keeps its type and bytes for the model).
13
+ * @returns false when the page holds no attachment intake or no composer for that chat.
14
+ */
15
+ export declare function attachDraft(ctx: Context, sessionId: string, file: File): boolean;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * What each chat turn saved (the Host's auto-save, `../auto-save.ts`): the line under an answer, "edited src/routes.ts, src/board.ts · saved as v7".
3
+ * The Host makes the version a moment after the turn ends, so a turn that has just closed asks again a few times before it concludes there was none.
4
+ */
5
+ import { type TurnSaveView } from '../contract.ts';
6
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
7
+ export interface ChatSavesApi {
8
+ read(session: string): Promise<readonly TurnSaveView[]>;
9
+ }
10
+ export declare function createChatSavesApi(fetcher?: FetchLike): ChatSavesApi;
11
+ /** "edited src/routes.ts, src/board.ts · saved as v7". */
12
+ export declare function saveLine(save: Pick<TurnSaveView, 'files' | 'version'>): string;
13
+ /** When a closed turn with no save yet asks again, after these many milliseconds each: the version lands a moment after the turn's last event. */
14
+ export declare const SAVE_RETRY_MS: readonly number[];
15
+ export declare class ChatSavesStore {
16
+ private readonly api;
17
+ private readonly onSaved;
18
+ private readonly saves;
19
+ private readonly asked;
20
+ private readonly listeners;
21
+ /** `onSaved` is told when a read brings a save the page had not seen: the versions and the unsaved count have changed with it. */
22
+ constructor(api: ChatSavesApi, onSaved?: () => void);
23
+ getSnapshot(session: string): readonly TurnSaveView[];
24
+ subscribe(listener: () => void): () => void;
25
+ /** Read the chat's saves; reads that overlap share one request. A failed read keeps what was shown. */
26
+ refresh(session: string): Promise<void>;
27
+ }
28
+ export {};