@maslowcnc/abundance-bridge 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,7 +6,9 @@ You are assisting with writing code for an Abundance Code Atom. Abundance is a w
6
6
 
7
7
  A code atom helps build **one physical part**, inside that part's own molecule. Every board, panel, or bracket in a design gets its own molecule; left and right copies are one molecule placed twice with Move or Rotate. Never generate several parts from one code atom.
8
8
 
9
- Inside the part's molecule, use built-in atoms (Rectangle, Circle, Difference, Extrude, Rotate, Move, Tag, Add-BOM-Tag) and library molecules for everything they can do. Keep the code atom to the piece they can't, such as an unusual 2D outline, and return it so built-in atoms extrude, place, and tag it. Don't model slots or holes for mating parts: position the parts overlapping and let an Assembly cut them.
9
+ Inside the part's molecule, use built-in atoms (Rectangle, Circle, Difference, Extrude, Rotate, Move, Tag, Add-BOM-Tag) and library molecules for everything they can do. Keep the code atom to the piece they can't, such as an unusual 2D outline, and return it so built-in atoms extrude, place, and tag it. Don't model slots or holes for mating parts: position the parts overlapping and let an Assembly cut them. The same goes for clearance around hardware already in the design, such as pockets over bolt heads: keepout shapes around the hardware, assembled after the part, cut them. Standard hardware such as bolts and nuts comes from shared molecules (search_molecules), not code. A code atom is never a way to fit many features in one place because built-ins would take many atoms; give each feature a molecule of its own.
10
+
11
+ Code made only of boxes, cylinders, regular polygons, `translate`, `rotate`, `fuse`, `cut`, and `intersect` is refused by the agent bridge, because built-in atoms do all of it: Rectangle or Circle → Extrude for the solid, Rotate to point a cylinder along X or Y or lean a part, Move to place it, Difference or an Assembly for holes, and a pattern library molecule for repeated features. A code atom earns its place by drawing what those can't: a custom outline (`draw().lineTo()`, arcs, splines), a loft, revolve, or sweep, fillets, or geometry computed from a reference file's data.
10
12
 
11
13
  ## Code Structure Requirements
12
14
 
@@ -121,102 +123,71 @@ The Replicad library is available as the global `replicad`. Here are commonly us
121
123
 
122
124
  ## Common Patterns
123
125
 
124
- ### 1. Basic Geometry Creation with Default Parameters
125
-
126
- ```typescript
127
- function run(
128
- width: number = 40,
129
- depth: number = 30,
130
- height: number = 20,
131
- color: string = "#5B9BD5",
132
- ): Assembly {
133
- // Create a box with one corner at origin
134
- const box = replicad.makeBaseBox(width, depth, height);
135
-
136
- // Center it by translating
137
- const centered = box.translate(-width / 2, -depth / 2, 0);
138
-
139
- // Wrap in Assembly with metadata
140
- return new Assembly({
141
- geometry: centered,
142
- color: color,
143
- tags: ["box"],
144
- bom: [`Box ${width}×${depth}×${height} mm`],
145
- });
146
- }
147
- ```
148
-
149
- ### 2. Creating and Extruding Sketches
150
-
151
- ```typescript
152
- function run(radius: number = 10, height: number = 20): Assembly {
153
- const cylinder = replicad.drawCircle(radius).sketchOnPlane().extrude(height);
154
-
155
- return new Assembly({
156
- geometry: cylinder,
157
- color: "#FF6B6B",
158
- tags: ["cylinder"],
159
- });
160
- }
161
- ```
126
+ Every example below draws something built-in atoms can't. Boxes, cylinders, polygons, holes, moves, rotations, and plain booleans are built-in atoms (Rectangle, Circle, RegularPolygon, Extrude, Move, Rotate, Difference, Fusion, Assembly), so they never get a code atom of their own.
162
127
 
163
- ### 2b. Building Custom Sketches with Path Methods
128
+ ### 1. An Outline Computed from Inputs
164
129
 
165
130
  ```typescript
166
- function run(width: number = 30, height: number = 20): Assembly {
167
- // Build a custom shape using drawing chain
168
- const customShape = replicad
169
- .drawRectangle(width, height)
170
- .moveTo(0, 0)
171
- .lineTo(width / 2, height / 2) // draw diagonal line
131
+ /** Teardrop outline: a round end of the given radius tapering to a point. */
132
+ function run(radius: number = 15, length: number = 50): Assembly {
133
+ const angle = Math.asin(radius / length); // where the straight sides meet the circle
134
+ const tx = radius * Math.sin(angle);
135
+ const ty = radius * Math.cos(angle);
136
+ const outline = replicad
137
+ .draw([length, 0])
138
+ .lineTo([tx, ty])
139
+ .threePointArcTo([tx, -ty], [-radius, 0])
172
140
  .close();
173
-
174
- const extruded = customShape.sketchOnPlane().extrude(10);
175
-
176
- return new Assembly({
177
- geometry: extruded,
178
- tags: ["custom"],
179
- });
141
+ // Return the 2D outline; an Extrude atom beside this one gives it thickness.
142
+ return new Assembly({ geometry: outline, tags: ["teardrop"] });
180
143
  }
181
144
  ```
182
145
 
183
- ### 2c. Drawing with Curves
146
+ ### 2. Revolving a Profile
184
147
 
185
148
  ```typescript
186
- function run(): Assembly {
187
- const curved = replicad
188
- .drawRectangle(20, 20)
189
- .moveTo(10, 0)
190
- .bezierCurveTo(15, 5, 15, 15, 10, 20) // cubic Bezier curve
149
+ /** A turned knob: a profile drawn in XZ and revolved about Z. */
150
+ function run(diameter: number = 30, height: number = 20): Assembly {
151
+ const r = diameter / 2;
152
+ const profile = replicad
153
+ .draw([0, 0])
154
+ .lineTo([r, 0])
155
+ .lineTo([r, height * 0.6])
156
+ .sagittaArcTo([0, height], r * 0.3)
191
157
  .close();
192
-
193
- return new Assembly({
194
- geometry: curved.sketchOnPlane().extrude(5),
195
- });
158
+ const knob = profile.sketchOnPlane("XZ").revolve();
159
+ return new Assembly({ geometry: knob, color: "#333333", tags: ["knob"] });
196
160
  }
197
161
  ```
198
162
 
199
- ### 3. Boolean Operations (Union & Cut)
163
+ ### 3. A Curved Slot
164
+
165
+ An arc-shaped slot with round ends, such as an adjustment slot for a pivot. The code returns only the slot's outline; an Extrude atom makes it a cutter and a Difference atom cuts it from the part.
200
166
 
201
167
  ```typescript
202
- function run(baseSize: number = 40, holeRadius: number = 6): Assembly {
203
- // Create base plate
204
- const plate = replicad.makeBaseBox(baseSize, baseSize, 5);
205
-
206
- // Create hole cutter
207
- const holeCutter = replicad
208
- .drawCircle(holeRadius)
209
- .sketchOnPlane()
210
- .extrude(7)
211
- .translate(0, 0, -1); // Start below surface to ensure clean cut
212
-
213
- // Cut the hole
214
- const result = plate.cut(holeCutter);
215
-
216
- return new Assembly({
217
- geometry: result,
218
- tags: ["plate-with-hole"],
219
- });
168
+ function run(
169
+ radius: number = 40, // radius of the slot's centerline
170
+ width: number = 8, // slot width
171
+ sweepDeg: number = 60, // angle the slot covers
172
+ ): Assembly {
173
+ const a = (sweepDeg * Math.PI) / 180;
174
+ const ro = radius + width / 2,
175
+ ri = radius - width / 2;
176
+ const pt = (r: number, t: number) => [r * Math.cos(t), r * Math.sin(t)];
177
+ // Each round end bulges out along the slot's direction at that end.
178
+ const endCapMid = [
179
+ radius * Math.cos(a) - (width / 2) * Math.sin(a),
180
+ radius * Math.sin(a) + (width / 2) * Math.cos(a),
181
+ ];
182
+ const startCapMid = [radius, -width / 2];
183
+ const outline = replicad
184
+ .draw(pt(ro, 0))
185
+ .threePointArcTo(pt(ro, a), pt(ro, a / 2)) // outer edge
186
+ .threePointArcTo(pt(ri, a), endCapMid) // far round end
187
+ .threePointArcTo(pt(ri, 0), pt(ri, a / 2)) // inner edge
188
+ .threePointArcTo(pt(ro, 0), startCapMid) // near round end
189
+ .close();
190
+ return new Assembly({ geometry: outline, tags: ["slot"] });
220
191
  }
221
192
  ```
222
193
 
@@ -241,7 +212,11 @@ function run(
241
212
  When only a part's outline needs code, return the sketch and let Extrude, Rotate, Move, and Tag atoms in the molecule do the rest:
242
213
 
243
214
  ```typescript
244
- function run(width: number = 90, height: number = 580, sweep: number = 20): Assembly {
215
+ function run(
216
+ width: number = 90,
217
+ height: number = 580,
218
+ sweep: number = 20,
219
+ ): Assembly {
245
220
  const offset = height * Math.tan((sweep * Math.PI) / 180);
246
221
  const outline = replicad
247
222
  .draw([0, 0])
@@ -253,6 +228,54 @@ function run(width: number = 90, height: number = 580, sweep: number = 20): Asse
253
228
  }
254
229
  ```
255
230
 
231
+ ### 5b. An Outline Traced from a Reference
232
+
233
+ trace_reference returns a shape's outline from a photo or drawing as points in project units. Paste them into a code atom that draws a smooth closed curve through them (a Catmull-Rom spline, drawn as cubic Béziers), and extrude it with an Extrude atom:
234
+
235
+ ```typescript
236
+ /** Body outline traced from the reference photo, in mm. */
237
+ const POINTS: number[][] = [
238
+ [-0.9, -430.5], [8.7, -431.6], [18.2, -432.9], // ...every point trace_reference returned
239
+ ];
240
+
241
+ function run(): Assembly {
242
+ const n = POINTS.length;
243
+ const p = (i: number) => POINTS[(i + n) % n];
244
+ let pen = replicad.draw(p(0));
245
+ for (let i = 0; i < n; i++) {
246
+ const [a, b, c, d] = [p(i - 1), p(i), p(i + 1), p(i + 2)];
247
+ const c1 = [b[0] + (c[0] - a[0]) / 6, b[1] + (c[1] - a[1]) / 6];
248
+ const c2 = [c[0] - (d[0] - b[0]) / 6, c[1] - (d[1] - b[1]) / 6];
249
+ pen = pen.cubicBezierCurveTo(c, c1, c2);
250
+ }
251
+ return new Assembly({ geometry: pen.close() });
252
+ }
253
+ ```
254
+
255
+ ### 5c. Reading a Reference Image's Pixels
256
+
257
+ Images, PDFs, and glTF models from Import atoms reach code atoms as reference parts: `part.isReference()` is true and `part.geometryType` is `"image"`, `"pdf"`, or `"gltf"` (it's undefined for replicad shapes). `part.metadata.reference` describes the file (name, mimeType, pixel size, page). `await part.file()` returns the file as a Blob, and for images `await part.pixels()` returns `{ width, height, data }` with RGBA bytes, row by row from the top. `part.placement` is a 4x4 column-major matrix from the file's own coordinates to the project's: an image is a rectangle one unit per pixel, centered on its origin, +Y up. A reference can't be cut, moved, or changed in code; return it as it is to keep it in the output. This builds a block per pixel from a heightmap, with red as height:
258
+
259
+ ```typescript
260
+ async function run(map: Assembly, maxHeight: number = 10): Promise<Assembly> {
261
+ const { width, height, data } = await map.pixels();
262
+ const m = map.placement; // m[0] and m[5] are mm per pixel when not rotated
263
+ const blocks: Assembly[] = [];
264
+ for (let row = 0; row < height; row++) {
265
+ for (let col = 0; col < width; col++) {
266
+ const z = (data[(row * width + col) * 4] / 255) * maxHeight;
267
+ if (z <= 0) continue;
268
+ const x = (col + 0.5 - width / 2) * m[0] + m[12];
269
+ const y = (height / 2 - row - 0.5) * m[5] + m[13];
270
+ blocks.push(new Assembly({
271
+ geometry: replicad.makeBaseBox(m[0], m[5], z).translate([x, y, 0]),
272
+ }));
273
+ }
274
+ }
275
+ return new Assembly({ geometry: blocks });
276
+ }
277
+ ```
278
+
256
279
  ### 6. Adding Fillets and Chamfers
257
280
 
258
281
  ```typescript
@@ -306,53 +329,45 @@ function run(input: Assembly | undefined): Assembly {
306
329
  7. ❌ Using old JavaScript `Inputs` array syntax in new code
307
330
  8. ❌ Building several parts in one code atom instead of one molecule per part
308
331
  9. ❌ Cutting slots, tabs' mating holes, or dogbones for other parts by hand instead of letting an Assembly cut them
332
+ 10. ❌ Using a code atom for what built-in atoms do: boxes, cylinders (along any axis), hex heads, holes, moves, rotations, repeated features, and booleans of those. The agent bridge refuses such code.
309
333
 
310
334
  ## Example: Complete TypeScript Code Atom
311
335
 
312
336
  ```typescript
313
337
  /**
314
- * Mounting plate with optional countersunk holes.
338
+ * Disc cam outline from its motion: the follower rises by `lift` over
339
+ * `riseDeg` with a smooth (cycloidal) motion, dwells, then falls back over
340
+ * the same angle. Returns the 2D outline; in the cam's molecule an Extrude atom
341
+ * gives it thickness and a Circle with a Difference atom cuts the shaft bore.
315
342
  */
316
343
  function run(
317
- width: number = 50,
318
- depth: number = 40,
319
- thickness: number = 5,
320
- holeRadius: number = 4,
321
- holeCount: number = 2,
322
- color: string = "#4A90E2",
344
+ baseRadius: number = 25, // follower distance at its lowest
345
+ lift: number = 10, // how far the follower rises
346
+ riseDeg: number = 120, // cam rotation over which it rises (and falls)
347
+ steps: number = 180, // points around the outline
323
348
  ): Assembly {
324
- console.log(
325
- `Creating plate: ${width}×${depth}×${thickness} with ${holeCount} holes`,
326
- );
327
-
328
- // Create base plate, centered
329
- let plate = replicad
330
- .makeBaseBox(width, depth, thickness)
331
- .translate(-width / 2, -depth / 2, 0);
332
-
333
- // Create holes
334
- for (let i = 0; i < holeCount; i++) {
335
- const x = (i - (holeCount - 1) / 2) * (width / (holeCount + 1));
336
- const holeCutter = replicad
337
- .drawCircle(holeRadius)
338
- .sketchOnPlane()
339
- .extrude(thickness + 2)
340
- .translate(x, 0, -1);
341
-
342
- plate = plate.cut(holeCutter);
349
+ const rise = (riseDeg * Math.PI) / 180;
350
+ const radiusAt = (t: number) => {
351
+ if (t <= rise)
352
+ return (
353
+ baseRadius +
354
+ lift * (t / rise - Math.sin((2 * Math.PI * t) / rise) / (2 * Math.PI))
355
+ );
356
+ const fallStart = 2 * Math.PI - rise;
357
+ if (t >= fallStart) return radiusAt(2 * Math.PI - t);
358
+ return baseRadius + lift;
359
+ };
360
+ const points = [];
361
+ for (let i = 0; i < steps; i++) {
362
+ const t = (i / steps) * 2 * Math.PI;
363
+ const r = radiusAt(t);
364
+ points.push([r * Math.cos(t), r * Math.sin(t)]);
343
365
  }
344
-
345
- // Soften top edges
346
- plate = plate.fillet(0.5, (e) => e.inPlane("XY", thickness));
347
-
348
- return new Assembly({
349
- geometry: plate,
350
- color: color,
351
- tags: ["mounting-plate", "drilled"],
352
- bom: [
353
- `Mounting plate ${width}×${depth}×${thickness}mm with ${holeCount} holes`,
354
- ],
355
- });
366
+ let pen = replicad.draw(points[0]);
367
+ for (const p of points.slice(1)) pen = pen.lineTo(p);
368
+ const outline = pen.close();
369
+ console.log(`Cam: ${baseRadius} to ${baseRadius + lift} mm`);
370
+ return new Assembly({ geometry: outline, color: "#4A90E2", tags: ["cam"] });
356
371
  }
357
372
  ```
358
373
 
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
- # Abundance AI agent bridge
1
+ # Abundance® AI agent bridge
2
2
 
3
- Lets an AI agent on your computer, such as Claude, inspect and edit the [Abundance](https://abundance.maslowcnc.com) CAD project open in your browser. It's an MCP server: your AI app starts it, and your Abundance tab connects to it over a local, token-protected connection.
3
+ Lets an AI agent on your computer, such as Claude, inspect and edit the [Abundance®](https://abundance.maslowcnc.com) CAD project open in your browser. It's an MCP server: your AI app starts it, and your Abundance tab connects to it over a local, token-protected connection.
4
4
 
5
5
  It works with any AI app that can run commands on your computer and use MCP servers, such as Claude Code, Codex, GitHub Copilot in agent mode, and Cursor.
6
6