(feat) PDF and Projection POC (#5)

Author: aka-blackboots

.gitignore

@@ -29,4 +29,8 @@ dist
 settings.json
 
 # Copilot
-.github/*.md
+.github/*.md
+
+# CAD export artifacts
+*.pdf
+*.dxf

AGENTS.md

@@ -0,0 +1,111 @@
+# AGENTS.md
+
+Repository-level standards for Codex, Copilot, and other AI coding agents.
+
+This file defines how agents must operate to produce production-ready code.
+If a subdirectory has stricter instructions, follow both; if they conflict, use the more restrictive rule.
+
+## Core Outcome
+
+All agent work must be:
+
+- Correct and behaviorally safe
+- Testable and reproducible
+- Secure by default
+- Backward-compatible unless explicitly approved
+- Reviewable through small, clear diffs
+
+## Documentation Location Policy (Mandatory)
+
+- All AI-generated docs must be placed under `AI-DOCs/`.
+- Do not add AI-generated docs under app/code directories such as `main/`, `src/`, `test/`, or package folders.
+- If a task needs documentation, create or update files in `AI-DOCs/` unless the user explicitly asks otherwise.
+
+## Documentation Naming Rules
+
+- Use `kebab-case` file names.
+- Prefix date when useful: `YYYY-MM-DD-topic.md`.
+- Keep one concern per file (design note, runbook, handoff, postmortem, etc.).
+
+## Engineering Standards
+
+### 1) Scope Discipline
+
+- Only change what is necessary for the request.
+- Do not refactor unrelated modules unless explicitly requested.
+- Keep each change atomic and explainable.
+
+### 2) API and Compatibility
+
+- Preserve public API behavior by default.
+- If a breaking change is required, document it clearly and provide migration guidance.
+- Avoid hidden behavioral changes in existing call paths.
+
+### 3) Security and Safety
+
+- Never hardcode secrets, keys, tokens, or credentials.
+- Validate and sanitize all external/user-controlled inputs.
+- Prefer fail-safe behavior on invalid state or malformed input.
+- Minimize attack surface: least privilege, least data exposure, least capability.
+
+### 4) Reliability and Error Handling
+
+- Avoid panics for recoverable runtime conditions.
+- Return structured errors with actionable context.
+- Do not silently swallow failures.
+- Keep retries bounded and deterministic.
+
+### 5) Performance and Scalability
+
+- Avoid obviously unbounded algorithms in hot paths.
+- Reuse existing components and avoid duplicate data transformations.
+- Consider memory overhead and serialization costs for large scenes/data.
+
+### 6) Readability and Maintainability
+
+- Prefer simple, explicit code over clever shortcuts.
+- Keep functions focused and names descriptive.
+- Add concise comments only where intent is not obvious from code.
+
+## Testing and Validation Standards (Mandatory)
+
+Before finalizing a change, run relevant checks for touched areas:
+
+- Formatting
+- Static/build checks
+- Tests
+- Example/integration command for user-facing features
+
+Minimum expectations:
+
+- Run project-standard commands where available (for example `cargo fmt`, `cargo check`, `cargo test`).
+- If full validation cannot run, report exactly:
+  - which command failed or was skipped
+  - why
+  - residual risk
+
+## Change Management
+
+- Prefer incremental commits with focused intent.
+- Do not commit generated binaries or transient artifacts.
+- Keep diffs review-friendly and avoid noisy unrelated formatting churn.
+
+## Pull Request / Handoff Standard
+
+For significant changes, add/update a short handoff note in `AI-DOCs/` including:
+
+- What changed
+- Why it changed
+- How to test locally
+- Backward-compatibility notes
+- Known caveats and follow-ups
+
+## Definition of Done
+
+A task is done only when all are true:
+
+- Requested functionality is implemented end-to-end.
+- Quality gates have been run or limitations are explicitly documented.
+- Documentation and examples are updated when behavior/API changed.
+- No unintended artifacts are introduced into version control.
+- Result is ready for production review without hidden assumptions.

AI-DOCs/README.md

@@ -0,0 +1,30 @@
+# AI-DOCs
+
+Central location for documentation generated by AI agents (Codex, Copilot, etc.).
+
+## What goes here
+
+- design notes
+- implementation logs
+- testing/runbooks
+- migration notes
+- handoff summaries
+
+## What does not go here
+
+- source code
+- compiled output/binaries
+- user-facing product docs that belong elsewhere by explicit request
+
+## Conventions
+
+- Use `kebab-case` file names.
+- Prefer focused docs over one large catch-all file.
+- Include runnable commands and expected outputs when relevant.
+
+## Recommended starter files
+
+- `codex-repo-playbook.md`
+- `local-testing-checklist.md`
+- date-stamped implementation notes as needed
+

AI-DOCs/codex-repo-playbook.md

@@ -0,0 +1,42 @@
+# Codex Repo Playbook
+
+This playbook defines practical defaults for Codex work in this repository.
+
+## 1) Before changing code
+
+- Read relevant files first.
+- Confirm scope and avoid unrelated edits.
+- Prefer deterministic commands and explicit outputs.
+
+## 2) During implementation
+
+- Keep patches small and understandable.
+- Reuse existing modules/functions before adding new abstractions.
+- Add examples for new user-facing capabilities.
+
+## 3) Validation
+
+Run, at minimum, relevant checks for touched areas:
+
+```bash
+# example baseline commands
+cargo fmt --check
+cargo check
+cargo test
+```
+
+If full validation cannot run, document exactly why and what was run instead.
+
+## 4) Commit hygiene
+
+- Keep commit messages clear and specific.
+- Do not include generated binaries.
+- Include doc updates in `AI-DOCs/` for significant work.
+
+## 5) Handoff checklist
+
+- Summary of changes
+- Local verification commands
+- Expected artifacts/outputs
+- Known caveats
+

AI-DOCs/local-testing-checklist.md

@@ -0,0 +1,18 @@
+# Local Testing Checklist
+
+Use this checklist before finalizing AI-generated changes.
+
+## Quick checklist
+
+- [ ] Formatting passed
+- [ ] Build/check passed
+- [ ] Tests passed (or limitation documented)
+- [ ] Example commands run for new features
+- [ ] No binary artifacts staged
+- [ ] Notes updated in `AI-DOCs/` if needed
+
+## Output checks
+
+- Verify expected files are generated in intended output directories.
+- Confirm no generated files are accidentally tracked in git.
+

AI-DOCs/opengeometry/local-testing.md

@@ -0,0 +1,96 @@
+# OpenGeometry Local Testing Guide
+
+This file documents how to locally validate the camera projection + scenegraph pipeline implemented in this branch.
+
+## 1) Run from the Rust crate root
+
+```bash
+cd main/opengeometry
+```
+
+## 2) Build and test
+
+```bash
+cargo fmt --check
+cargo check --examples
+cargo test -q
+```
+
+Expected: build succeeds and unit tests pass.
+
+## 3) Generate projection PDFs
+
+Create an output folder:
+
+```bash
+mkdir -p ./out
+```
+
+### Perspective camera projection
+
+```bash
+cargo run --example pdf_camera_projection -- ./out/pdf_camera_projection.pdf
+```
+
+### Orthographic HLR on/off comparison
+
+```bash
+cargo run --example pdf_camera_projection_views -- ./out/pdf_camera_projection_views
+```
+
+Expected output files:
+- `./out/pdf_camera_projection_views_hlr_on.pdf`
+- `./out/pdf_camera_projection_views_hlr_off.pdf`
+
+### All supported primitives
+
+```bash
+cargo run --example pdf_primitives_all -- ./out/pdf_primitives
+```
+
+Expected output files:
+- `./out/pdf_primitives_line.pdf`
+- `./out/pdf_primitives_polyline.pdf`
+- `./out/pdf_primitives_arc.pdf`
+- `./out/pdf_primitives_rectangle.pdf`
+- `./out/pdf_primitives_polygon.pdf`
+- `./out/pdf_primitives_cuboid.pdf`
+- `./out/pdf_primitives_cylinder.pdf`
+
+### Scenegraph projection (shared projectTo2DCamera + PDF path)
+
+```bash
+cargo run --example scenegraph_projection -- ./out/scenegraph_projection.pdf
+```
+
+Expected output file:
+- `./out/scenegraph_projection.pdf`
+
+### Inspect projectTo2DCamera JSON payloads
+
+```bash
+cargo run --example scenegraph_projection_dump_json -- ./out/projection_dump
+```
+
+Expected output files:
+- `./out/projection_dump_scene2d.json` (raw `Scene2D` shape from `projectTo2DCamera`)
+- `./out/projection_dump_lines2d.json` (normalized `Scene2DLines` payload from `projectTo2DLines`)
+
+Optional pretty inspection with `jq`:
+
+```bash
+jq . ./out/projection_dump_scene2d.json
+jq . ./out/projection_dump_lines2d.json
+```
+
+## 4) Verify files were created
+
+```bash
+ls -1 ./out/*.pdf
+```
+
+## 5) Frontend / WASM note
+
+- `projectTo2DCamera` is designed for frontend usage (returns serialized 2D scene data).
+- `projectToPDF` is native-only in this crate build (`not(target_arch = "wasm32")`).
+- In browser builds, use `projectTo2DCamera` and render lines in Three.js.

AI-DOCs/opengeometry/project-to-2d-format.md

@@ -0,0 +1,74 @@
+# projectTo2D Data Format
+
+This document describes how to inspect and consume scene projection data from `OGSceneManager`.
+
+## API methods
+
+- `projectTo2DCamera(sceneId, cameraJson, hlrJson?)` -> `Scene2D` JSON string
+- `projectTo2DCameraPretty(sceneId, cameraJson, hlrJson?)` -> pretty `Scene2D` JSON string
+- `projectTo2DLines(sceneId, cameraJson, hlrJson?)` -> normalized `Scene2DLines` JSON string
+- `projectTo2DLinesPretty(sceneId, cameraJson, hlrJson?)` -> pretty normalized JSON string
+- `projectCurrentTo2DCamera(...)` / `projectCurrentTo2DLines(...)` use current scene
+
+## `Scene2D` shape
+
+```json
+{
+  "name": "Main Scene",
+  "paths": [
+    {
+      "segments": [
+        {
+          "Line": {
+            "start": { "x": -0.2, "y": 0.1 },
+            "end": { "x": 0.3, "y": 0.4 }
+          }
+        }
+      ],
+      "stroke_width": null,
+      "stroke_color": null
+    }
+  ]
+}
+```
+
+## `Scene2DLines` normalized shape (recommended for frontend rendering)
+
+```json
+{
+  "name": "Main Scene",
+  "lines": [
+    {
+      "start": { "x": -0.2, "y": 0.1 },
+      "end": { "x": 0.3, "y": 0.4 },
+      "stroke_width": null,
+      "stroke_color": null
+    }
+  ]
+}
+```
+
+## Frontend usage (Three.js lines)
+
+```ts
+const scene2dLinesJson = manager.projectTo2DLines(
+  sceneId,
+  JSON.stringify(camera),
+  JSON.stringify({ hide_hidden_edges: true })
+);
+const scene2dLines = JSON.parse(scene2dLinesJson);
+
+for (const line of scene2dLines.lines) {
+  // line.start.x, line.start.y, line.end.x, line.end.y
+  // map to your viewport scale and build Three.js LineSegments geometry
+}
+```
+
+## Local inspection
+
+```bash
+cd main/opengeometry
+cargo run --example scenegraph_projection_dump_json -- ./out/projection_dump
+jq . ./out/projection_dump_scene2d.json
+jq . ./out/projection_dump_lines2d.json
+```

README.md

@@ -23,3 +23,9 @@ Documentation is available at [OpenGeometry Documentation](https://docs.opengeom
 - Extrusion
 - Offset
 - Boolean Operations (In Progress)
+
+## AI Agent Docs Policy
+
+- Repository-level AI agent instructions are in [AGENTS.md](./AGENTS.md).
+- All AI-generated documentation must live under [`AI-DOCs/`](./AI-DOCs/).
+- AI-generated docs should not be added under app/code folders unless explicitly requested.