@theoremjs/studio 0.0.0-stage → 0.3.2

package/map-line.d.ts

@@ -0,0 +1,19 @@
+export interface MapPlace {
+    x: number;
+    y: number;
+}
+export interface MapCurve {
+    d: string;
+    /** The point `t` of the way along, from 0 to 1. */
+    at(t: number): MapPlace;
+}
+/**
+ * The line every map draws between two nodes: level as it leaves and as it arrives, turning at
+ * `via`, which is halfway between them unless said.
+ */
+export declare function mapCurve(from: MapPlace, to: MapPlace, via?: number): MapCurve;
+/**
+ * A line that runs level from `from` to `rail`, straight up or down it, and level to `to`, its two
+ * corners rounded by `radius`. Lines that share an end and a rail are one line along both.
+ */
+export declare function mapRail(from: MapPlace, to: MapPlace, rail: number, radius: number): MapCurve;

package/map-line.js

@@ -0,0 +1,42 @@
+/**
+ * The line every map draws between two nodes: level as it leaves and as it arrives, turning at
+ * `via`, which is halfway between them unless said.
+ */
+export function mapCurve(from, to, via = (from.x + to.x) / 2) {
+    return {
+        d: `M ${from.x} ${from.y} C ${via} ${from.y}, ${via} ${to.y}, ${to.x} ${to.y}`,
+        at(t) {
+            const u = 1 - t;
+            return {
+                x: u * u * u * from.x + 3 * u * t * via + t * t * t * to.x,
+                y: (u * u * u + 3 * u * u * t) * from.y + (3 * u * t * t + t * t * t) * to.y,
+            };
+        },
+    };
+}
+/**
+ * A line that runs level from `from` to `rail`, straight up or down it, and level to `to`, its two
+ * corners rounded by `radius`. Lines that share an end and a rail are one line along both.
+ */
+export function mapRail(from, to, rail, radius) {
+    const lead = Math.abs(rail - from.x);
+    const rise = Math.abs(to.y - from.y);
+    const tail = Math.abs(to.x - rail);
+    const length = lead + rise + tail;
+    const along = Math.sign(to.x - from.x);
+    const up = Math.sign(to.y - from.y);
+    const round = Math.min(radius, rise / 2, lead, tail);
+    const corners = ` L ${rail - along * round} ${from.y} Q ${rail} ${from.y}, ${rail} ${from.y + up * round}` +
+        ` L ${rail} ${to.y - up * round} Q ${rail} ${to.y}, ${rail + along * round} ${to.y}`;
+    return {
+        d: `M ${from.x} ${from.y}${round > 0 ? corners : ''} L ${to.x} ${to.y}`,
+        at(t) {
+            const run = t * length;
+            if (run < lead)
+                return { x: from.x + along * run, y: from.y };
+            if (run > lead + rise)
+                return { x: to.x - along * (length - run), y: to.y };
+            return { x: rail, y: from.y + up * (run - lead) };
+        },
+    };
+}

package/map.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The workspace as a map. Each profile is a card of its sections; what feeds it stands beside it:
+ * the providers and models it runs on, the settings the project shares, the tools it may call. A
+ * line joins each to the section it feeds. It is read from the workspace and changes nothing; each
+ * node and section names the workspace node that opens it.
+ */
+import { type MapPlace } from './map-line.ts';
+import { type SharedEntry } from './shared-settings.ts';
+import { type StudioWorkspace } from './workspace.ts';
+export type MapNodeKind = 'provider' | 'shared' | 'model' | 'agent' | 'tool';
+/** One section of a profile, on its card. */
+export interface MapRow {
+    /** The section's workspace node id, which also opens it. */
+    id: string;
+    label: string;
+    /** Beside the label: the models' names, how many tools are allowed, the kind of output. */
+    note: string;
+    opens: string;
+    /** The section, as `FACET_ICON` names it. */
+    type: string;
+}
+export interface MapNode {
+    id: string;
+    kind: MapNodeKind;
+    label: string;
+    /** Under the label: a tool's description, a model's provider and id, where a setting is declared. */
+    note: string;
+    /** The workspace node that opens it; unset for a shared setting nothing here uses. */
+    opens?: string;
+    /** A model: every workspace node it stands for, one for each profile that runs it. */
+    holds?: string[];
+    /** A model whose label another model has too: its label with what tells the two apart. */
+    long?: string;
+    /** An agent's profile type, a tool's type, a model's provider definition, or the section a shared setting fills. */
+    type?: string;
+    /** A profile's sections, in the tree's order. */
+    rows?: MapRow[];
+}
+/**
+ * What joins two nodes, read from `from` to `to`. An end is a node's id, or the id of the profile's
+ * section it feeds:
+ * - `serves`: a provider serves a model.
+ * - `sets`: a shared setting sets a section of a profile, or a tool.
+ * - `runs`: a model runs a profile.
+ * - `allows`: a profile may call a tool.
+ * - `asks`: an agent tool asks its profile.
+ * - `summarised`: a profile has another write its summaries.
+ */
+export type MapLinkKind = 'serves' | 'sets' | 'runs' | 'allows' | 'asks' | 'summarised';
+export interface MapLink {
+    from: string;
+    to: string;
+    kind: MapLinkKind;
+}
+export interface MapGroup {
+    label: string;
+    nodes: MapNode[];
+}
+export interface WorkspaceMap {
+    /**
+     * Left to right: providers, what profiles are set with, the profiles, the tools. A column holds
+     * only groups with nodes.
+     */
+    columns: MapGroup[][];
+    links: MapLink[];
+}
+/** The map of `workspace`, with the settings its project shares. */
+export declare function workspaceMap(workspace: StudioWorkspace, shared?: readonly SharedEntry[]): WorkspaceMap;
+/** The nodes a link joins: a link to a profile's section joins the profile. */
+export declare function mapLinkEnds(map: WorkspaceMap): {
+    link: MapLink;
+    from: string;
+    to: string;
+}[];
+/** `id` and every node a link joins it to. */
+export declare function mapNeighbours(map: WorkspaceMap, id: string): Set<string>;
+/** The nodes whose name or note holds `query`, whatever its case: their ids. None for an empty query. */
+export declare function mapFound(map: WorkspaceMap, query: string): string[];
+/**
+ * `id`'s family: the node, everything that feeds it, and everything it feeds, however many links
+ * away, with the links between them. Empty when the map has no such node. Several ids give their
+ * families together.
+ */
+export declare function mapFamily(map: WorkspaceMap, id: string | readonly string[]): WorkspaceMap;
+/** What joins a node to the rest, in words: "Runs on gemini-2.5-flash. Allows get_weather, find_plant." */
+export declare function mapLinkWords(map: WorkspaceMap, id: string): string;
+/** The sizes a map is laid out with, in pixels. */
+export interface MapSizes {
+    /** A node's slot in its column. Its height is a token's, or with detail a node whose note runs to two lines. */
+    node: {
+        width: number;
+        height: number;
+    };
+    /**
+     * With detail, a node with sections: its head, each section's row, and the room under the last.
+     * A node with a one-line note is a head alone.
+     */
+    card: {
+        head: number;
+        row: number;
+        foot: number;
+    };
+    /** Between columns, and between a column's nodes. */
+    columnGap: number;
+    rowGap: number;
+    /** A group's heading, and the room between one group and the next. */
+    heading: number;
+    groupGap: number;
+    /** Around the whole map. */
+    padding: number;
+    /** Between a node's side and the line that leaves or arrives there. */
+    lineGap: number;
+}
+export type { MapPlace };
+export interface MapView {
+    /** Where nodes were put, by id. */
+    moved?: Readonly<Record<string, MapPlace>>;
+    /** How wide each node is drawn, by id, when narrower than its slot. */
+    widths?: Readonly<Record<string, number>>;
+    /** Each profile as a card of its sections and a line to the section it joins; else every node is one token. */
+    detail?: boolean;
+}
+/** A link's line as an SVG path from `link.from` to `link.to`, and the nodes it joins. */
+export interface MapLine {
+    link: MapLink;
+    from: string;
+    to: string;
+    d: string;
+}
+export interface MapLayout {
+    width: number;
+    height: number;
+    /** Each node's top left corner and height, by id. */
+    nodes: Record<string, MapPlace & {
+        height: number;
+    }>;
+    /** Each group's heading: its top left corner. */
+    headings: (MapPlace & {
+        label: string;
+    })[];
+    lines: MapLine[];
+}
+/** How many lines of its note a node shows: a tool's description and a shared setting's source run to two. */
+export declare function mapNoteLines(node: MapNode): 1 | 2;
+/**
+ * Where everything on the map goes: the columns side by side from the top, each group under its
+ * heading, except a node in `moved`, which goes where it was put. A line leaves the side of a node
+ * that faces the other; between two nodes one above the other it bows out to the right, past what
+ * stands between them. Between two columns the lines that share an end run as one, and part beside
+ * the end fewer lines share, each end's lines along a rail of their own: two columns stand far enough
+ * apart for the rails between them. A line that would pass behind a node or a heading goes over or under only
+ * what is in its way, whichever is nearer. The map is large enough for every line.
+ */
+export declare function mapLayout(map: WorkspaceMap, sizes: MapSizes, view?: MapView): MapLayout;