Skip to content

Latest commit

 

History

History
183 lines (170 loc) · 10.7 KB

CLAUDE.md

File metadata and controls

183 lines (170 loc) · 10.7 KB

occlude — project ethos

Occlude is a plotter-native creative-coding system: the pen is the medium, not a renderer of last resort. These are the artist's laws. Process notes and implementation details do not live here.

Design laws

  1. Occlusion is available, exact, and opt-in. The point of the project is that shapes can hide what is beneath them, and the engine computes exact visible strokes. Fill does not imply occlude: a texture that does not hide, and an opaque mask with no texture, are both first-class. When something is opaque, it hides — overlays do not erode the strokes underneath.

  2. Composable data, generic operations. Everything interesting is data you can hold, iterate, and feed to the next operation. Generators and graph nodes return plain, editable geometry (points, curves, meshes, chains), not sealed drawings. Named algorithms are recipes, not API surface: scatter(field).settle(n) is weighted LBG stippling — there is no lbg(). Generic ops over per-feature specials. If signatures diverge, split the function. No mode flags whose options are only valid in some modes.

  3. Same program, same seed, same ink. With a given build, a sketch plus seed is reproducible. Changing the code may change existing sketches; that is allowed. All randomness flows through seeded streams.

  4. One time model for plot duration. Anything that talks about how long a plot takes uses one estimator. Today that is estimatePlanMs. Do not grow a second clock.

  5. Preview matches the plot. What you see at nib width is as close as we can get to paper. Preview, export, and the machine agree.

Routing default, not a law: the engine does not duplicate edges to Eulerize a tour. Retrace is allowed when the artist asks for it.

Sub-nib judging, input snapping, dash phase, tour budgets, and field rasters are implementation numbers. They are not tenants.

API shape

  • One Toolkit surface. Do not maintain a parallel Toolkit interface and TOOLKIT_BASE object by hand — that dual model is a tax, not a feature.
  • Pure factories (shapes, fills, modifiers, units, map/ease, svg, voronoi/triangulate, and graph nodes that do not read seed or paper) are module imports. Anything that reads the seed or the resolved paper (rnd/noise/stream, bounds/grid/times, scatter) lives on the toolkit.
  • One point atom per job. {x, y} objects are points-as-things — identity and metadata ride on them. [x, y] pairs are anonymous vertices inside loops. Arithmetic takes either spelling and returns a fresh pair (XY in, Vec out). No point class, and no third spelling.
  • An area is an input, not a type. There is no public Region type and no region() constructor; the engine's contours-plus-winding is an internal word. Area consumers (polygon, distanceTo, force.boundary, the bounds of a point operation) accept loops, contour records, one face, a chain material, a shape, or a rect, and read closure and winding from the source. Several areas at once — a face collection — must name which one it means. t.within(x, area) is the one word for "only what lies inside": a field is bounded, a material is cut at the boundary, a point selection and a face collection are filtered. A shape area is lowered by the toolkit, never by a pure kernel.
  • One accessor protocol. A geometry value says what it is by what it answers: contours() for areas, curves for chains (a property, rows in walk order), points for positions. Every area consumer reads contours(), every chain consumer curves, every point consumer points; a consumer refuses a value that cannot answer, by name. The protocol is structural — no base class, no marker, nothing a value cannot already say honestly.
  • A thing you can read is a property, computed on first read. What a value has — its domains (g.points, g.edges, g.curves, g.faces), a row's relations and derived columns (p.adjacent, face.parent, face.source, p.u) — is a property, stored or derived, built the first time it is read and kept on the immutable value, never before. A call makes a new value or answers a question with arguments: g.move(…), sel.adjacent(), sel.components(), face.contours(). The rule is one rule for 2D and 3D.
  • A method stays in its world; a function crosses one. Material to material is a method (m.thicken, m.warp, m.move); shape to material, material to ink, geometry to field are functions (polygon, strokes, distanceTo). Anything that needs paper, units or the seed is on the toolkit whatever world it stays in. connect.* is the one kept exception: a family of recipes reads better with its prefix.
  • The frame rule. Value methods exist only on resolved data-world values (a material, a Selection, its rows, a Placement). Anything that needs the sketch frame — paper, units, a shape's own transform — is a toolkit function. group(p.placement(), …) is right; .along() or .length on circle() is not: t.material(circle(…)) first.
  • A shape is not geometry until the toolkit lowers it. A shape needs the paper, the units and its own transform before it has points, so t.distanceTo(circle(…)) works and distanceTo(circle(…)) does not. The two doors are t.material and t.sample; a pure kernel never lowers a shape, and a consumer handed one refuses by name and says which door to use.
  • Identity is internal; the value you hold is the name. Every row still has an identity — minted once, never reused, kept by the library for relations and source, and a split still retires the parent and keeps its lineage, which is how a face keeps its columns across a subdivided wall. But a sketch never names an id: a point or edge value (point(…), edge(…)), a row view or a selection you hold names its rows in any later state and in any write, and what is gone is skipped. Access is by rule (filter, near, pick, a relation), never by an id or a row number.
  • Relations speak the mesh's words. p.adjacent and p.edges for one vertex; sel.adjacent(), sel.connected(), sel.components() for a whole selection, the same three on points and on edges in 2D and 3D; points.near for distance (nearest first), which is a different question from topology; rows to hand back rows the sketch worked out; source for the rows of the input a derived row came from. One meaning each, named: sel.edges is the edges among the members and sel.edges.adjacent() the edges touching them.
  • Drawing stays explicit. strokes, stroke, polygon and dots interpret geometry as ink — along a contour, over an area, and as a tap at every point. A Material never draws itself, and no value carries a display translation that changes what is drawn. (dot is the vector product and stays.)
  • One conversion per meaning. Two doors, one contract each: t.material(shape, { tolerance? }) keeps the boundary's own vertices — a rectangle's four corners — and t.sample(shape, { count?, spacing?, tolerance? }) redistributes points along the boundary by arc length, which need not land on a corner. material(points) is the pure constructor. No toMaterial/toRegion aliases and no third spelling of either door.
  • origin is the pivot. rotate and scale pivot on origin ([x, y], or 'center' for the drawable's middle); on the user origin when it is unset. Scaling about the middle is an option, never a compensating translate. A value in space carries its own origin; rotate and scale pivot on it, and origin overrides.
  • Wasm protocol changes (strides, flags, export signatures) land on both sides in the same commit. Buffer strides are documented at the top of scene.rs.
  • Machine state lives in named MachineProfiles (server-side, like pens) — never re-grow flat settings.machine/ebb.

Working agreements

  • Evidence before diagnosis. Reproduce before theorizing; measure instead of estimating. The "stale tab" diagnosis may be played at most once per issue.
  • When patches stack, stop and rearchitect.
  • Definition of done: pnpm check — one line per gate: Rust tests, TS tests, the library typecheck (src, tools, test and bench), the studio typecheck, every docs example rendering, the docs ink oracle against packages/occlude/test/fixtures/docs-ink.json, the root build, and the wasm md5 match. Then commit/push. A DELIBERATE ink change re-saves that baseline in the same commit, with the reason in the message. The server serves dist per request, and reports its build id per request, so a REBUILD needs no restart; restart only for server.mjs / *-store.mjs changes (kill by PID — pkill aborts the shell). Ship with pnpm ship --push (ship.mjs): the Docker build runs those gates, restarts the studio, verifies the served build stamp, then pushes master and dev; pnpm ship dev from the isolated dev checkout does the same for the 5273 service. pnpm ship dev --quick skips the gates and the image (host build, copy dist into the dev container, verify the stamp; ~45 s) — for carrying on with a sketch, never for landing work.
  • Docs are the reference and the examples, with live sketches. The docs site (packages/occlude-docs, Blume) is docs/reference — one entry per word: the signature spliced from the types, a paragraph and a ts live example — and docs/examples, one page per drawing. Every feature gets its entry; explanation, signature and live sketch stay together, with no separate guide layer. The checker and the ink oracle read DOC_PAGES in packages/occlude/src/docsExamples.ts; a page on the site is in that list too. The checker also reports ink outside the drawable.
  • Copyleft neighbors: saxi (AGPL), EggBot (GPL), Spicker stippling (LGPL), Marlin/Klipper (GPL) — ideas, protocol facts, and papers only, NEVER code. Keep the README credits table current.
  • Oracle: pnpm --filter occlude plotstats <sketch> --seed 42 (church.ts) before/after any toolpath-affecting change. Golden fixtures regenerate only deliberately (UPDATE_GOLDEN=1).
  • Rejected on principle (don't resurrect): veil/partial occlusion (use decimate fields on the content), raster-based coverage, channels-as-FieldFn, drawing images, branded algorithm names, mode-flag mega-functions, and the fills-redesign's obsoleted machinery (mailbox/SAB field sampling, COOP/COEP isolation, mid-pipeline wasm→JS fill callback, presence-mask NaN rasters, bleed margins — each obsoleted by the worker-owned runtime and the two-pass pipeline, which get field values in JS before the second wasm call; recorded with the rest of the refusals in docs/notes.md).