Spec: Complete Taprats pen-plot artwork and recoverable job workflow

[jamiejk]

Problem Statement

Patternmaker has an unfinished Taprats integration that can load bundled tilings and generate vector layers, but its current behavior does not yet form a reliable physical plotting workflow. Source-tile construction geometry is plotted by default, preview colours are disconnected from pen passes, concentric fills are approximate centroid scaling rather than constant-distance insets, and path optimization can destroy the predictable spatial order needed while manually depositing ink into wet regions.

The application also lacks a durable boundary between editable plot artwork and the exact job sent to the remote plotter server. A failed send cannot be recovered reliably, previous output cannot be resent without regeneration, and the settings that produced an SVG are not archived with it.

The user needs Patternmaker to turn the bundled Taprats source tilings into trustworthy plot artwork: previewable, physically drawable, predictably ordered, exportable as one structured SVG, and recoverable from a local job archive.

Solution

Patternmaker will treat bundled Taprats tilings as source geometry for pen-plotter artwork rather than trying to reproduce the full TiledPatternMaker application.

A newly selected source tiling will produce motif-only plot artwork by default. The user can assign a plot treatment and intended colour to each tile type. Intended colour will be the source of truth for both the preview and colour-based pen passes. The application will offer an idealized Artwork preview and an authoritative Path preview, defaulting to the latter.

Plot fills will be physically drawable interior paths. Concentric fills will use true constant-distance inward offsets; parallel hatching will remain available. Paths will be clipped to the printable area and organized first by intended colour, then into fill-before-linework phases. Each phase will restart at the configured hand-safe sweep origin. Concentric regions will remain intact and plot outermost-to-innermost so the maker can predict where to deposit ink while the region remains wet.

A user action will prepare and freeze an immutable plot job. Each prepared job will contain one authoritative SVG with all colour passes and ordered phases plus one companion JSON record. Patternmaker will archive the pair locally as a draft before transmission and mark it sent only after the plotter server acknowledges receipt. Resend will use the archived payload exactly; Recreate will start a new editable draft from archived settings.

User Stories

1. As a pen-plotter artist, I want to choose from the bundled Taprats tilings, so that I can build artwork from established geometric source material.
2. As a pen-plotter artist, I want unsupported bundled tilings to report an explicit reason, so that I never mistake a silent parser failure for an empty design.
3. As a pen-plotter artist, I want a new source tiling to default to motif-only output, so that construction geometry is not plotted accidentally.
4. As a pen-plotter artist, I want plot treatment to apply by tile type, so that repeated instances remain consistent without per-face editing.
5. As a pen-plotter artist, I want None treatment to retain motif derivation without adding construction geometry, so that motif-only output is explicit.
6. As a pen-plotter artist, I want Outline treatment to add tile-type boundaries, so that selected construction geometry can become artwork.
7. As a pen-plotter artist, I want Fill treatment to add only interior drawable paths, so that it does not secretly include an outline.
8. As a pen-plotter artist, I want Outline + Fill treatment to include both boundary and interior paths, so that the two choices compose predictably.
9. As a pen-plotter artist, I want Hidden treatment to exclude a tile type from motif, outline, and fill output, so that unwanted geometry contributes nothing.
10. As a pen-plotter artist, I want changing source tilings to reset tile-type treatments and colours, so that incompatible tile definitions do not inherit stale settings.
11. As a pen-plotter artist, I want global paper, pen, motif, preview, and plot-order settings preserved when changing source tilings, so that unrelated choices are not lost.
12. As a pen-plotter artist, I want motif settings to apply globally, so that the artwork remains coherent and the controls remain manageable.
13. As a pen-plotter artist, I want invalid motif paths omitted with a visible warning, so that valid output can still be used.
14. As a pen-plotter artist, I want export and plotting blocked only when the complete artwork is empty, so that one invalid component does not discard valid paths.
15. As a pen-plotter artist, I want an Artwork preview showing intended colours and simplified coloured regions, so that I can judge the planned visual result.
16. As a pen-plotter artist, I want a Path preview showing exact drawable paths, so that I can inspect what will physically be plotted.
17. As a pen-plotter artist, I want Path preview selected by default, so that the initial view is authoritative.
18. As a pen-plotter artist, I want intended colours to appear consistently in both preview modes, so that the screen communicates planned pen usage.
19. As a pen-plotter artist, I want each plotted component to have an intended colour, so that it can be assigned to a physical pen pass.
20. As a pen-plotter artist, I want paths with the same intended colour grouped into one pen pass, so that I do not perform unnecessary pen changes.
21. As a pen-plotter artist, I want component identity retained as metadata after colour grouping, so that motif, outline, and plot-fill paths remain inspectable.
22. As a pen-plotter artist, I want one active pen profile to define physical pen characteristics for all passes initially, so that colour grouping does not prematurely require a per-colour pen library.
23. As a pen-plotter artist, I want plot-fill spacing derived from the active nib width, so that path density reflects the physical pen.
24. As a pen-plotter artist, I want an explicit fill-spacing override, so that I can tune deposition experimentally.
25. As a pen-plotter artist, I want concentric plot fills to use constant-distance inward offsets, so that irregular regions receive consistent physical spacing.
26. As a pen-plotter artist, I want concentric fills to omit the boundary, so that the boundary appears only when Outline is selected.
27. As a pen-plotter artist, I want parallel hatch plot fills as an alternative, so that I can choose conventional shading.
28. As a pen-plotter artist, I want the source tiling repeated over the entire printable area, so that the page is fully covered.
29. As a pen-plotter artist, I want all drawable paths clipped to the printable boundary, so that no path crosses into the margins.
30. As a pen-plotter artist, I want partial edge geometry retained and cleanly clipped, so that full-area coverage does not create an irregular inset.
31. As a pen-plotter artist, I want scale expressed as a physical repeat size in millimetres, so that the same value means the same density across paper sizes.
32. As a pen-plotter artist, I want Auto scale to start around six repeats across the shorter printable dimension, so that new artwork begins at a useful density.
33. As a pen-plotter artist, I want Auto scale visually validated across representative paper sizes and tiling complexities, so that its default is practical rather than arbitrary.
34. As a pen-plotter artist, I want predictable hand-safe spatial ordering within every colour pass, so that I can deposit ink safely while plotted regions are wet.
35. As a pen-plotter artist, I want predictability to take precedence over minimum pen-up travel, so that path optimization does not undermine the physical workflow.
36. As a pen-plotter artist, I want each concentric region kept as an uninterrupted group, so that the plotter does not return later across wet work.
37. As a pen-plotter artist, I want concentric paths plotted outermost-to-innermost, so that a newly bounded region is immediately available for ink deposition.
38. As a pen-plotter artist, I want plot fills drawn before linework within each colour pass, so that structural strokes do not precede the wet-fill workflow.
39. As a pen-plotter artist, I want optional linework drawn as a later phase, so that I can add motif and outlines after fills.
40. As a pen-plotter artist, I want a master linework control, so that I can enable or disable all linework without losing individual motif and outline choices.
41. As a pen-plotter artist, I want linework enabled by default, so that the motif-only default remains visible and drawable.
42. As a pen-plotter artist, I want every phase to restart from the configured sweep origin, so that phase movement remains predictable.
43. As a pen-plotter artist, I want one complete job sent to the remote plotter server, so that pass and phase order remain intact.
44. As a pen-plotter artist, I want the plotter server to own starting, pausing, and supervising execution, so that Patternmaker does not duplicate remote machine controls.
45. As a pen-plotter artist, I want export to produce one authoritative SVG, so that there is one exact representation of the prepared job.
46. As a pen-plotter artist, I want the SVG grouped by colour pass and then by ordered phase, so that its physical execution structure is explicit.
47. As a pen-plotter artist, I want the SVG to retain component metadata, so that motif, outline, and fill paths remain identifiable.
48. As a pen-plotter artist, I want SVG dimensions and coordinates expressed in physical millimetres, so that output matches the selected paper.
49. As a pen-plotter artist, I want SVG paths to use intended colour, the active nib width, and fill=none, so that visual inspection reflects the physical centreline job.
50. As a pen-plotter artist, I want centreline paths to remain authoritative, so that stroke widths are not expanded into alternate geometry.
51. As a pen-plotter artist, I want to name a job before preparing it, so that archived work is recognizable.
52. As a pen-plotter artist, I want Prepare Job to freeze the exact payload, so that later UI edits cannot change what will be sent.
53. As a pen-plotter artist, I want preparation to create a local draft before transmission, so that network failure cannot destroy the job.
54. As a pen-plotter artist, I want each archived job to contain exactly one SVG and one JSON file, so that the archive remains simple and authoritative.
55. As a pen-plotter artist, I want the JSON to contain job identity, status, timestamps, schema and generator versions, complete generating parameters, pass/phase ordering, SVG filename, and checksum, so that the SVG can be verified and understood later.
56. As a pen-plotter artist, I want timestamped, sanitized folder and file names plus an immutable identifier, so that jobs are readable and collision-safe.
57. As a pen-plotter artist, I want to choose a local archive directory, so that Patternmaker does not burden the plotter server with storage.
58. As a pen-plotter artist, I want a ZIP download fallback when direct folder access is unavailable, so that I can still prepare and preserve jobs.
59. As a pen-plotter artist, I want prepare-and-send to remain available with ZIP fallback, so that browser capability does not block plotting.
60. As a pen-plotter artist, I want a warning when Patternmaker cannot later update local status without directory access, so that archive limitations are explicit.
61. As a pen-plotter artist, I want a job marked sent only after a successful server response, so that archive status reflects acknowledged delivery.
62. As a pen-plotter artist, I want local archive failure reported separately after successful remote delivery, so that Patternmaker never resends automatically and risks a duplicate job.
63. As a pen-plotter artist, I want failed transmissions to remain archived as drafts, so that they can be retried safely.
64. As a pen-plotter artist, I want retry and Resend to transmit the exact frozen SVG and metadata, so that sequence and geometry remain unchanged.
65. As a pen-plotter artist, I want an SVG checksum verified before Resend, so that corrupt or edited archives are not transmitted unknowingly.
66. As a pen-plotter artist, I want checksum-mismatched archives viewable but blocked from Resend, so that damage is visible and safe.
67. As a pen-plotter artist, I want Recreate to load archived parameters into a new editable draft, so that I can produce a variation without changing history.
68. As a pen-plotter artist, I want Recreate to warn when generator or schema versions differ, so that regenerated output is not mistaken for the archived original.
69. As a pen-plotter artist, I want every recreated job to receive a new immutable identity, so that it cannot overwrite its source job.
70. As a pen-plotter artist, I want sending to reuse the prepared SVG rather than regenerate it, so that preview changes after preparation cannot alter the transmitted job.

Implementation Decisions

• Introduce one high-level job-preparation service as the principal application seam. It accepts parsed source tiling data and complete artwork settings, and returns either an immutable prepared-job model or explicit validation/incompatibility errors.
• Keep source-tiling parsing, tile placement, plot-artwork generation, plot planning, and serialization behind the job-preparation service. Existing modules may be adapted, but the coordinator must no longer assemble the contract piecemeal from UI state.
• The prepared-job model retains semantic hierarchy: intended-colour pen passes contain ordered plot phases; phases retain component and region identity; regions retain their ordered paths.
• Plot treatment is keyed by tile type, not individual placed face. The initial treatment for every tile type is None.
• None contributes a tile type to motif derivation only. Outline, Fill, and Outline + Fill add the named construction-derived output. Hidden contributes nothing.
• A master linework switch suppresses motif and outline output without deleting their underlying settings.
• Intended colour is the single source of truth for preview colour and pen-pass membership. Matching colours merge physical passes even when their paths come from different components.
• One active pen profile supplies nib width and derived fill spacing to all passes in this release. Per-colour pen profiles are deferred.
• Concentric plot fill uses true geometric inward offsets at constant physical spacing. It excludes the original boundary. Invalid or collapsed inset rings terminate that region cleanly.
• Hatch plot fill generates clipped interior centreline segments and likewise excludes the boundary.
• All generated geometry is clipped to the printable boundary after placement while preserving partial edge regions.
• Scale is stored as physical repeat size in millimetres. Auto scale estimates a starting value targeting roughly six repeats across the shorter printable dimension; the final heuristic remains subject to the acceptance matrix.
• Plot planning groups by normalized intended colour before ordering. Colour-pass order is deterministic and preserved in the prepared job.
• Within every pen pass, plot-fill phase precedes linework phase. Each phase independently restarts from the configured sweep origin.
• Fill-region identity must survive geometry generation and colour grouping. Concentric paths for one region remain contiguous and are ordered outermost-to-innermost before advancing to the next region in the sweep.
• Hand-safe sweep is the default and authoritative plot order. Nearest-neighbour optimization may be retained only where it cannot reorder passes, phases, regions, or their required internal order.
• Path preview renders the prepared plot model's exact centreline paths. Artwork preview uses the same settings and intended colours but may render simplified regions. Cosmetic artwork-preview geometry never enters export or transmission.
• The SVG serializer emits one document with physical millimetre size and view box. Its hierarchy is colour pass, then fill/linework phase, with component and region metadata retained. Every drawable path has no solid fill and uses the active nib width as stroke width.
• Preparing generates a UUID, immutable creation timestamp, sanitized display-name slug, exact SVG, settings snapshot, ordering metadata, schema/generator versions, and SHA-256 SVG checksum.
• A prepared job's SVG, generating parameters, ordering, identity, and creation time are immutable. The companion JSON's delivery status, acknowledgement timestamp, receipt data, and error history may change as lifecycle metadata.
• Archive names combine an ISO-style timestamp, sanitized user name, and short immutable ID. The unsanitized display name remains in JSON.
• The local archive adapter uses a user-selected directory through the File System Access API. Each job has one subfolder containing one SVG and one JSON file.
• A ZIP adapter produces the identical SVG+JSON pair when direct directory access is absent or denied. ZIP fallback permits preparation and sending but cannot provide durable in-app listing or post-send status mutation unless the package is re-opened later.
• The browser archive adapter writes the draft before network transmission. A successful HTTP response from the configured plotter endpoint is acknowledgement; response metadata is recorded when available.
• Remote success followed by local status-update failure is reported as “sent, archive update failedâ€� and never triggers an automatic resend.
• Resend reads and verifies the archived SVG checksum, then transmits that exact prepared payload without consulting current UI state or rerunning preparation.
• Recreate loads recorded generating settings into a new working artwork, warns on schema/generator-version differences, and assigns a new identity when prepared.
• The plotter payload carries the complete SVG and companion job metadata needed to preserve pass/phase intent. Patternmaker does not issue execution, pause, or phase-confirmation commands.
• Bundled tilings are validated against the supported parser/generator contract. Each catalog entry is either usable or has a surfaced unsupported/invalid reason; arbitrary XML upload is not introduced.

Testing Decisions

• Tests assert external behavior and serialized contracts rather than private geometry helpers, DOM structure, or internal module call order.
• The principal seam is the job-preparation service. Given source tiling input and artwork settings, tests inspect the prepared plot hierarchy, SVG, JSON record, warnings, or incompatibility errors.
• Golden or structural SVG assertions verify physical dimensions, pass and phase hierarchy, intended colours, stroke widths, fill=none, clipping, component metadata, deterministic path order, and checksum stability. Tests should prefer semantic XML assertions over fragile whole-document string snapshots.
• Treatment tests cover None, Outline, Fill, Outline + Fill, and Hidden, including motif contribution and boundary exclusion.
• Geometry tests through the preparation seam cover constant-distance inset spacing for regular and irregular convex regions, hatch clipping, collapsed small regions, partial paper-edge regions, and absence of paths outside printable bounds.
• Ordering tests cover colour grouping, fill-before-linework phases, phase restart at each sweep origin, region-level sweep order, contiguous concentric regions, and outermost-to-innermost paths. These tests establish that nearest-neighbour logic cannot violate hand-safe order.
• Preview tests are limited to observable mode behavior: Path preview matches exact prepared paths; Artwork preview is visibly idealized; intended colours agree; cosmetic regions never enter exported SVG.
• Archive adapter contract tests cover directory creation, exact two-file packages, sanitized collision-safe naming, immutable content, draft creation before send, acknowledgement-driven sent status, status-update failure after remote success, and checksum validation.
• ZIP adapter tests verify that fallback contains the same SVG and JSON content as directory archival and supports prepare-and-send without claiming durable in-app status updates.
• Plotter-client tests use a fake endpoint to cover acknowledgement, rejection, timeout, exact resend payload, no automatic retry after ambiguous/successful delivery, and receipt metadata.
• Recreate tests cover setting restoration, new identity, version mismatch warnings, and the explicit possibility that regenerated output differs from archived output.
• All 235 bundled tilings are run through a compatibility test. Every entry must return usable motif output or a specific unsupported/invalid result; silent empty or corrupt output fails the suite.
• Auto-scale visual acceptance uses A5 portrait, A4 landscape, and A3 portrait with a simple regular tiling, mixed-polygon tiling, and irregular/complex tiling. Review checks recognizable motifs, neither sparse nor congested density, clean coverage, and non-pathological path counts.
• A small browser-level interaction suite covers changing source tilings, treatment reset versus global-setting preservation, preview toggle, master linework toggle, Prepare Job freeze behavior, archive-folder selection, ZIP fallback, Resend, and Recreate.
• No existing automated-test precedent exists in the repository. Introduce a lightweight JavaScript test harness capable of importing ES modules, parsing XML/SVG, mocking browser boundaries, and running deterministic tests without a real plotter server.

Out of Scope

• Reproducing the complete TiledPatternMaker/Taprats desktop application or exact UI parity.
• Editing source tilings, polygons, placements, or individual placed faces.
• User-supplied or arbitrary XML imports.
• Per-tile-instance plot treatments.
• Per-tile-type motif parameters.
• Per-colour pen profiles or a pen inventory system.
• Solid SVG paint fills as physical output.
• Expanding centreline paths into stroke outlines.
• Multiple SVG files per job or per pen pass.
• Plotter-server job archival.
• Starting, pausing, supervising, or confirming physical plot phases from Patternmaker.
• Automatically resending after network ambiguity or archive-update failure.
• Guaranteeing identical Recreate output across generator/schema versions.
• Permanently fixing the Auto-scale heuristic at six repeats before visual validation.
• Adding new source-tiling families, wallpaper-group editors, dual tilings, custom crop shapes, serial connectivity, G-code, or HP-GL export.

Further Notes

• Existing Taprats parsing, generation, SVG export, plot ordering, and plotter-client code is partial prior work and should be reused where it satisfies this contract. Current behavior is not itself the acceptance criterion.
• The present concentric-fill implementation uses centroid scaling and must not be considered a valid constant-distance inset.
• The current colour-grouping implementation flattens semantic components and therefore cannot preserve required phases and fill-region ordering without redesign.
• The job archive is intentionally owned by Patternmaker because the remote plotter server has separate priorities.
• Domain terminology is defined in the repository glossary. Architectural rationale for remote execution ownership, local archival, and hand-safe ordering is recorded in the corresponding ADRs.