@constructorfleet/sketchforge-engine 1.25.0 → 1.27.0

package/dist/sketchFaceDraftKernel.d.ts

@@ -0,0 +1,248 @@
+/**
+ * The retained face and prism drafts of a sketch extrusion, on a kernel the
+ * caller supplies.
+ *
+ * Browser-safe: nothing here loads a kernel, so the editor's CAD worker runs
+ * these on its own OCCT instance and the server runs the same functions inside
+ * `withCadKernel`. A draft the editor makes must be the same feature, with the
+ * same record and placement, that `PATCH faceDraft` or `POST /draft-prism`
+ * makes, and the way to keep two callers from drifting is for both to call one
+ * implementation. Shared here, and called by both: which face a draft names
+ * (`resolveRetainedFaceDraft`, legacy segment inference included), the draft
+ * itself (`draftSketchFace`), result face IDs, the records, and where the
+ * drafted part is placed (`retainedDraftSourcePlacement`).
+ *
+ * Errors carry the messages the REST API has always returned; each caller
+ * wraps them in its own error type.
+ */
+import type { OcctKernel, ShapeHandle, Vec3 } from "occt-wasm";
+import type { CadBrepFrame, SketchFaceDraft, SketchProfile, WorkplaneShape } from "./domain/sketchforge.js";
+export declare const SKETCH_FACE_DRAFT_PULL_AXES: {
+    readonly x: {
+        readonly x: 1;
+        readonly y: 0;
+        readonly z: 0;
+    };
+    readonly y: {
+        readonly x: 0;
+        readonly y: 1;
+        readonly z: 0;
+    };
+    readonly z: {
+        readonly x: 0;
+        readonly y: 0;
+        readonly z: 1;
+    };
+    readonly "-x": {
+        readonly x: -1;
+        readonly y: 0;
+        readonly z: 0;
+    };
+    readonly "-y": {
+        readonly x: 0;
+        readonly y: -1;
+        readonly z: 0;
+    };
+    readonly "-z": {
+        readonly x: 0;
+        readonly y: 0;
+        readonly z: -1;
+    };
+};
+export type SketchFaceDraftPullDirection = keyof typeof SKETCH_FACE_DRAFT_PULL_AXES;
+export type SketchFaceDraftRequest = {
+    sourceFaceId: string;
+    angle: number;
+    pullDirection: SketchFaceDraftPullDirection;
+};
+export type SketchFaceSegmentMatch = {
+    status: "unsupported";
+} | {
+    status: "cap";
+} | {
+    status: "matched";
+    segmentId: string;
+    faceId: string;
+    normal: Vec3;
+} | {
+    status: "missing";
+} | {
+    status: "ambiguous";
+};
+/** What a face-draft lookup needs of the undrafted source extrusion. */
+export type SketchFaceDraftSource = Pick<WorkplaneShape, "id" | "sketchOperation" | "sketchProfile" | "cadBrep" | "faceIds" | "cadBrepFrame" | "height">;
+type SegmentEndpoints = {
+    id: string;
+    start: {
+        x: number;
+        z: number;
+    };
+    end: {
+        x: number;
+        z: number;
+    };
+};
+type BoundaryEdge = {
+    curveType: string;
+    vertices: Vec3[];
+};
+export declare function uniqueSketchSegmentForSideBoundary(boundary: BoundaryEdge[], segments: SegmentEndpoints[], height: number): {
+    status: "matched";
+    segmentId: string;
+} | {
+    status: "missing" | "ambiguous";
+};
+/**
+ * A face's outward normal at the middle of its parameter range, or null.
+ *
+ * The same sample the REST face listing reports, so a normal recorded here
+ * compares equal to one a script read from `GET /faces`.
+ */
+export declare function sketchFaceNormal(cad: OcctKernel, face: ShapeHandle): Vec3 | null;
+/** Map a selected source face to its exact sketch line segment, when supported. */
+export declare function sketchSegmentForDraftFaceOnKernel(cad: OcctKernel, shape: SketchFaceDraftSource, faceId: string): SketchFaceSegmentMatch;
+/** Find the unique source face corresponding to a retained sketch segment. */
+export declare function draftFaceForSketchSegmentOnKernel(cad: OcctKernel, shape: SketchFaceDraftSource, segmentId: string): SketchFaceSegmentMatch;
+/**
+ * Draft one face of a solid about a signed local pull axis, or null when the
+ * kernel cannot.
+ *
+ * OCCT's draft only reliably takes +Z as the pull direction, so when the
+ * direct call refuses, the solid is turned until the requested axis is +Z, the
+ * face found again on the turned solid by its normal and centre, drafted, and
+ * turned back.
+ */
+export declare function draftSketchFace(cad: OcctKernel, solid: ShapeHandle, face: ShapeHandle, request: {
+    angle: number;
+    pullDirection: SketchFaceDraftPullDirection;
+}): ShapeHandle | null;
+/**
+ * Face IDs for a result, inherited from the source where a face is plainly
+ * the same one.
+ *
+ * Keep an ID only when an exact face BREP or a unique planar support surface
+ * occurs on each side. OCCT face ordering and hash codes are kernel details,
+ * so an unmatched or ambiguous face receives a new application ID.
+ */
+export declare function faceIdsForCadResult(cad: OcctKernel, source: Pick<WorkplaneShape, "id" | "faceIds">, resultFaces: ShapeHandle[], sourceSolid: ShapeHandle): string[];
+/**
+ * Why a retained face draft could not be made, for a caller that words it
+ * itself: the face it names cannot be found (`unresolved`), the angle is out of
+ * range, the kernel refuses that face, axis and angle (`incompatible`), or the
+ * result is not a valid solid. The message is the REST API's.
+ */
+export declare class SketchFaceDraftError extends Error {
+    readonly reason: "unresolved" | "angle" | "incompatible" | "invalid-result";
+    constructor(message: string, reason: SketchFaceDraftError["reason"]);
+}
+/** The single solid a stored B-rep describes, healed the way the server reads one. */
+export declare function solidFromBrepOnKernel(cad: OcctKernel, brep: string): ShapeHandle;
+/** What a face-draft resolution needs of the shape the draft was asked of. */
+export type RetainedFaceDraftPrior = Pick<WorkplaneShape, "id" | "faceIds" | "cadBrep" | "cadBrepFrame" | "height" | "sketchOperation" | "sketchProfile" | "faceDraft" | "faceDraftSourceFaceIds" | "faceDraftSourceSegmentId" | "faceDraftSourceFrame">;
+/**
+ * The solid a resolution lists faces on. The server passes its oriented solid,
+ * which carries a shape's mirror; the default is the stored B-rep as it is.
+ */
+export type RetainedFaceDraftSolidOf = (cad: OcctKernel, shape: RetainedFaceDraftPrior | SketchFaceDraftSource) => ShapeHandle;
+/**
+ * Infer the sketch segment of a draft saved before segments were recorded,
+ * from its saved source face ID or, failing that, its normal on the extrusion
+ * rebuilt from its sketch.
+ */
+export declare function legacyDraftSegmentOnKernel(cad: OcctKernel, shape: RetainedFaceDraftPrior): SketchFaceSegmentMatch;
+/** The face a retained draft acts on, with the evidence its record keeps. */
+export type ResolvedSketchFaceDraftSource = {
+    faceId: string;
+    normal: Vec3;
+    segmentMatch: SketchFaceSegmentMatch;
+};
+export type RetainedFaceDraftResolution = {
+    /** The shape the draft was asked of: undrafted for a new draft, drafted for an edit or replay. */
+    existing: RetainedFaceDraftPrior;
+    /** The undrafted extrusion the draft is made on, with a stable ID per face. */
+    source: SketchFaceDraftSource;
+    request: {
+        sourceFaceId: string;
+        angle: number;
+        pullDirection: SketchFaceDraftPullDirection;
+    };
+    /** Whether the sketch profile was replaced, so faces must be found by segment or normal. */
+    profileChanged: boolean;
+};
+/**
+ * Resolve which face of the undrafted source a retained face draft acts on.
+ *
+ * The one implementation behind both `PATCH faceDraft` on a sketch extrusion
+ * and the editor's draft, edit and replay. In order: a draft already on the
+ * same face keeps its recorded normal; a new face is looked up by ID, on the
+ * rebuilt source when the sketch is unchanged and on the prior shape
+ * otherwise; after a profile edit the recorded sketch segment, or the one a
+ * legacy draft's saved face implies, must still bound exactly one side face;
+ * failing an ID, exactly one flat face must carry the normal. Whatever face is
+ * chosen must not match two segments, nor be a side no segment bounds. Each
+ * refusal carries the message the API returns for it.
+ */
+export declare function resolveRetainedFaceDraft(cad: OcctKernel, { existing, source, request, profileChanged }: RetainedFaceDraftResolution, solidOf?: RetainedFaceDraftSolidOf): ResolvedSketchFaceDraftSource;
+/** The fields a retained face draft adds to its shape. */
+export type RetainedFaceDraftFields = {
+    faceDraft: SketchFaceDraft;
+    faceDraftSourceFaceIds: string[] | undefined;
+    faceDraftSourceSegmentId: string | undefined;
+    faceDraftSourceFrame: CadBrepFrame | undefined;
+};
+/**
+ * The record of a retained face draft.
+ *
+ * `sourceFaceIds` are the IDs of the undrafted source it was resolved on, and
+ * `frameSource` the shape the draft was asked of: its earlier source frame is
+ * kept through every replay, so a sketch edit never loses where it started.
+ */
+export declare function retainedFaceDraftFields(sourceFaceIds: string[] | undefined, frameSource: Pick<WorkplaneShape, "faceDraftSourceFrame" | "cadBrepFrame">, resolved: Pick<ResolvedSketchFaceDraftSource, "faceId" | "normal" | "segmentMatch">, request: {
+    angle: number;
+    pullDirection: SketchFaceDraftPullDirection;
+}): RetainedFaceDraftFields;
+/**
+ * Resolve and draft a retained face draft on the undrafted source.
+ *
+ * The editor's CAD worker runs this. The drafted solid is in the source
+ * B-rep's own frame; `sourceFaceIds` are the source's listed IDs and
+ * `resultFaceIds` inherit them for faces the draft left alone.
+ */
+export declare function retainedSketchFaceDraft(cad: OcctKernel, resolution: RetainedFaceDraftResolution): {
+    solid: ShapeHandle;
+    resolved: ResolvedSketchFaceDraftSource;
+    sourceFaceIds: string[];
+    resultFaceIds: string[];
+};
+/** The fields a retained prism draft adds to its shape. */
+export declare function retainedPrismDraftFields(shape: Pick<WorkplaneShape, "draftPrismSourceFrame" | "draftPrismSourceHeight" | "cadBrepFrame" | "height">, angle: number): {
+    draftPrismSourceFrame?: CadBrepFrame | undefined;
+    draftPrismAngle: number;
+    draftPrismSourceHeight: number;
+};
+/**
+ * The centre of a profile's bounds: where a prism draft's B-rep is centred,
+ * and where a straight extrusion of it has its frame.
+ */
+export declare function draftPrismProfileOffset(profile: Pick<SketchProfile, "points">): {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Where the REST API places the undrafted extrusion a retained draft is
+ * rebuilt on, and so the drafted result, which keeps it.
+ *
+ * The shape's position is moved by however far the rebuilt extrusion's frame
+ * is from the source frame the draft first started from. Frame offsets are in
+ * sketch coordinates, so rotate them by the shape's placement before adding
+ * them to its world position. The editor and REST use this same rule so one
+ * record means one placement whichever side wrote it (#384, #435).
+ */
+export declare function retainedDraftSourcePlacement(existing: Pick<WorkplaneShape, "x" | "z" | "elevation" | "rotation" | "rotationX" | "rotationZ" | "mirrorX" | "mirrorY" | "mirrorZ" | "faceDraftSourceFrame" | "draftPrismSourceFrame" | "cadBrepFrame">, rebuiltFrame: Pick<CadBrepFrame, "x" | "z" | "elevation">, sourceFrameOverride?: Pick<CadBrepFrame, "x" | "z" | "elevation">): {
+    x: number;
+    z: number;
+    elevation: number;
+};
+export {};
+//# sourceMappingURL=sketchFaceDraftKernel.d.ts.map

package/dist/sketchFaceDraftKernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sketchFaceDraftKernel.d.ts","sourceRoot":"","sources":["../src/sketchFaceDraftKernel.ts"],"names":[],"mappings":"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"}