@twinfinity/printing 6.1.0-beta → 6.1.2-ci.30738-beta

package/templates/default-a4-portrait.json

@@ -3,20 +3,58 @@
   "id": "default-a4-portrait",
   "presets": {
     "includeClasses": {
-      "defaultBuilding": ["space", "walls", "windows", "doors", "beam", "columns", "stairs", "floor"]
+      "defaultBuilding": [
+        "space",
+        "walls",
+        "windows",
+        "doors",
+        "beam",
+        "columns",
+        "stairs",
+        "floor"
+      ]
     },
     "scales": {
-      "default": { "preferredScales": [2, 10, 25, 50, 100, 150, 250, 500, 1000, 2500] }
+      "default": {
+        "preferredScales": [
+          2,
+          10,
+          25,
+          50,
+          100,
+          150,
+          250,
+          500,
+          1000,
+          2500
+        ]
+      }
     }
   },
-  "page": { "widthMm": 210, "heightMm": 297, "marginMm": 5, "backgroundColor": "#ffffff" },
+  "page": {
+    "widthMm": 210,
+    "heightMm": 297,
+    "marginMm": 5,
+    "backgroundColor": "#ffffff"
+  },
   "styles": {
-    "body": { "fontFamily": "Arial", "fontSizeMm": 3.5, "color": "#000000" },
-    "spaceLabels": { "fontFamily": "Arial", "fontSizeMm": 5, "color": "#000000" }
+    "body": {
+      "fontFamily": "Arial",
+      "fontSizeMm": 3.5,
+      "color": "#000000"
+    },
+    "spaceLabels": {
+      "fontFamily": "Arial",
+      "fontSizeMm": 5,
+      "color": "#000000"
+    }
   },
-  "allowRemoteAssets": true,
-  "assets": [
-    { "id": "logo-main", "src": "https://twinfinity.com/theme-assets/logo.svg" }
+  "allowRemoteResources": true,
+  "resources": [
+    {
+      "id": "logo-main",
+      "src": "https://twinfinity.com/theme-assets/logo.svg"
+    }
   ],
   "elements": [
     {
@@ -26,7 +64,7 @@
       "yMm": 7,
       "widthMm": 40,
       "heightMm": 10,
-      "assetId": "logo-main",
+      "resourceId": "logo-main",
       "fit": "contain"
     },
     {
@@ -47,19 +85,38 @@
       "yMm": 20,
       "widthMm": 200,
       "heightMm": 250,
-      "includeClasses": { "preset": "defaultBuilding" },
+      "includeClasses": {
+        "preset": "defaultBuilding"
+      },
       "scaleMode": "fitAndRound",
       "scalePreset": "default",
       "align": "center",
-      "rotationDeg": 0,
-      "fills": [{ "class": "space", "fill": "sample", "fillOpacity": 0.35 }],
+      "fills": [
+        {
+          "class": "space",
+          "fill": "sample",
+          "fillOpacity": 0.35
+        }
+      ],
       "lineStyles": {
-        "default":       { "widthMm": 0.01, "color": "#1f2937" },
-        "visibleLines":  { "widthMm": 0.01, "color": "#1f2937" },
-        "hiddenLines":   { "widthMm": 0.005, "color": "#9ca3af", "dash": "4 2" },
-        "stairArrows":   { "widthMm": 0.015, "color": "#1f2937" }
-      },
-      "border": { "stroke": "none", "strokeWidthMm": 0.25 }
+        "default": {
+          "widthMm": 0.25,
+          "color": "#1f2937"
+        },
+        "visibleLines": {
+          "widthMm": 0.25,
+          "color": "#1f2937"
+        },
+        "hiddenLines": {
+          "widthMm": 0.13,
+          "color": "#9ca3af",
+          "dash": "4 2"
+        },
+        "stairArrows": {
+          "widthMm": 0.35,
+          "color": "#1f2937"
+        }
+      }
     },
     {
       "kind": "text",

package/templates/llm-authoring-guide.md

@@ -0,0 +1,247 @@
+# Layout-template authoring guide for AI assistants
+
+You are helping a user author a **layout template** for `@twinfinity/printing`
+— a JSON document that renders BIM building data (floor plans, sections) onto
+a print sheet as SVG/PDF. This file is a complete, self-contained
+specification: follow it and the output will validate and render. The
+machine-checkable truth is the sibling `template-schema.json`; when in doubt,
+that schema wins.
+
+## Your output contract
+
+- Produce **one valid JSON object** in a single code block. No comments, no
+  trailing commas, no placeholders — every value concrete and renderable.
+- Ask the user (or assume and say so): page size, what the sheet should show
+  (which floor / which spaces), and which property set holds their data
+  (`BIP` is the common Swedish default).
+- The user iterates in the **template-workbench** app, which shows render
+  warnings — mention that warnings (not silence) are how missing data shows
+  up.
+
+## Units — the #1 mistake
+
+- **Page space is millimetres**: every `xMm`/`yMm`/`widthMm`/`heightMm`/
+  `sizeMm` field, line widths (`widthMm`, `strokeWidthMm`) and `dash`
+  patterns (e.g. `"4 2"` = 4 mm dash, 2 mm gap).
+- **Model space is metres**: `cutHeight`, `planePosition`, `depth.above`/
+  `depth.below`, `expandBy`.
+- `cutHeight` must be a real storey cut height (floor elevation + ~1.2 m),
+  not 0 and not a guess — ask the user or tell them to adjust it in the
+  workbench (wrong height = empty or wrong-floor drawing with no error).
+
+## Root structure
+
+```json
+{
+  "id": "my-template",
+  "page": { "widthMm": 420, "heightMm": 297, "backgroundColor": "#ffffff" },
+  "styles": { "body": { "fontFamily": "Arial", "fontSizeMm": 3.5, "color": "#000000" } },
+  "variables": {},
+  "presets": {},
+  "resources": [],
+  "elements": []
+}
+```
+
+- `page` is required (`marginMm` only affects legend auto-placement).
+- `styles` is a name → text-style map: `{ fontFamily, fontSizeMm, fontWeight?,
+  color?, letterSpacingMm?, lineHeightMm? }`. **Every `textStyle` you
+  reference on an element MUST exist here** — a missing style silently skips
+  the element (with a warning).
+- `resources`: `[{ id, src }]` or `[{ id, content }]` (inline SVG). Remote
+  `https://` sources also need root `"allowRemoteResources": true`.
+- `presets`: reusable lists — `"includeClasses": { "name": ["walls", …] }`
+  and `"scales": { "name": { "preferredScales": [50, 100, …] } }`.
+- `variables`: declared parameters, each **must have a `default`**:
+  `{ "spacenumber": { "type": "string", "default": "6043", "label": "Space number" } }`.
+  Names must be **simple identifiers** (`[A-Za-z_][A-Za-z0-9_]*` — no dashes
+  or dots; they'd collide with the `{{vars.<name>}}` syntax). Reference
+  anywhere in element strings — including `where` values — as
+  `{{vars.spacenumber}}`. Types: `string | number | boolean | array`;
+  optional `format` (`color|email|url|date`), `enum`, `min`/`max`,
+  `pattern` drive the editing UI.
+
+## Elements (all have required `kind` + unique `id`; optional `zIndex`)
+
+### viewport — a cut of the model on the page
+Required: `xMm, yMm, widthMm, heightMm`, and in practice **`preferredScales`**
+(e.g. `[50, 100, 200, 400]`) or a `scalePreset` — without candidates the
+scale is NaN and the viewport is skipped.
+
+- Section definition (self-describing cut): plans use `"cutHeight": 3.0` +
+  `"depth": { "above": 0.5, "below": 1.5 }`; vertical sections use
+  `"planeNormal": [0,0,1]` (or `[1,0,0]`, negated variants) +
+  `"planePosition": 31` (metres along the normal). Never both.
+- **Prefer binding the cut to a variable** so the user can adjust it without
+  editing JSON: `"cutHeight": "{{vars.cutHeight}}"` + a number variable
+  `"cutHeight": { "type": "number", "default": 3, "step": 0.1, "label": "Cut height (m)" }`.
+  (Whole-value bindings keep the number type; only these two section fields
+  support it.)
+- `scaleMode`: `"fitAndRound"` (default — picks the nearest preferred scale
+  that fits) | `"fit"` (exact fill, odd denominators) | `"fixed"` (+
+  `fixedScaleDenom`).
+- `includeClasses`: what to draw — `["walls", "windows", "doors", "columns",
+  "stairs", "floor"]`, entries may also be `{ "class": "space", "where": {…} }`,
+  or `{ "preset": "name" }`. Omitted = everything (slow). Class names:
+  category form (`walls`, `space`) or IFC form (`IfcWall`, `IfcSpace`) —
+  interchangeable everywhere.
+- `lineStyles`: per-category styling `{ color?, widthMm?, dash?, enabled? }`
+  for `default, defaultVisibleLines, defaultHiddenLines, cutLines,
+  visibleLines, hiddenLines, silhouettes, featureEdges, stairArrows,
+  outlineVisible, outlineHidden`. `defaultVisibleLines` styles every
+  visible-class category (cutLines, visibleLines, silhouettes, featureEdges,
+  outlineVisible) and `defaultHiddenLines` every hidden-class one
+  (hiddenLines, outlineHidden) unless the specific category key overrides it;
+  `stairArrows` follows only `default`. Sensible print widths:
+  default/visible **0.25**, hidden **0.13** + `"dash": "4 2"`, heavy
+  **0.35** (mm on paper).
+- `stairArrows` (viewport-level, plans only): geometry of the generated stair
+  arrows — `{ "startMarker": "filled" | "open" | "none", "arrowhead":
+  "filled" | "outline" | "open", "lengthScale"?, "minLength"?, "maxLength"?,
+  "landingExtension"? }`. Defaults: filled circle at the bottom, filled
+  triangle at the top. Styling/hiding stays in `lineStyles.stairArrows`.
+- `fills`: `[{ "class": "space", "where": {…}, "fill": "#80c8b4" | "sample" |
+  "legend", "fillOpacity": 0.35, "matchClipFilter": true }]` — `"legend"`
+  takes colors from a legend with `assignColors` on the SAME viewport;
+  `matchClipFilter` restricts fills to items inside the clip.
+- `clip`: crop to matching items — `{ "class": "space", "where": {…}
+  (required), "expandBy": 1.5, "clipLabels": true, "color": "#000",
+  "widthMm": 0.7, "dash": "6 2", "opacity": 1 }`. The boundary is the matched
+  items' polygons expanded `expandBy` metres.
+- `highlight`: restyle matching items — `{ "class": …, "where": {…}
+  (required), "color": "#f00", "widthMm": 0.5, "fill": "#ff0",
+  "fillOpacity": 1, "intersectsViewport": "otherViewportId"? }`.
+- Highlight/clip classes are **exempt** from `includeClasses` — a highlighted
+  space still shows in a walls-only view.
+- `includeClasses` gates `fills` too: a fill rule for an excluded class draws
+  nothing. Exception: a rule with `"matchClipFilter": true` under an active
+  clip follows the clip's item set instead (the clipped apartment's space
+  fills render even when spaces are excluded from drawing).
+- `includeClasses` also scopes COMPUTATION: only the viewport's include
+  classes (plus its highlight/clip/fill/label/legend classes) take part in
+  section generation — excluded geometry neither draws nor occludes, and
+  costs nothing. Always list `includeClasses`; a viewport without them
+  computes against the entire model and is dramatically slower on big twins.
+- Include entries can carry per-class behavior flags (both default `true`):
+  `{ "class": "flow", "occludes": false, "classify": false }` —
+  `occludes: false` = the class hides nothing (a pipe run must not erase the
+  wall behind it); `classify: false` = its own lines skip hidden-line testing
+  and draw as-is. Use both for schematic MEP linework — it is also the single
+  biggest performance lever when including dense curved classes like pipes.
+- `border`: `{ "stroke": "#000", "strokeWidthMm": 0.25, "dash"? }`.
+- `northArrow`: `{ "resourceId": …, "sizeMm": 12 }` — anchored top-right.
+- Maximum **8 viewports** per template.
+
+### text
+`{ "kind": "text", "id", "xMm", "yMm", "text", "textStyle", "align"? }`.
+`xMm/yMm` anchor the **baseline**. Interpolations: `{{vars.*}}` and
+`{{viewport.<id>.scaleText}}` (renders e.g. `1:100`).
+
+### labels — per-item text at item centroids (PLAN viewports only)
+`{ "kind": "labels", "id", "viewport" (required), "text" (required),
+"textStyle", "class"?, "where"?, "align"?, "matchClipFilter"? }`.
+`text` interpolates item properties: `"{{BIP.spacename}} {{BIP.area | round:1}} m²"`.
+Do not attach labels to elevation viewports — they would be misplaced.
+
+### legend — table of matching items
+`{ "kind": "legend", "id", "viewport" (required), "columns" (required),
+"class"?, "where"?, "clipToViewport"?, "textStyle", "anchor":
+"top-right|top-left|bottom-right|bottom-left", "anchorPositionMm"?:
+{xMm,yMm}, "groupBy"?: "BIP.spacename", "assignColors"?: { "enabled": true,
+"palette": "auto" }, "showColorColumn"?, "summary"?: { "enabled": true,
+"label": "Total" }, "border"/"grid"/"header"?: { stroke, strokeWidthMm } }`.
+Columns: `[{ "id", "label", "property": "BIP.area", "format": { "digits": 1,
+"suffix": " m²" }, "align"?, "summary": true? }]` — `summary: true` columns
+are summed in the totals row. `groupBy` merges equal-valued rows (numeric
+columns summed). `assignColors` + a viewport fill `"fill": "legend"` =
+color-coded plan matching the legend swatches.
+
+### shapes — line / rect / circle / polyline / polygon (page mm)
+- `line`: `{ x1Mm, y1Mm, x2Mm, y2Mm, stroke?, strokeWidthMm?, dash? }`
+- `rect`: `{ xMm, yMm, widthMm, heightMm, stroke?, strokeWidthMm?, fill?, dash? }`
+- `circle`: `{ cxMm, cyMm, rMm (required), stroke?, strokeWidthMm?, fill?, dash? }`
+- `polyline`: `{ points: [{xMm,yMm}…] (≥2), stroke (required), strokeWidthMm (required), dash? }`
+- `polygon`: `{ points (≥3), stroke?, strokeWidthMm?, fill?, dash? }`
+
+### scaleBar
+`{ "kind": "scaleBar", "id", "xMm", "yMm", "maxLengthMm" (required),
+"segments": 10, "labelEvery": 2, "unit": "m", "stroke", "strokeWidthMm",
+"textStyle" (needed for the numbers), "viewport"? }`.
+
+### qr
+`{ "kind": "qr", "id", "xMm", "yMm", "sizeMm" (required), "role":
+"main"|"anchor"|"custom", "viewport"?, "anchorCorner"?, "dataTemplate"? }`.
+`main` (default) encodes a viewer link at the drawing location; `anchor` +
+`anchorCorner` are AR positioning markers; `custom` + `dataTemplate` is an
+arbitrary interpolated payload.
+
+### image
+`{ "kind": "image", "id", "xMm", "yMm", "widthMm", "heightMm", "resourceId"
+(required), "fit": "contain"|"cover"|"stretch" }`.
+
+### group
+`{ "kind": "group", "id", "children": […], "transform"?:
+{ translateXMm, translateYMm, rotateDeg, scaleX, scaleY }, "opacity"?,
+"clip"?: { "type": "rect", xMm, yMm, widthMm, heightMm } }`.
+Note: `labels`/`qr` children render as page-level overlays — the group's
+transform does not move them.
+
+## Where-conditions (used by clip/highlight/fills/labels/legend/includeClasses)
+
+`{ "BIP.spacetype": "ROOM" }` — key is `<PropertySet>.<property>`, value is
+a scalar (case-insensitive equality) or an array (any-of). Multiple keys AND
+together. Values may reference variables: `{ "BIP.spacenumber":
+"{{vars.spacenumber}}" }`.
+
+## Placeholder format filters
+
+Any `{{…}}` placeholder accepts `| round:N` (round, trim trailing zeros) or
+`| fixed:N` (exactly N decimals): `{{BIP.area | round:1}}` → `344.6`.
+Raw numeric properties are unrounded doubles — **always filter area-like
+values**.
+
+## Minimal valid skeleton
+
+```json
+{
+  "id": "basic-plan",
+  "page": { "widthMm": 420, "heightMm": 297 },
+  "styles": { "body": { "fontFamily": "Arial", "fontSizeMm": 3.5, "color": "#000000" } },
+  "elements": [
+    {
+      "kind": "viewport",
+      "id": "main",
+      "xMm": 5, "yMm": 15, "widthMm": 410, "heightMm": 260,
+      "cutHeight": 3, "depth": { "above": 0.5, "below": 1.5 },
+      "scaleMode": "fitAndRound", "preferredScales": [50, 100, 200, 400],
+      "includeClasses": ["walls", "windows", "doors", "columns", "stairs", "floor"],
+      "lineStyles": {
+        "default": { "widthMm": 0.25, "color": "#1f2937" },
+        "hiddenLines": { "widthMm": 0.13, "color": "#9ca3af", "dash": "4 2" }
+      }
+    },
+    { "kind": "text", "id": "scale", "xMm": 210, "yMm": 290, "textStyle": "body",
+      "align": "center", "text": "Scale: {{viewport.main.scaleText}}" }
+  ]
+}
+```
+
+For a full-featured example (variables, clip + expand, highlights, legend
+with colors + summary, labels, plan + section viewports) see the
+`hyresgastbilaga` template in the template-workbench gallery.
+
+## Checklist before you emit the JSON
+
+1. Valid JSON, unique element `id`s, ≤ 8 viewports.
+2. Every viewport has `preferredScales` (or `scalePreset`) and exactly one
+   section definition (`cutHeight` XOR `planeNormal`+`planePosition`).
+3. Every `textStyle` reference exists in `styles`; scaleBar has a
+   `textStyle` if it should show numbers.
+4. Every variable has a `default`; every `{{vars.*}}` is declared.
+5. `labels` only on plan viewports; numeric placeholders filtered
+   (`| round:1`).
+6. `fill: "legend"` only if a legend with `assignColors` targets the same
+   viewport.
+7. Every `resourceId` exists in `resources`; remote URLs have
+   `allowRemoteResources: true`.
+8. Units sanity: mm on the page, metres in the model.