@draftably/runtime 0.0.0-stage → 0.2.0

package/dist/types/src/dsl/syntax.d.ts

@@ -0,0 +1,317 @@
+/**
+ * The `.draft` diagram language: a line-based source format that keeps comments, plus a model
+ * parser and a formatter. Adapted from the Meld 0.1 prototype in `reference/meld/original`.
+ *
+ * Source is kept as a list of lines so that edits can change single statements and formatting
+ * keeps every comment and unrelated statement.
+ */
+import { type DiagramAppearance, type Shade } from '../model/appearance.js';
+import { type EndMarker } from '../model/markers.js';
+import type { Status } from '../model/status.js';
+import type { ColorKey, LayoutAlgorithmId, LayoutSettings, PortSide, RoutingSettings, ShapeKind } from '../model/types.js';
+export declare class DslError extends Error {
+    readonly line: number;
+    readonly column: number;
+    constructor(message: string, line?: number, column?: number);
+}
+/** Change marks before `node`, `group` and `edge`, read like a diff, and the status each sets. */
+export declare const MARKS: {
+    readonly '+': "added";
+    readonly '-': "removed";
+    readonly '~': "changed";
+    readonly '.': "context";
+};
+export type Mark = keyof typeof MARKS;
+/** A word in a statement. Quoted words are strings; bare words are identifiers and numbers. */
+export interface Word {
+    value: string;
+    quoted: boolean;
+}
+export interface Statement {
+    kind: 'statement';
+    command: string;
+    /** Change mark written before the command, as in a diff: `+`, `-`, `~` or `.`. */
+    mark?: Mark;
+    args: Word[];
+    attrs: Array<[string, Word]>;
+    /** Inline comment including its `#` or `//` marker. */
+    comment?: string;
+    /** 1-based line in the source this statement was parsed from; 0 when added by an edit. */
+    line: number;
+}
+export type SourceLine = {
+    kind: 'blank';
+} | {
+    kind: 'comment';
+    text: string;
+} | Statement;
+export interface SourceDoc {
+    lines: SourceLine[];
+}
+export declare const bare: (value: string | number) => Word;
+export declare const quoted: (value: string) => Word;
+/**
+ * Split one line into raw tokens, each with its 1-based start column, and a trailing comment.
+ * Quoted tokens keep their quotes.
+ */
+export declare function tokenize(text: string, line?: number): {
+    tokens: string[];
+    columns: number[];
+    comment?: string;
+};
+/** Read source text into lines. Only lexical errors are reported here. */
+export declare function readSource(source: string): SourceDoc;
+export declare function printStatement(s: Statement): string;
+/**
+ * Print source consistently: one space between words, no indentation, at most one blank line in a
+ * row, and a final newline. Comments and statement order are kept.
+ */
+export declare function printSource(doc: SourceDoc): string;
+/** Format source text. Throws `DslError` for lexical errors; semantics are not checked. */
+export declare const formatSource: (source: string) => string;
+export type DslColor = ColorKey | 'auto';
+export type DslShape = Exclude<ShapeKind, 'icon' | 'image'>;
+/** `cells` lays a group's members edge to edge as one object: a sequence, table or byte layout. */
+export type Algorithm = 'flow' | 'row' | 'column' | 'lanes' | 'sequence' | 'cells';
+export interface ModelObject {
+    id: string;
+    type: 'node' | 'group';
+    label: string;
+    parent: string;
+    color: DslColor;
+    /** Explicit shade; omitted means the default for the object type. */
+    shade?: Shade;
+    shape: DslShape;
+    /** From a change mark; unchanged when omitted. */
+    status?: Status;
+    /** With `~`: the label before the change. */
+    was?: string;
+    /** With `~`, nodes only: the shape before the change. */
+    wasShape?: DslShape;
+    /** With `~`, nodes only: the count before the change; 1 means a single box. */
+    wasCount?: number | string;
+    /** A link to open from exported drawings, such as a source file or URL. */
+    href?: string;
+    /**
+     * Nodes only: how many things this one box stands for, drawn as a stack with a badge. A short
+     * symbol such as `N` or `many` stands for an unknown number.
+     */
+    count?: number | string;
+    /**
+     * Groups only: `soft` draws a tint behind the members and `none` draws nothing. Either way the
+     * group is not a layout scope: its members are laid out with the nearest framed container's.
+     */
+    frame?: 'soft' | 'none';
+    /** Groups only: `fold=never` keeps the group's chain in one column even when it is much the tallest. */
+    fold?: 'never';
+    /** Set by the compiler: the soft groups this object sits in below its layout scope, outermost first. */
+    soft?: string[];
+    /** Cells only: how many columns (or units) of its group's grid the cell covers; `var` for a
+     * field of variable length in a byte or bit layout. */
+    span?: number | 'var';
+    line: number;
+}
+export interface ModelEdge {
+    id: string;
+    source: string;
+    target: string;
+    label: string;
+    dashed: boolean;
+    from: PortSide;
+    to: PortSide;
+    /** From a change mark; unchanged when omitted. */
+    status?: Status;
+    /** With `~`: the label before the change. */
+    was?: string;
+    /** `directed=false`: an undirected connection, drawn without an arrowhead. */
+    directed?: false;
+    /** `head=`: the mark at the target end, when it isn't the plain arrow. */
+    head?: EndMarker;
+    /** `tail=`: the mark at the source end, when it has one. */
+    tail?: EndMarker;
+    /** `constraint=false`: drawn and routed, but layout doesn't rank or order by it. */
+    constraint?: false;
+    line: number;
+}
+/** A layout engine run cold over a scope's subtree; see `src/engines/layout-engine.js`. */
+export interface EngineRecipe {
+    algorithm: LayoutAlgorithmId;
+    params: Partial<LayoutSettings>;
+}
+/** Image shapes a drawing can aim for (`fit=`, `vary --fit`): width over height. */
+export declare const FITS: {
+    readonly wide: 2;
+    readonly slide: 1.78;
+    readonly square: 1;
+    readonly page: 0.77;
+    readonly tall: 0.6;
+};
+export type Fit = keyof typeof FITS;
+export interface ModelLayout {
+    scope: string;
+    algorithm: Algorithm;
+    /** Set when the scope is arranged by a layout engine instead of a built-in recipe. */
+    engine?: EngineRecipe;
+    direction: 'auto' | 'right' | 'down';
+    /** `cells` only: columns in each row of the grid; one row or column without it. */
+    columns?: number;
+    /** `cells` only: a byte or bit layout, where each column is one unit of the same width. */
+    unit?: 'bit' | 'byte';
+    /** With `unit`: the width of one unit, and whether unit numbers run above the first row. */
+    unitWidth?: number;
+    ruler?: boolean;
+    /** `flow` only: whether a long run of ranks folds into bands. Engines take `fold` as a param. */
+    fold: 'auto' | 'never';
+    /** Root only: the image shape to aim for; compile tries direction and folding to get closest. */
+    fit?: Fit;
+    gap: number;
+    minWidth: number;
+    minHeight: number;
+    line: number;
+}
+export type Hint = {
+    type: 'order';
+    scope: string;
+    ids: string[];
+    line: number;
+} | {
+    type: 'align';
+    axis: 'x' | 'y';
+    ids: string[];
+    strength: Strength;
+    line: number;
+} | {
+    type: 'near';
+    id: string;
+    ref: string;
+    side: NearSide;
+    gap: number;
+    offset: number;
+    strength: Strength;
+    line: number;
+} | {
+    type: 'nudge';
+    id: string;
+    dx: number;
+    dy: number;
+    line: number;
+} | {
+    type: 'stay';
+    id: string;
+    x: number;
+    y: number;
+    weight: number;
+    line: number;
+} | {
+    type: 'pin';
+    id: string;
+    x: number;
+    y: number;
+    line: number;
+}
+/** `height` is unset for `height=auto`: the title's height at that width, as without a size. */
+ | {
+    type: 'size';
+    id: string;
+    width: number;
+    height?: number;
+    line: number;
+};
+export type Strength = 'prefer' | 'required';
+/**
+ * What `near id ref` places against: `ref` itself when it is a sibling of `id`, else the group
+ * around `ref` that is `id`'s sibling. Undefined when `ref` is not inside one.
+ */
+export declare function nearAnchor(by: Map<string, ModelObject>, id: string, ref: string): string | undefined;
+export type NearSide = 'right' | 'left' | 'above' | 'below';
+export type HintType = Hint['type'];
+export declare const POSITION_HINTS: HintType[];
+export interface Model {
+    title: string;
+    objects: ModelObject[];
+    edges: ModelEdge[];
+    layouts: ModelLayout[];
+    hints: Hint[];
+    /** Router settings from a `routing` statement. */
+    routing: Partial<RoutingSettings>;
+    /** Theme, overrides and color definitions from `theme` and `theme-color` statements. */
+    appearance: DiagramAppearance;
+    /** Source line of the `theme` statement, and of each `theme-color` by `family:shade`. */
+    themeLine: number;
+    colorLines: Map<string, number>;
+    /** Source line of each `legend` entry, in order. */
+    legendLines: number[];
+    /** Source line of each `note`, in order. */
+    noteLines: number[];
+    /** Source line of each `footnote`, in order. */
+    footnoteLines: number[];
+    /** Source line of each ID an emphasis state lists, by `state:id`. */
+    stateLines: Map<string, number>;
+    /** Sequence diagrams: `phase` statements, each a run of messages drawn as a row band. */
+    phases: Array<{
+        id: string;
+        label: string;
+        ids: string[];
+        line: number;
+    }>;
+    /** Sequence diagrams: the `was-order` statement, the older version's message order. */
+    wasOrder?: {
+        ids: string[];
+        line: number;
+    };
+    /** Problems that do not stop the file from drawing, such as a `config` key set twice. */
+    warnings: {
+        code: string;
+        message: string;
+        line: number;
+    }[];
+}
+/** `config` keys and the setting each sets. */
+export declare const CONFIG_KEYS: {
+    readonly 'link-base': "linkBase";
+    readonly editor: "editor";
+    readonly 'strike-removed': "strikeRemoved";
+};
+/** Theme attributes in the file and the override each sets. */
+export declare const THEME_ATTRS: {
+    readonly 'padding-x': "paddingX";
+    readonly 'padding-y': "paddingY";
+    readonly radius: "radius";
+    readonly 'title-font': "titleFont";
+    readonly 'annotation-font': "annotationFont";
+    readonly canvas: "canvas";
+    readonly text: "text";
+    readonly connection: "connection";
+};
+type Param<K extends string> = {
+    key: K;
+    min: number;
+    max: number;
+} | {
+    key: K;
+    choices: readonly string[];
+};
+/**
+ * Layout engines a file can name. `separate` is left out: it only repairs overlaps in the current
+ * drawing, so it cannot be recomputed from the source.
+ */
+export declare const ENGINES: readonly LayoutAlgorithmId[];
+/** Engine settings by source attribute. Ranges match the engine's own limits. */
+export declare const ENGINE_PARAMS: Record<string, Param<keyof LayoutSettings>>;
+/** Router settings by source attribute. Ranges match the router's own limits. */
+export declare const ROUTING_PARAMS: Record<string, Param<keyof RoutingSettings>>;
+/** Source attribute for an engine or router setting. */
+export declare const paramAttr: (table: Record<string, Param<string>>, key: string) => string | undefined;
+export declare const isIdentifier: (s: string) => boolean;
+export declare const COLORS: DslColor[];
+export declare const DSL_SHAPES: DslShape[];
+/** Shapes a node's box can draw as it was: a marker's box is a thin cut, so it has no other shape. */
+export declare const PAST_SHAPES: ("text" | "diamond" | "circle" | "box" | "pill")[];
+/** Parse and validate source. Throws `DslError` with a line number for the first problem. */
+export declare function parseModel(source: string | SourceDoc): Model;
+/**
+ * The container that lays an object out: its parent, or the nearest framed container above it
+ * when its parent is a soft or frameless group. Soft groups are never layout scopes.
+ */
+export declare function layoutParent(by: Map<string, ModelObject>, id: string): string;
+export {};

package/dist/types/src/engines/explorer-engine.d.ts

@@ -0,0 +1,67 @@
+import type { Diagram, LayoutAlgorithmId, LayoutIntent } from '../model/types.js';
+import type { LayoutReport, LayoutScope } from './layout-engine.js';
+import type { PriorRoute, RouteInput, RoutingResult } from './routing-engine.js';
+
+export type ParamValue = string | number | boolean;
+
+export interface ParamDefinition {
+  name: string;
+  values: ParamValue[];
+  passOnly?: boolean;
+}
+
+export type ComparisonMode = 'layout' | 'routing';
+export type ComparisonRun = 'rebuild' | 'warm' | 'pass';
+
+export interface ComparisonConfig {
+  mode: ComparisonMode;
+  /** Engines, the suggested routing alternatives, or a grid of parameter values. */
+  kind: 'algorithms' | 'routes' | 'parameters';
+  algorithm: LayoutAlgorithmId;
+  algorithms: LayoutAlgorithmId[];
+  axisA: string;
+  valuesA: string;
+  axisB: string;
+  valuesB: string;
+  run: ComparisonRun;
+  maxIterations: number;
+  scope: LayoutScope;
+  autoPorts: boolean;
+  selected: string[];
+  containerId?: string;
+  fixedIds: string[];
+  intent: LayoutIntent;
+  viewport: { w: number; h: number };
+  priorRoutes: PriorRoute[];
+}
+
+export interface CandidateSpec {
+  key: string;
+  title: string;
+  subtitle: string;
+  patch: Record<string, ParamValue>;
+}
+
+export interface CandidateResult {
+  spec: CandidateSpec;
+  document: Diagram;
+  report: LayoutReport | null;
+  routing: RoutingResult;
+}
+
+export const ExplorerLab: {
+  layoutParams: Record<string, ParamDefinition>;
+  routeParams: Record<string, ParamDefinition>;
+  parseValues(key: string, text: string, mode?: ComparisonMode): ParamValue[];
+  effectiveParams(
+    algorithm: LayoutAlgorithmId,
+    run: ComparisonRun,
+  ): Record<string, ParamDefinition>;
+  specs(config: ComparisonConfig): CandidateSpec[];
+  sceneInput(doc: Diagram): RouteInput;
+  candidate(
+    baseline: Diagram,
+    spec: CandidateSpec,
+    config: ComparisonConfig,
+  ): Promise<CandidateResult>;
+};

package/dist/types/src/engines/layout-engine.d.ts

@@ -0,0 +1,120 @@
+import type {
+  Diagram,
+  IntentPlacement,
+  LayoutAlgorithmId,
+  LayoutIntent,
+  LayoutSettings,
+  NodeGeometry,
+  Point,
+} from '../model/types.js';
+
+export type LayoutSettingKey =
+  | 'boundaryPull'
+  | 'hierarchySweeps'
+  | 'groupGap'
+  | 'rankGap'
+  | 'edgeLength'
+  | 'repulsion'
+  | 'flowStrength'
+  | 'alignment'
+  | 'compactness'
+  | 'gridStrength'
+  | 'ordering'
+  | 'fold'
+  | 'rootId';
+
+export interface LayoutAlgorithm {
+  id: LayoutAlgorithmId;
+  name: string;
+  family: string;
+  short: string;
+  detail: string;
+  controls: LayoutSettingKey[];
+}
+
+export interface LayoutMetrics {
+  overlaps: number;
+  overlapArea: number;
+  width: number;
+  height: number;
+  aspect: number;
+  area: number;
+  linkLength: number;
+}
+
+export type LayoutScope = 'all' | 'selection' | 'neighbourhood' | 'container';
+
+export interface LayoutOptions extends Partial<LayoutSettings> {
+  scope?: LayoutScope;
+  containerId?: string;
+  selected?: string[];
+  fixedIds?: string[];
+  viewport?: { w: number; h: number };
+  warmStart?: boolean;
+  settle?: boolean;
+  maxIterations?: number;
+  trace?: boolean;
+  rebuild?: boolean;
+}
+
+export type Termination = 'settled' | 'objective plateau' | 'iteration limit' | 'bounded pass';
+
+export interface LayoutReport {
+  intent: Array<{
+    role: string;
+    id: string;
+    placement: IntentPlacement;
+    error: number;
+    satisfied: boolean;
+    pinned: boolean;
+  }>;
+  backwardEdges: number;
+  directedEdges: number;
+  feedbackEdges: number;
+  algorithm: LayoutAlgorithmId;
+  name: string;
+  mode: 'pass' | 'rebuild' | 'journey';
+  scope: LayoutScope;
+  moved: number;
+  maxDisplacement: number;
+  rmsDisplacement: number;
+  movementLimit: number | null;
+  iterations: number;
+  batches: number;
+  before: LayoutMetrics;
+  after: LayoutMetrics;
+  warnings: string[];
+  milliseconds: number;
+  deterministic: boolean;
+  termination: Termination;
+  solverStops: Array<{ reason: string }>;
+  /** Added by the app: where the computation ran. */
+  thread?: string;
+  /** Added by the app when a timeline step is kept. */
+  selectedStep?: number;
+}
+
+export interface TraceFrame {
+  nodes: NodeGeometry;
+  iteration: number;
+  phase: string;
+  metrics: LayoutMetrics;
+}
+
+export interface LayoutResult {
+  document: Diagram;
+  report: LayoutReport;
+  trace?: TraceFrame[];
+}
+
+export const LayoutLab: {
+  algorithms: LayoutAlgorithm[];
+  defaults: LayoutSettings;
+  settings(values?: object): LayoutSettings;
+  compute(doc: Diagram, opts: LayoutOptions): Promise<LayoutResult>;
+  normalizeIntent(raw: unknown, validIds?: Set<string> | null): LayoutIntent;
+  placements: Record<IntentPlacement, [number, number]>;
+  topology(items: Array<{ id: string }>, edges: unknown[], intent?: LayoutIntent): unknown;
+};
+
+export type { Point };

package/dist/types/src/engines/routing-engine.d.ts

@@ -0,0 +1,108 @@
+import type { EdgeLayout, Point, Rect, RoutingSettings, ShapeKind, Side } from '../model/types.js';
+
+export interface RouteNodeInput extends Rect {
+  id: string;
+  parentId?: string;
+  shape: ShapeKind;
+  /** The stub for lines that end on an open group's frame: the group's rectangle. */
+  frame?: boolean;
+}
+
+export interface RouteGroupInput extends Rect {
+  id: string;
+  parentId?: string;
+  collapsed: boolean;
+  /** Width of the header's icon and title from the group's left edge; the rest of the band is open. */
+  titleWidth?: number;
+  /** Height of the title band the router keeps clear; 28 when unset. */
+  titleHeight?: number;
+}
+
+export interface RouteEdgeInput {
+  id: string;
+  from: string;
+  to: string;
+  directed?: boolean;
+  cfg: EdgeLayout;
+}
+
+export interface RouteInput {
+  nodes: RouteNodeInput[];
+  groups: RouteGroupInput[];
+  edges: RouteEdgeInput[];
+}
+
+export interface Route {
+  id: string;
+  from: string;
+  to: string;
+  fromSide: Side;
+  toSide: Side;
+  fromOffset: number;
+  toOffset: number;
+  points: Point[];
+  blocked: boolean;
+  reason?: string;
+}
+
+export interface PriorRoute {
+  id: string;
+  fromSide: Side;
+  toSide: Side;
+}
+
+export interface RoutingReport {
+  crossings: number;
+  shared: number;
+  lanePairs: number;
+  laneDeficit: number;
+  minimumConflictingGap: number | null;
+  requestedEdgeGap: number;
+  blocked: number;
+  bends: number;
+  length: number;
+  initial: unknown;
+  accepted: number;
+  nudged: number;
+  tidied?: number;
+  edges: number;
+  milliseconds: number;
+  passes: number;
+}
+
+export interface RoutingResult {
+  routes: Route[];
+  report: RoutingReport;
+}
+
+export interface RoutingOptions extends Partial<RoutingSettings> {
+  previous?: PriorRoute[];
+  quick?: boolean;
+  /** A reading direction for every edge without its own `cfg.flow`; forward edges run along it. */
+  direction?: 'right' | 'down';
+  /**
+   * Keep fans on the sides facing their other ends, off far sides, and a full standoff away
+   * from their own end boxes. On unless false.
+   */
+  facing?: boolean;
+  /**
+   * Keep lines out of a group's title band, except a line straight into or out of a member's
+   * top. On unless false.
+   */
+  titleBands?: boolean;
+  /** Search each route near its two boxes first, and the whole grid only when that fails. On unless false. */
+  window?: boolean;
+  /** Even out ports, fans and corridors after routing. On unless false. */
+  tidy?: boolean;
+  /**
+   * In the tidy pass, straighten steps under 12px by sliding a run (and its port, or through a
+   * fold lane's waypoints) onto the next. On unless false.
+   */
+  jogs?: boolean;
+}
+
+export const RouteLab: {
+  compute(input: RouteInput, options?: RoutingOptions): RoutingResult;
+  settings(raw?: Partial<RoutingSettings>): RoutingSettings;
+  defaults: RoutingSettings;
+};

package/dist/types/src/engines/sculpt-engine.d.ts

@@ -0,0 +1,71 @@
+import type { Diagram, LayoutSettings, NodeGeometry, Point } from '../model/types.js';
+import type { LayoutMetrics, LayoutOptions, LayoutReport } from './layout-engine.js';
+
+export type BrushMode = 'tidy' | 'flow' | 'space' | 'restore' | 'protect';
+
+export interface BrushSettings {
+  radius: number;
+  strength: number;
+  softness: number;
+  step: number;
+  mode: BrushMode;
+  holdRestored: boolean;
+}
+
+export interface DabOptions extends Partial<BrushSettings> {
+  point?: Point;
+  worldRadius?: number;
+  reference?: NodeGeometry | null;
+  protectedIds?: string[];
+}
+
+export interface DabResult {
+  document: Diagram;
+  weights: Record<string, number>;
+  locked: string[];
+  moved: string[];
+  maxDisplacement: number;
+  blocked: boolean;
+  attenuation?: number;
+  mode: BrushMode;
+}
+
+export interface TimelineFrame {
+  nodes: NodeGeometry;
+  iteration: number;
+  phase: string;
+  metrics: LayoutMetrics;
+  index: number;
+  moved: number;
+  travel: number;
+  cumulative: number;
+  maxMove: number;
+}
+
+export interface TimelineBookmark {
+  index: number;
+  title: string;
+}
+
+export interface Timeline {
+  schemaVersion: 1;
+  kind: 'diagram-studio-journey';
+  baseline: Diagram;
+  settings: LayoutSettings;
+  execution: Record<string, unknown>;
+  report: LayoutReport;
+  frames: TimelineFrame[];
+  finalDocument: Diagram;
+  bookmarks: TimelineBookmark[];
+  createdAt: string;
+  /** Added by the app: routes in effect when the timeline was recorded. */
+  routePrior?: unknown[];
+}
+
+export const SculptLab: {
+  defaults: BrushSettings;
+  settings(input?: Partial<BrushSettings>): BrushSettings;
+  dab(input: Diagram, options?: DabOptions): DabResult;
+  journey(input: Diagram, options?: LayoutOptions): Promise<Timeline>;
+  lookahead(frames: TimelineFrame[], index: number, pixels?: number, scale?: number): number;
+};

package/dist/types/src/lib/font-data.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The bundled diagram fonts as data URLs, for SVG exports that must render without the app.
+ * The browser loads this module only when exporting; the CLI bundles it.
+ */
+import type { ResolvedAppearance } from '../model/appearance.js';
+/** `@font-face` rules for the faces an appearance draws with. */
+export declare function fontFaceCss(look: ResolvedAppearance): string;
+/** Make the bundled faces available to the page, so the canvas draws with measured fonts. */
+export declare function registerFonts(): void;