bimdown-cli 0.4.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/README.md +24 -3
  2. package/dist/chunk-4SKM4RHY.js +142 -0
  3. package/dist/chunk-4SKM4RHY.js.map +1 -0
  4. package/dist/chunk-4YHVOWS4.js +255 -0
  5. package/dist/chunk-4YHVOWS4.js.map +1 -0
  6. package/dist/chunk-AYAXRYGP.js +2129 -0
  7. package/dist/chunk-AYAXRYGP.js.map +1 -0
  8. package/dist/chunk-EC5MR5ZH.js +648 -0
  9. package/dist/chunk-EC5MR5ZH.js.map +1 -0
  10. package/dist/chunk-HS3PO2LB.js +487 -0
  11. package/dist/chunk-HS3PO2LB.js.map +1 -0
  12. package/dist/chunk-IQJA3EFO.js +179 -0
  13. package/dist/chunk-IQJA3EFO.js.map +1 -0
  14. package/dist/chunk-JY6KWRDB.js +80 -0
  15. package/dist/chunk-JY6KWRDB.js.map +1 -0
  16. package/dist/chunk-KWSGJUMZ.js +2501 -0
  17. package/dist/chunk-KWSGJUMZ.js.map +1 -0
  18. package/dist/chunk-LWYIPR64.js +35 -0
  19. package/dist/chunk-LWYIPR64.js.map +1 -0
  20. package/dist/chunk-OBY3UYCO.js +44 -0
  21. package/dist/chunk-OBY3UYCO.js.map +1 -0
  22. package/dist/chunk-XC6WHJRL.js +29 -0
  23. package/dist/chunk-XC6WHJRL.js.map +1 -0
  24. package/dist/chunk-XQU52JKB.js +187 -0
  25. package/dist/chunk-XQU52JKB.js.map +1 -0
  26. package/dist/clash-load-D3LNQR6G.js +941 -0
  27. package/dist/clash-load-D3LNQR6G.js.map +1 -0
  28. package/dist/cli.js +306 -3377
  29. package/dist/cli.js.map +1 -1
  30. package/dist/dehydrate-ZHAGOI7Q.js +90 -0
  31. package/dist/dehydrate-ZHAGOI7Q.js.map +1 -0
  32. package/dist/diff-T2KOK2WR.js +89 -0
  33. package/dist/diff-T2KOK2WR.js.map +1 -0
  34. package/dist/engine-2TPWJVEQ.js +12 -0
  35. package/dist/engine-2TPWJVEQ.js.map +1 -0
  36. package/dist/hydrate-V24H7IF3.js +673 -0
  37. package/dist/hydrate-V24H7IF3.js.map +1 -0
  38. package/dist/import-ifc-RCZSXDA6.js +5324 -0
  39. package/dist/import-ifc-RCZSXDA6.js.map +1 -0
  40. package/dist/info-QC7YXWNX.js +92 -0
  41. package/dist/info-QC7YXWNX.js.map +1 -0
  42. package/dist/init-VWDML3UC.js +112 -0
  43. package/dist/init-VWDML3UC.js.map +1 -0
  44. package/dist/lib.d.ts +427 -44
  45. package/dist/lib.js +6482 -225
  46. package/dist/lib.js.map +1 -1
  47. package/dist/mep-W4HJI363.js +25 -0
  48. package/dist/mep-W4HJI363.js.map +1 -0
  49. package/dist/merge-ESOPDSA5.js +413 -0
  50. package/dist/merge-ESOPDSA5.js.map +1 -0
  51. package/dist/publish-3TAXQCUV.js +80 -0
  52. package/dist/publish-3TAXQCUV.js.map +1 -0
  53. package/dist/render-UEWYHPN6.js +1807 -0
  54. package/dist/render-UEWYHPN6.js.map +1 -0
  55. package/dist/resolve-topology-AQ2RO3W3.js +338 -0
  56. package/dist/resolve-topology-AQ2RO3W3.js.map +1 -0
  57. package/dist/spec/csv-schema/annotation/dimension.yaml +77 -0
  58. package/dist/spec/csv-schema/annotation/tag.yaml +44 -0
  59. package/dist/spec/csv-schema/annotation/text_note.yaml +52 -0
  60. package/dist/spec/csv-schema/architecture/ceiling.yaml +8 -1
  61. package/dist/spec/csv-schema/architecture/column.yaml +5 -1
  62. package/dist/spec/csv-schema/architecture/curtain_wall.yaml +45 -5
  63. package/dist/spec/csv-schema/architecture/door.yaml +5 -0
  64. package/dist/spec/csv-schema/architecture/furniture.yaml +28 -0
  65. package/dist/spec/csv-schema/architecture/opening.yaml +27 -6
  66. package/dist/spec/csv-schema/architecture/railing.yaml +35 -0
  67. package/dist/spec/csv-schema/architecture/roof.yaml +34 -1
  68. package/dist/spec/csv-schema/architecture/slab.yaml +19 -0
  69. package/dist/spec/csv-schema/architecture/space.yaml +11 -1
  70. package/dist/spec/csv-schema/architecture/stair.yaml +49 -0
  71. package/dist/spec/csv-schema/architecture/stair_landing.yaml +36 -0
  72. package/dist/spec/csv-schema/architecture/stair_run.yaml +31 -0
  73. package/dist/spec/csv-schema/architecture/wall.yaml +14 -1
  74. package/dist/spec/csv-schema/architecture/window.yaml +19 -0
  75. package/dist/spec/csv-schema/base/element.yaml +20 -11
  76. package/dist/spec/csv-schema/base/furniture_params.yaml +60 -0
  77. package/dist/spec/csv-schema/base/hosted_element.yaml +10 -2
  78. package/dist/spec/csv-schema/base/mep_connectable.yaml +23 -0
  79. package/dist/spec/csv-schema/base/mep_design.yaml +24 -0
  80. package/dist/spec/csv-schema/base/mep_insulated.yaml +9 -0
  81. package/dist/spec/csv-schema/base/mep_system_tag.yaml +12 -0
  82. package/dist/spec/csv-schema/base/point_element.yaml +1 -0
  83. package/dist/spec/csv-schema/base/section_profile.yaml +5 -0
  84. package/dist/spec/csv-schema/base/spatial_line_element.yaml +4 -2
  85. package/dist/spec/csv-schema/base/structural_section_profile.yaml +50 -0
  86. package/dist/spec/csv-schema/base/vertical_span.yaml +5 -4
  87. package/dist/spec/csv-schema/base/wall_bounded.yaml +21 -0
  88. package/dist/spec/csv-schema/grid.yaml +5 -0
  89. package/dist/spec/csv-schema/mep/cable_tray.yaml +10 -3
  90. package/dist/spec/csv-schema/mep/circuit.yaml +70 -0
  91. package/dist/spec/csv-schema/mep/conduit.yaml +2 -2
  92. package/dist/spec/csv-schema/mep/connector.yaml +112 -0
  93. package/dist/spec/csv-schema/mep/duct.yaml +10 -3
  94. package/dist/spec/csv-schema/mep/equipment.yaml +18 -1
  95. package/dist/spec/csv-schema/mep/mep_node.yaml +91 -2
  96. package/dist/spec/csv-schema/mep/mep_system.yaml +21 -0
  97. package/dist/spec/csv-schema/mep/pipe.yaml +27 -3
  98. package/dist/spec/csv-schema/mep/terminal.yaml +22 -1
  99. package/dist/spec/csv-schema/model_group.yaml +40 -0
  100. package/dist/spec/csv-schema/sheet/sheet.yaml +50 -0
  101. package/dist/spec/csv-schema/sheet/sheet_viewport.yaml +86 -0
  102. package/dist/spec/csv-schema/structure/beam.yaml +29 -1
  103. package/dist/spec/csv-schema/structure/beam_system.yaml +29 -0
  104. package/dist/spec/csv-schema/structure/brace.yaml +24 -1
  105. package/dist/spec/csv-schema/structure/foundation.yaml +40 -7
  106. package/dist/spec/csv-schema/structure/structure_column.yaml +19 -1
  107. package/dist/spec/csv-schema/structure/structure_slab.yaml +32 -0
  108. package/dist/spec/csv-schema/structure/structure_wall.yaml +22 -0
  109. package/dist/spec/csv-schema/types/beam_type.yaml +11 -0
  110. package/dist/spec/csv-schema/types/ceiling_type.yaml +6 -0
  111. package/dist/spec/csv-schema/types/column_type.yaml +12 -0
  112. package/dist/spec/csv-schema/types/curtain_wall_type.yaml +32 -0
  113. package/dist/spec/csv-schema/types/door_type.yaml +27 -0
  114. package/dist/spec/csv-schema/types/element_type.yaml +21 -0
  115. package/dist/spec/csv-schema/types/fenestration.yaml +16 -0
  116. package/dist/spec/csv-schema/types/foundation_type.yaml +36 -0
  117. package/dist/spec/csv-schema/types/furniture_type.yaml +11 -0
  118. package/dist/spec/csv-schema/types/layered_type.yaml +13 -0
  119. package/dist/spec/csv-schema/types/railing_type.yaml +40 -0
  120. package/dist/spec/csv-schema/types/roof_type.yaml +7 -0
  121. package/dist/spec/csv-schema/types/slab_type.yaml +9 -0
  122. package/dist/spec/csv-schema/types/type_layer.yaml +47 -0
  123. package/dist/spec/csv-schema/types/wall_type.yaml +6 -0
  124. package/dist/spec/csv-schema/types/window_type.yaml +31 -0
  125. package/dist/spec/csv-schema/underlay.yaml +73 -0
  126. package/dist/spec/csv-schema/view.yaml +36 -0
  127. package/dist/spec/duckdb-strategy.md +4 -3
  128. package/dist/spec/geojson-schema/readme.md +380 -0
  129. package/dist/spec/mep-port-conventions.md +190 -0
  130. package/dist/spec/migration-guide.md +1 -1
  131. package/dist/spec/project_metadata.schema.yaml +52 -4
  132. package/dist/spec/readme.md +356 -97
  133. package/dist/spec/starter-types/global/beam_type.csv +5 -0
  134. package/dist/spec/starter-types/global/ceiling_type.csv +3 -0
  135. package/dist/spec/starter-types/global/column_type.csv +5 -0
  136. package/dist/spec/starter-types/global/curtain_wall_type.csv +2 -0
  137. package/dist/spec/starter-types/global/door_type.csv +6 -0
  138. package/dist/spec/starter-types/global/foundation_type.csv +7 -0
  139. package/dist/spec/starter-types/global/furniture_type.csv +11 -0
  140. package/dist/spec/starter-types/global/railing_type.csv +5 -0
  141. package/dist/spec/starter-types/global/roof_type.csv +3 -0
  142. package/dist/spec/starter-types/global/slab_type.csv +4 -0
  143. package/dist/spec/starter-types/global/type_layer.csv +40 -0
  144. package/dist/spec/starter-types/global/wall_type.csv +8 -0
  145. package/dist/spec/starter-types/global/window_type.csv +6 -0
  146. package/dist/spec/svg-schema/readme.md +47 -1
  147. package/package.json +6 -3
  148. package/dist/spec/csv-schema/base/mep_connected_segment.yaml +0 -17
  149. package/dist/spec/csv-schema/base/mep_system.yaml +0 -7
@@ -2,7 +2,13 @@
2
2
 
3
3
  This directory defines the **BimDown data format** — a "Minimum Viable Building" representation optimized for AI-native building design and bidirectional sync with BIM tools (Revit).
4
4
 
5
- BimDown uses **CSV for attributes** and **SVG for 2D geometry**, both human-readable and AI-friendly. A CLI tool with DuckDB provides relational query and auto-sync capabilities.
5
+ BimDown uses **CSV for attributes** and a **geometry layer** that may be encoded as either **SVG** or **GeoJSON** — both human-readable and AI-friendly. The two encodings are interchangeable and fully supported; a project declares which it uses via `format_version` (`1` = SVG, `2` = GeoJSON). GeoJSON adds 2D **and** 3D coordinates and is the default for new projects; SVG is 2D-only and was the original encoding. A CLI tool with DuckDB provides relational query and auto-sync capabilities over either.
6
+
7
+ > Geometry storage specs (canonical forms, AI input flexibility, build-time normalization):
8
+ > - **[geojson-schema/readme.md](geojson-schema/readme.md)** — GeoJSON encoding (`format_version: 2`, default)
9
+ > - **[svg-schema/readme.md](svg-schema/readme.md)** — SVG encoding (`format_version: 1`)
10
+ >
11
+ > The CSV attribute layer below is identical for both encodings.
6
12
 
7
13
  ---
8
14
 
@@ -10,108 +16,192 @@ BimDown uses **CSV for attributes** and **SVG for 2D geometry**, both human-read
10
16
 
11
17
  ```text
12
18
  {project-id}/
13
- ├── project_metadata.json # Format version, project name, units, source
19
+ ├── project_metadata.json # format_version, project name, units, source
14
20
  ├── global/
15
- │ ├── level.csv # Floor level definitions
16
- │ ├── grid.csv # Structural grid lines
17
- │ ├── wall.csv / wall.svg # Multi-story walls (span > 1 level above)
18
- │ ├── stair.csv / stair.svg # Multi-story stairs
19
- │ └── ... # Any element spanning > 1 level above
21
+ │ ├── level.csv # floor level definitions (with elevations)
22
+ │ ├── grid.csv # structural grid lines
23
+ │ ├── wall_type.csv, door_type.csv, …, type_layer.csv # element types (optional)
24
+ │ ├── view.csv # saved section views (optional)
25
+ │ ├── sheet.csv, sheet_viewport.csv # drawing sheets and the views placed on them (optional)
26
+ │ ├── dimension.csv, text_note.csv # annotations on sections / elevations (view_id, optional)
27
+ │ ├── wall.csv / wall.geojson # multi-story walls (span > 1 level above)
28
+ │ ├── stair.csv / stair.geojson # multi-story stairs
29
+ │ ├── pipe.csv / pipe.geojson # vertical risers
30
+ │ └── ... # any element genuinely spanning > 1 level
20
31
  ├── 1F/
21
- │ ├── wall.csv / wall.svg
22
- │ ├── column.csv / column.svg
23
- │ ├── slab.csv / slab.svg
24
- │ ├── door.csv # No SVG (hosted, parametric position)
25
- │ ├── window.csv # No SVG (hosted, parametric position)
26
- │ ├── space.csv # No SVG (seed point only)
32
+ │ ├── wall.csv / wall.geojson
33
+ │ ├── column.csv / column.geojson
34
+ │ ├── slab.csv / slab.geojson
35
+ │ ├── door.csv # no geometry file (hosted)
36
+ │ ├── window.csv # no geometry file (hosted)
37
+ │ ├── space.csv # no geometry file (seed point in CSV)
27
38
  │ └── ...
28
39
  ├── 2F/
29
40
  │ └── ...
30
- └── _IdMap.csv # UUID ↔ short ID mapping (Revit round-trip)
41
+ ├── underlays/ # optional: tracing references (png/jpg/webp/pdf/dxf), see global/underlay.csv
42
+ ├── _IdMap.csv # UUID ↔ short ID mapping (Revit round-trip)
43
+ └── LICENSE.txt # optional licence / attribution note (also README, NOTICE, CREDITS; .txt/.md)
31
44
  ```
32
45
 
46
+ > The geometry files above are shown as `.geojson` (`format_version: 2`). In an SVG project (`format_version: 1`) the same elements use `.svg` files instead (`wall.svg`, `column.svg`, …); CSV files are unchanged. See [svg-schema/readme.md](svg-schema/readme.md).
47
+
33
48
  ---
34
49
 
35
50
  ## Partitioning Rules (Level vs Global)
36
51
 
37
- All elements belong to a **base level** (their `level_id`).
52
+ All elements belong to a **base level** (their `base_level_id`).
38
53
 
39
- - **Level directory**: Elements whose vertical extent stays within one level above their base (e.g. a 1F wall with `top_level_id` = 2F is normal single-story — goes in `1F/`).
40
- - **Global directory**: Elements that span **more than one level above** their base (e.g. a 1F wall with `top_level_id` = 3F). Also: `level.csv`, `grid.csv`.
41
- - **Elements without `vertical_span`**: Always go in their level directory.
54
+ - **`base_level_id` always equals the containing directory's level** — no cross-directory references. To express a multi-level element, place it in `global/`.
55
+ - **Level directory** (e.g. `1F/`, `2F/`): elements whose vertical extent stays within one level above their base.
56
+ - **Global directory** (`global/`): elements that span **more than one level above** their base (multi-story walls, vertical pipe risers, etc.), plus `level.csv`, `grid.csv`, `view.csv`, the sheets and the annotations drawn on sections / elevations.
57
+ - **Spatial elements** (beams, ramps, ducts, etc.) should be placed in the level directory they primarily belong to. Only truly cross-level instances go in `global/`.
58
+
59
+ Consequence: editing or rendering one level view requires loading at most **two directories** — the current level and `global/`.
42
60
 
43
61
  ---
44
62
 
45
63
  ## Schema Overview
46
64
 
65
+ The **GeoJSON type** column below maps directly to an SVG element in the SVG encoding: `Point` → `<rect>`/`<circle>`, `LineString` → `<path>`, `Polygon` → `<polygon>`. A `3D LineString` (spatial element) becomes a 2D `<path>` plus `start_z`/`end_z` columns in CSV. See [svg-schema/readme.md §6](svg-schema/readme.md).
66
+
47
67
  ### Global Tables
48
68
 
49
- | Table | SVG | Description |
50
- |---------|-----|-------------|
69
+ | Table | Geometry file | Description |
70
+ |---------|---------------|-------------|
51
71
  | `level` | No | Floor levels by elevation |
52
- | `grid` | No | Structural/reference grid lines |
72
+ | `grid` | No | Structural/reference grid lines (inline coords in CSV) |
73
+ | `*_type`, `type_layer` | No | Element types and their layers — see [Element Types](#element-types) |
74
+ | `view` | No | Saved section views: `view_type=section`, plan line `start_*`→`end_*` (looks to its left), optional far-clip `depth` |
53
75
 
54
76
  ### Architecture
55
77
 
56
- | Table | Geometry | SVG | Description |
57
- |------------------|-----------------|---------|-------------|
58
- | `wall` | Line | `<path>` | Architectural wall with thickness and vertical span |
59
- | `column` | Point | `<rect>`/`<circle>` | Architectural column with section profile |
60
- | `slab` | Polygon | `<polygon>` | Floor/roof/finish slab |
61
- | `space` | Seed point | `<polygon>` (computed) | Named space/room (boundary computed by `build` from walls, curtain walls, room separators) |
62
- | `door` | Hosted on wall | No | Door with operation type |
63
- | `window` | Hosted on wall | No | Window with dimensions |
64
- | `opening` | Hosted | Conditional | Wall opening (no SVG) or slab opening (`<rect>`/`<polygon>`) |
65
- | `stair` | Spatial line | `<path>` | Stair run with vertical span |
66
- | `ramp` | Spatial line | `<path>` | Accessibility ramp |
67
- | `railing` | Spatial line | `<path>` | Railing along path |
68
- | `curtain_wall` | Line | `<path>` | Curtain wall with grid parameters |
69
- | `ceiling` | Polygon | `<polygon>` | Ceiling surface |
70
- | `roof` | Polygon | `<polygon>` | Roof surface |
71
- | `room_separator` | Line | `<path>` | Invisible boundary line for room separation |
78
+ | Table | Geometry | GeoJSON type | Description |
79
+ |------------------|------------------|-----------------|-------------|
80
+ | `wall` | Line | `LineString` 2D | Architectural wall with thickness and vertical span |
81
+ | `column` | Point | `Point` 2D | Architectural column with section profile |
82
+ | `slab` | Polygon | `Polygon` 2D | Floor/roof/finish slab |
83
+ | `space` | Seed point | (CSV `x`,`y`) | Named space/room (boundary computed by `build` from walls, curtain walls, room separators) |
84
+ | `door` | Hosted on wall | No geometry file | Door with operation type |
85
+ | `window` | Hosted on wall | No geometry file | Window with dimensions |
86
+ | `opening` | Hosted | Conditional | Wall opening (no geometry file) or slab opening (`Polygon`) |
87
+ | `stair` | Spatial line | `LineString` 3D | Stair (its own first run) with vertical span; optional multi-storey repetition |
88
+ | `stair_run` | Spatial line | `LineString` 3D | Further flight of a stair (`host_id` → stair); curved with a GeoJSON `arc` |
89
+ | `stair_landing` | Polygon | `Polygon` 2D | Landing between runs (`host_id` → stair), top at `base_offset`; `step_count` > 0 = winders |
90
+ | `ramp` | Spatial line | `LineString` 3D | Accessibility ramp |
91
+ | `railing` | Spatial line | Conditional | Sketched railing (`LineString` 3D, optionally on a slab via `host_id`) or stair railing (`host_id` → stair + `side`, no geometry) |
92
+ | `curtain_wall` | Line | `LineString` 2D | Curtain wall with grid parameters |
93
+ | `ceiling` | Polygon | `Polygon` 2D | Ceiling surface |
94
+ | `roof` | Polygon | `Polygon` 2D | Roof surface |
95
+ | `room_separator` | Line | `LineString` 2D | Invisible boundary line for room separation |
96
+ | `furniture` | Point | `Point` 2D | Built-in parametric component: furniture, casework, appliances without ports, toilet partitions, cars / parking, planting, people, placeholders (`family`, `variant`, `size_x` × `size_y` × `height`, `mirror`) |
72
97
 
73
98
  ### Structure
74
99
 
75
- | Table | Geometry | SVG | Description |
76
- |--------------------|------------|---------|-------------|
77
- | `structure_wall` | Line | `<path>` | Structural wall |
78
- | `structure_column` | Point | `<rect>`/`<circle>` | Structural column |
79
- | `structure_slab` | Polygon | `<polygon>` | Structural slab |
80
- | `beam` | Spatial line | `<path>` | Structural beam |
81
- | `brace` | Spatial line | `<path>` | Structural brace |
82
- | `foundation` | Mixed | `<rect>`/`<circle>`, `<path>`, or `<polygon>` | Unified foundation (geometry determines form) |
100
+ | Table | Geometry | GeoJSON type | Description |
101
+ |--------------------|------------|-----------------|-------------|
102
+ | `structure_wall` | Line | `LineString` 2D | Structural wall |
103
+ | `structure_column` | Point | `Point` 2D | Structural column |
104
+ | `structure_slab` | Polygon | `Polygon` 2D | Structural slab |
105
+ | `beam` | Spatial line | `LineString` 3D | Structural beam |
106
+ | `brace` | Spatial line | `LineString` 3D | Structural brace |
107
+ | `foundation` | Mixed | `Point`/`LineString`/`Polygon` 2D | Unified foundation (geometry type chooses form) |
108
+ | `beam_system` | Polygon | `Polygon` 2D | Associative infill beams across a bay: `spacing`, `direction`, `type_id`; its beams carry `beam_system_id` and are regenerated when it changes |
83
109
 
84
110
  ### MEP
85
111
 
86
- | Table | Geometry | SVG | Description |
87
- |--------------|-------------|---------|-------------|
88
- | `duct` | Spatial line | `<path>` | HVAC duct (endpoints from connectors) |
89
- | `pipe` | Spatial line | `<path>` | Plumbing/process pipe (endpoints from connectors) |
90
- | `cable_tray` | Spatial line | `<path>` | Electrical cable tray (endpoints from connectors) |
91
- | `conduit` | Spatial line | `<path>` | Electrical conduit (endpoints from connectors) |
92
- | `equipment` | Point | `<rect>`/`<circle>` | MEP equipment (AHU, chiller, pump...) |
93
- | `terminal` | Point | `<rect>`/`<circle>` | MEP terminal (diffuser, outlet...) |
94
- | `mep_node` | Point | `<rect>`/`<circle>` | Topology node (fitting/accessory in Revit) |
112
+ | Table | Geometry | GeoJSON type | Description |
113
+ |--------------|--------------|-----------------|-------------|
114
+ | `duct` | Spatial line | `LineString` 3D | HVAC duct (endpoints from connectors) |
115
+ | `pipe` | Spatial line | `LineString` 3D | Plumbing/process pipe |
116
+ | `cable_tray` | Spatial line | `LineString` 3D | Electrical cable tray |
117
+ | `conduit` | Spatial line | `LineString` 3D | Electrical conduit |
118
+ | `equipment` | Point | `Point` 3D | MEP equipment (AHU, chiller, pump...) |
119
+ | `terminal` | Point | `Point` 3D | MEP terminal (diffuser, outlet...) |
120
+ | `mep_node` | Point | `Point` 3D | Topology node (fitting/accessory in Revit) |
121
+ | `connector` | None (CSV) | — | Connection port on equipment/terminal/mep_node — host-local offset + outward direction, cross-section, flow direction, domain. Curves reference it via `from`/`to` (`host_id:name`). CSV-only. |
122
+ | `circuit` | None (CSV) | — | Electrical branch circuit hosted on a panel (`host_id`); devices join through `circuit_id`. `phase` / `power_factor` give the current (I = P / (U·cosφ), ×√3 three-phase); `cable_size` + `cable_trays` count toward tray fill. CSV-only. |
123
+
124
+ ### Annotation
125
+
126
+ Plan annotations, CSV only, in level directories. They reference model elements by id, so they follow edits; see [csv-schema/annotation/](csv-schema/annotation/). Dimensions and text notes drawn on a section or elevation live in `global/` with `view_id` (a `view.csv` section id, or `north` / `south` / `east` / `west`) and view coordinates: x along the view as seen, y = absolute elevation.
127
+
128
+ Annotation sizes are **paper sizes**: text, ticks and tag boxes are millimetres on the sheet, drawn at `mm × scale / 1000` metres in the model (2.5 mm = 0.25 m at 1:100, 0.5 m at 1:200), so a note reads the same at every scale. `text_note.paper_size` stores the height in mm; the legacy `size` (project units, fixed) is used only when `paper_size` is empty.
129
+
130
+ | Table | Geometry file | Description |
131
+ |--------------|---------------|-------------|
132
+ | `dimension` | No (CSV points) | Linear dimension: two measured points, each optionally stuck to an element (`start_ref` / `end_ref`: `w-1`, `w-1:left`, `w-1:end`, `d-1:start`, …), a `direction` (empty = aligned) and an `offset` for the dimension line |
133
+ | `text_note` | No (CSV point) | Free text at `x`,`y` with `paper_size` (mm) and `rotation` |
134
+ | `tag` | No (CSV point) | Label of one element (`host_id`): door/window mark, room name + number + area, number/name/type/size; empty `x`,`y` = default spot that follows the host |
135
+
136
+ ### Model groups
137
+
138
+ A repeated unit (an apartment, a toilet core, a bay of columns) placed several times. Each placement is a `model_group` row in the level directory (CSV only): `name`, origin `x`,`y`, `rotation` (degrees CCW) and `mirrored`. Its members are ordinary elements of the same level with `group_id` = the row id, stored as usual (absolute plan coordinates), so anything that ignores groups still reads them. Instances with the same `name` are copies of one group: their members are identical in the group's local frame (plan = origin + rotate(rotation) · (mirrored ? flip-Y : identity) · local). Editing one instance in an editor rebuilds the others; `bimdown build` warns when instances of one group differ.
139
+
140
+ | Table | Geometry file | Description |
141
+ |---------------|---------------|-------------|
142
+ | `model_group` | No (CSV point) | Group instance: `name`, `x`, `y`, `rotation`, `mirrored`; members carry `group_id` |
143
+
144
+ ### Pinned elements
145
+
146
+ `pinned = "true"` (every element, and grids) marks an element editors must not move, rotate or reshape (properties stay editable). Empty = not pinned.
95
147
 
96
148
  ### Fallback
97
149
 
98
- | Table | SVG | Description |
99
- |--------|-----|-------------|
100
- | `mesh` | No | Generic 3D model (GLB) for elements without parametric schema |
150
+ | Table | Geometry file | Description |
151
+ |--------|---------------|-------------|
152
+ | `mesh` | No (GLB) | Generic 3D model for elements without parametric schema |
153
+
154
+ `furniture` covers what used to need a GLB: a closed list of library families (`bimdown schema furniture` prints them with variants and default sizes). Plan symbols and low-poly 3D massing are generated from the family and its parameters, so files stay small and editable; `mesh_file` on a row overrides the 3D only. Local frame: `size_x` along X, `size_y` along Y, **+Y is the back** (the side against a wall), `rotation` CCW in GeoJSON properties. Empty sizes take the family / variant default. Exporters map families to IFC4 `IfcFurniture` (DESK, CHAIR, TABLE, BED, SOFA, SHELF, FILECABINET), `IfcElectricAppliance` (appliances), `IfcFurnishingElement`, `IfcGeographicElement` (trees) or `IfcBuildingElementProxy` (cars, parking, people, generic). Plumbing fixtures with pipe connections are MEP `terminal`s, not furniture.
155
+
156
+ ### Underlays (reference drawings)
157
+
158
+ | Table | Geometry file | Description |
159
+ |------------|---------------|-------------|
160
+ | `underlay` | No (file in `underlays/`) | `global/underlay.csv`: an image, PDF page or DXF placed under one level for tracing |
161
+
162
+ An underlay row places `file` (under `underlays/`) on `level_id`: plan = `(x, y)` + rotate(`rotation`°) · (`scale` · local), where local is image pixels (origin bottom-left), PDF points or DXF drawing units; `scale` is project units per local unit. `opacity`, `visible`, `locked`, `page` (PDF) and `hidden_layers` (DXF, `;`-separated) are display settings. Underlays are not building elements: `build`, `render`, `query` and the exports ignore them; `validate` checks only that the file exists.
163
+
164
+ ### Sheets (drawings for print)
165
+
166
+ | Table | Geometry file | Description |
167
+ |-------|---------------|-------------|
168
+ | `sheet` | No | `global/sheet.csv`: one sheet: `number` (unique, e.g. A-101), `name`, `paper` (A0–A4 landscape), revision fields, `issue_date`, `drawn_by`, `checked_by` |
169
+ | `sheet_viewport` | No | `global/sheet_viewport.csv`: a view on a sheet: `view_type` plan (`level_id`, `discipline`), section (`view_id`), elevation (`view_id` = direction), schedule (`schedule`) or legend, at `scale` (100 = 1:100), centred at `x`,`y` mm from the paper's bottom-left |
170
+
171
+ The title block shows `project_name`, `project_number`, `client` and `address` from `project_metadata.json`, the sheet number / name, date, revision and the scale of each viewport. Sheets are not building elements: `build` and `render` ignore them (`query` reads them like any table).
172
+
173
+ ---
174
+
175
+ ## Storage Layout (CSV vs GeoJSON vs computed)
176
+
177
+ | Class | Storage | Examples |
178
+ |---|---|---|
179
+ | Scalar attributes, enum values, FKs | **CSV** | `material`, `thickness`, `size_x`, `size_y`, `shape`, `function`, `operation`, `host_id`, `position`, `base_level_id`, `top_level_id` |
180
+ | Geometry coordinates | **GeoJSON `geometry`** | LineString points, Polygon rings, Point coord; 2D for level-anchored, 3D for spatial |
181
+ | Numeric geometry hints | **GeoJSON `properties`** | `base_offset`, `top_offset`, `arc`, `rotation` |
182
+ | Derived spatial data | **Computed (DuckDB hydrate)** | `length`, `area`, `net_area` (spaces), `height`, `volume` (structural tables), `start_x/y/z`, `end_x/y/z`, `x`, `y`, `points`, `bbox_*`, `level_id` |
183
+
184
+ YAML schemas use the following markers:
185
+
186
+ - **`required: true`** — Semantic source of truth in CSV. AI writes directly. If geometry contradicts, CSV wins.
187
+ - **`computed: true`** — Spatial derivative, never stored. DuckDB hydrate produces it at query time.
188
+ - **`storage: geojson_property`** — Lives in GeoJSON Feature `properties`, not CSV. Source of truth in GeoJSON. **In the SVG encoding**, the same hint is expressed intrinsically by SVG (`rotation` → `transform`, `arc` → path `A` command) or, where SVG cannot (Z offsets, spatial Z), moves to a CSV column. See [svg-schema/readme.md §6](svg-schema/readme.md).
189
+ - **(default)** — Stored in CSV (identical in both encodings).
101
190
 
102
191
  ---
103
192
 
104
- ## Schema Field Metadata
193
+ ## Z-Axis Handling Summary
105
194
 
106
- ### `required: true`
195
+ Two modes (see [geojson-schema/readme.md §4](geojson-schema/readme.md) for details):
107
196
 
108
- Semantic **source of truth**. Written directly in `.csv` by AI. If SVG geometry contradicts a required field, the CLI uses the CSV value to auto-correct SVG on sync.
197
+ 1. **Level-anchored** (wall, column, slab, ceiling, roof, curtain_wall): geometry coords are 2D; Z lives in CSV (`base_level_id`, `top_level_id`) + GeoJSON properties (`base_offset`, `top_offset`). Resilient to level elevation changes.
198
+ 2. **Spatial** (beam, brace, stair, ramp, railing, duct, pipe, cable_tray, conduit): geometry coords are 3D with absolute Z; CSV still carries `base_level_id` for partitioning but no Z numerics.
109
199
 
110
- ### `computed: true`
200
+ Changing a level's `elevation` moves everything on that level with it: level-anchored elements follow by themselves; the absolute Z in that level's spatial GeoJSON (beams, ducts, pipes, stairs, equipment, …) must be shifted by the same amount (editors rewrite it). To keep the storey heights above, shift the higher levels (and their spatial Z) too.
111
201
 
112
- Spatial derivatives extracted from SVG at runtime. **Not stored in CSV**. The DuckDB CLI engine hydrates these as virtual columns during queries.
202
+ This split keeps numeric Z arithmetic out of the LLM's hands for the bulk of building elements while preserving full 3D fidelity for elements that genuinely need it.
113
203
 
114
- **Rule**: Elements with SVG have their geometry fields as `computed`. Elements without SVG (door, window, space, grid, level) have geometry fields as `required`.
204
+ In the **SVG encoding** (2D-only), the same two modes apply but Z always lives in CSV: level-anchored `base_offset`/`top_offset` and spatial `start_z`/`end_z` are CSV columns. See [svg-schema/readme.md §6](svg-schema/readme.md).
115
205
 
116
206
  ---
117
207
 
@@ -119,18 +209,23 @@ Spatial derivatives extracted from SVG at runtime. **Not stored in CSV**. The Du
119
209
 
120
210
  | Mixin | Key Fields |
121
211
  |------------------------------|------------|
122
- | `element` | `id` (short ID, PK), `number`, `base_offset`, `mesh_file` |
123
- | `line_element` | `start_x/y`, `end_x/y`, `length` (all computed from SVG `<path>`) |
124
- | `spatial_line_element` | extends `line_element` + `start_z`, `end_z` (required, CSV) |
125
- | `point_element` | `x`, `y`, `rotation` (all computed from SVG) |
126
- | `polygon_element` | `points`, `area` (all computed from SVG) |
127
- | `hosted_element` | `host_id` (reference), `position` (distance in meters from host start) |
128
- | `vertical_span` | `top_level_id`, `top_offset`, `height` (computed) |
129
- | `materialized` | `material` (enum: concrete, steel, wood, clt, glass, aluminum, brick, stone, gypsum, insulation, copper, pvc, ceramic, fiber_cement, composite) |
130
- | `section_profile` | `shape` (rect/round), `size_x`, `size_y` |
131
- | `structural_section_profile` | `shape` (rect/round/i/t/l/c/cross), `size_x`, `size_y` |
132
- | `mep_system` | `system_type` (string, e.g. "CHWS", "SA", "DW") |
133
- | `mep_connected_segment` | `start_node_id`, `end_node_id` (auto-resolved by CLI) |
212
+ | `element` | `id` (short ID, PK), `number`, `base_offset` (GeoJSON property), `mesh_file`, `group_id` (model group), `pinned` |
213
+ | `line_element` | `start_x/y`, `end_x/y`, `length` (all computed) |
214
+ | `spatial_line_element` | extends `line_element` + `start_z`, `end_z` (computed from 3D coords) |
215
+ | `point_element` | `x`, `y` (computed from Point coords), `rotation` (computed from GeoJSON property) |
216
+ | `polygon_element` | `points`, `area` (computed) |
217
+ | `hosted_element` | `host_id` (CSV reference), `position` (CSV float, meters along host start) |
218
+ | `vertical_span` | `base_level_id`, `top_level_id` (CSV FKs), `top_offset` (GeoJSON property), `height` (computed) |
219
+ | `materialized` | `material` (CSV enum) |
220
+ | `wall_bounded` | `boundary_walls`, `boundary_face`, `boundary_offset` (CSV; slab, structure_slab, roof, ceiling) |
221
+ | `section_profile` | `shape` (CSV enum rect/round), `size_x`, `size_y` (CSV) |
222
+ | `structural_section_profile` | `shape` (CSV enum rect/round/i/t/l/c/cross), `size_x`, `size_y` (CSV) |
223
+ | `mep_system` | `system_type` (CSV string) |
224
+ | `mep_connectable` | `from`, `to` (CSV; port-ref `host_id:port_name` or bare `host_id`, auto-resolved by CLI) |
225
+ | `mep_design` | `flow` (L/s), `load` (W), `circuit_id` (equipment, terminal; not lengths) |
226
+ | `mep_insulated` | `insulation_thickness` (duct, pipe) |
227
+
228
+ **Room area.** A space's boundary is derived along wall centre lines (`space.geojson`, written by `bimdown build`), so its `area` is the gross, centre-line area. `net_area` is the area at the wall finish faces: each boundary edge moves inward by half the thickness of the wall it lies on (room separators and edges on no wall stay put) — Revit's default room area. Drawings, room tags, schedules and IFC `NetFloorArea` use `net_area`; `area` is kept for backward compatibility (and as IFC `GrossFloorArea`).
134
229
 
135
230
  ---
136
231
 
@@ -150,6 +245,8 @@ All elements use prefixed short IDs: `{prefix}-{n}`. Counters are 1-based per ta
150
245
  | `window` | `wn` | `wn-1` |
151
246
  | `opening` | `op` | `op-1` |
152
247
  | `stair` | `st` | `st-1` |
248
+ | `stair_run` | `sr` | `sr-1` |
249
+ | `stair_landing` | `sl_land` | `sl_land-1` |
153
250
  | `ramp` | `rp` | `rp-1` |
154
251
  | `railing` | `rl` | `rl-1` |
155
252
  | `curtain_wall` | `cw` | `cw-1` |
@@ -169,7 +266,23 @@ All elements use prefixed short IDs: `{prefix}-{n}`. Counters are 1-based per ta
169
266
  | `equipment` | `eq` | `eq-1` |
170
267
  | `terminal` | `tm` | `tm-1` |
171
268
  | `mep_node` | `mn` | `mn-1` |
269
+ | `connector` | `cn` | `cn-1` |
270
+ | `circuit` | `ci` | `ci-1` |
172
271
  | `mesh` | `ms` | `ms-1` |
272
+ | `wall_type` / `slab_type` / `roof_type` / `ceiling_type` | `wt` / `slt` / `rot` / `clt` | `wt-ext-concrete-eps` |
273
+ | `door_type` / `window_type` / `curtain_wall_type` | `dt` / `wnt` / `cwt` | `dt-single-900` |
274
+ | `column_type` / `beam_type` | `colt` / `bmt` | `bmt-steel-ipe-300` |
275
+ | `foundation_type` | `fdt` | `fdt-pad-2000` |
276
+ | `furniture_type` | `fut` | `fut-desk-1600` |
277
+ | `railing_type` | `rlt` | `rlt-steel-1000` |
278
+ | `type_layer` | `tl` | `tl-1` |
279
+ | `dimension` | `dm` | `dm-1` |
280
+ | `text_note` | `tx` | `tx-1` |
281
+ | `tag` | `tg` | `tg-1` |
282
+ | `underlay` | `ul` | `ul-1` |
283
+ | `furniture` | `fu` | `fu-1` |
284
+ | `sheet` / `sheet_viewport` | `sh` / `vp` | `sh-1`, `vp-1` |
285
+ | `model_group` | `mg` | `mg-1` |
173
286
 
174
287
  Round-trip fidelity with Revit is maintained via a `BimDown_Id` shared parameter stored on each Revit element, and `_IdMap.csv` at the project root.
175
288
 
@@ -184,64 +297,210 @@ Architectural and structural elements are fully independent. `structure_column`,
184
297
  ### Section Profiles
185
298
 
186
299
  - Architecture columns use `section_profile` (rect/round).
187
- - Structural elements use `structural_section_profile` with engineering shapes (I, T, L, C, cross).
300
+ - Structural elements use `structural_section_profile` with engineering shapes (I, T, L, C, cross, `rect_hollow` RHS/SHS, `round_hollow` CHS; `thickness` = wall thickness; `open_web` K / LH bar joists: chords solid, web open), optional `root_radius` (root fillet / RHS outer corner) and `designation` (catalogue name such as HEA 300, W14X90, CHS 219.1x8, used as the IFC ProfileName). Computed `weight` (kg) on columns / beams / braces = volume × material density (steel 7850 kg/m³); beams / braces use their computed `cut_length` (to the faces of the columns / girders they frame into, as the editor schedules).
301
+ - Section attributes (`shape`, `size_x`, `size_y`) live in CSV. Point-element orientation (`rotation`) lives in GeoJSON `properties` if non-zero.
302
+
303
+ ### Two Geometry Encodings (SVG and GeoJSON)
188
304
 
189
- ### SVG as AI-Native Geometry Storage
305
+ The geometry layer is **not** used for visualization in either encoding — it is structured geometry storage. BimDown supports two interchangeable encodings:
190
306
 
191
- SVG is **not** used for visualization — it is a geometry storage format chosen because AI models have extensive training data on SVG and strong spatial reasoning with it. The spec uses standard SVG subset (`<path>`, `<rect>`, `<circle>`, `<polygon>`) without custom attributes or styling requirements.
307
+ - **SVG** (`format_version: 1`) — 2D only. AI models have extensive SVG training data and strong spatial reasoning with the format. See [svg-schema/readme.md](svg-schema/readme.md).
308
+ - **GeoJSON** (`format_version: 2`, **default**) — 2D and 3D. Chosen as the default because:
309
+ - AI models produce equivalent or better quality on GeoJSON vs SVG at lower token cost (validated on Gemini 3 Flash; see `bimdown-format-comparison`).
310
+ - Native 3D coordinate support `[x, y, z]` per RFC 7946.
311
+ - JSON parsing is universally available; no XML/SVG parser dependency.
312
+ - Compatible with the GIS toolchain (turf.js, DuckDB spatial, QGIS) for downstream analysis.
192
313
 
193
- Line elements use `<path>` with `M`, `L`, `A` commands. This naturally supports both straight lines and arcs (curved walls, ramps) using standard SVG syntax that AI models already understand well.
314
+ Both define a strict subset and a canonical form (GeoJSON: Point/LineString/Polygon, no Multi*; SVG: `<path>` with M/L/A only, `<rect>`, `<circle>`, `<polygon>`). AI may write looser variants (tessellated arcs, rotated polygons for rect columns, unclosed rings, etc.) and `bimdown build` normalizes to canonical. The two encodings are losslessly convertible over the shared 2D subset (GeoJSON additionally carries 3D). See [geojson-schema/readme.md §6](geojson-schema/readme.md) and [svg-schema/readme.md §6](svg-schema/readme.md).
194
315
 
195
- ### Elements Without SVG
316
+ ### Elements Without Geometry File
196
317
 
197
- Some elements have no SVG representation:
198
- - **Door/Window**: Fully defined by `host_id` + `position` (parametric placement on wall). Absolute coordinates would require re-syncing whenever the host wall moves.
199
- - **Space**: Defined by seed point `(x, y)` in CSV. Boundary polygon is auto-computed by `bimdown build` from surrounding walls, curtain walls, room separators, and structure walls using a half-edge face tracing algorithm. The generated `space.svg` contains `<polygon>` elements whose IDs match the space CSV rows.
318
+ Some elements have no geometry file:
319
+ - **Door/Window/Wall-Opening**: Fully defined by `host_id` + `position`. Absolute coordinates would require re-syncing when the host wall moves.
320
+ - **Space**: Defined by seed point `(x, y)` in CSV. Boundary polygon is auto-computed by `bimdown build` from surrounding walls, curtain walls, room separators, and structure walls using a half-edge face tracing algorithm. The generated `space.geojson` contains `Polygon` features whose IDs match the space CSV rows. Two seeds in one enclosed area (Revit "redundant room"): the first row keeps the area, later ones get `redundant: true` and `net_area` 0 (a build warning; add a room_separator or delete the extra row). A seed outside every closed loop gets no polygon.
200
321
  - **Grid/Level**: Global reference data with coordinates in CSV.
322
+ - **Dimension/Text note/Tag**: Annotations with inline CSV coordinates. A dimension end with a reference is re-derived from the referenced element (location line: the stored point projected onto it; `:start`/`:end`; wall face `:left`/`:right`; `:center`); the stored coordinates are the last resolved points and the fallback. Tags read their text (number, name, size, room area) from the host.
201
323
 
202
324
  ### Unified Foundation Type
203
325
 
204
- Rather than separate types for isolated/strip/raft foundations, a single `foundation` table covers all forms. The geometry type (point/line/polygon) is determined by the SVG element. This reduces table count while the SVG naturally disambiguates the form.
326
+ Rather than separate types for isolated/strip/raft foundations, a single `foundation` table covers all forms. The GeoJSON geometry gives the footprint and the optional `kind` names the type (empty = the geometry's default):
327
+
328
+ | Geometry | `kind` | Plan size |
329
+ |---|---|---|
330
+ | `Point` | `pad` (default) | `width` (X) × `length` (Y, empty = square), turned by `rotation` |
331
+ | `Point` | `pile` | round, diameter `width` (rectangular `width` × `length` when `length` is set) |
332
+ | `LineString` | `strip` (default) | `width` across the centre line |
333
+ | `Polygon` | `raft` (default), `pile_cap`, `pad` | the real footprint (inner rings = holes) |
334
+
335
+ The top face is level + `base_offset`; the body hangs down by `thickness` (a pile's length).
336
+
337
+ Structural tables also carry an optional `material_grade` (C30, Q355, GL24h…) next to `material`, and `structure_slab.span_direction` (degrees CCW from +X) marks a one-way slab or deck. `volume` is computed at query time for structural tables; slabs also get `net_area` (inner rings and hosted Polygon openings deducted), and slab volume uses it.
338
+
339
+ Marks (`number`) can be generated per category; `project_metadata.json` `numbering` maps a table (or `table.kind`: `foundation.pile`, `equipment.ahu`, `beam.secondary`) to its prefix.
340
+
341
+ ### Model Checks
342
+
343
+ `bimdown validate` rejects non-positive `thickness`, `width`, `height`, `size_x` / `size_y`, `step_count`, grid spacings and mullion sizes (empty = inherited from the type) and negative `position`. `bimdown build` warns about doors / windows / openings overlapping on one wall (not ones stacked one above the other), walls overlapping each other (parallel, one centre line inside the other's thickness), redundant / unbounded rooms, stair calculator failures and MEP connectivity. The editor's Warnings panel shows the same checks.
205
344
 
206
345
  ### Opening: Wall and Slab Voids
207
346
 
208
347
  `opening` supports two modes via the same table:
209
- - **Wall opening**: `host_id` → wall, with `position`, `width`, `height`. No SVG.
210
- - **Slab opening**: `host_id` → slab, with SVG geometry (`<rect>` or `<polygon>`).
348
+ - **Wall opening**: `host_id` → wall, with `position`, `width`, `height`, and an optional sill `base_offset` (CSV, like door/window). No GeoJSON.
349
+ - **Slab / roof opening**: `host_id` → slab, structure_slab or roof, with GeoJSON `Polygon` geometry, cut vertically (skylights, dormer openings).
350
+ - **Shaft**: a `Polygon` opening with `top_level_id` (+ `top_offset`); it cuts every slab, structure_slab, ceiling and roof whose body lies between its bottom (its level + `base_offset`) and its top, on every level. `host_id` may stay empty. One `opening` per level hosted on each slab also works.
351
+
352
+ ### Roofs and Attached Walls
353
+
354
+ A roof is a footprint polygon (the eave outline, overhang included); `base_offset` is the underside at the eaves. `edge_slopes` gives one slope per footprint edge (`;`-separated degrees, edge i from vertex i to i+1, 0 = gable / rake edge): each sloped edge is a plane rising inward, and the roof underside is the lowest plane reaching each point, so L / T / U footprints get exact ridges, hips and valleys. Without `edge_slopes`, `roof_type` + `slope` imply them (hip: all edges; gable: all but the wing ends; shed: one eave; mansard: all edges, steeper, with a flat deck). A flat roof drains with small edge slopes (`1.2;0;0;0`). `roof_type: extrusion` sweeps `profile` (`u,z;...`: rise z at distance u across the first edge) along the first edge.
355
+
356
+ **Sloped floors** (Revit slope arrow): a slab or structure_slab with `slope_arrow` = `tx,ty,tz;hx,hy,hz` has its top on the plane through the tail and head (plan x, y; z = height above level + `base_offset`), level across the arrow; thickness stays vertical, and attached walls follow the sloped soffit. Empty = flat. E.g. a ramped floor rising 0.5 m over 10 m: `0,2,0;10,2,0.5`.
357
+
358
+ A wall (or structure_wall) with `top_attach_id` = a roof or slab id (any level) has its top follow that element's underside wherever the wall is under it (gable end walls, walls under a sloped ceiling); elsewhere it keeps its `top_level_id` / `top_offset` top.
359
+
360
+ ```csv
361
+ # lv-2/roof.csv — L-shaped gable over a 6-edge outline, wing ends at edges 2 and 5
362
+ id,roof_type,slope,edge_slopes,thickness
363
+ ro-1,gable,35,35;35;0;35;35;0,0.25
364
+ # lv-2/wall.csv — walls under it attach their tops
365
+ id,thickness,top_level_id,top_attach_id
366
+ w-1,0.2,lv-3,ro-1
367
+ ```
368
+
369
+ **Boundaries picked from walls.** A slab, structure_slab, roof or ceiling with `boundary_walls` (`w-1;w-2;…`, walls / curtain walls / room separators on its level or in global/) keeps its outline associated with those walls (Revit "Pick Walls"): the polygon is still stored, but editors rebuild it from the walls' loop at `boundary_face` (interior, core, centerline, core_exterior, exterior; default core, roofs exterior, ceilings interior) moved out by `boundary_offset` (a roof's overhang) whenever one of the walls moves, flips or changes thickness. Editing the polygon directly clears `boundary_walls`. `validate` checks the ids.
370
+
371
+ ### Stairs and Railings
372
+
373
+ A stair is assembled from components, like Revit's stair by component:
374
+
375
+ - `stair` — its own 3D LineString is the **first run** (bottom riser → top, along the walking line), `step_count` = its risers, `width`; `stair_type` is a shape hint. A stair without geometry — or whose line spans exactly the bottom-to-top of its `stair_run` rows (an overall axis) — is a container whose runs are all `stair_run` rows.
376
+ - `stair_run` (`host_id` → stair) — further flights, each with its own `width` and `step_count`.
377
+ - `stair_landing` (`host_id` → stair) — platform polygons; `base_offset` is the landing **top** (= top of the run arriving on it), `thickness` hangs below.
378
+
379
+ Runs are ordered by their start Z. All risers of a stair share one height: riser = total rise / total risers; a run's going = run length / its `step_count` (its last tread is flush with the landing or floor above). Editors keep run Z values and landing heights in step when steps or levels change.
380
+
381
+ **Multi-storey**: `multistory_top_level_id` repeats the stair (runs, landings, stair railings) on every storey from the base level up to that level. Repetitions keep the step count and plan; the riser adapts to each storey's height. Exporters write one IfcStair per storey.
382
+
383
+ **Calculator checks** (`bimdown build` warnings): riser 0.15–0.19 m, going ≥ 0.26 m, 2R+G 0.60–0.65 m, width ≥ 0.90 m; plus a landing whose top differs from the run arriving on it.
211
384
 
212
- For multi-story shaft openings: export one `opening` per level, each hosted on its respective slab.
385
+ **Railings** have three forms (one `railing` table):
386
+
387
+ | Form | `host_id` | Geometry | Path |
388
+ |---|---|---|---|
389
+ | Sketched | empty | `LineString` 3D | the coordinates |
390
+ | On a slab edge | slab / structure_slab | `LineString` (Z ignored) | on the slab top, follows it |
391
+ | On a stair | stair, plus `side` = `left` / `right` | none (CSV only) | derived: along that side's run edges (inset 5 cm), around the outer side of landings, across the well side of U stairs; rises with the nosing line |
392
+
393
+ `height` is measured from the walking surface (stair nosing line or floor). A `railing_type` supplies height, top rail (`top_rail_shape`, `top_rail_size`), infill (`balusters` at `baluster_spacing` / `baluster_size`, `glass` panels or `none`) and material.
394
+
395
+ ```csv
396
+ # lv-1/stair.csv — an L stair: st-1 is run 1, sr-1 run 2, one landing, railings both sides
397
+ id,width,step_count,stair_type,top_level_id,multistory_top_level_id
398
+ st-1,1.2,9,quarter_turn,lv-2,
399
+ # lv-1/stair_run.csv
400
+ id,host_id,width,step_count
401
+ sr-1,st-1,1.2,9
402
+ # lv-1/railing.csv (no railing.geojson features for these)
403
+ id,host_id,side,type_id,height
404
+ rl-1,st-1,left,rlt-steel-1000,
405
+ rl-2,st-1,right,rlt-steel-1000,
406
+ ```
213
407
 
214
408
  ### MEP Topology
215
409
 
216
410
  MEP networks form a **bipartite graph**: `mep_curve` (duct, pipe, cable_tray, conduit) connects to `mep_node` (fittings, accessories), and nodes connect back to curves. Two curves never connect directly — there is always a node in between.
217
411
 
218
- - **mep_curve** geometry is defined by its two connector endpoints (not the physical centerline). In SVG this is a `<path>`. In Revit, endpoints are taken from `Connector.Origin` positions, which naturally align with the connectors of adjacent fittings.
219
- - **mep_node** is a minimal topology node with position only. In SVG this is a `<rect>`. In Revit it maps to fittings (`DuctFitting`, `PipeFitting`, etc.) and accessories (`DuctAccessory`, `PipeAccessory`).
412
+ - **mep_curve** geometry is defined by its two connector endpoints (not the physical centerline). In GeoJSON this is a 3D `LineString`. In Revit, endpoints are taken from `Connector.Origin` positions, which naturally align with the connectors of adjacent fittings.
413
+ - **mep_node** is a minimal topology node with position only. In GeoJSON this is a 3D `Point`. In Revit it maps to fittings (`DuctFitting`, `PipeFitting`, etc.) and accessories (`DuctAccessory`, `PipeAccessory`).
220
414
  - **equipment** and **terminal** also serve as network endpoints — curves can connect directly to them.
415
+ - **connector** rows define the named ports on equipment, terminals, and active accessories: a host-local offset, outward direction, cross-section, flow direction, and domain. A curve's `from`/`to` references a port as `host_id:name` (or bare `host_id` for passive fittings, whose ports are derived from geometry at runtime). See [`mep-port-conventions.md`](mep-port-conventions.md).
416
+
417
+ **Fittings and accessories**: passive `mep_node`s (empty `kind`) are derived elbows / tees / crosses / reducers / transitions / caps (an optional `fitting` hint records `tap`, `cap`, `open`); tools draw them with real bodies (elbow centre-line radius 1.0 × width for ducts and trays, 1.5 × D for pipes, 4 × D for conduit; runs are pulled back to the fitting face). Inline accessories (`kind` valve / damper / …) carry `in` / `out` connector rows and the run is split around them.
221
418
 
222
419
  **AI authoring workflow**:
223
- 1. Place equipment and terminals (anchors)
224
- 2. Draw duct/pipe segments connecting them (endpoint coordinates)
225
- 3. Call CLI `build` / `resolve-topology` — this detects coincident endpoints, generates `mep_node` entries at junctions, and back-fills `start_node_id`/`end_node_id` on each segment. Warns about disconnected endpoints.
420
+ 1. Place equipment and terminals (anchors) with their `connector` rows
421
+ 2. Draw duct/pipe segments whose ends sit exactly on port points, on other run ends, or on another run's body; add a vertical segment wherever heights differ
422
+ 3. Call CLI `resolve-topology` — ends on ports get `host:port`, meeting ends get a passive `mep_node`, an end on a run's body splits that run with a tee (same table and system only), and the remaining problems are listed
423
+ 4. `build` (and `mep-check`) report MEP connectivity warnings: open ends, refs that don't resolve, ends off their port, system / domain mismatches, disconnected devices, orphan fittings, overloaded circuits (current over 80 % of the breaker), cable trays over their fill limit (`max_fill`, default 40 %). Ids resolve in the curve's own level first, then `global/`, then another level (a riser reaching a node on the level above): such an id must not exist on the curve's level or in `global/`, and should be unique in the project.
226
424
 
227
- **Revit export**: Fittings and accessories are exported as `mep_node`. Curve endpoints are taken from connector positions (not `LocationCurve`), so they naturally coincide with node positions. `start_node_id`/`end_node_id` are derived from Revit's connector relationships.
425
+ **Revit export**: Fittings and accessories are exported as `mep_node`. Curve endpoints are taken from connector positions (not `LocationCurve`), so they naturally coincide with node positions. `from`/`to` are derived from Revit's connector relationships and reference the specific port via `host_id:port_name`. Connections Revit makes that BimDown can't express are rebuilt with nodes: duct onto duct → a passive node between them; a tap → the main split with a `fitting=tap` node; a run crossing the floor of the level its host is on → split there with a node on the upper level (the lower piece reaches it across levels). Fittings move to the level of their runs; hosts still referenced from another level get project-unique ids. See [`mep-port-conventions.md`](mep-port-conventions.md) for port naming conventions.
228
426
 
229
427
  **Revit import**: Curves are created from endpoint coordinates. Fittings are auto-inserted at junctions where curves meet nodes.
230
428
 
429
+ ### Curtain Wall Grids and Panels
430
+
431
+ A curtain wall is a grid of cells: columns along the wall (col 0 at the start), rows up from the base (row 0 at the bottom).
432
+ - **Uniform**: `v_grid_count` columns × `u_grid_count` rows (or a line every `v_spacing` / `u_spacing` when the count is empty; default 3 × 3).
433
+ - **Explicit**: `v_grids` = vertical lines as distances from the start, `u_grids` = horizontal lines as heights above the base, semicolon-separated (`1.2;2.4;3.9`); they override the counts. Lines must lie inside the wall.
434
+ - **Panels**: `panels` = `col:row=kind` overrides, `;`-separated, `*` = every col / row (`*:0=solid;1:0=door`). Kinds: `glass` (default, `panel_material`), `solid` (opaque spandrel, `solid_material`), `door`, `double_door` (hinged on the cell's start side, swinging to the wall's left; no bottom transom), `empty` (mullions only). Door panel marks: `door_numbers` = `D105;D106`, one per door panel in cell order (column from the start, then row); they share the door numbering (unique project-wide).
435
+ - **Mullions**: `mullion_width` (along the wall; Ø when round), `mullion_depth`, `mullion_profile` (`rect`/`round`, interior members only), all type parameters. Two curtain walls meeting at an endpoint share one corner mullion.
436
+ - **Embedded** (Revit "Automatically Embed"): a straight curtain wall drawn along a straight wall or structure_wall (parallel within ~1°, both ends inside the wall's thickness), or an arc curtain wall on an arc wall (same centre, radius within the wall's thickness), cuts that wall over the overlap (along the arc for arcs), from the curtain wall's base to its top; exporters write it as an opening in the host filled by the curtain wall. Derived, nothing stored: move or delete the curtain wall and the host follows. To keep both, offset the curtain wall out of the wall.
437
+
438
+ ```csv
439
+ id,v_grids,u_grids,panels
440
+ cw-1,1.5;3.3;4.8,0.9;2.4,*:0=solid;1:0=door;3:2=empty
441
+ ```
442
+
231
443
  ### Material Enum
232
444
 
233
- A fixed enum of 15 common structural/architectural materials. Represents the **primary material** of an element. Composite/multi-layer constructions are not modeled — the Revit plugin handles layer composition independently.
445
+ A fixed enum of 15 common structural/architectural materials. Represents the **primary material** of an element. Multi-layer constructions are expressed through element types (below); `material` stays the primary (core) material.
446
+
447
+ ### Element Types
448
+
449
+ Like Revit family types: a named set of defaults that many elements share. All type tables live in `global/` (schemas in `csv-schema/types/`).
450
+
451
+ | Type table | Used by (`type_id`) | Type parameters |
452
+ |---|---|---|
453
+ | `wall_type` | `wall`, `structure_wall` | `thickness`, `material` + layers |
454
+ | `slab_type` | `slab`, `structure_slab` | `thickness`, `material` + layers |
455
+ | `roof_type` | `roof` | `thickness`, `material` + layers |
456
+ | `ceiling_type` | `ceiling` | `material` + layers (thickness is type-only) |
457
+ | `door_type` | `door` | `width`, `height`, `operation`, `material`; type-only `frame_width`, `u_value`, `shgc`, `vt` |
458
+ | `window_type` | `window` | same as `door_type` |
459
+ | `curtain_wall_type` | `curtain_wall` | `u_spacing`, `v_spacing`, `panel_material`, `solid_material`, `mullion_width`, `mullion_depth`, `mullion_profile`, `material`; type-only thermal |
460
+ | `column_type` | `column`, `structure_column` | `shape`, `size_x`, `size_y`, `flange`, `web`, `thickness`, `root_radius`, `designation`, `material`, `material_grade` |
461
+ | `beam_type` | `beam`, `brace` | same as `column_type` |
462
+ | `foundation_type` | `foundation` | `kind`, `width`, `length`, `thickness`, `material`, `material_grade` |
463
+ | `furniture_type` | `furniture` | `family`, `variant`, `size_x`, `size_y`, `height` |
464
+ | `railing_type` | `railing` | `height`, `baluster_spacing`, `material`; type-only `top_rail_shape`, `top_rail_size`, `infill` (balusters/glass/none), `baluster_size` |
465
+
466
+ **Resolution rule.** A field a type table shares by name with the instance table is a *type parameter*. An instance with `type_id` leaves it **empty to inherit** the type's value, or sets it to **override** for that element. Required instance fields (`wall.thickness`, `door.width`, …) may be empty when the type supplies them. Untyped elements are unchanged. Tools write a value equal to the type's back as empty, so editing a type updates every instance that follows it.
467
+
468
+ **Layers** (`type_layer.csv`): `type_id`, `seq` (1 = a wall's exterior face — its left side looking from start to end, as in Revit for walls drawn clockwise — or the top face of a slab/roof/ceiling), `function` (`core`, `substrate`, `insulation`, `air_gap`, `membrane`, `finish`), `material`, `thickness`, optional `conductivity` (W/(m·K)) and `name`. A layered type's thickness is the sum of its layers; its own `thickness` column may be empty (derived) or must equal that sum. When an instance overrides `thickness`, its core layer absorbs the difference (build warns).
469
+
470
+ **Thermal fields** on door/window/curtain wall types: `u_value` (W/(m²·K), whole unit), `shgc` and `vt` (0–1).
471
+
472
+ ```csv
473
+ # global/wall_type.csv
474
+ id,name,material,thickness
475
+ wt-ext-concrete-eps,Exterior - Concrete 200 + EPS 100,concrete,0.325
476
+ # global/type_layer.csv
477
+ id,type_id,seq,function,material,thickness,conductivity,name
478
+ tl-2,wt-ext-concrete-eps,1,finish,composite,0.01,0.7,Exterior render
479
+ tl-3,wt-ext-concrete-eps,2,insulation,insulation,0.1,0.035,EPS 100
480
+ tl-4,wt-ext-concrete-eps,3,core,concrete,0.2,2.3,Reinforced concrete
481
+ tl-5,wt-ext-concrete-eps,4,finish,gypsum,0.015,0.4,Gypsum plaster
482
+ # lv-1/wall.csv — w-1 follows the type (0.325), w-2 overrides it
483
+ id,type_id,thickness
484
+ w-1,wt-ext-concrete-eps,
485
+ w-2,wt-ext-concrete-eps,0.35
486
+ ```
487
+
488
+ New projects start with a starter catalog ([`starter-types/global/`](starter-types/global/), metric; `bimdown init --units` and the editor scale its lengths to the project units): concrete, ETICS, brick cavity, timber frame and stud walls; floor, ground floor and roof build-ups; ceilings; single/double/sliding doors; casement/fixed/sliding/tilt-and-turn windows; concrete/steel/timber column and beam sections. `bimdown query` returns effective values (`SELECT thickness FROM wall` includes inherited ones) and type tables join directly: `SELECT w.id, t.name FROM wall w JOIN wall_type t ON w.type_id = t.id`.
234
489
 
235
490
  ### Format Versioning
236
491
 
237
- `project_metadata.json` at the project root includes `format_version` for forward compatibility.
492
+ `project_metadata.json` at the project root includes `format_version`, which selects the geometry encoding:
493
+ - `1` — CSV + **SVG** (2D). Fully supported; see [svg-schema/readme.md](svg-schema/readme.md).
494
+ - `2` — CSV + **GeoJSON** (2D/3D). Fully supported; default for new projects.
495
+
496
+ Both are maintained; neither is deprecated. `bimdown migrate svg-to-geojson` converts a v1 project to v2 (to gain 3D fidelity); tools may also detect the encoding from the geometry files present (`*.svg` vs `*.geojson`).
238
497
 
239
498
  ---
240
499
 
241
500
  ## Storage & Query Architecture
242
501
 
243
502
  See **[DuckDB & CLI Strategy](duckdb-strategy.md)** for details on:
244
- 1. **Hydration**: Merging partitioned CSVs + parsing SVG geometry into in-memory DuckDB tables.
503
+ 1. **Hydration**: Merging partitioned CSVs + parsing GeoJSON geometry into in-memory DuckDB tables.
245
504
  2. **Execution**: Standard SQL queries over unified, geometry-enriched views.
246
- 3. **Sync-Out**: Stripping computed fields, auto-healing SVG from CSV source-of-truth, re-partitioning by level.
505
+ 3. **Sync-Out**: Stripping computed fields, auto-healing GeoJSON from CSV source-of-truth, re-partitioning by level.
247
506
  4. **Resolve-Topology**: Auto-generating MEP connectivity graph from endpoint coordinates.
@@ -0,0 +1,5 @@
1
+ id,name,description,material,shape,size_x,size_y,flange,web,thickness,root_radius,designation,material_grade
2
+ bmt-concrete-250x500,Concrete 250 x 500,,concrete,rect,0.25,0.5,,,,,,C30
3
+ bmt-concrete-300x600,Concrete 300 x 600,,concrete,rect,0.3,0.6,,,,,,C30
4
+ bmt-steel-ipe-300,Steel IPE 300,European I-beam,steel,i_shape,0.15,0.3,0.0107,0.0071,,0.015,IPE 300,S355
5
+ bmt-glulam-200x400,Glulam 200 x 400,Glued laminated timber,wood,rect,0.2,0.4,,,,,,GL24h