@acrylblends/blends-frame 0.0.0-stage → 0.1.1

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 (67) 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 +102 -0
  6. package/lib/app-generation.js.map +1 -0
  7. package/lib/app-plugins.d.ts +118 -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 +18899 -0
  15. package/lib/client.js.map +1 -0
  16. package/lib/contract.d.ts +293 -0
  17. package/lib/git-sync.d.ts +52 -0
  18. package/lib/index.d.ts +169 -0
  19. package/lib/index.js +3064 -0
  20. package/lib/index.js.map +1 -0
  21. package/lib/outward-guard.d.ts +45 -0
  22. package/lib/real-chats.d.ts +42 -0
  23. package/lib/selection-context.d.ts +118 -0
  24. package/lib/tool-call-guard.d.ts +104 -0
  25. package/lib/types/client/BlendsFrame.d.ts +46 -0
  26. package/lib/types/client/FileView.d.ts +8 -0
  27. package/lib/types/client/FilesView.d.ts +17 -0
  28. package/lib/types/client/GitView.d.ts +18 -0
  29. package/lib/types/client/LeftPanel.d.ts +71 -0
  30. package/lib/types/client/PluginsSection.d.ts +7 -0
  31. package/lib/types/client/RemoteSync.d.ts +17 -0
  32. package/lib/types/client/RightPanel.d.ts +45 -0
  33. package/lib/types/client/SelectionChip.d.ts +59 -0
  34. package/lib/types/client/SettingsLauncher.d.ts +9 -0
  35. package/lib/types/client/ShortcutsRow.d.ts +15 -0
  36. package/lib/types/client/TerminalView.d.ts +7 -0
  37. package/lib/types/client/TurnSaveFooter.d.ts +18 -0
  38. package/lib/types/client/app-reload.d.ts +28 -0
  39. package/lib/types/client/branch-chats.d.ts +71 -0
  40. package/lib/types/client/branches.d.ts +23 -0
  41. package/lib/types/client/canvas/AppCanvas.d.ts +25 -0
  42. package/lib/types/client/canvas/app-canvas.d.ts +59 -0
  43. package/lib/types/client/canvas/picker.d.ts +27 -0
  44. package/lib/types/client/chat-draft.d.ts +15 -0
  45. package/lib/types/client/chat-saves.d.ts +28 -0
  46. package/lib/types/client/chats.d.ts +182 -0
  47. package/lib/types/client/feedback.d.ts +21 -0
  48. package/lib/types/client/frame-state.d.ts +34 -0
  49. package/lib/types/client/frame-view.d.ts +35 -0
  50. package/lib/types/client/fuzzy.d.ts +23 -0
  51. package/lib/types/client/git-sync.d.ts +39 -0
  52. package/lib/types/client/highlight.d.ts +15 -0
  53. package/lib/types/client/index.d.ts +23 -0
  54. package/lib/types/client/panel-resize.d.ts +29 -0
  55. package/lib/types/client/plugins-navigator.d.ts +51 -0
  56. package/lib/types/client/selection.d.ts +56 -0
  57. package/lib/types/client/sidebar-opens.d.ts +36 -0
  58. package/lib/types/client/snapshot.d.ts +11 -0
  59. package/lib/types/client/styles.d.ts +3 -0
  60. package/lib/types/client/switch-request.d.ts +18 -0
  61. package/lib/types/client/tab-sizing.d.ts +31 -0
  62. package/lib/types/client/tabs.d.ts +139 -0
  63. package/lib/types/client/tools.d.ts +15 -0
  64. package/lib/types/client/versions.d.ts +34 -0
  65. package/lib/types/client/view-state.d.ts +42 -0
  66. package/lib/types/contract.d.ts +293 -0
  67. package/package.json +124 -4
@@ -0,0 +1,293 @@
1
+ /** The one route the frame's client reads: what the frame shows around the app, from the Host that serves it. */
2
+ export declare const FRAME_API_PREFIX = "/api/acryl-blends-frame";
3
+ export declare const FRAME_STATE_PATH = "/api/acryl-blends-frame/state";
4
+ /** POST `{ name }`: a new branch from the checked-out version, switched to (the files stay as they are). */
5
+ export declare const FRAME_BRANCHES_NEW_PATH = "/api/acryl-blends-frame/branches/new";
6
+ /** POST `{ name }`: the app's folder moves to an existing local branch. */
7
+ export declare const FRAME_BRANCHES_SWITCH_PATH = "/api/acryl-blends-frame/branches/switch";
8
+ /** GET: `{ chats: { <session id>: <branch> } }`; POST `{ id, branch }`: record which branch a chat was opened on. */
9
+ export declare const FRAME_BRANCH_CHATS_PATH = "/api/acryl-blends-frame/branches/chats";
10
+ /** POST `{ hashes }`: which of these versions are also on another branch or the remote. */
11
+ export declare const FRAME_VERSIONS_SHARED_PATH = "/api/acryl-blends-frame/versions/shared";
12
+ /** GET (`?fetch=1` asks the remote first): the checked-out branch against its remote, a {@link GitRemoteState}. */
13
+ export declare const FRAME_GIT_REMOTE_PATH = "/api/acryl-blends-frame/git/remote";
14
+ /** POST: what a push would send and where (a {@link PushPlan}), after asking the remote; nothing is sent. */
15
+ export declare const FRAME_GIT_PUSH_PLAN_PATH = "/api/acryl-blends-frame/git/push-plan";
16
+ /**
17
+ * POST `{ confirm }`: send the checked-out branch to its upstream, setting the upstream on the first push, only when `confirm` is the plan the
18
+ * person said yes to and it still holds. Never forced. Answers a {@link GitSyncResult}.
19
+ */
20
+ export declare const FRAME_GIT_PUSH_PATH = "/api/acryl-blends-frame/git/push";
21
+ /** POST: bring the upstream's new versions in, by fast-forward only; a branch that has moved on both sides is left as it is. Answers a {@link GitSyncResult}. */
22
+ export declare const FRAME_GIT_PULL_PATH = "/api/acryl-blends-frame/git/pull";
23
+ /** POST: the app's snapshot verb `capture` (a row for every plugin folder that has none, then `blend.lock.json`). Answers a {@link SnapshotCapture}. */
24
+ export declare const FRAME_SNAPSHOT_CAPTURE_PATH = "/api/acryl-blends-frame/snapshot/capture";
25
+ /** What a capture did: the plugin folders that got a row, and how many plugins the lock now records. */
26
+ export interface SnapshotCapture {
27
+ readonly addedRows: readonly string[];
28
+ readonly modules: number;
29
+ }
30
+ /** A snapshot against its lock: `problems` names `blend.yaml` or each plugin folder that changed since the capture. */
31
+ export interface SnapshotVerify {
32
+ readonly ok: boolean;
33
+ readonly problems: readonly string[];
34
+ readonly checked: number;
35
+ }
36
+ /** What an apply did; nothing is written when `ok` is false. `extra` are the app's folders the snapshot lacks, kept and switched off. */
37
+ export interface SnapshotApply {
38
+ readonly ok: boolean;
39
+ readonly problems: readonly string[];
40
+ readonly modules: ReadonlyArray<{
41
+ readonly name: string;
42
+ readonly status: 'added' | 'unchanged' | 'conflict' | 'skipped';
43
+ readonly detail?: string;
44
+ }>;
45
+ readonly manifestChanged: boolean;
46
+ readonly extra: readonly string[];
47
+ }
48
+ /** @throws when the answer is not a capture result. */
49
+ export declare function parseSnapshotCapture(value: unknown): SnapshotCapture;
50
+ /**
51
+ * The checked-out branch against its remote:
52
+ * - `detached`: the folder is on no branch, so there is nothing to push or pull;
53
+ * - `no-remote`: the repository has no remote;
54
+ * - `unpublished`: the branch is not on the remote yet (its first push sets the upstream); `remote` is absent when there are several remotes and
55
+ * none is `origin`, so which one to use is not plain;
56
+ * - `tracking`: the branch has an upstream; `ahead` versions are here and not there, `behind` there and not here. `fetchError` is git's line when
57
+ * asking the remote failed, and the counts are then as of the last time it answered.
58
+ */
59
+ export type GitRemoteState = {
60
+ readonly kind: 'detached';
61
+ } | {
62
+ readonly kind: 'no-remote';
63
+ } | {
64
+ readonly kind: 'unpublished';
65
+ readonly branch: string;
66
+ readonly remote?: string;
67
+ } | {
68
+ readonly kind: 'tracking';
69
+ readonly branch: string;
70
+ readonly upstream: string;
71
+ readonly ahead: number;
72
+ readonly behind: number;
73
+ readonly fetchError?: string;
74
+ };
75
+ /**
76
+ * What a push will do, shown to the person before anything is sent: the versions it sends, the branch they land on and the remote's address
77
+ * (without any credential), and whether the branch is created there. A push sends exactly this, or nothing.
78
+ */
79
+ export interface PushPlan {
80
+ readonly branch: string;
81
+ readonly remote: string;
82
+ /** Where the versions land, as git names it (`origin/main`). */
83
+ readonly target: string;
84
+ /** The remote as a person reads it: `github.com/ana/notes`, or a folder's path. */
85
+ readonly address: string;
86
+ /** Versions here and not there. */
87
+ readonly versions: number;
88
+ /** The branch is not on the remote yet: the push creates it. */
89
+ readonly createsBranch: boolean;
90
+ /** The commit sent; a version made after the yes changes the plan, so nothing is sent. */
91
+ readonly head: string;
92
+ }
93
+ /** @throws when the value is not a push plan. */
94
+ export declare function parsePushPlan(value: unknown): PushPlan;
95
+ /** The same push: what the person confirmed is what would be sent now. */
96
+ export declare function samePushPlan(a: PushPlan, b: PushPlan): boolean;
97
+ /** What a push or pull did, in one line, and the remote state after it. */
98
+ export interface GitSyncResult {
99
+ readonly message: string;
100
+ readonly remote: GitRemoteState;
101
+ }
102
+ /** @throws when the answer is not a remote state. */
103
+ export declare function parseGitRemoteState(value: unknown): GitRemoteState;
104
+ /** @throws when the answer is not a push or pull result. */
105
+ export declare function parseGitSyncResult(value: unknown): GitSyncResult;
106
+ /** @throws when the answer is not a list of version hashes. */
107
+ export declare function parseSharedVersions(value: unknown): string[];
108
+ /** What the Host remembers of the chats: the branch each belongs to, and which are open (null until they were first decided). */
109
+ export interface BranchChatsView {
110
+ readonly chats: Record<string, string>;
111
+ readonly open: string[] | null;
112
+ }
113
+ /** @throws when the answer is not a map of chat id to branch name with the list of open chats. */
114
+ export declare function parseBranchChats(value: unknown): BranchChatsView;
115
+ /**
116
+ * Why a name cannot be a new branch, in words for the person typing it; `undefined` when it can. The Host asks git as well
117
+ * (`check-ref-format --branch`), so this only catches what is plain to see while typing.
118
+ */
119
+ export declare function branchNameProblem(name: string): string | undefined;
120
+ /** A local branch of the app's repository. */
121
+ export interface FrameBranch {
122
+ readonly name: string;
123
+ /** The branch the app's folder has checked out. */
124
+ readonly current: boolean;
125
+ }
126
+ export interface FrameState {
127
+ /** The app's name: its folder's name. */
128
+ readonly appName: string;
129
+ /** The app's folder, which the versions calls take as their path. */
130
+ readonly appRoot: string;
131
+ /** Where the app's own page is served, an absolute path on the frame's origin (`/app`); absent when the Host serves no app. */
132
+ readonly appPage?: string;
133
+ /** Local branches, the checked-out one marked; empty when the folder is not a git repository. */
134
+ readonly branches: readonly FrameBranch[];
135
+ /** The checked-out commit; absent before the first version or outside a repository. A change means the versions changed. */
136
+ readonly head?: string;
137
+ /** Files changed since the last version; absent outside a repository. */
138
+ readonly unsaved?: number;
139
+ /** The commit the checked-out branch's upstream points at, as last fetched or pushed; absent without one. A change means the shared marks changed. */
140
+ readonly upstreamHead?: string;
141
+ }
142
+ /** @throws an Error naming the field when the answer is not a frame state. */
143
+ export declare function parseFrameState(value: unknown): FrameState;
144
+ export declare const FRAME_PLUGINS_PATH = "/api/acryl-blends-frame/plugins";
145
+ export declare const FRAME_PLUGINS_SWITCH_PATH = "/api/acryl-blends-frame/plugins/switch";
146
+ /** POST `{ name }`: what sharing this local plugin would do (a {@link SharePlan}); nothing leaves the machine. */
147
+ export declare const FRAME_PLUGINS_SHARE_PLAN_PATH = "/api/acryl-blends-frame/plugins/share-plan";
148
+ /** POST `{ name, confirm }`: publish it, only when `confirm` is the plan the person said yes to and it still holds. */
149
+ export declare const FRAME_PLUGINS_SHARE_PATH = "/api/acryl-blends-frame/plugins/share";
150
+ /** Where a shared plugin went: its GitHub repository and the released version other apps install. */
151
+ export interface SharedPluginView {
152
+ readonly url: string;
153
+ readonly version: string;
154
+ /** GitHub says the repository no longer exists (deleted or renamed): the row shows it gone and offers a new share. */
155
+ readonly gone?: boolean;
156
+ }
157
+ export type ShareVisibility = 'private' | 'public';
158
+ /**
159
+ * What a share will do, shown to the person before anything is sent: the GitHub repository it goes to (created when it does not exist), the version
160
+ * it releases and who can see it. A share publishes exactly this plan, or nothing.
161
+ */
162
+ export interface SharePlan {
163
+ readonly owner: string;
164
+ readonly repo: string;
165
+ readonly version: string;
166
+ readonly visibility: ShareVisibility;
167
+ /** The repository does not exist yet: the share creates it. */
168
+ readonly createsRepository: boolean;
169
+ /** The version already released there; the plan then releases the next patch. */
170
+ readonly released?: string;
171
+ }
172
+ /** @throws when the value is not a share plan. */
173
+ export declare function parseSharePlan(value: unknown): SharePlan;
174
+ /** The same plan: what the person confirmed is what would be published now. */
175
+ export declare function samePlan(a: SharePlan, b: SharePlan): boolean;
176
+ /**
177
+ * Where a plugin of the app comes from: a row of the app's `blend.yaml` (the library plugins the app was made with), or a plugin written into the
178
+ * app's `plugins/` folder after it was made (what agents build; the `extensions` row starts them).
179
+ */
180
+ export type AppPluginKind = 'row' | 'made';
181
+ /** One plugin of the app, as Settings → Plugins lists it. */
182
+ export interface AppPluginView {
183
+ readonly name: string;
184
+ readonly kind: AppPluginKind;
185
+ /** Who wrote it: the agent or person of its first commit; absent for a library row. */
186
+ readonly by?: string;
187
+ /** When it was first committed (ISO time); absent when it is not saved yet or a library row. */
188
+ readonly at?: string;
189
+ /** Not committed yet: it runs, but no version has it. */
190
+ readonly unsaved?: boolean;
191
+ /** The library release a library row was copied from (`plugins/library.lock.json`). */
192
+ readonly version?: string;
193
+ /** A local plugin this app shared: where it went (a GitHub repository) and the version it released. */
194
+ readonly shared?: SharedPluginView;
195
+ readonly description: string;
196
+ readonly on: boolean;
197
+ }
198
+ /** How one of the frame's own Loader rows runs: started, waiting for a service it needs, failed to start, or switched off. */
199
+ export type FramePluginState = 'active' | 'waiting' | 'failed' | 'off';
200
+ /** One of the frame's own plugins (its Loader rows around the app): shown, not switched here. */
201
+ export interface FramePluginView {
202
+ readonly id: string;
203
+ readonly name: string;
204
+ readonly version?: string;
205
+ readonly description: string;
206
+ readonly state: FramePluginState;
207
+ }
208
+ export interface AppPluginsView {
209
+ readonly plugins: readonly AppPluginView[];
210
+ readonly frame: readonly FramePluginView[];
211
+ }
212
+ /** @throws when the answer is not a plugin list. */
213
+ export declare function parseAppPluginsView(value: unknown): AppPluginsView;
214
+ export declare const FRAME_FEEDBACK_PATH = "/api/acryl-blends-frame/feedback";
215
+ export declare const FRAME_FEEDBACK_SEEN_PATH = "/api/acryl-blends-frame/feedback/seen";
216
+ /** GET `?id=`: one note's screenshot, served by the frame so the left panel and the chat hand-off never depend on the app's mount. */
217
+ export declare const FRAME_FEEDBACK_SHOT_PATH = "/api/acryl-blends-frame/feedback/shot";
218
+ /** One note a person sent from the app (the `feedback` plugin), as the left panel shows it. */
219
+ export interface FeedbackNoteView {
220
+ readonly id: string;
221
+ /** ISO time it was sent. */
222
+ readonly at: string;
223
+ readonly text: string;
224
+ /** The page's path it was sent from. */
225
+ readonly page: string;
226
+ /** The element it was pinned on; absent for "Nothing specific". */
227
+ readonly element?: {
228
+ readonly selector: string;
229
+ readonly label: string;
230
+ };
231
+ /** What the person saw when they sent it; absent when the browser refused the capture. */
232
+ readonly screenshot?: {
233
+ readonly mediaType: 'image/webp' | 'image/png';
234
+ readonly width: number;
235
+ readonly height: number;
236
+ };
237
+ readonly seen: boolean;
238
+ }
239
+ /** `available` is false when the app has no `feedback` plugin (or it is switched off): the left panel then shows no section. */
240
+ export interface FeedbackView {
241
+ readonly available: boolean;
242
+ readonly notes: readonly FeedbackNoteView[];
243
+ }
244
+ /** @throws when the value is not a list of notes. */
245
+ export declare function parseFeedbackNotes(value: unknown): FeedbackNoteView[];
246
+ /** @throws when the answer is not a feedback view. */
247
+ export declare function parseFeedbackView(value: unknown): FeedbackView;
248
+ /** GET `?session=<id>`: what each of that chat's turns saved (`ChatSavesView`). */
249
+ export declare const FRAME_CHAT_SAVES_PATH = "/api/acryl-blends-frame/chat-saves";
250
+ /** The save point the frame made by itself when a chat turn changed the app's files. */
251
+ export interface TurnSaveView {
252
+ /** The chat turn (DSH's turn number) that changed the files. */
253
+ readonly turn: number;
254
+ /** The files the turn changed, relative to the app's folder. */
255
+ readonly files: readonly string[];
256
+ /** The version the turn was saved as: its commit, how many versions the branch had then (`v7`), and what it was called. */
257
+ readonly hash: string;
258
+ readonly version: number;
259
+ readonly subject: string;
260
+ }
261
+ export interface ChatSavesView {
262
+ readonly saves: readonly TurnSaveView[];
263
+ }
264
+ /** @throws when the value is not a list of turn saves. */
265
+ export declare function parseChatSaves(value: unknown): ChatSavesView;
266
+ /** GET: the chats that have at least one turn, each with its name (`RealChatsView`); a chat nobody has written to is not a chat the frame lists. */
267
+ export declare const FRAME_REAL_CHATS_PATH = "/api/acryl-blends-frame/real-chats";
268
+ export interface RealChatView {
269
+ readonly id: string;
270
+ readonly title: string;
271
+ }
272
+ export interface RealChatsView {
273
+ readonly chats: readonly RealChatView[];
274
+ }
275
+ /** @throws when the value is not a list of chats. */
276
+ export declare function parseRealChats(value: unknown): RealChatsView;
277
+ /**
278
+ * GET: the app's code as the Host runs it - `{ seq, generation, error }` (./app-reload.ts). With `?after=<seq>` the Host answers when `seq` differs
279
+ * from that (or after a while with the same answer), so the page hears of a new generation as it is up, without a timer.
280
+ */
281
+ export declare const FRAME_APP_PATH = "/api/acryl-blends-frame/app";
282
+ /** POST `{ session, label, page, selector }`: the element the chat message being sent is about, for the Host to hand to the agent as context. */
283
+ export declare const FRAME_SELECTION_PATH = "/api/acryl-blends-frame/selection";
284
+ /** Which code the app runs: a new `generation` means the app's files were loaded again; `error` is why the last load was refused (the last good code runs on). */
285
+ export interface AppReloadView {
286
+ /** Changes with every other field: the long poll's cursor. */
287
+ readonly seq: number;
288
+ /** 0 for the code the host started with, plus one for each reload that took. */
289
+ readonly generation: number;
290
+ readonly error: string | null;
291
+ }
292
+ /** @throws an Error naming the field when the answer is not an app reload view. */
293
+ export declare function parseAppReloadView(value: unknown): AppReloadView;
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Push and pull for the checked-out branch, the Git tab's "share through git". The Host owns every git call; the client only calls the routes.
3
+ *
4
+ * - The remote is the branch's own (`branch.<name>.remote`), else `origin`, else the only remote. Several remotes and none named `origin` is
5
+ * refused plainly rather than guessed.
6
+ * - Push sends the branch to its upstream, and on the first push sets it (`--set-upstream`). It is never forced: a remote that has moved on is
7
+ * said so before git is even asked. It sends work under the person's name, so it is planned first (what, where, to which address) and sends
8
+ * only the plan the person confirmed, read again just before; a plan that changed meanwhile sends nothing.
9
+ * - Pull fetches, then fast-forwards only. A branch that has moved on both here and there is left exactly as it is, with a sentence that says so.
10
+ * - Every failure carries git's own line (the runner's `detail`): no remote, a refused login, a network that is down.
11
+ *
12
+ * Push and pull run one at a time: a second click waits for the first to finish rather than racing it.
13
+ */
14
+ import { type GitRemoteState, type GitSyncResult, type PushPlan } from './contract.ts';
15
+ /** The part of the confined git runner (`acryl-versions`) this module uses: an argument array, never a shell. */
16
+ export interface SyncGit {
17
+ run(args: readonly string[], cwd: string, acceptExit?: number, timeoutMs?: number): Promise<{
18
+ readonly stdout: string;
19
+ }>;
20
+ }
21
+ /** The checked-out branch against its remote. With `fetch`, the remote is asked first; when it cannot be reached, its error rides along. */
22
+ export declare function remoteState(git: SyncGit, root: string, options?: {
23
+ readonly fetch?: boolean;
24
+ }): Promise<GitRemoteState>;
25
+ /**
26
+ * The remote's address as a person reads it, never with a credential: `https://user:token@github.com/ana/notes.git` and
27
+ * `git@github.com:ana/notes.git` both read `github.com/ana/notes`; a folder stays its path.
28
+ */
29
+ export declare function remoteAddress(url: string): string;
30
+ export declare class GitSync {
31
+ private readonly git;
32
+ private readonly root;
33
+ private queue;
34
+ constructor(git: SyncGit, root: string);
35
+ state(options?: {
36
+ readonly fetch?: boolean;
37
+ }): Promise<GitRemoteState>;
38
+ /** What a push would send and where, after asking the remote; nothing is sent. @throws the one line saying why there is nothing to push. */
39
+ planPush(): Promise<PushPlan>;
40
+ /**
41
+ * Send exactly the confirmed plan: the branch to its upstream, setting it on the first push. Never forced. The plan is read again first, and a
42
+ * changed one (a new version, the remote moved, another address) sends nothing. @throws an Error whose message is the one line to show.
43
+ */
44
+ push(confirmed: PushPlan): Promise<GitSyncResult>;
45
+ /** The plan, and the upstream ref its versions land on (`refs/heads/main`). */
46
+ private plan;
47
+ /** Bring the upstream's new versions in by fast-forward only; a branch that moved on both sides is left as it is. @throws the one line to show. */
48
+ pull(): Promise<GitSyncResult>;
49
+ private serial;
50
+ }
51
+ /** The commit the checked-out branch's upstream points at, or `undefined` without one (for the frame state: a push changes it). */
52
+ export declare function upstreamHead(git: SyncGit, root: string): Promise<string | undefined>;
package/lib/index.d.ts ADDED
@@ -0,0 +1,169 @@
1
+ /**
2
+ * Cordis Host plugin: the Blends frame's one route, `GET /api/acryl-blends-frame/state` - the app's name and folder, where its page is served,
3
+ * and its local branches. The frame itself is the client half (`./client`).
4
+ *
5
+ * One effect owns the confined git runner and both registrations; disposal unmounts the route and reaps any git call still running. The right
6
+ * panel's terminals, PTY agents, files and git are the workspace's own Host services (`acryl-workspace`), run here as a child plugin: only its
7
+ * Host half, since the frame, not the workbench, owns the page.
8
+ */
9
+ import type { Context } from '@deepseek-ai/cordis';
10
+ import { Acryl } from 'acrylblends';
11
+ import { GitRunner, Versions } from '@acrylblends/versions';
12
+ import { type ShareAppPluginResult } from './app-plugins.ts';
13
+ import { type AppRow } from './app-reload.ts';
14
+ import { SelectionInbox } from './selection-context.ts';
15
+ import { type BranchChatsRecord } from './branch-chats.ts';
16
+ import { type AppPluginKind, type AppReloadView, type AppPluginsView, type ChatSavesView, type FeedbackView, type PushPlan, type SharePlan, type FrameBranch, type FrameState, type GitRemoteState, type GitSyncResult } from './contract.ts';
17
+ import { type AppSnapshotService } from './app-snapshot.ts';
18
+ /**
19
+ * The part of the runtime's `appInstance` service ACRYL plugins read (a separated interface: plugins do not import the runtime). Every plugin
20
+ * declares exactly this shape, so the Context augmentations agree in a program that loads several; the app's folder (`root`) is read apart.
21
+ */
22
+ interface AppInstanceService {
23
+ readonly home: string;
24
+ readonly dshHome: string;
25
+ }
26
+ declare module '@deepseek-ai/cordis' {
27
+ interface Context {
28
+ appInstance: AppInstanceService;
29
+ }
30
+ }
31
+ export interface FrameConfig {
32
+ /** Where the app's own page is served (`/app`); the frame shows no app without it. */
33
+ readonly appPage?: string;
34
+ /**
35
+ * The GitHub account or organization a local plugin is shared to; the signed-in `gh` account when absent. A rehearsal sets a test organization
36
+ * (`shareOwner: inboxxobni`) so nothing lands on the person's own account.
37
+ */
38
+ readonly shareOwner?: string;
39
+ }
40
+ export declare const name = "@acrylblends/blends-frame";
41
+ export declare const inject: string[];
42
+ /** `git for-each-ref` lines `<current marker> <name>`: the checked-out branch first, the rest by name. */
43
+ export declare function parseBranches(stdout: string): FrameBranch[];
44
+ /** A git call as the state and the shared-versions check use it: the versions runner satisfies it, and a test stands in for it. */
45
+ export interface GitLike {
46
+ run(args: readonly string[], cwd: string): Promise<{
47
+ readonly stdout: string;
48
+ }>;
49
+ }
50
+ /**
51
+ * The versions that are also on another local branch or a remote-tracking branch: another line of work has them, or they are on the remote, so
52
+ * the list marks them "shared". The current branch's own ref is left out (being on it is not sharing); one `rev-list` per other ref, then an
53
+ * intersection with the listed versions.
54
+ */
55
+ export declare function sharedVersions(git: GitLike, root: string, hashes: readonly string[]): Promise<string[]>;
56
+ /** `git status --porcelain -z` entries: one per changed path (a rename's second, NUL-separated path is not counted twice). */
57
+ export declare function countChanges(stdout: string): number;
58
+ /** Settings → Plugins: the app's plugins, switching one in `blend.yaml`, and sharing a local one. */
59
+ export interface PluginsPort {
60
+ read(): Promise<AppPluginsView>;
61
+ switch(kind: AppPluginKind, name: string, on: boolean): Promise<void>;
62
+ /** What sharing one local plugin would do (repository, version, visibility); nothing is sent. */
63
+ planShare(name: string): Promise<SharePlan>;
64
+ /** Publish one local plugin to its GitHub repository and release, through the plugin-hub path: only the plan the person confirmed. */
65
+ share(name: string, confirmed: SharePlan): Promise<ShareAppPluginResult>;
66
+ }
67
+ /** A note's screenshot as the frame serves it: the bytes and their image type. */
68
+ export interface FeedbackShot {
69
+ readonly bytes: Uint8Array;
70
+ readonly mediaType: 'image/webp' | 'image/png';
71
+ }
72
+ /** The builder's side of the app's feedback: the notes people sent, marking them seen, and one note's screenshot. */
73
+ export interface FeedbackPort {
74
+ read(): Promise<FeedbackView>;
75
+ markSeen(ids: readonly string[]): Promise<void>;
76
+ screenshot(id: string): Promise<FeedbackShot | undefined>;
77
+ }
78
+ /** Reads the app's `feedback` service where it is now; `available` false without it. */
79
+ export declare function feedbackPort(source: () => unknown): FeedbackPort;
80
+ /** What the Branches "New" button asks of the Host. */
81
+ export interface BranchesPort {
82
+ /** Make the branch from the checked-out version and switch to it; rejects with git's reason. */
83
+ create(name: string): Promise<void>;
84
+ /** Move the app's folder to an existing local branch; rejects with git's reason. */
85
+ switchTo(name: string): Promise<void>;
86
+ }
87
+ /** The Git tab's push and pull for the checked-out branch (./git-sync.ts). Each rejects with the one line to show. */
88
+ export interface GitSyncPort {
89
+ state(options: {
90
+ readonly fetch?: boolean;
91
+ }): Promise<GitRemoteState>;
92
+ /** What a push would send and where; nothing is sent. */
93
+ planPush(): Promise<PushPlan>;
94
+ /** Sends only the plan the person confirmed. */
95
+ push(confirmed: PushPlan): Promise<GitSyncResult>;
96
+ pull(): Promise<GitSyncResult>;
97
+ }
98
+ /** What each turn of a chat saved (the auto-save), for the line under the answer. */
99
+ export interface ChatSavesPort {
100
+ read(session: string): Promise<ChatSavesView>;
101
+ }
102
+ /** The chats that have a turn (the left panel lists only those, and the open one). */
103
+ export interface RealChatsPort {
104
+ read(): Promise<readonly {
105
+ readonly id: string;
106
+ readonly title: string;
107
+ }[]>;
108
+ }
109
+ /** The app's code as the Host runs it: what it runs now, and the answer once that changes. */
110
+ export interface AppReloadPort {
111
+ view(): AppReloadView;
112
+ wait(after: number, timeoutMs: number): Promise<AppReloadView>;
113
+ }
114
+ /** The `name` of a branch request, or why it cannot be one. */
115
+ export declare function parseBranchName(body: unknown): {
116
+ name: string;
117
+ } | {
118
+ problem: string;
119
+ };
120
+ /** Which branch each chat was opened on (the frame lists a branch's own chats; DSH itself knows no branches), and which chats are open. */
121
+ export interface BranchChatsPort {
122
+ read(): Promise<BranchChatsRecord>;
123
+ /** Records a chat's branch once; a chat stays where it was opened. */
124
+ assign(id: string, branch: string): Promise<void>;
125
+ /** Opens or closes one chat. */
126
+ setOpen(id: string, open: boolean): Promise<void>;
127
+ /** Decides which chats are open when nobody has yet. */
128
+ initOpen(ids: readonly string[]): Promise<void>;
129
+ }
130
+ export interface FrameRoutesDeps {
131
+ readonly state: () => Promise<FrameState>;
132
+ readonly report?: (cause: unknown) => void;
133
+ readonly plugins?: PluginsPort;
134
+ readonly feedback?: FeedbackPort;
135
+ readonly branches?: BranchesPort;
136
+ readonly branchChats?: BranchChatsPort;
137
+ /** What each turn of a chat saved (the auto-save), for the line under the answer. */
138
+ readonly chatSaves?: ChatSavesPort;
139
+ /** Which of the listed versions are also on another branch or the remote. */
140
+ readonly shared?: (hashes: readonly string[]) => Promise<string[]>;
141
+ readonly realChats?: RealChatsPort;
142
+ readonly gitSync?: GitSyncPort;
143
+ /** The capture a Save point starts with. */
144
+ readonly snapshot?: Pick<AppSnapshotService, 'captureForSave'>;
145
+ readonly appReload?: AppReloadPort;
146
+ /** The element picks waiting for the step that reads the message they belong to (./selection-context.ts). */
147
+ readonly selection?: SelectionInbox;
148
+ }
149
+ export declare function frameRoutes({ state, report, plugins, feedback, branches, branchChats, chatSaves, shared, realChats, gitSync, snapshot, appReload, selection }: FrameRoutesDeps): Acryl;
150
+ /**
151
+ * The app's rows, plugins first and routes after (the order they start in): each as the reloader drives it. A row's module is imported under the
152
+ * current generation (`./app-generation.ts`) by the loader itself, so `restart` stops the row's plugin and has the loader start the entry again - not
153
+ * `fiber.restart()`, which runs the module the row already has. The plugin leaves the registry (what DSH's own hot reload does) rather than its fiber
154
+ * being disposed: the loader reads a fiber disposed on its own as the person switching the row off, and writes that into the app's `cordis.yml`.
155
+ */
156
+ export declare function appRowsOf(loader: Context['loader'] | undefined): AppRow[];
157
+ /**
158
+ * Save the app's folder as a version called `message`, and say which one it is (`v7`: how many versions the branch has then). Only a turn DSH says changed
159
+ * files comes here, but the commit takes the whole folder as a save point does: a file the person changed by hand since the last version goes into it. A folder
160
+ * with nothing to commit (the agent committed itself, or the files are ignored) makes no version.
161
+ */
162
+ export declare function saveVersion(git: GitRunner, versions: Versions, root: string, message: string): Promise<{
163
+ hash: string;
164
+ version: number;
165
+ subject: string;
166
+ } | undefined>;
167
+ export declare function apply(ctx: Context, config?: FrameConfig): void;
168
+ export { AutoSave, messageText, requestSubject, SaveStore } from './auto-save.ts';
169
+ export { FRAME_API_PREFIX, FRAME_STATE_PATH, parseFrameState, type FrameBranch, type FrameState } from './contract.ts';