ThePirateRay/docs/design/mopa-workbench-ux.md

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.

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
• Product and research roadmap
• LightBurn-to-Rayforge UX capability map
• Graphical workflow model spike
• Windows GUI preflight
• Proposed reuse decision