Module grid 

The grid: the pitch, the snapping ladder, the screen-mapping constants every shape is measured against, and the bridge to the document’s own integer geometry.

This module is the scalar half — one axis at a time, no document type involved. The typed half converts whole points, vectors and rects; it is re-exported here so a call site reads one namespace.

Modules

bridge 🔒

The bridge between world pixels and the document’s own integer geometry, encoded once (the conversion table in docs/op-emitter-playbook.md). Each op emitter lands the rows it consumes through these, and the geometry layer reads them back through the same functions, so a rect drawn and a rect committed cannot disagree about where a cell is.

Structs

GridCell

A grid cell in the x,y spelling scripts use: the cell nearest a world position.

Constants

BLOCK_STROKE_WIDTH

Stroke width of a block/port outline, in world units. The single source of truth shared by the frame (draw_block_frame) and the pins that butt against it: a pin stub stops half this width outside the bbox edge so it meets the outline’s outer face instead of crossing into it.

BLOCK_TYPE_TEXT_SIZE

A block’s type label, drawn slightly smaller than its title.

DEFAULT_SCALE_FOR_NEW_VIEW

When a block is expanded into its own view, its boundary ports are laid out to mirror the parent’s pin arrangement, magnified by this factor so there is room to place interior child blocks between them.

GRID_SIZE

GROUP_SELECTION_PAD

Padding between a multi-selection’s contents and the group frame drawn around them, so the frame sits clear of the shapes’ own edges rather than hugging them.

HIT_RADIUS

Larger radius used for hit-testing interactive control points (ports, waypoints, resize handles). Intentionally bigger than PORT_RADIUS so targets are easier to click without changing how they look.

LINE_RADIUS

LOCK_HINT_SIZE

Side length of the passive “locked” padlock hint drawn in a selected locked block’s upper-right corner. Grid-relative and small so it reads as a hint.

MAX_LABEL_CHARS

Maximum length of a short on-canvas label (pin name and its two lines, block or area title, pin/block tag, route label). The rename editors enforce this so an accidental paste of a long string can’t break the canvas layout.

MAX_LOCATION_CHARS

Maximum length of a pin’s short “location” designator (its tag, e.g. “A1”). Tighter than MAX_LABEL_CHARS since it’s a compact label drawn above the stub.

MAX_TEXT_BOX_CHARS

Maximum length of a free-floating text box. Much larger than a label since a text box is a paragraph annotation, but still bounded so an accidental paste of a huge string can’t blow up the layout.

MOVE_HOVER_DISTANCE

PIN_PITCH

On-screen distance between consecutive pin slots.

PIN_PITCH_GRID

Vertical space a pin slot occupies, in grid units. Adjacent integer offsets are this many grid units apart.

PIN_TOP_MARGIN

Vertical margin from a block’s top edge to its first pin slot, and the matching clearance kept below the lowest slot. A whole number of grid cells, kept independent of PIN_PITCH so the pitch may be odd: the first pin sits this far down and pins are a full PIN_PITCH apart.

PORT_RADIUS

PORT_RENDER_HEIGHT

PORT_SUBTITLE_TEXT_SIZE

Subtitle (second line) of a pin/port name. Slightly smaller than the name.

PORT_TEXT_SIZE

RESIZE_SHIM

ROUTE_HIT_MARGIN

Generous margin for snapping a route to a pin: the cursor registers anywhere near the pin’s stub or its end, not just on the connection point. Kept just under half a PIN_PITCH so adjacent pins stay distinct.

ROUTE_TEXT_SIZE

SHIM

TAG_SHIM

Horizontal gap between a block/port edge and the start of its tag label.

TAG_TEXT_SIZE

TITLE_TEXT_SIZE

TYPE_SHIM_Y

Vertical nudge applied to the pin’s type label, which is otherwise centered one GRID_SIZE below the name. Zero keeps it centered exactly a grid cell below the stub; the wider pin pitch leaves room for the full gap.

Functions

artwork_rect

The inverse of screen_rect.

ceil_block_height

The smallest valid block height (see snap_block_height) that still holds height_px — the height counterpart of ceil_to_grid.

ceil_to_grid

The smallest whole grid width that still holds width_px. A resize floor has to be expressed on the lattice the drop snaps to, or the snap rounds back through it.

grid_i32

grid_point

A world-space gesture point onto the grid cell nearest it.

grid_pos

The world-space position of a grid cell’s corner, for the places that author canvas coordinates in whole cells.

grid_rect

The grid rect a two-corner gesture drew — either corner may be either end of the drag.

grid_size_ceil

A world-space extent as the whole cells that fully enclose it — the measured size a text box records.

grid_u32

grid_u32_ceil

A world-space extent in whole grid cells, rounded up so the cell count always fully encloses the extent, and clamped to at least one cell per axis.

grid_vec

A drag delta as the whole-cell offset the move commits at.

max_pin_slot

The largest pin slot that fits within a shape of the given height while keeping at least a PIN_TOP_MARGIN of clearance below it. Slot s sits at pin_offset_y = top + PIN_TOP_MARGIN + PIN_PITCH * s, so the lowest slot leaving a PIN_TOP_MARGIN above the bottom edge is floor((height - 2 * PIN_TOP_MARGIN) / PIN_PITCH). This is the bound that bounds-checks pin placement (see Block::new_pin_locations).

pin_offset_y

Screen y of pin slot offset within a shape whose top edge is at top. offset is a plain contiguous integer index; the pitch lives here, not in the stored value. The first slot sits a PIN_TOP_MARGIN below the top edge; each further slot is one PIN_PITCH down.

pin_slot

Pixel offset (slot * PIN_PITCH) → slot index.

pin_slot_row

pin_offset_y in whole grid cells: the row slot offset sits on in a shape whose top edge is at cell top. The document’s own geometry is integer, so a reader that stays in grid space never crosses through pixels to place a pin.

px

px_point

The world-space corner of a grid cell — the inverse of grid_point.

px_rect

The world-space rect a grid rect covers.

px_u

px_vec

The world-space vector a snapped grid_vec covers — what artwork riding a grid move (a block’s icon) translates by.

round_to_grid

round_to_pitch

Round a pixel offset to the nearest pin slot, in pixels.

screen_rect

Artwork geometry — free-floating images and block icons — is the one float rect the document stores: unsnapped, so a placed image keeps the aspect the drag gave it.

snap_block_height

A block’s height is constrained to 2 * PIN_TOP_MARGIN + h * PIN_PITCH for an unsigned h: a PIN_TOP_MARGIN above the top pin slot and below the bottom one, plus one PIN_PITCH per added slot. So a height-h block holds h + 1 pins, at offsets 0..=h (and max_pin_slot of this height is exactly h). This rounds a raw pixel height to the nearest such valid height, floored at the h = 0 minimum of 2 * PIN_TOP_MARGIN.

snap_block_height_cells

snap_block_height expressed in whole grid cells — the form a block’s inner.size.h stores. The minimum is 4 cells (2 * PIN_TOP_MARGIN) and each added slot adds PIN_PITCH_GRID cells: one of 4, 7, 10, ….

snap_offset

Grid-snap a translation delta (the vector form of snap_to_grid), used to round a drag offset to whole grid steps.

snap_rect

A world-space rect with both corners snapped to the grid.

snap_to_grid