@acrylblends/blends-frame 0.1.1 → 0.1.3

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 (38) hide show
  1. package/lib/app-plugins.d.ts +32 -5
  2. package/lib/client.js +31886 -367
  3. package/lib/client.js.map +1 -1
  4. package/lib/contract.d.ts +116 -0
  5. package/lib/github-connect.d.ts +44 -0
  6. package/lib/graph-contract.d.ts +85 -0
  7. package/lib/graph-inspect.d.ts +16 -0
  8. package/lib/index.d.ts +20 -3
  9. package/lib/index.js +1040 -36
  10. package/lib/index.js.map +1 -1
  11. package/lib/plain.d.ts +26 -0
  12. package/lib/plugin-graph.d.ts +38 -0
  13. package/lib/registry.d.ts +71 -0
  14. package/lib/types/client/AppSection.d.ts +10 -0
  15. package/lib/types/client/BlendsFrame.d.ts +7 -1
  16. package/lib/types/client/GraphView.d.ts +22 -0
  17. package/lib/types/client/NameYourApp.d.ts +10 -0
  18. package/lib/types/client/PluginsSection.d.ts +11 -1
  19. package/lib/types/client/RegistryView.d.ts +11 -0
  20. package/lib/types/client/SettingsExpand.d.ts +6 -0
  21. package/lib/types/client/ShareChooser.d.ts +21 -0
  22. package/lib/types/client/desktop-app.d.ts +65 -0
  23. package/lib/types/client/graph-api.d.ts +11 -0
  24. package/lib/types/client/graph-canvas.d.ts +63 -0
  25. package/lib/types/client/graph-link.d.ts +21 -0
  26. package/lib/types/client/graph-model.d.ts +23 -0
  27. package/lib/types/client/graph-styles.d.ts +3 -0
  28. package/lib/types/client/index.d.ts +1 -1
  29. package/lib/types/client/plain-failure.d.ts +10 -0
  30. package/lib/types/client/plugins-navigator.d.ts +37 -7
  31. package/lib/types/client/registry-api.d.ts +21 -0
  32. package/lib/types/client/registry-list.d.ts +14 -0
  33. package/lib/types/client/settings-fullscreen.d.ts +13 -0
  34. package/lib/types/client/theme-switch.d.ts +27 -0
  35. package/lib/types/contract.d.ts +116 -0
  36. package/lib/types/graph-contract.d.ts +85 -0
  37. package/lib/types/graph-inspect.d.ts +16 -0
  38. package/package.json +9 -7
package/lib/plain.d.ts ADDED
@@ -0,0 +1,26 @@
1
+ /**
2
+ * What the person reads when sharing or adding a plugin goes wrong or cannot start: plain words and the one thing to do, never a git line, a stack or a
3
+ * tool's own message. The technical text is kept next to it as `details`, behind a "Details" toggle for developers, so nothing is lost.
4
+ */
5
+ import type { GithubReadiness } from './contract.ts';
6
+ export type { GithubReadiness };
7
+ /** A message for a person and, for a developer, what the tool said. */
8
+ export interface Plain {
9
+ readonly say: string;
10
+ readonly details?: string;
11
+ }
12
+ /** A failure whose message is already for the person; a route answers it as it is. */
13
+ export declare class PlainError extends Error {
14
+ readonly plain: Plain;
15
+ constructor(plain: Plain);
16
+ }
17
+ export declare const GITHUB_MISSING: GithubReadiness;
18
+ export declare const GITHUB_SIGNED_OUT: GithubReadiness;
19
+ /** What a failed tool call says about the person's setup: the helper is not installed, or it is not signed in. */
20
+ export declare function githubProblemOf(message: string): 'missing' | 'signed-out' | undefined;
21
+ /** Read whether sharing to GitHub can work: ask who is signed in. `login` is the host's own check (it throws a tool message when it cannot). */
22
+ export declare function githubReadiness(login: () => string): GithubReadiness;
23
+ /** A share that could not be planned or sent, in words a person can act on. */
24
+ export declare function plainShareProblem(cause: unknown): Plain;
25
+ /** Why a plugin could not be added to the app, by the kind of refusal the app's pull gives (`plugins/plugin-share/pull-check.ts`). */
26
+ export declare function plainPullRefusal(refusal: string, reason: string, next: string): Plain;
@@ -0,0 +1,38 @@
1
+ import type { Context } from '@deepseek-ai/cordis';
2
+ import type { GraphEvent, GraphEventsAnswer, GraphView } from './graph-contract.ts';
3
+ import { type SourceOf } from './graph-inspect.ts';
4
+ export { inspectCordisContext, type SourceOf } from './graph-inspect.ts';
5
+ /** How long a request for events waits for one before it answers with none; the browser asks again at once. */
6
+ export declare const EVENTS_WAIT_MS = 20000;
7
+ /** The recent fiber changes, numbered; a request for those after a number waits for the next change when there are none. */
8
+ export declare class GraphRecorder {
9
+ private seq;
10
+ private readonly events;
11
+ private readonly waiting;
12
+ /** The newest event number; 0 before the first. */
13
+ get head(): number;
14
+ record(event: Omit<GraphEvent, 'seq' | 'at'>, at?: number): void;
15
+ /** Every recorded event after `after`, oldest first. */
16
+ since(after: number): GraphEventsAnswer;
17
+ /** The events after `after`, as soon as there are some; none when `ms` passes first or `signal` aborts (the browser left). */
18
+ wait(after: number, ms: number, signal?: AbortSignal): Promise<GraphEventsAnswer>;
19
+ /** Wake every waiting request now (the Host is stopping); each answers with what it has. */
20
+ release(): void;
21
+ }
22
+ /** Record every fiber of `ctx`'s tree changing: created, removed, or moved to another phase. Returns the stop. */
23
+ export declare function recordFibers(ctx: Context, recorder: GraphRecorder): () => void;
24
+ /**
25
+ * Find where a Loader entry's code is. In the order the app itself finds it: a folder of the app's `plugins/` named like the row, then a path from the app's
26
+ * folder (`./src/frame.ts`), then a package the app or the frame (for the DSH packages, which the frame's own install carries) can resolve.
27
+ */
28
+ export declare function sourceFinder(appRoot: string): SourceOf;
29
+ /** What the routes need: the graph now, and the changes after a number. */
30
+ export interface GraphPort {
31
+ read(): GraphView;
32
+ events(after: number, signal?: AbortSignal): Promise<GraphEventsAnswer>;
33
+ }
34
+ /** The graph of the Host's context, with its recorder started. `stop` ends the recording and answers every waiting request. */
35
+ export declare function createGraphPort(ctx: Context, appRoot: string): {
36
+ readonly port: GraphPort;
37
+ readonly stop: () => void;
38
+ };
@@ -0,0 +1,71 @@
1
+ /**
2
+ * The public plugin registry as the frame reads it. cordisplugins.github.io lists a plugin by its public GitHub repository: the repository has the topic
3
+ * `cordis-plugin` and its latest release has one packed copy; the site's sync finds it within the hour and publishes `registry/index.json`
4
+ * (formatVersion 1, one entry per plugin). This reads that file, on the Host: no token, no GitHub search, and a page of the app never fetches it.
5
+ * When the file cannot be read the answer says so in plain words, and a copy read earlier is still shown.
6
+ */
7
+ import type { RegistryEntryView, RegistryView } from './contract.ts';
8
+ export declare const REGISTRY_INDEX_URL = "https://cordisplugins.github.io/registry/index.json";
9
+ type FetchLike = (input: string, init?: {
10
+ readonly signal?: AbortSignal;
11
+ readonly headers?: Record<string, string>;
12
+ }) => Promise<{
13
+ readonly ok: boolean;
14
+ readonly status: number;
15
+ json(): Promise<unknown>;
16
+ }>;
17
+ /** A plugin's folder name: the name without its scope, lower case (`@owner/notes` is `notes`). */
18
+ export declare const bareName: (name: string) => string;
19
+ /** What the app already has and who the person is, so a row can say "Added" and "Yours". */
20
+ export interface RegistryMarks {
21
+ /** The folder names of the app's plugins. */
22
+ readonly names: ReadonlySet<string>;
23
+ /** `owner/repo` (lower case) of every plugin the app pulled. */
24
+ readonly repos: ReadonlySet<string>;
25
+ /** GitHub accounts that are the person's own (signed in, or the share account), lower case. */
26
+ readonly accounts: ReadonlySet<string>;
27
+ }
28
+ /** `owner/repo` of a `github:` source, lower case; undefined for any other source. */
29
+ export declare function repoOfSource(source: string): string | undefined;
30
+ /**
31
+ * The entries a Blends app can pull: the ones the index gives a version and a pull line (a plugin whose code is only a folder of another
32
+ * repository has none). @throws when the index is not formatVersion 1.
33
+ */
34
+ export declare function registryEntries(index: unknown, marks: RegistryMarks): RegistryEntryView[];
35
+ /** The raw index, read once in a while: a fresh copy within `ttlMs`, else a new read, else the copy read before with the time it was read. */
36
+ export declare function createRegistryReader(fetcher: FetchLike, options?: {
37
+ readonly ttlMs?: number;
38
+ readonly timeoutMs?: number;
39
+ readonly now?: () => number;
40
+ }): () => Promise<{
41
+ readonly index: unknown;
42
+ readonly readAt: string;
43
+ } | {
44
+ readonly message: string;
45
+ }>;
46
+ /** The registry as the frame shows it, from one read of the index. */
47
+ export declare function readRegistryView(read: ReturnType<typeof createRegistryReader>, marks: () => Promise<RegistryMarks>): Promise<RegistryView>;
48
+ /** What one pull answers, as the app's `pluginShare` gives it: the plugin now running, or why it was refused (`plugins/plugin-share/pull-check.ts`). */
49
+ export type PullAnswer = {
50
+ readonly ok: true;
51
+ readonly name: string;
52
+ readonly version: string;
53
+ readonly action: 'installed' | 'updated' | 'unchanged';
54
+ readonly state: string;
55
+ } | {
56
+ readonly ok: false;
57
+ readonly refusal: string;
58
+ readonly reason: string;
59
+ readonly next: string;
60
+ };
61
+ /** The slice of the app's `pluginShare` service the registry uses. */
62
+ export interface PluginShareSlice {
63
+ pull(source: string): Promise<PullAnswer>;
64
+ list(): readonly {
65
+ readonly name: string;
66
+ readonly pulledFrom?: string;
67
+ }[];
68
+ }
69
+ /** The running app's `pluginShare`, read at each call (the app's rows come and go with a reload); undefined when the app has none. */
70
+ export declare function pluginShareOf(service: () => unknown): PluginShareSlice | undefined;
71
+ export {};
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Settings > App, in a desktop product: the app's name, its folder and size, export, import, the other apps on this computer, start over, and the
3
+ * licence of the git the product ships. Laid out as the Plugins page is (docs/design/blends-frame-mockup.html): a title, one line under it, one bordered
4
+ * row per thing. Start over asks inside the page, and Cancel is what a stray Enter or click does.
5
+ */
6
+ import { type DesktopApp } from './desktop-app.ts';
7
+ export interface AppSectionInjected {
8
+ readonly app: DesktopApp;
9
+ }
10
+ export declare function AppSection({ app }: AppSectionInjected): import("react").JSX.Element;
@@ -19,6 +19,8 @@ import { type SidebarPort } from './RightPanel.tsx';
19
19
  import type { FrameTabs } from './tabs.ts';
20
20
  import type { SwitchRequests } from './switch-request.ts';
21
21
  import type { FrameTools } from './tools.ts';
22
+ import type { DesktopApp } from './desktop-app.ts';
23
+ import type { ThemeSwitch } from './theme-switch.ts';
22
24
  export interface BlendsFrameInjected {
23
25
  readonly layout: DesktopLayoutState;
24
26
  /** DSH's right sidebar, drawn in the right panel's Panel tab. */
@@ -29,6 +31,8 @@ export interface BlendsFrameInjected {
29
31
  /** Whether the app's last code was refused (a syntax error): the bar says so while the canvas keeps the last good app. */
30
32
  readonly appReload: AppReloadStore;
31
33
  readonly view: FrameViewState;
34
+ /** The Dark/Light switch in the top bar. */
35
+ readonly themeSwitch: ThemeSwitch;
32
36
  readonly chats: ChatsPort;
33
37
  readonly versions: VersionsPort;
34
38
  /** The Git tab's push and pull (the Host runs git). */
@@ -41,6 +45,8 @@ export interface BlendsFrameInjected {
41
45
  readonly branchChats: BranchChatsPort;
42
46
  /** A chat of another branch asked for from the chat's History: the left panel offers the switch. */
43
47
  readonly switchRequests: SwitchRequests;
48
+ /** A desktop product's app (`./desktop-app.ts`): the bar shows the name the person gave it. */
49
+ readonly desktop?: DesktopApp;
44
50
  }
45
51
  export type BlendsFrameProps = PropsRuntime<'root'> & PropsRenderSlots<'main' | 'rightbar' | 'shell.overlay' | 'sidebar.settings'> & BlendsFrameInjected;
46
- export declare function BlendsFrame({ layout, sidebar, canvas, selection, frameState, appReload, view, chats, versions, gitSync, tabs, tools, feedback, branches, branchChats, switchRequests, renderSlot }: BlendsFrameProps): import("react").JSX.Element;
52
+ export declare function BlendsFrame({ layout, sidebar, canvas, selection, frameState, appReload, view, themeSwitch, chats, versions, gitSync, tabs, tools, feedback, branches, branchChats, switchRequests, desktop, renderSlot }: BlendsFrameProps): import("react").JSX.Element;
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Settings > Plugins > Graph: every plugin of the running app (and of the frame around it) as a picture, with how they depend on each other, and a line for
3
+ * each change as it happens. Ported from cordis-plugin-graph's `GraphTab.tsx` (MIT, commit e9bf6b5): the planes, the three relation toggles, the filter, the
4
+ * counts and the detail card are its. New here: the picture is updated in place and the Host's fiber events arrive by a waiting request, not by asking every
5
+ * two seconds; a changed plugin pulses; the strip lists the changes; the card says who a plugin needs and who needs it; and a plugin's code opens in the
6
+ * Files tab from the card.
7
+ */
8
+ import type { GraphEvent, GraphSnapshot } from '../graph-contract.ts';
9
+ import type { GraphApi } from './graph-api.ts';
10
+ /** The browser's own Cordis context, as the view reads it: its graph now, and each fiber change as it happens. */
11
+ export interface ClientGraph {
12
+ inspect(): GraphSnapshot;
13
+ subscribe(listener: (event: Omit<GraphEvent, 'seq' | 'at'>) => void): () => void;
14
+ }
15
+ export interface GraphViewInjected {
16
+ readonly api: GraphApi;
17
+ /** Absent where the browser's context cannot be read: the client plane is then not offered. */
18
+ readonly client?: ClientGraph;
19
+ /** Open a file of the app (a path from the app's folder) in the Files tab. */
20
+ readonly openSource: (path: string) => void;
21
+ }
22
+ export declare function GraphView({ api, client, openSource }: GraphViewInjected): import("react").JSX.Element;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * The first start of a desktop product asks one thing, in the app's own window: "Name your app" (app-storage.md, "What the person sees"). The product's
3
+ * name for its starting app is offered and selected, so Enter keeps it and typing replaces it. Once the person answers, the app is named and this never
4
+ * shows again; Settings > App renames it later. Drawn in the frame's overlay, over the frame, in the look of its Settings dialog.
5
+ */
6
+ import type { DesktopApp } from './desktop-app.ts';
7
+ export interface NameYourAppInjected {
8
+ readonly app: DesktopApp;
9
+ }
10
+ export declare function NameYourApp({ app }: NameYourAppInjected): import("react").JSX.Element | null;
@@ -1,7 +1,17 @@
1
1
  /** The Plugins page of Settings: search, the groups as chips, and one row per plugin with who made it, its state and its switch. */
2
+ import { type GraphViewInjected } from './GraphView.tsx';
2
3
  import { type NavigatorPlugin } from './plugins-navigator.ts';
4
+ import type { RegistryApi } from './registry-api.ts';
3
5
  export interface PluginsSectionInjected {
4
6
  /** Every plugin of the app and the frame, read fresh. */
5
7
  readonly loadPlugins: () => Promise<readonly NavigatorPlugin[]>;
8
+ /** What the Graph view reads and does; absent, the page has no Graph tab. */
9
+ readonly graph?: GraphViewInjected;
10
+ /** The public registry, adding a plugin from it, and whether this computer can share to GitHub. */
11
+ readonly registry: RegistryApi;
6
12
  }
7
- export declare function PluginsSection({ loadPlugins }: PluginsSectionInjected): import("react").JSX.Element;
13
+ /** What the Settings shell hands a section: `close` leaves Settings (View source shows the file in the frame, behind the dialog). */
14
+ export interface PluginsSectionOwner {
15
+ readonly close?: () => void;
16
+ }
17
+ export declare function PluginsSection({ loadPlugins, graph, registry, close }: PluginsSectionInjected & PluginsSectionOwner): import("react").JSX.Element;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * The Registry tab of Settings > Plugins: the public Cordis plugin registry, searchable, with one button to add a plugin to this app. Plain words;
3
+ * the address, compatibility and the tool's own messages are behind "Details". Nothing is added without the person's yes (the question names whose code it is).
4
+ */
5
+ import type { RegistryApi } from './registry-api.ts';
6
+ export interface RegistryViewProps {
7
+ readonly api: RegistryApi;
8
+ /** The app's plugin list changed (a plugin was added): read it again. */
9
+ readonly onAdded: () => void;
10
+ }
11
+ export declare function RegistryView({ api, onAdded }: RegistryViewProps): import("react").JSX.Element;
@@ -0,0 +1,6 @@
1
+ /**
2
+ * The expand button in DSH's Settings header (its `settings.action` list, next to "Open configuration file" and the close button): the window fills the
3
+ * browser window, and a second click, a double click on the header, or Esc brings it back. The choice is remembered by the browser. While the Graph is
4
+ * full screen on top, Esc leaves the Graph first (its handler runs before this one).
5
+ */
6
+ export declare function SettingsExpand(): import("react").JSX.Element;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Share a plugin, in plain words: four places it can go (this computer, my GitHub privately, my GitHub publicly, the public registry), one question before
3
+ * anything is sent with Cancel as the default, and a short answer after. Git, repositories, licenses and topics are behind a "Details" toggle.
4
+ * It owns only what the person is looking at; the sharing itself is `plugin.share`, the packed copy `plugin.actions.save`, both from the Host.
5
+ */
6
+ import type { GithubReadiness, SavedPluginResult, SharedPluginView } from '../contract.ts';
7
+ import { type NavigatorPlugin } from './plugins-navigator.ts';
8
+ import type { GithubConnectApi } from './registry-api.ts';
9
+ export interface ShareChooserProps {
10
+ readonly plugin: NavigatorPlugin;
11
+ /** Whether this computer can share to GitHub; read once when the chooser opens. */
12
+ readonly readGithub: () => Promise<GithubReadiness>;
13
+ /** Connect GitHub from here (GitHub's browser sign-in); without it the note shows the Terminal command only. */
14
+ readonly connectGithub?: GithubConnectApi;
15
+ /** Copy a text; false when the browser refuses. */
16
+ readonly copy: (text: string) => Promise<boolean>;
17
+ readonly onSaved: (saved: SavedPluginResult) => void;
18
+ readonly onShared: (shared: SharedPluginView) => void;
19
+ readonly onClose: () => void;
20
+ }
21
+ export declare function ShareChooser({ plugin, readGithub, connectGithub, copy, onSaved, onShared, onClose }: ShareChooserProps): import("react").JSX.Element;
@@ -0,0 +1,65 @@
1
+ /**
2
+ * The app as a desktop product keeps it (specs/049-framework-architecture/app-storage.md in ACRYL): its name, its folder, export, import and start over.
3
+ * A product's window gets `window.acrylBlendsApp` from its preload (acrylblends `plugins/desktop/preload.cjs`, answered by `plugins/desktop/app-page.ts`);
4
+ * a browser tab and an app run with `npm run dev` have none, and the frame then shows no App page. The operation names and shapes are that module's:
5
+ * keep them in step.
6
+ */
7
+ /** What the App pages show. `named` is false until the person names the app: the first start asks. */
8
+ export interface DesktopAppState {
9
+ readonly id: string;
10
+ readonly name: string;
11
+ readonly named: boolean;
12
+ /** The other apps on this computer; two may share a name, so each says when it was made (an ISO date). */
13
+ readonly others: readonly {
14
+ readonly id: string;
15
+ readonly name: string;
16
+ readonly created: string;
17
+ }[];
18
+ readonly fileManager: 'Finder' | 'Explorer' | 'Files';
19
+ readonly git: boolean;
20
+ }
21
+ export interface DesktopAppSize {
22
+ readonly bytes: number;
23
+ readonly files: number;
24
+ }
25
+ type Result = {
26
+ readonly ok: true;
27
+ readonly value?: unknown;
28
+ } | {
29
+ readonly ok: false;
30
+ readonly message: string;
31
+ };
32
+ interface Bridge {
33
+ call(op: string, arg?: unknown): Promise<Result>;
34
+ }
35
+ /** The product's app, read through the bridge: a store of its state (the bar's name and the first start's question follow it) and its operations. */
36
+ export declare class DesktopApp {
37
+ private readonly bridge;
38
+ private state;
39
+ private readonly listeners;
40
+ constructor(bridge: Bridge);
41
+ private ask;
42
+ private set;
43
+ getSnapshot: () => DesktopAppState | undefined;
44
+ subscribe: (listener: () => void) => (() => void);
45
+ refresh(): Promise<DesktopAppState>;
46
+ rename(name: string): Promise<DesktopAppState>;
47
+ size(): Promise<DesktopAppSize>;
48
+ reveal(): Promise<void>;
49
+ /** The save dialog, then the file; `undefined` when the person cancelled. */
50
+ export(data: boolean): Promise<string | undefined>;
51
+ /** The open dialog, then the new app opens in this window (the page reloads); resolves only when the person cancelled. */
52
+ import(): Promise<void>;
53
+ /** The app moves to the product's trash folder and a fresh one opens in this window (the page reloads). */
54
+ startOver(): Promise<void>;
55
+ open(id: string): Promise<void>;
56
+ gitLicence(): Promise<void>;
57
+ gitSource(): Promise<void>;
58
+ }
59
+ /** The product's app when this page is a product's window, else undefined. */
60
+ export declare function desktopApp(scope?: {
61
+ readonly acrylBlendsApp?: unknown;
62
+ }): DesktopApp | undefined;
63
+ /** A size as a person reads it: `3.3 MB`, `840 KB`. */
64
+ export declare function formatSize(bytes: number): string;
65
+ export {};
@@ -0,0 +1,11 @@
1
+ /** The browser's side of the Host's plugin graph routes. */
2
+ import { type GraphEventsAnswer, type GraphView } from '../graph-contract.ts';
3
+ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
4
+ export interface GraphApi {
5
+ /** The Host's graph now, and the number of its newest fiber event. */
6
+ read(): Promise<GraphView>;
7
+ /** The fiber events after `after`: answered when there are some, or empty after the Host waited a while. Rejects when `signal` aborts. */
8
+ events(after: number, signal?: AbortSignal): Promise<GraphEventsAnswer>;
9
+ }
10
+ export declare function createGraphApi(fetcher?: FetchLike): GraphApi;
11
+ export {};
@@ -0,0 +1,63 @@
1
+ /**
2
+ * The plugin graph's drawing: a snapshot as Cytoscape elements, and a canvas that takes a new set of them without starting over (so a fiber changing
3
+ * phase changes one colour, and the picture a person was looking at stays put). Ported from cordis-plugin-graph (MIT, commit e9bf6b5,
4
+ * `src/client/cytoscape-graph.ts`): the elements, the colours by phase and the cose layout are its; the incremental update, the pulses and the theme
5
+ * palette are new.
6
+ */
7
+ import { type ElementDefinition } from 'cytoscape';
8
+ import type { EdgeKind, GraphSnapshot, NodePhase } from '../graph-contract.ts';
9
+ export declare const PHASE_COLOR: Record<NodePhase, string>;
10
+ export declare const EDGE_COLOR: Record<EdgeKind, string>;
11
+ /** Which edge kinds to include. */
12
+ export type EdgeFilter = Record<EdgeKind, boolean>;
13
+ /** What a fiber change looks like on the node: it came up, it went away, it failed, or it moved to some other phase. */
14
+ export type PulseKind = 'up' | 'down' | 'error' | 'change';
15
+ /** The colours the frame's theme gives the picture (the labels and the outline of a node). */
16
+ export interface Palette {
17
+ readonly label: string;
18
+ readonly outline: string;
19
+ }
20
+ export declare const DARK_PALETTE: Palette;
21
+ export declare const LIGHT_PALETTE: Palette;
22
+ /** The node id for a fiber of a plane: the two planes never collide. */
23
+ export declare const nodeId: (prefix: string, uid: number) => string;
24
+ /** One snapshot as elements. `prefix` namespaces the ids so the two planes can share one picture. An unresolved `inject` (a self loop) is left out. */
25
+ export declare function toElements(snapshot: GraphSnapshot, filter: EdgeFilter, prefix?: string): ElementDefinition[];
26
+ /** A picture of the plugins that takes new elements without drawing everything again. `container` is null only in tests (Cytoscape then draws nothing). */
27
+ export declare class GraphCanvas {
28
+ private readonly onSelect;
29
+ private readonly cy;
30
+ private laidOut;
31
+ private readonly timers;
32
+ private onWheel;
33
+ private plainZoom;
34
+ private wheelTarget;
35
+ constructor(container: HTMLElement | null, palette: Palette, onSelect?: (id: string | undefined) => void);
36
+ /** The ids now in the picture (nodes and edges). */
37
+ ids(): string[];
38
+ /** Make the picture these elements. Existing ones keep their place and take the new data; the layout runs again only when a node came or went. Returns whether it did. */
39
+ update(elements: readonly ElementDefinition[]): boolean;
40
+ /** The theme changed: the labels and outlines take its colours. */
41
+ setPalette(palette: Palette): void;
42
+ fit(): void;
43
+ /** The zoom buttons: one step in or out around the middle of the picture (not past the limits), 1.4 times each way. */
44
+ zoomBy(factor: number): void;
45
+ zoomLevel(): number;
46
+ /** The box changed size (the view went full screen, or came back): Cytoscape measures it again. Zoom, position and selection stay as they are. */
47
+ resize(): void;
48
+ /** Whether a plain scroll zooms. Off where the picture sits in a pane that scrolls (there Ctrl or Cmd is needed); on when it fills the window. */
49
+ setPlainZoom(on: boolean): void;
50
+ /** Flash one node (a fiber just changed). A node that is not in the picture is left alone. */
51
+ pulse(id: string, kind: PulseKind): void;
52
+ /** Whether a node has a pulse showing (for tests and for the first frame after an update). */
53
+ pulsing(id: string): boolean;
54
+ /** Show only a node and what it touches (or everything again with undefined); the node is selected. */
55
+ focus(id: string | undefined): void;
56
+ /** Fade what does not match a name or module (nothing for an empty query); `focus` is cleared. */
57
+ search(query: string): void;
58
+ /** Where a node sits in the container, so a list can scroll the picture to it. */
59
+ centre(id: string): void;
60
+ destroy(): void;
61
+ }
62
+ /** The colours of the frame's theme, read from the element the picture is in. */
63
+ export declare function readPalette(element: Element): Palette;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The graph view's link to the app: read the graph, then wait for each change, and when the app stops answering say so and start over by itself.
3
+ *
4
+ * Starting over means reading the graph again, not asking for "changes after the number I had": an app that was stopped and started again counts its
5
+ * changes from the beginning, so the old number would make the view wait for changes that never come.
6
+ */
7
+ import type { GraphEvent, GraphSnapshot } from '../graph-contract.ts';
8
+ import type { GraphApi } from './graph-api.ts';
9
+ export type Live = 'connecting' | 'live' | 'lost';
10
+ /** The sentence shown while the link is down (one place, so the view and the tests say the same). */
11
+ export declare const LOST_TEXT = "Lost the connection to the app, trying again...";
12
+ export declare const RETRY_MS = 3000;
13
+ export interface LinkEvents {
14
+ onLive(live: Live): void;
15
+ onSnapshot(snapshot: GraphSnapshot): void;
16
+ onEvents(events: readonly GraphEvent[]): void;
17
+ }
18
+ /** Wait `ms`, or less when `signal` aborts. */
19
+ export declare function pause(ms: number, signal: AbortSignal): Promise<void>;
20
+ /** Runs until `signal` aborts. `wait` is injectable for tests. */
21
+ export declare function runLink(api: GraphApi, events: LinkEvents, signal: AbortSignal, wait?: (ms: number, signal: AbortSignal) => Promise<void>): Promise<void>;
@@ -0,0 +1,23 @@
1
+ /** What the graph view works out from a snapshot and the fiber events, apart from drawing: how a change pulses, how it reads in the strip, and who a plugin needs and who needs it. */
2
+ import type { GraphEvent, GraphNode, GraphSnapshot, NodePhase } from '../graph-contract.ts';
3
+ import type { PulseKind } from './graph-canvas.ts';
4
+ /** How a fiber change shows on its node: up when it became active (or was created), error when it failed, down when it went away, else a plain change. */
5
+ export declare function pulseOf(event: Pick<GraphEvent, 'kind' | 'to'>): PulseKind;
6
+ /** One line of the strip: `cart: loading to active`, `cart: created`, `cart: removed`. */
7
+ export declare function eventLine(event: Pick<GraphEvent, 'name' | 'kind' | 'from' | 'to'>): string;
8
+ export interface Relation {
9
+ readonly service: string;
10
+ readonly node: GraphNode;
11
+ }
12
+ export interface Relations {
13
+ /** The plugins this one needs, by the service that joins them. */
14
+ readonly requires: readonly Relation[];
15
+ /** The services this one needs that no active plugin provides now. */
16
+ readonly missing: readonly string[];
17
+ /** The plugins that need something this one provides. */
18
+ readonly usedBy: readonly Relation[];
19
+ }
20
+ /** Who a plugin needs and who needs it, read from the relations of one snapshot. */
21
+ export declare function relationsOf(snapshot: GraphSnapshot, uid: number): Relations;
22
+ /** How many nodes are in each phase. */
23
+ export declare function phaseCounts(snapshots: readonly (GraphSnapshot | undefined)[]): Map<NodePhase, number>;
@@ -0,0 +1,3 @@
1
+ /** The graph view's styles, in the frame's own tokens (`--bf-*`, set on `.acrylBlendsPlugins` for both themes). A style element of its own, so the view adds nothing to the frame's sheet. */
2
+ /** Add the styles once; returns the removal. */
3
+ export declare function installGraphStyles(): () => void;
@@ -14,7 +14,7 @@ declare module '@deepseek-ai/cordis' {
14
14
  }
15
15
  declare module '@deepseek-ai/dsh-client-ui-slots' {
16
16
  interface LocaleNamespaceMap {
17
- 'acryl.blendsFrame': 'plugins';
17
+ 'acryl.blendsFrame': 'plugins' | 'app';
18
18
  }
19
19
  }
20
20
  /** The Loader row that composes the app's own plugins (`frame/app-plugins.mjs`): loading it again applies a switch in `blend.yaml`. */
@@ -0,0 +1,10 @@
1
+ /**
2
+ * A request the Host refused, in the words it chose for the person: `message` is the plain sentence, `details` what the tool said (shown behind a
3
+ * "Details" toggle for developers). A Host that answered without a sentence gets a plain one here, never a status line.
4
+ */
5
+ export declare class PlainFailure extends Error {
6
+ readonly details: string | undefined;
7
+ constructor(message: string, details?: string);
8
+ }
9
+ /** The failure a refused response carries. */
10
+ export declare function failureOf(response: Response): Promise<PlainFailure>;
@@ -3,14 +3,36 @@
3
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
4
  * chosen; the Host then starts the app's plugins again, and the canvas loads the app page again.
5
5
  */
6
- import { type AppPluginKind, type AppPluginsView, type AppPluginView, type FramePluginView, type SharedPluginView, type SharePlan } from '../contract.ts';
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';
7
9
  /** Sharing a local plugin: first what it would do, then, on the person's yes, exactly that. */
8
10
  export interface PluginShare {
9
- plan(): Promise<SharePlan>;
11
+ plan(target?: ShareTarget): Promise<SharePlan>;
10
12
  publish(confirmed: SharePlan): Promise<SharedPluginView>;
11
13
  }
12
- /** The question a share asks before anything is sent: the repository, whether it is created, the version and who can see it. */
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
+ */
13
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[];
14
36
  /** Which filter chip a plugin falls under. */
15
37
  export type PluginGroup = 'made' | 'registry' | 'frame';
16
38
  export interface NavigatorPlugin {
@@ -26,6 +48,12 @@ export interface NavigatorPlugin {
26
48
  readonly state: string;
27
49
  /** Where a local plugin was shared: its repository and released version. */
28
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;
29
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. */
30
58
  readonly share?: PluginShare;
31
59
  /** Absent when the plugin cannot be switched here (the frame's protected rows). */
@@ -33,19 +61,21 @@ export interface NavigatorPlugin {
33
61
  }
34
62
  /** "today", "yesterday", "Mon", or "12 Oct" for an older day. */
35
63
  export declare function madeWhen(at: string, now?: Date): string;
36
- export declare function appPluginRow(plugin: AppPluginView, toggle: (on: boolean) => Promise<void>, share?: PluginShare, now?: Date): NavigatorPlugin;
64
+ export declare function appPluginRow(plugin: AppPluginView, toggle: (on: boolean) => Promise<void>, share?: PluginShare, now?: Date, actions?: PluginActions): NavigatorPlugin;
37
65
  /** One of the frame's own plugins: shown with its state, switched only by changing the frame. */
38
- export declare function framePluginRow(plugin: FramePluginView): NavigatorPlugin;
66
+ export declare function framePluginRow(plugin: FramePluginView, actions?: PluginActions): NavigatorPlugin;
39
67
  /** The plugins a search and a chip leave. */
40
68
  export declare function filterPlugins(plugins: readonly NavigatorPlugin[], query: string, group: PluginGroup | 'all'): NavigatorPlugin[];
41
69
  type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
42
70
  export interface AppPluginsApi {
43
71
  read(): Promise<AppPluginsView>;
44
72
  switch(kind: AppPluginKind, name: string, on: boolean): Promise<void>;
45
- /** What sharing one local plugin would do; nothing is sent. */
46
- planShare(name: string): Promise<SharePlan>;
73
+ /** What sharing one local plugin would do (private unless `visibility` says public); nothing is sent. */
74
+ planShare(name: string, target?: ShareTarget): Promise<SharePlan>;
47
75
  /** Share one local plugin as the person confirmed it; answers where it went. */
48
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>;
49
79
  }
50
80
  export declare function createAppPluginsApi(fetcher?: FetchLike): AppPluginsApi;
51
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,14 @@
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 } 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
+ /** 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. */
6
+ export declare function filterRegistry(entries: readonly RegistryEntryView[], query: string, showAll: boolean): RegistryEntryView[];
7
+ /** The address a person can type or paste: `github:<owner>/<repo>@<version>`; leading and trailing space is ignored. */
8
+ export declare function cleanAddress(text: string): string | undefined;
9
+ /** The question before anything is added: whose code it is, in one sentence. */
10
+ export declare const addQuestion: (name: string, owner: string) => string;
11
+ /** The answer after an add. */
12
+ export declare function addedText(pulled: PulledPluginView): string;
13
+ /** One line under a row: who released it, which version and when. */
14
+ export declare const entryByline: (entry: RegistryEntryView) => string;
@@ -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 {};