@linkiez/dxf-renew 7.0.0 → 7.2.0

package/.eslintrc.json

@@ -5,9 +5,7 @@
     "node": true
   },
   "extends": [
-    "plugin:react/recommended",
     "standard",
-    "standard-react",
     "prettier"
   ],
   "globals": {
@@ -21,25 +19,12 @@
     "afterEach": "readonly"
   },
   "parserOptions": {
-    "babelOptions": {
-      "presets": ["@babel/preset-react"]
-    },
-    "ecmaFeatures": {
-      "jsx": true
-    },
-    "ecmaVersion": 2018,
+    "ecmaVersion": 2020,
     "sourceType": "module"
   },
-  "plugins": ["react"],
-  "parser": "@babel/eslint-parser",
   "rules": {
     "no-lone-blocks": "off"
   },
-  "settings": {
-    "react": {
-      "version": "detect"
-    }
-  },
   "overrides": [
     {
       "files": ["*.ts", "*.tsx"],

package/.github/instructions/code-patterns.instructions.md

@@ -22,7 +22,7 @@ This document codifies the current implementation patterns used in DXF-Renewed,
 Best practices:
 
 - Prefer `import type { ... }` for type-only imports.
-- Avoid `any` in new code. If runtime constraints require it, keep it local and document why.
+- Avoid `any` or `unknown` in new code. If runtime constraints require it, keep it local and document why.
 - Keep names and comments in **English (en_US)**.
 
 ## Project Architecture (High-Level)

package/.github/instructions/exdxf.instruction.md

@@ -0,0 +1,161 @@
+---
+applyTo: '**/*'
+---
+
+# Development Instructions (DXF-Renewed) — using ezdxf
+
+This repository is a TypeScript DXF parser. For DXF fixtures, debugging, and cross-checking group codes, we use the Python library **ezdxf**.
+
+Official docs:
+
+- Setup (extras): <https://ezdxf.readthedocs.io/en/stable/setup.html#installation-with-extras>
+- Reference index: <https://ezdxf.readthedocs.io/en/stable/reference.html>
+
+## 1) Install ezdxf (recommended: local venv)
+
+Many Linux distributions use an externally-managed Python environment (PEP 668), which blocks `pip install --user`.
+Use a local virtualenv inside this repo:
+
+```bash
+cd <path-to>/DXF-Renewed
+python3 -m venv .venv-ezdxf
+. .venv-ezdxf/bin/activate
+python -m pip install -U pip
+
+# Core library
+python -m pip install -U ezdxf
+
+# Optional drawing add-on dependencies (recommended by ezdxf docs)
+python -m pip install -U 'ezdxf[draw]'
+```
+
+Extras from the ezdxf docs:
+
+- `ezdxf[draw]`: Matplotlib, PySide6, PyMuPDF, Pillow
+- `ezdxf[dev]`: `draw` + setuptools, wheel, Cython, pytest
+- If PySide6 is not available, use `ezdxf[draw5]` / `ezdxf[dev5]` (PyQt5-based)
+
+Verify:
+
+```bash
+. .venv-ezdxf/bin/activate
+python -m ezdxf -V
+```
+
+## 2) How ezdxf helps this repo
+
+Use ezdxf for:
+
+- generating **minimal DXF fixtures** for TDD (`test/resources/*.dxf`)
+- dumping **raw group-code tags** for an entity/object/table
+- checking real-world DXF parsing expectations without guessing group codes
+
+This repo’s workflow is TDD-first:
+
+- add a minimal fixture + failing unit test
+- implement parser support
+- keep `yarn test` + `yarn lint` green
+
+## 3) Inspect an existing DXF fixture
+
+Print entity types, handles, and layers:
+
+```bash
+. .venv-ezdxf/bin/activate
+python - <<'PY'
+import ezdxf
+
+doc = ezdxf.readfile('test/resources/entities.dxf')
+msp = doc.modelspace()
+
+for e in msp:
+    handle = getattr(e.dxf, 'handle', None)
+    layer = getattr(e.dxf, 'layer', None)
+    print(e.dxftype(), handle, layer)
+PY
+```
+
+## 4) Dump raw group codes (tags) for a single entity
+
+This is the most useful thing for implementing a new handler in `src/handlers/entity/*`.
+
+```bash
+. .venv-ezdxf/bin/activate
+python - <<'PY'
+import ezdxf
+from ezdxf.lldxf.tagwriter import TagCollector
+
+doc = ezdxf.readfile('test/resources/leader-basic.dxf')
+entity = next(iter(doc.modelspace()))
+
+collector = TagCollector()
+entity.export_dxf(collector)
+
+for tag in collector.tags:
+    print(tag.code, tag.value)
+PY
+```
+
+Tip: If you want to dump all entities:
+
+```bash
+. .venv-ezdxf/bin/activate
+python - <<'PY'
+import ezdxf
+from ezdxf.lldxf.tagwriter import TagCollector
+
+doc = ezdxf.readfile('test/resources/entities.dxf')
+for i, entity in enumerate(doc.modelspace()):
+    print('---', i, entity.dxftype(), '---')
+    collector = TagCollector()
+    entity.export_dxf(collector)
+    for tag in collector.tags:
+        print(tag.code, tag.value)
+PY
+```
+
+## 5) Generate a new minimal fixture (recommended pattern)
+
+If ezdxf supports the entity via `layout.new_entity()`, you can create it directly.
+
+Example: create a minimal `TOLERANCE` entity and export:
+
+```bash
+. .venv-ezdxf/bin/activate
+python - <<'PY'
+import ezdxf
+
+doc = ezdxf.new('R2010')
+msp = doc.modelspace()
+
+# Create entity by DXF type name. dxfattribs depends on entity.
+# "insert" maps to group codes 10/20/30 for many entities.
+fcf = msp.new_entity('TOLERANCE', dxfattribs={
+    'layer': '0',
+    'insert': (10, 20, 0),
+})
+
+# You can set additional attributes if supported:
+# fcf.dxf.text = '%%v%%v'
+
+out = 'test/resources/tolerance-basic.dxf'
+doc.saveas(out)
+print('wrote', out)
+PY
+```
+
+If the high-level attribute you need is unclear, use the **tag dump** technique above to learn what ezdxf writes.
+
+## 6) Run DXF-Renewed checks
+
+```bash
+cd <path-to>/DXF-Renewed
+yarn test
+yarn lint
+```
+
+## 7) Reference sitemap
+
+Curated ezdxf reference links live here:
+
+- docs/EZDXF_REFERENCE_SITEMAP.md

package/.github/instructions/tdd.instructions.md

@@ -0,0 +1,271 @@
+---
+applyTo: '**/*'
+---
+
+# Test-Driven Development (TDD) Principles - AI Instructions
+
+## Core TDD Workflow
+
+1. **RED**: Write failing test first
+2. **GREEN**: Write minimal code to pass test
+3. **REFACTOR**: Improve code while maintaining test pass
+
+## Mandatory Rules
+
+### Test-First Discipline
+
+- NEVER write production code without failing test
+- Test describes expected behavior before implementation
+- Watch test fail before writing implementation
+- Verify test passes after implementation
+
+### Minimal Implementation
+
+- Write ONLY code needed to pass current test
+- Avoid premature optimization
+- Resist implementing features without tests
+- Each test drives one specific behavior
+
+### Test Quality Standards
+
+- Tests must be deterministic (same input = same output)
+- Tests should be independent (no execution order dependency)
+- Use descriptive test names explaining expected behavior
+- One assertion concept per test (arrange, act, assert)
+
+## Test Structure Pattern
+
+```typescript
+describe('UnitUnderTest', () => {
+  // Arrange: Setup test data and mocks
+  const input = validInput();
+  const expected = expectedOutput();
+
+  // Act: Execute function/method
+  const result = functionUnderTest(input);
+
+  // Assert: Verify result matches expectation
+  expect(result).toEqual(expected);
+});
+```
+
+## Code Coverage Requirements
+
+- Aim for 100% line coverage
+- 100% branch coverage (all if/else paths)
+- 100% function coverage
+- Use Istanbul/c8 for coverage reporting
+- Uncovered code indicates missing tests
+
+## Anti-Patterns to Avoid
+
+### Do NOT
+
+- Write implementation before test
+- Write multiple tests before implementation
+- Skip watching test fail
+- Test implementation details instead of behavior
+- Couple tests to internal structure
+- Use random/non-deterministic test data
+- Share state between tests
+
+### Do NOT Cheat
+
+- Hard-coding expected results to pass tests
+- Writing `if` statements matching test inputs
+- Returning specific values for test cases
+- Example of cheating:
+  ```typescript
+  // BAD: Hard-coded for specific test
+  function calculate(a: number, b: number): number {
+    if (a === 215 && b === 300) return 85;
+    if (a === 486 && b === 600) return 114;
+    return 0;
+  }
+  ```
+
+## Mocking Strategy
+
+### When to Mock
+
+- External dependencies (APIs, databases, file system)
+- Time-dependent operations (Date.now(), timers)
+- Random operations (Math.random())
+- Complex dependencies not under test
+- Async operations (Promises, Observables)
+
+### Mock Requirements
+
+- Mock external service calls
+- Mock database queries
+- Mock file I/O operations
+- Use spy functions to verify interactions
+- Return predictable, synchronous data when possible
+
+### Mock Example
+
+```typescript
+// Mock Observable service method
+jest.spyOn(service, 'get').mockReturnValue(
+  of({
+    id: 1,
+    data: 'test',
+    toJson: () => ({ id: 1, data: 'test' }),
+  }),
+);
+```
+
+## Handling Async Operations
+
+### Observable/Promise Patterns
+
+- Use `firstValueFrom()` in implementation
+- Mock Observables with `of()` or `throwError()`
+- Properly handle async/await in tests
+- Ensure all Observables complete in tests
+
+### Timeout Prevention
+
+- Mock all external async operations
+- Avoid real HTTP calls in unit tests
+- Mock timers with `jest.useFakeTimers()`
+- Set reasonable test timeouts
+
+## Test Organization
+
+### File Structure
+
+- `*.spec.ts` for unit tests (same directory as source)
+- `*.test.ts` for integration tests
+- `*.e2e.ts` for end-to-end tests
+- One test file per source file
+
+### Test Grouping
+
+```typescript
+describe('ServiceName', () => {
+  describe('methodName', () => {
+    it('should handle valid input', () => {});
+    it('should throw on invalid input', () => {});
+    it('should return empty for edge case', () => {});
+  });
+});
+```
+
+## Regression Prevention
+
+- All tests must pass before commit
+- New features require new tests
+- Bug fixes require reproduction test
+- Refactoring must not break existing tests
+- Use CI to enforce test pass
+
+## Documentation Through Tests
+
+- Tests serve as executable documentation
+- Test names explain functionality
+- Use JSDoc comments for complex logic
+- Include usage examples in test descriptions
+
+## Performance Considerations
+
+- Unit tests should run fast (< 1s per test)
+- Mock slow operations
+- Use test parallelization
+- Avoid real database/network in unit tests
+- Integration tests can be slower
+
+## Implementation Workflow
+
+1. Write test describing one behavior
+2. Run test → verify it fails
+3. Write minimum code to pass test
+4. Run test → verify it passes
+5. Refactor if needed
+6. Run all tests → verify no regression
+7. Repeat for next behavior
+
+## Red-Green-Refactor Cycle
+
+**RED Phase:**
+
+- Write test for non-existent functionality
+- Test must fail with meaningful error
+- Verify test failure reason is correct
+
+**GREEN Phase:**
+
+- Write simplest code to make test pass
+- Don't worry about code quality yet
+- Focus only on making test green
+
+**REFACTOR Phase:**
+
+- Improve code structure
+- Remove duplication
+- Optimize performance if needed
+- All tests must remain green
+
+## Practical Example: Vending Machine Change
+
+**Requirement:** Calculate coin change for vending machine
+
+**Test 1 - Empty Case:**
+
+```typescript
+test('getChange(1,1) returns empty array', () => {
+  expect(getChange(1, 1)).toEqual([]);
+});
+```
+
+**Implementation 1:**
+
+```typescript
+function getChange(payable: number, paid: number): number[] {
+  return [];
+}
+```
+
+**Test 2 - Basic Change:**
+
+```typescript
+test('getChange(215, 300) returns [50,20,10,5]', () => {
+  expect(getChange(215, 300)).toEqual([50, 20, 10, 5]);
+});
+```
+
+**Implementation 2:**
+
+```typescript
+function getChange(payable: number, paid: number): number[] {
+  const coins = [200, 100, 50, 20, 10, 5, 2, 1];
+  const change: number[] = [];
+  let remaining = paid - payable;
+
+  for (const coin of coins) {
+    while (remaining >= coin) {
+      change.push(coin);
+      remaining -= coin;
+    }
+  }
+
+  return change;
+}
+```
+
+## Summary Checklist
+
+Before writing any production code:
+
+- [ ] Write failing test
+- [ ] Verify test fails with expected reason
+- [ ] Write minimal implementation
+- [ ] Verify test passes
+- [ ] Verify no test regressions
+- [ ] Refactor if needed
+- [ ] All tests still pass
+
+## Reference Sources
+
+Based on: https://github.com/dwyl/learn-tdd
+Key principles: Red-Green-Refactor, Test-First, Minimal Implementation

package/ARCHITECTURE.md

@@ -0,0 +1,163 @@
+# Architecture
+
+This document describes the high-level architecture of DXF-Renewed, including the parsing pipeline, denormalisation (INSERT expansion), and rendering outputs.
+
+## Goals
+
+- Parse DXF text into a typed model deterministically.
+- Expand INSERT/BLOCK references into a flattened entity list with transforms.
+- Provide multiple output formats:
+  - SVG string (`toSVG`)
+  - numeric polylines (`toPolylines`)
+  - JSON string (`toJson`)
+- Prefer "parse what we can, warn for what we can’t" over throwing, when feasible.
+
+## Project Layout
+
+- `src/` — TypeScript source
+  - `src/index.ts` — public API exports
+  - `src/Helper.ts` — convenience wrapper around parsing + denormalisation + outputs
+  - `src/parseString.ts` — main DXF text parser (routes sections)
+  - `src/handlers/` — section handlers and entity handlers
+  - `src/types/` — public type definitions
+  - `src/denormalise.ts` — INSERT expansion + transform stacking
+  - `src/toSVG.ts` — SVG renderer
+  - `src/toPolylines.ts` + `src/entityToPolyline.ts` — polyline renderer
+  - `src/toJson.ts` — JSON serializer for the parsed model
+  - `src/util/` — shared helpers (logger, XML escaping, etc.)
+- `test/` — tests and fixtures
+  - `test/unit/` — unit tests (Mocha + TSX)
+  - `test/integration-browser/` — Playwright browser rendering tests
+  - `test/resources/` — DXF fixtures
+- `docs/` — documentation and references
+- `lib/` and `dist/` — build outputs
+
+## Data Flow (End-to-End)
+
+Typical usage:
+
+1. `parseString(dxfText)` produces a `ParsedDXF` object.
+2. `denormalise(parsed)` expands block inserts and returns a flattened `Entity[]`.
+3. Render or export:
+   - `toSVG(parsed)` renders the denormalised entities into an SVG string.
+   - `toPolylines(parsed)` converts supported entities into numeric polyline arrays.
+   - `toJson(parsed)` serializes the `ParsedDXF` model into a JSON string.
+
+The `Helper` class wraps this pipeline:
+
+- Constructs from DXF text
+- Exposes `parsed` and `denormalised`
+- Exposes `toSVG()`, `toPolylines()`, and `toJson()`
+
+### Pipeline Diagram
+
+```mermaid
+flowchart LR
+  A[DXF text] --> B[parseString]
+  B --> C[ParsedDXF]
+
+  subgraph SectionHandlers[Section handlers]
+    H[HEADER]
+    T[TABLES]
+    BL[BLOCKS]
+    E[ENTITIES]
+    O[OBJECTS]
+  end
+
+  B -. routes sections .-> SectionHandlers
+  SectionHandlers -. populate .-> C
+
+  C --> D[denormalise]
+  D --> E2["Entity[] (flattened + transforms)"]
+
+  E2 --> S[toSVG]
+  E2 --> P[toPolylines]
+  C --> J[toJson]
+
+  S --> S2[SVG string]
+  P --> P2[Polyline arrays]
+  J --> J2[JSON string]
+
+  A --> HLP[Helper]
+  HLP --> C
+  HLP --> E2
+  HLP --> S2
+  HLP --> P2
+  HLP --> J2
+```
+
+## Parsing
+
+### Tuple Stream
+
+The parser converts the DXF text into a tuple stream of `[groupCode, value]` and routes it by section.
+
+### Section Routing
+
+`src/parseString.ts` is responsible for splitting tuples into sections and delegating to section handlers:
+
+- `src/handlers/header.ts`
+- `src/handlers/tables.ts`
+- `src/handlers/blocks.ts`
+- `src/handlers/entities.ts`
+- `src/handlers/objects.ts`
+
+### Entity Handlers
+
+Entity handlers live in `src/handlers/entity/*.ts` and follow a consistent pattern:
+
+- Export `TYPE` (DXF entity type string).
+- Export a `process(tuples)` function that reduces group codes into a typed entity.
+- Delegate common fields (layer, color, handle, etc.) to shared parsing helpers.
+
+Multi-entity sequences (e.g. `POLYLINE` → `VERTEX`… → `SEQEND`) are handled by sequencing logic in `src/handlers/entities.ts`.
+
+## Denormalisation (INSERT Expansion)
+
+`src/denormalise.ts` expands `INSERT` entities into the referenced BLOCK contents.
+
+Responsibilities:
+
+- Resolve INSERT → BLOCK.
+- Apply transform stacks to expanded entities.
+- Expand rectangular arrays when present.
+
+The output is a flat list of entities with an optional `transforms` stack used by renderers.
+
+## Rendering
+
+### SVG (`toSVG`)
+
+`src/toSVG.ts` renders the denormalised entities.
+
+- Uses native SVG primitives when feasible (`<circle>`, `<ellipse>`, path arcs).
+- Uses polyline approximations for entities that do not have a native SVG primitive or where approximation is acceptable.
+- Unsupported entity types are skipped with a warning.
+
+### Polylines (`toPolylines`)
+
+`src/entityToPolyline.ts` is the main conversion point for entities → polylines.
+
+- Designed to be pure: same input entity should result in the same polyline output.
+- Options (e.g., interpolation density) should be expressed via `ToPolylinesOptions`.
+
+### JSON (`toJson`)
+
+`src/toJson.ts` provides a stable way to serialize the parsed model.
+
+- Intended to represent the parsed model 1-to-1.
+- Supports pretty-printing via options.
+
+## Logging & Error Handling
+
+- Logging goes through `src/util/logger.ts`.
+- Prefer warnings over exceptions for unsupported features.
+- Parsing should remain resilient: bad/unknown codes should not crash the entire parse when possible.
+
+## Build & Test
+
+- Build: TypeScript + esbuild bundling.
+- Unit tests: Mocha executed with `tsx`.
+- Browser integration tests: Playwright (renders fixtures and captures screenshots under `test/rendered/`).
+- Functional manual viewer: Vite dev server under `test/functional/`.
+

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## 7.2.0 (2026-01-01)
+
+* Merge pull request #2 from linkiez/feature/2026.01.01 ([c01512f](https://github.com/linkiez/DXF-Renewed/commit/c01512f)), closes [#2](https://github.com/linkiez/DXF-Renewed/issues/2)
+* docs: add architecture diagram ([7f61ef2](https://github.com/linkiez/DXF-Renewed/commit/7f61ef2))
+* docs: clarify supported entities ([8cd47dc](https://github.com/linkiez/DXF-Renewed/commit/8cd47dc))
+* docs: consolidate documentation into PLAN.md ([204abf9](https://github.com/linkiez/DXF-Renewed/commit/204abf9))
+* docs: fix mermaid diagram parsing ([0cedf8d](https://github.com/linkiez/DXF-Renewed/commit/0cedf8d))
+* docs: improve README structure ([3c6659d](https://github.com/linkiez/DXF-Renewed/commit/3c6659d))
+* docs: rename plan to roadmap ([23b060e](https://github.com/linkiez/DXF-Renewed/commit/23b060e))
+* docs: update README progress ([64566b7](https://github.com/linkiez/DXF-Renewed/commit/64566b7))
+* feat: add toJson processor ([94e112c](https://github.com/linkiez/DXF-Renewed/commit/94e112c))
+* feat(entities): add handlers for additional 2D entities ([221ef8b](https://github.com/linkiez/DXF-Renewed/commit/221ef8b))
+* feat(parser): add FIELD/DIMASSOC objects and extra table types ([ef89ed7](https://github.com/linkiez/DXF-Renewed/commit/ef89ed7))
+* feat(render): support LEADER/RAY/XLINE/TRACE/SHAPE/WIPEOUT ([05a7c82](https://github.com/linkiez/DXF-Renewed/commit/05a7c82))
+* chore(tooling): remove babel/react/webpack and migrate functional tests to vite ([dd92031](https://github.com/linkiez/DXF-Renewed/commit/dd92031))
+
+## 7.1.0 (2026-01-01)
+
+* Merge pull request #1 from linkiez/feat/seqend-sequencing ([068c6e1](https://github.com/linkiez/DXF-Renewed/commit/068c6e1)), closes [#1](https://github.com/linkiez/DXF-Renewed/issues/1)
+* docs: add ezdxf reference sitemap and dev instructions ([859da63](https://github.com/linkiez/DXF-Renewed/commit/859da63))
+* docs: add SVG rendering integration testing docs ([5bb0dbb](https://github.com/linkiez/DXF-Renewed/commit/5bb0dbb))
+* docs: clarify type safety guidance ([dc01286](https://github.com/linkiez/DXF-Renewed/commit/dc01286))
+* docs: consolidate documentation and plan ([2f4f01e](https://github.com/linkiez/DXF-Renewed/commit/2f4f01e))
+* docs: switch to main-only workflow ([6098ad6](https://github.com/linkiez/DXF-Renewed/commit/6098ad6))
+* docs: update dimension docs and test guidance ([c171703](https://github.com/linkiez/DXF-Renewed/commit/c171703))
+* chore: ignore local ezdxf venv ([053e4c4](https://github.com/linkiez/DXF-Renewed/commit/053e4c4))
+* chore(fixtures): add ezdxf validation tooling ([c81c871](https://github.com/linkiez/DXF-Renewed/commit/c81c871))
+* chore(fixtures): regenerate DXF fixtures via ezdxf ([7c6876d](https://github.com/linkiez/DXF-Renewed/commit/7c6876d))
+* chore(tests): track rendered screenshots ([ebcd1f1](https://github.com/linkiez/DXF-Renewed/commit/ebcd1f1))
+* test(dimension): add fixtures for all dimension types ([6b5f9cf](https://github.com/linkiez/DXF-Renewed/commit/6b5f9cf))
+* test(integration): add node DIMENSION SVG rendering test ([820efc6](https://github.com/linkiez/DXF-Renewed/commit/820efc6))
+* test(integration): run SVG rendering tests in browser ([b0abe31](https://github.com/linkiez/DXF-Renewed/commit/b0abe31))
+* feat(dimension): add angular 3-point rendering ([a9ee537](https://github.com/linkiez/DXF-Renewed/commit/a9ee537))
+* feat(entities): add image, underlay, leader, and tolerance support ([7f17e47](https://github.com/linkiez/DXF-Renewed/commit/7f17e47))
+* feat(objects): add handle maps for common DXF objects ([7672211](https://github.com/linkiez/DXF-Renewed/commit/7672211))
+* style: normalize import ordering ([55d54c1](https://github.com/linkiez/DXF-Renewed/commit/55d54c1))
+* fix(denormalise): apply block basepoint to TEXT/MTEXT/DIMENSION ([1ee560e](https://github.com/linkiez/DXF-Renewed/commit/1ee560e))
+* fix(parser): harden POLYLINE sequencing ([7eb1fb7](https://github.com/linkiez/DXF-Renewed/commit/7eb1fb7))
+
 ## 7.0.0 (2025-12-31)
 
 * fix: consolidar tipos ParsedDXF e corrigir incompatibilidades ([804c485](https://github.com/linkiez/DXF-Renewed/commit/804c485))