feat(constructie): voeg doortekenbaar betonbalk-object toe

- hartlijn klik-voor-klik (zoals polylijn) met live balkvoorbeeld; Enter/
  dubbelklik/rechtermuisklik sluit af, Escape annuleert laatste punt en
  daarna de balk; tool blijft actief voor de volgende balk
- instelbare breedte in mm (schaalgebied-bewust, vaste 1:100-fallback) en
  lijnstijl doorgetrokken/gestippeld (NL-conventie: hartlijn streep-punt
  resp. doorgetrokken dun)
- verstek-joins op knikken met miter-limiet naar bevel; haakse eindkappen
  op vrije uiteinden
- automatische T-/hoekaansluiting tussen balken: eigen randen eindigen op
  de doelrand, geen eindkap op het aansluitvlak; doelbalk blijft in data
  ongewijzigd (opschonen puur op render- en AP-tijd)
- persistentie als /Polygon met /Vertices=omtrek en eigen appearance-
  stream; OPS_Hartlijn/OPS_BreedteMm/OPS_Lijnstijl maken de balk bij
  heropenen weer bewerkbaar, incl. verplaatsings-compensatie via OPS_BbRect
- eigenschappen-paneel (breedte/lijnstijl), palette-entry NL IFC Bouw,
  registraties in snap-engine, hit-test, bounds en spatial-index
- node-unittest scripts/test-betonbalk.mjs (13 tests, o.a. verstek 90/45,
  miter-limiet, T-aansluiting, eindkappen, round-trip)

Author: DutchSailor

docs/superpowers/specs/2026-07-25-betonbalk-design.md

@@ -0,0 +1,87 @@
+# Betonbalk — doortekenbaar balkobject in plattegrond (ontwerp)
+
+**Doel:** een constructieve betonbalk voor plattegronden die je als hartlijn
+doortekent (klik-klik-klik, zoals de polylijn), met een instelbare breedte.
+De twee randlijnen worden op elke knik in verstek gejoined, en aansluitingen
+tussen áparte balken worden automatisch opgeschoond (T- en hoekaansluiting).
+
+## Interactie
+
+1. Gereedschap `betonbalk` activeren vanuit het toolpalette (NL IFC Bouw).
+2. Elke klik voegt een hartlijnpunt toe; het segment-in-wording toont een
+   live voorbeeld met randen op de huidige breedte. Snap-engine doet mee
+   (eindpunten, haaks, polair) zoals bij de bestaande tekengereedschappen.
+3. Enter of dubbelklik sluit de balk af; Escape annuleert het laatste punt,
+   nogmaals Escape annuleert de balk.
+4. Grippunten op de hartlijnpunten; verslepen van een punt hertekent de
+   verstekken. Verplaatsen van de hele balk zoals elk object.
+
+## Datamodel
+
+Eigen annotatietype `betonbalk` (precedent: stavenreeks — eigen type, geen
+sjabloon, want sjablonen kennen geen klik-voor-klik-invoer):
+
+| Veld | Betekenis | Default |
+|---|---|---|
+| `points` | hartlijnpunten (app-ruimte) | — |
+| `breedteMm` | balkbreedte in mm, schaalgebied-bewust | 300 |
+| `lijnstijl` | `'doorgetrokken'` \| `'gestippeld'` | doorgetrokken |
+| `strokeColor`, `lineWidth`, `opacity` | zoals elders | |
+
+`realSizeMm`-gedrag: bij plaatsing in een schaalgebied wordt `breedteMm`
+omgerekend naar papierpunten via de plaatselijke schaal; buiten een
+schaalgebied geldt een vaste omrekening (1:100) zoals bij de staalprofielen.
+De hartlijn zelf volgt de klikpunten (die zijn al in papierruimte).
+
+## Geometrie (kern, testbaar in Node)
+
+Nieuw module `js/annotations/betonbalk.js` — één bron voor canvas én PDF-AP:
+
+- `beamOutline(points, halfWidthPt)` → de twee randpolylijnen, met
+  **verstek-join** per knik: randsegmenten van aangrenzende segmenten
+  worden gesneden; bij bijna-parallelle of zeer scherpe hoeken (miter-limiet
+  ~4× halve breedte) terugvallen op afgeschuinde (bevel) join zodat geen
+  extreme uitschieters ontstaan.
+- `trimAgainstBeams(outline, andereBalken)` → **inter-balk-join**: eindigt of
+  begint een hartlijn op (het lijf of een uiteinde van) een andere betonbalk
+  op dezelfde pagina (tolerantie: halve breedte van de dunste balk), dan:
+  - worden de eigen randlijnen doorgetrokken/afgekort tot de randlijn van de
+    doelbalk (T-aansluiting), en
+  - wordt op het aansluitvlak géén eindkap getekend, zodat de balken visueel
+    één geheel vormen.
+  De doelbalk zelf blijft ongewijzigd in data; het opschonen is puur
+  render-tijd (en AP-tijd), zodat verplaatsen/verwijderen altijd
+  omkeerbaar blijft en er geen verborgen mutaties in andere annotaties
+  ontstaan.
+- Eindkappen: haaks dichtgezet op vrije uiteinden.
+
+## Weergave
+
+- Twee randlijnen (kleur/lijndikte uit het object), hartlijn optioneel als
+  dunne streep-punt-lijn (stijl `'gestippeld'`: randen onderbroken — balk
+  boven het aanzichtvlak, NL-conventie; hartlijn dan doorgetrokken dun).
+- Geen vulling/arcering in v1.
+- Selectie: bestaande selectiehandvatten; hit-test op het balklijf
+  (polygon-contains op de outline).
+
+## Persistentie
+
+Opslaan als `/Polygon`-annotatie met `/Vertices` = outline (zodat externe
+programma's iets redelijks tonen en het object verplaatsbaar is), eigen
+appearance-stream met de exacte lijnvoering (incl. verstek en inter-balk-trim
+op het moment van opslaan), en privésleutels `OPS_Subtype: 'betonbalk'`,
+`OPS_Hartlijn` (punten), `OPS_BreedteMm`, `OPS_Lijnstijl` zodat de app hem
+bij heropenen weer als bewerkbare betonbalk laadt. Canonieke conventie:
+Matrix identiteit, BBox = Rect-maat, geen top-level rotatie.
+
+## Verificatie
+
+1. Node-unittest `scripts/test-betonbalk.mjs`: verstek op 90°- en 45°-knik
+   (exacte snijpunten), miter-limiet → bevel bij scherpe hoek, T-aansluiting
+   (rand eindigt op doelrand, geen eindkap), vrije einden wel kap,
+   round-trip hartlijn → outline → zelfde bij herberekening.
+2. Rig: balk met 3 knikken tekenen, breedte wijzigen in het paneel,
+   lijnstijl wisselen, tweede balk T-vormig laten aansluiten — screenshots.
+3. Opslaan naar kopie → heropenen: nog steeds bewerkbaar; pypdfium2-render
+   van de kopie toont dezelfde lijnvoering.
+4. Rooktest `a-drawing` groen; `npm run build` groen.

open-pdf-studio/js/annotations/betonbalk-scale.js

@@ -0,0 +1,80 @@
+// Schaalgebied-bewuste brug voor de betonbalk.
+//
+// De pure geometrie-module (betonbalk.js) mag GEEN app-state importeren; de
+// balkbreedte (breedteMm) moet toch de plaatselijke tekeningschaal volgen.
+// Deze dunne helper haalt de px-per-mm op de positie van de balk op en levert
+// de opts waarmee buildBetonbalk() de balk op werkelijke breedte tekent.
+//
+// De schaal wordt via de LICHTE bronnen opgevraagd (scale-region.js +
+// scale-bar.js, die alleen state/factory importeren) — bewust NIET via
+// symbols/real-size.js → annotations/measurement.js, want die keten trekt
+// rendering.js mee en vormt dan een import-cyclus met de modules die deze
+// helper aanroepen (rendering, geometry, spatial-index, selection-helpers).
+// Zelfde patroon als stavenreeks-scale.js.
+//
+// FALLBACK: buiten elk schaalgebied (en zonder kalibratie) geldt de vaste
+// 1:100-omrekening uit betonbalk.js (PX_PER_MM_1_100), zodat een balk op een
+// ongekalibreerde tekening een verdedigbare papierbreedte houdt.
+import { getScaleFromRegion } from './scale-region.js';
+import { getScaleForPoint } from './scale-bar.js';
+import { resolveBetonbalkParams, halfWidthFromMm } from './betonbalk.js';
+
+const UNIT_TO_MM = { mm: 1, cm: 10, m: 1000, in: 25.4, ft: 304.8 };
+
+// Referentiepunt van een balk: het midden van de bounding box van de
+// hartlijnpunten — valt altijd binnen (of het dichtst bij) een schaalgebied
+// dat de balk overlapt en is stabiel bij het bijtekenen van punten.
+function _anchor(ann) {
+  const pts = Array.isArray(ann?.points) ? ann.points : [];
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const p of pts) {
+    const x = Number(p?.x), y = Number(p?.y);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+  }
+  if (!Number.isFinite(minX)) return null;
+  return { x: (minX + maxX) / 2, y: (minY + maxY) / 2 };
+}
+
+/**
+ * Pagina-pixels per werkelijke millimeter op de positie van de balk.
+ * Prioriteit: schaalgebied → viewport/schaalbalk/doc-schaal. 0 = onbekend
+ * (dan valt halfWidthFromMm terug op de vaste 1:100-omrekening).
+ */
+export function betonbalkPxPerMm(ann) {
+  if (!ann || ann.page == null) return 0;
+  const a = _anchor(ann);
+  if (!a) return 0;
+  const ms = getScaleFromRegion(ann.page, a.x, a.y)
+    || getScaleForPoint(ann.page, a.x, a.y) || null;
+  if (!ms || !(ms.pixelsPerUnit > 0)) return 0;
+  const mmPerUnit = UNIT_TO_MM[ms.unit || 'mm'] || 1;
+  const k = ms.pixelsPerUnit / mmPerUnit;
+  return Number.isFinite(k) && k > 0 ? k : 0;
+}
+
+/** Halve balkbreedte in app-px, schaalgebied-bewust (fallback 1:100). */
+export function betonbalkHalfWidthPx(ann) {
+  const { breedteMm } = resolveBetonbalkParams(ann);
+  return halfWidthFromMm(breedteMm, betonbalkPxPerMm(ann));
+}
+
+/**
+ * opts voor buildBetonbalk(): eigen halve breedte + de andere betonbalken op
+ * dezelfde pagina (voor de inter-balk-join), elk met hun eigen schaalbewuste
+ * halve breedte. De doelbalken worden hier alleen GELEZEN — nooit gemuteerd.
+ */
+export function betonbalkBuildOpts(ann, annotations) {
+  const others = [];
+  for (const o of annotations || []) {
+    if (!o || o.type !== 'betonbalk' || o === ann) continue;
+    if (o.id != null && ann?.id != null && o.id === ann.id) continue;
+    if (o.page !== ann?.page) continue;
+    if (!Array.isArray(o.points) || o.points.length < 2) continue;
+    others.push({ points: o.points, halfWidth: betonbalkHalfWidthPx(o) });
+  }
+  return { halfWidth: betonbalkHalfWidthPx(ann), others };
+}