@toolpath/tool-support 0.1.0

package/dist/holding.js

@@ -0,0 +1,203 @@
+/**
+ * What holds a tool, and the stack the two make together.
+ *
+ * ## The holder is a union, not one shape with optional extras
+ *
+ * A holder arrives in one of two forms and they are alternatives rather than a
+ * refinement of one by the other: {@link Holder} is what a vendor *publishes*
+ * about it, and {@link HolderProfile} is what its own CAD model *measures*.
+ * {@link isHolderProfile} tells them apart. A consumer that has both picks one;
+ * a consumer that has neither passes `null` and the tool stands alone.
+ *
+ * ## What is here and what is not
+ *
+ * Three shapes in this tree called themselves a holder and no two agreed on
+ * which fields exist — sixteen, nine and nineteen. What they *did* agree on is
+ * the geometry below, which is also exactly what a drawing and a clearance
+ * sweep read. Identity and commerce — a guid, a brand, a catalog number, the
+ * vendor's own CAD download — belong to a catalog's record, which extends this.
+ *
+ * ## How a holder grips is optional, and the absence is load bearing
+ *
+ * {@link Holder.clamping}, {@link Holder.boreDiameter} and {@link Holder.taper}
+ * arrived with the functions that read them, and they are optional because a
+ * drawing has never needed them: a consumer that hands over nine numbers to get
+ * a picture must not have to invent a clamping mode to do it.
+ *
+ * **Absent means nobody has said, and nobody-has-said refuses.** A holder that
+ * does not state how it clamps takes no tool, offers no grip range and matches
+ * no taper. That is the same rule {@link holderTakesTool} applies to a tool
+ * with no stated shank, and for the same reason: the unchecked case here is a
+ * cutter falling out of a spindle.
+ */
+import { DEFAULT_STICKOUT_POLICY, stickoutRange, } from './stickout.js';
+import { DEFAULT_CLAMPING } from './clamping.js';
+/**
+ * Which of the two holder forms this is.
+ *
+ * On the presence of `points` rather than on a `kind` tag, because a tag would
+ * have to be added to {@link Holder} as well and every existing adapter would
+ * stop compiling to gain nothing a structural check does not already give.
+ */
+export const isHolderProfile = (holder) => 'points' in holder;
+/**
+ * A collet fits a holder when the holder takes collets of exactly its series.
+ *
+ * A series is a mechanical interface and not a size class: an `ER16` collet
+ * does not go in an `ER20` nose.
+ */
+export const colletFitsHolder = (collet, holder) => holder.clamping === 'collet' && holder.colletSeries === collet.series;
+/**
+ * A hair of tolerance, because 3/8" is 9.525 on the collet's sheet and
+ * 9.524999999999999 on the tool's after a conversion. Strict, 350 tools in the
+ * scraped catalog had no collet in the crib.
+ */
+const GRIP_TOLERANCE = 1e-6;
+/** Whether a collet grips a given shank diameter, in millimetres. */
+export const gripsShank = (collet, shank) => shank >= collet.clampMin - GRIP_TOLERANCE && shank <= collet.clampMax + GRIP_TOLERANCE;
+/**
+ * Whether a bore, shrink or hydraulic holder's one diameter is this shank.
+ *
+ * The same hair of tolerance {@link gripsShank} carries, for the same reason: a
+ * ½" bore is 12.7 on the holder's sheet and 12.699999999999999 on the tool's
+ * after a conversion. Exact, an inch holder matches an inch tool only by luck.
+ */
+const boreTakesShank = (bore, shank) => Math.abs(bore - shank) <= GRIP_TOLERANCE;
+/**
+ * Whether a holder takes this tool's shank, with the collet if it needs one.
+ *
+ * **A tool whose shank the vendor does not state is refused, not assumed to
+ * fit.** This is the one place the domain differs from "what is not stated is
+ * not checked", because here the unchecked case is a cutter falling out of a
+ * spindle.
+ */
+export const holderTakesTool = (holder, collet, tool) => {
+    const shank = tool.geometry.SFDM;
+    if (shank === undefined) {
+        return false;
+    }
+    if (holder.clamping === 'collet') {
+        return collet !== null && colletFitsHolder(collet, holder) && gripsShank(collet, shank);
+    }
+    // A holder that states no clamping mode falls here and is refused: absent
+    // means nobody has said, and nobody-has-said takes no tool.
+    if (collet !== null || holder.boreDiameter === null || holder.boreDiameter === undefined) {
+        return false;
+    }
+    return boreTakesShank(holder.boreDiameter, shank);
+};
+/**
+ * The furthest a tool can stand out of its holder, in millimetres: overall
+ * length less the length that has to stay gripped.
+ *
+ * `null` when either is unstated. A maximum stickout is exactly the number
+ * somebody would use to decide a deep pocket is reachable, and a guessed one is
+ * worse than an absent one. A bore or shrink holder's grip length is the
+ * holder's rather than a collet's, and this package does not carry it — so
+ * those answer `null` too, honestly, until the contract gains it.
+ */
+export const maxStickout = (tool, collet) => {
+    const overall = tool.geometry.OAL;
+    if (overall === undefined || collet === null || collet.clampLength === null) {
+        return null;
+    }
+    const stickout = overall - collet.clampLength;
+    return stickout > 0 ? stickout : null;
+};
+/**
+ * How well the holder has hold of the tool at this stickout, by the share of
+ * the overall length left in the holder.
+ *
+ * At or above `good` is good; between `least` and that is possible but bad;
+ * below `least` is not compatible. The thresholds are a shop's, handed in as
+ * fractions rather than named here, because they are the same knob
+ * {@link StickoutPolicy.heldShare} is and a package must not carry two.
+ */
+export const holdBand = (tool, stickout, thresholds) => {
+    const { OAL } = tool.geometry;
+    if (OAL === undefined || OAL <= 0) {
+        return null;
+    }
+    const held = (OAL - stickout) / OAL;
+    return held >= thresholds.good - 1e-9
+        ? 'good'
+        : held >= thresholds.least - 1e-9
+            ? 'medium'
+            : 'bad';
+};
+/**
+ * How far this tool may stand out of this holder — the collet-shaped way into
+ * {@link stickoutRange}.
+ *
+ * **The arithmetic is not here.** This was one of the four places that worked
+ * out a stickout, and the one that capped at a share of the overall length
+ * while the clamping rule capped at a length of shank and neither knew about
+ * the other. `stickout.ts` owns the quantity and combines the two knobs in one
+ * place; this maps a collet onto the grip length that module asks for, which is
+ * all a collet was ever contributing.
+ */
+export const stickoutLimits = (tool, collet, 
+/** What the holder needs to clear the part, from the sweep: the setup stands out at least this far. */
+required = null, policy = DEFAULT_STICKOUT_POLICY, rule = DEFAULT_CLAMPING) => stickoutRange(tool, { grip: collet?.clampLength ?? null, required, policy, rule });
+/**
+ * The stickout an assembly starts at: the setup length for this tool, held
+ * within what the grip allows.
+ *
+ * A tool whose setup outruns its grip is gripped as short as the grip lets it
+ * and no shorter — rather than refused, because the shop is the one who knows
+ * whether that is a problem.
+ */
+export const defaultStickout = (tool, collet) => stickoutLimits(tool, collet)?.setup ?? maxStickout(tool, collet);
+/** `taper` narrows to one spindle interface, `colletSeries` to one collet family; either left out means "any". */
+export const gripRanges = (holders, collets, want = {}) => {
+    const spans = [];
+    const bores = [];
+    for (const holder of holders) {
+        if (want.taper && holder.taper !== want.taper) {
+            continue;
+        }
+        if (holder.clamping === 'collet') {
+            for (const collet of collets) {
+                if (want.colletSeries && collet.series !== want.colletSeries) {
+                    continue;
+                }
+                if (!colletFitsHolder(collet, holder)) {
+                    continue;
+                }
+                spans.push([collet.clampMin, collet.clampMax]);
+            }
+            continue;
+        }
+        // A bore or shrink holder takes one nominal diameter, so it can never
+        // satisfy a request for a particular collet series.
+        if (want.colletSeries) {
+            continue;
+        }
+        if (holder.boreDiameter !== null && holder.boreDiameter !== undefined) {
+            bores.push(holder.boreDiameter);
+        }
+    }
+    return { spans, bores };
+};
+/**
+ * Whether anything in {@link gripRanges} holds this shank, in millimetres.
+ *
+ * **Through {@link gripsShank} and {@link boreTakesShank}, not a second
+ * comparison.** This is the fast filter and `holderTakesTool` is the exact
+ * check, and the two must agree: asked strictly, a ⅜" shank that converts to
+ * 9.524999999999999 misses a collet whose sheet says 9.525, so the crib reports
+ * no holder for a tool the holder plainly takes. That is the failure the
+ * tolerance above was introduced for, and it belongs on both paths.
+ */
+export const gripsAnyShank = (ranges, shank) => ranges.spans.some(([clampMin, clampMax]) => gripsShank({ clampMin, clampMax }, shank)) ||
+    ranges.bores.some((bore) => boreTakesShank(bore, shank));
+/**
+ * Whether the crib can hold this tool at all.
+ *
+ * A tool whose shank the vendor does not state is refused, for the same reason
+ * {@link holderTakesTool} refuses it.
+ */
+export const canHold = (ranges, tool) => {
+    const shank = tool.geometry.SFDM;
+    return shank !== undefined && gripsAnyShank(ranges, shank);
+};

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The cutting-tool domain: what a tool, a holder, a collet and an assembly
+ * _are_, and the arithmetic that follows from them.
+ *
+ * This package takes no runtime dependencies and imports no React, no DOM, no
+ * `fs` and no Toolpath SDK. Everything else that speaks about cutting tools
+ * depends on it and it depends on nothing — which is what lets a Node ingest
+ * script, a server route and a React renderer share one answer instead of three.
+ *
+ * ## Why it exists
+ *
+ * A scraper produced tool data, a drawing consumed it, and every application in
+ * between re-derived what a tool assembly is. The same fact was declared three
+ * times over — two names for one unit constant, three for one unit vocabulary,
+ * three provenance types, two `PROFILES_VERSION`s compared against each other
+ * under an alias, and three shapes called "holder" of which no two agreed on
+ * which fields exist.
+ *
+ * That is not a tidiness complaint. How far a tool stands out of its holder was
+ * computed in four unconnected places and disagreed by a factor of two on an
+ * ordinary tool: a details table printed one number and the drawing beside it
+ * drew another, and the dimension line ran past the holder nose into the holder
+ * body. It was fixed inside one application, so the next consumer of the same
+ * two packages reproduces it from scratch. The quantity that went wrong is a
+ * pure function of the tool, the collet and a shop's policy, and it had no home.
+ *
+ * ## What is here
+ *
+ * The vocabulary and the contracts: units, provenance, the geometry dictionary,
+ * the form list, the holder union, the collet, the profile, the reach curve and
+ * what a feature demands of a tool. Everything is a readonly interface or a pure
+ * function over one — no classes, deliberately, because a class loses structural
+ * typing at a package boundary and `instanceof` breaks across duplicate installs.
+ *
+ * On them, the arithmetic that had been written more than once: {@link hasNeck}
+ * and {@link shankOf}, {@link heightAt} and {@link belowGageLine} each had two
+ * copies with a note beside each saying the two must agree and nothing watching
+ * whether they did — and {@link stickoutRange}, which had four.
+ *
+ * With those, the decisions that follow from them: what holds what
+ * ({@link holderTakesTool}, {@link gripRanges}), what a shop keeps clamped
+ * ({@link clampWanted}), whether a tool cuts a feature ({@link fitAgainst}),
+ * whether the whole stack clears the material around it ({@link clearance},
+ * {@link assemblyAgainst}), and the feature in section ({@link sectionOutline})
+ * that draws what the sweep checked.
+ */
+export { MM_PER_INCH, UNIT_ABBREVIATION, UNIT_SYSTEMS, convertArea, convertLength, decimalsFor, formatArea, formatLength, type UnitSystem, } from './units.js';
+export { PROVENANCE, type Provenance, type ProvenanceMap } from './provenance.js';
+export { GEOMETRY_FIELDS, convertGeometry, geometryField, isLengthField, type Geometry, type GeometryCode, type GeometryField, type GeometryUnit, } from './geometry.js';
+export { MILLING_FORMS, TOOL_FORMS, isToolForm, type ToolForm, type ToolFormEntry, } from './forms.js';
+export { hasNeck, shankOf, type Shank, type Tool } from './tool.js';
+export { PROFILES_VERSION, belowGageLine, type HolderProfile, type ProfileDatum, type ProfilePoint, } from './profile.js';
+export { canHold, colletFitsHolder, defaultStickout, gripRanges, gripsAnyShank, gripsShank, holdBand, holderTakesTool, isHolderProfile, maxStickout, stickoutLimits, type Assembly, type Clamping, type Collet, type GripRanges, type HoldBand, type Holder, } from './holding.js';
+export { DEFAULT_CLAMPING, clampShortfall, clampWanted, headLength, heldDiameter, type ClampingRule, } from './clamping.js';
+export { DEFAULT_STICKOUT_POLICY, HELD_SHARE, minStickout, setupStickout, stickoutCeiling, stickoutRange, type StickoutLimit, type StickoutPolicy, type StickoutRange, type StickoutRequest, type StickoutTool, } from './stickout.js';
+export { heightAt, type ReachCurve } from './reach.js';
+export type { FeatureDemand } from './demand.js';
+export { DRILLING_FORMS, fitAgainst, fitTools, type FitFailure, type ToolFit } from './fit.js';
+export { ASSEMBLY_PARTS, NO_MARGINS, SILHOUETTE_PARTS, type AssemblyPart, type Margins, type Silhouette, type SilhouettePart, } from './parts.js';
+export { materialProfile, type OutlinePoint } from './material.js';
+export { clearance, describeCollision, holderSilhouette, toolCollisions, toolSilhouette, type Clearance, type Collision, type SweptAssembly, } from './clearance.js';
+export { FLOOR_BAND, REACH, sectionOutline, type FeatureSection, type Section, type SectionKind, type SectionPoint, } from './section.js';
+export { NOT_MODELLED, assemblyAgainst, type AssemblyFit } from './assembly-fit.js';

package/dist/index.js

@@ -0,0 +1,62 @@
+/**
+ * The cutting-tool domain: what a tool, a holder, a collet and an assembly
+ * _are_, and the arithmetic that follows from them.
+ *
+ * This package takes no runtime dependencies and imports no React, no DOM, no
+ * `fs` and no Toolpath SDK. Everything else that speaks about cutting tools
+ * depends on it and it depends on nothing — which is what lets a Node ingest
+ * script, a server route and a React renderer share one answer instead of three.
+ *
+ * ## Why it exists
+ *
+ * A scraper produced tool data, a drawing consumed it, and every application in
+ * between re-derived what a tool assembly is. The same fact was declared three
+ * times over — two names for one unit constant, three for one unit vocabulary,
+ * three provenance types, two `PROFILES_VERSION`s compared against each other
+ * under an alias, and three shapes called "holder" of which no two agreed on
+ * which fields exist.
+ *
+ * That is not a tidiness complaint. How far a tool stands out of its holder was
+ * computed in four unconnected places and disagreed by a factor of two on an
+ * ordinary tool: a details table printed one number and the drawing beside it
+ * drew another, and the dimension line ran past the holder nose into the holder
+ * body. It was fixed inside one application, so the next consumer of the same
+ * two packages reproduces it from scratch. The quantity that went wrong is a
+ * pure function of the tool, the collet and a shop's policy, and it had no home.
+ *
+ * ## What is here
+ *
+ * The vocabulary and the contracts: units, provenance, the geometry dictionary,
+ * the form list, the holder union, the collet, the profile, the reach curve and
+ * what a feature demands of a tool. Everything is a readonly interface or a pure
+ * function over one — no classes, deliberately, because a class loses structural
+ * typing at a package boundary and `instanceof` breaks across duplicate installs.
+ *
+ * On them, the arithmetic that had been written more than once: {@link hasNeck}
+ * and {@link shankOf}, {@link heightAt} and {@link belowGageLine} each had two
+ * copies with a note beside each saying the two must agree and nothing watching
+ * whether they did — and {@link stickoutRange}, which had four.
+ *
+ * With those, the decisions that follow from them: what holds what
+ * ({@link holderTakesTool}, {@link gripRanges}), what a shop keeps clamped
+ * ({@link clampWanted}), whether a tool cuts a feature ({@link fitAgainst}),
+ * whether the whole stack clears the material around it ({@link clearance},
+ * {@link assemblyAgainst}), and the feature in section ({@link sectionOutline})
+ * that draws what the sweep checked.
+ */
+export { MM_PER_INCH, UNIT_ABBREVIATION, UNIT_SYSTEMS, convertArea, convertLength, decimalsFor, formatArea, formatLength, } from './units.js';
+export { PROVENANCE } from './provenance.js';
+export { GEOMETRY_FIELDS, convertGeometry, geometryField, isLengthField, } from './geometry.js';
+export { MILLING_FORMS, TOOL_FORMS, isToolForm, } from './forms.js';
+export { hasNeck, shankOf } from './tool.js';
+export { PROFILES_VERSION, belowGageLine, } from './profile.js';
+export { canHold, colletFitsHolder, defaultStickout, gripRanges, gripsAnyShank, gripsShank, holdBand, holderTakesTool, isHolderProfile, maxStickout, stickoutLimits, } from './holding.js';
+export { DEFAULT_CLAMPING, clampShortfall, clampWanted, headLength, heldDiameter, } from './clamping.js';
+export { DEFAULT_STICKOUT_POLICY, HELD_SHARE, minStickout, setupStickout, stickoutCeiling, stickoutRange, } from './stickout.js';
+export { heightAt } from './reach.js';
+export { DRILLING_FORMS, fitAgainst, fitTools } from './fit.js';
+export { ASSEMBLY_PARTS, NO_MARGINS, SILHOUETTE_PARTS, } from './parts.js';
+export { materialProfile } from './material.js';
+export { clearance, describeCollision, holderSilhouette, toolCollisions, toolSilhouette, } from './clearance.js';
+export { FLOOR_BAND, REACH, sectionOutline, } from './section.js';
+export { NOT_MODELLED, assemblyAgainst } from './assembly-fit.js';

package/dist/material.d.ts

@@ -0,0 +1,29 @@
+import type { ReachCurve } from './reach.js';
+/**
+ * The material around a feature, as a drawing.
+ *
+ * The one reading of a reach curve with two consumers that are not both
+ * drawings: a clearance overlay draws the wall from it, and `section.ts` draws
+ * a feature section from it. It sat in an application because moving it into a
+ * rendering package would have put the second of those behind a dependency it
+ * has no use for; here it is behind nothing.
+ */
+/** Radius out from the axis and height above the tip, both in millimetres. */
+export interface OutlinePoint {
+    readonly r: number;
+    readonly z: number;
+}
+/**
+ * The material around the feature as a drawing beside the tool.
+ *
+ * The reach curve's offsets are from the wall of the cut, so each knot lands at
+ * `cuttingRadius + offset` across. **The staircase is the sweep's, exactly**:
+ * `heightAt` reads "material within h[i] rises to v[i]" as *every* offset up
+ * to the knot being that tall, so the rise comes at the start of each run,
+ * not at its end. Drawn the other way round — up at the knot, as this once
+ * was — the picture showed a nose clearing material the sweep had already
+ * failed it on, and a drawing that disagrees with its own verdict is worse
+ * than none. Past the last knot the material stays at the last height, which
+ * is the renderer's to extend to its edge.
+ */
+export declare const materialProfile: (curve: ReachCurve, cuttingRadius: number) => Array<OutlinePoint>;

package/dist/material.js

@@ -0,0 +1,30 @@
+/**
+ * The material around the feature as a drawing beside the tool.
+ *
+ * The reach curve's offsets are from the wall of the cut, so each knot lands at
+ * `cuttingRadius + offset` across. **The staircase is the sweep's, exactly**:
+ * `heightAt` reads "material within h[i] rises to v[i]" as *every* offset up
+ * to the knot being that tall, so the rise comes at the start of each run,
+ * not at its end. Drawn the other way round — up at the knot, as this once
+ * was — the picture showed a nose clearing material the sweep had already
+ * failed it on, and a drawing that disagrees with its own verdict is worse
+ * than none. Past the last knot the material stays at the last height, which
+ * is the renderer's to extend to its edge.
+ */
+export const materialProfile = (curve, cuttingRadius) => {
+    const points = [{ r: cuttingRadius, z: 0 }];
+    const push = (point) => {
+        const last = points[points.length - 1];
+        if (!last || last.r !== point.r || last.z !== point.z) {
+            points.push(point);
+        }
+    };
+    let from = 0;
+    curve.horizontalOffset.forEach((offset, index) => {
+        const height = curve.verticalOffset[index] ?? 0;
+        push({ r: cuttingRadius + from, z: height });
+        push({ r: cuttingRadius + offset, z: height });
+        from = offset;
+    });
+    return points;
+};

package/dist/parts.d.ts

@@ -0,0 +1,56 @@
+/**
+ * What an assembly is made of, named once.
+ *
+ * Two vocabularies for these eight words stood in this tree: a drawing's
+ * `OutlinePart`, and a clearance sweep's `SilhouettePart`, which was the same
+ * list without the two cutting parts. They were not a duplicate by accident —
+ * the sweep genuinely does not check the cutting end, because the cutting end
+ * is what is cutting — but the *words* were, and a part renamed in one would
+ * have gone on meaning the old thing in the other.
+ *
+ * ## Two representations, one vocabulary
+ *
+ * A drawing needs a polyline per part; a sweep needs one radius from one height
+ * upward. Those are different shapes for different questions and neither
+ * projects onto the other, so both survive — {@link Silhouette} here and
+ * `OutlineSegment` in `@toolpath/tool-drawing`. What is shared is the naming.
+ */
+/** Every part a drawn or swept assembly is made of, tip first. */
+export declare const ASSEMBLY_PARTS: readonly ["tip", "flutes", "neck", "shank", "collet", "nose", "body", "flange"];
+export type AssemblyPart = (typeof ASSEMBLY_PARTS)[number];
+/**
+ * The parts a clearance sweep checks: everything but the cutting end.
+ *
+ * Derived from {@link ASSEMBLY_PARTS} rather than listed again, so a part added
+ * there is swept unless it is deliberately excluded here. The tip and the
+ * flutes are excluded because they are the cut — material at the cutting radius
+ * is what the tool is there to remove.
+ */
+export declare const SILHOUETTE_PARTS: readonly Exclude<AssemblyPart, "tip" | "flutes">[];
+export type SilhouettePart = (typeof SILHOUETTE_PARTS)[number];
+/**
+ * One step of an assembly's profile: this radius, from this height above the
+ * tip.
+ *
+ * **A radius from a height upward**, not a band: the last stated diameter
+ * carries itself up to the next step. That is the layer model a reach curve is
+ * swept against, and it is why nothing has to be invented for the shape between
+ * a holder's body and its flange.
+ */
+export interface Silhouette {
+    readonly part: SilhouettePart;
+    readonly radius: number;
+    readonly fromHeight: number;
+}
+/** Room the shop wants kept between the stack and the part, in millimetres. */
+export interface Margins {
+    /**
+     * Widens every swept part, so it must clear the wall sideways by this much.
+     */
+    readonly radial: number;
+    /**
+     * Lifts the material, so a part must stand this far above what it clears.
+     */
+    readonly axial: number;
+}
+export declare const NO_MARGINS: Margins;

package/dist/parts.js

@@ -0,0 +1,38 @@
+/**
+ * What an assembly is made of, named once.
+ *
+ * Two vocabularies for these eight words stood in this tree: a drawing's
+ * `OutlinePart`, and a clearance sweep's `SilhouettePart`, which was the same
+ * list without the two cutting parts. They were not a duplicate by accident —
+ * the sweep genuinely does not check the cutting end, because the cutting end
+ * is what is cutting — but the *words* were, and a part renamed in one would
+ * have gone on meaning the old thing in the other.
+ *
+ * ## Two representations, one vocabulary
+ *
+ * A drawing needs a polyline per part; a sweep needs one radius from one height
+ * upward. Those are different shapes for different questions and neither
+ * projects onto the other, so both survive — {@link Silhouette} here and
+ * `OutlineSegment` in `@toolpath/tool-drawing`. What is shared is the naming.
+ */
+/** Every part a drawn or swept assembly is made of, tip first. */
+export const ASSEMBLY_PARTS = [
+    'tip',
+    'flutes',
+    'neck',
+    'shank',
+    'collet',
+    'nose',
+    'body',
+    'flange',
+];
+/**
+ * The parts a clearance sweep checks: everything but the cutting end.
+ *
+ * Derived from {@link ASSEMBLY_PARTS} rather than listed again, so a part added
+ * there is swept unless it is deliberately excluded here. The tip and the
+ * flutes are excluded because they are the cut — material at the cutting radius
+ * is what the tool is there to remove.
+ */
+export const SILHOUETTE_PARTS = ASSEMBLY_PARTS.filter((part) => part !== 'tip' && part !== 'flutes');
+export const NO_MARGINS = { radial: 0, axial: 0 };

package/dist/profile.d.ts

@@ -0,0 +1,104 @@
+/**
+ * A holder as its own CAD model measures it: the silhouette, and nothing
+ * parametric.
+ *
+ * Two `PROFILES_VERSION = 1` constants stood in this tree, one of which was
+ * imported under an alias specifically so it could be compared against the
+ * other. This is the one.
+ */
+import type { ProvenanceMap } from './provenance.js';
+/** Bumped when {@link HolderProfile} changes shape in a way a consumer must handle. */
+export declare const PROFILES_VERSION = 1;
+/** One vertex of a silhouette: `[z, r]`, both in millimetres. */
+export type ProfilePoint = readonly [z: number, r: number];
+/**
+ * What `z = 0` means on a profile.
+ *
+ * `gage-line` is the spindle face, with `z` increasing toward the cutting end —
+ * so the taper is negative, the nose positive, and the holder's gauge length is
+ * the last vertex's `z`. `nose` is the frame a holder with no taper to solve a
+ * gauge plane on is measured in, and it is stated rather than silently
+ * referenced to an arbitrary end: there is no gauge length to read off it, and a
+ * consumer must say so instead of printing one.
+ *
+ * **Per profile rather than per document.** One datum over a batch is only true
+ * while every holder in it has a taper, and the first Capto or straight-shank
+ * holder makes the document's own header wrong about some of its entries.
+ */
+export type ProfileDatum = 'gage-line' | 'nose';
+/**
+ * The measured envelope.
+ *
+ * A parametric holder is a handful of numbers off a DIN 4000 sheet, and a
+ * drawing built from them is a stylised holder. This is the other thing a
+ * catalog can have — the envelope measured off the vendor's STEP model, a
+ * hundred-odd vertices carrying the V-flange groove and the thread relief that
+ * a machinist actually looks for. **It is not a refinement of the parametric
+ * form and does not project onto it**: reducing it to a nose and a body throws
+ * away the only reason to measure.
+ *
+ * So the two are a union rather than one shape with optional extras — see
+ * `holding.ts` — and a consumer that has both picks one.
+ *
+ * How well the model agrees with the vendor's published gauge length, and by
+ * how much it falls short when it does not, is a fact about *that measurement
+ * run* and stays on whatever document carries the run. A record that has it
+ * extends this.
+ */
+export interface HolderProfile {
+    /**
+     * The silhouette as `[z, r]` in millimetres, `z` ascending.
+     *
+     * Two vertices share a `z` where the solid steps, so this is a polyline and
+     * not a function of `z`. Fewer than two vertices is no holder.
+     */
+    readonly points: readonly ProfilePoint[];
+    readonly datum: ProfileDatum;
+    /** The series the holder takes, as a parametric `Holder` means it. */
+    readonly colletSeries: string | null;
+    /** How far the seated collet stands proud of the nose, in millimetres. */
+    readonly colletProtrusion: number | null;
+    /**
+     * Keyed as a parametric `Holder`'s is, plus `points` for the measurement
+     * itself — which is `vendor-stated` unless a caller says otherwise, because
+     * the shape measured is the vendor's own model rather than a derivation from
+     * its table.
+     */
+    readonly provenance?: ProvenanceMap;
+}
+/**
+ * The silhouette from the gage line out, where the measurement knows where the
+ * gage line is.
+ *
+ * A CAT40 model is measured whole, and about half of what comes back is the
+ * 7:24 cone and the retention knob — the part that is inside the spindle when
+ * the holder is in the machine. That says nothing a machinist is asking a
+ * holder drawing, and it costs the frame: the tool ends up a third of the
+ * height it could be because the picture is scaled to fit a taper nobody is
+ * looking at.
+ *
+ * So a `gage-line` profile is cut at `z = 0`, which is the spindle face, and
+ * where the polyline crosses it between two vertices the crossing point is
+ * **interpolated** so the cut is the face rather than the nearest vertex to it.
+ * Nothing below the gage line is touched — the vertices that survive are the
+ * measurement, grooves and thread reliefs included.
+ *
+ * A `nose`-datumed profile is returned whole: with no gauge plane solved there
+ * is no line to cut on, and guessing one would be inventing the very number the
+ * datum exists to say is missing. A profile that would be left shorter than a
+ * segment is also returned whole, because a holder measured entirely inside the
+ * spindle is bad data and drawing a stub of it hides that.
+ *
+ * ## The crossing is the part that has to be shared
+ *
+ * A renderer that draws the whole holder still has to find this same `z = 0`
+ * crossing, because it splits the silhouette there to draw the connection in
+ * its own shade rather than trimming it away — a different decision about the
+ * same line. The two interpolations have to land on the same radius or a holder
+ * meets its gage line in two places, and that is asserted against this function
+ * rather than left as a note in both files.
+ *
+ * Takes the profile structurally, so a measurement record that carries more
+ * than this satisfies it with no adapter.
+ */
+export declare const belowGageLine: (profile: Pick<HolderProfile, "points" | "datum">) => readonly ProfilePoint[];

package/dist/profile.js

@@ -0,0 +1,68 @@
+/**
+ * A holder as its own CAD model measures it: the silhouette, and nothing
+ * parametric.
+ *
+ * Two `PROFILES_VERSION = 1` constants stood in this tree, one of which was
+ * imported under an alias specifically so it could be compared against the
+ * other. This is the one.
+ */
+/** Bumped when {@link HolderProfile} changes shape in a way a consumer must handle. */
+export const PROFILES_VERSION = 1;
+/**
+ * The silhouette from the gage line out, where the measurement knows where the
+ * gage line is.
+ *
+ * A CAT40 model is measured whole, and about half of what comes back is the
+ * 7:24 cone and the retention knob — the part that is inside the spindle when
+ * the holder is in the machine. That says nothing a machinist is asking a
+ * holder drawing, and it costs the frame: the tool ends up a third of the
+ * height it could be because the picture is scaled to fit a taper nobody is
+ * looking at.
+ *
+ * So a `gage-line` profile is cut at `z = 0`, which is the spindle face, and
+ * where the polyline crosses it between two vertices the crossing point is
+ * **interpolated** so the cut is the face rather than the nearest vertex to it.
+ * Nothing below the gage line is touched — the vertices that survive are the
+ * measurement, grooves and thread reliefs included.
+ *
+ * A `nose`-datumed profile is returned whole: with no gauge plane solved there
+ * is no line to cut on, and guessing one would be inventing the very number the
+ * datum exists to say is missing. A profile that would be left shorter than a
+ * segment is also returned whole, because a holder measured entirely inside the
+ * spindle is bad data and drawing a stub of it hides that.
+ *
+ * ## The crossing is the part that has to be shared
+ *
+ * A renderer that draws the whole holder still has to find this same `z = 0`
+ * crossing, because it splits the silhouette there to draw the connection in
+ * its own shade rather than trimming it away — a different decision about the
+ * same line. The two interpolations have to land on the same radius or a holder
+ * meets its gage line in two places, and that is asserted against this function
+ * rather than left as a note in both files.
+ *
+ * Takes the profile structurally, so a measurement record that carries more
+ * than this satisfies it with no adapter.
+ */
+export const belowGageLine = (profile) => {
+    if (profile.datum !== 'gage-line') {
+        return profile.points;
+    }
+    const cut = profile.points.findIndex(([z]) => z >= 0);
+    const inside = profile.points[cut - 1];
+    const outside = profile.points[cut];
+    if (cut <= 0 || inside === undefined || outside === undefined) {
+        return profile.points;
+    }
+    const kept = profile.points.slice(cut);
+    if (kept.length < 2) {
+        return profile.points;
+    }
+    if (outside[0] === 0) {
+        return kept;
+    }
+    const meet = [
+        0,
+        inside[1] + (-inside[0] / (outside[0] - inside[0])) * (outside[1] - inside[1]),
+    ];
+    return [meet, ...kept];
+};