@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,81 @@
1
+ /**
2
+ * Settings → Plugins (docs/design/blends-frame-mockup.html): everything the app is made of, in one list, all read from the frame's Host: the
3
+ * app's plugins (`blend.yaml` rows and what was written into `plugins/`) and the frame's own Loader rows. A switch writes where the plugin is
4
+ * chosen; the Host then starts the app's plugins again, and the canvas loads the app page again.
5
+ */
6
+ import { type AppPluginKind, type AppPluginsView, type AppPluginView, type FramePluginView, type SavedPluginResult, type SavedPluginView, type ShareVisibility, type SharedPluginView, type SharePlan } from '../contract.ts';
7
+ /** Where a share goes: a private repository (the team), a public one (everyone), or a public one the registry lists. */
8
+ export type ShareTarget = ShareVisibility | 'registry';
9
+ /** Sharing a local plugin: first what it would do, then, on the person's yes, exactly that. */
10
+ export interface PluginShare {
11
+ plan(target?: ShareTarget): Promise<SharePlan>;
12
+ publish(confirmed: SharePlan): Promise<SharedPluginView>;
13
+ }
14
+ /** What the person can do with one local plugin besides sharing it: keep a packed copy on this machine, and look at its code. */
15
+ export interface PluginActions {
16
+ /** Keep a packed copy in this app's plugin store; nothing leaves the machine. */
17
+ readonly save?: () => Promise<SavedPluginResult>;
18
+ /** Open the plugin's main file in the Files tab. Absent when the file is outside the app. */
19
+ readonly viewSource?: () => void;
20
+ }
21
+ /** The command another app runs to take a shared plugin, from its repository address and version. */
22
+ export declare function pullCommand(shared: SharedPluginView): string | undefined;
23
+ /** What to send a colleague so they can add a shared plugin: the address the Registry tab's "Add by address" takes. */
24
+ export declare function colleagueAddress(shared: SharedPluginView): string | undefined;
25
+ /**
26
+ * The question a share asks before anything is sent, in plain words: who will be able to use the plugin, and (for a repeated share) that this is the next
27
+ * version. Nothing technical: the repository, license and labels are in {@link shareDetails}.
28
+ */
29
+ export declare function shareQuestion(plan: SharePlan): string;
30
+ /** The words on the one big button that confirms a share. */
31
+ export declare function shareButton(plan: SharePlan): string;
32
+ /** The exact sentence of what a share does, for the "Details" of the confirmation: the repository, whether it is created, the version and who can see it. */
33
+ export declare function shareSentence(plan: SharePlan): string;
34
+ /** What a developer wants to see behind "Details": where it goes and under what terms. One short line each. */
35
+ export declare function shareDetails(plan: SharePlan): string[];
36
+ /** Which filter chip a plugin falls under. */
37
+ export type PluginGroup = 'made' | 'registry' | 'frame';
38
+ export interface NavigatorPlugin {
39
+ /** Unique across groups: `app:<name>` or `frame:<entryId>`. */
40
+ readonly key: string;
41
+ readonly name: string;
42
+ readonly group: PluginGroup;
43
+ /** The badge: who made it ("Claude · today"), "registry", "frame". */
44
+ readonly by: string;
45
+ readonly description: string;
46
+ readonly on: boolean;
47
+ /** Shown after the description: "active", "off", "not saved yet", "failed". */
48
+ readonly state: string;
49
+ /** Where a local plugin was shared: its repository and released version. */
50
+ readonly shared?: SharedPluginView;
51
+ /** The newest packed copy kept on this machine. */
52
+ readonly saved?: SavedPluginView;
53
+ /** Absolute path of the plugin's folder, shown small on the card. */
54
+ readonly folder?: string;
55
+ /** What the person can do with it besides share it (save here, view the code). */
56
+ readonly actions?: PluginActions;
57
+ /** Publish this local plugin so another app can install it, after the person confirms its plan. Absent when the row cannot be shared here. */
58
+ readonly share?: PluginShare;
59
+ /** Absent when the plugin cannot be switched here (the frame's protected rows). */
60
+ readonly toggle?: (on: boolean) => Promise<void>;
61
+ }
62
+ /** "today", "yesterday", "Mon", or "12 Oct" for an older day. */
63
+ export declare function madeWhen(at: string, now?: Date): string;
64
+ export declare function appPluginRow(plugin: AppPluginView, toggle: (on: boolean) => Promise<void>, share?: PluginShare, now?: Date, actions?: PluginActions): NavigatorPlugin;
65
+ /** One of the frame's own plugins: shown with its state, switched only by changing the frame. */
66
+ export declare function framePluginRow(plugin: FramePluginView, actions?: PluginActions): NavigatorPlugin;
67
+ /** The plugins a search and a chip leave. */
68
+ export declare function filterPlugins(plugins: readonly NavigatorPlugin[], query: string, group: PluginGroup | 'all'): NavigatorPlugin[];
69
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
70
+ export interface AppPluginsApi {
71
+ read(): Promise<AppPluginsView>;
72
+ switch(kind: AppPluginKind, name: string, on: boolean): Promise<void>;
73
+ /** What sharing one local plugin would do (private unless `visibility` says public); nothing is sent. */
74
+ planShare(name: string, target?: ShareTarget): Promise<SharePlan>;
75
+ /** Share one local plugin as the person confirmed it; answers where it went. */
76
+ share(name: string, confirmed: SharePlan): Promise<SharedPluginView>;
77
+ /** Keep a packed copy of one local plugin on this machine. */
78
+ save(name: string): Promise<SavedPluginResult>;
79
+ }
80
+ export declare function createAppPluginsApi(fetcher?: FetchLike): AppPluginsApi;
81
+ export {};
@@ -0,0 +1,21 @@
1
+ /** The registry, adding a plugin and the GitHub check, as the page asks the frame's Host for them (see `../registry.ts`, `../plain.ts`). */
2
+ import { type GithubConnectState, type GithubReadiness, type PulledPluginView, type RegistryView } from '../contract.ts';
3
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
4
+ export interface RegistryApi {
5
+ /** The public registry with the plugins this app already has marked; an unreadable registry is an answer, not a failure. */
6
+ registry(): Promise<RegistryView>;
7
+ /** Add one released plugin (`github:<owner>/<repo>@<version>`) to the running app. @throws PlainFailure with why it was refused. */
8
+ add(source: string): Promise<PulledPluginView>;
9
+ /** Whether this computer can share to GitHub now. */
10
+ github(): Promise<GithubReadiness>;
11
+ /** Connect GitHub from the app: GitHub's own browser sign-in, which gives a one-time code for github.com/login/device. */
12
+ readonly connect: GithubConnectApi;
13
+ }
14
+ export interface GithubConnectApi {
15
+ /** Start the sign-in (or rejoin the one waiting); answers with the code once GitHub gave it. */
16
+ start(): Promise<GithubConnectState>;
17
+ /** Where the sign-in is now. */
18
+ state(): Promise<GithubConnectState>;
19
+ }
20
+ export declare function createRegistryApi(fetcher?: FetchLike): RegistryApi;
21
+ export {};
@@ -0,0 +1,18 @@
1
+ /** What the Registry tab lists and how it words one row: pure, so the rules are tested without a page. */
2
+ import type { PulledPluginView, RegistryEntryView, RegistryOrigin } from '../contract.ts';
3
+ /** A plugin for a different kind of app (a stock DeepSeek Harness plugin) cannot run in a Blends app; it is hidden until the person asks to see all. */
4
+ export declare const forOtherApps: (entry: RegistryEntryView) => boolean;
5
+ /** All (the default), or only official or only community entries. */
6
+ export type OriginFilter = 'all' | RegistryOrigin;
7
+ /** The entries a search shows: by name, description or owner, every word of it; the ones for other apps only when asked. Order is kept. */
8
+ export declare function filterRegistry(entries: readonly RegistryEntryView[], query: string, showAll: boolean, origin?: OriginFilter): RegistryEntryView[];
9
+ /** The address a person can type or paste: `github:<owner>/<repo>@<version>`; leading and trailing space is ignored. */
10
+ export declare function cleanAddress(text: string): string | undefined;
11
+ /** A download size the way a person reads it: whole megabytes (1 MB = 1,000,000 bytes, as npm and the Blends pages count). */
12
+ export declare const megabytes: (bytes: number) => string;
13
+ /** The question before anything is added: whose code it is (a community plugin says so: nobody at ACRYL reviewed it), and what it downloads for this computer. */
14
+ export declare const addQuestion: (name: string, owner: string, download?: number, origin?: RegistryOrigin) => string;
15
+ /** The answer after an add. */
16
+ export declare function addedText(pulled: PulledPluginView): string;
17
+ /** One line under a row: who released it, which version and when. */
18
+ export declare const entryByline: (entry: RegistryEntryView) => string;
@@ -0,0 +1,56 @@
1
+ /**
2
+ * An element the person picked in the app canvas, and the context the next chat message carries for it
3
+ * (docs/design/blends-frame-mockup.html, scenario 2, "Building with the chat"). The frame owns the picker and the chip above the
4
+ * composer; the send gesture hands the pick to the frame's Host, which gives it to the agent as context for that message, so the person's own
5
+ * bubble keeps exactly their words.
6
+ */
7
+ /** One element picked in the app's page. `page` is the app path the canvas shows, with its query. */
8
+ export interface SelectedElement {
9
+ readonly label: string;
10
+ readonly selector: string;
11
+ readonly page: string;
12
+ }
13
+ /** What the frame knows about the selected element; the chip and the send hook read it. */
14
+ export declare class SelectionStore {
15
+ private snapshot;
16
+ private readonly listeners;
17
+ getSnapshot(): {
18
+ readonly selection: SelectedElement | undefined;
19
+ };
20
+ subscribe(listener: () => void): () => void;
21
+ select(element: SelectedElement): void;
22
+ clear(): void;
23
+ private publish;
24
+ }
25
+ /**
26
+ * A short name for an element: what it says it is, else its heading, else the first words it shows (a card's title, not its title run into the
27
+ * line under it), else its tag (plugins/feedback/client.js).
28
+ */
29
+ export declare function elementLabel(element: Element): string;
30
+ /** A CSS selector that finds the element again: up from it to the nearest id, each step its tag and place among its siblings. */
31
+ export declare function elementSelector(element: Element): string;
32
+ /** The element under a click, described as the chat will carry it; `page` is the app page's path and query. */
33
+ export declare function selectedElement(element: Element, page: string): SelectedElement;
34
+ /** Whether a draft carries a chat message the pick belongs to: it has words and is not a slash command (those are not chat messages). */
35
+ export declare function carriesSelection(draft: string): boolean;
36
+ /** What the frame's Host reads for one pick: the chat it belongs to and the element itself. */
37
+ export interface SelectionPost {
38
+ readonly session: string;
39
+ readonly label: string;
40
+ readonly page: string;
41
+ readonly selector: string;
42
+ }
43
+ /** The body one send gesture posts for its pick. */
44
+ export declare function selectionPost(session: string, element: SelectedElement): SelectionPost;
45
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
46
+ /**
47
+ * Hand the pick to the frame's Host at the person's send gesture, before the composer sends: the Host attaches it to the step that reads this
48
+ * message and never writes it into the message (./selection-context.ts on the Host side). Nothing awaits the answer, so every send gesture keeps
49
+ * working and a hand-off that fails costs only the context, never the person's message.
50
+ * @param fetcher - the page's fetch.
51
+ * @param session - the chat being sent to.
52
+ * @param element - the picked element.
53
+ * @returns whether the Host took it; the frame does not wait for this to send.
54
+ */
55
+ export declare function handOffSelection(fetcher: FetchLike, session: string, element: SelectedElement): Promise<boolean>;
56
+ export {};
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Whether DSH's Settings window fills the browser window, and the browser's memory of it. The window itself is DSH's; the frame only marks the body
3
+ * (`data-bf-settings-full`, which styles.ts and graph-styles.ts read) and keeps the choice, so the next time Settings opens it opens the same way.
4
+ */
5
+ export declare const SETTINGS_FULL_ATTRIBUTE = "data-bf-settings-full";
6
+ export declare const SETTINGS_FULL_KEY = "acrylBlends.settingsFull";
7
+ type Store = Pick<Storage, 'getItem' | 'setItem'>;
8
+ /** The remembered choice; false when nothing is remembered or the storage cannot be read. */
9
+ export declare function readSettingsFull(store?: Store | undefined): boolean;
10
+ export declare function writeSettingsFull(full: boolean, store?: Store | undefined): void;
11
+ /** Mark (or unmark) the body so the Settings window styles take effect. */
12
+ export declare function markSettingsFull(full: boolean, body?: HTMLElement): void;
13
+ export {};
@@ -0,0 +1,36 @@
1
+ /**
2
+ * DSH's right sidebar (`dsh-client-ui-sidebar-right`) is drawn in the right panel's Panel tab. When something opens a page in it (a Plan card's button,
3
+ * a file of a turn's changes, a file an answer names) the person has to see it, so the Panel tab comes forward. The layout only says whether the sidebar
4
+ * is shown, which does not change when it already is; what changes on every open is the opened tab's navigation record, whose `revision` DSH increments
5
+ * on each navigation to it (`SidebarRightTabNavigation`), including a page that was already open.
6
+ */
7
+ /** The part of DSH's `SidebarRightController` an open is read from. */
8
+ export interface SidebarRightOpens {
9
+ /** Every open tab of every session, published on each change. */
10
+ readonly openTabs: {
11
+ getSnapshot(): readonly {
12
+ readonly sessionId: string;
13
+ readonly tabId: string;
14
+ }[];
15
+ subscribe(listener: () => void): () => void;
16
+ };
17
+ readonly tabDomain: {
18
+ /** @throws while the tab has no navigation record yet (it is being opened, or its session is not on screen). */
19
+ occurrence(sessionId: string, tab: {
20
+ readonly id: string;
21
+ }): {
22
+ readonly navigation: {
23
+ getSnapshot(): {
24
+ readonly revision: number;
25
+ };
26
+ subscribe(listener: () => void): () => void;
27
+ };
28
+ };
29
+ };
30
+ }
31
+ /**
32
+ * Call `opened` on every open in the sidebar after this call. The tabs already there, and those a session brings back from its saved layout (revision 0),
33
+ * are not opens.
34
+ * @returns the disposer.
35
+ */
36
+ export declare function watchSidebarOpens(sidebar: SidebarRightOpens, opened: () => void): () => void;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * The capture a Save point starts with: the app's snapshot verb `capture` on the frame's Host, so every version is a captured snapshot.
3
+ */
4
+ import { type SnapshotCapture } from '../contract.ts';
5
+ export interface SnapshotPort {
6
+ /** Undefined when the app was made before the snapshot verbs. @throws the Host's one line (a `blend.yaml` that does not parse). */
7
+ capture(): Promise<SnapshotCapture | undefined>;
8
+ }
9
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
10
+ export declare function createSnapshotApi(fetcher?: FetchLike): SnapshotPort;
11
+ export {};
@@ -0,0 +1,3 @@
1
+ /** The frame's look, taken from the owner's mockup (docs/design/blends-frame-mockup.html): a dark workbench around the app's own light page. */
2
+ /** @returns disposer, for one owning `ctx.effect`. */
3
+ export declare function installFrameStyles(): () => void;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * A chat that lives on another branch, asked for from somewhere other than the left panel (the chat's History): the left panel owns the switch, with its
3
+ * save point and its guard, so the History hands the request to it instead of switching by itself.
4
+ */
5
+ export interface SwitchRequest {
6
+ readonly branch: string;
7
+ /** The chat to open once the folder has moved. */
8
+ readonly chat: string;
9
+ }
10
+ export declare class SwitchRequests {
11
+ private pending;
12
+ private readonly listeners;
13
+ getSnapshot(): SwitchRequest | undefined;
14
+ subscribe(listener: () => void): () => void;
15
+ request(request: SwitchRequest): void;
16
+ /** The left panel took the request. */
17
+ clear(): void;
18
+ }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * The right panel's tab strip sizing (412px wide beside the canvas): every open chat has a tab, so several chats and tools have to share that width instead
3
+ * of running past its edge and clipping their labels. Each tab takes an equal share of the strip between a minimum and a maximum; a label that does not fit
4
+ * ellipsizes inside its tab, the model or agent kind ("DeepSeek", "PTY") is dropped when the share is too narrow for it, and when even the minimums do not
5
+ * fit the strip scrolls with the tabs at the minimum. The rule is pure so the one-tab case and the crowded ones are checked without a browser.
6
+ */
7
+ export interface TabSizingOptions {
8
+ /** The least a tab may take; below this the strip scrolls. */
9
+ readonly min?: number;
10
+ /** The most one tab takes, however wide the panel. */
11
+ readonly max?: number;
12
+ /** The gap between tabs. */
13
+ readonly gap?: number;
14
+ /** The + button at the strip's right edge, which keeps its width. */
15
+ readonly plus?: number;
16
+ /** The narrowest tab that still has room for its kind beside the label. */
17
+ readonly kindMin?: number;
18
+ }
19
+ /** One tab's size and the strip's behavior at a given width. */
20
+ export interface TabSizing {
21
+ /** The most one tab may take. */
22
+ readonly width: number;
23
+ /** Whether the strip has to scroll: the minimums do not fit. */
24
+ readonly scroll: boolean;
25
+ /** Whether a tab shows its kind ("DeepSeek", "PTY") beside the label. */
26
+ readonly kind: boolean;
27
+ }
28
+ /** The frame's sizes: five tabs fit the 412px panel at the minimum without scrolling. */
29
+ export declare const TAB_SIZING: Required<TabSizingOptions>;
30
+ /** The tab strip's sizing for `count` tabs in a strip `stripWidth` px wide. */
31
+ export declare function tabSizing(stripWidth: number, count: number, options?: TabSizingOptions): TabSizing;
@@ -0,0 +1,139 @@
1
+ /**
2
+ * The right panel's tabs (docs/design/blends-frame-mockup.html): the chat, PTY agents (Claude Code, Codex, Pi as they are, in a terminal), a
3
+ * terminal, Files, a file opened from it, and Git. One store for the right panel's strip and the left panel's open items; remembered per page.
4
+ * A terminal tab names the Host's PTY session, which outlives the page, so a reload shows the same terminal again. Every tab but the chat belongs
5
+ * to the branch it was opened on: the strip shows the checked-out branch's tabs, and the others stay (a terminal keeps running) out of the list.
6
+ */
7
+ import type { ViewStorage } from './view-state.ts';
8
+ /** The PTY agents the + menu offers, in its order: their workspace agent ids and labels. */
9
+ export declare const PTY_AGENTS: readonly [{
10
+ readonly agent: "claude";
11
+ readonly label: "Claude Code";
12
+ readonly tab: "Claude";
13
+ }, {
14
+ readonly agent: "codex";
15
+ readonly label: "Codex";
16
+ readonly tab: "Codex";
17
+ }, {
18
+ readonly agent: "pi";
19
+ readonly label: "Pi";
20
+ readonly tab: "Pi";
21
+ }];
22
+ export type PtyAgent = (typeof PTY_AGENTS)[number]['agent'];
23
+ export type FrameTab =
24
+ /** `chat` is the base tab, always there: the branch's chat. A chat made with "+ then Chat" has a tab of its own, named `chat:<session>`. */
25
+ {
26
+ readonly kind: 'chat';
27
+ readonly id: string;
28
+ readonly session?: string;
29
+ readonly branch?: string;
30
+ } | {
31
+ readonly kind: 'pty';
32
+ readonly id: string;
33
+ readonly agent: PtyAgent;
34
+ readonly terminalId: string;
35
+ readonly branch?: string;
36
+ } | {
37
+ readonly kind: 'terminal';
38
+ readonly id: string;
39
+ readonly terminalId: string;
40
+ readonly branch?: string;
41
+ } | {
42
+ readonly kind: 'files';
43
+ readonly id: 'files';
44
+ readonly branch?: string;
45
+ } | {
46
+ readonly kind: 'file';
47
+ readonly id: string;
48
+ readonly path: string;
49
+ readonly branch?: string;
50
+ } | {
51
+ readonly kind: 'git';
52
+ readonly id: 'git';
53
+ readonly branch?: string;
54
+ }
55
+ /**
56
+ * DSH's right sidebar (`ui-sidebar-right`): the Plan, the changed-files review and the files an answer links to, as DSH draws them. It shows the chat on
57
+ * screen, whatever the branch, so it is on every branch like the base chat tab.
58
+ */
59
+ | {
60
+ readonly kind: 'details';
61
+ readonly id: 'details';
62
+ readonly branch?: string;
63
+ };
64
+ export interface FrameTabsSnapshot {
65
+ readonly tabs: readonly FrameTab[];
66
+ readonly active: string;
67
+ /**
68
+ * The base chat tab's x was pressed: its chat was closed like any chat tab's, and the strip keeps the tab away until a chat is opened again.
69
+ * Absent means open, the first-run state.
70
+ */
71
+ readonly baseClosed?: boolean;
72
+ /**
73
+ * What each terminal says it runs (its title, as a shell sets it: `npm test`), by terminal id. Remembered, so a terminal row still says what ran in it
74
+ * after the page reloads or the Host restarts and the shell that set the title is gone.
75
+ */
76
+ readonly titles?: Readonly<Record<string, string>>;
77
+ }
78
+ /** The first run: the chat alone. */
79
+ export declare const FIRST_RUN_TABS: FrameTabsSnapshot;
80
+ export declare const chatTab: (session: string) => FrameTab;
81
+ export declare const ptyTab: (agent: PtyAgent, terminalId: string) => FrameTab;
82
+ export declare const terminalTab: (terminalId: string) => FrameTab;
83
+ export declare const fileTab: (path: string) => FrameTab;
84
+ export declare const FILES_TAB: FrameTab;
85
+ export declare const GIT_TAB: FrameTab;
86
+ export declare const DETAILS_TAB: FrameTab;
87
+ /**
88
+ * What each file tab calls itself: the file's name, or as much of its folder as it takes to tell it from the other file tabs open beside it. Two
89
+ * `index.ts` in different folders read `team-board/index.ts` and `src/index.ts`; a name no other tab shares keeps its file name alone.
90
+ */
91
+ export declare function fileTabLabels(paths: readonly string[]): ReadonlyMap<string, string>;
92
+ /**
93
+ * The tabs the strip shows on a branch: the base chat (unless its x closed it), and what was opened on that branch. No branch (outside a repository):
94
+ * every tab.
95
+ */
96
+ export declare function tabsForBranch(snapshot: FrameTabsSnapshot, branch: string | undefined): readonly FrameTab[];
97
+ /** A remembered strip, or the first run's when it is missing or malformed. The chat is always there, first. */
98
+ export declare function parseStoredTabs(raw: string | null): FrameTabsSnapshot;
99
+ /** The tab a terminal session shows in, if one does. */
100
+ export declare function tabOfTerminal(snapshot: FrameTabsSnapshot, terminalId: string): FrameTab | undefined;
101
+ export declare class FrameTabs {
102
+ private readonly storage?;
103
+ private snapshot;
104
+ private readonly listeners;
105
+ /** The checked-out branch the strip is showing; new tabs are opened on it. */
106
+ private branch;
107
+ /** Whether the remembered tabs already went through the branch migration (see `setBranch`). */
108
+ private branched;
109
+ constructor(storage?: ViewStorage | undefined);
110
+ getSnapshot(): FrameTabsSnapshot;
111
+ subscribe(listener: () => void): () => void;
112
+ /**
113
+ * The checked-out branch. The first time it is known, the tabs remembered before branches had their own lists (every tab carried no branch) are
114
+ * put on that branch, which is where they were opened as far as anyone can tell; later calls only change where new tabs go.
115
+ */
116
+ setBranch(branch: string | undefined): void;
117
+ /** Show a tab, adding it at the end of the strip when it is not open yet; a tab opened now belongs to the checked-out branch. */
118
+ open(tab: FrameTab): void;
119
+ /** Add tabs that are not in the strip yet, at the end, without showing them; a tab added now belongs to the checked-out branch. */
120
+ add(...added: readonly FrameTab[]): void;
121
+ activate(id: string): void;
122
+ /** The id of the tab that shows a chat: its own when it has one, else the base chat tab. */
123
+ chatTabId(session: string): string;
124
+ /**
125
+ * Close a tab; the one before it is shown when it was. The base chat tab closes like any other (its chat is closed by the panel, and the tab
126
+ * returns when a chat is opened again). @returns the closed tab.
127
+ */
128
+ close(id: string): FrameTab | undefined;
129
+ /** Close the chat tabs of chats that are not open (a chat closed on another page, or before this strip was remembered). @returns whether any closed. */
130
+ closeChatsNotIn(open: ReadonlySet<string>): boolean;
131
+ /** A terminal's program set its title; remembered with the strip, so the row still says what ran there after a reload or a Host restart. */
132
+ setTitle(terminalId: string, title: string): void;
133
+ private set;
134
+ }
135
+ /**
136
+ * What a terminal row says it runs: the command a shell put in its title (`npm test`); an idle prompt's `user@host:/path/app` title says only
137
+ * the folder (`app`).
138
+ */
139
+ export declare function terminalMeta(title: string | undefined): string;
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The top bar's Dark/Light switch. DSH's theme service owns the preference (light, dark or system, saved in the user's settings and following the OS
3
+ * while it is `system`); this reads the colour scheme it resolved and flips it with `setTheme`, so the button, Settings > General > Appearance and the
4
+ * OS all drive the same one value. Nothing here touches the DOM: the theme presenter paints the body, and the frame's styles follow it.
5
+ */
6
+ export type ColorScheme = 'light' | 'dark';
7
+ /** The part of DSH's theme service this reads. */
8
+ export interface ThemeSource {
9
+ getTheme(): {
10
+ readonly active: {
11
+ readonly colorScheme: ColorScheme;
12
+ };
13
+ };
14
+ setTheme(id: string): void;
15
+ }
16
+ export declare class ThemeSwitch {
17
+ private readonly theme;
18
+ private scheme;
19
+ private readonly listeners;
20
+ constructor(theme: ThemeSource);
21
+ getSnapshot: () => ColorScheme;
22
+ subscribe: (listener: () => void) => (() => void);
23
+ /** Reads the scheme again after the theme service said it changed. */
24
+ refresh(): void;
25
+ /** Switches to the other scheme and keeps it (an explicit choice replaces `system`). */
26
+ toggle(): void;
27
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * The right panel's tools, from the workspace's reusable client layers (`acryl-workspace/ui`): the live terminal sessions and the PTY, files and
3
+ * git routes its Host half serves (run by this frame's Host, see `../index.ts`). Built once per client activation; the effect that builds it
4
+ * releases the sessions.
5
+ */
6
+ import { TerminalRegistry, type WorkspaceFilesApi, type WorkspaceGitApi, type WorkspacePtyApi } from '@acryldev/workspace/ui';
7
+ export interface FrameTools {
8
+ readonly terminals: TerminalRegistry;
9
+ readonly pty: WorkspacePtyApi;
10
+ readonly files: WorkspaceFilesApi;
11
+ readonly git: WorkspaceGitApi;
12
+ }
13
+ export declare function createFrameTools(): FrameTools;
14
+ /** xterm's own stylesheet, once per page. @returns disposer, for one owning `ctx.effect`. */
15
+ export declare function installXtermStyles(): () => void;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * The versions the left panel lists, through `acryl-versions`: the calls it makes, how a version is numbered, how its time reads, and which
3
+ * versions are shared (also on another branch or the remote, which the frame's Host answers).
4
+ */
5
+ import type { VersionsEntry, VersionsLogView } from '@acryldev/versions';
6
+ export interface VersionsPort {
7
+ log(path: string): Promise<VersionsLogView>;
8
+ save(path: string, message: string): Promise<unknown>;
9
+ /** Put the app back to a version as a new version on top (history is never rewritten), then show it: the frame state read again, the app page reloaded. */
10
+ restore(path: string, hash: string, message: string): Promise<unknown>;
11
+ /** The versions that are also on another local branch or a remote-tracking branch. */
12
+ shared(hashes: readonly string[]): Promise<readonly string[]>;
13
+ }
14
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
15
+ export interface SharedVersionsApi {
16
+ /** @throws when the Host does not answer the shared check. */
17
+ shared(hashes: readonly string[]): Promise<readonly string[]>;
18
+ }
19
+ export declare function createSharedVersionsApi(fetcher?: FetchLike): SharedVersionsApi;
20
+ /** "v7" for the newest of seven versions: the number counts from the first. */
21
+ export declare function versionNumber(entries: readonly VersionsEntry[], index: number): number;
22
+ /** "saved" when nothing changed since the last version, else how many files did; nothing outside a repository. */
23
+ export declare function savedLabel(unsaved: number | undefined): string | undefined;
24
+ /** The versions list's short time: "now", "2 min", "2 h", the weekday within a week ("Sun"), then days ("9 d"). */
25
+ export declare function shortTime(at: string, now?: number): string;
26
+ /** A chat's "last active" in the same short form as a version's time; empty when DSH did not say. */
27
+ export declare function chatTime(updatedAt: number | undefined, now?: number): string;
28
+ /** The new version's name when the app goes back to one: "Back to v2 · Due dates". */
29
+ export declare function backToMessage(number: number, subject: string): string;
30
+ /** The save point made first when files are unsaved. */
31
+ export declare function saveBeforeBackMessage(number: number): string;
32
+ /** What the confirmation says; with unsaved files (or an uncounted tree) it says a save point comes first. */
33
+ export declare function backText(number: number, subject: string, unsaved: number | undefined): string;
34
+ export {};
@@ -0,0 +1,42 @@
1
+ /**
2
+ * The frame's own view: which panels are open, their widths and which mode it is in. Both panels open on the first run; after that the person's choice
3
+ * is remembered in the page's storage. The frame's page is the app's own origin (its own port), so the widths are the app's own: another app has its
4
+ * own storage, and a restart keeps them. A storage that throws (a private window, blocked site data) only costs the memory.
5
+ */
6
+ import { type PanelSide } from './panel-resize.ts';
7
+ export type FrameMode = 'build' | 'preview';
8
+ export interface FrameView {
9
+ readonly left: boolean;
10
+ readonly right: boolean;
11
+ readonly mode: FrameMode;
12
+ /** The width the person last gave each panel; a collapsed panel keeps its own and returns at it. */
13
+ readonly leftWidth: number;
14
+ readonly rightWidth: number;
15
+ }
16
+ export declare const FIRST_RUN_VIEW: FrameView;
17
+ /** A stored view, or the first-run view for anything absent or malformed. A stored view from before the resize keeps its panels and gets the defaults. */
18
+ export declare function parseStoredView(raw: string | null): FrameView;
19
+ export interface ViewStorage {
20
+ getItem(key: string): string | null;
21
+ setItem(key: string, value: string): void;
22
+ }
23
+ export declare class FrameViewState {
24
+ private readonly storage;
25
+ private view;
26
+ private readonly listeners;
27
+ constructor(storage: ViewStorage | undefined);
28
+ getSnapshot(): FrameView;
29
+ subscribe(listener: () => void): () => void;
30
+ toggleLeft(): void;
31
+ toggleRight(): void;
32
+ /** Show the left panel (something in it was asked for); Preview is left for Build, where the panel is. */
33
+ showLeft(): void;
34
+ /** Show the right panel (something was opened in it); Preview is left for Build, where the panel is. */
35
+ showRight(): void;
36
+ setMode(mode: FrameMode): void;
37
+ /** The width a drag settled on; a collapsed panel keeps it for the next time it opens. A click that settled on the same width writes nothing. */
38
+ setWidth(side: PanelSide, width: number): void;
39
+ /** Double-click on the panel's inner edge: the default width comes back. */
40
+ resetWidth(side: PanelSide): void;
41
+ private publish;
42
+ }