Help page "Stitch sequences are optimized for 10-needle machines" claim unfulfilled — there's no machine-specific stitch sequence optimization in the codebase #175

New issue

Closed

opened 2026-10-03 17:34:26 +00:00 by Mark · 1 comment

Mark commented

2026-10-03 17:34:26 +00:00

Owner

Finding

src/pages/Help.tsx (the Home page feature card and the Help page compatibility table) advertises stitch sequence optimizations for 10-needle machines:

"Stitch sequences are optimized for 10-needle machines, minimizing color changes and thread trims for faster production runs."

Verified: grep -rn 'optimize.*sequence\|minimize.*color.*change\|10.needle.*optim\|threadSystem' src/ returns 1 hit in src/lib/easystitch-client.ts:35-78 (the threadSystem: "pr10" | "single" field on the machine profile) and nothing else. The threadSystem field is never read outside of its definition.

There is no client-side logic that reorders thread stops to minimize color changes based on the machine profile's needle count. The digitize service receives the design as-is and returns a stitch sequence; the service is documented as accepting the settings and producing a sequence, but the client doesn't ask for any optimization.

The Help page claim says the optimization happens; the codebase has no implementation.

Where

Help claim: src/pages/Help.tsx:102
threadSystem field (defined, unread): src/lib/easystitch-client.ts:35-78
No consumer: anywhere in src/

Suggested fix shape

Three options:

Implement the optimization. Add a optimizeForMachine(stitchObjects, machineProfile) function that reorders the stitch sequence to group adjacent same-color stitches. The optimization is a graph-coloring problem: find a Hamiltonian path through the stitches that minimizes color changes. Real implementations use TSP heuristics; a simpler version groups by color and stitches color-by-color.
Send the machine profile to the service for service-side optimization. Add a optimization: 'speed' | 'balanced' | 'detail' field to the AutoDigitizeSettings and the ExportRequest. The service does the work. The client just selects an option.
Update the Help page text. Drop the "optimized for 10-needle machines" claim; replace with something the implementation actually delivers.

Option 2 is the right product move: the optimization is a service concern, the client just asks for it. The codebase already has stitchPreference: 'balanced' | 'quality' | 'speed' for the digitize side; a similar axis for export makes sense.

Severity

Medium. The user reads the Help page and expects optimization. They get the engine's default sequence.

Discovered by

Gap analysis (2026-10-02) of export optimization claims.

#158 (open) — Help page fabrications. This is one of the more specific items in that umbrella.
#136 (closed) — added machine profiles. The threadSystem field is the data; the consumer is the missing piece.

## Finding `src/pages/Help.tsx` (the Home page feature card and the Help page compatibility table) advertises stitch sequence optimizations for 10-needle machines: > "Stitch sequences are optimized for 10-needle machines, minimizing color changes and thread trims for faster production runs." Verified: `grep -rn 'optimize.*sequence\|minimize.*color.*change\|10.needle.*optim\|threadSystem' src/` returns 1 hit in `src/lib/easystitch-client.ts:35-78` (the `threadSystem: "pr10" | "single"` field on the machine profile) and nothing else. The `threadSystem` field is **never read** outside of its definition. There is no client-side logic that reorders thread stops to minimize color changes based on the machine profile's needle count. The digitize service receives the design as-is and returns a stitch sequence; the service is documented as accepting the settings and producing a sequence, but the client doesn't ask for any optimization. The Help page claim says the optimization happens; the codebase has no implementation. ## Where - Help claim: `src/pages/Help.tsx:102` - threadSystem field (defined, unread): `src/lib/easystitch-client.ts:35-78` - No consumer: anywhere in `src/` ## Suggested fix shape Three options: 1. **Implement the optimization.** Add a `optimizeForMachine(stitchObjects, machineProfile)` function that reorders the stitch sequence to group adjacent same-color stitches. The optimization is a graph-coloring problem: find a Hamiltonian path through the stitches that minimizes color changes. Real implementations use TSP heuristics; a simpler version groups by color and stitches color-by-color. 2. **Send the machine profile to the service for service-side optimization.** Add a `optimization: 'speed' | 'balanced' | 'detail'` field to the `AutoDigitizeSettings` and the `ExportRequest`. The service does the work. The client just selects an option. 3. **Update the Help page text.** Drop the "optimized for 10-needle machines" claim; replace with something the implementation actually delivers. Option 2 is the right product move: the optimization is a service concern, the client just asks for it. The codebase already has `stitchPreference: 'balanced' | 'quality' | 'speed'` for the digitize side; a similar axis for export makes sense. ## Severity Medium. The user reads the Help page and expects optimization. They get the engine's default sequence. ## Discovered by Gap analysis (2026-10-02) of export optimization claims. ## Related - #158 (open) — Help page fabrications. This is one of the more specific items in that umbrella. - #136 (closed) — added machine profiles. The `threadSystem` field is the data; the consumer is the missing piece.

Mark added the

bug

triage-approved

labels

2026-10-03 17:34:27 +00:00

Mark referenced this issue from a commit

2026-10-03 19:19:09 +00:00

fix(#175): Help page no longer claims machine-specific stitch-sequence optimization

Mark commented

2026-10-03 19:19:21 +00:00

Author

Owner

Closed via commit c178a3d1 (HEAD on main is c1789d1; rebased onto origin/main after #172 landed). Help page now describes what the export path actually does today (format/hoop/thread-cartridge selection follows the chosen Machine Profile; the user can reorder thread stops manually in the Bottom Thread Bar before exporting) — the false "stitch sequences minimize color changes by grouping adjacent same-color regions" claim is gone. Regression test asserts both halves (false claim absent, accurate card present). tsc/eslint clean, Help.test.tsx 14/14, full suite 759/762 with the 3 EditorCanvas failures being pre-existing on main (unrelated to #175).

Closed via commit c178a3d1 (HEAD on main is c1789d1; rebased onto origin/main after #172 landed). Help page now describes what the export path actually does today (format/hoop/thread-cartridge selection follows the chosen Machine Profile; the user can reorder thread stops manually in the Bottom Thread Bar before exporting) — the false "stitch sequences minimize color changes by grouping adjacent same-color regions" claim is gone. Regression test asserts both halves (false claim absent, accurate card present). tsc/eslint clean, Help.test.tsx 14/14, full suite 759/762 with the 3 EditorCanvas failures being pre-existing on main (unrelated to #175).

Mark closed this issue

2026-10-03 19:19:24 +00:00

Mark referenced this issue

2026-10-03 23:46:40 +00:00

Help page lists 5 stitch types but the Editor's right-panel stitch-type selector only offers the subset present in the design's threads — Help page overstates editor capability #189