Cyber Fidget Guide Studio¶

Cyber Fidget Guide Studio is an interactive browser-based authoring tool for creating iFixit-style build and repair guides that integrate directly with an MkDocs-based documentation site.
It lets you organize steps, annotate images, and automatically generate Markdown that drops straight into your documentation build.

🚀 Overview¶

The studio allows you to:

Organize an assembly or teardown guide into major steps (step1, step2, etc.) and minor steps (images within each folder).
Add annotations (pins, boxes, circles, arrows) on images to highlight features or actions.
Write descriptions, tools, and parts lists for each major step.
Generate and manage:
step.meta.json – metadata (title, description, tools, parts, pin counters)
*.annot.json – per-image annotation data
step.md – individual Markdown file for each step
guide.md – the full assembled guide
Preview annotations directly on your documentation site with live zoom, hover-to-swap thumbnails, and click-to-zoom images.

Everything is stored alongside your docs (e.g. docs/getting-started/assembly/stepN/), so the workflow is sustainable and version-controlled.

🗂️ Folder Structure¶

Typical structure of an assembly section:

docs/
└── getting-started/
    └── assembly/
        ├── step1/
        │   ├── step1.1.jpg
        │   ├── step1.1.annot.json
        │   ├── step1.md
        │   └── step.meta.json
        ├── step2/
        │   ├── step2.1.jpg
        │   ├── step2.2.jpg
        │   ├── step2.1.annot.json
        │   ├── step2.2.annot.json
        │   ├── step2.md
        │   └── step.meta.json
        └── guide.md

guide.md is automatically generated by the studio’s “Build Full Guide” button.

🧠 How It Works¶

The studio runs entirely client-side using the File System Access API: 1. You click “Pick Folder” and select the top-level assembly/ directory.
- The tool remembers this folder in local storage. 2. It enumerates subfolders (step1, step2, …) as major steps, and the image files inside each as minor steps. 3. When you annotate or edit metadata, the tool writes JSON and Markdown directly into those folders. 4. The MkDocs site simply reads these files: - guide.js + multi.js render the galleries and annotation overlays. - guide.md references all images and metadata with correct relative paths.

You fully own the content—no cloud service or database required.

🧩 Major Features¶

Category	Features
File Management	Local file system integration (no uploads), remembers last folder, “Save All” writes all JSON + metadata, optional overwrite toggle
Annotation Tools	Pins, Boxes, Circles, Arrows — all editable, draggable, copy/pasteable, undo/redo supported
Keyboard Shortcuts	Quick tool switching (`P`, `B`, `C`, `A`), movement nudging, deletion, undo/redo
Inspector / Sidebar	Live coordinate and size editors, pin numbering, per-object label editing
Metadata Editing	Title, description (supports paragraphs + `<br>` via Shift+Enter), tools, parts
Cross-Image Pin Numbering	Pin numbers tracked across the entire major step (`step.meta.json` keeps counter)
Multi-Image Step Gallery	Hover thumbnails to swap main image, click main image to open full-size, auto-loads annotations for each image
Undo / Redo	`Ctrl+Z` / `Ctrl+Shift+Z` or `Ctrl+Y`
Copy / Paste	`Ctrl+C` / `Ctrl+V` to clone selected annotation
Delete	`Delete` key removes selected annotation
Drag / Arrow Keys	Mouse drag to move points, arrow keys nudge (Shift+Arrow for fine control)
Markdown Generation	Creates `step.md` and full `guide.md` with proper relative paths, caption formatting, and paragraph support
Paragraph Formatting	Single newline → `<br>`, double newline or `---` line → new `<p>` block
Auto-Numbering Pins	Step-wide numbering continues across thumbnails
Renumber Button	“Renumber pins (step-wide)” reassigns sequential numbers across all images in a step
Responsive Layout	Works in Chrome/Edge, mobile-friendly galleries, click-to-zoom large image view

⌨️ Keyboard Shortcuts¶

Key	Action
P	Pin tool
B	Box tool
C	Circle tool
A	Arrow tool
Enter	Finish drawing current shape / blur active input
Shift + Enter	Newline inside description textarea
Esc	Cancel drawing or revert text edit
Ctrl + Z	Undo
Ctrl + Shift + Z or Ctrl + Y	Redo
Ctrl + C / Ctrl + V	Copy / Paste selected annotation
Delete	Delete selected annotation
Arrow Keys	Nudge selected annotation
Shift + Arrow Keys	Fine nudge (smaller step)

🧭 Typical Workflow¶

Prepare Images
Place all photos for each major step in its own subfolder (step1, step2, or simply 1, 2, …).
Name images consistently (step2.1.jpg, step2.2.jpg, or step1.jpg, step2.jpg, or simply 1.jpg, 2.jpg, etc.).
Open the Studio
Open cf-guide-studio.html in Chrome or Edge.
Click “Pick Folder” and choose the top-level assembly directory.
Annotate Images
Select a step → click an image → draw pins/boxes/arrows.
Use the right sidebar to edit labels, colors, and metadata.
Use Ctrl+S (or Save All) to persist *.annot.json.
Edit Step Metadata
Set a human-friendly title, write a multi-line description (Shift+Enter for line breaks), and list tools / parts.
Optionally edit or renumber pins step-wide.
Generate Step Markdown
Click Generate step.md to create a Markdown file for that step.
It embeds the gallery HTML and your formatted description.
Build the Full Guide
Click Build full guide.md to concatenate all step Markdown files into one page with correct relative image paths.
Preview in MkDocs
Run mkdocs serve and navigate to /getting-started/assembly/guide/.
You’ll see interactive thumbnails and live annotations rendered by guide.js and multi.js.

🖼️ Gallery / Annotation Runtime¶

multi.js
Handles thumbnail hover and image swapping. Updates data-annot-src so the correct annotation JSON is fetched when images change.
guide.js
Loads .annot.json files, draws SVG overlays, and updates dynamically when the main image changes.
Missing annotation files simply render no overlay (no errors).

Click-to-Zoom: Each gallery’s main image is wrapped in an <a class="cf-zoom"> anchor that opens the raw file in a new tab for detailed viewing.

Mobile: The gallery auto-scales with a right padding gutter to avoid edge-to-edge cropping.

💡 Description Formatting¶

Input	Output
`Line 1 <Shift+Enter> Line 2`	`Line 1<br>Line 2`
`Line 1 <Shift+Enter><Shift+Enter> Line 2`	Separate paragraphs (`<p>`)
Line with only `---`	Forces a new paragraph break

🧮 Step-Wide Pin Numbering & Auto-Save¶

🔢 Global Pin Numbers¶

Pins are now numbered across an entire major step, not per image.
This means you can have:

Minor Step	Pins	Numbers
step2.1.jpg	Pin 1	1
step2.3.jpg	Pin 2	2
step2.5.jpg	Pin 3	3

The counter is stored in each step.meta.json as pinNext, so numbering resumes correctly when you add more pins later.

{
  "title": "Install Front Housing",
  "caption": "Align halves and fasten screws",
  "tools": ["Hex Key 2.5mm"],
  "parts": ["Socket Head Cap Screw #6-32"],
  "pinNext": 4
}

🧷 How It Works¶

Every time you drop a new pin, Studio assigns the next available number (pinNext) and automatically updates the counter in step.meta.json.
The number is stored inside each pin’s data ("n": 2) and drawn consistently across all thumbnails.
Editing a pin’s number in the Inspector updates its JSON immediately.

🔁 Renumber Pins Button¶

If you’ve imported old *.annot.json files or want to reset numbering:

Open the major step folder.
Click Renumber pins (step-wide) in the top bar.
Studio scans all images in the step, assigns sequential numbers starting from 1, and updates both the JSON files and pinNext.

You’ll see a console log such as:

Renumbered pins 1..12 across 5 image(s).

💾 Auto-Save Behavior¶

To prevent “lost” numbering when switching images:

Studio now tracks a dirty flag.
When you switch thumbnails or steps, or press Ctrl + S, it writes the current image’s .annot.json automatically.
The Save All button also performs a quick auto-save of the active image first.
If you try to close the tab with unsaved edits, the browser shows a warning.

Action	Shortcut	Notes
Add Pin	P then Click	Uses next step-wide number
Edit Pin Number	Select Pin → Inspector	Change `Pin #` field
Renumber All Pins	Button	Sequentially re-indexes pins in this step
Auto-Save	Ctrl + S or image change	Writes current `.annot.json`
Undo / Redo	Ctrl + Z / Ctrl + Y	Works on pin edits too

⚙️ JSON Compatibility¶

Old annotation files without the "n" field still work.
During render, Studio falls back to per-image numbering (1..N).
You can run Renumber pins once to migrate legacy steps.

🧭 Recommended Workflow (updated)¶

Annotate pins normally across thumbnails in a step.
Use Ctrl + S or navigate to another image to auto-save.
If numbers ever get inconsistent, click Renumber pins (step-wide).
Continue numbering seamlessly from the last assigned pin.

🔄 Compatibility and Backward Safety¶

Existing steps with older *.annot.json (no pin numbers) still render correctly.
Old guides can be migrated using the Renumber pins (step-wide) button.
Missing JSON files cause no errors—just no overlay.
All generated Markdown remains standard HTML + Markdown, so even without JS, images display correctly.

🧰 Example Folder and Output¶

Example Folder:

assembly/
 ├── step1/
 │   ├── step1.1.jpg
 │   ├── step1.1.annot.json
 │   ├── step1.md
 │   └── step.meta.json
 ├── step2/
 │   ├── step2.1.jpg
 │   ├── step2.2.jpg
 │   ├── step2.1.annot.json
 │   ├── step2.2.annot.json
 │   ├── step2.md
 │   └── step.meta.json
 └── guide.md

Generated Markdown (excerpt):

## Step 2 – Assemble Housing

<p class="muted">1 – Align the halves<br>2 – Insert the screws</p>

<div class="cf-step-gallery" style="--cf-main-w: 640px; --cf-thumb-w: 64px;">
  <a class="cf-zoom" href="../step2/step2.1.jpg" target="_blank" rel="noopener">
    <img class="cf-main" src="../step2/step2.1.jpg" alt="Step main"
         data-annot-src="../step2/step2.1.annot.json">
  </a>
  <div class="cf-thumbs">
    <img src="../step2/step2.1.jpg" alt="step2.1.jpg">
    <img src="../step2/step2.2.jpg" alt="step2.2.jpg">
  </div>
</div>

🧑‍💻 Technical Notes¶

Pure HTML + JS — no build process required.
Uses the File System Access API (requires Chrome/Edge).
JSON schemas are simple and human-readable; easy to version control.
Works with mkdocs-material or any MkDocs theme.
All annotations render via inline SVG; nothing external required.
Persistent local storage remembers your working folder between sessions.

🧭 Recommended Workflow Summary¶

Set up structure – create assembly/stepN/ folders.
Open studio – point it to assembly/.
Annotate images – draw pins, boxes, etc.
Write metadata – description, tools, parts.
Generate step.md for each folder.
Build guide.md once all steps are done.
Serve with MkDocs – done.

🧑‍🏫 Example Use Case¶

Scenario	Outcome
Teaching a student to assemble the Cyber Fidget	Step-by-step guide with clickable annotations
Showing machining or PCB assembly order	Each step folder contains photos from each operation
Documenting a teardown	Reverse the step order; same structure works
Open-source community repair guide	Contributors can edit JSONs/Markdown directly and regenerate locally

❤️ Credits & License¶

Developed by Sam Steele for the Cyber Fidget project.
Open for educational and maker use — feel free to adapt it for your own MkDocs projects.
If you fork or improve it, please credit the original and share your enhancements!