{
  "schema": "leumas.docs.page/1",
  "id": "pkg:@leumas/grids",
  "slug": "engines/grids",
  "kind": "capabilities",
  "bucket": "package",
  "title": "@leumas/grids",
  "name": "@leumas/grids",
  "eyebrow": null,
  "chip": null,
  "summary": "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...",
  "keywords": [
    "grids",
    "creategridsrouter",
    "conditional",
    "variable",
    "programming",
    "grids api",
    "leumas grids",
    "cells"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# @leumas/grids\n\nThe **3D programming grid/graph runtime**. A *grid* is a set of **layers** of **cells**; a **cell is\nan action** (code, endpoint, conditional, variable) — reusable across the whole system. Cells\nreference each other by `$Layer.Cell`; the engine resolves those refs, memoizes results,\ndetects cycles, and recommends the next cell to run.\n\n**Absorbs (DRY-consolidated from):** `Servers/z.Programming3` (v4, four core cell types). Ported the\ncore runtime only — dropped the bundled express server, pino logging, Postgres/pglite/File stores,\nnode-cron trigger engine, media/plugin-upload/plugin-generator/adapter-scan machinery, and the\nbundled React frontend.\n\n## Usage (in leumas-api)\n\n```js\nimport { createGridsRouter, createCollectionStore } from '@leumas/grids';\nimport { requirePassNode } from '@leumas/auth';\n\n// Persist grids in the dynamic `grids` collection over leumas.db (same connector everything uses).\nconst store = createCollectionStore(connector.get(), 'grids');\napp.use('/api/grids', createGridsRouter({ store, gate: requirePassNode() })); // gate = price/meter\n```\n\nWith no `store`, an in-memory store is used (dev / tests).\n\n## API (mounted at `/api/grids`)\n\n- `GET /` · `POST /` · `GET /:id` · `PUT /:id` · `DELETE /:id` — grid CRUD\n- `GET /cell-types` — the built-in cell catalogue (a cell = an action)\n- `POST /:id/execute` `{ entryCell:\"Layer.Ref\" }` — run a cell (+ its deps), returns `value`,\n  `results`, `debug`, and `suggestions` (what to run next)\n- `POST /:id/execute-many` `{ executeCells?, executeLayers? }` — run many\n- `POST /:id/suggest` `{ executed? }` — recommend next cells from an executed set\n\n## Grid shape\n\n```json\n{\n  \"id\": \"demo\",\n  \"name\": \"Demo\",\n  \"layers\": [\n    { \"name\": \"default\", \"cells\": {\n      \"A2\": { \"type\": \"variable\", \"specialConfig\": { \"value\": 5 } },\n      \"A3\": { \"type\": \"variable\", \"specialConfig\": { \"value\": 10 } },\n      \"A1\": { \"type\": \"code\", \"code\": \"$default.A2 + $default.A3\" }\n    } },\n    { \"name\": \"Layer 2\", \"cells\": {\n      \"B1\": { \"type\": \"code\", \"code\": \"$default.A1 * 2\" }\n    } }\n  ]\n}\n```\n\n## Core cell types\n\n- **code** — custom JavaScript (runs in a `node:vm` sandbox — no `process`/`require` reach), `$ref`-aware\n- **endpoint** — HTTP request builder (baseUrl/url/method/headers/query/body), all fields `$ref`-aware\n- **conditional** — evaluate a JS boolean and pick `trueResult` / `falseResult`\n- **variable** — a static value (numeric-looking strings coerce losslessly to numbers)\n\nExtend at the call site: `createGridsRouter({ adapters: { ...coreCellAdapters, myType } })`, where an\nadapter is `{ meta, run(cell, ctx) }` and `ctx` provides `replaceRefsInText`, `executeCell`,\n`layerName`, `fullCellId`, `debug`.\n",
  "source": {
    "path": "shared/engines/grids/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 2959,
    "hash": "fa35c6da01667f5b6d36913e3ae9688111930162"
  },
  "urls": {
    "html": "/p/engines/grids",
    "json": "/docs/engines/grids.json",
    "md": "/docs/engines/grids.md"
  },
  "links": {
    "composes": [],
    "usedBy": [
      "pkg:@leumas/lmx"
    ],
    "product": [
      "pkg:@leumas/studio"
    ],
    "howTo": [],
    "skills": [
      "skill:leumas-lmx",
      "skill:leumas-lmx#lmg"
    ]
  },
  "exports": null
}