laser-cutter 1.0.5 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 3a3d7b723ed7171e84a93783545f037adeeeb122
-  data.tar.gz: d3571947154cda05176e1d1bbb84d8d2ee140c02
+SHA256:
+  metadata.gz: 140ec85d7822779ce6cf52830e4d462252bda1d9b03f0f45c433a68c381e08ac
+  data.tar.gz: 6f103d783a2b0de67eeba6491fac047029e52fec5ffe824dd0508481d8fcd41a
 SHA512:
-  metadata.gz: 870c36a4b07b2d4190076c524917f4322d599c58f5ff9b226b47e00a011dd63f722a7153ed885c192cbe0caefbda17fb150269a7822f4e36a001f4913a435d19
-  data.tar.gz: 67c264109139865d62292cb8cea2573ec5dbc569fec92316b00a14f942c0ea15d096d0391d1a5a275e3eaf78c7f9f8f179e95331f93859df982f7c7a80589e08
+  metadata.gz: 1e465b0c64a35fbbc397e0d98fccb520ae1fb0e8bb6fc073be86cf4fa80b141461ee238f7dcd8d77e8380f9c4043ac86a86efbecf9a380a4b1db2bcd0a7a0fd5
+  data.tar.gz: 9946ba8635c743ca01a7d458d3622037ea7bf811631bcda87c96a8c94398941ff6931809a46ec57624eefd1d1827036fff50155b8dd8492d60b23265bb3f1376

data/.envrc

@@ -0,0 +1,2 @@
+PATH_add bin
+PATH_add exe

data/.github/workflows/lint.yml

@@ -0,0 +1,22 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: [4.0.6]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Run Specs
+      run: |
+        bundle check || bundle install -j 4
+        bundle exec rubocop

data/.github/workflows/rspec.yml

@@ -0,0 +1,22 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: [4.0.6]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Run Specs
+      run: |
+       bundle check || bundle install -j 4
+       bundle exec rspec --format documentation

data/.gitignore

@@ -1,5 +1,6 @@
 **.pdf
 **.DS_Store
+.rspec_status
 **/*.swp
 *.gem
 *.rbc
@@ -9,8 +10,6 @@
 Gemfile.lock
 InstalledFiles
 _yardoc
-coverage
-lib/bundler/man
 pkg
 rdoc
 spec/reports
@@ -23,6 +22,7 @@ tmp
 *.a
 mkmf.log
 .idea/
-**output.pdf
-.ruby_version
-doc
+.ruby-lsp
+/coverage
+!docs/coverage/
+/doc

data/.plans/001.00-dry-cli-migration/plan.md

@@ -0,0 +1,29 @@
+# 001.00 Migrate the CLI to dry-cli, load with Zeitwerk
+
+Branch `kig/migrate-to-dry-cli`, off `kig/2.0.0-alpha`; the PR targets `kig/2.0.0-alpha`.
+
+## Decisions
+
+- `lib/laser_cutter/` moves to `lib/laser/cutter/`, loaded by `Zeitwerk::Loader.for_gem_extension(Laser)`, eager-loaded. `lib/laser-cutter.rb` and `lib/laser_cutter.rb` remain as shims.
+
+- `generate` takes height as `-H` / `--height`: dry-cli owns `-h`, and `-v` means verbose. `version` answers to `-V` / `--version`.
+
+- Ruby 4.0.6, pinned in `.ruby-version`.
+
+- The executables move from `bin/` to `exe/` and call `Laser::Cutter::Launcher`.
+
+- Help and boxes share one width, 90 columns or fewer; a progress bar is 60 cells.
+
+- `--inside-box` draws the unkerfed outline, which `--debug` used to do by accident; `--debug` is gone, `--verbose` prints the backtrace.
+
+## Work
+
+- [x] Zeitwerk: one constant per file (split `configuration.rb` and `path_generator.rb`, move `geometry/shape/{line,rect}.rb` up), eager load
+- [x] dry-cli with dry-cli-help, dry-cli-ui and dry-cli-autocomplete; commands `generate`, `page-sizes`, `examples`, `help`, `version`, `completion`
+- [x] `generate -f/--format pdf|svg`, PDF by default
+- [x] Green progress bar, at most 60 cells wide, advancing once per line drawn
+- [x] SVG output through `victor`
+- [x] Launcher plus in-process Aruba suite
+- [x] Bug: a notch that divides the sides exactly (4x3x2, notch 0.5) makes adjacent sides mismatch
+- [x] README and CLAUDE.md updated
+- [x] Bug: PageManager read the default Symbol units as millimeters

data/.plans/002.00-lid-options/plan.md

@@ -0,0 +1,45 @@
+# 002.00 Lid options: notched on one side, or plain
+
+Branch `kig/add-lid-options`, off `master`; the PR targets `master`. Released as 2.0.1.
+
+## Goal
+
+A box whose lid lifts off. Today the lid (the `top` panel) is notched on all four sides and can only be glued shut.
+
+## Decisions
+
+Answered by Konstantin on 2026-09-30:
+
+- The lid rests on top of the walls. Where a lid edge is plain, the wall edge under it is straight at the inner height `H`, and the lid reaches the outer footprint.
+- The lid notched on one side joins the **back** wall, always.
+- The option is `--lid full|back|plain`, `-L`, `full` by default. `full` draws exactly what 2.0.0 drew.
+
+Decided without an answer (he had gone to bed), so worth a look in review:
+
+- In `back` and `plain` the lid owns all four top corner squares, so no wall rises above `H` at a corner. In `back` the lid's two back corners are the feet either side of its notched edge.
+- The internal height stays `H` in every mode: the underside of the lid is at `H`.
+- The layout does not move. A wall without its tabs leaves its old space unused.
+
+## Geometry
+
+Faces are laid out in a column (`top`, `front`, `bottom`, `back`) with `left` and `right` beside `front`. A `Rect`'s sides run 0 bottom, 1 right, 2 top, 3 left. The lid's joints:
+
+| Lid side | Wall    | Wall side |
+| :------- | :------ | :-------- |
+| 0        | `back`  | 2         |
+| 1        | `right` | 0         |
+| 2        | `front` | 0         |
+| 3        | `left`  | 0         |
+
+- A plain wall edge is the edge's **inside** line. The sides next to it lose the corner box, and its kerf fix-ups, at that end only.
+- A plain lid edge is the edge's **outside** line.
+- Kerf grows every outline by half the kerf, as it does for notches.
+
+## Work
+
+- [x] `Configuration`: `lid`, default `full`, rejected by `validate!` when unknown
+- [x] `Notching::Edge` and `PathGenerator`: a corner box per end, not per edge
+- [x] `Box`: per-face outlines; plain and back lids; straight wall edges
+- [x] `generate --lid`, README, CLAUDE.md
+- [x] Specs: each outline against an independent even-odd oracle, with and without kerf
+- [x] Version 2.0.1

data/.plans/003.00-ruby-api/plan.md

@@ -0,0 +1,37 @@
+# 003.00 A Ruby API for MakeABox.io
+
+Branch `kig/add-ruby-api-facade`, off `master` once 002.00 had merged; the API carries the lid that plan added.
+
+## Goal
+
+MakeABox.io, a Rails application, draws boxes in-process. It must not shell out to `laser-cutter`, and it must be able to ask for any lid.
+
+## What 2.0.0 already allowed
+
+`Configuration.new(hash)`, `validate!`, `Renderer::LayoutRenderer.new(config).render` and `PageManager#page_size_values` are what the website calls today against 1.0.3, and all still work. Two things were missing:
+
+- A renderer could only write to `config.file`. A controller wants the bytes.
+- `validate!` demanded `file`, so a caller with no file had to invent one.
+- `Configuration` is a Mash: it takes any key and any value, and says nothing until a renderer trips over it.
+
+## Decisions
+
+- Asked for by Konstantin mid-way: the facade takes every option as a **typed class**. That is `Laser::Cutter::Options`, a strict `Dry::Struct` with its types in `Laser::Cutter::Types`. dry-struct becomes a runtime dependency.
+- `Laser::Cutter.render(options)` returns the document as a String. No file is needed or written.
+- `Laser::Cutter.write(options)` writes it to `options.file`. Without a format, the extension of the file decides.
+- Both take an `Options`, or a Hash they turn into one, and pass a block through as the per-line callback.
+- `Options` coerces Strings, reads a blank String as left out, and refuses unknown keys. A missing dimension raises `MissingOption`, with the message `Configuration#validate!` gives, since the website rewrites that message. Anything else raises `InvalidOption`.
+- The `--box` shorthand is not an attribute: it is a way to type four options, not a fifth.
+- Renderers answer `document`, the String; `render` writes it to `config.file` as before.
+- `Configuration` also reads a blank lid as the default, for callers still building one by hand.
+- "The two lid types (or none)" is read as `back`, `plain`, or no lid setting at all, which is `full`. A box with no lid panel is not part of this.
+- Requiring the gem still loads dry-cli and the commands. Harmless in a Rails process; splitting the CLI out of the default require is left for later.
+- The command line keeps building a `Configuration` itself; it is not moved onto `Options` here.
+
+## Work
+
+- [x] `document` on both renderers
+- [x] `Types` and `Options`
+- [x] `Laser::Cutter.render` and `Laser::Cutter.write`
+- [x] Specs, including Strings from a form and the calls the website makes today
+- [x] README section, CLAUDE.md

data/.relaxed_rubocop.yml

@@ -0,0 +1,153 @@
+# Relaxed.Ruby.Style
+## Version 2.5
+
+Style/Alias:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylealias
+
+Style/AsciiComments:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleasciicomments
+
+Style/BeginBlock:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylebeginblock
+
+Style/BlockDelimiters:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleblockdelimiters
+
+Style/CommentAnnotation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylecommentannotation
+
+Style/Documentation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styledocumentation
+
+Layout/DotPosition:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutdotposition
+
+Style/DoubleNegation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styledoublenegation
+
+Style/EndBlock:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleendblock
+
+Style/FormatString:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleformatstring
+
+Style/IfUnlessModifier:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleifunlessmodifier
+
+Style/Lambda:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylelambda
+
+Style/ModuleFunction:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylemodulefunction
+
+Style/MultilineBlockChain:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylemultilineblockchain
+
+Style/NegatedIf:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenegatedif
+
+Style/NegatedWhile:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenegatedwhile
+
+Style/NumericPredicate:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenumericpredicate
+
+Style/ParallelAssignment:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleparallelassignment
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylepercentliteraldelimiters
+
+Style/PerlBackrefs:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleperlbackrefs
+
+Style/Semicolon:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesemicolon
+
+Style/SignalException:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesignalexception
+
+Style/SingleLineBlockParams:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesinglelineblockparams
+
+Style/SingleLineMethods:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesinglelinemethods
+
+Layout/SpaceBeforeBlockBraces:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutspacebeforeblockbraces
+
+Layout/SpaceInsideParens:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutspaceinsideparens
+
+Style/SpecialGlobalVars:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylespecialglobalvars
+
+Style/StringLiterals:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylestringliterals
+
+Style/TrailingCommaInArguments:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainarguments
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainarrayliteral
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainhashliteral
+
+Style/SymbolArray:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylesymbolarray
+
+Style/WhileUntilModifier:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylewhileuntilmodifier
+
+Style/WordArray:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylewordarray
+
+Lint/AmbiguousRegexpLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#lintambiguousregexpliteral
+
+Lint/AssignmentInCondition:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#lintassignmentincondition
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics:
+  Enabled: false
+

data/.rspec

@@ -1,2 +1,3 @@
 --color
 --format progress
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,31 @@
+inherit_from:
+  - .rubocop_todo.yml
+  - .relaxed_rubocop.yml
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 4.0
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: false
+
+Lint/StructNewOverride:
+  Enabled: false
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_first_argument
+
+Naming/MethodParameterName:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,90 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2026-09-29 22:33:21 UTC using RuboCop version 1.91.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'laser-cutter.gemspec'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Lint/CopDirectiveSyntax:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+# Offense count: 1
+# Configuration parameters: DelegatingMethods, AllowedCrossFilePaths.
+# DelegatingMethods: delegate
+Lint/DuplicateMethods:
+  Exclude:
+    - 'lib/laser/cutter/geometry/shape.rb'
+
+# Offense count: 2
+# Configuration parameters: AllowedParentClasses.
+Lint/MissingSuper:
+  Exclude:
+    - 'lib/laser/cutter/geometry/line.rb'
+    - 'lib/laser/cutter/renderer/meta_renderer.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Lint/RedundantCopDisableDirective:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+# Offense count: 3
+Lint/RescueException:
+  Exclude:
+    - 'lib/laser/cutter/cli/serializer.rb'
+    - 'spec/laser/cutter/renderer/layout_renderer_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: ExpectMatchingDefinition, CheckDefinitionPathHierarchy, CheckDefinitionPathHierarchyRoots, Regex, IgnoreExecutableScripts, AllowedAcronyms.
+# CheckDefinitionPathHierarchyRoots: lib, spec, test, src
+# AllowedAcronyms: CLI, DSL, ACL, API, ASCII, CPU, CSS, DNS, EOF, GUID, HTML, HTTP, HTTPS, ID, IP, JSON, LHS, QPS, RAM, RHS, RPC, SLA, SMTP, SQL, SSH, TCP, TLS, TTL, UDP, UI, UID, UUID, URI, URL, UTF8, VM, XML, XMPP, XSRF, XSS
+Naming/FileName:
+  Exclude:
+    - 'Rakefile.rb'
+    - 'lib/laser-cutter.rb'
+
+# Offense count: 3
+# Configuration parameters: ForbiddenDelimiters.
+# ForbiddenDelimiters: (?i-mx:(^|\s)(EO[A-Z]{1}|END)(\s|$))
+Naming/HeredocDelimiterNaming:
+  Exclude:
+    - 'lib/laser/cutter/cli/opt_parser.rb'
+    - 'lib/laser/cutter/renderer/meta_renderer.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: MaxUnannotatedPlaceholdersAllowed, Mode, AllowedMethods, AllowedPatterns.
+# SupportedStyles: annotated, template, unannotated
+Style/FormatStringToken:
+  EnforcedStyle: unannotated
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: always, always_true, never
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - '**/*.arb'
+    - 'lib/laser/cutter/page_manager.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/MapToHash:
+  Exclude:
+    - 'lib/laser/cutter/configuration.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: Mode.
+Style/StringConcatenation:
+  Exclude:
+    - 'lib/laser/cutter/renderer/meta_renderer.rb'

data/.ruby-version

@@ -0,0 +1 @@
+4.0.6

data/CLAUDE.md

@@ -0,0 +1,75 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`laser-cutter` is a Ruby gem and CLI that generates a PDF of the six notched panels of a box. You cut the panels on a laser cutter and they snap together. Prawn renders the PDF. The notch algorithm favors **symmetric** panels over identical notch lengths.
+
+## Commands
+
+The `justfile` drives everything. Its recipes wrap `bundle exec` in `eval "$(rbenv init - bash)"`. `.ruby-version` and CI pin Ruby **4.0.6**; dry-cli-help and dry-cli-ui need 4.0.
+
+```bash
+just lint                     # rubocop
+just format                   # rubocop -a, plus mdformat on every *.md
+just test                     # rspec (progress format, random order)
+just test spec/laser/cutter/edge_spec.rb:42   # one file or example
+just test-docs                # rspec --format documentation
+just ci                       # lint + test-coverage
+just doc                      # YARD docs
+```
+
+- `bundle exec rspec`, `bundle exec rubocop` and `bundle exec rake` (default task `spec`) also work.
+- Every rspec run rewrites `docs/badges/coverage_badge.svg` through the SimpleCov `at_exit` hook in `spec/spec_helper.rb`. That file shows up in `git status` after any test run.
+- `spec_helper.rb` fails the run under 95% line coverage. The Aruba suite in `spec/laser/cutter/cli_spec.rb` counts towards it.
+
+## Architecture
+
+Everything lives under `Laser::Cutter`, in `lib/laser/cutter/`. `lib/laser/cutter.rb` requires the third-party gems, then sets up `Zeitwerk::Loader.for_gem_extension(Laser)` and **eager-loads** it. So: one constant per file, the file name matches the constant, and no `require` between the gem's own files. `lib/laser-cutter.rb` and `lib/laser_cutter.rb` are shims.
+
+Pipeline, from config to file:
+
+1. **`Configuration`** is a `Hashie::Mash` with symbolized keys. It parses the `--box WxHxD/T[/N]` shorthand, casts numeric strings to floats, and merges per-unit defaults for kerf, margin, padding and stroke. Notch defaults to `3 × thickness`. `validate!` raises `MissingOption` / `ZeroValueNotAllowed`, and `InvalidOption` for a lid it does not know. `units` defaults to the Symbol `:in`, and arrives as a String from the command line, so compare it with `to_s` or `to_sym`.
+1. **`Renderer.for(format, config)`** picks `LayoutRenderer` (PDF, Prawn) or `SvgRenderer` (SVG, Victor). Both answer `total` (lines to draw) and `render { |line| }`, which yields after each line. That block drives the progress bar.
+   - `LayoutRenderer` draws a `BoxRenderer`, a `MetaRenderer` when `config.metadata` is set, and a second red `BoxRenderer` without kerf when `config.debug` is set. It sizes the page from the box enclosure unless `page_size` is given.
+   - `SvgRenderer` fits the page to the box, flips y (SVG counts down from the top), and writes the metadata as a `<desc>`.
+1. **`Box`** models the six faces as `Geometry::Rect`s. `position_faces!` lays them out in a cross (see the ASCII diagram in that method). `generate_notches` pairs each side of a face with the matching side of its outer bounding rect (face grown by `thickness`) as a **`Notching::Edge`**. The `conf` table sets per-face alignment: `valign`/`halign` decide whether a side's center notch points `:out` or `:in`. `corners` plus `pick_corners_face` decide which face fills the corner squares.
+   - `lid` (`full`, `back`, `plain`) sets how the `top` panel joins the walls. A plain lid edge is the edge's **outside** line, and the wall side under it (`LID_SIDES`) is the edge's **inside** line, so the lid lies on walls that end at the inner height. The lid then owns the corners above the walls: `corner_ends` strips the corner box from the wall sides that touch it.
+   - `outlines` holds the merged lines of each face by name; `notches` is all of them, flattened.
+1. **`Notching::Edge`** holds the inside and outside lines of one side, both shifted by `kerf / 2`. `calculate_notch_width!` forces an **odd** notch count of at least 3 and recomputes the real notch width, so the requested notch is only a guide. It rounds `length / notch` to `RATIO_DIGITS` before `ceil`: two panels meeting at a joint must get the same count, and float noise used to split them when the notch divided the side exactly.
+1. **`Notching::PathGenerator`** turns an `Edge` into `Geometry::Line`s. It zigzags between the inside and outside lines using `Shift` deltas from two alternating `InfiniteIterator`s. It widens or narrows notches by `kerf` and adds the corner boxes, at the ends the edge names in `corner_ends`. Kerf grows every outline by half the kerf on every side; `spec/laser/cutter/box_lid_spec.rb` checks exactly that, point by point, through `spec/support/outline.rb`.
+1. **`Aggregator`** merges the lines of a face into the outline to cut. Neighbouring edges draw shared stretches twice, and a shared stretch runs through the material, so each collinear group is combined as a symmetric difference: a point is cut when an odd number of lines cover it. It groups lines by axis and offset and sweeps each group once, so a face takes n log n; the old pairwise version made a 100×80×60 box take 55 seconds.
+
+Geometry is unitless, in the config's units. Conversion to PDF points happens only at render time (`value.send(:in)` / `.send(:mm)`). `PageManager#value_from_units` converts PDF points back.
+
+### Ruby API
+
+- `Laser::Cutter.render(options)` returns the document as a String, and `Laser::Cutter.write(options)` writes it to `options.file`. Both live in `lib/laser/cutter.rb`, take an `Options` or a Hash, and pass a block through as the per-line callback. MakeABox.io calls these; keep them working without a file, a terminal or the CLI classes.
+- `Options` (`options.rb`) is a strict `Dry::Struct`, one attribute per `generate` option, with its types in `Types` (`types.rb`). It raises `MissingOption` for a missing dimension and `InvalidOption` for anything else, and turns into a `Configuration` with `to_configuration`. A new `generate` option needs an attribute here too.
+- Renderers answer `document`, the String. `Renderer::Base#render` writes it to `config.file`.
+
+### Command line
+
+- `exe/laser-cutter` (and `exe/lc`) call `Laser::Cutter::Launcher.new(ARGV).execute!`. The Launcher takes argv, the three streams and `kernel`, and exits only through `kernel.exit`. Aruba runs it in-process (`spec/support/aruba.rb`), so commands must write to `out` and `err`, never to `$stdout`.
+- `CLI` (`cli.rb`) is the dry-cli registry and the `Dry::CLI::Help.configure` block. Commands live in `cli/`: `generate`, `page-sizes`, `examples`, `help`, `version`, `completion`.
+- Every message goes through `ui`: errors in `ui.error` boxes on STDERR (the Launcher draws them), `generate` opens with `ui.info` and closes with `ui.success`.
+- `CLI::Command` is the base: it includes `Dry::CLI::UI`, declares `-v`, and offers `progress(label, total:)`, a green bar of 60 cells. Help and boxes share one width, `CLI.help_width`: the terminal's less 6, and 90 at most.
+- `-h` belongs to help, so height is `-H`.
+
+## Known gaps
+
+- `generate` declares defaults for `--units` and `--page-layout`, and they override what `-R` reads from a saved configuration. `--lid` has no dry-cli default for that reason.
+
+- `just build` is an empty recipe, so `just publish` builds nothing. `rake build` is the real build.
+
+- The `Rakefile` YARD title is copied from another project, and it references a `CHANGELOG.md` that does not exist.
+
+- The gemspec lists `tty-*` and `pastel` directly, though only dry-cli-ui uses them.
+
+- `Box` still carries the comment "badly needs refactoring and tests".
+
+## Conventions
+
+- `.rubocop.yml` inherits `.relaxed_rubocop.yml` and `.rubocop_todo.yml`, with a 120-column line limit and table-aligned hashes.
+- Specs mirror `lib/` under `spec/laser/cutter/` and use `rspec-its`, `disable_monkey_patching!` and random order.

data/CONTRIBUTING.md

@@ -1,5 +1,4 @@
-Contributing to Laser-Cutter
-======================
+# Contributing to Laser-Cutter
 
 You're encouraged to submit [pull requests](https://github.com/kigster/laser-cutter/pulls), [propose features and discuss issues](https://github.com/kigster/laser-cutter/issues).
 
@@ -34,8 +33,7 @@ bundle exec rake
 
 #### Write Tests
 
-Try to write a test that reproduces the problem you're trying to fix or describes a 
-feature that you want to build. Add to [spec/laser-cutter](spec/laser-cutter).
+Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build. Add to [spec/laser-cutter](spec/laser-cutter).
 
 We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
 

data/Gemfile

@@ -1,5 +1,19 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in laser-cutter-cutter.gemspec
 gemspec
 
+group 'development', 'test' do
+  gem 'aruba'
+  gem 'coverage-badge'
+  gem 'rake'
+  gem 'rspec'
+  gem 'rspec-its'
+  gem 'rubocop', require: false
+  gem 'rubocop-rake', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov'
+  gem 'yard'
+end