python-cad-tools 0.1.7__tar.gz → 0.1.10__tar.gz

{python_cad_tools-0.1.7 → python_cad_tools-0.1.10}/.github/workflows/ci.yml

@@ -250,11 +250,127 @@ jobs:
           name: ${{ matrix.lock }}
           path: ${{ matrix.lock }}
 
+  toolchain-matrix:
+    name: Toolchain matrix (${{ matrix.os }}, py${{ matrix.python }}, ${{ matrix.group }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.13"]
+        group: [core, cad, bim, mesh, drawings, engineering, visualization, all]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      # Full matrix on main/tags/release-candidates; a fast core+all subset on pull requests.
+      - name: Determine whether this matrix cell runs
+        id: gate
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ] && \
+             ! { [ "${{ matrix.os }}" = "ubuntu-latest" ] && [ "${{ matrix.python }}" = "3.13" ] && \
+                 { [ "${{ matrix.group }}" = "core" ] || [ "${{ matrix.group }}" = "all" ]; }; }; then
+            echo "run=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        if: steps.gate.outputs.run == 'true'
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+        if: steps.gate.outputs.run == 'true'
+      - name: Install capability group
+        if: steps.gate.outputs.run == 'true'
+        run: |
+          if [ "${{ matrix.group }}" = "core" ]; then
+            pip install -e .
+          else
+            pip install -e ".[${{ matrix.group }}]"
+          fi
+      - run: pip check
+        if: steps.gate.outputs.run == 'true'
+      - name: Import declared libraries for this group
+        if: steps.gate.outputs.run == 'true'
+        run: |
+          python - <<'PY'
+          import importlib
+          import json
+          import sys
+
+          GROUPS = {
+              "core": ["build123d", "OCP", "ifcopenshell", "trimesh", "numpy", "ezdxf", "reportlab", "pypdf"],
+              "cad": ["build123d", "OCP"],
+              "bim": ["ifcopenshell"],
+              "mesh": ["trimesh", "numpy"],
+              "drawings": ["ezdxf", "reportlab", "pypdf"],
+              "engineering": ["shapely", "manifold3d", "meshio"],
+              "visualization": [],
+              "all": [
+                  "build123d", "OCP", "ifcopenshell", "trimesh", "numpy", "ezdxf", "reportlab", "pypdf",
+                  "shapely", "manifold3d", "meshio",
+              ],
+          }
+          group = "${{ matrix.group }}"
+          modules = GROUPS[group]
+          results = {}
+          for name in modules:
+              try:
+                  module = importlib.import_module(name)
+                  results[name] = getattr(module, "__version__", "unknown")
+              except ImportError as error:
+                  print(f"::error::failed to import {name!r} for group {group!r}: {error}", file=sys.stderr)
+                  sys.exit(1)
+          report = {
+              "schema_id": "urn:python-cad-tools:schema:toolchain-compatibility:1",
+              "schema_version": 1,
+              "os": "${{ matrix.os }}",
+              "python": "${{ matrix.python }}",
+              "group": group,
+              "resolved_versions": results,
+              "ok": True,
+          }
+          with open("toolchain-compatibility.json", "w", encoding="utf-8") as stream:
+              json.dump(report, stream, indent=2, sort_keys=True)
+          print(json.dumps(report, indent=2, sort_keys=True))
+          PY
+      - name: Tier-2 interop smoke and no-GUI assertion
+        if: steps.gate.outputs.run == 'true' && matrix.group == 'all'
+        run: |
+          python - <<'PY'
+          import sys
+
+          from build123d import Box
+          from python_cad_tools.geometry import tessellate
+
+          solid = Box(10, 10, 10)
+          vertices, triangles = tessellate(solid, 0.5, 0.25)
+          assert vertices and triangles, "tessellation produced no geometry"
+
+          import trimesh
+          mesh = trimesh.Trimesh(vertices=vertices, faces=triangles, process=False)
+          assert mesh.is_watertight or len(mesh.faces) > 0, "trimesh failed to load the tessellated shape"
+
+          import ifcopenshell
+          file = ifcopenshell.file(schema="IFC4")
+          file.createIfcCartesianPoint((0.0, 0.0, 0.0))
+
+          import ezdxf
+          document = ezdxf.new("R2018")
+          document.modelspace().add_line((0, 0), (1, 1))
+
+          forbidden = [name for name in sys.modules if name.startswith(("vtk", "pyvista", "PyQt", "PySide", "tkinter"))]
+          assert not forbidden, f"GUI/visualization modules present after Tier-2 interop smoke: {forbidden}"
+          print("Tier-2 interop smoke and no-GUI assertion passed.")
+          PY
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        if: steps.gate.outputs.run == 'true'
+        with:
+          name: toolchain-compatibility-${{ matrix.os }}-py${{ matrix.python }}-${{ matrix.group }}
+          path: toolchain-compatibility.json
+
   build-publish:
     name: Build and publish to PyPI
-    if: |
-      (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
-      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v'))
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
     needs:
       - lint-type-unit
       - exporter-integration
@@ -298,9 +414,7 @@ jobs:
 
   provenance:
     name: Generate SLSA provenance
-    if: |
-      (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
-      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v'))
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
     needs: [build-publish]
     permissions:
       actions: read

{python_cad_tools-0.1.7 → python_cad_tools-0.1.10}/.gitignore

@@ -9,6 +9,7 @@ htmlcov/
 build/
 dist/
 *.egg-info/
+build-local.sh
 
 generated/*
 !generated/.gitkeep

{python_cad_tools-0.1.7 → python_cad_tools-0.1.10}/CHANGELOG.md

@@ -7,6 +7,49 @@ stable release is published.
 
 ## [Unreleased]
 
+## [0.1.10] - 2026-08-11
+
+### Added
+
+- Capability-based dependency extras (`cad`, `bim`, `mesh`, `drawings`,
+  `engineering`, `visualization`, `all`); the Tier 1 verified stack stays
+  required in `[project.dependencies]`. See `docs/toolchain.md`.
+- A documented two-tier authoring contract (`docs/two-tier-contract.md`) and a
+  neutral-model field reference (`docs/neutral-model.md`).
+- `DesignElement.properties` now exports as `Pset_PythonCadUser` on IFC-exported
+  elements; property values must be `str`, `bool`, `int`, or `float`.
+- Computed quantities now export as an `IfcElementQuantity` named
+  `Qto_PythonCadDesign` on IFC-exported elements with a quantity record.
+- `DesignElement.storey` now drives on-demand `IfcBuildingStorey` creation; a
+  model with no declared storey is unaffected.
+- New `DesignElement.openings: list[Opening]` field; each opening exports an
+  `IfcOpeningElement` + `IfcRelVoidsElement` on its host. Openings add IFC
+  semantics only — geometry in every other format is unaffected.
+- New public `python_cad_tools.drawings.Dimension` annotation primitive,
+  rendered through the verified annotation pipeline in SVG, DXF, and PDF.
+
+### Changed
+
+- The IFC unit assignment gains a `MASSUNIT` (`KILO`/`GRAM`) entry. This
+  changes the emitted IFC file, and therefore its artifact hash, for every
+  project — a one-time change from this release.
+
+## [0.1.9] - 2026-08-03
+
+### Fixed
+
+- Made iPhone panning substantially faster and added visible, press-and-hold pan and zoom controls for reliable touch navigation when browser gestures are inconsistent.
+- Added a selectable 1×–100× navigation speed that adjusts drag, wheel, pinch, and on-screen pan/zoom controls, with the previous speed retained as the minimum.
+
+## [0.1.8] - 2026-07-21
+
+### Fixed
+- Made CI publish to PyPI and generate release provenance only for version-tag
+  pushes, preventing the following `main` push from attempting to upload the
+  same immutable distribution files a second time.
+- Corrected Pan mode to replace Babylon's higher-priority primary-touch Rotate
+  mapping on iPhone instead of only adding a buttonless-touch fallback.
+
 ## [0.1.7] - 2026-07-21
 
 ### Changed

{python_cad_tools-0.1.7/src/python_cad_tools.egg-info → python_cad_tools-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cad-tools
-Version: 0.1.7
+Version: 0.1.10
 Summary: Typed, headless Python tooling for CAD/BIM models and artifacts
 Author: Brandon Benge
 License: AGPL-3.0-only
@@ -26,6 +26,25 @@ Requires-Dist: numpy<3,>=2.3
 Requires-Dist: ezdxf<2,>=1.4
 Requires-Dist: reportlab<5,>=4.4
 Requires-Dist: pypdf<7,>=6
+Provides-Extra: cad
+Requires-Dist: build123d<0.12,>=0.11.1; extra == "cad"
+Requires-Dist: cadquery-ocp-novtk<7.10,>=7.9.3.1.1; extra == "cad"
+Provides-Extra: bim
+Requires-Dist: ifcopenshell<0.9,>=0.8.5; extra == "bim"
+Provides-Extra: mesh
+Requires-Dist: trimesh<5,>=4.12; extra == "mesh"
+Requires-Dist: numpy<3,>=2.3; extra == "mesh"
+Provides-Extra: drawings
+Requires-Dist: ezdxf<2,>=1.4; extra == "drawings"
+Requires-Dist: reportlab<5,>=4.4; extra == "drawings"
+Requires-Dist: pypdf<7,>=6; extra == "drawings"
+Provides-Extra: engineering
+Requires-Dist: shapely<3,>=2.1; extra == "engineering"
+Requires-Dist: manifold3d<4,>=3; extra == "engineering"
+Requires-Dist: meshio<6,>=5.3; extra == "engineering"
+Provides-Extra: visualization
+Provides-Extra: all
+Requires-Dist: python-cad-tools[bim,cad,drawings,engineering,mesh,visualization]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.2; extra == "dev"
 Requires-Dist: twine<7,>=6; extra == "dev"
@@ -50,6 +69,17 @@ The canonical project identities are:
 
 Licensed under [AGPL-3.0-only](LICENSE). Published on [PyPI](https://pypi.org/project/python-cad-tools/).
 
+## Install
+
+```bash
+pip install "python-cad-tools[all]"
+```
+
+Capability-based extras (`cad`, `bim`, `mesh`, `drawings`, `engineering`,
+`visualization`) install a subset of the curated, version-tested toolchain.
+See [`docs/toolchain.md`](docs/toolchain.md) for the supported-library table,
+the dependency license policy, and the compatibility verification matrix.
+
 ## Install for development
 
 Python 3.12 or 3.13 is required.
@@ -66,6 +96,43 @@ python3 -m pip install ./dist/python_cad_tools-*.whl
 python-cad --version
 ```
 
+## Build locally
+
+Building the complete distribution requires Python 3.12 or 3.13 and Node.js
+22.15.0. From a fresh checkout, create and activate the Python environment
+before building the viewer. Activation is important because the viewer staging
+script reads the installed `python-cad-tools` version from that environment.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[dev]'
+
+cd viewer
+npm ci
+npm test
+npm run build
+cd ..
+
+python -m build --wheel --sdist --outdir dist .
+python -m twine check dist/*
+```
+
+The viewer build compiles the private TypeScript source and stages its verified,
+model-free static shell under `src/python_cad_tools/_viewer_static/`. The final
+wheel and source archive are written to `dist/`. To inspect the viewer while
+developing its source, run `npm run preview` from `viewer/` after
+`npm run build` and open the local URL printed by Vite.
+
+To build and serve an actual CAD project with the locally installed editable
+package, change to that project's directory and run:
+
+```bash
+python-cad build
+python-cad serve
+```
+
 ## Create a new project
 
 ```bash
@@ -125,6 +192,14 @@ documented in [`docs/drawing-extensions.md`](docs/drawing-extensions.md). One
 annotation set is validated and rendered consistently to SVG, DXF, and PDF
 before artifact hashes are recorded.
 
+Python CAD Tools is a curated engineering platform with a two-tier authoring
+contract: verified authoring through the neutral model (Tier 1), and
+supported-but-unverified direct use of a pinned library such as
+`ifcopenshell` or `trimesh` (Tier 2). See
+[`docs/two-tier-contract.md`](docs/two-tier-contract.md),
+[`docs/neutral-model.md`](docs/neutral-model.md), and
+[`docs/toolchain.md`](docs/toolchain.md).
+
 ## Verification
 
 ```bash
@@ -138,6 +213,7 @@ before artifact hashes are recorded.
 .venv/bin/python -m twine check dist/*
 ```
 
+
 The default pytest command runs the fast unit suite. Integration, packaging,
 and external typing suites are explicit release gates. Packaging tests inspect wheel and sdist inventories, install the wheel
 non-editably into an isolated environment outside the checkout, prove the

python_cad_tools-0.1.7/PKG-INFO → python_cad_tools-0.1.10/README.md

@@ -1,40 +1,3 @@
-Metadata-Version: 2.4
-Name: python-cad-tools
-Version: 0.1.7
-Summary: Typed, headless Python tooling for CAD/BIM models and artifacts
-Author: Brandon Benge
-License: AGPL-3.0-only
-Project-URL: Homepage, https://github.com/brandon-benge/python-cad-tools
-Project-URL: Repository, https://github.com/brandon-benge/python-cad-tools
-Project-URL: Issues, https://github.com/brandon-benge/python-cad-tools/issues
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: GNU Affero General Public License v3
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Typing :: Typed
-Requires-Python: <3.14,>=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: build123d<0.12,>=0.11.1
-Requires-Dist: cadquery-ocp-novtk<7.10,>=7.9.3.1.1
-Requires-Dist: ifcopenshell<0.9,>=0.8.5
-Requires-Dist: trimesh<5,>=4.12
-Requires-Dist: numpy<3,>=2.3
-Requires-Dist: ezdxf<2,>=1.4
-Requires-Dist: reportlab<5,>=4.4
-Requires-Dist: pypdf<7,>=6
-Provides-Extra: dev
-Requires-Dist: build<2,>=1.2; extra == "dev"
-Requires-Dist: twine<7,>=6; extra == "dev"
-Requires-Dist: pytest<9,>=8.4; extra == "dev"
-Requires-Dist: pytest-cov<8,>=7; extra == "dev"
-Requires-Dist: ruff<0.15,>=0.14; extra == "dev"
-Requires-Dist: mypy<2,>=1.18; extra == "dev"
-Dynamic: license-file
-
 # Python CAD Tools
 
 Python CAD Tools is an installable, typed Python package for defining shared
@@ -50,6 +13,17 @@ The canonical project identities are:
 
 Licensed under [AGPL-3.0-only](LICENSE). Published on [PyPI](https://pypi.org/project/python-cad-tools/).
 
+## Install
+
+```bash
+pip install "python-cad-tools[all]"
+```
+
+Capability-based extras (`cad`, `bim`, `mesh`, `drawings`, `engineering`,
+`visualization`) install a subset of the curated, version-tested toolchain.
+See [`docs/toolchain.md`](docs/toolchain.md) for the supported-library table,
+the dependency license policy, and the compatibility verification matrix.
+
 ## Install for development
 
 Python 3.12 or 3.13 is required.
@@ -66,6 +40,43 @@ python3 -m pip install ./dist/python_cad_tools-*.whl
 python-cad --version
 ```
 
+## Build locally
+
+Building the complete distribution requires Python 3.12 or 3.13 and Node.js
+22.15.0. From a fresh checkout, create and activate the Python environment
+before building the viewer. Activation is important because the viewer staging
+script reads the installed `python-cad-tools` version from that environment.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[dev]'
+
+cd viewer
+npm ci
+npm test
+npm run build
+cd ..
+
+python -m build --wheel --sdist --outdir dist .
+python -m twine check dist/*
+```
+
+The viewer build compiles the private TypeScript source and stages its verified,
+model-free static shell under `src/python_cad_tools/_viewer_static/`. The final
+wheel and source archive are written to `dist/`. To inspect the viewer while
+developing its source, run `npm run preview` from `viewer/` after
+`npm run build` and open the local URL printed by Vite.
+
+To build and serve an actual CAD project with the locally installed editable
+package, change to that project's directory and run:
+
+```bash
+python-cad build
+python-cad serve
+```
+
 ## Create a new project
 
 ```bash
@@ -125,6 +136,14 @@ documented in [`docs/drawing-extensions.md`](docs/drawing-extensions.md). One
 annotation set is validated and rendered consistently to SVG, DXF, and PDF
 before artifact hashes are recorded.
 
+Python CAD Tools is a curated engineering platform with a two-tier authoring
+contract: verified authoring through the neutral model (Tier 1), and
+supported-but-unverified direct use of a pinned library such as
+`ifcopenshell` or `trimesh` (Tier 2). See
+[`docs/two-tier-contract.md`](docs/two-tier-contract.md),
+[`docs/neutral-model.md`](docs/neutral-model.md), and
+[`docs/toolchain.md`](docs/toolchain.md).
+
 ## Verification
 
 ```bash
@@ -138,6 +157,7 @@ before artifact hashes are recorded.
 .venv/bin/python -m twine check dist/*
 ```
 
+
 The default pytest command runs the fast unit suite. Integration, packaging,
 and external typing suites are explicit release gates. Packaging tests inspect wheel and sdist inventories, install the wheel
 non-editably into an isolated environment outside the checkout, prove the

{python_cad_tools-0.1.7 → python_cad_tools-0.1.10}/docs/drawing-extensions.md

@@ -42,9 +42,20 @@ so the prior generated tree and its recorded hashes remain unchanged.
 
 The stable home module `python_cad_tools.drawings` exports `Point2`,
 `Direction`, `DrawingStyleToken`, `DrawingSheet`, `Line`, `Polyline`, `Text`,
-`SectionCallout`, `ElevationMarker`, `TableRow`, `Table`, `SheetAnnotations`,
-and `DrawingAnnotationSet`. The dataclass fields and literal tokens are the v1
-contract; there is no dictionary or renderer-specific alternate form.
+`Dimension`, `SectionCallout`, `ElevationMarker`, `TableRow`, `Table`,
+`SheetAnnotations`, and `DrawingAnnotationSet`. The dataclass fields and
+literal tokens are the v1 contract; there is no dictionary or
+renderer-specific alternate form.
+
+`Dimension(id, sheet_id, start, end, offset_mm, label, style)` draws a
+measurement: a dimension line offset from the measured segment (in Y for a
+predominantly horizontal segment, in X otherwise), extension/witness lines
+back to `start`/`end`, arrowheads at both ends, and a centred label. It uses
+the `"annotation-dimension"` style token. The rendered DXF output is tagged
+geometry (lines, arrowheads, and text with `PYTHON_CAD_TOOLS` XDATA), not a
+native associative `DIMENSION` entity — a project needing an editable CAD
+dimension should treat the drawing as conceptual, consistent with every other
+Python CAD Tools drawing output.
 
 `DrawingContext.sheets` contains these standard sheets:
 
@@ -125,6 +136,8 @@ direction.
 
 Compound IDs are deterministic:
 
+- dimension: `.line`, `.extension.start`, `.extension.end`, `.arrow.start`,
+  `.arrow.end`, and `.label`;
 - section callout: `.line`, `.arrow.start`, `.arrow.end`, `.label.start`, and
   `.label.end`;
 - elevation marker: `.outline`, `.pointer`, and `.label`;

python_cad_tools-0.1.10/docs/neutral-model.md

@@ -0,0 +1,138 @@
+# Neutral model reference
+
+This is the Tier 1 authoring reference: the `DesignElement`/`DesignModel`
+field semantics, the `IfcMapping` contract, the new Phase 1 capabilities
+(user properties, computed quantities, multiple storeys, openings, drawing
+dimensions), and the validator invocation model. See
+`docs/two-tier-contract.md` for what "Tier 1" means and
+`docs/public-api.md` for the full module allowlist.
+
+## `DesignElement` fields
+
+| Field | Type | Semantics |
+| --- | --- | --- |
+| `id` | `str` | Stable, unique identifier. Used to derive every downstream IFC `GlobalId` and to key manifests. |
+| `name` | `str` | Human-readable display name. |
+| `category` | `str` | Free-text classification, exported as `ObjectType` in IFC. |
+| `geometry` | `Any` | A build123d-compatible solid, shell, wire, or edge. Required and opaque — the framework does not restrict how it was built. |
+| `geometry_kind` | `"solid" \| "shell" \| "wire" \| "edge" \| "reference"` | Declares the geometry's topological kind. Physical elements must be `"solid"`. |
+| `placement` | `Placement` | Translation (mm) and rotation (degrees, XYZ) applied on top of `geometry`'s own coordinates. |
+| `dimensions` | `Dimensions` | Declared, author-stated extents. Independent of the geometry's actual bounds; exported into `Pset_PythonCadDesign`. |
+| `material` | `MaterialSpec \| None` | Required for physical elements. Drives IFC material association and quantity mass calculation (`density_kg_m3`). |
+| `color_rgb` | `Color \| None` | Overrides the material color for this element's rendering/styling. |
+| `ifc_mapping` | `IfcMapping` | See below. |
+| `storey` | `str \| None` | The `IfcBuildingStorey` this element belongs to. `None` means the framework's implicit "Default Storey". |
+| `tags` | `set[str]` | Free-text classification tags; not exported to any format. |
+| `properties` | `dict[str, Any]` | User properties. Exported to IFC as `Pset_PythonCadUser` for IFC-exported elements (see below). Values must be `str`, `bool`, `int`, or `float`. |
+| `children` | `list[DesignElement]` | Nested elements, walked depth-first by `DesignModel.walk()`. |
+| `visible` | `bool` | Excludes the element from every exporter when `False`. |
+| `export_formats` | `set[str]` | Which exporters (`step`, `ifc`, `glb`, `drawings`, `quantities`) include this element. |
+| `source_module` | `str` | Free-text provenance, exported into `Pset_PythonCadDesign`. |
+| `physical` | `bool` | Physical elements must be `"solid"` and require a material; non-physical (reference) elements are excluded from IFC, quantities, and mass. |
+| `parent_id` | `str \| None` | Parent element ID, exported as an `IfcRelAggregates` relationship when both ends are IFC-exported. |
+| `openings` | `list[Opening]` | Semantic voids in this host element. See "Openings" below. |
+
+## `IfcMapping`
+
+```python
+IfcMapping(ifc_class: str | None, predefined_type: str | None = None, exclude_reason: str | None = None)
+```
+
+Exactly one of `ifc_class` or `exclude_reason` must be set (enforced at
+`validate` time). `ifc_class` is validated live against the installed
+`ifcopenshell` IFC4 schema at export time: it must name a concrete (non-
+abstract) subtype of `IfcElement`, and `predefined_type` (default
+`"NOTDEFINED"`) must be a member of that class's declared `PredefinedType`
+enumeration. Any concrete `IfcElement` subtype is accepted — the framework
+does not restrict the mapping to a fixed list.
+
+## Openings
+
+```python
+Opening(id: str, geometry: Any, name: str | None = None, predefined_type: str | None = None)
+```
+
+An `Opening` on `DesignElement.openings` produces one `IfcOpeningElement` and
+one `IfcRelVoidsElement` per opening when the host is IFC-exported.
+`predefined_type` maps to `IfcOpeningElementTypeEnum` (`"OPENING"` or
+`"RECESS"`; defaults to `"OPENING"`).
+
+**Openings add IFC semantics only.** The host element's `geometry` stays
+authoritative for STEP, GLB, drawings, quantities, and bounds — the framework
+does not boolean-subtract an opening from the host tessellation. The
+supported authoring pattern is to cut the void from the host solid directly
+(`host_solid.cut(opening_solid)`, as `benge-property-cad/model.py` already
+does) and declare the same void as an `Opening` so IFC also carries the
+`IfcOpeningElement`/`IfcRelVoidsElement` pair. Declaring an opening without
+cutting the host geometry produces an IFC void that other formats do not
+reflect — do not do this for artifacts that need Tier 1 multi-format
+consistency.
+
+## IFC property sets and quantities
+
+Every IFC-exported element carries `Pset_PythonCadDesign`
+(`StableId`, `Category`, `SourceModule`, `GeometryKind`, and any declared
+dimensions) — unchanged from before this document existed, and the sole
+anchor the framework uses to identify its own authored elements.
+
+- **`Pset_PythonCadUser`** — present when `element.properties` is non-empty.
+  One `IfcPropertySingleValue` per entry, typed by Python type:
+  `bool → IfcBoolean`, `int → IfcInteger`, `float → IfcReal`,
+  `str → IfcLabel`. Any other value type is a `validate`-time error.
+- **`Qto_PythonCadDesign`** — an `IfcElementQuantity` present when the
+  element has a computed quantity record (the same records
+  `python-cad build`'s `quantities` exporter produces). Contains `Count`
+  (`IfcQuantityCount`), `NetSurfaceArea` (`IfcQuantityArea`, m²), `NetVolume`
+  (`IfcQuantityVolume`, m³), and — only when the element's material has a
+  density — `NetWeight` (`IfcQuantityWeight`, kg). Units convert from the
+  neutral model's mm/mm²/mm³ into the file's declared unit assignment, which
+  includes an explicit `MASSUNIT` (`KILO`/`GRAM`).
+
+`IfcOpeningElement` entities carry `Pset_PythonCadOpening`
+(`StableId`, `HostId`) instead of `Pset_PythonCadDesign`, so they are never
+mistaken for an authored design element by `_design_products` or by any
+sidecar reconciliation.
+
+## Storeys
+
+An element with `storey=None` is placed in the implicit "Default Storey"
+(stable ID `<model.id>.ifc.storey` — unchanged from before multi-storey
+support existed). An element with `storey="Some Name"` is placed in an
+`IfcBuildingStorey` named `"Some Name"`, created on demand, one per distinct
+declared name among IFC-exported elements. A model that declares no storey on
+any element produces byte-identical spatial structure to a single-storey
+model. Storey names must be non-empty text (validated).
+
+## Drawing dimensions
+
+`python_cad_tools.drawings.Dimension` is a public annotation primitive:
+
+```python
+Dimension(id: str, sheet_id: str, start: Point2, end: Point2, offset_mm: float, label: str, style: DrawingStyleToken)
+```
+
+It renders through the same verified annotation-entity pipeline as every
+other annotation primitive (`Line`, `Text`, `Table`, ...): it flattens into
+six identified child entities (dimension line, two extension/witness lines,
+two arrowheads, and a label), each carrying an `SVG data-annotation-id`, a DXF
+`PYTHON_CAD_TOOLS` XDATA tag, and an annotation-manifest record, so it
+round-trip verifies in SVG, DXF, and PDF like any other Tier 1 drawing
+annotation. The dimension line offsets perpendicular to the measured segment:
+in Y for a predominantly horizontal measurement, in X otherwise. The rendered
+DXF output is tagged geometry, not a native associative `DIMENSION` entity.
+
+## Validator invocation
+
+`validate_model(model)` runs the built-in element/model rules (stable IDs,
+geometry validity, material requirements, IFC mapping intent, storey names,
+user property types, opening identity/geometry) and then every callable in
+`DesignModel.validators` in list order, each receiving the model and
+returning a `list[ValidationIssue]`. `fatal_issues(...)` filters to
+`severity == "error"`; `python-cad build`/`validate` fail on any fatal issue
+before export begins.
+
+## Construction recipes (Phase 2)
+
+Parametric BREP/SweptSolid IFC representation via a construction-recipe model
+(`python_cad_tools.recipes`) is scoped as a separate SpecRepo proposal and is
+not yet implemented. This section will be extended when that proposal ships.

{python_cad_tools-0.1.7 → python_cad_tools-0.1.10}/docs/public-api.md

@@ -9,7 +9,8 @@ of optional runtime imports.
 
 - `python_cad_tools.context`: `BuildContext` and `DrawingContext`.
 - `python_cad_tools.elements`: `Color`, `GeometryKind`, `DesignElement`,
-  `DesignModel`, `Dimensions`, `IfcMapping`, `MaterialSpec`, and `Placement`.
+  `DesignModel`, `Dimensions`, `IfcMapping`, `MaterialSpec`, `Opening`, and
+  `Placement`.
 - `python_cad_tools.units`: `Length`, `Area`, `Volume`, `MM`, `INCH`, `FOOT`,
   `mm`, `inches`, `feet`, `feet_inches`, `to_mm`, `square_feet`, `cubic_feet`,
   `cubic_yards`, `metres`, and `square_metres`.
@@ -17,7 +18,7 @@ of optional runtime imports.
   `prism_between`, `sloped_pool`, `bounds`, `combined_bounds`, `tessellate`,
   `is_valid_solid`, and `diagonal`.
 - `python_cad_tools.drawings`: `Point2`, `Direction`, `DrawingStyleToken`,
-  `DrawingSheet`, `Line`, `Polyline`, `Text`, `SectionCallout`,
+  `DrawingSheet`, `Line`, `Polyline`, `Text`, `Dimension`, `SectionCallout`,
   `ElevationMarker`, `TableRow`, `Table`, `SheetAnnotations`, and
   `DrawingAnnotationSet`.
 - `python_cad_tools.validation`: `ValidationIssue`.
@@ -35,6 +36,12 @@ of optional runtime imports.
 flattened compound entities, file writers, and drawing validators remain
 private. See [Format-neutral drawing extensions](drawing-extensions.md).
 
+Python CAD Tools distinguishes Tier 1 (verified authoring through this public
+API) from Tier 2 (supported, unverified direct use of a library named in
+`docs/toolchain.md`). See [The two-tier authoring
+contract](two-tier-contract.md) and the full field reference in
+[Neutral model reference](neutral-model.md).
+
 Every public type is inline-typed and the wheel includes `py.typed`. Public
 module `__all__` values are tested as allowlists. Exporter implementations,
 `_project_loader`, `_project_state`, renderer code, staging helpers, and other