@world-engines/authoring-ui 0.1.0-alpha.0

package/dist/ladybug/graph-node-metrics.d.ts

@@ -0,0 +1,33 @@
+/** Graph node 内容尺寸的单一参数 authority。 */
+export declare const GRAPH_NODE_METRICS: Readonly<{
+    minDiameter: 48;
+    maxDiameter: number;
+    pixelsPerSqrtCharacter: 3;
+    maxContentLength: 4096;
+    maxTraversalDepth: 8;
+    maxVisitedContainers: 2048;
+    maxVisitedEntries: 4096;
+}>;
+export interface GraphNodeMetrics {
+    readonly contentLength: number;
+    readonly diameter: number;
+    readonly radius: number;
+    /** true 表示预算已截断遍历，contentLength 只是有界下限而非精确值。 */
+    readonly truncated: boolean;
+    /** true 表示视觉尺寸已到上限，继续增加正文不会再放大节点。 */
+    readonly saturated: boolean;
+}
+/** 外部预计算 metrics 也必须经过相同 48-72px authority，radius 始终由 diameter 派生。 */
+export declare function constrainGraphNodeMetrics(metrics: GraphNodeMetrics): GraphNodeMetrics;
+export interface GraphContentProp {
+    readonly value?: unknown;
+}
+/** 宿主只需投影作者可见的 name/props envelope，无需泄漏完整 EntityNode。 */
+export interface GraphContentEntity {
+    readonly name?: string | readonly string[];
+    readonly props: Readonly<Record<string, GraphContentProp | undefined>>;
+}
+export type GraphNameAttrPredicate = (key: string) => boolean;
+/** 只读取作者可见文本；宿主可注入自己的 canonical name-key 判定。 */
+export declare function measureGraphNodeContent(entity: GraphContentEntity, isNameAttrKey?: GraphNameAttrPredicate): number;
+export declare function graphNodeMetrics(entity: GraphContentEntity, isNameAttrKey?: GraphNameAttrPredicate): GraphNodeMetrics;

package/dist/ladybug/graph-node-metrics.js

@@ -0,0 +1,173 @@
+import { NODE_DIAMETER } from "./graph-placement.js";
+/** Graph node 内容尺寸的单一参数 authority。 */
+export const GRAPH_NODE_METRICS = Object.freeze({
+    minDiameter: NODE_DIAMETER,
+    maxDiameter: NODE_DIAMETER * 1.5,
+    pixelsPerSqrtCharacter: 3,
+    maxContentLength: 4_096,
+    maxTraversalDepth: 8,
+    maxVisitedContainers: 2_048,
+    maxVisitedEntries: 4_096
+});
+/** 外部预计算 metrics 也必须经过相同 48-72px authority，radius 始终由 diameter 派生。 */
+export function constrainGraphNodeMetrics(metrics) {
+    const rawContentLength = Number.isFinite(metrics.contentLength)
+        ? Math.max(0, Math.floor(metrics.contentLength))
+        : 0;
+    const contentLength = Math.min(GRAPH_NODE_METRICS.maxContentLength, rawContentLength);
+    const requestedDiameter = Number.isFinite(metrics.diameter)
+        ? metrics.diameter
+        : GRAPH_NODE_METRICS.minDiameter;
+    const diameter = Math.min(GRAPH_NODE_METRICS.maxDiameter, Math.max(GRAPH_NODE_METRICS.minDiameter, requestedDiameter));
+    return Object.freeze({
+        contentLength,
+        diameter,
+        radius: diameter / 2,
+        truncated: metrics.truncated || rawContentLength > GRAPH_NODE_METRICS.maxContentLength,
+        saturated: metrics.saturated || diameter === GRAPH_NODE_METRICS.maxDiameter
+    });
+}
+const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+const consumeEntry = (state) => {
+    if (state.visitedEntries >= GRAPH_NODE_METRICS.maxVisitedEntries) {
+        state.truncated = true;
+        return false;
+    }
+    state.visitedEntries += 1;
+    return true;
+};
+const countString = (text, state) => {
+    // 逐 code point 消费；到预算即停，避免 Array.from 对超长正文全量扫描与复制。
+    for (const _codePoint of text) {
+        if (state.length >= GRAPH_NODE_METRICS.maxContentLength) {
+            state.truncated = true;
+            return;
+        }
+        state.length += 1;
+    }
+};
+const countPropValue = (value, state, depth) => {
+    if (depth > GRAPH_NODE_METRICS.maxTraversalDepth) {
+        state.truncated = true;
+        return;
+    }
+    if (typeof value === "string") {
+        countString(value, state);
+        return;
+    }
+    if (value === null || typeof value !== "object")
+        return;
+    if (state.seen.has(value)) {
+        state.truncated = true;
+        return;
+    }
+    if (state.visitedContainers >= GRAPH_NODE_METRICS.maxVisitedContainers) {
+        state.truncated = true;
+        return;
+    }
+    state.seen.add(value);
+    state.visitedContainers += 1;
+    const record = value;
+    // 真实 prop value 的资源和引用对象只含结构 identity，不是作者正文。
+    if (hasOwn(record, "$ref") || hasOwn(record, "$asset"))
+        return;
+    if (hasOwn(record, "$rich")) {
+        const segments = record.$rich;
+        if (!Array.isArray(segments))
+            return;
+        for (let index = 0; index < segments.length; index += 1) {
+            if (!consumeEntry(state))
+                return;
+            const segment = segments[index];
+            if (segment !== null
+                && typeof segment === "object"
+                && hasOwn(segment, "text")
+                && typeof segment.text === "string") {
+                countString(segment.text, state);
+            }
+            if (state.truncated)
+                return;
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        // prop array 的每项都是 prop；只读 value，忽略 title/states/trigger 等元数据。
+        for (let index = 0; index < value.length; index += 1) {
+            if (!consumeEntry(state))
+                return;
+            const prop = value[index];
+            if (prop !== null && typeof prop === "object" && hasOwn(prop, "value")) {
+                countPropValue(prop.value, state, depth + 1);
+            }
+            if (state.truncated)
+                return;
+        }
+        return;
+    }
+    // prop object 的 key 是作者字段名，不能按名字过滤。
+    for (const key in record) {
+        if (!hasOwn(record, key))
+            continue;
+        if (!consumeEntry(state))
+            return;
+        const prop = record[key];
+        if (prop !== null && typeof prop === "object" && hasOwn(prop, "value")) {
+            countPropValue(prop.value, state, depth + 1);
+        }
+        if (state.truncated)
+            return;
+    }
+};
+const measureGraphNodeContentState = (entity, isNameAttrKey) => {
+    const state = {
+        length: 0,
+        visitedContainers: 0,
+        visitedEntries: 0,
+        truncated: false,
+        seen: new WeakSet()
+    };
+    const rawNames = typeof entity.name === "string"
+        ? [entity.name]
+        : Array.isArray(entity.name)
+            ? entity.name
+            : [];
+    for (let index = 0; index < rawNames.length; index += 1) {
+        if (!consumeEntry(state))
+            return state;
+        const name = rawNames[index];
+        if (typeof name === "string")
+            countString(name, state);
+        if (state.truncated)
+            return state;
+    }
+    for (const key in entity.props) {
+        if (!hasOwn(entity.props, key))
+            continue;
+        if (!consumeEntry(state))
+            return state;
+        // canonical name 已在顶层计量；仅在旧节点缺顶层名称时消费 props.name。
+        if (isNameAttrKey(key) && rawNames.length > 0)
+            continue;
+        countPropValue(entity.props[key]?.value, state, 0);
+        if (state.truncated)
+            return state;
+    }
+    return state;
+};
+const defaultIsNameAttrKey = (key) => key === "name";
+/** 只读取作者可见文本；宿主可注入自己的 canonical name-key 判定。 */
+export function measureGraphNodeContent(entity, isNameAttrKey = defaultIsNameAttrKey) {
+    return measureGraphNodeContentState(entity, isNameAttrKey).length;
+}
+export function graphNodeMetrics(entity, isNameAttrKey = defaultIsNameAttrKey) {
+    const measured = measureGraphNodeContentState(entity, isNameAttrKey);
+    const diameter = Math.min(GRAPH_NODE_METRICS.maxDiameter, Math.max(GRAPH_NODE_METRICS.minDiameter, GRAPH_NODE_METRICS.minDiameter
+        + GRAPH_NODE_METRICS.pixelsPerSqrtCharacter * Math.sqrt(measured.length)));
+    return constrainGraphNodeMetrics({
+        contentLength: measured.length,
+        diameter,
+        radius: diameter / 2,
+        truncated: measured.truncated,
+        saturated: diameter === GRAPH_NODE_METRICS.maxDiameter
+    });
+}

package/dist/ladybug/graph-physics.d.ts

@@ -0,0 +1,49 @@
+export declare const PHYSICS_NODE_RADIUS: number;
+export declare const PHYSICS_MIN_DIST: number;
+export declare const PHYSICS_GRID_SIZE: number;
+export declare const PHYSICS_IDEAL_LEN: number;
+export declare const PHYSICS_REPULSION_K = 60000;
+export declare const PHYSICS_SPRING_K = 0.06;
+export declare const PHYSICS_MAX_STEP: number;
+export declare const PHYSICS_STEP_SCALE = 60;
+export declare const PHYSICS_SLEEP_SPEED = 4;
+export declare const PHYSICS_FLUSH_INTERVAL_MS = 400;
+export declare const PHYSICS_MAX_DT_MS = 32;
+export declare const PHYSICS_EPSILON = 0.001;
+export declare const PHYSICS_MIN_DIST_SQ: number;
+export declare const PHYSICS_CELL_SIZE: number;
+export declare const PHYSICS_OVERLAP_PUSH_FRACTION = 0.5;
+export declare const PHYSICS_COLLISION_GAP: number;
+export declare const PHYSICS_SPRING_GAP: number;
+export interface PhysicsBody {
+    readonly id: string;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    readonly mass: number;
+    readonly radius?: number;
+}
+export interface PhysicsSeedNode {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly radius?: number;
+}
+export interface PhysicsEdge {
+    readonly from: string;
+    readonly to: string;
+}
+export declare const computeNodeMass: (nodeId: string, edges: ReadonlyArray<PhysicsEdge>) => number;
+export declare const initBodies: (seeds: ReadonlyArray<PhysicsSeedNode>, edges: ReadonlyArray<PhysicsEdge>) => PhysicsBody[];
+/** 与 editor 已验证的可变半径 spatial-grid force tick 同算法。 */
+export declare const stepPhysics: (bodies: PhysicsBody[], edges: ReadonlyArray<PhysicsEdge>, dtSeconds: number) => void;
+export interface GridPoint {
+    readonly x: number;
+    readonly y: number;
+    readonly radius?: number;
+}
+export declare const snapToGrid: (x: number, y: number) => GridPoint;
+export declare const tryFindGridSlot: (target: GridPoint, others: ReadonlyArray<GridPoint>) => GridPoint | null;
+export declare const findGridSlot: (target: GridPoint, others: ReadonlyArray<GridPoint>) => GridPoint;
+export declare const snapNodesToGrid: (seeds: ReadonlyArray<PhysicsSeedNode>) => PhysicsSeedNode[];

package/dist/ladybug/graph-physics.js

@@ -0,0 +1,266 @@
+import { NODE_DIAMETER, NODE_RADIUS, NODE_SPACING_RADIUS_MULTIPLIER, requiredNodeCenterDistance } from "./graph-placement.js";
+export const PHYSICS_NODE_RADIUS = NODE_DIAMETER / 2;
+export const PHYSICS_MIN_DIST = requiredNodeCenterDistance(PHYSICS_NODE_RADIUS, PHYSICS_NODE_RADIUS);
+export const PHYSICS_GRID_SIZE = PHYSICS_NODE_RADIUS;
+export const PHYSICS_IDEAL_LEN = PHYSICS_NODE_RADIUS * 5;
+export const PHYSICS_REPULSION_K = 60000;
+export const PHYSICS_SPRING_K = 0.06;
+export const PHYSICS_MAX_STEP = PHYSICS_NODE_RADIUS;
+export const PHYSICS_STEP_SCALE = 60;
+export const PHYSICS_SLEEP_SPEED = 4;
+export const PHYSICS_FLUSH_INTERVAL_MS = 400;
+export const PHYSICS_MAX_DT_MS = 32;
+export const PHYSICS_EPSILON = 0.001;
+export const PHYSICS_MIN_DIST_SQ = PHYSICS_MIN_DIST * PHYSICS_MIN_DIST;
+export const PHYSICS_CELL_SIZE = PHYSICS_MIN_DIST * 2;
+export const PHYSICS_OVERLAP_PUSH_FRACTION = 0.5;
+export const PHYSICS_COLLISION_GAP = NODE_RADIUS * NODE_SPACING_RADIUS_MULTIPLIER;
+export const PHYSICS_SPRING_GAP = PHYSICS_IDEAL_LEN - NODE_DIAMETER;
+const PHYSICS_GRID_SEARCH_MAX_RING = 40;
+const PHYSICS_MAX_NEIGHBORS_PER_BODY = 48;
+const PHYSICS_VELOCITY_RESPONSE = 10;
+const PHYSICS_OVERLAP_CORRECTION_SPEED = 8;
+const PHYSICS_OVERLAP_SLOP = 0.75;
+const PHYSICS_TAU = Math.PI * 2;
+const PHYSICS_GOLDEN_ANGLE = 2.399963;
+const finiteRadius = (radius) => typeof radius === "number" && Number.isFinite(radius) && radius > 0
+    ? radius
+    : PHYSICS_NODE_RADIUS;
+export const computeNodeMass = (nodeId, edges) => {
+    let degree = 0;
+    for (const edge of edges) {
+        if (edge.from === nodeId || edge.to === nodeId)
+            degree += 1;
+    }
+    return 1 + degree;
+};
+export const initBodies = (seeds, edges) => {
+    const degreeById = new Map();
+    for (const edge of edges) {
+        degreeById.set(edge.from, (degreeById.get(edge.from) ?? 0) + 1);
+        degreeById.set(edge.to, (degreeById.get(edge.to) ?? 0) + 1);
+    }
+    return seeds.map((seed) => ({
+        id: seed.id,
+        x: seed.x,
+        y: seed.y,
+        vx: 0,
+        vy: 0,
+        mass: 1 + (degreeById.get(seed.id) ?? 0),
+        radius: finiteRadius(seed.radius)
+    }));
+};
+const clampStep = (value) => {
+    if (value > PHYSICS_MAX_STEP)
+        return PHYSICS_MAX_STEP;
+    if (value < -PHYSICS_MAX_STEP)
+        return -PHYSICS_MAX_STEP;
+    return value;
+};
+const buildSpatialGrid = (bodies, cellSize) => {
+    const cells = new Map();
+    for (let index = 0; index < bodies.length; index += 1) {
+        const body = bodies[index];
+        const cellX = Math.floor(body.x / cellSize);
+        const cellY = Math.floor(body.y / cellSize);
+        let row = cells.get(cellX);
+        if (!row) {
+            row = new Map();
+            cells.set(cellX, row);
+        }
+        let cell = row.get(cellY);
+        if (!cell) {
+            cell = [];
+            row.set(cellY, cell);
+        }
+        cell.push(index);
+    }
+    return { cellSize, cells };
+};
+const forEachNeighbor = (grid, x, y, afterIndex, visit) => {
+    let accepted = 0;
+    const cellX = Math.floor(x / grid.cellSize);
+    const cellY = Math.floor(y / grid.cellSize);
+    for (let offsetX = -1; offsetX <= 1; offsetX += 1) {
+        const row = grid.cells.get(cellX + offsetX);
+        if (!row)
+            continue;
+        for (let offsetY = -1; offsetY <= 1; offsetY += 1) {
+            const cell = row.get(cellY + offsetY);
+            if (!cell)
+                continue;
+            let low = 0;
+            let high = cell.length;
+            while (low < high) {
+                const middle = low + Math.floor((high - low) / 2);
+                if (cell[middle] <= afterIndex)
+                    low = middle + 1;
+                else
+                    high = middle;
+            }
+            for (let cursor = low; cursor < cell.length; cursor += 1) {
+                visit(cell[cursor]);
+                accepted += 1;
+                if (accepted >= PHYSICS_MAX_NEIGHBORS_PER_BODY)
+                    return;
+            }
+        }
+    }
+};
+/** 与 editor 已验证的可变半径 spatial-grid force tick 同算法。 */
+export const stepPhysics = (bodies, edges, dtSeconds) => {
+    const size = bodies.length;
+    if (size === 0)
+        return;
+    const forceX = new Array(size).fill(0);
+    const forceY = new Array(size).fill(0);
+    const correctionVx = new Array(size).fill(0);
+    const correctionVy = new Array(size).fill(0);
+    const maxRadius = bodies.reduce((largest, body) => Math.max(largest, finiteRadius(body.radius)), PHYSICS_NODE_RADIUS);
+    const gridCellSize = Math.max(PHYSICS_CELL_SIZE, (maxRadius * 2 + PHYSICS_COLLISION_GAP) * 2);
+    const grid = buildSpatialGrid(bodies, gridCellSize);
+    for (let left = 0; left < size; left += 1) {
+        const a = bodies[left];
+        forEachNeighbor(grid, a.x, a.y, left, (right) => {
+            const b = bodies[right];
+            let dx = a.x - b.x;
+            let dy = a.y - b.y;
+            let distSq = dx * dx + dy * dy;
+            if (distSq < PHYSICS_EPSILON) {
+                const angle = (left * PHYSICS_GOLDEN_ANGLE + right) % PHYSICS_TAU;
+                dx = Math.cos(angle) * PHYSICS_EPSILON;
+                dy = Math.sin(angle) * PHYSICS_EPSILON;
+                distSq = PHYSICS_EPSILON * PHYSICS_EPSILON;
+            }
+            const distance = Math.sqrt(distSq);
+            const collisionDistance = requiredNodeCenterDistance(a.radius, b.radius);
+            if (distance < collisionDistance) {
+                const unitX = dx / distance;
+                const unitY = dy / distance;
+                const penetration = Math.max(0, collisionDistance - distance - PHYSICS_OVERLAP_SLOP);
+                const correction = penetration * PHYSICS_OVERLAP_CORRECTION_SPEED * 0.5;
+                correctionVx[left] += unitX * correction;
+                correctionVy[left] += unitY * correction;
+                correctionVx[right] -= unitX * correction;
+                correctionVy[right] -= unitY * correction;
+                return;
+            }
+            const interactionDistance = collisionDistance * 2;
+            if (distance >= interactionDistance)
+                return;
+            const force = (PHYSICS_REPULSION_K * a.mass * b.mass) / distSq;
+            const rangeRatio = (interactionDistance - distance) /
+                (interactionDistance - collisionDistance);
+            const taperedForce = force * rangeRatio * rangeRatio;
+            const unitX = dx / distance;
+            const unitY = dy / distance;
+            forceX[left] += unitX * taperedForce;
+            forceY[left] += unitY * taperedForce;
+            forceX[right] -= unitX * taperedForce;
+            forceY[right] -= unitY * taperedForce;
+        });
+    }
+    const indexById = new Map();
+    for (let index = 0; index < size; index += 1)
+        indexById.set(bodies[index].id, index);
+    for (const edge of edges) {
+        const left = indexById.get(edge.from);
+        const right = indexById.get(edge.to);
+        if (left === undefined || right === undefined || left === right)
+            continue;
+        const a = bodies[left];
+        const b = bodies[right];
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        const distSq = dx * dx + dy * dy;
+        if (distSq < PHYSICS_EPSILON)
+            continue;
+        const distance = Math.sqrt(distSq);
+        const idealLength = requiredNodeCenterDistance(a.radius, b.radius);
+        const force = PHYSICS_SPRING_K * (distance - idealLength);
+        const unitX = dx / distance;
+        const unitY = dy / distance;
+        forceX[left] += unitX * force;
+        forceY[left] += unitY * force;
+        forceX[right] -= unitX * force;
+        forceY[right] -= unitY * force;
+    }
+    const safeDt = Math.max(0, dtSeconds);
+    const velocityBlend = 1 - Math.exp(-PHYSICS_VELOCITY_RESPONSE * safeDt);
+    for (let index = 0; index < size; index += 1) {
+        const body = bodies[index];
+        const accelerationX = forceX[index] / body.mass;
+        const accelerationY = forceY[index] / body.mass;
+        const targetVx = accelerationX * PHYSICS_STEP_SCALE + correctionVx[index];
+        const targetVy = accelerationY * PHYSICS_STEP_SCALE + correctionVy[index];
+        body.vx += (targetVx - body.vx) * velocityBlend;
+        body.vy += (targetVy - body.vy) * velocityBlend;
+        const targetSpeed = Math.hypot(targetVx, targetVy);
+        const speed = Math.hypot(body.vx, body.vy);
+        if (targetSpeed < PHYSICS_SLEEP_SPEED && speed < PHYSICS_SLEEP_SPEED) {
+            body.vx = 0;
+            body.vy = 0;
+            continue;
+        }
+        body.x += clampStep(body.vx * safeDt);
+        body.y += clampStep(body.vy * safeDt);
+    }
+};
+export const snapToGrid = (x, y) => ({
+    x: Math.round(x / PHYSICS_GRID_SIZE) * PHYSICS_GRID_SIZE,
+    y: Math.round(y / PHYSICS_GRID_SIZE) * PHYSICS_GRID_SIZE
+});
+const conflictsWithOthers = (point, others) => {
+    for (const other of others) {
+        const dx = point.x - other.x;
+        const dy = point.y - other.y;
+        const minDistance = requiredNodeCenterDistance(point.radius, other.radius);
+        if (dx * dx + dy * dy < minDistance * minDistance)
+            return true;
+    }
+    return false;
+};
+export const tryFindGridSlot = (target, others) => {
+    const start = snapToGrid(target.x, target.y);
+    const footprint = (point) => ({ ...point, radius: finiteRadius(target.radius) });
+    if (!conflictsWithOthers(footprint(start), others))
+        return start;
+    for (let ring = 1; ring <= PHYSICS_GRID_SEARCH_MAX_RING; ring += 1) {
+        const offset = ring * PHYSICS_GRID_SIZE;
+        for (let index = -ring; index <= ring; index += 1) {
+            const shift = index * PHYSICS_GRID_SIZE;
+            const top = { x: start.x + shift, y: start.y - offset };
+            if (!conflictsWithOthers(footprint(top), others))
+                return top;
+            const bottom = { x: start.x + shift, y: start.y + offset };
+            if (!conflictsWithOthers(footprint(bottom), others))
+                return bottom;
+        }
+        for (let index = -ring + 1; index <= ring - 1; index += 1) {
+            const shift = index * PHYSICS_GRID_SIZE;
+            const left = { x: start.x - offset, y: start.y + shift };
+            if (!conflictsWithOthers(footprint(left), others))
+                return left;
+            const right = { x: start.x + offset, y: start.y + shift };
+            if (!conflictsWithOthers(footprint(right), others))
+                return right;
+        }
+    }
+    return null;
+};
+export const findGridSlot = (target, others) => tryFindGridSlot(target, others) ?? snapToGrid(target.x, target.y);
+export const snapNodesToGrid = (seeds) => {
+    const placed = [];
+    const out = [];
+    for (const seed of seeds) {
+        const slot = findGridSlot({ x: seed.x, y: seed.y, ...(seed.radius === undefined ? {} : { radius: seed.radius }) }, placed);
+        placed.push({ ...slot, radius: finiteRadius(seed.radius) });
+        out.push({
+            id: seed.id,
+            x: slot.x,
+            y: slot.y,
+            ...(seed.radius === undefined ? {} : { radius: finiteRadius(seed.radius) })
+        });
+    }
+    return out;
+};

package/dist/ladybug/graph-placement.d.ts

@@ -0,0 +1,33 @@
+export declare const NODE_DIAMETER = 48;
+export declare const NODE_RADIUS: number;
+export declare const NODE_SPACING_RADIUS_MULTIPLIER = 3;
+export declare const PLACEMENT_GAP: number;
+export declare const SAFE_DIST: number;
+export declare const SAFE_ZONE_MULT: number;
+export declare const MIN_NODE_DIST: number;
+export interface PlacementPoint {
+    readonly x: number;
+    readonly y: number;
+    readonly radius?: number;
+}
+export interface ExistingNode {
+    readonly position: PlacementPoint;
+    readonly radius?: number;
+}
+/** 外框净空为较大节点半径的三倍。 */
+export declare const requiredNodeCenterDistance: (leftRadius: number | undefined, rightRadius: number | undefined) => number;
+export declare const placeEntityWithoutOverlap: (existing: Readonly<Record<string, ExistingNode>>, candidate: PlacementPoint, excludeId?: string, distThreshold?: number) => PlacementPoint;
+export interface PlaceableNode {
+    readonly id: string;
+    readonly position: PlacementPoint;
+    readonly radius?: number;
+}
+export declare const resolveOverlaps: <T extends PlaceableNode>(nodes: ReadonlyArray<T>, distThreshold?: number) => T[];
+export interface ForceNode {
+    readonly id: string;
+    readonly position: PlacementPoint;
+    readonly radius?: number;
+}
+export declare const clampToSafeDistance: (target: PlacementPoint, others: ReadonlyArray<PlacementPoint>, distThreshold?: number) => PlacementPoint;
+/** 保留 editor 既有的静态 force API；共享 Canvas 的按钮布局使用 graph-physics。 */
+export declare const forcePlacement: <T extends ForceNode>(nodes: ReadonlyArray<T>) => T[];