summer-engine 3.1.0 → 3.2.0

package/dist/core/capabilities/placement.d.ts

@@ -0,0 +1,485 @@
+/**
+ * Kit-placement tools, shared by both faces: the MCP tools
+ * (src/mcp/tools/placement-tools.ts) register these zod shapes and call these
+ * runners; `summer tool <slug>` (tool-dispatch.ts) parses with the same
+ * schemas and calls the same runners.
+ *
+ *   summer_inspect_asset      measure an asset file without adding it to a scene
+ *   summer_place_adjacent     put one node's bounds face against another's
+ *   summer_attach_to_surface  turn a piece's back onto a surface and seat it
+ *   summer_repeat_along       instance copies of a scene along a line
+ *   summer_connect_ports      meet one piece's port with another's
+ *   summer_raycast            cast an arbitrary ray (physics, then visual AABB)
+ *   summer_measure            gap/overlap per axis, or face coplanarity
+ *
+ * No engine op is new. Reads run the placement probe (placement-script.ts)
+ * through RunSceneScript with undo "none" and no checkpoint; mutations are the
+ * ordinary SetProp / SnapToSurface / InstantiateScene ops with the usual scene
+ * target, undo and final SaveScene. attach_to_surface checks its seat before
+ * the SaveScene and, when it refuses, sets the piece's original transform back
+ * instead of saving. Every result is compact (< 5 KB) and names its evidence:
+ * visual_aabb (visible GeometryInstance3D bounds, the definition
+ * AlignDistribute3D uses), physics (collider queries), or mesh_triangles.
+ */
+import { z } from "zod";
+import { type CapabilityAdvertisingClient } from "../capability-skew.js";
+import { type JsonRecord } from "../util/json.js";
+import { type Basis3, type SignedAxis, type Vec3, type WorldAxis, type Xform } from "./placement-math.js";
+export interface PlacementClient extends CapabilityAdvertisingClient {
+    executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+}
+export type PlacementResult = JsonRecord & {
+    ok: boolean;
+};
+/** What a placement tool tells the model when the engine lacks RunSceneScript. */
+export declare const PLACEMENT_PROBE_FALLBACK = "read bounds with summer_starcast (or summer_inspect_node + summer_inspect_resource) and place with summer_set_prop, then verify with summer_screenshot";
+export declare function isSafeNodePath(value: string): boolean;
+export declare function isSafeResPath(value: string): boolean;
+/**
+ * Run the placement probe and return its result dictionary, or a structured
+ * failure. Never mutates: undo "none", no checkpoint.
+ */
+export declare function runPlacementProbe(client: PlacementClient, tool: string, args: JsonRecord, seconds?: number): Promise<PlacementResult>;
+/** Trim the named lists (in order) until the result fits; declare every trim. */
+export declare function fitToBudget(result: JsonRecord, listKeys: string[], target?: number): JsonRecord;
+export declare const inspectAssetArgsSchema: z.ZodObject<{
+    path: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    maxTriangles: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    detail: z.ZodDefault<z.ZodOptional<z.ZodEnum<["summary", "full"]>>>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    detail: "summary" | "full";
+    maxTriangles: number;
+}, {
+    path: string;
+    detail?: "summary" | "full" | undefined;
+    maxTriangles?: number | undefined;
+}>;
+export type InspectAssetArgs = z.output<typeof inspectAssetArgsSchema>;
+/** Planes the probe reports, largest first. */
+interface PlaneRecord {
+    normal: Vec3;
+    offset: number;
+    area: number;
+    tris?: number;
+    cull_back?: number;
+}
+/** One open boundary loop as the probe reports it: full precision, in the
+ *  piece's own frame (the frame of the asset root, or of the scene node with
+ *  its own transform excluded), in discovery order. */
+export interface RawLoop {
+    center: Vec3;
+    direction: Vec3;
+    radius: number;
+    vertices?: number;
+    mesh?: number;
+    max_dev?: number;
+    direction_ambiguous?: boolean;
+}
+/** A loop with its stable place: `index` in the stable order and `id`. */
+export interface OrderedLoop extends RawLoop {
+    index: number;
+    id: string;
+    /** The signed piece axis its outward direction is nearest, e.g. "+Y";
+     *  "~Y" when the probe could not decide which way it faces. */
+    facing: string;
+}
+/** What the port-like rules read from a loop. */
+interface LoopRecord {
+    direction: Vec3;
+    radius: number;
+    center?: Vec3;
+    direction_ambiguous?: boolean;
+}
+/** A stable open-loop id: "+Y", "+Y#2" (the second loop facing +Y), "~Z". */
+export declare const LOOP_ID_PATTERN: RegExp;
+/**
+ * The stable order and ids of a piece's open loops. Sort key: the signed piece
+ * axis the outward direction is nearest (+X, -X, +Y, -Y, +Z, -Z, then the
+ * undecided ~X, ~Y, ~Z); then the outermost along that axis first; then centre
+ * x, y, z; radius (largest first) and vertex count only break exact ties. All
+ * in the piece's own frame, so the ids are the same in summer_inspect_asset
+ * and summer_connect_ports and do not change with the piece's pose. The first
+ * loop facing +Y is "+Y", the next "+Y#2". Exported for tests.
+ */
+export declare function orderLoops(loops: RawLoop[]): OrderedLoop[];
+export type PortSelector = {
+    kind: "marker";
+    name: string;
+} | {
+    kind: "loop_id";
+    id: string;
+} | {
+    kind: "loop_index";
+    index: number;
+};
+/** "+y", "+Y" and "+Y#1" all name the loop "+Y"; numbers are loop indices;
+ *  any other string is a Marker3D (or Node3D) name. */
+export declare function parsePortSelector(port: string | number): PortSelector;
+/**
+ * The two largest pairs of opposite planes, for reading facing at a glance:
+ * per plane direction the largest plane and the largest one facing the other
+ * way (null for a single sheet), ranked by their combined area; pairs under 1%
+ * of the largest pair's area are left out. Exported for tests.
+ */
+export declare function planePairs(planes: PlaneRecord[], limit?: number): JsonRecord[];
+/**
+ * Loops that look like pipe or duct ends: radius over 2 cm, a decided
+ * direction, and at least one partner loop of similar radius facing more than
+ * 60 degrees away (the other end of a straight run or a bend). The outline of
+ * a flat sheet and its holes all face one way and never qualify. Exported for
+ * tests.
+ */
+export declare function portLikeLoops<T extends LoopRecord>(loops: T[], aabb?: {
+    min: Vec3;
+    max: Vec3;
+}): T[];
+export declare function inspectAsset(client: PlacementClient, args: InspectAssetArgs): Promise<PlacementResult>;
+export declare const measureArgsSchema: z.ZodObject<{
+    scenePath: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+    mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["pair", "plane"]>>>;
+    a: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    b: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    axis: z.ZodOptional<z.ZodEnum<["x", "y", "z"]>>;
+    nodes: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">>;
+    face: z.ZodOptional<z.ZodEnum<["+x", "-x", "+y", "-y", "+z", "-z"]>>;
+    space: z.ZodDefault<z.ZodOptional<z.ZodEnum<["world", "local"]>>>;
+    tolerance: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    mode: "pair" | "plane";
+    scenePath: string;
+    space: "local" | "world";
+    tolerance: number;
+    a?: string | undefined;
+    axis?: "y" | "x" | "z" | undefined;
+    nodes?: string[] | undefined;
+    b?: string | undefined;
+    face?: "-y" | "+x" | "-x" | "+y" | "+z" | "-z" | undefined;
+}, {
+    scenePath: string;
+    mode?: "pair" | "plane" | undefined;
+    a?: string | undefined;
+    space?: "local" | "world" | undefined;
+    axis?: "y" | "x" | "z" | undefined;
+    nodes?: string[] | undefined;
+    b?: string | undefined;
+    tolerance?: number | undefined;
+    face?: "-y" | "+x" | "-x" | "+y" | "+z" | "-z" | undefined;
+}>;
+export type MeasureArgs = z.output<typeof measureArgsSchema>;
+export declare function measure(client: PlacementClient, args: MeasureArgs): Promise<PlacementResult>;
+export declare const raycastArgsSchema: z.ZodObject<{
+    scenePath: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+    origin: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    direction: z.ZodEffects<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, [number, number, number], [number, number, number]>;
+    maxDistance: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    collisionMask: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    collideWithAreas: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    evidence: z.ZodDefault<z.ZodOptional<z.ZodEnum<["auto", "physics", "visual_aabb"]>>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    scenePath: string;
+    origin: [number, number, number];
+    direction: [number, number, number];
+    evidence: "auto" | "physics" | "visual_aabb";
+    maxDistance: number;
+    collisionMask: number;
+    collideWithAreas: boolean;
+    exclude?: string[] | undefined;
+}, {
+    scenePath: string;
+    origin: [number, number, number];
+    direction: [number, number, number];
+    evidence?: "auto" | "physics" | "visual_aabb" | undefined;
+    maxDistance?: number | undefined;
+    collisionMask?: number | undefined;
+    collideWithAreas?: boolean | undefined;
+    exclude?: string[] | undefined;
+}>;
+export type RaycastArgs = z.output<typeof raycastArgsSchema>;
+export declare function raycast(client: PlacementClient, args: RaycastArgs): Promise<PlacementResult>;
+declare const alignMode: z.ZodEnum<["min", "center", "max", "none"]>;
+type AlignMode = z.output<typeof alignMode>;
+export declare const placeAdjacentArgsSchema: z.ZodObject<{
+    scenePath: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+    subject: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    reference: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    axis: z.ZodEnum<["x", "y", "z"]>;
+    side: z.ZodEnum<["min", "max"]>;
+    gap: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    alignOtherAxes: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["min", "center", "max", "none"]>, z.ZodObject<{
+        x: z.ZodOptional<z.ZodEnum<["min", "center", "max", "none"]>>;
+        y: z.ZodOptional<z.ZodEnum<["min", "center", "max", "none"]>>;
+        z: z.ZodOptional<z.ZodEnum<["min", "center", "max", "none"]>>;
+    }, "strip", z.ZodTypeAny, {
+        y?: "none" | "min" | "max" | "center" | undefined;
+        x?: "none" | "min" | "max" | "center" | undefined;
+        z?: "none" | "min" | "max" | "center" | undefined;
+    }, {
+        y?: "none" | "min" | "max" | "center" | undefined;
+        x?: "none" | "min" | "max" | "center" | undefined;
+        z?: "none" | "min" | "max" | "center" | undefined;
+    }>]>>>;
+    space: z.ZodDefault<z.ZodOptional<z.ZodEnum<["world", "local"]>>>;
+}, "strip", z.ZodTypeAny, {
+    scenePath: string;
+    space: "local" | "world";
+    gap: number;
+    axis: "y" | "x" | "z";
+    subject: string;
+    reference: string;
+    side: "min" | "max";
+    alignOtherAxes: "none" | "min" | "max" | "center" | {
+        y?: "none" | "min" | "max" | "center" | undefined;
+        x?: "none" | "min" | "max" | "center" | undefined;
+        z?: "none" | "min" | "max" | "center" | undefined;
+    };
+}, {
+    scenePath: string;
+    axis: "y" | "x" | "z";
+    subject: string;
+    reference: string;
+    side: "min" | "max";
+    space?: "local" | "world" | undefined;
+    gap?: number | undefined;
+    alignOtherAxes?: "none" | "min" | "max" | "center" | {
+        y?: "none" | "min" | "max" | "center" | undefined;
+        x?: "none" | "min" | "max" | "center" | undefined;
+        z?: "none" | "min" | "max" | "center" | undefined;
+    } | undefined;
+}>;
+export type PlaceAdjacentArgs = z.output<typeof placeAdjacentArgsSchema>;
+/** Per-axis translation that puts subject against reference. Exported for tests. */
+export declare function adjacentDeltas(subject: Array<[number, number]>, reference: Array<[number, number]>, axis: WorldAxis, side: "min" | "max", gap: number, align: (axis: WorldAxis) => AlignMode): Vec3;
+export declare function placeAdjacent(client: PlacementClient, args: PlaceAdjacentArgs): Promise<PlacementResult>;
+export declare const attachToSurfaceArgsSchema: z.ZodObject<{
+    scenePath: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+    subject: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    surface: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    ray: z.ZodOptional<z.ZodObject<{
+        origin: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        direction: z.ZodEffects<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, [number, number, number], [number, number, number]>;
+    }, "strip", z.ZodTypeAny, {
+        origin: [number, number, number];
+        direction: [number, number, number];
+    }, {
+        origin: [number, number, number];
+        direction: [number, number, number];
+    }>>;
+    placeAt: z.ZodDefault<z.ZodOptional<z.ZodEnum<["current", "hit"]>>>;
+    maxMove: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    backAxis: z.ZodDefault<z.ZodOptional<z.ZodEnum<["+x", "-x", "+y", "-y", "+z", "-z"]>>>;
+    upAxis: z.ZodDefault<z.ZodOptional<z.ZodEnum<["+x", "-x", "+y", "-y", "+z", "-z"]>>>;
+    worldUp: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, [number, number, number], [number, number, number]>>>;
+    standoff: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxDistance: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    collisionMask: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    scenePath: string;
+    subject: string;
+    maxDistance: number;
+    collisionMask: number;
+    placeAt: "current" | "hit";
+    maxMove: number;
+    backAxis: "-y" | "+x" | "-x" | "+y" | "+z" | "-z";
+    upAxis: "-y" | "+x" | "-x" | "+y" | "+z" | "-z";
+    worldUp: [number, number, number];
+    standoff: number;
+    surface?: string | undefined;
+    ray?: {
+        origin: [number, number, number];
+        direction: [number, number, number];
+    } | undefined;
+}, {
+    scenePath: string;
+    subject: string;
+    surface?: string | undefined;
+    ray?: {
+        origin: [number, number, number];
+        direction: [number, number, number];
+    } | undefined;
+    maxDistance?: number | undefined;
+    collisionMask?: number | undefined;
+    placeAt?: "current" | "hit" | undefined;
+    maxMove?: number | undefined;
+    backAxis?: "-y" | "+x" | "-x" | "+y" | "+z" | "-z" | undefined;
+    upAxis?: "-y" | "+x" | "-x" | "+y" | "+z" | "-z" | undefined;
+    worldUp?: [number, number, number] | undefined;
+    standoff?: number | undefined;
+}>;
+export type AttachToSurfaceArgs = z.output<typeof attachToSurfaceArgsSchema>;
+/** The piece is turned and put this far in front of its planned seat before
+ *  SnapToSurface sweeps it in. */
+export declare const ATTACH_PRESEAT_CLEARANCE = 0.05;
+/** How far past the planned seat the sweep may go (a collider set back from
+ *  the visible back face). */
+export declare const ATTACH_SEAT_REACH = 0.25;
+/** A seat this far in front of the planned plane stopped on something else. */
+export declare const ATTACH_PLAN_TOLERANCE = 0.03;
+/** Extents of a node's visible bounds along its own local axes, relative to
+ *  its origin: lo/hi per local x, y, z. Exported for tests. */
+export declare function localExtents(intervals: Array<[number, number]>, dirs: Vec3[], origin: Vec3): {
+    lo: Vec3;
+    hi: Vec3;
+};
+/**
+ * Where the subject's origin must go so its back face (the extreme of its
+ * visible bounds along backAxis) sits standoff in front of the surface plane
+ * through hitPoint. `current` keeps the origin's place along the surface (and
+ * so its height on a wall); `hit` puts the centre of the back face on the hit
+ * point. `rotation` maps local unit axes to their new world directions.
+ * Exported for tests.
+ */
+export declare function seatOrigin(plan: {
+    origin: Vec3;
+    extents: {
+        lo: Vec3;
+        hi: Vec3;
+    };
+    backAxis: SignedAxis;
+    rotation: Basis3;
+    hitPoint: Vec3;
+    normal: Vec3;
+    standoff: number;
+    placeAt: "current" | "hit";
+}): {
+    origin: Vec3;
+    backOffset: number;
+    backCentre: Vec3;
+};
+/** The mounting rotation: local back -> -normal, local up -> world up projected
+ *  onto the surface plane. Exported for tests. */
+export declare function mountingRotation(backAxis: SignedAxis, upAxis: SignedAxis, normal: Vec3, worldUp: Vec3, currentUp?: Vec3): {
+    rotation: Basis3;
+    up: Vec3;
+    usedCurrentUp: boolean;
+} | null;
+/** One concrete next step for a failed seat, naming what blocked it. */
+export declare function seatNextStep(reason: string, blockers: JsonRecord | undefined, sweep: number): string;
+export declare function attachToSurface(client: PlacementClient, args: AttachToSurfaceArgs): Promise<PlacementResult>;
+export declare const repeatAlongArgsSchema: z.ZodObject<{
+    scenePath: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+    template: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    parent: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    start: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    end: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    direction: z.ZodOptional<z.ZodEffects<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, [number, number, number], [number, number, number]>>;
+    count: z.ZodOptional<z.ZodNumber>;
+    spacing: z.ZodOptional<z.ZodNumber>;
+    align: z.ZodDefault<z.ZodOptional<z.ZodEnum<["start", "center", "end"]>>>;
+    rotationDegrees: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    scale: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    namePrefix: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strip", z.ZodTypeAny, {
+    scenePath: string;
+    template: string;
+    parent: string;
+    start: [number, number, number];
+    align: "end" | "start" | "center";
+    end?: [number, number, number] | undefined;
+    count?: number | undefined;
+    scale?: [number, number, number] | undefined;
+    direction?: [number, number, number] | undefined;
+    spacing?: number | undefined;
+    rotationDegrees?: [number, number, number] | undefined;
+    namePrefix?: string | undefined;
+}, {
+    scenePath: string;
+    template: string;
+    parent: string;
+    start: [number, number, number];
+    end?: [number, number, number] | undefined;
+    count?: number | undefined;
+    scale?: [number, number, number] | undefined;
+    direction?: [number, number, number] | undefined;
+    spacing?: number | undefined;
+    align?: "end" | "start" | "center" | undefined;
+    rotationDegrees?: [number, number, number] | undefined;
+    namePrefix?: string | undefined;
+}>;
+export type RepeatAlongArgs = z.output<typeof repeatAlongArgsSchema>;
+export declare const REPEAT_MAX_COPIES = 64;
+/** Copy positions for a repeat_along call. Exported for tests. */
+export declare function repeatPositions(args: Pick<RepeatAlongArgs, "start" | "end" | "direction" | "count" | "spacing" | "align">): {
+    positions: Vec3[];
+    spacing: number;
+    direction: Vec3;
+};
+export declare function repeatAlong(client: PlacementClient, args: RepeatAlongArgs): Promise<PlacementResult>;
+/** A join may tilt the subject's up axis this many degrees unless allowed. */
+export declare const DEFAULT_MAX_TILT_DEGREES = 5;
+export declare const connectPortsArgsSchema: z.ZodObject<{
+    scenePath: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+    subject: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    subjectPort: z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>;
+    target: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    targetPort: z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>;
+    gap: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    rollDegrees: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxTiltDegrees: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    allowTilt: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    maxTriangles: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    scenePath: string;
+    target: string;
+    gap: number;
+    subject: string;
+    maxTriangles: number;
+    subjectPort: string | number;
+    targetPort: string | number;
+    rollDegrees: number;
+    maxTiltDegrees: number;
+    allowTilt: boolean;
+}, {
+    scenePath: string;
+    target: string;
+    subject: string;
+    subjectPort: string | number;
+    targetPort: string | number;
+    gap?: number | undefined;
+    maxTriangles?: number | undefined;
+    rollDegrees?: number | undefined;
+    maxTiltDegrees?: number | undefined;
+    allowTilt?: boolean | undefined;
+}>;
+export type ConnectPortsArgs = z.output<typeof connectPortsArgsSchema>;
+interface PortRead {
+    kind: string;
+    position: Vec3;
+    direction: Vec3;
+    radius?: number;
+    name?: string;
+    id?: string;
+    index?: number;
+    direction_ambiguous?: boolean;
+    analysis_truncated?: boolean;
+    /** The subject's other ports (ports read with other_ports). */
+    others?: PortRead[];
+    others_total?: number;
+}
+/**
+ * The probe's answer for one port -> the port in scene space. A marker comes
+ * resolved; an open-loop port comes as every loop of the node in its own
+ * frame, which is ordered here (orderLoops) and picked by id or index, so the
+ * same id names the same loop in every pose. With withOthers, the node's other
+ * loops come along in scene space.
+ */
+export declare function resolveProbePort(raw: unknown, selector: PortSelector, label: "subject" | "target", node: string, withOthers: boolean): {
+    port: PortRead;
+} | {
+    failure: PlacementResult;
+};
+/** New scene-space transform that joins the subject port to the target port.
+ *  `joint` is where the subject port lands; a subject point p moves to
+ *  rotation * (p - subject port) + joint. */
+export declare function connectTransform(subject: Xform, sp: PortRead, tp: PortRead, gap: number, rollDegrees: number): {
+    xform: Xform;
+    rotation: Basis3;
+    joint: Vec3;
+    rollAxis: Vec3;
+};
+/** How far a scene-space rotation turns the subject's up axis (its local +Y),
+ *  in degrees. A turn about the up axis is 0. Exported for tests. */
+export declare function tiltDegrees(subject: Xform, rotation: Basis3): number;
+export declare function connectPorts(client: PlacementClient, args: ConnectPortsArgs): Promise<PlacementResult>;
+export {};