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.
-
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.
-
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 nolbg(). Generic ops over per-feature specials. If signatures diverge, split the function. No mode flags whose options are only valid in some modes. -
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.
-
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. -
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.
- One Toolkit surface. Do not maintain a parallel
Toolkitinterface andTOOLKIT_BASEobject 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 (XYin,Vecout). No point class, and no third spelling. - An area is an input, not a type. There is no public
Regiontype and noregion()constructor; the engine's contours-plus-winding is an internal word. Area consumers (polygon,distanceTo,force.boundary, theboundsof 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,curvesfor chains (a property, rows in walk order),pointsfor positions. Every area consumer readscontours(), every chain consumercurves, every point consumerpoints; 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.lengthoncircle()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 anddistanceTo(circle(…))does not. The two doors aret.materialandt.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.adjacentandp.edgesfor 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.nearfor distance (nearest first), which is a different question from topology;rowsto hand back rows the sketch worked out;sourcefor the rows of the input a derived row came from. One meaning each, named:sel.edgesis the edges among the members andsel.edges.adjacent()the edges touching them. - Drawing stays explicit.
strokes,stroke,polygonanddotsinterpret 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. (dotis 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 — andt.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. NotoMaterial/toRegionaliases and no third spelling of either door. originis the pivot.rotateandscalepivot onorigin([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;rotateandscalepivot on it, andoriginoverrides.- 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.
- 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,testandbench), the studio typecheck, every docs example rendering, the docs ink oracle againstpackages/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 withpnpm 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 devfrom the isolated dev checkout does the same for the 5273 service.pnpm ship dev --quickskips 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 liveexample — 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 readDOC_PAGESin 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).