SOF-8023: Job Designer UX — plan, mockups, and phases 1–3

[timurbazhirov]

Summary

UI/UX work for the Job Designer (SOF-8023): the brainstorm deliverables and all three phases, across six repos.

This is the designated branch for job-designer, so docs and code live together here. Happy to split the docs out if you'd rather review them separately.

Everything is behind opt-in flags, defaulted off for hosts and on in the standalone demos. A host that sets nothing sees no change at all.

Phase 1 — de-noise

• Submit is a header button (#job-submit-button). It used to be a dropdown item shown only when job.id && job.isInInitialStatus — hidden is the worst state for a control: the reader can't act on it and isn't told why. It's now always visible while the job is a draft and, when disabled, names what's missing.
• Terminate replaces it while running, and asks first — it was one unconfirmed click that kills a running job.
• Visible error state. The ErrorBoundary fallback was <div />, so a render error produced a silently blank page.
• One Compute tab — passes hideComputeSubTab.

Phase 2 — guided designer

2.1 Readiness rail (src/jobReadiness.ts, JobReadinessRail). Numbered tabs implied a sequence while looking identical whether a step was done or untouched. Each rail step carries its state and a line saying what is chosen — Compute · cluster-007 · 1×16 · 04:00:00, Review & submit · 2 steps remaining. Keyboard-navigable, aria-current on the active step.

2.2 Context strip. Checking which material a job runs on used to mean leaving the step you were on. Chips for material / workflow / compute / estimate, each a way back. The parent job moves here from a dismissable Alert whose X was really "unset parent".

2.3 Compute redesign (cove + ive + here). Four new cove primitives, then cluster cards, presets and a live estimate in ive. This repo's share is the host data ive can't fetch: clusterMetadata, computeQuota, and runs — a batch runs once per material, and an estimate for one would understate the cost by that factor.

2.4 Preflight at submit (src/preflight/, PreflightDialog). Five ordered checks; fails block and deep-link to the fixing step, warnings need acknowledging, hosts append their own via setDependencies({ preflightChecks }). There is a fourth outcome, skip, for checks the host published no data to judge — a green "Budget" row backed by no pricing would be a lie the reader can't check. A check that throws also yields skip: our own bug must not stand between a reader and their job.

2.5 Materials tray + metadata panel. The Materials tab was a full-bleed 3D canvas and nothing else. Now a chip tray that also states the batch consequence, and a metadata panel.

2.6 Save-state honesty. All changes saved / Unsaved changes / Saving, with a beforeunload guard armed only when leaving would actually lose work. Explicitly not autosave — that's UX-498's call.

Phase 3 — the living job

3.1 Lifecycle header. The status tint on the header icon is replaced by cove's JobLifecycleTimeline: Draft → Queued → Running → Finished, each stage with its own icon and its timestamp from the status track. A failed job shows the failure where the finish would have been, and greys stages it never reached — "upcoming" would suggest a terminated job might still run.

3.2 Run monitor (jove + cove + here). A submitted job used to disappear. Now the designer moves to the monitor — on the status transition, not the click: switching at the click would land on a Results tab conditionalTabsMap hasn't enabled yet, because the job is still pre-submission until the server says otherwise. ResultsTab gets the units and, where the host injects getJobLogTail, the log.

3.3 Unit inspector + theme parity (workflow-designer + wove + here). Clicking a flowchart unit opens its settings beside the diagram instead of a three-tab bounce, and the workflow designer stops pinning itself to a light theme inside a dark shell.

Three things worth a reviewer's attention

• The readiness selector had to learn about cluster limits, and Submit had to stop calling getSubmitBlockers itself. Without both, the rail showed Compute complete over a preflight that refused to submit.
• Every shouldComponentUpdate addition is load-bearing. This component's mixins only consider the job entity, so state it owns (terminate dialog, dirty flag, preflight) is invisible to them and the render is skipped. That bug class bit three times.
• The demo needed real data before any of this could be reviewed. It passed clusters={[]} (compute unfillable), the job had no _id (Submit permanently blocked on "Save the job"), and a submitted job was unreachable (monitor, lifecycle past Draft, and the rail's Monitor step invisible). All three are fixed in the demo, each with a comment saying why.

Docs and plan

• UIUX_IMPROVEMENTS.md — proposals A1–F2, from the running app.
• mockups/ — four self-contained interactive HTML mockups.
• plan/ — phase 1, phase 2 and phase 3 sit in review/, each with a Status section recording what shipped, where it diverged, and what is still open. The overview keeps what outlives them.
• AGENTS.md — from mat3ra/agents@c75a1b8, plus two divergences worth upstreaming: date-based plan filenames with the ticket inside the document (public repo, private tracker), and §1.7.1 on committed build output.

Known debt, stated rather than hidden

src/computeEstimate.ts duplicates @mat3ra/ive's utils/computeEstimate, which is canonical. The copy exists only because the ive release carrying it hasn't shipped; it has a TODO(SOF-8023) to delete it. The two are identical today.

Companion PRs — merge order

1. Design language: status tones, StatusChip, CopyId, palette fixes, and four new primitives cove#97 — palette, StatusChip/CopyId, and six new primitives
2. Hide flowchart ids and designer status by default; let the flowchart follow its theme wove#11 — ids/status opt-in, flowchart theming
3. Compute form: progressive validation, cluster cards, presets and a live estimate ive#6, Let the host hide a subworkflow's Compute tab workflow-designer#13 → fix: dispatch material removal to the designer's own store #14, Run monitor: show what a submitted job is doing jove#9 — all import cove primitives that don't exist in the published package, so step 1 is a hard prerequisite
4. this PR — bump the pins, drop the duplicated estimator, then merge

Verification

tsc clean, eslint 0 errors, 86 unit tests pass. Behaviour was measured in the running demos, not assumed:

• draft → 4 steps remaining, Submit disabled naming the first;
• compute filled → Ready to submit, estimate chip 64 core·h ≈ $5.12, preflight 5 passes;
• walltime 24 h → Compute reads over the 12 h queue limit, Submit disabled with the reason in its tooltip;
• 4 × 32 × 12 h → within limits but fails budget at 1536 of 500 core·h; "Reduce resources" lands on Compute;
• a warning holds Submit until acknowledged, then releases it;
• job set running → lifecycle Draft[done] → Queued[done] → Running[current], rail swaps Review & submit for Monitor · Running and Files, Submit disappears, monitor renders over the workflow's five units;
• guided layout off → rail and strip gone, numbered tabs back, one-click submit unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DK8KomMescJvMQNSEfeRR8

[timurbazhirov]

Cross-cutting items now done too

The three phases were the visible work; these are the four things the plan asked for around them that the phases had skipped. All in this branch.

Performance guardrail

The plan asked for "a regression test that counts job.render() calls during compute edits". tests/renderGuardrail.tests.ts does exactly that, because the guided designer recomputes readiness, the estimate and the submit blockers on every render — which means on every keystroke in the compute form. If any of them touched the entity, typing a walltime would re-render the whole workflow.

It asserts zero calls across a burst of seven walltime keystrokes, and that a whole preflight report renders exactly once — that one is deliberate, and the test pins it at once rather than once-per-check.

Localization

The plan says new user-facing strings go through an injectable resolver rather than being scattered through components. Phases 1–3 had scattered about 70 of them. src/messages.ts now holds each with a key and an English default; hosts inject setDependencies({ translate }).

Interpolation is the part that matters: "3 materials — runs 3 times" is not a fragment plus a number — languages place the count differently and inflect the noun — so every varying message stays one string with named parameters. Fallback is per key, since a partial translation is the normal case and the keys it lacks must still read as sentences, never as keys.

The catalogue test asserting no two keys share an English default immediately found one: "Configure compute" existed twice. Merged.

Not covered: component chrome outside the phase 2–3 surfaces — legacy tab labels, the error card, dropdown actions. Those are static strings a scanner can lift later; the derived prose here could not have been.

Analytics

The plan wants a baseline before the flag flips, or "did the redesign help?" is answerable only by opinion. src/analytics.ts declares the event set rather than scattering string literals: designer opened + job submitted (time to first submit), preflight completed with which checks failed, fix-link followed, warning acknowledged, step selected (where abandonment happens), and terminate-after-submit.

A throwing recorder is swallowed on purpose — analytics is the least important thing on the page and must never be what stops somebody submitting a job. Still needed: the webapp's recorder and a dashboard. The events exist; nothing collects them yet.

e2e

The existing suite tested a placeholder app: #job-designer-app, an h1, #status-badges-container and four status badges — none of which exist in the demo, so 4 of its 5 scenarios could only fail. Its baseUrl also pointed at port 3002, which is workflow-designer's dev server, so the suite was aimed at a different application.

Replaced with guided_designer.feature, covering the plan's list. Selectors are ids the components set deliberately, never text or classes, so a copy change — or a translation — fails the assertion it should rather than the lookup.

Cypress is not installed in my environment, so I could not execute the run. All 30 selectors were instead resolved against the running demo with a headless browser — 0 failures, including the submit tooltip's aria-label reading "Configure compute" and all five preflight rows. The step logic is exercised; the Cypress harness itself is unverified here and wants a run before anyone relies on it.

And in cove

The risk table's "ButtonMultiSelect mount-snapshot bug class" mitigation asked for a regression test. mat3ra/cove#97 now has one: the resolution rule is a pure module with 8 assertions covering what the object-holding version got wrong. Job.jsx's read-at-click-time workaround can come out once cove ships.

---

Generated by Claude Code

[timurbazhirov]

I audited the acceptance criteria against the running app, and two of them were not met

I had recorded phase 2.1 as built. Checking each criterion in the browser rather than against my own notes found two that were false, plus a latent crash.

"A new user can create and submit a job without opening any dropdown" — was false

The plan says the three "Select …" dialogs open from Change affordances on their steps. The rail only navigated. Picking a material or a workflow still meant the actions dropdown — the exact thing the rail exists to replace. So the headline acceptance criterion for the whole item did not hold.

Each step that owns a dialog now carries Change (or Choose, when the step is empty), labelled per step so a screen reader hears "Change Material" rather than four identical "Change"s. It sits beside the step row, not inside it: a button within a button is invalid and unreachable by keyboard.

Correctly absent from Compute (edited in place) and Review (nothing to choose).

"Collapses to a horizontal stepper under 760 px" — was false

The rail went full-width with the steps still stacked, pushing the step's own content off a narrow screen entirely. Now a horizontal scrolling strip below the md breakpoint.

viewport	before	after
1400 px	284×262, vertical	320×262, vertical
900 px	284×262, vertical	320×262, vertical
700 px	700×263, vertical	700×77, horizontal
500 px	500×263, vertical	500×77, horizontal

The affordances exposed a crash

Clicking Change threw object is not iterable. This package's types disagree with its own code: JobDesignerDialogState describes { isOpen, open, close } — what the container declares and the demo passed — while Job.jsx destructures [open, close], which is what useReduxDialog returns and therefore what the webapp actually flows. Both shapes are real.

Nothing caught it because the only route to those openers was the actions dropdown, which no test or demo run had ever clicked. normalizeDialogHandle now accepts either rather than picking a winner, so no host has to migrate first, and a dialog the host never wired does nothing instead of throwing. 5 unit tests.

What held up

2.2, 2.4 and 2.6 were verified as claimed: context chips stay visible on all three steps; an incomplete job cannot be submitted; the save indicator reads All changes saved → Unsaved changes on an edit with the beforeunload guard arming alongside it (both directions checked by dispatching the event and reading defaultPrevented).

2.5 gained a 1-vs-3 materials toggle in the demo, because the batch multiplier — the thing the plan says surprises readers most — could not be reviewed with a single material. Three tray chips over "3 materials — the workflow runs 3 times, once per material", with the rail step and context chip both reading "3 materials — runs 3 times".

One thing I did not change, because it is a product decision

A saved draft cannot change its materials. MaterialTab gets addRemoveAllowed={!job.id}, so the tray's Add and Remove disappear the moment a draft is saved — while editable (status === pre_submission) stays true, so the designer simultaneously reports the job as editable.

This predates the guided designer, but the guided designer makes it matter much more: the tray is now the primary affordance for materials, and on any saved draft it is inert. Materials may well be intended to bake into the saved job document — so it is filed as open question 5 rather than changed on a guess. It is also why 2.5's "removing the active material selects a sane neighbour" is the one criterion still unverified: the demo's job carries an _id so Submit is not permanently blocked on "Save the job", which switches the remove affordance off.

The rail's Change Material is gated on isInInitialStatus instead, so the selector stays reachable either way.

---

Generated by Claude Code

[netlify]

✅ Deploy Preview for mat3ra-job-designer ready!

Name	Link
🔨 Latest commit	8cbd58a
🔍 Latest deploy log	https://app.netlify.com/projects/mat3ra-job-designer/deploys/6a8b7811145ad80008cb1d21
😎 Deploy Preview	https://deploy-preview-19--mat3ra-job-designer.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[timurbazhirov]

Netlify deploy preview: wired up, and red for one reason

The mat3ra-job-designer site is now configured from the repo (netlify.toml), but its check will stay red until cove publishes the new primitives. Recording the diagnosis so the red check isn't mistaken for a defect in this branch.

What was actually wrong

Three separate faults, found in order. The first two were real and are fixed here:

1. npm ci could not run at all — EUSAGE ... Missing: husky@7.0.4 from lock file. dfd2501 added husky to devDependencies without regenerating the lockfile. Nothing caught it because this repo's CI and README install with npm install --legacy-peer-deps, which reconciles the drift; Netlify installs with npm ci, which refuses to. Note this is EUSAGE, not ERESOLVE — --legacy-peer-deps does not rescue it.

2. A lockfile entry required an SSH key — "resolved": "git+ssh://git@github.com/Exabyte-io/simpl-schema.git#355fbea", present on main too. Netlify's builder has no GitHub SSH key. This is invisible locally because our containers and CI carry a git insteadOf rule rewriting ssh://git@github.com/ to https://github.com/. Neither package that pulls simpl-schema in asked for SSH — @mat3ra/workflow-designer (dependency) and @mat3ra/move (peer) both declare git+https://; npm rewrote it when writing resolved. Rewritten back; the lockfile now holds no git+ssh entries.

3. The blocker — the build cannot resolve @mat3ra/cove/dist/mui/components/lifecycle/LifecycleTimeline. Both this repo and the lockfile pin cove 2026.7.28-0, and the published 2026.7.28-0 does not contain the Phase 1.5 primitives. Same root cause as the red CI on ive chore: consume wave.js from @mat3ra scope #6 and jove fix: forward fileUtils and DataGridComponent to ResultsTab #9.

Correcting an earlier claim

I previously reported that this branch builds cleanly with npm run build:standalone. That was true only in my working container, whose node_modules/@mat3ra/cove had been replaced with a locally-built copy during the cove work. Against the published package it does not build. Verified by reproducing in a clean clone.

Evidence that cove is the only remaining blocker

In a clean clone (npm ci, published versions of every @mat3ra package), swapping in the locally-built cove dist and nothing else:

✓ built in 1m 46s     EXIT=0

Every other package — wove, ive, workflow-designer, jove — resolves fine at its published version. Publishing cove unblocks this deploy preview, ive #6 and jove #9 together.

Configuration notes

netlify.toml sets VITE_BASE=/ because Netlify serves from the domain root while GitHub Pages serves from /job-designer/. Vite's base now reads that env var, defaulting to the Pages subpath, so Pages and npm run dev are unchanged — verified both ways. A wrong base here fails as a blank page rather than a build error, which is why it is worth stating.

Two things I did not determine: the cause of the very first production deploy failure from main at 01:29 UTC, which predates any of this and ran before main had a netlify.toml; and anything from Netlify's build logs, which need account credentials this session doesn't have — the whole diagnosis above comes from local reproduction plus the unauthenticated deploy API.

---

Generated by Claude Code

[timurbazhirov]

Correction, and merged main in

Retracting one claim from my previous comment

I wrote that the git+ssh://…/simpl-schema lockfile entry broke Netlify's install. That was wrong. npm falls back to an HTTPS tarball for public GitHub repos, and I verified simpl-schema installs cleanly with a cold cache and this container's ssh→https rewrite disabled. The entry was never a problem, and the commit that rewrote it fixed nothing. This merge takes main's lockfile wholesale, which reverts it.

Fault 1 in that comment was real: npm ci genuinely could not run against a lockfile missing husky.

Merging main (conflicts resolved)

main reversed two things this branch was built on, so the resolution wasn't textual.

dist/ is no longer committed (7de5cf3). 18 of the 20 conflicts were modify/delete on files this branch had regenerated — all resolved in main's favour. AGENTS.md §1.7.1 documented the opposite policy at length, so it's rewritten rather than left to rot: this repo lets CI build and publish, while the rest of the @mat3ra family hasn't all migrated, so it now says to check git ls-tree per repo instead of assuming either model.

Pins moved to published versions (3983b74). Took main's versions for all 18 @mat3ra packages.

Two things git got wrong on its own, which a plain checkout --theirs would also have missed:

• .husky/pre-commit auto-merged into something incoherent — it kept this branch's comment claiming dist/ is tracked and shipped, took main's contradicting action, and silently dropped main's npx lint-staged line. Restored to main's version exactly.
• husky and "prepare": "husky install" are dropped. They existed only to keep the tracked dist/ in sync, and that reason is gone. Arming main's current hook actively breaks commits: its first line is npx lint-staged, and lint-staged is neither a dependency nor configured anywhere here. Not a prediction — my first attempt at the merge commit was rejected by that hook, which fetched lint-staged@17.3.0 and failed with could not find any valid configuration. AGENTS.md now records why the hook is dormant and what arming it would require.

The diff drops from 134 files to 62 and from ~10.6k additions to ~7.4k, entirely by shedding dist/.

Verified after resolution: tsc clean, eslint 0 errors, 111/111 tests, 0 files tracked under dist/, and main's ApplicationDriver → StandataDriver rename in src/standalone/preloads.ts intact.

Still blocked on cove

@mat3ra/cove@2026.8.19-4 — the version main now pins — ships none of the six primitives from cove#97. Its dist/mui/components/ contains only the pre-existing set (accordion, button, checkbox, custom, dialog, dropdown, icon, linear-progress, nested-dropdown, popover, radio-group, select, stepper, tabs). So build:standalone and the Netlify deploy preview stay red until cove#97 is released. The merge order in the description is unchanged.

Worth knowing why unit CI stays green while the bundle doesn't build: tsc doesn't typecheck Job.jsx, which is where the cove import lives. Only the Vite build resolves it.

---

Generated by Claude Code

[timurbazhirov]

Deploy preview is live

https://deploy-preview-19--mat3ra-job-designer.netlify.app

No longer blocked on cove#97 merging. Per mat3ra/agents#5, cove's release-wip workflow publishes a branch's build as a GitHub pre-release tarball, so this branch installs cove#97 directly:

"@mat3ra/cove": "https://github.com/mat3ra/cove/releases/download/wip-03c8439/cove.tgz"

node_modules/@mat3ra/cove now carries lifecycle, status, metric, selectable-card, numeric-stepper, log-viewer and copy-id. build:standalone completes in 1m30s where it previously died in 9s.

This pin is temporary by design. Per step 4 of that guideline it reverts to a semver range as soon as cove#97 merges and a normal version publishes — the tarball URL exists only to test pre-merge changes. The tag is per-commit and immutable, so the asset cannot change content underneath us.

Getting there took three attempts, and two were my own mistakes

Recording them because they're the same failure class and cheap to repeat:

1. npm ci EUSAGE. After merging main into cove#97, I reconciled its auto-merged lockfile with npm install --legacy-peer-deps. cove doesn't need that flag and its CI doesn't use it — legacy peer resolution produced a tree only my local install satisfied.
2. tsc failed on a dependency. Fixing that with npm install --package-lock-only re-resolved from scratch and floated @types/node from main's 22.10.7 to 26.2.0, whose .d.ts syntax cove's TypeScript can't parse: ffi.d.ts(273,35): error TS1005.

The actual fix was to stop regenerating. cove#97 changes no dependencies — its dependency, devDependency and peerDependency sets are identical to main's, and the only package.json change is the test/test:unit scripts. So it needs no lockfile of its own; restoring main's byte-for-byte was correct, and the release then published first try.

Verified, not assumed

• cove#97: npm ci exits 0, npm run transpile exits 0, npm test green (112/112) — checked locally before pushing, after burning two CI runs guessing.
• job-designer: npm ci --dry-run resolves (Netlify installs with npm ci, so a lockfile it rejects fails the deploy before building), tsc clean, eslint 0 errors, prettier clean, 111/111 tests.
• The deploy itself: / returns 200 referencing /main.js at the root, main.js 200 / 14.1 MB, and a deep path returns 200 through the SPA redirect. I then downloaded exactly what Netlify serves, rendered it, and confirmed the full guided designer — rail with Change affordances, context strip, lifecycle timeline, save state, metadata panel — rather than trusting that a green build means a working page.

What the preview does and doesn't show

It runs job-designer's own work against published versions of the companion packages. The features living in those packages — ive's compute cards and estimate, workflow-designer's unit inspector, jove's run monitor, wove's flowchart theming — are not in it yet. Each needs the same WIP-release treatment.

---

Generated by Claude Code