Design Intuition

Appearance

Stipulations ​

The load-bearing rules the app is built on. Without these written down, work drifts. Anything new should be checked against this list. All entries are guesses pending review.

Coverage summary: all sixty-two rules are directly covered. Fifty-six are pinned by unit tests in src/lib/ts/tests/; six — the user-interface flows that need real mouse events and a real animation loop, plus the print pipeline that runs against the live DOM — are pinned by browser-driven tests under e2e/tests/. Coverage judgments are guesses pending review.

ALWAYS: Always update the authoritative count testing is done.

Format ​

Every stipulation carries three lines beneath the prose: a stable id (a short kebab-case slug), a test: pointer to the test that pins it, and a code: pointer to the source file and lines that prove it. The slug is what the test index references back.

The shape:

text
N. Plain English statement of the rule.
    - id: short-slug-name
    - test: [Test_File.test.ts](../../../../src/lib/ts/tests/Test_File.test.ts) test 1
    - code: [src/lib/ts/path/to/source.ts:42-57](../../../../src/lib/ts/path/to/source.ts)

A real example, fully written:

text
99. The world is made of blocks called smart objects (SO). Every SO has three directions {x, y, z}.
    - id: so-three-directions
    - test: [Data_Layout.test.ts](../../../../src/lib/ts/tests/Data_Layout.test.ts) "an SO has exactly three directions"
    - code: [src/lib/ts/runtime/Smart_Object.ts:9-14](../../../../src/lib/ts/runtime/Smart_Object.ts)

Smart objects ​

  1. The world is made of blocks called smart objects (SO). Every SO has three dimensions / axes
  2. Every SO is a block with eight corners, twelve edges between them, and six faces, all at right angles.
  3. Each axis has three attributes: start, length and end
  4. Two of these (start and end) are defined to be relative to parent's start (except root)
  5. Every SO has a visibility flag. An SO also has a flag that hides all of its children. Hidden blocks do not render but still participate in the rule pipeline (formulas, layout, save and load).

Children ​

  1. An SO sits inside at most one other block. Inside means its position numbers are written in its parent's frame.
  2. Moving a parent moves all of its children. Resizing a parent does not change a child's stored numbers.

Each attribute has several flavors ​

  1. plain number
  2. locked number
  3. a formula computes the number

Invariants ​

  1. Always and only one of them is called invariant. It uses a built-in formula
  2. If the value of an invariant is directly altered (set) by the user, this causes reverse propagation such that computing the formula results in the new value

Root ​

  1. has no parent
  2. end is always invariant
  3. start is always zero
  4. length can be locked

Formulas ​

  1. A formula attribute dynamically recomputes the value during propagation

  2. Propagation is initially triggered by some change, somewhere within the scope of its formula

  3. Setting a formula on an attribute clears the attribute's lock.

  4. When a formula uses a bare name to refer to another SO, the resolver starts at the formula's host SO and walks up the parent chain. At each level, it looks among the children of that level for an SO with the matching name. The first match wins.

  5. Formula references must not form a loop. If one attribute's formula references a second attribute, and the second attribute's formula references the first, the system refuses the loop rather than recomputing forever.

  6. A change to one attribute never quietly changes an attribute on another SO, except during propagation when that other SO has a formula referring to the an attribute of the first.

  7. A formula may reference the center of any direction using the bare letter c (host direction) or the axis-qualified form <direction>.c for a different direction. The center resolves to start-plus-end-over-two on the named direction, computed fresh on every read. Center references are read-only — reverse propagation refuses to write through a center, and a drag on an attribute whose formula reads a center posts the message "cannot drag a center" to the on-screen status strip. A formula on a start, end, or length attribute that references the same-direction same-SO center is rejected at the moment it is typed.

Formula trees ​

  1. The text of a formula is first broken into pieces — numbers, names, operators.
  2. The pieces are assembled into a small tree.
  3. Walking the tree computes the number from the formula.
  4. The same tree can be walked backwards: starting from a target number T, the system finds the one editable number E inside the tree whose value can be changed so as to make the formula compute T, and writes it to E.
  5. When a formula tree is walked backwards from a target number, exactly one unlocked attribute inside the tree receives the new value. If there is no unlocked attribute, the write is refused. There is never more than one writable target.

Propagation ​

  1. The value of a locked attribute must not be altered by propagation or reverse propagation

Repeaters ​

  1. A block can be marked as repeating along an axis called run. Its first child becomes the master copy. The rest are duplicates of that master.

  2. Each duplicate has a copy the master's stored numbers. run axis' start attribute is incremented using the run length

  3. A repeater's duplicates are not saved with the scene. The master is saved along with the repeater configuration; the duplicates are rebuilt from the master after load.

  4. A repeater carries its own spacing parameter, separate from the master block's run-direction length. Duplicates step along the run direction by the spacing, which need not equal the master's run-direction length.

  5. A fire block's size on the cross direction (the direction perpendicular to the run that is the tallest non-run side of the master) matches the master's size on that direction. The fire block is centered along that direction.

  6. A repeater block can also be told to fill the gaps between duplicates. Each filler is shaped to fit its gap and centered along the z axis.

Camera and projection ​

  1. The camera has two viewing modes — 3D mode (the normal view where things farther from the camera look smaller) and 2D mode (a flat view where things at different distances keep their real size). The choice is stored as a user preference outside the saved scene file.
  2. The world is shown through one camera. The camera defines how every point in the world corresponds to a spot on the screen or sheet of paper.
  3. The same definition runs the other way: any spot on the screen becomes a ray that starts at the camera and points into the world. Thus a given mouse location corresponds to a ray piercing straight into the scene. Whatever objects are encountered along that ray are identified in the hits 3D manager
  4. The drawing's screen silhouette is the smallest rectangle on the canvas that contains every painted (non-transparent) pixel of the picture. The painted pixels are what the printer captures; a silhouette derived from world-space corner projection cannot be trusted because the renderer clips lines and shapes at the camera's near plane and the canvas edges, which corner projection does not account for. If the canvas has no painted pixels, the silhouette is empty and no print transform is applied.

Error state ​

  1. An error reported on a formula stays on that formula until it is explicitly cleared.

Dragging ​

  1. A drag of a face of an SO is confined to that face's flat plane.

  2. The drag's screen motion becomes a ray into the world. The ray's hit point on the face's plane is the new position for the dragged point.

  3. That position is broken down along two directions defined by the face. Each part of the breakdown drives one editable number.

  4. A drag with a current selection edits that selection — moves a corner, an edge, or a face. A drag with nothing selected tumbles the camera around the topmost SO.

Saving and loading ​

  1. Saving and loading is a round trip: the world after a save-then-load matches the world before the save, after the load-time recompute runs.

Angles ​

  1. Each axis on an SO carries an angle. The block's overall rotation is the composition of those three angles, applied in a recorded order. The order matters — applying the same three angles in different orders produces different visible results.

Givens ​

  1. The user can define named values outside any block — call them ALPHA, BETA. Formulas can reference these names the same way they reference a block's attributes. The named values are saved with the scene and restored on load before any formula is recomputed.

Undo ​

  1. Undo brings the world back to exactly the state it was in before the last user action. Nothing is recomputed.
  2. After undo, redo brings the world forward to the state that was just undone. Like undo, redo restores stored values; nothing is recomputed during the restore.

Precision ​

  1. Stored position numbers are in millimeters. The user can type a value in inches or feet; the parser converts to millimeters before storage. Anything that reads a stored value receives millimeters.
  2. When the user drags an edge, corner, or face, the resulting new value is rounded to the current precision grid before it is written to storage.
  3. Changing the precision setting snaps every plain-number attribute's value in the scene to the new grid. Formula attributes are not touched.

Identity, persistence, and deletion ​

  1. Every SO carries a unique identifier that stays the same across save and load. Formulas, parent links, and the saved selection all point at SOs by this identifier; identifier stability is what lets save and load round-trip the world.
  2. Deleting an SO removes every descendant of that SO too. Every formula inside the deleted subtree is cleared, and every formula on a surviving SO that referenced any deleted SO is also cleared.

Editing lock ​

  1. There is an editing-lock toggle. While the lock is on, clicks on the canvas do nothing; the cursor stays as the open-grab-hand.

View-mode and tumbling ​

  1. Switching from the normal three-dimensional view to the flat view snaps the camera onto the front-most face of the topmost SO and saves the prior orientation. Switching back restores that saved orientation.
  2. When the rotation-snap toggle is on, releasing a tumble drag animates the orientation to the nearest face-aligned orientation. Turning the toggle off restores the orientation that was in place before the snap was last turned on.

Preferences layer ​

  1. A long list of user preferences persists across reloads through browser storage: chosen unit system, theme colors, the view mode, edge thickness, grid opacity, the precision level, the editing-lock toggle, which decorations are visible, which parts table tab is open, the parts hide list, which detail panels are showing, and several more. Preferences are not part of the saved scene file — they belong to the user, not the design.

Cutting a smart object in half ​

  1. The user can cut the selected smart object in half along its longest direction (measured by the plain stored length value). The original keeps the lower half; a new sibling appears as the upper half (named with a numeric-suffix bump matching the duplicate routine's naming) and becomes the selected part. The cut is refused — with a red message in the on-screen status strip and no change to the scene — when two directions are tied for longest, and when the selected part is root, a clone of a repeater, the template of a repeater, or any other part with children. Repeaters are an exception to the "has children" refusal: a cut on a repeater produces two repeaters, each carrying its own copy of the template; clones in each half regenerate from each half's own template on the next sync. On the cut direction, the formula on whichever attribute is the invariant is preserved unchanged on both halves; the two non-invariant attributes are rewritten so each half's length value equals half the original's old length on that direction. The exact rewrite depends on which attribute the invariant points at: when the invariant is on length, the original's end and the new sibling's start are altered to the half-way point; when the invariant is on start, the length on each half is divided in half (and the original's end is set to the half-way point); when the invariant is on end, the length on each half is divided in half (and the new sibling's start is set to the half-way point). "Half-way" means: alter the formula so its value evaluates to the half-way point; if the relevant attribute carries no formula, write the half-way value directly as a plain number. Both halves carry the original's formulas on the two directions that are NOT being cut, copied unchanged.

Printing ​

  1. There are three coordinate systems for printing: the world (in millimeters), the screen (in screen pixels), and the printed sheet of paper (in sheet-of-paper pixels).

  2. During printing, the browser delivers two notifications. The first is ignored. The second arrives after the printable paper area has settled. This is when we compute two things (1) the printable paper area (a rectangle in sheet-of-paper pixels) and (2) the screen silhouette (a rectangle in screen pixels -- see [drawing-silhouette]).

  3. From them we compute two more things: (3) a single scale factor that fits the silhouette inside the printable area along the limiting axis, and (4) a margin along the other axis that centers the result. These are applied to the screen image using css, which then is printed on the sheet of paper.

  4. During print, the drawing area's CSS box fills the printable area along both directions. The printable area is the printed sheet minus the default half-inch margin on every side, so the drawing area's CSS box equals (paper width minus one inch) by (paper height minus one inch). The fit math reads the drawing area's CSS dimensions and treats them as the printable-area dimensions; if the box is smaller along either direction the picture cannot be centered or scaled. The full chain from the top-most page container down to the drawing area must resolve to the printable-area dimensions, with no intermediate container collapsing to its content.

  5. During print, the body element's CSS height equals the printable page area's height. This anchors the chain of percentage-based heights from body down through the page layout to the drawing area, so heights along the chain resolve to concrete page-area numbers instead of collapsing to content height.

  6. During print, the printed sheet carries a default half-inch margin on every side. The drawing fills the printable area (sheet minus margin), so the printed picture is inset by half an inch from every edge of the paper. The margin is achieved via padding on the body element with border-box sizing, not via the page-area margin, so the inset applies uniformly across browsers.

  7. During print, every UI helper is suppressed — the background grid, the origin axes, the work-area indicator, the dashed wireframe of invisible objects, and the selection and hover dots. The renderer detects print mode and skips all of them so the printed sheet shows only the picture itself — no scene-orientation chrome carries onto the paper. The renderer also subscribes to print-media changes and flags the canvas out of date on every flip, so the next animation frame repaints under the new media. This pairs with rule 39 (silhouette is the bounding rectangle of painted pixels): with every helper suppressed, an empty scene paints nothing and the silhouette is empty.