Fix EasyEDA footprint model references

Rewrite EasyEDA footprint model paths after STEP/WRL export, strip stale KiCad model blocks when no 3D artifact is produced, and add service-worker regressions plus docs updates.

Author: JoeShade

CHANGELOG.md

@@ -38,6 +38,7 @@ This section summarizes the current `Development` branch compared with `main` as
 ### Fixed
 
 - Improved provider-aware page detection for JLCPCB, LCSC, Mouser, and Farnell product pages.
+- Reconciled EasyEDA footprint model references with exported STEP/WRL artifacts and removed stale model blocks when no 3D artifact is exported.
 - Preserved SamacSys KiCad library relationships by rewriting symbol footprint properties and footprint model paths in library mode.
 - Handled SamacSys ZIP structures where `KiCad/` and `3D/` folders appear either at the archive root or under a part-specific parent folder.
 - Reworked SamacSys ZIP `401` handling into clearer sign-in-required errors and retry behavior.

README.md

@@ -116,6 +116,8 @@ Downloads/
 `-- <component>-datasheet.pdf
 ```
 
+When a footprint and matching 3D model are exported together, the footprint model reference is rewritten to the generated model path. If no 3D model is exported, stale model references are removed from the generated footprint.
+
 ## Supported sources and outputs
 
 | Source flow | Pages | Symbol | Footprint | 3D model | Datasheet | Notes |

docs/architecture-notes.md

@@ -32,6 +32,7 @@ This file records short implementation notes that supplement, but do not replace
 - Farnell, element14, and Newark do not have their own backend adapter files because they intentionally reuse the shared SamacSys distributor backend.
 - Symbol library append behavior depends on `chrome.storage.local`, not on local filesystem reads.
 - Library-mode download paths remain relative to Downloads and are resolved from extension settings, not absolute filesystem paths.
+- EasyEDA footprints are written after 3D export attempts so their KiCad `(model ...)` path can match the artifact that was actually downloaded, or be stripped when no model artifact was produced.
 - SamacSys distributor support is still Chrome-first, but Firefox can opt into a user-managed relay through the advanced Firefox settings menu.
 - Chrome direct SamacSys ZIP export now retries once with configured upstream auth after a `401`, but preview requests still use the normal direct browser session without preemptive auth headers.
 - Firefox relay mode forwards matching `componentsearchengine.com` cookies so authenticated SamacSys ZIP downloads can reuse the browser session instead of teaching the relay to log in.

src/sources/easyeda_adapter.js

@@ -15,6 +15,7 @@ import {
 } from "./easyeda_common.js";
 import {
   createExportContext,
+  getLibraryName,
   resolveExportOptions,
   writeBinaryArtifact,
   writeSymbolArtifact,
@@ -27,6 +28,175 @@ function buildSafeFilename(name, extension, fallback) {
   return `${sanitizeFilenamePart(name, fallback)}.${extension}`;
 }
 
+function isKicadModelBlockStart(text, index) {
+  const token = "(model";
+  const nextChar = text[index + token.length] || "";
+  return (
+    text.startsWith(token, index) &&
+    (!nextChar || /\s|\)/.test(nextChar))
+  );
+}
+
+function findNextKicadModelBlock(text, startIndex = 0) {
+  let inString = false;
+  let escaped = false;
+
+  for (let index = startIndex; index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === "\"") {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === "\"") {
+      inString = true;
+      continue;
+    }
+    if (!isKicadModelBlockStart(text, index)) {
+      continue;
+    }
+
+    let depth = 0;
+    let blockInString = false;
+    let blockEscaped = false;
+    for (let blockEnd = index; blockEnd < text.length; blockEnd += 1) {
+      const blockChar = text[blockEnd];
+      if (blockInString) {
+        if (blockEscaped) {
+          blockEscaped = false;
+        } else if (blockChar === "\\") {
+          blockEscaped = true;
+        } else if (blockChar === "\"") {
+          blockInString = false;
+        }
+        continue;
+      }
+      if (blockChar === "\"") {
+        blockInString = true;
+        continue;
+      }
+      if (blockChar === "(") {
+        depth += 1;
+      } else if (blockChar === ")") {
+        depth -= 1;
+        if (depth === 0) {
+          return { start: index, end: blockEnd + 1 };
+        }
+      }
+    }
+
+    return null;
+  }
+
+  return null;
+}
+
+function stripKicadFootprintModels(footprintText) {
+  const text = String(footprintText || "");
+  let result = "";
+  let cursor = 0;
+  let modelBlock = findNextKicadModelBlock(text, cursor);
+
+  while (modelBlock) {
+    let removalStart = modelBlock.start;
+    while (removalStart > cursor && /[ \t]/.test(text[removalStart - 1])) {
+      removalStart -= 1;
+    }
+    if (removalStart > cursor && text[removalStart - 1] === "\n") {
+      removalStart -= 1;
+      if (removalStart > cursor && text[removalStart - 1] === "\r") {
+        removalStart -= 1;
+      }
+    }
+
+    result += text.slice(cursor, removalStart);
+    cursor = modelBlock.end;
+    modelBlock = findNextKicadModelBlock(text, cursor);
+  }
+
+  result += text.slice(cursor);
+  return result.replace(/(?:[ \t]*\r?\n){3,}/g, "\n\n");
+}
+
+function findKicadModelPathRange(modelBlockText) {
+  if (!modelBlockText.startsWith("(model")) {
+    return null;
+  }
+
+  let cursor = "(model".length;
+  while (cursor < modelBlockText.length && /\s/.test(modelBlockText[cursor])) {
+    cursor += 1;
+  }
+
+  if (modelBlockText[cursor] === "\"") {
+    const pathStart = cursor + 1;
+    let escaped = false;
+    for (cursor = pathStart; cursor < modelBlockText.length; cursor += 1) {
+      const char = modelBlockText[cursor];
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === "\"") {
+        return { start: pathStart, end: cursor };
+      }
+    }
+    return null;
+  }
+
+  const pathStart = cursor;
+  while (
+    cursor < modelBlockText.length &&
+    !/[\s)]/.test(modelBlockText[cursor])
+  ) {
+    cursor += 1;
+  }
+
+  if (cursor === pathStart) {
+    return null;
+  }
+
+  return { start: pathStart, end: cursor };
+}
+
+function rewriteFirstKicadFootprintModelPath(footprintText, modelPath) {
+  if (!modelPath) {
+    return stripKicadFootprintModels(footprintText);
+  }
+
+  const text = String(footprintText || "");
+  const modelBlock = findNextKicadModelBlock(text);
+  if (!modelBlock) {
+    return text;
+  }
+
+  const modelBlockText = text.slice(modelBlock.start, modelBlock.end);
+  const pathRange = findKicadModelPathRange(modelBlockText);
+  if (!pathRange) {
+    return text;
+  }
+
+  const rewrittenBlock = `${modelBlockText.slice(0, pathRange.start)}${modelPath}${modelBlockText.slice(pathRange.end)}`;
+  return `${text.slice(0, modelBlock.start)}${rewrittenBlock}${text.slice(modelBlock.end)}`;
+}
+
+function resolveEasyedaFootprintModelPath(exportContext, modelFilename) {
+  if (!modelFilename) {
+    return "";
+  }
+  if (exportContext.settings.downloadIndividually) {
+    return "${KIPRJMOD}/" + modelFilename;
+  }
+
+  const libraryName = getLibraryName(exportContext.libraryPaths);
+  return `../${libraryName}.3dshapes/${modelFilename}`;
+}
+
 function createEasyedaAdapter(deps) {
   const {
     chromeApi,
@@ -55,6 +225,11 @@ function createEasyedaAdapter(deps) {
         symbol: resolvedOptions.symbol,
         footprint: resolvedOptions.footprint
       });
+      const modelInfo = find3dModelInfo(cadData.packageDetail);
+      const safeModelName = modelInfo
+        ? sanitizeFilenamePart(modelInfo.name, modelInfo.uuid || "model")
+        : "";
+      let footprintModelFilename = "";
 
       if (kicadFiles.symbol) {
         const symbolFilename = buildSafeFilename(
@@ -72,28 +247,8 @@ function createEasyedaAdapter(deps) {
         });
       }
 
-      if (kicadFiles.footprint) {
-        const footprintFilename = buildSafeFilename(
-          kicadFiles.footprint.name,
-          "kicad_mod",
-          "footprint"
-        );
-        downloadCount += await writeTextArtifact({
-          downloads,
-          exportContext,
-          content: kicadFiles.footprint.content,
-          individualFilename: footprintFilename,
-          libraryPath: `${exportContext.libraryPaths.footprintDir}/${footprintFilename}`
-        });
-      }
-
       if (resolvedOptions.model3d) {
-        const modelInfo = find3dModelInfo(cadData.packageDetail);
         if (modelInfo) {
-          const safeModelName = sanitizeFilenamePart(
-            modelInfo.name,
-            modelInfo.uuid || "model"
-          );
           const stepResponse = await fetchImpl(
             EASYEDA_MODEL_STEP_ENDPOINT.replace("{uuid}", modelInfo.uuid)
           );
@@ -106,6 +261,7 @@ function createEasyedaAdapter(deps) {
               individualFilename: `${safeModelName}.step`,
               libraryPath: `${exportContext.libraryPaths.modelDir}/${safeModelName}.step`
             });
+            footprintModelFilename = `${safeModelName}.step`;
           } else {
             console.warn("3D STEP download failed:", stepResponse.status);
             warnings.push("3D STEP model download failed.");
@@ -124,6 +280,7 @@ function createEasyedaAdapter(deps) {
               individualFilename: `${safeModelName}.wrl`,
               libraryPath: `${exportContext.libraryPaths.modelDir}/${safeModelName}.wrl`
             });
+            footprintModelFilename = `${safeModelName}.wrl`;
           } else {
             console.warn("3D OBJ download failed:", objResponse.status);
             warnings.push("3D WRL model download failed.");
@@ -133,6 +290,30 @@ function createEasyedaAdapter(deps) {
         }
       }
 
+      if (kicadFiles.footprint) {
+        const footprintFilename = buildSafeFilename(
+          kicadFiles.footprint.name,
+          "kicad_mod",
+          "footprint"
+        );
+        const modelPath = resolveEasyedaFootprintModelPath(
+          exportContext,
+          footprintModelFilename
+        );
+        const footprintContent = rewriteFirstKicadFootprintModelPath(
+          kicadFiles.footprint.content,
+          modelPath
+        );
+
+        downloadCount += await writeTextArtifact({
+          downloads,
+          exportContext,
+          content: footprintContent,
+          individualFilename: footprintFilename,
+          libraryPath: `${exportContext.libraryPaths.footprintDir}/${footprintFilename}`
+        });
+      }
+
       if (resolvedOptions.datasheet) {
         if (!datasheetInfo.url) {
           warnings.push("Datasheet not available for this part.");

systemDesign.md

@@ -255,6 +255,10 @@ The test suite remains the primary regression net for:
   - loose-file downloads when `downloadIndividually` is `true`
   - KiCad-style library structure when `downloadIndividually` is `false`
 - Library-mode symbol exports merge into a stored symbol library keyed by the resolved library root.
+- Footprint model references are reconciled after 3D export attempts finish:
+  - loose-file footprints reference `${KIPRJMOD}/<modelFilename>` when a model was exported
+  - library-mode footprints reference `../<libraryName>.3dshapes/<modelFilename>` when a model was exported
+  - stale footprint `(model ...)` blocks are removed when no selected 3D model artifact is exported
 - Library-mode datasheet exports are written under `<libraryRoot>/datasheets/`.
 
 ### 5.4 Export SamacSys distributor parts
@@ -339,6 +343,7 @@ The test suite remains the primary regression net for:
 - SamacSys distributor loose-file symbol output keeps the extracted `.kicad_sym` filename from the ZIP.
 - Footprint output uses the extracted or generated `.kicad_mod` filename.
 - SamacSys distributor footprint library-mode downloads rewrite the model path into the library `.3dshapes` directory.
+- EasyEDA footprint downloads rewrite the first KiCad `(model ...)` path to the exported STEP or WRL artifact, preferring WRL when both are produced, and remove stale model blocks when no model artifact is exported.
 - EasyEDA datasheet output uses a sanitized base name plus `-datasheet` and the detected extension. In library mode it is saved under `<libraryRoot>/datasheets/`.
 - The library root name defaults to `easyECADDownloader` and can be changed to another Downloads-relative folder for library mode.