feat: enhance SOP with detailed instructions and add instructional media for assembly

Author: dhuzard

site/public/docs/beatbox-assembly-sop.html

@@ -219,6 +219,26 @@
       background: var(--surface-2);
     }
     .subsection h3 { margin: 0 0 9px; font-size: 1rem; }
+    .instruction-media {
+      margin: 12px 0 14px;
+      overflow: hidden;
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      background: white;
+    }
+    .instruction-media img {
+      display: block;
+      width: 100%;
+      max-height: 560px;
+      object-fit: contain;
+      background: #f8fafc;
+    }
+    .instruction-media figcaption {
+      padding: 9px 12px;
+      color: var(--muted);
+      font-size: .86rem;
+      border-top: 1px solid var(--line);
+    }
     .checklist { display: grid; gap: 8px; }
     .check-row {
       display: grid;
@@ -385,6 +405,7 @@ <h1 id="pageTitle"></h1>
 let metaState = loadJSON(META_KEY, {});
 let noteState = loadJSON(NOTE_KEY, {});
 let itemIndex = [];
+applySopEnhancements();
 
 function loadJSON(key, fallback) {
   try { return JSON.parse(localStorage.getItem(key)) ?? fallback; } catch { return fallback; }
@@ -406,6 +427,191 @@ <h1 id="pageTitle"></h1>
 function renderList(list, el) {
   el.innerHTML = list.map(x => `<li>${escapeHTML(x)}</li>`).join('');
 }
+function applySopEnhancements() {
+  const findSection = id => SOP.sections.find(section => section.id === id);
+  const findSubsection = (sectionId, title) => findSection(sectionId)?.subsections?.find(subsection => subsection.title === title);
+  const addUnique = (items, item, index = items?.length) => {
+    if (!items || items.some(existing => existing.text === item.text)) return;
+    items.splice(index, 0, item);
+  };
+  const replaceItemText = (items, from, to) => {
+    if (!items) return;
+    items.forEach(item => {
+      if (item.text === from) item.text = to;
+    });
+  };
+  const walkItems = cb => {
+    SOP.sections.forEach(section => {
+      if (section.items) section.items.forEach(item => cb(item, section));
+      section.subsections?.forEach(subsection => subsection.items?.forEach(item => cb(item, section, subsection)));
+    });
+  };
+  const replaceExactText = (from, to) => walkItems(item => {
+    if (item.text === from) item.text = to;
+  });
+
+  [
+    'Soldering is required for the screen and IR nosepoke / IR barrier assemblies. This may be a practical limitation for users without soldering equipment or experience.',
+    'Wall color remains an open tracking-design decision: white, black, and gray walls must be compared for tracking quality, reflections, contrast, and illumination stability before release.'
+  ].forEach(text => {
+    if (!SOP.limitations.includes(text)) SOP.limitations.push(text);
+  });
+
+  replaceExactText(
+    'Keep the matte side of plexiglass facing outward and the glossy side inward unless a module-specific exception is documented.',
+    'Keep the matte side of plexiglass facing inward to reduce internal reflections unless a module-specific exception is documented.'
+  );
+  replaceExactText(
+    'Verify which surface is matte and which is glossy: matte side outward, glossy side inward.',
+    'Verify which surface is matte and which is glossy: matte side inward to reduce reflections.'
+  );
+  replaceExactText(
+    'Confirm all matte sides face outward.',
+    'Confirm all matte sides face inward to reduce internal reflections.'
+  );
+  replaceExactText(
+    'Use the same basic panel logic: matte side outward.',
+    'Use the same basic panel logic: matte side inward.'
+  );
+
+  const tools = SOP.sections.find(section => section.id === 'tools');
+  if (tools?.items) {
+    const hexTool = tools.items.find(item => item.text === 'Hex key / Allen key appropriate for M5 hardware');
+    if (hexTool) hexTool.text = 'T-handle ball-end hex key, 2.5 mm';
+    const forcepsText = 'Tissue forceps for clearing 3D-printed insert seats and placing inserts';
+    if (!tools.items.some(item => item.text === forcepsText)) {
+      tools.items.splice(4, 0, { text: forcepsText });
+    }
+  }
+
+  const materials = findSection('materials');
+  if (materials?.subsections && !materials.subsections.some(subsection => subsection.title === 'PCB identifiers')) {
+    materials.subsections.splice(2, 0, {
+      title: 'PCB identifiers',
+      items: [
+        { text: 'Feeder main PCB: BB_Feeder_main_V1 or BB_Feeder_main_V1.1' },
+        { text: 'IR light curtain PCB: BB_IR_light_curtain' },
+        { text: 'Feeder IR barrier PCB: BB_Feeder_IRBarrier_V1.1', level: 'todo', note: 'Revision/name to confirm.' },
+        { text: 'Raspberry Pi shield PCB: BB_RPi_shield_V1.1' },
+        { text: 'Lighting PCB: BP_Lighting_V1.1' }
+      ]
+    });
+  }
+
+  const safety = findSection('safety');
+  addUnique(safety?.items, {
+    text: 'When inserting M3 inserts, work over a flat, solid surface only. Never push the insert above a hand or body part; injury can occur if the tool slips.',
+    level: 'critical'
+  });
+  addUnique(safety?.items, {
+    text: 'Soldering is required for the screen and IR nosepoke / IR barrier assemblies; confirm the builder has appropriate soldering tools and experience before starting.',
+    level: 'critical'
+  });
+
+  const prebuild = findSection('prebuild');
+  addUnique(prebuild?.items, {
+    text: 'Confirm the exact PCB revisions before assembly: BB_Feeder_main_V1 / V1.1, BB_IR_light_curtain, BB_Feeder_IRBarrier_V1.1, BB_RPi_shield_V1.1, and BP_Lighting_V1.1.',
+    level: 'critical'
+  }, 2);
+  addUnique(prebuild?.items, {
+    text: 'Confirm soldering capability and required soldering steps for the screen and IR nosepoke / IR barrier assemblies.',
+    level: 'critical'
+  }, 4);
+
+  const partPrepIntegrity = findSubsection('part_prep', '2. Verify printed-part integrity');
+  addUnique(partPrepIntegrity?.items, {
+    text: 'Use tissue forceps to clean small 3D-printing imperfections and to open insert entries before placing inserts.',
+    level: 'caution'
+  });
+  addUnique(partPrepIntegrity?.items, {
+    text: 'Start each insert by pushing gently with a thumb only to initiate entry, then use the 2.5 mm T-handle ball-end hex key to drive it in straight.',
+    level: 'critical'
+  });
+
+  const stageA = findSection('stage_a');
+  const basePrep = stageA?.subsections?.find(subsection => subsection.title === '3. Prepare the base');
+  if (basePrep) {
+    basePrep.media = {
+      src: '/videos/buidling_gifs/BEATBox_foot1.gif',
+      alt: 'Installing the BEATBox base foot assembly',
+      caption: 'Base and foot assembly reference.'
+    };
+  }
+
+  const pillars = findSubsection('stage_a', '4. Prepare the pillars');
+  addUnique(pillars?.items, {
+    text: 'Use tissue forceps to clear insert/nut seats and start inserts cleanly before driving them with the 2.5 mm T-handle ball-end hex key.',
+    level: 'caution'
+  });
+  addUnique(pillars?.items, {
+    text: 'Place the pillar on a flat, solid surface before applying force to inserts; never brace the part against your hand or body.',
+    level: 'critical'
+  });
+
+  const wallBuild = findSubsection('stage_b', '6. Build each plexiglass sandwich panel');
+  addUnique(wallBuild?.items, {
+    text: 'Resolve wall color for tracking before production: compare white, black, and gray for tracking contrast, reflections, lighting stability, and compatibility with the camera/IR setup.',
+    level: 'todo',
+    note: 'Decision still open.'
+  });
+
+  const screenPreparation = findSubsection('screen_module', 'Preparation');
+  addUnique(screenPreparation?.items, {
+    text: 'Confirm soldering is complete or planned for the screen assembly before closing the module.',
+    level: 'critical'
+  });
+  addUnique(screenPreparation?.items, {
+    text: 'Define and document the optimal cable length: cables must be neither too long nor too short, with enough slack for connection but no loops that interfere with closing or mounting.',
+    level: 'todo'
+  });
+
+  const screenAssembly = findSubsection('screen_module', 'Assembly');
+  if (screenAssembly?.items) {
+    replaceItemText(screenAssembly.items, 'Install required M3 inserts.', 'Install required M3 inserts using tissue forceps to start the entry and the 2.5 mm T-handle ball-end hex key to drive them in straight.');
+    replaceItemText(screenAssembly.items, 'Mount the screen PCB.', 'Screw the screen alone into the first housing part.');
+    replaceItemText(screenAssembly.items, 'Insert the screen in the intended orientation.', 'Place and route the cables before joining the two housing/electronic parts.');
+    replaceItemText(screenAssembly.items, 'Connect the screen properly to the board.', 'Connect the two parts, checking connector orientation and cable strain before tightening.');
+    replaceItemText(screenAssembly.items, 'Add the cover/front face.', 'Screw the second housing part only after cables are seated, strain-free, and clear of the closing surfaces.');
+    addUnique(screenAssembly.items, {
+      text: 'Verify cable length after closure: not too short to pull connectors, not too long to create loops or pinching. Define the optimal length and preferred routing solution for the release.',
+      level: 'todo'
+    });
+  }
+
+  const screenIr = findSubsection('screen_module', 'IR barrier on screen-side module');
+  addUnique(screenIr?.items, {
+    text: 'Confirm soldering requirements for IR nosepoke / IR barrier elements before mounting.',
+    level: 'critical'
+  });
+
+  const ceilingAssembly = findSubsection('ceiling_module', 'Assembly');
+  replaceItemText(ceilingAssembly?.items, 'Install inserts as needed.', 'Install inserts as needed, using tissue forceps to clean the entry and the 2.5 mm T-handle ball-end hex key to drive inserts in straight over a flat, solid surface.');
+
+  const tunnelItems = findSection('tunnel_module')?.items;
+  replaceItemText(tunnelItems, 'Install inserts.', 'Install inserts, using tissue forceps to clean the entry and the 2.5 mm T-handle ball-end hex key to drive inserts in straight over a flat, solid surface.');
+
+  const feederPrep = findSubsection('feeder_module', 'Preparation');
+  addUnique(feederPrep?.items, {
+    text: 'Confirm whether BB_Feeder_main_V1 or BB_Feeder_main_V1.1 is used for this build.',
+    level: 'critical'
+  }, 1);
+  addUnique(feederPrep?.items, {
+    text: 'Confirm BB_Feeder_IRBarrier_V1.1 sensor hardware and any required soldering are complete.',
+    level: 'critical'
+  });
+
+  const feederMechanical = findSubsection('feeder_module', 'Mechanical assembly');
+  replaceItemText(feederMechanical?.items, 'Install M3 inserts in the feeder housing.', 'Install M3 inserts in the feeder housing, using tissue forceps to clean/start the entry and the 2.5 mm T-handle ball-end hex key to drive inserts in straight over a flat, solid surface.');
+  addUnique(feederMechanical?.items, {
+    text: 'For feeder IR sensors, physically remove the small black locating pin with scissors or tissue forceps when it prevents flat contact with the wall surface.',
+    level: 'critical'
+  }, 2);
+}
+function renderMedia(media) {
+  if (!media?.src) return '';
+  const caption = media.caption ? `<figcaption>${escapeHTML(media.caption)}</figcaption>` : '';
+  return `<figure class="instruction-media"><img src="${escapeHTML(media.src)}" alt="${escapeHTML(media.alt || '')}" loading="lazy" />${caption}</figure>`;
+}
 function renderItems(items, section, path='') {
   if (!items || !items.length) return '';
   return `<div class="checklist">${items.map(item => {
@@ -446,6 +652,7 @@ <h1 id="pageTitle"></h1>
         <div class="subsection">
           <h3>${escapeHTML(sub.title)}</h3>
           ${sub.intro ? `<p class="intro">${escapeHTML(sub.intro)}</p>` : ''}
+          ${renderMedia(sub.media)}
           ${renderItems(sub.items || [], section, sub.title)}
         </div>`).join('');
     } else {
@@ -627,4 +834,4 @@ <h3>${escapeHTML(sub.title)}</h3>
 init();
 </script>
 </body>
-</html>
+</html>