@draftably/runtime 0.0.0-stage → 0.1.0

package/dist/types/src/model/types.d.ts

@@ -0,0 +1,277 @@
+export type Point = {
+    x: number;
+    y: number;
+};
+export type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type Side = 'left' | 'right' | 'top' | 'bottom';
+export type PortSide = Side | 'auto';
+export type Direction = 'RIGHT' | 'DOWN';
+export type Theme = 'light' | 'dark';
+import type { DiagramAppearance, Shade } from './appearance.js';
+import type { EndMarker } from './markers.js';
+import type { Spot, Status } from './status.js';
+export type ShapeKind = 'box' | 'pill' | 'circle' | 'diamond' | 'text' | 'icon' | 'image'
+/** A seam between two cells of a `cells` group. */
+ | 'marker';
+/** A color family: a built-in one, one the file defines, or `auto` for the theme's surface. */
+export type ColorKey = string;
+export type LabelMode = 'center' | 'top' | 'bottom' | 'left' | 'right' | 'detached';
+export interface DiagramNode {
+    id: string;
+    title: string;
+    /** Title before a change, from `was=` on a `~` line. */
+    was?: string;
+    /** Shape before a change, from `was-shape=` on a `~` line. */
+    wasShape?: ShapeKind;
+    /** Count before a change, from `was-count=` on a `~` line; 1 means a single box. */
+    wasCount?: number | string;
+    /** A link to open from exported drawings. */
+    href?: string;
+    /** How many things this box stands for, or a symbol such as `N`; drawn as a stack with a badge. */
+    count?: number | string;
+    /** A cell's columns (or units), or `var` for a field of variable length. */
+    span?: number | 'var';
+    parentId?: string;
+    image?: string;
+    /** A sequence participant: length of the dashed lifeline below the box. */
+    lifeline?: number;
+}
+export interface DiagramGroup {
+    id: string;
+    title: string;
+    /** Title before a change, from `was=` on a `~` line. */
+    was?: string;
+    /** A link to open from exported drawings. */
+    href?: string;
+    parentId?: string;
+    /** `soft` draws a tint behind the members instead of a frame; `none` draws nothing. */
+    frame?: 'soft' | 'none';
+    /** Lines the title wraps to, when more than one; the header grows by a line for each. */
+    titleLines?: number;
+    /** A soft group's tint: rectangles relative to the group's top left; the first holds the label. */
+    hull?: Rect[];
+}
+export interface DiagramEdge {
+    id: string;
+    from: string;
+    to: string;
+    label: string;
+    /** Label before a change, from `was=` on a `~` line. */
+    was?: string;
+    directed: boolean;
+    /** The mark at the target end, when it isn't the plain arrow; see `headOf`. */
+    head?: EndMarker;
+    /** The mark at the source end, when it has one; see `tailOf`. */
+    tail?: EndMarker;
+    emphasis: boolean;
+    dashed: boolean;
+    /** How it differs between two versions of the diagram. */
+    status?: Status;
+    /** How the drawn emphasis state treats it; see `withState`. */
+    spot?: Spot;
+}
+export interface NodeLayout extends Rect {
+    manual?: boolean;
+    pinned?: boolean;
+}
+export interface EdgeLayout {
+    fromSide?: PortSide;
+    toSide?: PortSide;
+    labelDx?: number;
+    labelDy?: number;
+    waypoints?: Point[];
+    /** The reading direction of the layout that places both ends; the edge runs along it. */
+    flow?: 'right' | 'down';
+    /** Set by the compiler for a fold's wrap edge: the line it returns along, between two bands. */
+    lane?: Lane;
+    /** From a lane, at route time: where along its target's side the edge arrives, off centre. */
+    toOffset?: number;
+    /** A sequence message: drawn straight between the two lifelines at this height, not routed. */
+    row?: number;
+}
+/**
+ * A channel between two bands of a fold: a level line at `y`, or an upright one at `x`. With
+ * `leave`, the edge leaves its source's side and turns onto the lane at that coordinate; with
+ * `enter`, it runs on along the lane to that coordinate and turns into its target's side.
+ * With `out`, it is a return or skip lane beyond both ends.
+ */
+export type Lane = ({
+    y: number;
+} | {
+    x: number;
+}) & {
+    leave?: number;
+    enter?: number;
+    /**
+     * A lane beyond both ends, outside their band: the edge leaves by the side facing it, runs
+     * along it, and at `enter` turns into the target's side that faces back toward the source.
+     */
+    out?: boolean;
+    /**
+     * With `out`: the gap beside the target holds another edge's label, so the edge arrives square
+     * on the target's face toward the lane, at `enter` (its middle), instead of turning into that gap.
+     */
+    face?: boolean;
+};
+export interface LabelLayout {
+    mode?: LabelMode;
+    dx?: number;
+    dy?: number;
+    width?: number;
+    leader?: boolean;
+}
+export interface ContainerLayout {
+    direction: 'inherit' | Direction;
+    padding: number;
+    manualSize: boolean;
+    /** Set for a `cells` group: its members touch, under a title band this tall. */
+    cellsBand?: number;
+    /** A byte or bit layout's extra marks, relative to the group's top-left corner. */
+    cellsChrome?: CellsChrome;
+}
+/** What a byte or bit layout draws besides its cells. */
+export interface CellsChrome {
+    /** Unit numbers in a strip under the title band. */
+    ruler?: {
+        y: number;
+        h: number;
+        ticks: Array<{
+            x: number;
+            label: string;
+        }>;
+    };
+    /** Further pieces of fields that run on past a row's end, by field. */
+    pieces?: Record<string, Rect[]>;
+    /** Fields of variable length, drawn with broken ends. */
+    open?: string[];
+}
+export type IntentRole = 'start' | 'end';
+export type IntentPlacement = 'top-left' | 'left-center' | 'center' | 'top-center' | 'top-right' | 'right-center' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+export type LayoutIntent = Partial<Record<IntentRole, {
+    id: string;
+    placement: IntentPlacement;
+}>>;
+export interface NodeStyle {
+    shape: ShapeKind;
+    color: ColorKey;
+    /** Numeric shade; omitted means the default for the object (500 for nodes, 100 for groups). */
+    shade?: Shade;
+    icon: string;
+    /** How it differs between two versions of the diagram. */
+    status?: Status;
+    /** How the drawn emphasis state treats it; see `withState`. */
+    spot?: Spot;
+}
+export type LayoutAlgorithmId = 'compound-flow' | 'boundary-align' | 'compound-spring' | 'tidy' | 'stress' | 'force' | 'flow' | 'layered' | 'tree' | 'grid' | 'separate';
+export type AspectSetting = 'canvas' | '1' | '1.333' | '1.6' | '2' | '0.75';
+export interface LayoutSettings {
+    algorithm: LayoutAlgorithmId;
+    direction: Direction;
+    mode: 'pass' | 'rebuild';
+    maxMove: number;
+    stability: number;
+    iterations: number;
+    nodeGap: number;
+    rankGap: number;
+    edgeLength: number;
+    repulsion: number;
+    flowStrength: number;
+    alignment: number;
+    compactness: number;
+    gridStrength: number;
+    aspect: AspectSetting;
+    fold: 'auto' | 'never';
+    respectDirection: boolean;
+    ordering: 'stable' | 'crossings';
+    rootId: string;
+    respectManual: boolean;
+    growContainers: boolean;
+    boundaryPull: number;
+    hierarchySweeps: number;
+    groupGap: number;
+}
+export interface RoutingSettings {
+    clearance: number;
+    portGap: number;
+    edgeGap: number;
+    bendPenalty: number;
+    crossingPenalty: number;
+    sharedPenalty: number;
+    parallelPenalty: number;
+    portStability: number;
+    fanoutPenalty: number;
+    passes: number;
+    cornerRadius: number;
+    standoff: number;
+}
+export interface DiagramSettings extends LayoutSettings {
+    snap: boolean;
+    showManual: boolean;
+    routing: RoutingSettings;
+}
+export interface Camera {
+    x: number;
+    y: number;
+    k: number;
+}
+export interface Diagram {
+    schemaVersion: 2;
+    id: string;
+    title: string;
+    graph: {
+        nodes: DiagramNode[];
+        edges: DiagramEdge[];
+        groups: DiagramGroup[];
+    };
+    layout: {
+        nodes: Record<string, NodeLayout>;
+        edges: Record<string, EdgeLayout>;
+        labels: Record<string, LabelLayout>;
+        containers: Record<string, ContainerLayout>;
+        intent: LayoutIntent;
+        /** A sequence diagram's frame and the row bands of its `phase` statements. */
+        sequence?: SequenceLayout;
+    };
+    styles: Record<string, NodeStyle>;
+    collapsed: string[];
+    settings: DiagramSettings;
+    camera: Camera;
+    /** Editor light or dark mode; independent of the diagram's appearance. */
+    theme: Theme;
+    /** Diagram theme, overrides and color definitions. Saved with the diagram. */
+    appearance: DiagramAppearance;
+}
+export type NodeGeometry = Record<string, NodeLayout>;
+/** The panel a sequence diagram is drawn on, and a row band for each `phase`. */
+export interface SequenceLayout {
+    panel: Rect;
+    phases: SequencePhase[];
+    /** Left edge for phase labels, when a note in the left margin widens the panel past them. */
+    phaseX?: number;
+    /** Spots of the notes that sit in a side margin, by index in `appearance.notes`. */
+    notes?: Array<Rect | null>;
+    /** With `notes`: the panel without those margins, for drawings with their notes in the frame. */
+    inner?: Rect;
+    /**
+     * From `was-order`: each message's row and the phase bands in the older message order, and how
+     * much further that order runs down the panel.
+     */
+    before?: {
+        rows: Record<string, number>;
+        phases: SequencePhase[];
+        grow: number;
+    };
+}
+export type SequencePhase = {
+    id: string;
+    label: string;
+    y: number;
+    h: number;
+};
+/** Any object that can be selected: a shape, a container, or a connection. */
+export type Entity = DiagramNode | DiagramGroup | DiagramEdge;

package/dist/types/src/runtime/element.d.ts

@@ -0,0 +1,12 @@
+import type { UpdateResult, ViewerHandle, ViewerOptions } from './viewer.js';
+export interface DraftDiagramElement extends HTMLElement {
+    source: string;
+    options: ViewerOptions;
+    readonly viewer?: ViewerHandle;
+    readonly updateComplete: Promise<UpdateResult | undefined>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'draft-diagram': DraftDiagramElement;
+    }
+}

package/dist/types/src/runtime/index.d.ts

@@ -0,0 +1,5 @@
+import type { RenderOptions, RenderResult, ValidateOptions, ValidationResult } from './types.js';
+export declare const renderSvg: (source: string, options?: RenderOptions) => Promise<RenderResult>;
+export declare const validate: (source: string, options?: ValidateOptions) => Promise<ValidationResult>;
+export { runtimeVersion, fontMetricsVersion } from './version.js';
+export type { CompileLimits, CommonRenderOptions, Diagnostic, DiagramSummary, ItemSummary, LinkPolicy, RenderFailure, RenderLimits, RenderOptions, RenderResult, RenderedDiagram, Severity, SourceLocation, ValidateOptions, ValidationResult, } from './types.js';

package/dist/types/src/runtime/policy.d.ts

@@ -0,0 +1,7 @@
+import type { Diagram } from '../model/types.js';
+import type { Diagnostic, RenderOptions } from './types.js';
+export declare function assertOptions(options: RenderOptions): void;
+/** A link in note or footnote text: kept only as a safe HTTP(S) URL under a safe policy. */
+export declare const textLink: (options: RenderOptions) => (href: string) => string | null;
+/** The host resolves first; final validation never trusts the callback or authored link-base. */
+export declare function applyLinks(doc: Diagram, options: RenderOptions): Diagnostic[];

package/dist/types/src/runtime/render.d.ts

@@ -0,0 +1,10 @@
+import { type Scene } from '../dsl/compile.js';
+import type { RenderOptions, RenderResult, ValidateOptions, ValidationResult } from './types.js';
+export interface InternalRender {
+    result: RenderResult;
+    scene?: Scene;
+}
+/** Internal bridge for repository callers that need the editable Scene alongside public output. */
+export declare function renderWithScene(source: string, options?: RenderOptions): Promise<InternalRender>;
+export declare function renderSvg(source: string, options?: RenderOptions): Promise<RenderResult>;
+export declare function validate(source: string, options?: ValidateOptions): Promise<ValidationResult>;

package/dist/types/src/runtime/svg-renderer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A standalone SVG of a projected diagram for terminal and agent inspection. It draws with the
+ * same appearance, shapes and title wrapping as the canvas and embeds the fonts it uses.
+ */
+import { type ResolvedAppearance } from '../model/appearance.js';
+import type { Diagram, Rect } from '../model/types.js';
+/** How an object's `href` is written into the file; as written unless the caller says. */
+export interface SvgOptions {
+    href?: (href: string) => string;
+    /** Writes a link in note or footnote text; null draws the text without a link. */
+    textHref?: (href: string) => string | null;
+    /** Draw every emphasis state as its own panel. */
+    states?: boolean;
+    /** Host-owned policies used by the portable runtime. */
+    idPrefix?: string;
+    fontCss?: string;
+    title?: string;
+    description?: string;
+    styleNonce?: string;
+    linkTarget?: '_self' | '_blank';
+    metadata?: string;
+    maxOutputBytes?: number;
+}
+export declare class SvgLimitError extends Error {
+}
+/**
+ * A sequence diagram's panel, a light surface with a border that bounds the exchange, and a row
+ * band for each phase with its label in a tab at the left edge. Drawn under everything else.
+ */
+export declare function sequenceBackdrop(doc: Diagram, look: ResolvedAppearance): {
+    panel: string[];
+    phases: string[];
+};
+/** Inset of a phase label from its band's top left corner. */
+export declare const PHASE_TAB = 8;
+/** A thin stripe across the top of a box, inside its rounded corners. */
+export declare function accentPath(r: Rect, radius: number): string;
+export declare function renderSvg(doc: Diagram, opts?: SvgOptions): string;

package/dist/types/src/runtime/types.d.ts

@@ -0,0 +1,109 @@
+export type Severity = 'error' | 'warning' | 'info';
+export interface SourceLocation {
+    sourceId?: string;
+    line: number;
+    column?: number;
+}
+export interface Diagnostic {
+    code: string;
+    severity: Severity;
+    message: string;
+    location?: SourceLocation;
+    itemIds: readonly string[];
+    related?: readonly {
+        message: string;
+        location: SourceLocation;
+    }[];
+    nativeCode?: string;
+}
+export interface CompileLimits {
+    maxSourceChars: number;
+    maxSourceBytes: number;
+    maxObjects: number;
+    maxEdges: number;
+    maxDepth: number;
+}
+export interface RenderLimits extends CompileLimits {
+    maxOutputBytes: number;
+}
+export type LinkPolicy = {
+    mode: 'none';
+} | {
+    mode: 'safe';
+    baseUrl?: string;
+    target?: '_self' | '_blank';
+    resolve?: (request: {
+        itemId: string;
+        href: string;
+    }) => string | null;
+    cacheKey?: string;
+};
+export interface CommonRenderOptions {
+    title?: string;
+    description?: string;
+    includeSource?: boolean;
+    links?: LinkPolicy;
+    styleNonce?: string;
+    state?: string | null;
+    sourceId?: string;
+    signal?: AbortSignal;
+    limits?: Partial<RenderLimits>;
+}
+export type RenderOptions = CommonRenderOptions & ({
+    target?: 'image';
+    idPrefix?: never;
+    fonts?: 'embed';
+} | {
+    target: 'inline';
+    idPrefix: string;
+    fonts?: 'embed' | 'host';
+});
+export interface ValidateOptions {
+    sourceId?: string;
+    signal?: AbortSignal;
+    limits?: Partial<CompileLimits>;
+}
+export interface ItemSummary {
+    id: string;
+    kind: 'node' | 'group' | 'edge';
+    label: string;
+    line: number;
+    from?: string;
+    to?: string;
+}
+export interface DiagramSummary {
+    title: string;
+    description?: string;
+    width: number;
+    height: number;
+    viewBox: readonly [number, number, number, number];
+    items: readonly ItemSummary[];
+    states: readonly {
+        id: string;
+        label: string;
+    }[];
+    activeState: string | null;
+}
+export interface RenderedDiagram extends DiagramSummary {
+    svg: string;
+    provenance: {
+        runtimeVersion: string;
+        dslVersion: 1;
+        fontMetricsVersion: string;
+        renderContextVersion: string;
+    };
+}
+export type RenderFailure = {
+    ok: false;
+    reason: 'input' | 'limit' | 'aborted' | 'environment' | 'internal';
+    diagnostics: readonly Diagnostic[];
+};
+export type RenderResult = {
+    ok: true;
+    value: RenderedDiagram;
+    diagnostics: readonly Diagnostic[];
+} | RenderFailure;
+export type ValidationResult = {
+    ok: true;
+    diagnostics: readonly Diagnostic[];
+} | RenderFailure;

package/dist/types/src/runtime/version.d.ts

@@ -0,0 +1,2 @@
+export declare const runtimeVersion: string;
+export { fontMetricsVersion } from '../model/font-faces.js';

package/dist/types/src/runtime/viewer.d.ts

@@ -0,0 +1,84 @@
+import { fontMetricsVersion, runtimeVersion } from './version.js';
+import type { CommonRenderOptions, Diagnostic, LinkPolicy, RenderFailure, RenderResult } from './types.js';
+export { fontMetricsVersion, runtimeVersion };
+export interface Camera {
+    centerX: number;
+    centerY: number;
+    zoom: number;
+}
+export type ViewerExecution = {
+    mode: 'worker';
+    createWorker?: () => Worker;
+    timeoutMs?: number;
+} | {
+    mode: 'main';
+};
+export type ViewerRenderOptions = Omit<CommonRenderOptions, 'signal' | 'state'> & {
+    fonts?: 'host' | 'embed';
+};
+export interface ViewerOptions {
+    label?: string;
+    toolbar?: boolean;
+    execution?: ViewerExecution;
+    render?: ViewerRenderOptions;
+}
+export interface UpdateOptions {
+    camera?: 'preserve' | 'fit';
+    state?: string | null;
+    signal?: AbortSignal;
+}
+export type UpdateResult = {
+    status: 'committed';
+    revision: number;
+    value: Extract<RenderResult, {
+        ok: true;
+    }>['value'];
+    diagnostics: readonly Diagnostic[];
+} | {
+    status: 'error';
+    revision: number;
+    error: RenderFailure;
+} | {
+    status: 'superseded' | 'destroyed' | 'aborted';
+    revision: number;
+};
+export interface ViewerEvents {
+    render: {
+        revision: number;
+        value: Extract<RenderResult, {
+            ok: true;
+        }>['value'];
+    };
+    diagnostics: {
+        revision: number;
+        diagnostics: readonly Diagnostic[];
+        stale: boolean;
+    };
+    camera: {
+        camera: Camera;
+        reason: 'user' | 'resize' | 'fit' | 'api';
+    };
+    itemactivate: {
+        id: string;
+        kind: 'node' | 'group' | 'edge';
+        input: 'pointer' | 'keyboard';
+        revision: number;
+    };
+    link: {
+        itemId: string;
+        href: string;
+        target: '_self' | '_blank';
+        preventDefault(): void;
+    };
+}
+export interface ViewerHandle {
+    update(source: string, options?: UpdateOptions): Promise<UpdateResult>;
+    on<K extends keyof ViewerEvents>(type: K, listener: (event: ViewerEvents[K]) => void): () => void;
+    getCamera(): Camera;
+    setCamera(camera: Camera): void;
+    fit(): void;
+    focusItem(id: string): boolean;
+    destroy(): void;
+}
+export declare function mountViewer(host: HTMLElement, options?: ViewerOptions): ViewerHandle;
+export type { LinkPolicy };

package/dist/viewer.css

@@ -0,0 +1,90 @@
+.draft-viewer {
+  --dv-border: #cbd5e1;
+  --dv-ink: #1e293b;
+  --dv-bg: #fff;
+  display: grid;
+  grid-template-rows: auto minmax(8rem, 1fr) auto auto;
+  box-sizing: border-box;
+  height: 100%;
+  min-height: 16rem;
+  border: 1px solid var(--dv-border);
+  border-radius: 0.5rem;
+  color: var(--dv-ink);
+  background: var(--dv-bg);
+  font:
+    14px/1.45 system-ui,
+    sans-serif;
+  overflow: hidden;
+}
+.draft-viewer__toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.5rem;
+  border-bottom: 1px solid var(--dv-border);
+}
+.draft-viewer__toolbar button {
+  font: inherit;
+  padding: 0.25rem 0.55rem;
+  border: 1px solid var(--dv-border);
+  border-radius: 0.3rem;
+  background: var(--dv-bg);
+  color: inherit;
+}
+.draft-viewer button:focus-visible,
+.draft-viewer__viewport:focus-visible {
+  outline: 3px solid #2563eb;
+  outline-offset: 2px;
+}
+.draft-viewer__viewport {
+  position: relative;
+  overflow: hidden;
+  min-height: 8rem;
+  touch-action: none;
+  cursor: grab;
+}
+.draft-viewer__viewport:active {
+  cursor: grabbing;
+}
+.draft-viewer__viewport svg {
+  position: absolute;
+  left: 0;
+  top: 0;
+  overflow: visible;
+}
+.draft-viewer__status {
+  margin: 0;
+  padding: 0.35rem 0.65rem;
+}
+.draft-viewer__outline {
+  margin: 0;
+  padding: 0.4rem 0.8rem 0.6rem 2rem;
+  max-height: 7rem;
+  overflow: auto;
+  border-top: 1px solid var(--dv-border);
+}
+.draft-viewer__outline:empty {
+  display: none;
+}
+.draft-viewer--stale .draft-viewer__status {
+  color: #9a3412;
+  background: #fff7ed;
+}
+.draft-viewer__status:empty {
+  display: none;
+}
+@media (prefers-reduced-motion: reduce) {
+  .draft-viewer * {
+    scroll-behavior: auto !important;
+    transition: none !important;
+  }
+}
+@media (max-width: 600px) {
+  .draft-viewer__toolbar {
+    gap: 0.3rem;
+  }
+  .draft-viewer__toolbar button {
+    padding-inline: 0.45rem;
+  }
+}