# @leumas/grids

The 3D programming grid/graph runtime. A grid is layers of cells; a cell is an action (code, endpoint, conditional, variable). createGridsRouter → CRUD grids + a $ref-resolving, cycle-safe, memoizing...


The **3D programming grid/graph runtime**. A *grid* is a set of **layers** of **cells**; a **cell is
an action** (code, endpoint, conditional, variable) — reusable across the whole system. Cells
reference each other by `$Layer.Cell`; the engine resolves those refs, memoizes results,
detects cycles, and recommends the next cell to run.

**Absorbs (DRY-consolidated from):** `Servers/z.Programming3` (v4, four core cell types). Ported the
core runtime only — dropped the bundled express server, pino logging, Postgres/pglite/File stores,
node-cron trigger engine, media/plugin-upload/plugin-generator/adapter-scan machinery, and the
bundled React frontend.

## Usage (in leumas-api)

```js
import { createGridsRouter, createCollectionStore } from '@leumas/grids';
import { requirePassNode } from '@leumas/auth';

// Persist grids in the dynamic `grids` collection over leumas.db (same connector everything uses).
const store = createCollectionStore(connector.get(), 'grids');
app.use('/api/grids', createGridsRouter({ store, gate: requirePassNode() })); // gate = price/meter
```

With no `store`, an in-memory store is used (dev / tests).

## API (mounted at `/api/grids`)

- `GET /` · `POST /` · `GET /:id` · `PUT /:id` · `DELETE /:id` — grid CRUD
- `GET /cell-types` — the built-in cell catalogue (a cell = an action)
- `POST /:id/execute` `{ entryCell:"Layer.Ref" }` — run a cell (+ its deps), returns `value`,
  `results`, `debug`, and `suggestions` (what to run next)
- `POST /:id/execute-many` `{ executeCells?, executeLayers? }` — run many
- `POST /:id/suggest` `{ executed? }` — recommend next cells from an executed set

## Grid shape

```json
{
  "id": "demo",
  "name": "Demo",
  "layers": [
    { "name": "default", "cells": {
      "A2": { "type": "variable", "specialConfig": { "value": 5 } },
      "A3": { "type": "variable", "specialConfig": { "value": 10 } },
      "A1": { "type": "code", "code": "$default.A2 + $default.A3" }
    } },
    { "name": "Layer 2", "cells": {
      "B1": { "type": "code", "code": "$default.A1 * 2" }
    } }
  ]
}
```

## Core cell types

- **code** — custom JavaScript (runs in a `node:vm` sandbox — no `process`/`require` reach), `$ref`-aware
- **endpoint** — HTTP request builder (baseUrl/url/method/headers/query/body), all fields `$ref`-aware
- **conditional** — evaluate a JS boolean and pick `trueResult` / `falseResult`
- **variable** — a static value (numeric-looking strings coerce losslessly to numbers)

Extend at the call site: `createGridsRouter({ adapters: { ...coreCellAdapters, myType } })`, where an
adapter is `{ meta, run(cell, ctx) }` and `ctx` provides `replaceRefsInText`, `executeCell`,
`layerName`, `fullCellId`, `debug`.


---
Source: shared/engines/grids/README.md
Canonical: https://docs.leumas.tech/p/engines/grids