docs: restore MOPA workbench UX contract

docs/design/mopa-workbench-ux.md

@@ -0,0 +1,311 @@
+# MOPA workbench UX requirements
+
+- Status: Working product contract
+- Recreated: 2026-10-20
+- Scope: desktop application workflow; hardware-free through M1
+
+## Purpose
+
+The Pirate Ray should give a casual makerspace user a clear path from opening
+a design to a validated job. It should feel capable without presenting machine
+selection, controller configuration, lens data, or every galvo parameter as
+the first decision.
+
+This document records product behavior, not an application architecture. The
+current reuse direction remains Rayforge plus the narrowest practical JCZ
+integration. A prototype or mockup can illustrate these requirements, but it
+does not become a second implementation and does not prove machine behavior.
+
+This file was recreated because the UX document named by the repository
+handoff was absent from the active checkout and had no Git history, branch, or
+stash copy. The requirements below come from that handoff, the project charter
+and roadmap, and the evidence-backed
+[LightBurn-to-Rayforge capability map](../research/lightburn-rayforge-ux-capability-map.md).
+
+## Product principles
+
+1. **Start with the design.** Opening or importing artwork is the normal first
+   action. Choosing a controller, machine, or lens is an administrator task.
+2. **Keep the canvas stable.** Panels may collapse and themes may change, but
+   the work-area geometry, artwork position, and semantic layer colors do not.
+3. **Show the next useful decision.** Common layer settings are immediately
+   available; specialized settings appear only when the user's disclosure
+   level, operation, and active profile make them relevant.
+4. **Preview before job control.** The planned geometry, enabled operations,
+   ordering, hatch, field boundary, and warnings are inspectable before any
+   physical action.
+5. **Make uncertainty visible.** Unknown units, profile identity, correction,
+   lens compatibility, or parameter limits block encoding or execution rather
+   than receiving guessed defaults.
+6. **Reuse instead of cloning.** Extend existing Rayforge concepts and UI
+   seams where possible. Do not recreate a canvas, geometry engine, material
+   database, or general LightBurn parser.
+7. **Separate preparation from hardware.** Offline editing, preview, saving,
+   and simulation must remain useful when no controller backend is installed.
+
+## Primary maker flow
+
+The default flow is:
+
+1. open or import a design;
+2. inspect and arrange it on the machine-sized work area;
+3. select an object or layer;
+4. assign or edit the applicable operation settings;
+5. optionally apply a compatible material recipe;
+6. preview the planned path and operation order;
+7. resolve preflight errors and review warnings;
+8. save or export the portable project;
+9. only when a separately supported hardware profile is active, enter the
+   gated framing and job-control flow.
+
+The application must not force machine, controller, lens, or connection
+selection into steps 1–6 when a configured default profile already exists.
+
+## Workspace layout
+
+The central canvas is the stable visual anchor. It represents the configured
+work area and shows artwork, selection, field boundaries, planned paths, and
+non-destructive overlays.
+
+The right side contains independently collapsible panels in this order:
+
+1. **Layers** — operation list, color, order, selection, visibility and output
+   state;
+2. **Settings** — values applicable to the selected operation and current
+   disclosure level;
+3. **Material Library** — compatible recipes and their provenance;
+4. **Framing** — offline framing preview initially, physical framing only when
+   explicitly supported and gated.
+
+**Job Control** remains fixed at the bottom rather than disappearing with the
+other panels. In the offline product it shows simulation/no-device state and
+must not imply that a controller is connected.
+
+Collapsing panels may enlarge the available canvas viewport, but it must not
+change document coordinates, work-area dimensions, geometry, layer colors, or
+the meaning of the current selection.
+
+## Layers
+
+The layer list stays visible by default alongside the settings panel. Each
+entry should expose, at minimum:
+
+- semantic color and user-editable name;
+- operation or mode;
+- order;
+- a visibility state for the canvas;
+- a separate output-enabled state for preview and job planning;
+- concise values for the most important applicable settings.
+
+Visibility and output are independent. Hiding a layer must not silently
+disable it, and disabling output must be visually distinct from hiding it.
+Reordering operations must immediately affect preview order without moving
+the source geometry.
+
+The first supported operation types remain an open product decision. Until
+that decision is reviewed, the UI must not imply support beyond operation
+types already preserved end-to-end by tests.
+
+## Settings and disclosure levels
+
+The settings panel has three disclosure levels:
+
+- **Beginner** — the smallest set needed for an ordinary, already-configured
+  job;
+- **Advanced** — additional operation controls for a trained maker;
+- **Expert** — specialized galvo, timing, diagnostic, and compatibility
+  details supported by the active profile.
+
+Changing level reveals or hides rows; it must not replace the canvas, move the
+panels into a different workflow, or reset values. Unsupported settings remain
+absent rather than disabled with invented defaults.
+
+Power, speed, passes, frequency, Q-pulse width, interval, hatch, scan angle,
+and timing are candidate fields, not a promise that every operation exposes
+all of them. Frequency and Q-pulse width require explicit units. Machine- and
+source-specific ranges require verified profile evidence.
+
+Exactly which fields belong in Beginner mode remains an open product decision.
+The initial choice should be made from representative workshop jobs, not by
+copying every field from LightBurn.
+
+## Material library
+
+Recipes are optional accelerators, not a mandatory wizard. A user can ignore
+the library and edit job values directly.
+
+A recipe can describe:
+
+- material;
+- thickness when relevant;
+- operation or recipe variant, such as engraving or cutting;
+- process settings with explicit units;
+- source and validation status;
+- compatible machine, source, lens, correction profile, and software schema;
+- notes and revision information.
+
+The library supports multiple collections:
+
+- makerspace-shared;
+- personal;
+- optionally project-specific.
+
+Personal collections are portable through import/export and require no cloud
+account. Applying an incompatible or unverified recipe must produce an
+explanation and must not silently override the active machine profile.
+
+The evidence required for the label “makerspace-approved” remains an open
+product decision. Exported LightBurn values and observed recipes are not, by
+themselves, certified hardware limits or approved settings.
+
+## Preview and preflight
+
+Preview must work without a controller. It should show, where supported:
+
+- field boundary and geometry;
+- enabled versus disabled output layers;
+- operation order;
+- hatch or fill representation;
+- an approximate path;
+- warnings and blocking validation failures;
+- estimated behavior only when the estimate's basis is explicit.
+
+Preflight blocks at least:
+
+- geometry outside the supported field;
+- machine, source, lens, or correction-profile mismatch;
+- unknown or ambiguous units;
+- unsupported operations;
+- invalid parameter values;
+- incomplete MOPA import data required by the selected backend.
+
+A warning must not be presented as a passed safety check. An approximate path
+or time estimate must be labelled as approximate.
+
+## Framing
+
+Framing has two distinct meanings:
+
+1. **Canvas framing preview** — an offline overlay showing the proposed bounds
+   or contour. This is safe to provide during M1 when clearly labelled as a
+   simulation.
+2. **Physical galvo framing** — controller behavior that may move galvos or
+   activate a guide source. This remains unavailable until a separately
+   reviewed protocol authorizes the exact operation and safety conditions.
+
+The UI must never present simulated framing as proof that the physical machine
+has framed the job. `RequireFrameBeforeStart` is a profile observation and a
+future policy input, not authorization to issue a framing command.
+
+## Job control and states
+
+Job Control remains visually separate from design editing. The interface must
+make its current execution boundary explicit, for example:
+
+- **Offline** — edit, save, validate and preview only;
+- **Simulated** — run against a deterministic fake/no-device driver;
+- **Blocked** — a named profile, validation, recovery, or evidence condition
+  prevents execution;
+- **Hardware unavailable** — no reviewed production backend is reachable;
+- future hardware states only after their protocols are reviewed.
+
+The no-device workflow may expose Start Simulation, Hold, Resume, Cancel and
+Recover when backed by deterministic tests. A physical Start action remains
+absent or disabled while the production controller backend is gated.
+
+Cancellation must clear pending work, and restart must require explicit
+recovery when that is the driver contract. The UI must not translate a failed
+or cancelled job into an apparently ready state without explanation.
+
+## Machine and administrator settings
+
+Machine, controller, source, lens, correction and connection settings belong
+in an advanced administrator area. They must remain inspectable because they
+are safety-relevant, but they are not routine choices at job start.
+
+The normal workspace may show a concise active-profile summary and any
+compatibility problem. Changing the lens or correction profile is an explicit
+configuration action. The application must not offer a guessed replacement
+when required profile evidence is missing.
+
+## Themes and visual semantics
+
+The default direction is clear and light. A dark theme may be provided, but it
+must preserve:
+
+- canvas geometry and scale;
+- artwork position and appearance sufficiently for comparison;
+- semantic layer colors;
+- panel placement and collapse state;
+- selection, warning, blocked, offline and simulated meanings.
+
+Theme changes must not be used to hide safety or provenance information.
+
+## Diagnostics and wording
+
+Messages should state:
+
+1. what is wrong or unknown;
+2. why the action is blocked or limited;
+3. which evidence or user action can resolve it;
+4. whether the result is offline, simulated, inferred, or physically verified.
+
+Avoid language that implies communication with a controller when only a model,
+preview, mock transport, or UI prototype is active.
+
+## Deferred capabilities
+
+The following are not required for the first useful offline product unless a
+representative workshop job proves otherwise:
+
+- physical framing or marking;
+- automatic Windows USB-driver switching;
+- arbitrary raw controller commands;
+- all LightBurn operation modes;
+- sub-layers, cleanup passes, wobble, 3D sliced images, and specialized galvo
+  timing controls;
+- a production material-test run flow;
+- cloud accounts or cloud-only recipe storage;
+- simultaneous support for every makerspace laser.
+
+## Offline acceptance scenarios
+
+The UX direction is ready for implementation decisions when a packaged
+no-device desktop checkpoint can demonstrate:
+
+1. opening representative synthetic geometry directly into the workbench;
+2. selecting, naming, coloring and ordering layers;
+3. independent visibility and output state, or a documented upstream gap;
+4. editing supported settings with visible units and capability gates;
+5. applying or declining a compatible synthetic material recipe;
+6. previewing enabled geometry, hatch/order and field violations;
+7. saving and reopening without losing supported settings;
+8. starting a simulation, holding, resuming, cancelling and explicitly
+   recovering against the no-device driver;
+9. keeping controller discovery and transport unreachable;
+10. preserving canvas geometry and layer semantics across theme and disclosure
+    changes.
+
+Passing these scenarios does not authorize physical framing or marking.
+
+## Open product decisions
+
+Kaz should decide these when a concrete implementation needs them:
+
+1. Which operation types are included in the first useful release?
+2. Which exact fields are visible in Beginner mode for each operation?
+3. What evidence and review process makes a shared recipe
+   “makerspace-approved”?
+
+All other choices should follow the casual-maker defaults above unless new
+evidence reveals a conflict.
+
+## Traceability
+
+- [Project charter](../project-charter.md)
+- [Product and research roadmap](../roadmap.md)
+- [LightBurn-to-Rayforge UX capability map](../research/lightburn-rayforge-ux-capability-map.md)
+- [Graphical workflow model spike](../research/rayforge-graphical-workflow-spike.md)
+- [Windows GUI preflight](../research/rayforge-windows-gui-preflight.md)
+- [Proposed reuse decision](../adr/0002-reuse-rayforge-and-balormk.md)
+

docs/research/lightburn-rayforge-ux-capability-map.md

@@ -0,0 +1,189 @@
+# LightBurn-to-Rayforge UX capability map
+
+- Date: 2026-10-20
+- Scope: desktop workflow and offline capability fit
+- Rayforge evidence baseline: commit `c28918c87f8273dd1d244f5a057addc192807fa5`
+- Hardware access: none
+
+## Purpose
+
+This note translates the useful parts of LightBurn's documented workflow into
+testable requirements for The Pirate Ray and compares them with the evidence
+already collected for Rayforge. It is a product-gap analysis, not permission
+to copy LightBurn code, text, graphics, assets, or proprietary behavior.
+
+The target is an approachable galvo job workbench. A normal maker should begin
+by opening a design, working on the canvas, selecting a layer, adjusting the
+applicable process settings, previewing the result, and optionally applying a
+material recipe. Machine, controller, lens, correction, and driver selection
+belong in an advanced or administrator path after initial configuration.
+
+The previously referenced `docs/design/mopa-workbench-ux.md` was absent from
+the active repository checkout and had no Git history, branch, or stash copy.
+It has now been recreated as a traceable working product contract from the
+repository handoff, charter, roadmap, and evidence cited in this note. The
+missing HTML prototype was not treated as application evidence.
+
+## Evidence labels
+
+- **Proven offline**: exercised in the pinned code path with deterministic
+  output and no transport.
+- **Source-inspected**: found in the pinned upstream source, but not exercised
+  in the packaged Windows application.
+- **Product requirement**: agreed behavior that still needs an implementation
+  or interaction test.
+- **Gated**: must remain unavailable until named evidence or safety conditions
+  are satisfied.
+- **Deferred**: useful LightBurn behavior, but outside the first useful
+  product.
+
+## Reference workflow
+
+LightBurn's documentation provides a useful interaction vocabulary:
+
+1. the workspace represents the machine work area and contains arranged
+   artwork;
+2. colors/layers bind artwork to ordered operations;
+3. the layer list controls visibility, output, order, mode, and abbreviated
+   process settings;
+4. the full settings editor reveals controls according to machine type and
+   operation mode;
+5. preview is used to inspect the planned output before job control;
+6. material-library entries reapply grouped process settings;
+7. framing is a separate physical alignment action, not merely another canvas
+   view;
+8. advanced galvo controls include frequency, Q-pulse width, sub-layers,
+   timing, wobble, angle changes, and cleanup passes.
+
+This vocabulary is useful, but The Pirate Ray should implement only the subset
+required by real workshop jobs and supported by evidence.
+
+## Capability map
+
+| Maker need | LightBurn reference behavior | Current Rayforge evidence | Classification | Narrow next step |
+| --- | --- | --- | --- | --- |
+| Open a design directly into a work area | Artwork is imported or created on a machine-sized workspace | Rayforge has a desktop editor, projects, geometry and broad import support; the local spike proved a preview artifact from synthetic geometry | Source-inspected; preview proven offline | Exercise open/import in the packaged no-device Windows checkpoint |
+| See and select operations as layers | The layer list uses color to identify operations and keeps order visible | Rayforge has layers and workflow steps, but the desired persistent layer/settings arrangement has not been interaction-tested | Source-inspected plus product requirement | Verify selection, ordering, naming and color semantics without creating a parallel layer model |
+| Hide geometry without disabling output, and disable output without hiding geometry | LightBurn separates `Show` and `Output` | Rayforge separates `Layer.visible` canvas state from `Step.visible` job participation and serializes both; output is operation-level rather than a layer-level control | Proven offline at model/source level; aggregate UI untested | Add or propose a tri-state layer Output control over existing step states, then verify it in the packaged no-device GUI |
+| Edit common settings quickly | The layer list exposes mode, speed, power, passes and applicable galvo fields | Rayforge's generated laser-step settings expose power, speed, frequency and pulse width; serialization is proven offline | Proven offline at the model/UI-contract level | Confirm editing and save/reload in the packaged no-device GUI |
+| Reveal complexity progressively | LightBurn Beginner Mode hides some advanced settings; PirateRay calls for Beginner, Advanced and Expert levels without moving the canvas | Rayforge capability sections can hide machine-dependent fields, but three user-facing disclosure levels are not proven | Product requirement | Define the smallest beginner field set from real job needs before adding controls |
+| Preserve MOPA units and values | Galvo frequency is presented in kHz and Q-pulse width in ns | Rayforge's workflow uses Hz and ns and preserves both; LightBurn project import does not yet map frequency or pulse width into workflow settings | Partly proven; import gated | Keep explicit conversion at the import boundary and wait for a known-working `.lbrn2` before mapping `QPulseWidth` |
+| Apply a reusable material recipe | LightBurn libraries organize presets by material, thickness and description and apply/link them to layers | Rayforge has material recipes, but workshop provenance, approval, machine/lens compatibility and portable personal collections are not proven | Source-inspected plus product requirement | Map the existing recipe schema before designing a new library UI; specify provenance and compatibility gaps |
+| Inspect planned behavior before any run | LightBurn Preview reflects enabled layers and planned order | Rayforge produced a populated `JobArtifact` with Ops, path length and no machine code | Proven offline; human interaction untested | Verify layer filtering, order, hatch and warnings in the packaged no-device GUI |
+| Reject a visibly invalid job | Preview/preflight should reveal unintended output; the target product must reject profile mismatch and out-of-field geometry | Existing JCZ negative tests reject profile mismatch, out-of-field geometry, invalid values and unsupported Ops | Proven offline at encoder boundary | Surface these failures as understandable preflight messages without weakening the fail-closed gate |
+| Keep machine and lens selection out of the normal start flow | LightBurn device settings are separate from ordinary layer work | Rayforge has machine profiles and capability-gated settings; the desired administrator-oriented placement is not interaction-tested | Product requirement | Verify default-profile startup and move profile/lens changes behind an advanced path if upstream behavior requires it |
+| Save and reopen without losing job intent | Project files retain artwork and layer settings | The synthetic step retained power, speed, frequency and pulse width through serialization/deserialization; full project interaction is untested | Partly proven offline | Add save/reload to the packaged no-device checklist |
+| Frame safely | Galvo framing is a distinct physical action used to align a job | No physical framing is authorized; galvo framing semantics and Rayforge fit remain unproven | Gated | Keep only an explicitly labelled on-canvas simulation until a reviewed hardware protocol authorizes exact behavior |
+| Start, hold, cancel and recover | Job control is distinct from editing and preview | The no-device driver proves hold/resume, cancellation, cleared buffers and explicit recovery | Proven offline at driver level; GUI untested | Exercise the controls only against the no-device driver in the packaged GUI |
+| Run a material test | LightBurn generates a grid varying two applicable process parameters | No production Rayforge/PirateRay material-test flow has been proven; a UI mock is not machine functionality | Deferred | Retain as a future offline planner feature; do not expose a physical run action |
+| Use sub-layers, cleanup passes, wobble and per-layer galvo timings | LightBurn exposes these as advanced, mode- and device-specific settings | Hatch planning and basic MOPA operations are proven, but these specialized semantics are not covered end-to-end | Deferred | Select only from demonstrated workshop needs after the basic JPT vertical slice closes |
+| Use identical geometry and semantic colors in light and dark themes | PirateRay requires theme changes not to reshape the work area | No current packaged-app evidence | Product requirement | Treat theme as presentation only and add a later visual regression check |
+
+## What should be reused
+
+The evidence supports reusing Rayforge's existing:
+
+- canvas, document, layer, project and geometry concepts;
+- import pipeline rather than creating a general LightBurn parser;
+- workflow steps and generated capability-aware settings UI;
+- material-recipe foundation;
+- preview-facing `JobArtifact`, simulation and preflight boundaries;
+- machine-profile, addon, encoder and asynchronous driver seams;
+- project serialization and packaged desktop direction.
+
+The PirateRay-specific work should remain narrow:
+
+- JCZ profile recognition and provenance;
+- evidence-backed LightBurn MOPA import conversion;
+- JPT/lens/correction compatibility validation;
+- fail-closed preflight and clear diagnostics;
+- a casual-maker presentation of existing capabilities;
+- a physically gated Balor transport after a separate reviewed protocol.
+
+## Gaps that must not be papered over
+
+1. A known-working private galvo `.lbrn2` is still required to establish
+   project-level `QPulseWidth` serialization and omission/default behavior.
+2. The current Windows environment has not launched the pinned Rayforge GTK
+   application; the headless UI contract is not a human interaction test.
+3. `RequireFrameBeforeStart` is observed in a LightBurn device export and
+   preserved by the narrow addon seam, but it is not proof of safe physical
+   framing behavior.
+4. Machine-specific frequency, pulse-width, timing and correction limits are
+   not established by LightBurn documentation or exported recipe values.
+5. Material recipes lack a proven contract for provenance, approval and
+   machine/lens/correction compatibility.
+6. The HTML prototype named by the handoff is absent from the active checkout;
+   its historical controls must not be treated as implemented capability.
+
+## Recommended implementation order
+
+### P0 — recover the product contract (completed 2026-10-20)
+
+- `docs/design/mopa-workbench-ux.md` has been recreated from traceable project
+  requirements and this capability analysis.
+- Resolve the open product decisions only when they block a concrete task:
+  first supported operation types, beginner-visible fields, and the evidence
+  required for a makerspace-approved recipe.
+
+### P1 — complete the no-device desktop checkpoint
+
+- Use a reviewed Windows GTK runtime for the pinned Rayforge checkout.
+- Load the synthetic JCZ-capable profile with no discovery or transport.
+- Open geometry, select a layer, edit power/speed/frequency/pulse width,
+  preview, save, reload, hold, cancel and recover.
+- Record the actual placement and behavior of layers, settings, recipes,
+  preflight and job controls.
+
+### P2 — close only evidenced gaps
+
+- Propose small upstream or addon changes for independent Show/Output state,
+  casual-maker disclosure and safety diagnostics only when P1 proves they are
+  absent.
+- Extend material recipes with provenance and compatibility metadata using the
+  existing model where possible.
+- Add LightBurn MOPA field conversion only after private project evidence
+  establishes serialization and units.
+
+### P3 — defer specialized and physical behavior
+
+- Keep material-test execution, physical framing, controller status and laser
+  start outside the offline product.
+- Add sub-layers, cleanup passes, wobble and timing controls only in response
+  to supported workshop jobs and end-to-end tests.
+
+## Decision impact
+
+This analysis finds no UX requirement that currently justifies a separate
+desktop application. Rayforge covers the expensive general-product foundation,
+while the identified gaps are narrow enough to test as addon or upstream
+extensions. ADR 0002 should remain **Proposed** until the packaged no-device
+interaction checkpoint and the LightBurn MOPA fixture gate are complete.
+
+No USB enumeration, controller command, galvo movement, physical framing,
+arming, or laser output was performed for this analysis.
+
+## Sources
+
+Project evidence:
+
+- [Open-source landscape](open-source-landscape.md)
+- [Graphical workflow model spike](rayforge-graphical-workflow-spike.md)
+- [Layer visibility and output spike](rayforge-layer-model-spike.md)
+- [Windows GUI preflight](rayforge-windows-gui-preflight.md)
+- [Synthetic LightBurn MOPA import spike](rayforge-lightburn-mopa-import-spike.md)
+- [Synthetic LightBurn JCZ device-import spike](rayforge-lightburn-device-import-spike.md)
+- [Rayforge JCZ negative cases](rayforge-jcz-negative-cases.md)
+- [Rayforge cancellation and recovery spike](rayforge-jcz-cancel-recovery-spike.md)
+- [ADR 0002](../adr/0002-reuse-rayforge-and-balormk.md)
+
+Official LightBurn behavior references:
+
+- [Workspace / Edit Window](https://docs.lightburnsoftware.com/latest/Reference/UI/Workspace/)
+- [Cuts / Layers Window](https://docs.lightburnsoftware.com/latest/Reference/CutsLayersWindow/)
+- [Galvo-Specific Cut Settings](https://docs.lightburnsoftware.com/latest/Reference/CutSettingsEditor/GalvoSpecificCutSettings/)
+- [Sub-Layers](https://docs.lightburnsoftware.com/latest/Reference/CutSettingsEditor/SubLayers/)
+- [Previewing](https://docs.lightburnsoftware.com/latest/GetStarted/PreviewBeginner/)
+- [Material Test](https://docs.lightburnsoftware.com/latest/GetStarted/FirstMaterialTest/)
+- [Galvo Ports and Laser Settings](https://docs.lightburnsoftware.com/latest/Reference/DeviceSettings/GalvoPorts/)
+

docs/roadmap.md

@@ -41,6 +41,10 @@ hardware command is possible. The real controller backend remains absent or
 physically gated until its protocol and safety behavior are supported by
 evidence.
 
+The corresponding casual-maker workflow, layout, disclosure, preview and
+offline acceptance requirements are recorded in the
+[MOPA workbench UX requirements](design/mopa-workbench-ux.md).
+
 ## What the installer snapshot gives us
 
 The collected installer snapshot establishes: