How vortiago/sh7pad works
1. What this repo is
- sh7pad is a fully client-side browser app for viewing, creating, editing, previewing, importing, and exporting .sh7 decorative-stitch files.
- There is no backend: all parsing, editing, preview rendering, storage, and export happen in the browser.
2. Top-level architecture
- The app is split into three main layers:
- src/parser for reading and validating existing .sh7 files.
- src/creator for the project/domain model and stitch-generation logic.
- src/ui/creator for the interactive editor, preview, side panels, dialogs, and interaction handling.
- src/shared contains geometry helpers shared between parser and creator logic.
3. Core domain model
- The central object is the “project,” which represents the in-progress design shown in both panes.
- Project-related modules in src/creator handle metadata, invariants, migration, sample creation, repository/store access, and type definitions.
- This is the boundary where user intent lives: points, segments, stitch settings, manual stitches, and export settings.
4. Import path
- .sh7 files are parsed through src/parser/parseFile.ts, parseHeader.ts, parseChunks.ts, and the stitch/satin parsers.
- Validation is explicit and layered under src/parser/validate/*, which checks headers, records, chunks, metadata, satin payloads, and version-specific constraints.
- The parser converts raw bytes into validated structures that can be turned into a project or inspected as file data.
5. Design-mode stitch generation
- The design editor does not store machine stitches directly; it stores geometric intent.
- src/creator/pipeline/* converts that intent into stitch output:
- segment reduction and stitching,
- carriage planning,
- foot tracking,
- multi-block emission,
- final design encoding.
- Satin-specific logic is a major subdomain: the app generates zigzag fill inside satin cones and other stitch sequences from higher-level shapes.
6. Manual mode
- Manual mode bypasses some of the design-mode opinionated generation and lets the user place individual needle drops and jump stitches.
- This mode exists for patterns that are easier to author as explicit stitch sequences than as vector segments.
- It is a separate editing path, but it still feeds the same project/export pipeline.
7. Preview and playback
- The preview pane simulates the stitched result rather than editing geometry.
- It renders fabric, thread, repeated motifs, and a transport scrubber so the user can step through the stitch sequence.
- Preview code lives under src/ui/creator/preview, with scene/render modules that consume the project’s generated stitch stream.
8. Editor UI composition
- The editor is composed of many small UI subsystems: canvas interaction, keyboard shortcuts, pan/zoom, rulers, sidebar, toolbar, inspector peek, bottom sheet, context menus, toasts, and modals.
- src/ui/creator/editor/* handles the canvas interaction and rendering model; src/ui/creator/canvasGesture/* and canvasCamera/* handle touch/pointer gestures and viewport control.
- The layout is responsive and mode-driven, so the same project can be edited in different viewport arrangements.
9. State and rendering flow
- UI state is separated from project state in src/ui/creator/store/*.
- The UI store schedules re-rendering, manages layout attributes, and tracks transport state for preview playback.
- This means interaction events update stores first, then the editor/preview canvases re-render from state rather than directly mutating DOM imperatively.
10. Persistence and local repository
- Projects persist in IndexedDB through src/creator/projectStore.ts and related repository modules.
- This supports offline use and keeps the “recent projects / saved projects” experience entirely local.
- Since there is no server, the browser store is the only persistence boundary.
11. Export formats
- The app exports native .sh7 binary files and .sh7c.json project wrappers.
- Export logic is split between JSON serialization, binary encoding, and SH7-specific limits/constants in src/creator/sh7*.
- Import/export is the main data boundary between the app’s editable project model and the machine-readable embroidery format.
12. Format and protocol foundation
- src/format contains lower-level chunk schema and record codecs used by the parser/encoder.
- The repo includes a reverse-engineered format reference in FORMAT.md and a Kaitai Struct subset in docs/format.ksy, which are important because the binary format is not an external official SDK.
- Cross-format research in docs/research/ supports compatibility and reverse engineering work.
13. Quality and delivery
- The project is built with Vite and TypeScript, tested with Vitest, and end-to-end checked with Playwright.
- GitHub Actions cover CI, accessibility checks, and Pages deployment, which fits the app’s static-client architecture.
Main entry points: project.ts Project model · stitch.ts Stitch pipeline · uiStore.ts UI store · index.ts Editor
Components 30
Docs & research
Reverse-engineered format notes, user guides, and design documentation.
- FORMAT.md · Reverse-engineered binary format reference.
FORMAT.md - Kaitai spec · Subset Kaitai Struct description of the .sh7 format.
docs/format.ksy
Format core
Low-level binary chunk and record codecs shared by parsing and encoding.
- Chunk schema · Chunk definitions and structural schema for the binary format.
src/format/chunkSchema.ts - Record codec · Encodes and decodes low-level records.
src/format/recordCodec.ts
Import parser
Reads .sh7 bytes, parses structure, and applies layered validation.
- File parse · Top-level .sh7 file parsing entry point.
src/parser/parseFile.ts - Header parse · Parses the file header and version metadata.
src/parser/parseHeader.ts - Chunk parse · Reads chunk layout and delegates to specialized parsers.
src/parser/parseChunks.ts - Stitch parse · Parses stitch records from file data.
src/parser/parseStitches.ts - Satin parse · Parses satin-specific payload structures.
src/parser/parseSatin.ts - Validation · Layered validation for headers, records, chunks, metadata, and version constraints.
src/parser/validateSh7Bytes.ts
Project engine
Project model, geometry intent, stitch generation, persistence, and export.
- Project model · Central editable project representation for design and manual modes.
src/creator/project.ts - Project types · Core project and stitch domain type definitions.
src/creator/types.ts - Stitch pipeline · Transforms geometric intent into stitch output.
src/creator/pipeline/stitch.ts - Encode design · Final design encoding stage for generated stitch output.
src/creator/pipeline/encodeDesign.ts - Segment reduce · Reduces design segments before stitch generation.
src/creator/segmentReducers.ts - Carriage plan · Plans carriage motion and stitch routing.
src/creator/carriagePlanner.ts - Foot track · Tracks foot state during stitch emission.
src/creator/foot.ts - Manual stitches · Explicit stitch and jump-stitch authoring path.
src/creator/manualStitch.ts - Project store · Browser-local persistence for saved and recent projects.
src/creator/projectStore.ts - Binary export · Exports native .sh7 binary files.
src/creator/sh7BinaryExport.ts - JSON export · Exports .sh7c.json project wrappers.
src/creator/sh7Json.ts - Binary import · Converts parsed bytes into project-ready structures.
src/creator/sh7BinaryImport.ts
Browser UI
Interactive creator, preview, panels, gestures, and state management.
- Creator app · Browser entrypoint and mounting for the creator experience.
src/ui/creator/main.ts - Editor · Interactive design canvas and interaction wiring.
src/ui/creator/editor/index.ts - Preview · Simulated stitched result and transport playback.
src/ui/creator/preview/index.ts - UI store · UI state, render scheduling, layout attributes, and transport state.
src/ui/creator/store/uiStore.ts - Sidebar · Project settings, stitch settings, and preview options.
src/ui/creator/sidebar/index.ts - Modals · Export, new project, and disclaimer dialogs.
src/ui/creator/modals/DialogBase.ts - Gestures · Pointer, touch, and camera gesture handling.
src/ui/creator/canvasGesture/index.ts
Shared geometry
Geometry helpers used by parser and creator logic.
- Satin shape · Shared satin geometry helpers used by generation and validation.
src/shared/satinShape.ts
Connections 31
- FORMAT.md → Chunk schema: documents · Format notes describe the binary chunk model.
- Kaitai spec → Record codec: describes · Kaitai subset mirrors record encoding rules.
- Chunk schema → Record codec: uses · Chunk structure is built on record codecs.
- File parse → Header parse: parses · File parse begins with header extraction.
- File parse → Chunk parse: parses · Then reads chunk structure and payloads.
- Chunk parse → Stitch parse: delegates · Chunk parsing routes stitch content to the stitch parser.
- Chunk parse → Satin parse: delegates · Chunk parsing routes satin payloads to the satin parser.
- File parse → Validation: validates · Parsed bytes are checked against layered constraints.
- Validation → Chunk schema: checks · Validation enforces format structure and record rules.
- Satin parse → Satin shape: uses · Satin parsing shares satin geometry definitions.
- Project model → Project types: defines · Project model is built from shared domain types.
- Project model → Segment reduce: feeds · Project geometry is reduced before stitch generation.
- Segment reduce → Stitch pipeline: feeds · Reduced segments enter the stitch pipeline.
- Stitch pipeline → Carriage plan: plans · Pipeline determines carriage motion.
- Stitch pipeline → Foot track: tracks · Pipeline maintains foot state during emission.
- Stitch pipeline → Encode design: emits · Pipeline ends in encoded design output.
- Manual stitches → Project model: writes · Manual mode stores explicit stitch intent in the project.
- Project store → Project model: persists · Project state is stored locally in IndexedDB.
- Binary import → Project model: creates · Imported .sh7 data becomes an editable project.
- Binary export → Stitch pipeline: exports · Binary export serializes generated design output.
- JSON export → Project model: serializes · JSON export wraps the editable project model.
- Creator app → UI store: boots · App shell initializes UI state and rendering.
- Creator app → Editor: mounts · Creator shell mounts the editor canvas.
- Creator app → Preview: mounts · Creator shell mounts preview playback.
- Editor → UI store: subscribes · Editor renders from store-driven state.
- Preview → UI store: subscribes · Preview and transport reflect store state.
- Sidebar → UI store: reads · Sidebar panels are driven from shared UI state.
- Modals → UI store: coordinates · Dialogs update or reflect application state.
- Gestures → Editor: drives · Pointer and touch gestures manipulate the editor.
- Editor → Project model: edits · Canvas interactions mutate project intent.
- Preview → Stitch pipeline: renders · Preview consumes generated stitch output.