@maslowcnc/abundance-bridge 0.1.4 → 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.
- package/AI_PROMPT_FOR_CODE_ATOMS.md +136 -121
- package/README.md +2 -2
- package/dist/index.js +775 -54
- package/package.json +2 -2
|
@@ -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
|
-
|
|
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
|
-
###
|
|
128
|
+
### 1. An Outline Computed from Inputs
|
|
164
129
|
|
|
165
130
|
```typescript
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
const
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
146
|
+
### 2. Revolving a Profile
|
|
184
147
|
|
|
185
148
|
```typescript
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
.
|
|
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.
|
|
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(
|
|
203
|
-
//
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
const
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
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(
|
|
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
|
-
*
|
|
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
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
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
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
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
|
-
|
|
346
|
-
|
|
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
|
|