@acryldev/blends-frame 0.0.0-stage → 0.2.0

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 +50422 -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 +46 -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 +124 -3
@@ -0,0 +1,414 @@
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
+ /** POST `{ name }`: keep a packed copy of this local plugin on this machine (the app's plugin store); nothing leaves the machine. */
151
+ export declare const FRAME_PLUGINS_SAVE_PATH = "/api/acryl-blends-frame/plugins/save";
152
+ /** GET: the public plugin registry (cordisplugins.github.io), each entry marked when this app already has it; read fresh by the Host, never by the page. */
153
+ export declare const FRAME_PLUGINS_REGISTRY_PATH = "/api/acryl-blends-frame/plugins/registry";
154
+ /** GET: whether this computer can share to GitHub (the helper program is installed and signed in), read before the person is asked anything. */
155
+ export declare const FRAME_PLUGINS_GITHUB_PATH = "/api/acryl-blends-frame/plugins/github";
156
+ /** POST: start GitHub's browser sign-in (a one-time code for github.com/login/device); GET: where it is; DELETE: stop one still waiting. */
157
+ export declare const FRAME_PLUGINS_GITHUB_CONNECT_PATH = "/api/acryl-blends-frame/plugins/github/connect";
158
+ /** POST `{ source }`: pull one released plugin (`github:<owner>/<repo>@<version>`) into the running app, through the app's plugin-share checks. */
159
+ export declare const FRAME_PLUGINS_PULL_PATH = "/api/acryl-blends-frame/plugins/pull";
160
+ /** A packed copy of a plugin kept on this machine: its version and where the tarball is. */
161
+ export interface SavedPluginView {
162
+ readonly version: string;
163
+ /** Absolute path of the packed copy (the store's `.tgz`). */
164
+ readonly path: string;
165
+ }
166
+ /** What a save did: the copy, whether it is new, and whether the version was raised because that version was already saved with other content. */
167
+ export interface SavedPluginResult extends SavedPluginView {
168
+ readonly added: boolean;
169
+ readonly bumped: boolean;
170
+ }
171
+ /** Where a shared plugin went: its GitHub repository and the released version other apps install. */
172
+ export interface SharedPluginView {
173
+ readonly url: string;
174
+ readonly version: string;
175
+ /** GitHub says the repository no longer exists (deleted or renamed): the row shows it gone and offers a new share. */
176
+ readonly gone?: boolean;
177
+ /** It was shared to the public registry (the `cordis-plugin` topic is set), not only as a public repository. */
178
+ readonly registry?: boolean;
179
+ }
180
+ export type ShareVisibility = 'private' | 'public';
181
+ /**
182
+ * 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
183
+ * it releases and who can see it. A share publishes exactly this plan, or nothing.
184
+ */
185
+ export interface SharePlan {
186
+ readonly owner: string;
187
+ readonly repo: string;
188
+ readonly version: string;
189
+ readonly visibility: ShareVisibility;
190
+ /** The repository does not exist yet: the share creates it. */
191
+ readonly createsRepository: boolean;
192
+ /** The version already released there; the plan then releases the next patch. */
193
+ readonly released?: string;
194
+ /** The license a public share is offered under, as an SPDX id (MIT unless the app says otherwise); a private share has none. */
195
+ readonly license?: string;
196
+ /** The public registry (cordisplugins.github.io) lists it: the share sets the `cordis-plugin` topic. Only a public share can be listed. */
197
+ readonly registry?: boolean;
198
+ }
199
+ /** @throws when the value is not a share plan. */
200
+ export declare function parseSharePlan(value: unknown): SharePlan;
201
+ /** @throws when the value is not what a save answers. */
202
+ export declare function parseSavedPlugin(value: unknown): SavedPluginResult;
203
+ /** The same plan: what the person confirmed is what would be published now. */
204
+ export declare function samePlan(a: SharePlan, b: SharePlan): boolean;
205
+ /**
206
+ * 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
207
+ * app's `plugins/` folder after it was made (what agents build; the `extensions` row starts them).
208
+ */
209
+ export type AppPluginKind = 'row' | 'made';
210
+ /** One plugin of the app, as Settings → Plugins lists it. */
211
+ export interface AppPluginView {
212
+ readonly name: string;
213
+ readonly kind: AppPluginKind;
214
+ /** Who wrote it: the agent or person of its first commit; absent for a library row. */
215
+ readonly by?: string;
216
+ /** When it was first committed (ISO time); absent when it is not saved yet or a library row. */
217
+ readonly at?: string;
218
+ /** Not committed yet: it runs, but no version has it. */
219
+ readonly unsaved?: boolean;
220
+ /** The library release a library row was copied from (`plugins/library.lock.json`). */
221
+ readonly version?: string;
222
+ /** A local plugin this app shared: where it went (a GitHub repository) and the version it released. */
223
+ readonly shared?: SharedPluginView;
224
+ /** The newest packed copy of it kept on this machine (the app's plugin store). */
225
+ readonly saved?: SavedPluginView;
226
+ /** Absolute path of the plugin's folder, where its code is. */
227
+ readonly folder?: string;
228
+ /** The plugin's main file, relative to the app's folder: absent when that file is outside the app (a package of `node_modules` elsewhere). */
229
+ readonly main?: string;
230
+ readonly description: string;
231
+ readonly on: boolean;
232
+ }
233
+ /** How one of the frame's own Loader rows runs: started, waiting for a service it needs, failed to start, or switched off. */
234
+ export type FramePluginState = 'active' | 'waiting' | 'failed' | 'off';
235
+ /** One of the frame's own plugins (its Loader rows around the app): shown, not switched here. */
236
+ export interface FramePluginView {
237
+ readonly id: string;
238
+ readonly name: string;
239
+ readonly version?: string;
240
+ readonly description: string;
241
+ readonly state: FramePluginState;
242
+ /** Absolute path of the package folder, where its code is. */
243
+ readonly folder?: string;
244
+ /** The package's main file relative to the app's folder; absent when it is outside the app. */
245
+ readonly main?: string;
246
+ }
247
+ export interface AppPluginsView {
248
+ readonly plugins: readonly AppPluginView[];
249
+ readonly frame: readonly FramePluginView[];
250
+ }
251
+ /** @throws when the answer is not a plugin list. */
252
+ export declare function parseAppPluginsView(value: unknown): AppPluginsView;
253
+ export declare const FRAME_FEEDBACK_PATH = "/api/acryl-blends-frame/feedback";
254
+ export declare const FRAME_FEEDBACK_SEEN_PATH = "/api/acryl-blends-frame/feedback/seen";
255
+ /** 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. */
256
+ export declare const FRAME_FEEDBACK_SHOT_PATH = "/api/acryl-blends-frame/feedback/shot";
257
+ /** One note a person sent from the app (the `feedback` plugin), as the left panel shows it. */
258
+ export interface FeedbackNoteView {
259
+ readonly id: string;
260
+ /** ISO time it was sent. */
261
+ readonly at: string;
262
+ readonly text: string;
263
+ /** The page's path it was sent from. */
264
+ readonly page: string;
265
+ /** The element it was pinned on; absent for "Nothing specific". */
266
+ readonly element?: {
267
+ readonly selector: string;
268
+ readonly label: string;
269
+ };
270
+ /** What the person saw when they sent it; absent when the browser refused the capture. */
271
+ readonly screenshot?: {
272
+ readonly mediaType: 'image/webp' | 'image/png';
273
+ readonly width: number;
274
+ readonly height: number;
275
+ };
276
+ readonly seen: boolean;
277
+ }
278
+ /** `available` is false when the app has no `feedback` plugin (or it is switched off): the left panel then shows no section. */
279
+ export interface FeedbackView {
280
+ readonly available: boolean;
281
+ readonly notes: readonly FeedbackNoteView[];
282
+ }
283
+ /** @throws when the value is not a list of notes. */
284
+ export declare function parseFeedbackNotes(value: unknown): FeedbackNoteView[];
285
+ /** @throws when the answer is not a feedback view. */
286
+ export declare function parseFeedbackView(value: unknown): FeedbackView;
287
+ /** GET `?session=<id>`: what each of that chat's turns saved (`ChatSavesView`). */
288
+ export declare const FRAME_CHAT_SAVES_PATH = "/api/acryl-blends-frame/chat-saves";
289
+ /** The save point the frame made by itself when a chat turn changed the app's files. */
290
+ export interface TurnSaveView {
291
+ /** The chat turn (DSH's turn number) that changed the files. */
292
+ readonly turn: number;
293
+ /** The files the turn changed, relative to the app's folder. */
294
+ readonly files: readonly string[];
295
+ /** The version the turn was saved as: its commit, how many versions the branch had then (`v7`), and what it was called. */
296
+ readonly hash: string;
297
+ readonly version: number;
298
+ readonly subject: string;
299
+ }
300
+ export interface ChatSavesView {
301
+ readonly saves: readonly TurnSaveView[];
302
+ }
303
+ /** @throws when the value is not a list of turn saves. */
304
+ export declare function parseChatSaves(value: unknown): ChatSavesView;
305
+ /** 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. */
306
+ export declare const FRAME_REAL_CHATS_PATH = "/api/acryl-blends-frame/real-chats";
307
+ export interface RealChatView {
308
+ readonly id: string;
309
+ readonly title: string;
310
+ }
311
+ export interface RealChatsView {
312
+ readonly chats: readonly RealChatView[];
313
+ }
314
+ /** @throws when the value is not a list of chats. */
315
+ export declare function parseRealChats(value: unknown): RealChatsView;
316
+ /**
317
+ * 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
318
+ * 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.
319
+ */
320
+ export declare const FRAME_APP_PATH = "/api/acryl-blends-frame/app";
321
+ /** POST `{ session, label, page, selector }`: the element the chat message being sent is about, for the Host to hand to the agent as context. */
322
+ export declare const FRAME_SELECTION_PATH = "/api/acryl-blends-frame/selection";
323
+ /** 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). */
324
+ export interface AppReloadView {
325
+ /** Changes with every other field: the long poll's cursor. */
326
+ readonly seq: number;
327
+ /** 0 for the code the host started with, plus one for each reload that took. */
328
+ readonly generation: number;
329
+ readonly error: string | null;
330
+ }
331
+ /** @throws an Error naming the field when the answer is not an app reload view. */
332
+ export declare function parseAppReloadView(value: unknown): AppReloadView;
333
+ /** What a plugin of the registry offers, as the registry's index lists it (`https://cordisplugins.github.io/registry/index.json`, formatVersion 1). */
334
+ /** Official: released from one of the project's organisations; community: from anyone else. The registry decides it from the repository owner's GitHub id. */
335
+ export type RegistryOrigin = 'official' | 'community';
336
+ export interface RegistryEntryView {
337
+ /** The plugin's name; a scoped name keeps its scope. */
338
+ readonly name: string;
339
+ readonly description: string;
340
+ /** The GitHub account or organization that released it. */
341
+ readonly owner: string;
342
+ /** The repository's address. */
343
+ readonly url: string;
344
+ readonly version: string;
345
+ /** The day of the release (`YYYY-MM-DD`), when the index says. */
346
+ readonly published?: string;
347
+ /** Where it runs: `ACRYL` (needs an ACRYL service), `Both`, or `DSH stock` (a Harness plugin, which an app of this kind cannot run). */
348
+ readonly compatibility: string;
349
+ readonly origin: RegistryOrigin;
350
+ /** The source a pull takes: `github:<owner>/<repo>@<version>`. */
351
+ readonly source: string;
352
+ /** This app already has a plugin of this name or pulled from this source. */
353
+ readonly installed: boolean;
354
+ /** The account the person is signed in to GitHub with (or shares to) released it. */
355
+ readonly mine: boolean;
356
+ /** Bytes it downloads besides itself for this computer (a native package, plugin-share/native.ts), when the index says. */
357
+ readonly download?: number;
358
+ }
359
+ /** The registry as the Host read it: its entries, or why they could not be read (offline, rate limited, the site changed). */
360
+ export type RegistryView = {
361
+ readonly status: 'ready';
362
+ readonly entries: readonly RegistryEntryView[];
363
+ readonly readAt: string;
364
+ } | {
365
+ readonly status: 'unavailable';
366
+ readonly message: string;
367
+ };
368
+ /** @throws when the value is not a registry view. */
369
+ export declare function parseRegistryView(value: unknown): RegistryView;
370
+ /** What a pull did: the plugin now running, or why it was refused (nothing changed then). */
371
+ export interface PulledPluginView {
372
+ readonly name: string;
373
+ readonly version: string;
374
+ readonly action: 'installed' | 'updated' | 'unchanged';
375
+ readonly state: string;
376
+ }
377
+ /** @throws when the value is not what a pull answers. */
378
+ export declare function parsePulledPlugin(value: unknown): PulledPluginView;
379
+ /** Whether the person can share to GitHub now, and when not, the single thing to do about it. */
380
+ export type GithubReadiness = {
381
+ readonly status: 'ready';
382
+ readonly account: string;
383
+ } | {
384
+ readonly status: 'signed-out';
385
+ readonly say: string;
386
+ readonly command: string;
387
+ } | {
388
+ readonly status: 'missing';
389
+ readonly say: string;
390
+ readonly link: string;
391
+ } | {
392
+ readonly status: 'unavailable';
393
+ readonly say: string;
394
+ };
395
+ /** Where connecting GitHub from the app is (`./github-connect.ts`). */
396
+ export type GithubConnectState = {
397
+ readonly status: 'idle';
398
+ } | {
399
+ readonly status: 'starting';
400
+ } | {
401
+ readonly status: 'code';
402
+ readonly code: string;
403
+ readonly url: string;
404
+ } | {
405
+ readonly status: 'connected';
406
+ } | {
407
+ readonly status: 'failed';
408
+ readonly say: string;
409
+ readonly details?: string;
410
+ };
411
+ /** @throws when the value is not a connect state. */
412
+ export declare function parseGithubConnectState(value: unknown): GithubConnectState;
413
+ /** @throws when the value is not a GitHub readiness. */
414
+ export declare function parseGithubReadiness(value: unknown): GithubReadiness;
@@ -0,0 +1,85 @@
1
+ /**
2
+ * The plugin graph's wire types: what the frame's Host answers and what the browser draws (Settings > Plugins > Graph). Ported from cordis-plugin-graph
3
+ * (MIT, github.com/cordisplugins/cordis-plugin-graph, commit e9bf6b5, `src/inspect.ts`), with two additions the original did not have: a node says where its
4
+ * code is (`source`), and the Host keeps a numbered list of fiber lifecycle events (`GraphEvent`) so the browser hears a change instead of asking again.
5
+ * No Node or browser import: both sides read this file.
6
+ */
7
+ /** The whole graph of the Host's Cordis context, now. */
8
+ export declare const FRAME_GRAPH_PATH = "/api/acryl-blends-frame/graph";
9
+ /** The fiber events after `?after=<seq>`: answered at once when there are some, else when the next one happens (or after about 20 s with none). */
10
+ export declare const FRAME_GRAPH_EVENTS_PATH = "/api/acryl-blends-frame/graph/events";
11
+ /** Fiber lifecycle phase, or `disabled` for a Loader row turned off. */
12
+ export type NodePhase = 'pending' | 'loading' | 'active' | 'failed' | 'unloading' | 'disposed' | 'disabled';
13
+ /** Edge kinds, all directed consumer -> dependency / child -> parent. */
14
+ export type EdgeKind = 'inject' | 'provider' | 'nesting';
15
+ /** Where a plugin's code is: the file to open, whether it is inside the app's folder (the Files tab opens only those), and the folder the plugin lives in. */
16
+ export interface GraphSource {
17
+ /** Absolute path of the plugin's main file. */
18
+ readonly file: string;
19
+ /** Absolute path of its folder (the package folder for an installed package). */
20
+ readonly folder: string;
21
+ /** The file relative to the app's folder, when it is inside it: the path the Files tab opens. */
22
+ readonly inApp?: string;
23
+ }
24
+ /** One plugin fiber (or a disabled Loader row) in the graph. */
25
+ export interface GraphNode {
26
+ /** Registry-unique fiber id (0 = root); a synthetic negative id for a disabled row with no fiber. */
27
+ readonly uid: number;
28
+ /** Display name (nearest named ancestor, else `root`). */
29
+ readonly name: string;
30
+ readonly phase: NodePhase;
31
+ /** Whether the owning Loader row is enabled. */
32
+ readonly enabled: boolean;
33
+ /** Exact module specifier the Loader entry imports, when this fiber/row owns one. */
34
+ readonly moduleName: string | null;
35
+ /** Stable Loader entry id owning this fiber, when it maps to one. */
36
+ readonly loaderEntryId: string | null;
37
+ /** Service names this fiber currently provides into the shared store. */
38
+ readonly provides: readonly string[];
39
+ /** Labels of this fiber's top-level live effects (registrations, listeners, timers...). */
40
+ readonly effects: readonly string[];
41
+ /** Where its code is, when the Host could find it. */
42
+ readonly source?: GraphSource;
43
+ }
44
+ /** One relation between two fibers. */
45
+ export interface GraphEdge {
46
+ readonly kind: EdgeKind;
47
+ readonly from: number;
48
+ readonly to: number;
49
+ /** For `inject` / `provider`: the service name. */
50
+ readonly service?: string;
51
+ /** For `inject`: whether the required service resolved to an active provider. */
52
+ readonly resolved?: boolean;
53
+ }
54
+ /** Point-in-time relation graph of one Cordis context. */
55
+ export interface GraphSnapshot {
56
+ readonly capturedAt: string;
57
+ /** `host` for the frame's Host (the app's plugins run there), `client` for the browser's. */
58
+ readonly plane: string;
59
+ readonly nodes: readonly GraphNode[];
60
+ readonly edges: readonly GraphEdge[];
61
+ }
62
+ /** The change a fiber went through, as the Host saw it: created, removed, or moved from one phase to another. */
63
+ export interface GraphEvent {
64
+ /** 1, 2, 3...: the order the Host saw them in; a browser asks for those after the last number it has. */
65
+ readonly seq: number;
66
+ /** Epoch ms. */
67
+ readonly at: number;
68
+ readonly uid: number;
69
+ readonly name: string;
70
+ readonly kind: 'created' | 'removed' | 'status';
71
+ readonly from?: NodePhase;
72
+ readonly to?: NodePhase;
73
+ }
74
+ export interface GraphView {
75
+ readonly snapshot: GraphSnapshot;
76
+ /** The newest event number when the snapshot was taken: the browser asks for events after it. */
77
+ readonly seq: number;
78
+ }
79
+ export interface GraphEventsAnswer {
80
+ /** The newest event number now. */
81
+ readonly seq: number;
82
+ readonly events: readonly GraphEvent[];
83
+ }
84
+ export declare function parseGraphView(value: unknown): GraphView;
85
+ export declare function parseGraphEvents(value: unknown): GraphEventsAnswer;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Reading a live Cordis context into a plugin graph: every fiber, the disabled Loader rows, and the relations between them (requires, provides to, nested in).
3
+ * Ported from cordis-plugin-graph (MIT, github.com/cordisplugins/cordis-plugin-graph, commit e9bf6b5, `src/inspect.ts`): the same walk of the public Cordis and
4
+ * Loader API, with a `source` on each node added. It imports nothing from Node, so the Host reads its own context with it and the browser reads the
5
+ * client's (the two planes).
6
+ */
7
+ import type { Context } from '@deepseek-ai/cordis';
8
+ import type { EdgeKind, GraphSnapshot, GraphSource, NodePhase } from './graph-contract.ts';
9
+ export declare const PHASE: Record<number, NodePhase>;
10
+ /** Where a node's code is, found from what the Loader entry names; undefined when it cannot be found. */
11
+ export type SourceOf = (moduleName: string | null, name: string) => GraphSource | undefined;
12
+ export declare const clamp: (value: string) => string;
13
+ /** The current Cordis graph of `ctx`: every fiber, the disabled Loader rows, and the three kinds of relation. */
14
+ export declare function inspectCordisContext(ctx: Context, plane: string, sourceOf?: SourceOf): GraphSnapshot;
15
+ /** The relation kinds, for the browser's toggles. */
16
+ export declare const EDGE_KINDS: readonly EdgeKind[];
package/package.json CHANGED
@@ -1,6 +1,127 @@
1
1
  {
2
2
  "name": "@acryldev/blends-frame",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.0",
4
+ "description": "ACRYL Blends frame: the workbench around an app being built - a top bar, the branches and versions on the left, the app alone in the centre, and the agents on the right - as one Cordis plugin with a Host and a client half",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/acryldev/acryl.git",
9
+ "directory": "plugins/blends-frame"
10
+ },
11
+ "homepage": "https://github.com/acryldev/acryl/tree/main/plugins/blends-frame#readme",
12
+ "bugs": {
13
+ "url": "https://github.com/acryldev/acryl/issues"
14
+ },
15
+ "type": "module",
16
+ "main": "lib/index.js",
17
+ "types": "lib/index.d.ts",
18
+ "exports": {
19
+ ".": {
20
+ "types": "./lib/index.d.ts",
21
+ "default": "./lib/index.js"
22
+ },
23
+ "./app-generation": {
24
+ "types": "./lib/app-generation.d.ts",
25
+ "default": "./lib/app-generation.js"
26
+ },
27
+ "./client": {
28
+ "types": "./lib/types/client/index.d.ts",
29
+ "default": "./lib/client.js"
30
+ },
31
+ "./package.json": "./package.json"
32
+ },
33
+ "dsh": {
34
+ "bundle": {
35
+ "patch": "./cordis.patch.yml"
36
+ },
37
+ "client": {
38
+ "inject": [
39
+ "@deepseek-ai/dsh-client-ui-slots",
40
+ "@deepseek-ai/dsh-client-ui-theme"
41
+ ],
42
+ "platform": "web"
43
+ }
44
+ },
45
+ "files": [
46
+ "cordis.patch.yml",
47
+ "lib/**",
48
+ "README.md",
49
+ "LICENSE"
50
+ ],
51
+ "engines": {
52
+ "node": "^22.19.0 || >=24.0.0"
53
+ },
54
+ "dependencies": {
55
+ "@acryldev/blends-core": "^0.6.0",
56
+ "@acryldev/plugin-hub-core": "^0.2.2",
57
+ "@acryldev/app-shell": "0.2.0",
58
+ "@acryldev/loopback-http": "0.2.0",
59
+ "@acryldev/versions": "0.2.0",
60
+ "@acryldev/workspace": "0.2.0",
61
+ "yaml": "2.9.0"
62
+ },
63
+ "peerDependencies": {
64
+ "@deepseek-ai/cordis": "^4.0.2",
65
+ "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
66
+ "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
67
+ "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
68
+ "@acryldev/blends": "^1.0.0",
69
+ "react": "18.3.1",
70
+ "react-dom": "18.3.1"
71
+ },
72
+ "devDependencies": {
73
+ "@acryldev/ui": "0.4.0",
74
+ "@deepseek-ai/cordis": "4.0.4",
75
+ "@deepseek-ai/cordis-plugin-loader": "1.0.5",
76
+ "@deepseek-ai/dsh-client-modules": "0.2.0-rc.2",
77
+ "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.2",
78
+ "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
79
+ "@deepseek-ai/dsh-client-ui-sidebar": "0.2.0-rc.2",
80
+ "@deepseek-ai/dsh-client-ui-sidebar-right": "0.2.0-rc.2",
81
+ "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
82
+ "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
83
+ "@testing-library/dom": "^10.4.1",
84
+ "@testing-library/react": "^16.3.2",
85
+ "@types/cytoscape": "3.31.0",
86
+ "@types/node": "^24.0.0",
87
+ "@types/react": "^18",
88
+ "@types/react-dom": "^18",
89
+ "@acryldev/blends": "1.7.0",
90
+ "cytoscape": "3.34.3",
91
+ "jsdom": "29.1.1",
92
+ "react": "18.3.1",
93
+ "react-dom": "18.3.1",
94
+ "tsdown": "0.23.0",
95
+ "typescript": "6.0.3",
96
+ "vitest": "5.0.3"
97
+ },
98
+ "acryl": {
99
+ "schemaVersion": 1,
100
+ "artifacts": {
101
+ "plugins": [
102
+ "./lib/index.js",
103
+ "./lib/client.js"
104
+ ]
105
+ },
106
+ "surfaces": [
107
+ "web"
108
+ ],
109
+ "runtime": "cordis",
110
+ "compatibility": {
111
+ "acryl": ">=0.1.0 <1.0.0",
112
+ "node": "^22.19.0 || >=24.0.0",
113
+ "hosts": {
114
+ "@deepseek-ai/cordis": "^4.0.2"
115
+ }
116
+ },
117
+ "capabilities": [
118
+ "blends-frame"
119
+ ]
120
+ },
121
+ "scripts": {
122
+ "build": "node scripts/clean.mjs && tsdown && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.client.json --emitDeclarationOnly",
123
+ "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit && tsc -p tsconfig.tests.json --noEmit",
124
+ "test": "vitest run",
125
+ "check": "pnpm run build && pnpm run typecheck && pnpm run test"
126
+ }
6
127
  }