@skygraph/core 0.0.0-placeholder.0 → 0.4.0

package/dist/graph.d.ts

@@ -0,0 +1,542 @@
+import { C as Core } from './types-B-rKQJ4R.js';
+
+/**
+ * GraphEngine types — the diagram (Visio-like) domain engine.
+ *
+ * Design intent (see ARCHITECTURE.md / chat-derived spec):
+ *
+ *   - The engine knows ONLY topology + minimal geometry needed for routing /
+ *     hit-testing. It does NOT know about React, DOM, SVG, canvas — those live
+ *     in `@skygraph/react/<Diagram component>`.
+ *   - A Node has an `outline` (rect / ellipse / polygon / flattened path),
+ *     a `transform` (position in parent space), an optional `parentId` for
+ *     hierarchy (groups, sub-groups), and an `anchorPolicy` describing how to
+ *     generate connection points along the outline.
+ *   - An Edge connects two anchors (each by node id + either an anchor id or
+ *     a normalized perimeter parameter `s ∈ [0..1]`).
+ *   - All anchor IDs are stable across `anchorPolicy` changes for the same
+ *     outline kind, so existing edges do not get "torn off" when the user
+ *     bumps `k` from 3 to 5.
+ */
+type NodeId = string;
+type EdgeId = string;
+type AnchorId = string;
+/**
+ * 2D point in the local coordinate space of an outline.
+ * The first element is x, the second is y.
+ */
+type Point = readonly [number, number];
+/**
+ * Axis-aligned bounding box in world space (no rotation).
+ * Computed from `transform` + `outline`. Used for broad-phase collision /
+ * spatial indexing in the routing layer.
+ */
+interface AABB {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Oriented bounding box in world space — a rectangle that may be rotated
+ * relative to the world axes. Returned by {@link GraphEngine.getNodeOBB}
+ * and consumed by selection / manipulator overlays that need a tight fit
+ * around a rotated node. See `obb.ts` for the helper module.
+ *
+ * `halfWidth` / `halfHeight` are pre-multiplied by world scale, so an OBB
+ * with `angle === 0` describes the same rectangle as the matching AABB
+ * (modulo the centre-vs-top-left representation).
+ */
+interface OBB$1 {
+    readonly center: Point;
+    readonly halfWidth: number;
+    readonly halfHeight: number;
+    readonly angle: number;
+}
+/**
+ * Visual outline of a node, expressed in the node's local coordinate space.
+ *
+ * - `rect` / `ellipse` are parametric primitives; the engine generates anchors
+ *   along their boundary on demand.
+ * - `polygon` carries explicit vertices.
+ * - `path` is a "flattened approximation" — the visual layer (React) is free
+ *   to render a curve (SVG path, Bezier, ...) but commits a discrete polyline
+ *   to the engine. This way the engine never needs to know about cubic Beziers.
+ */
+type Outline = {
+    readonly kind: 'rect';
+    readonly w: number;
+    readonly h: number;
+} | {
+    readonly kind: 'ellipse';
+    readonly rx: number;
+    readonly ry: number;
+} | {
+    readonly kind: 'polygon';
+    readonly verts: readonly Point[];
+} | {
+    readonly kind: 'path';
+    readonly flatten: readonly Point[];
+};
+/**
+ * 2D affine-ish transform of a node within its parent.
+ * Only translate is required; rotate/scale are optional for the v0 engine.
+ */
+interface NodeTransform {
+    /** X position in the parent's local space. */
+    x: number;
+    /** Y position in the parent's local space. */
+    y: number;
+    /** Rotation in radians. Optional; default 0. */
+    rot?: number;
+    /** Uniform scale factor. Optional; default 1. */
+    scale?: number;
+}
+/**
+ * Strategy for generating anchor points on a node outline.
+ *
+ *   - `perEdge: { k: 1..10 }` — primitives only (rect, polygon).
+ *     Corners are always anchors. `k` evenly-spaced anchors per edge,
+ *     not counting corners (open interval) — bumping `k` does NOT shift
+ *     existing anchor IDs.
+ *
+ *   - `byLength: { density }` — uniform along the perimeter at the given
+ *     distance step (in local units). Works for every outline kind.
+ *
+ *   - `manual: anchors[]` — explicit anchor list with stable IDs and
+ *     normalized perimeter parameter `s ∈ [0..1]`.
+ */
+type AnchorPolicy = {
+    readonly kind: 'perEdge';
+    readonly k: number;
+} | {
+    readonly kind: 'byLength';
+    readonly density: number;
+} | {
+    readonly kind: 'manual';
+    readonly anchors: readonly {
+        id: AnchorId;
+        s: number;
+    }[];
+};
+/**
+ * A point on the outline where edges can attach.
+ * `s` is the normalized perimeter parameter (0..1, monotonically increasing
+ * around the outline). Persisting an edge endpoint by `s` makes it stable
+ * under outline edits / anchor regeneration.
+ */
+interface Anchor {
+    /** Stable id assigned by the anchor generator (e.g. `nw`, `edge-0:1of3`). */
+    id: AnchorId;
+    /** Normalized perimeter parameter; `0` is the start of the outline traversal. */
+    s: number;
+    /** Local coordinates on the outline (x, y). */
+    point: Point;
+}
+/**
+ * A graph node — building block of the diagram. Can be a "shape" (with a
+ * visible outline), a "group" (`outline.kind === 'rect'` with `w=h=0` plus
+ * children, or any other size — visual layer decides whether to render
+ * border / background), or a leaf widget. The engine itself does NOT
+ * distinguish — it only sees outline + transform + children-by-parentId.
+ */
+interface GraphNode {
+    /** Stable identity; unique within the graph. */
+    id: NodeId;
+    /** Parent node id, or `null` for root-level nodes. */
+    parentId: NodeId | null;
+    /** Position / rotation / scale in parent space. */
+    transform: NodeTransform;
+    /** Local-space outline. */
+    outline: Outline;
+    /** How anchors are generated along the outline. */
+    anchorPolicy: AnchorPolicy;
+    /** Optional application payload; the engine never inspects it. */
+    data?: unknown;
+    /** Monotonic revision; increments on transform / outline / anchorPolicy change. */
+    geomRevision: number;
+}
+/**
+ * An edge is a connection between two anchors on (possibly different) nodes.
+ *
+ * `endpoint.anchor` may be:
+ *   - an `AnchorId` referring to an explicit / generated anchor;
+ *   - a `{ s }` parameter binding the edge to a perimeter position even when
+ *     the anchor list is regenerated.
+ */
+type EdgeEndpoint = {
+    readonly node: NodeId;
+    readonly anchor: AnchorId;
+} | {
+    readonly node: NodeId;
+    readonly anchor: {
+        readonly s: number;
+    };
+};
+interface GraphEdge {
+    /** Stable identity; unique within the graph. */
+    id: EdgeId;
+    /** Source endpoint. */
+    from: EdgeEndpoint;
+    /** Target endpoint. */
+    to: EdgeEndpoint;
+    /**
+     * Routing hint:
+     *   • `straight`   — single L line between the two anchors.
+     *   • `orthogonal` — axis-aligned polyline (right-angled). Combined
+     *                    with `routeAroundNodes` in `<Diagram>` the
+     *                    router avoids other nodes via A*. The visual
+     *                    layer also draws rounded corners.
+     *   • `bezier`     — single cubic Bezier curve. Control handles
+     *                    extend perpendicular to each node's nearest
+     *                    side, matching React Flow's `getBezierPath`.
+     *   • `manual`     — explicit waypoint polyline.
+     */
+    routing: 'straight' | 'orthogonal' | 'bezier' | 'manual';
+    /** Optional waypoints for `manual` routing (in world coordinates). */
+    waypoints?: readonly Point[];
+    /** Optional application payload. */
+    data?: unknown;
+}
+/**
+ * Snapshot of the current graph state — read-model the engine exposes.
+ * This object is immutable from the consumer's perspective; the engine
+ * publishes a new snapshot on every commit by writing into the Core store
+ * under the `$graph.` prefix.
+ */
+interface GraphState {
+    nodes: ReadonlyMap<NodeId, GraphNode>;
+    edges: ReadonlyMap<EdgeId, GraphEdge>;
+    /** Per-node list of incident edges (incoming + outgoing) for O(degree) lookup. */
+    edgesByNode: ReadonlyMap<NodeId, readonly EdgeId[]>;
+}
+/** Patch type for `moveNode` / `updateNode`. */
+interface NodeUpdate {
+    transform?: Partial<NodeTransform>;
+    outline?: Outline;
+    anchorPolicy?: AnchorPolicy;
+    data?: unknown;
+}
+/** Options for `addNode`. */
+interface NodeInit {
+    /** Optional pre-set id. If omitted, the engine generates one. */
+    id?: NodeId;
+    /** Parent for hierarchy. `null` (default) places the node at the root. */
+    parentId?: NodeId | null;
+    /** Transform in parent space. Defaults to `{ x: 0, y: 0 }`. */
+    transform?: NodeTransform;
+    /** Outline; defaults to a 100×60 rect. */
+    outline?: Outline;
+    /** Anchor strategy; defaults to `{ kind: 'perEdge', k: 1 }`. */
+    anchorPolicy?: AnchorPolicy;
+    /** Application payload. */
+    data?: unknown;
+}
+/** Options for `addEdge`. */
+interface EdgeInit {
+    /** Optional pre-set id. If omitted, the engine generates one. */
+    id?: EdgeId;
+    from: EdgeEndpoint;
+    to: EdgeEndpoint;
+    /** Routing strategy. Defaults to `'straight'`. */
+    routing?: 'straight' | 'orthogonal' | 'bezier' | 'manual';
+    waypoints?: readonly Point[];
+    data?: unknown;
+}
+/**
+ * Public API of the Graph engine. Created via `createGraph(core, options?)`.
+ * The engine is a thin façade over a path-based Core store under `$graph.`.
+ */
+interface GraphEngine {
+    /** Add a node and return its assigned id. */
+    addNode(init?: NodeInit): NodeId;
+    /** Remove a node and all edges incident to it. */
+    removeNode(id: NodeId): void;
+    /** Patch a node's transform / outline / anchorPolicy / data. */
+    updateNode(id: NodeId, patch: NodeUpdate): void;
+    /** Move a node by an absolute new (x, y) in parent space. */
+    moveNode(id: NodeId, x: number, y: number): void;
+    /** Re-parent a node (groups / sub-groups). `null` = root. */
+    setParent(id: NodeId, parentId: NodeId | null): void;
+    /** Add an edge between two endpoints. */
+    addEdge(init: EdgeInit): EdgeId;
+    /** Remove an edge by id. */
+    removeEdge(id: EdgeId): void;
+    /** Get a single node (or undefined). */
+    getNode(id: NodeId): GraphNode | undefined;
+    /** Get a single edge (or undefined). */
+    getEdge(id: EdgeId): GraphEdge | undefined;
+    /** Snapshot of the entire graph state. */
+    getState(): GraphState;
+    /** Direct children (immediate parentId match). */
+    childrenOf(id: NodeId | null): NodeId[];
+    /** Edges incident to a node (incoming + outgoing). */
+    edgesOf(id: NodeId): EdgeId[];
+    /** Compute anchors for a node according to its `anchorPolicy`. */
+    anchorsOf(id: NodeId): Anchor[];
+    /** Compute axis-aligned bounding box of a node in world coordinates. */
+    boundsOf(id: NodeId): AABB;
+    /**
+     * Compute the oriented bounding box of a node in world coordinates.
+     *
+     * For an axis-aligned node (`transform.rot === 0` everywhere up the
+     * parent chain) the OBB and AABB describe the same rectangle. When any
+     * ancestor has a non-zero rotation, the OBB is the tight fit and
+     * `boundsOf` (AABB) becomes a strict superset.
+     */
+    getNodeOBB(id: NodeId): OBB$1;
+    /**
+     * Subscribe to commits — callback fires after every snapshot publish
+     * (any `addNode`, `removeNode`, `addEdge`, etc.). Returns an unsubscribe fn.
+     *
+     * Prefer this for React adapters: it sidesteps the `$graph.snapshot.<id>`
+     * path lookup that varies per engine instance.
+     */
+    subscribe(cb: () => void): () => void;
+    /** Group multiple mutations into one history entry. Optional `label` is
+     *  attached to the resulting `HistoryEntry`. */
+    transaction(fn: () => void, label?: string): void;
+    /**
+     * Add a label to the history without changing the visible state.
+     *
+     * Behaviour depends on context:
+     *
+     *   - **Inside `transaction(fn)`**: commits the in-progress pending
+     *     entry as a sub-boundary (with `label`) and starts a fresh
+     *     capture for the rest of the transaction. Use this to split one
+     *     batch into multiple undo entries.
+     *
+     *   - **Outside a transaction**: re-labels the most recent undo entry.
+     *     Does NOT push a duplicate snapshot — auto-push has already
+     *     captured every meaningful boundary, so a standalone push would
+     *     only clutter the stack.
+     */
+    pushHistory(label?: string): void;
+    /** Restore the previous state, returning `true` if anything was undone. */
+    undo(): boolean;
+    /** Re-apply the most recently undone state, returning `true` on success. */
+    redo(): boolean;
+    /** `true` when there is at least one entry on the undo stack. */
+    canUndo(): boolean;
+    /** `true` when there is at least one entry on the redo stack. */
+    canRedo(): boolean;
+    /** Drop all undo and redo entries (state itself is not affected). */
+    clearHistory(): void;
+    /**
+     * Reset the graph (drops all nodes / edges, clears history).
+     * @internal Test helper.
+     */
+    clear(): void;
+}
+/** Options accepted by `createGraph`. */
+interface GraphEngineOptions {
+    /** Optional debug name for the engine instance. */
+    name?: string;
+}
+
+/**
+ * Reactive diagram engine — the fourth member of the form / table / tree /
+ * **graph** family. State is mirrored into the Core store under `$graph.`
+ * for cross-engine coordination, but the in-memory maps are the source of
+ * truth and the public read API.
+ *
+ * v0 scope (initial Graph engine stream — see CHANGELOG):
+ *   - Node / Edge model + parent hierarchy
+ *   - addNode / removeNode / updateNode / moveNode / setParent
+ *   - addEdge / removeEdge
+ *   - anchor generator (perEdge / byLength / manual)
+ *   - bounds computation (AABB, no rotation)
+ *   - geomRevision bump on geometry-affecting updates
+ *
+ * NOT in v0:
+ *   - orthogonal routing (with obstacle avoidance)
+ *   - undo / redo (covered separately by `plugins/history`)
+ *   - snap-to-grid, drag-and-drop palette
+ *   - rotated bounding boxes (OBB)
+ */
+declare function createGraph(core: Core, options?: GraphEngineOptions): GraphEngine;
+
+/** Options for {@link routeOrthogonal}. */
+interface RouteOrthogonalOptions {
+    /**
+     * Bend preference for the no-obstacle case.
+     *  - `auto` (default) picks H-then-V or V-then-H based on which leg is longer.
+     *  - `hv` forces horizontal first.
+     *  - `vh` forces vertical first.
+     *
+     * Ignored when `obstacles` is non-empty — A* picks bends from costs.
+     */
+    preferred?: 'auto' | 'hv' | 'vh';
+    /**
+     * Rectangular obstacles to avoid (in world coordinates). When omitted /
+     * empty, the router takes the cheap L-route path.
+     */
+    obstacles?: readonly AABB[];
+    /**
+     * Discretisation step for A*. Smaller values give smoother paths at the
+     * cost of more search nodes. Default: 10.
+     */
+    gridSize?: number;
+    /**
+     * Inflate every obstacle by this margin (world units) before clipping.
+     * Useful to keep edges from hugging node borders. Default: 0.
+     */
+    inflate?: number;
+    /**
+     * Hard cap on A* expansions. Acts as a safety net so a pathological
+     * search never hangs the renderer. Default: 5000.
+     */
+    maxNodes?: number;
+    /**
+     * AABB of the source node. When provided, the route exits the side of
+     * the rectangle nearest to `end` with a short perpendicular stub. The
+     * raw `start` point is kept as the first polyline vertex so the edge
+     * still meets the anchor exactly.
+     */
+    sourceBounds?: AABB;
+    /**
+     * AABB of the target node. When provided, the route enters the side of
+     * the rectangle nearest to `start` with a short perpendicular stub. The
+     * raw `end` point is kept as the last polyline vertex.
+     */
+    targetBounds?: AABB;
+    /**
+     * Length (world units) of the perpendicular stub generated when
+     * `sourceBounds` / `targetBounds` is set. Defaults to `max(8, gridSize)`.
+     */
+    stubLength?: number;
+    /**
+     * Snap intermediate waypoints to a grid of this step. Defaults to the
+     * effective `gridSize`. Set to `0` to disable snapping in the no-
+     * obstacle path. A* already operates on the grid so this option only
+     * affects the L-route fallback.
+     */
+    snap?: number;
+}
+/**
+ * Compute an orthogonal (right-angled) path between two points.
+ *
+ *   - With no `sourceBounds` / `targetBounds` and no obstacles: a single-
+ *     bend L-route, identical to the v0 implementation.
+ *   - With `sourceBounds` / `targetBounds`: the route exits/enters from
+ *     the side of each rectangle nearest to the other endpoint.
+ *   - With obstacles: 4-connected A* on a grid of step `gridSize`. Uses
+ *     a turn penalty so straight runs are preferred. Falls back to the
+ *     L-route if A* cannot find a path within `maxNodes` expansions or
+ *     either endpoint is unreachable.
+ *
+ * The third argument also accepts the legacy bare-string form
+ * (`'auto' | 'hv' | 'vh'`) for backwards compatibility with the v0 API.
+ */
+declare function routeOrthogonal(start: Point, end: Point, options?: RouteOrthogonalOptions | 'auto' | 'hv' | 'vh'): readonly Point[];
+/**
+ * Build an SVG path `d` attribute from a polyline.
+ *
+ *   pointsToPath([[0,0], [10,0], [10,5]]) → "M 0 0 L 10 0 L 10 5"
+ */
+declare function pointsToPath(points: readonly Point[]): string;
+/**
+ * Build a rounded-corner SVG path from an orthogonal polyline.
+ *
+ * Every interior bend (where two consecutive segments meet at a right
+ * angle) is replaced with a quadratic Bezier whose control point sits
+ * exactly at the corner — this produces the visual signature of
+ * "smooth-step" edges found in React Flow / draw.io / Lucidchart
+ * without changing the underlying polyline geometry.
+ *
+ *   pointsToRoundedPath([[0,0], [10,0], [10,5]], 4)
+ *     → "M 0 0 L 6 0 Q 10 0 10 4 L 10 5"
+ *
+ * `radius` is clamped to half of the shorter adjacent segment so the
+ * curves never overshoot. Passing `0` makes it identical to
+ * {@link pointsToPath}.
+ */
+declare function pointsToRoundedPath(points: readonly Point[], radius: number): string;
+/** Side of an AABB that an endpoint exits / enters through. */
+type Side = 'top' | 'right' | 'bottom' | 'left';
+interface BezierPathOptions {
+    /** Source point — where the curve starts. */
+    source: Point;
+    /** Side of the source node the curve exits through. */
+    sourceSide: Side;
+    /** Target point — where the curve ends. */
+    target: Point;
+    /** Side of the target node the curve enters through. */
+    targetSide: Side;
+    /**
+     * Curve intensity. `0.25` is React Flow's default — strong enough
+     * to feel natural, soft enough not to loop. Range: `0..1`.
+     */
+    curvature?: number;
+}
+/**
+ * Cubic-bezier SVG path between two endpoints, with control handles
+ * extending perpendicular to each side. Mirrors React Flow's
+ * `getBezierPath` algorithm.
+ *
+ * `sourceSide` / `targetSide` tell the function which face of each
+ * node the endpoint sits on so the curve always exits and enters
+ * perpendicular to the node outline — this is the difference between
+ * a "wavy" edge and a "deliberate" one.
+ *
+ * Use {@link nearestSide} to derive the side from an AABB + opposite
+ * point when the caller doesn't already know it.
+ */
+declare function getBezierPath(opts: BezierPathOptions): string;
+/**
+ * Pick the side of `box` whose midpoint is closest to `target`. Same
+ * logic as the internal helper used by orthogonal routing — exposed
+ * publicly so consumers of `getBezierPath` don't need to re-implement
+ * it.
+ */
+declare function nearestSide(box: AABB, target: Point): Side;
+
+/**
+ * Oriented Bounding Box — a rectangle in world space described by its centre,
+ * half-extents along its local axes, and a rotation angle.
+ *
+ * Used when a node has a non-zero `transform.rot`: the AABB is no longer a
+ * tight fit, so callers that need a tight collision shape (selection
+ * outline, manipulator handles, etc.) should use the OBB instead.
+ *
+ * Conventions:
+ *   - `center` is the centre of the rectangle in world coordinates.
+ *   - `halfWidth` / `halfHeight` are the half-extents along the OBB's own
+ *     local axes (already pre-multiplied by the world scale).
+ *   - `angle` is the rotation of the OBB's local frame relative to world,
+ *     in radians, positive counter-clockwise.
+ *
+ * For an axis-aligned node (`angle === 0`) the OBB and AABB coincide, modulo
+ * the (centre + half-extents) vs (top-left + size) representation.
+ */
+interface OBB {
+    readonly center: Point;
+    readonly halfWidth: number;
+    readonly halfHeight: number;
+    readonly angle: number;
+}
+/**
+ * Compute the four corners of an OBB in world space.
+ *
+ * Order is: top-left → top-right → bottom-right → bottom-left in OBB-local
+ * space, after applying the rotation. Useful for SVG `<polygon>` rendering
+ * and for AABB derivation.
+ */
+declare function obbCorners(obb: OBB): readonly [Point, Point, Point, Point];
+/**
+ * Build the tightest axis-aligned bounding box that contains a given OBB.
+ *
+ * For a non-zero `angle` the resulting AABB is strictly larger (in area)
+ * than the OBB — it has to enclose all four rotated corners. This is the
+ * canonical "broad-phase" box used by the routing layer.
+ */
+declare function aabbFromOBB(obb: OBB): AABB;
+/**
+ * Test whether a world-space point lies inside an OBB.
+ *
+ * Inverse-rotates the point into OBB-local space and checks the
+ * half-extents. O(1).
+ */
+declare function obbContainsPoint(obb: OBB, p: Point): boolean;
+
+export { type AABB, type Anchor, type AnchorId, type AnchorPolicy, type BezierPathOptions, type EdgeEndpoint, type EdgeId, type EdgeInit, type GraphEdge, type GraphEngine, type GraphEngineOptions, type GraphNode, type GraphState, type NodeId, type NodeInit, type NodeTransform, type NodeUpdate, type OBB$1 as OBB, type Outline, type Point, type RouteOrthogonalOptions, type Side, aabbFromOBB, createGraph, getBezierPath, nearestSide, obbContainsPoint, obbCorners, pointsToPath, pointsToRoundedPath, routeOrthogonal };

package/dist/graph.js

@@ -0,0 +1,24 @@
+import {
+  aabbFromOBB,
+  createGraph,
+  getBezierPath,
+  nearestSide,
+  obbContainsPoint,
+  obbCorners,
+  pointsToPath,
+  pointsToRoundedPath,
+  routeOrthogonal
+} from "./chunk-KP75DEA4.js";
+import "./chunk-5CCD5Q4B.js";
+export {
+  aabbFromOBB,
+  createGraph,
+  getBezierPath,
+  nearestSide,
+  obbContainsPoint,
+  obbCorners,
+  pointsToPath,
+  pointsToRoundedPath,
+  routeOrthogonal
+};
+//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}