Add a Layers axis (3D point lattice)

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to Swift Loop. Versions follow SemVer; the [v0.x.y] anchor links to the GitHub release.
 
+## [Unreleased]
+
+### Added
+- **Layers (3D lattice).** The Iterations section gains a **Layers** count: the grid becomes a Columns × Rows × Layers cube of clones. Each cell's layer index `l` (plus `layers` and `tz`) is exposed to formulas, which own the projection to 2D — the 3D look lives in formulas and library presets, not a built-in projection. New **Cube** library preset shows it off (oblique projection, near layers larger/brighter). Defaults to 1, so existing patterns are byte-identical.
+
 ## [v0.2.0] — 2026-05-22
 
 ### Added

README.md

@@ -114,7 +114,7 @@ rotation = t * 360
 scale    = 0.4 + 0.6 * sin(t * PI)
 ```
 
-You can use: `i` (index), `n` (total), `c` (column), `r` (row), `cols`, `rows`, `t` (0 to 1), `tx`, `ty`, `w`, `h`, `seed`.
+You can use: `i` (index), `n` (total), `c` (column), `r` (row), `l` (layer), `cols`, `rows`, `layers`, `t` (0 to 1), `tx`, `ty`, `tz` (0 to 1 across layers), `w`, `h`, `seed`.
 
 Functions: `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `sqrt`, `pow`, `exp`, `log`, `abs`, `min`, `max`, `floor`, `ceil`, `round`, `mod`, `rand()`.
 

docs/controls.md

@@ -22,6 +22,8 @@ The first section. This is where you set the count.
 
 **Rows.** How many rows. 1 to 100. Leave at 1 for linear and radial patterns.
 
+**Layers.** Depth layers (Z), 1 to 50. The grid becomes a Columns × Rows × Layers cube of clones. On its own it just stacks more copies in place — the 3D look comes from a formula (or a library preset like **Cube**) that reads the layer index `l`. Leave at 1 for a flat 2D pattern.
+
 **Angle.** Degrees of per-cell rotation, applied to each clone's grid offset around the source center. Leave at 0 for straight lines and rectangular grids. Bump it 5 to 30 degrees and a line curls into a spiral, a grid swirls. Crank it past 90 to wrap the pattern back around on itself. Think "how much do successive cells lean".
 
 If you've applied a library pattern, you'll also see a little pill showing its name. Click it to jump back to the library and pick something else.

docs/formulas.md

@@ -46,11 +46,13 @@ In every formula, these variables are defined for you:
 
 `r` is the clone's row index.
 
-`cols` and `rows` are the grid dimensions.
+`l` is the clone's layer index — the depth (Z) axis. It's 0 unless you set Layers above 1, which turns the grid into a Columns × Rows × Layers cube. Use it to write your own 3D projection, or start from the **Cube** library preset.
+
+`cols`, `rows`, and `layers` are the grid dimensions (layers is the depth axis).
 
 `t` is the most useful one. It's `i / (n - 1)`, so it goes from 0 to 1 across the whole loop. If you want anything to happen "smoothly across the loop", multiply or scale by `t`.
 
-`tx` and `ty` are the same thing but for columns and rows. Smooth 0-to-1 horizontally and vertically.
+`tx` and `ty` are the same thing but for columns and rows. Smooth 0-to-1 horizontally and vertically. `tz` is the same across layers — 0 at the back, 1 at the front.
 
 `w` and `h` are the source shape's width and height in pixels. Use these for tight tiling.
 

docs/llm-pattern-guide.md

@@ -47,13 +47,14 @@ You, the LLM reading this, are helping a designer write a new library pattern. Y
 | `author` | recommended | `@handle` form. |
 | `cols` | yes | Integer 1 to 100. The default column count when the pattern loads. |
 | `rows` | yes | Integer 1 to 100. The default row count. Use `1` for linear or radial patterns. |
+| `layers` | optional | Integer 1 to 100. Depth layers (Z) — turns the grid into a Columns × Rows × Layers lattice. Each cell's `l`/`layers`/`tz` are exposed to formulas, which project it to 2D (there is no built-in projection). Default `1` (flat). See the `Cube` preset. |
 | `angle` | optional | Number, -360 to 360. Per-cell rotation in degrees applied to the grid offset around the source center, *after* the formulas compute `x` and `y`. Cell `i` is rotated by `angle * i`. Lets a pattern declare a spiral or swirl without folding the rotation into every formula. Default `0`. See "Using `angle`" below. |
 | `showFirst` | optional | Defaults to `true`. Set to `false` only for radial or spiral patterns where the `i=0` clone naturally lands away from the origin, and you want the source shape to stay visually centered. See "showFirst" below. |
 | `formulas` | yes | Object. Any subset of `x`, `y`, `rotation`, `scaleX`, `scaleY`, `opacity`. Omit properties that should stay at their default. |
 
 ### Existing tags (please reuse)
 
-`radial`, `grid`, `wave`, `curve`, `linear`, `random`, `chaos`, `spiral`, `polar`, `rotation`, `scale`, `tiling`, `organic`, `arc`, `physics`.
+`radial`, `grid`, `wave`, `curve`, `linear`, `random`, `chaos`, `spiral`, `polar`, `rotation`, `scale`, `tiling`, `organic`, `arc`, `physics`, `3d`.
 
 Only invent a new tag when nothing existing fits.
 
@@ -68,14 +69,17 @@ Every formula has access to these:
 | Var | Meaning | Range |
 |---|---|---|
 | `i` | Linear clone index | `0` to `n-1` |
-| `n` | Total clones | `cols * rows` |
+| `n` | Total clones | `cols * rows * layers` |
 | `c` | Column index | `0` to `cols-1` |
 | `r` | Row index | `0` to `rows-1` |
+| `l` | Layer index (depth/Z) | `0` to `layers-1` |
 | `cols` | Column count | from config |
 | `rows` | Row count | from config |
+| `layers` | Layer count | from config |
 | `t` | Normalized index | `i / (n-1)`, so `0` to `1` across the whole loop |
 | `tx` | Normalized column | `c / (cols-1)`, so `0` to `1` across columns |
 | `ty` | Normalized row | `r / (rows-1)`, so `0` to `1` across rows |
+| `tz` | Normalized layer | `l / (layers-1)`, so `0` to `1` from back to front |
 | `w` | Source shape width | px |
 | `h` | Source shape height | px |
 | `seed` | Random seed | integer, user-controllable |