@sensebox/flash-tool 0.1.0 → 1.0.0

package/dist/index.cjs

@@ -190,12 +190,17 @@ var DEFAULT_FLASH_OPTIONS = {
   eraseAll: false,
   usingUsbOtg: true
 };
+var KNOWN_USB_DEVICES = {
+  "303a:81b8": "senseBox MCU-S2 (ESP32-S2)",
+  "303a:2": "senseBox MCU-S2 (ESP32-S2 bootloader)"
+};
 function labelForPort(port) {
   var _a;
   const info = _nullishCoalesce(((_a = port.getInfo) == null ? void 0 : _a.call(port)), () => ( {}));
   const vendor = info.usbVendorId ? info.usbVendorId.toString(16).padStart(4, "0") : "????";
   const product = info.usbProductId ? info.usbProductId.toString(16).padStart(4, "0") : "????";
-  return `USB device (VID 0x${vendor} / PID 0x${product})`;
+  const known = info.usbVendorId !== void 0 && info.usbProductId !== void 0 ? KNOWN_USB_DEVICES[`${info.usbVendorId.toString(16)}:${info.usbProductId.toString(16)}`] : void 0;
+  return known || `USB device (VID 0x${vendor} / PID 0x${product})`;
 }
 function useFlashDevice({
   usbVendorId = DEFAULT_USB_VENDOR_ID,
@@ -222,10 +227,17 @@ function useFlashDevice({
         filters: [{ usbVendorId }]
       });
       setPort(selectedPort);
-      setBootloaderPort(null);
       setNeedsBootloaderPermission(false);
       const label = labelForPort(selectedPort);
       setDeviceLabel(label);
+      if (isRomBootloaderPort(selectedPort, usbVendorId)) {
+        setBootloaderPort(selectedPort);
+        appendLog(
+          "Board is already in bootloader mode - skipping reset.\n"
+        );
+      } else {
+        setBootloaderPort(null);
+      }
       return selectedPort;
     } catch (err) {
       if ((err == null ? void 0 : err.name) !== "NotFoundError") {
@@ -233,7 +245,7 @@ function useFlashDevice({
       }
       return null;
     }
-  }, [usbVendorId]);
+  }, [usbVendorId, appendLog]);
   const disconnect = _react.useCallback.call(void 0, () => {
     setPort(null);
     setBootloaderPort(null);
@@ -391,7 +403,7 @@ function useFlashDevice({
 var LOADERS = {
   circuitpy: () => Promise.resolve().then(() => _interopRequireWildcard(require("./circuitpy-YPOEPYDE.cjs"))),
   ota: () => Promise.resolve().then(() => _interopRequireWildcard(require("./ota-FYGBPZA7.cjs"))),
-  basic: () => Promise.resolve().then(() => _interopRequireWildcard(require("./basic-O4U74F7T.cjs"))),
+  basic: () => Promise.resolve().then(() => _interopRequireWildcard(require("./basic-PDQS3NQS.cjs"))),
   standard: () => Promise.resolve().then(() => _interopRequireWildcard(require("./standard-N65QFGWL.cjs")))
 };
 var BUILTIN_FIRMWARE_TYPES = Object.keys(LOADERS);
@@ -410,15 +422,263 @@ async function loadBuiltinFirmware(type) {
   return base64ToBytes(module.default);
 }
 
+// src/react/Dropdown.jsx
+
+
+function Dropdown({
+  options,
+  value,
+  onChange,
+  disabled = false,
+  placeholder,
+  className,
+  "aria-label": ariaLabel
+}) {
+  const [open, setOpen] = _react.useState.call(void 0, false);
+  const [activeIndex, setActiveIndex] = _react.useState.call(void 0, -1);
+  const rootRef = _react.useRef.call(void 0, null);
+  const triggerRef = _react.useRef.call(void 0, null);
+  const optionRefs = _react.useRef.call(void 0, []);
+  const selectedIndex = options.findIndex((option) => option.value === value);
+  const selected = selectedIndex >= 0 ? options[selectedIndex] : null;
+  _react.useEffect.call(void 0, () => {
+    if (disabled && open) setOpen(false);
+  }, [disabled, open]);
+  _react.useEffect.call(void 0, () => {
+    if (!open) return;
+    const onDocPointerDown = (event) => {
+      if (rootRef.current && !rootRef.current.contains(event.target)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("pointerdown", onDocPointerDown);
+    return () => document.removeEventListener("pointerdown", onDocPointerDown);
+  }, [open]);
+  _react.useEffect.call(void 0, () => {
+    if (!open) return;
+    setActiveIndex(selectedIndex >= 0 ? selectedIndex : 0);
+  }, [open, selectedIndex]);
+  _react.useEffect.call(void 0, () => {
+    var _a;
+    if (!open || activeIndex < 0) return;
+    (_a = optionRefs.current[activeIndex]) == null ? void 0 : _a.focus();
+  }, [open, activeIndex]);
+  const commit = (index) => {
+    var _a;
+    const option = options[index];
+    if (!option || option.disabled) return;
+    onChange == null ? void 0 : onChange(option.value);
+    setOpen(false);
+    (_a = triggerRef.current) == null ? void 0 : _a.focus();
+  };
+  const handleTriggerKeyDown = (event) => {
+    if (disabled) return;
+    if (event.key === "Enter" || event.key === " " || event.key === "ArrowDown" || event.key === "ArrowUp") {
+      event.preventDefault();
+      setOpen(true);
+    }
+  };
+  const moveActive = (delta) => {
+    setActiveIndex((current) => {
+      const count = options.length;
+      let next = current;
+      for (let i = 0; i < count; i++) {
+        next = (next + delta + count) % count;
+        if (!options[next].disabled) return next;
+      }
+      return current;
+    });
+  };
+  const handleListKeyDown = (event) => {
+    var _a;
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        moveActive(1);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        moveActive(-1);
+        break;
+      case "Home":
+        event.preventDefault();
+        setActiveIndex(0);
+        break;
+      case "End":
+        event.preventDefault();
+        setActiveIndex(options.length - 1);
+        break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        commit(activeIndex);
+        break;
+      case "Escape":
+        event.preventDefault();
+        setOpen(false);
+        (_a = triggerRef.current) == null ? void 0 : _a.focus();
+        break;
+      case "Tab":
+        setOpen(false);
+        break;
+      default:
+        break;
+    }
+  };
+  return /* @__PURE__ */ _react2.default.createElement(
+    "div",
+    {
+      ref: rootRef,
+      className: `sbdropdown${open ? " sbdropdown--open" : ""}${disabled ? " sbdropdown--disabled" : ""}${className ? ` ${className}` : ""}`
+    },
+    /* @__PURE__ */ _react2.default.createElement(
+      "button",
+      {
+        ref: triggerRef,
+        type: "button",
+        className: "sbdropdown__trigger",
+        "aria-haspopup": "listbox",
+        "aria-expanded": open,
+        "aria-label": ariaLabel,
+        disabled,
+        onClick: () => setOpen((v) => !v),
+        onKeyDown: handleTriggerKeyDown
+      },
+      /* @__PURE__ */ _react2.default.createElement("span", { className: "sbdropdown__icon-slot" }, selected == null ? void 0 : selected.icon),
+      /* @__PURE__ */ _react2.default.createElement("span", { className: "sbdropdown__trigger-label" }, (selected == null ? void 0 : selected.label) || placeholder),
+      /* @__PURE__ */ _react2.default.createElement(IconChevron, { className: "sbdropdown__chevron" })
+    ),
+    /* @__PURE__ */ _react2.default.createElement(
+      "ul",
+      {
+        className: "sbdropdown__menu",
+        role: "listbox",
+        "aria-label": ariaLabel,
+        onKeyDown: handleListKeyDown
+      },
+      options.map((option, index) => /* @__PURE__ */ _react2.default.createElement("li", { key: option.value, role: "presentation" }, /* @__PURE__ */ _react2.default.createElement(
+        "button",
+        {
+          ref: (el) => {
+            optionRefs.current[index] = el;
+          },
+          type: "button",
+          role: "option",
+          "aria-selected": option.value === value,
+          tabIndex: -1,
+          className: `sbdropdown__option${option.value === value ? " sbdropdown__option--selected" : ""}${index === activeIndex ? " sbdropdown__option--active" : ""}`,
+          disabled: option.disabled,
+          onClick: () => commit(index),
+          onMouseEnter: () => setActiveIndex(index)
+        },
+        /* @__PURE__ */ _react2.default.createElement("span", { className: "sbdropdown__icon-slot" }, option.icon),
+        /* @__PURE__ */ _react2.default.createElement("span", { className: "sbdropdown__option-label" }, option.label),
+        option.value === value && /* @__PURE__ */ _react2.default.createElement(IconCheck, { className: "sbdropdown__option-check" })
+      )))
+    )
+  );
+}
+function IconChevron({ className }) {
+  return /* @__PURE__ */ _react2.default.createElement(
+    "svg",
+    {
+      className,
+      viewBox: "0 0 10 6",
+      width: "10",
+      height: "6",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "1.5",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true"
+    },
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M1 1l4 4 4-4" })
+  );
+}
+function IconCheck({ className }) {
+  return /* @__PURE__ */ _react2.default.createElement(
+    "svg",
+    {
+      className,
+      viewBox: "0 0 16 16",
+      width: "12",
+      height: "12",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true"
+    },
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M3 8.5 6.5 12 13 4.5" })
+  );
+}
+Dropdown.propTypes = {
+  options: _proptypes2.default.arrayOf(
+    _proptypes2.default.shape({
+      value: _proptypes2.default.string.isRequired,
+      label: _proptypes2.default.node.isRequired,
+      icon: _proptypes2.default.node,
+      disabled: _proptypes2.default.bool
+    })
+  ).isRequired,
+  value: _proptypes2.default.string,
+  onChange: _proptypes2.default.func,
+  disabled: _proptypes2.default.bool,
+  placeholder: _proptypes2.default.string,
+  className: _proptypes2.default.string,
+  "aria-label": _proptypes2.default.string
+};
+
 // src/react/FlashTool.jsx
 var builtinFirmwareCache = /* @__PURE__ */ new Map();
 var FIRMWARE_TYPES = ["circuitpy", "ota", "basic", "standard"];
+var FIRMWARE_ALIASES = {
+  circuitpython: "circuitpy"
+};
+function resolveFirmwareType(value) {
+  if (!value) return void 0;
+  return FIRMWARE_ALIASES[value] || value;
+}
 var BUILTIN_FIRMWARE_FLASH_OVERRIDES = {
   circuitpy: { address: 0, eraseAll: true },
   ota: { address: 0, eraseAll: true },
   basic: { address: 0, eraseAll: true },
   standard: { address: 0, eraseAll: true }
 };
+var DEFAULT_FIRMWARE_DESCRIPTIONS = {
+  circuitpy: {
+    text: "Install CircuitPython on your senseBox now! For a more detailed tutorial, check out our",
+    linkText: "docs",
+    linkUrl: "https://docs.sensebox.de/docs/editors/circuitpython/circuitpython_esp32/?board=edus2"
+  },
+  ota: {
+    text: "Flashes the senseBox OTA firmware, which lets you update your senseBox wirelessly afterwards."
+  },
+  basic: {
+    text: "A minimal starter sketch - a good starting point for your own senseBox projects."
+  },
+  standard: {
+    text: "The TinyUF2 bootloader, ready to read out and upload data from your connected sensors."
+  }
+};
+var DEFAULT_FIRMWARE_DESCRIPTIONS_DE = {
+  circuitpy: {
+    text: "Installiere jetzt CircuitPython auf deiner senseBox! Ein ausf\xFChrliches Tutorial findest du in unserer",
+    linkText: "Dokumentation",
+    linkUrl: "https://docs.sensebox.de/docs/editors/circuitpython/circuitpython_esp32/?board=edus2"
+  },
+  ota: {
+    text: "Spielt die senseBox-OTA-Firmware auf, mit der du deine senseBox anschlie\xDFend drahtlos aktualisieren kannst."
+  },
+  basic: {
+    text: "Ein minimales Starter-Sketch - ein guter Ausgangspunkt f\xFCr eigene senseBox-Projekte."
+  },
+  standard: {
+    text: "Das Standard-senseBox-Sketch, bereit zum Auslesen und Hochladen von Daten deiner angeschlossenen Sensoren."
+  }
+};
 var DEFAULT_STRINGS = {
   unsupported: "Web Serial is not supported in this browser.",
   connect: "Connect board",
@@ -432,16 +692,26 @@ var DEFAULT_STRINGS = {
   flash: "Upload",
   flashing: "Uploading...",
   done: "Upload complete",
+  newUpload: "Start new upload",
   error: "Upload failed",
   retry: "Retry",
   disconnect: "Disconnect",
   showLog: "Show log",
   hideLog: "Hide log",
+  logPlaceholder: 'Click "Connect board" to see the log here.',
   sketchLabel: "Sketch",
+  step1Title: "Connect your board",
+  step1Hint: "Plug in your senseBox, then pick it from the browser's device list.",
+  step2Title: "Enter bootloader mode",
+  step2Hint: "Put the board into upload mode.",
+  step2HintPermission: "Select the bootloader port the browser is asking for.",
+  step2Done: "Bootloader ready",
+  step3Title: "Upload firmware",
+  step3Hint: "Waiting for the previous steps to finish.",
   firmwareCircuitpy: "CircuitPython",
   firmwareOta: "senseBox OTA",
-  firmwareBasic: "Basic",
-  firmwareStandard: "Standard senseBox Sketch",
+  firmwareBasic: "senseBox:basic",
+  firmwareStandard: "TinyUF2",
   help: "Help",
   helpTitle: "How it works",
   helpStep1: "Connect your senseBox",
@@ -450,15 +720,60 @@ var DEFAULT_STRINGS = {
   helpStep4: "Start the upload",
   helpClose: "Close"
 };
+var DEFAULT_STRINGS_DE = {
+  unsupported: "Web Serial wird von diesem Browser nicht unterst\xFCtzt.",
+  connect: "Board verbinden",
+  connecting: "Verbinde...",
+  connected: "senseBox verbunden",
+  prepare: "Upload vorbereiten",
+  preparing: "Bereite vor...",
+  grantPermission: "Bootloader-Port ausw\xE4hlen",
+  waitingForBinary: "Warte auf Firmware...",
+  loadingFirmware: "Firmware wird geladen...",
+  flash: "Hochladen",
+  flashing: "Wird hochgeladen...",
+  done: "Upload abgeschlossen",
+  newUpload: "Neuen Upload starten",
+  error: "Upload fehlgeschlagen",
+  retry: "Erneut versuchen",
+  disconnect: "Trennen",
+  showLog: "Protokoll anzeigen",
+  hideLog: "Protokoll ausblenden",
+  logPlaceholder: 'Klicke auf "Board verbinden", um das Protokoll hier zu sehen.',
+  sketchLabel: "Sketch",
+  step1Title: "Board verbinden",
+  step1Hint: "Schlie\xDFe deine senseBox an und w\xE4hle sie aus der Ger\xE4teliste des Browsers aus.",
+  step2Title: "Bootloader-Modus aktivieren",
+  step2Hint: "Versetze das Board in den Upload-Modus.",
+  step2HintPermission: "W\xE4hle den Bootloader-Port aus, nach dem der Browser fragt.",
+  step2Done: "Bootloader bereit",
+  step3Title: "Firmware hochladen",
+  step3Hint: "Warte auf die vorherigen Schritte.",
+  firmwareCircuitpy: "CircuitPython",
+  firmwareOta: "senseBox OTA",
+  firmwareBasic: "senseBox:basic",
+  firmwareStandard: "TinyUF2",
+  help: "Hilfe",
+  helpTitle: "So funktioniert's",
+  helpStep1: "Verbinde deine senseBox",
+  helpStep2: "W\xE4hle einen Sketch aus",
+  helpStep3: "Erteile deinem Browser die Berechtigung",
+  helpStep4: "Starte den Upload",
+  helpClose: "Schlie\xDFen"
+};
 function FlashTool({
   binary,
   firmwares,
+  firmware,
   firmwareType,
   defaultFirmwareType,
   firmwareFlashOptions,
+  firmwareDescriptions,
   usbVendorId,
   flashOptions,
   autoFlash = true,
+  expand = false,
+  language = "en",
   strings,
   className,
   onConnected,
@@ -467,18 +782,25 @@ function FlashTool({
   onError,
   onFirmwareTypeChange
 }) {
-  const merged = { ...DEFAULT_STRINGS, ...strings };
-  const [logOpen, setLogOpen] = _react2.default.useState(false);
+  const merged = {
+    ...language === "de" ? DEFAULT_STRINGS_DE : DEFAULT_STRINGS,
+    ...strings
+  };
+  const [logOpen, setLogOpen] = _react2.default.useState(expand);
   const [helpOpen, setHelpOpen] = _react2.default.useState(false);
   const [busy, setBusy] = _react2.default.useState(null);
+  const lockedFirmwareType = resolveFirmwareType(firmwareType || firmware);
   const [selectedType, setSelectedType] = _react2.default.useState(
-    firmwareType || defaultFirmwareType || FIRMWARE_TYPES[0]
+    lockedFirmwareType || defaultFirmwareType || FIRMWARE_TYPES[0]
   );
-  const firmwareLocked = Boolean(firmwareType);
+  const firmwareLocked = Boolean(lockedFirmwareType);
   const showFirmwarePicker = Boolean(firmwares) || !binary || firmwareLocked;
   _react.useEffect.call(void 0, () => {
-    if (firmwareType) setSelectedType(firmwareType);
-  }, [firmwareType]);
+    if (lockedFirmwareType) setSelectedType(lockedFirmwareType);
+  }, [lockedFirmwareType]);
+  _react.useEffect.call(void 0, () => {
+    if (expand) setLogOpen(true);
+  }, [expand]);
   _react.useEffect.call(void 0, () => {
     if (!helpOpen) return;
     const onKeyDown = (event) => {
@@ -552,16 +874,30 @@ function FlashTool({
   const latestLogLine = _react2.default.useMemo(() => {
     if (!log) return "";
     const lines = log.split("\n").filter((line) => line.trim().length > 0);
-    return lines[lines.length - 1] || "";
+    const lastLine = lines[lines.length - 1] || "";
+    return lastLine.replace(/\s*\(\d+ ?%\)\s*$/, "");
   }, [log]);
-  const handleFirmwareChange = (event) => {
-    const value = event.target.value;
+  const activeFirmwareDescription = showFirmwarePicker ? {
+    ...language === "de" ? DEFAULT_FIRMWARE_DESCRIPTIONS_DE[selectedType] : DEFAULT_FIRMWARE_DESCRIPTIONS[selectedType],
+    ...firmwareDescriptions == null ? void 0 : firmwareDescriptions[selectedType]
+  } : null;
+  const handleFirmwareChange = (value) => {
     setSelectedType(value);
     onFirmwareTypeChange == null ? void 0 : onFirmwareTypeChange(value);
   };
+  const firmwareOptions = FIRMWARE_TYPES.map((type) => ({
+    value: type,
+    label: merged[`firmware${type.charAt(0).toUpperCase()}${type.slice(1)}`],
+    icon: FIRMWARE_ICONS[type]
+  }));
   const handleRetryFirmwareLoad = () => {
     setBuiltinRetryToken((token) => token + 1);
   };
+  const logRef = _react.useRef.call(void 0, null);
+  _react.useEffect.call(void 0, () => {
+    if (!logOpen || !logRef.current) return;
+    logRef.current.scrollTop = logRef.current.scrollHeight;
+  }, [log, logOpen]);
   const prevConnected = _react.useRef.call(void 0, connected);
   _react.useEffect.call(void 0, () => {
     if (connected && !prevConnected.current) onConnected == null ? void 0 : onConnected(deviceLabel);
@@ -621,24 +957,20 @@ function FlashTool({
     resetFlashState();
     if (resolvedBinary) flash(resolvedBinary, flashOverrides);
   };
-  return /* @__PURE__ */ _react2.default.createElement("div", { className: `sbflash ${className || ""}` }, /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__row" }, /* @__PURE__ */ _react2.default.createElement(
-    "span",
-    {
-      className: `sbflash__dot sbflash__dot--${status === "error" ? "error" : status === "flashing" ? "busy" : connected ? "ok" : "off"}`
-    }
-  ), /* @__PURE__ */ _react2.default.createElement(
-    "span",
-    {
-      className: "sbflash__label",
-      title: connected ? deviceLabel : void 0
-    },
-    connected ? merged.connected : merged.connect
-  )), /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__field" }, /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__field-head" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__field-label" }, merged.sketchLabel), /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__icon-row" }, log && /* @__PURE__ */ _react2.default.createElement(
+  const flashComplete = status === "done";
+  const step1Status = flashComplete ? "done" : connected ? "done" : "active";
+  const step2Status = flashComplete ? "done" : !connected ? "pending" : bootloaderReady ? "done" : "active";
+  const step3Status = flashComplete ? "done" : !bootloaderReady ? "pending" : status === "error" ? "error" : "active";
+  const handleStartNew = () => {
+    resetFlashState();
+  };
+  return /* @__PURE__ */ _react2.default.createElement("div", { className: `sbflash ${className || ""}` }, /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__field" }, /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__field-head" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__field-label" }, merged.sketchLabel), /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__icon-row" }, /* @__PURE__ */ _react2.default.createElement(
     "button",
     {
       type: "button",
       className: `sbflash__icon-button${logOpen ? " sbflash__icon-button--active" : ""}`,
-      onClick: () => setLogOpen((v) => !v),
+      onClick: () => !expand && setLogOpen((v) => !v),
+      disabled: expand,
       "aria-pressed": logOpen,
       "aria-label": logOpen ? merged.hideLog : merged.showLog,
       title: logOpen ? merged.hideLog : merged.showLog
@@ -664,16 +996,16 @@ function FlashTool({
       title: merged.help
     },
     /* @__PURE__ */ _react2.default.createElement(IconHelp, null)
-  ))), showFirmwarePicker && /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__select-wrap" }, /* @__PURE__ */ _react2.default.createElement(
-    "select",
+  ))), showFirmwarePicker && /* @__PURE__ */ _react2.default.createElement(
+    Dropdown,
     {
-      className: "sbflash__select",
+      options: firmwareOptions,
       value: selectedType,
       onChange: handleFirmwareChange,
-      disabled: firmwareLocked || status === "flashing"
-    },
-    FIRMWARE_TYPES.map((type) => /* @__PURE__ */ _react2.default.createElement("option", { key: type, value: type }, merged[`firmware${type.charAt(0).toUpperCase()}${type.slice(1)}`]))
-  )), builtinError && /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__field-error-row" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__field-error" }, builtinError), /* @__PURE__ */ _react2.default.createElement(
+      disabled: firmwareLocked || status === "flashing",
+      "aria-label": merged.sketchLabel
+    }
+  ), builtinError && /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__field-error-row" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__field-error" }, builtinError), /* @__PURE__ */ _react2.default.createElement(
     "button",
     {
       type: "button",
@@ -681,7 +1013,15 @@ function FlashTool({
       onClick: handleRetryFirmwareLoad
     },
     merged.retry
-  ))), helpOpen && _reactdom.createPortal.call(void 0, 
+  )), (activeFirmwareDescription == null ? void 0 : activeFirmwareDescription.text) && /* @__PURE__ */ _react2.default.createElement("p", { className: "sbflash__field-description" }, activeFirmwareDescription.text, activeFirmwareDescription.linkUrl && /* @__PURE__ */ _react2.default.createElement(_react2.default.Fragment, null, " ", /* @__PURE__ */ _react2.default.createElement(
+    "a",
+    {
+      href: activeFirmwareDescription.linkUrl,
+      target: "_blank",
+      rel: "noopener noreferrer"
+    },
+    activeFirmwareDescription.linkText || activeFirmwareDescription.linkUrl
+  )))), helpOpen && _reactdom.createPortal.call(void 0, 
     /* @__PURE__ */ _react2.default.createElement(
       "div",
       {
@@ -716,7 +1056,12 @@ function FlashTool({
       )
     ),
     document.body
-  ), !connected && /* @__PURE__ */ _react2.default.createElement(
+  ), /* @__PURE__ */ _react2.default.createElement("ol", { className: "sbflash__stepper" }, /* @__PURE__ */ _react2.default.createElement("li", { className: `sbflash__step sbflash__step--${step1Status}` }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-marker" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-index" }, step1Status === "done" ? /* @__PURE__ */ _react2.default.createElement(IconCheck2, null) : 1), /* @__PURE__ */ _react2.default.createElement(
+    "span",
+    {
+      className: `sbflash__step-line${step1Status === "done" ? " sbflash__step-line--done" : ""}`
+    }
+  )), /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__step-body" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-title" }, merged.step1Title), !connected && !flashComplete ? /* @__PURE__ */ _react2.default.createElement(_react2.default.Fragment, null, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-hint" }, merged.step1Hint), /* @__PURE__ */ _react2.default.createElement(
     "button",
     {
       type: "button",
@@ -725,7 +1070,12 @@ function FlashTool({
       disabled: busy === "connect"
     },
     busy === "connect" ? merged.connecting : merged.connect
-  ), connected && needsBootloaderPermission && /* @__PURE__ */ _react2.default.createElement(
+  )) : /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-detail", title: deviceLabel }, deviceLabel || merged.connected))), /* @__PURE__ */ _react2.default.createElement("li", { className: `sbflash__step sbflash__step--${step2Status}` }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-marker" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-index" }, step2Status === "done" ? /* @__PURE__ */ _react2.default.createElement(IconCheck2, null) : 2), /* @__PURE__ */ _react2.default.createElement(
+    "span",
+    {
+      className: `sbflash__step-line${step2Status === "done" ? " sbflash__step-line--done" : ""}`
+    }
+  )), /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__step-body" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-title" }, merged.step2Title), step2Status === "active" && needsBootloaderPermission && /* @__PURE__ */ _react2.default.createElement(_react2.default.Fragment, null, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-hint" }, merged.step2HintPermission), /* @__PURE__ */ _react2.default.createElement(
     "button",
     {
       type: "button",
@@ -734,16 +1084,7 @@ function FlashTool({
       disabled: busy === "grant"
     },
     merged.grantPermission
-  ), connected && !needsBootloaderPermission && !bootloaderReady && /* @__PURE__ */ _react2.default.createElement(
-    "button",
-    {
-      type: "button",
-      className: "sbflash__button sbflash__button--secondary",
-      onClick: handlePrepare,
-      disabled: busy === "prepare" || status === "flashing"
-    },
-    busy === "prepare" ? merged.preparing : merged.prepare
-  ), connected && bootloaderReady && status !== "flashing" && status !== "error" && /* @__PURE__ */ _react2.default.createElement(
+  )), step2Status === "active" && !needsBootloaderPermission && /* @__PURE__ */ _react2.default.createElement(_react2.default.Fragment, null, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-hint" }, merged.step2Hint)), step2Status === "done" && /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-detail" }, merged.step2Done), step2Status === "pending" && /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-hint" }, merged.step2Hint))), /* @__PURE__ */ _react2.default.createElement("li", { className: `sbflash__step sbflash__step--${step3Status}` }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-marker" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-index" }, step3Status === "done" ? /* @__PURE__ */ _react2.default.createElement(IconCheck2, null) : 3)), /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__step-body" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-title" }, merged.step3Title), step3Status === "pending" && /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__step-hint" }, merged.step3Hint), step3Status === "active" && status !== "flashing" && /* @__PURE__ */ _react2.default.createElement(
     "button",
     {
       type: "button",
@@ -758,7 +1099,15 @@ function FlashTool({
       className: "sbflash__progress-fill",
       style: { width: `${Math.min(100, progress)}%` }
     }
-  )), /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__progress-value" }, progress, "%")), latestLogLine && /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__progress-detail" }, latestLogLine)) : /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__task" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__task-spinner" }), /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__task-label" }, latestLogLine || merged.flashing))), status === "done" && /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__status sbflash__status--ok" }, merged.done), status === "error" && /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__status sbflash__status--error" }, merged.error, /* @__PURE__ */ _react2.default.createElement(
+  )), /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__progress-value" }, progress, "%")), latestLogLine && /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__progress-detail" }, latestLogLine)) : /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__task" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__task-spinner" }), /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__task-label" }, latestLogLine || merged.flashing))), status === "done" && /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__done-banner", role: "status" }, /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__done-icon" }, /* @__PURE__ */ _react2.default.createElement(IconCheck2, null)), /* @__PURE__ */ _react2.default.createElement("span", { className: "sbflash__done-text" }, merged.done), /* @__PURE__ */ _react2.default.createElement(
+    "button",
+    {
+      type: "button",
+      className: "sbflash__button sbflash__button--secondary",
+      onClick: handleStartNew
+    },
+    merged.newUpload
+  )), status === "error" && /* @__PURE__ */ _react2.default.createElement("div", { className: "sbflash__status sbflash__status--error" }, merged.error, /* @__PURE__ */ _react2.default.createElement(
     "button",
     {
       type: "button",
@@ -766,7 +1115,7 @@ function FlashTool({
       onClick: handleRetry
     },
     merged.retry
-  )), log && logOpen && /* @__PURE__ */ _react2.default.createElement("pre", { className: "sbflash__log" }, log));
+  ))))), logOpen && /* @__PURE__ */ _react2.default.createElement("pre", { className: "sbflash__log", ref: logRef }, log || merged.logPlaceholder));
 }
 function IconTerminal() {
   return /* @__PURE__ */ _react2.default.createElement(
@@ -787,6 +1136,23 @@ function IconTerminal() {
     /* @__PURE__ */ _react2.default.createElement("path", { d: "M8.5 11h3" })
   );
 }
+function IconCheck2() {
+  return /* @__PURE__ */ _react2.default.createElement(
+    "svg",
+    {
+      viewBox: "0 0 16 16",
+      width: "11",
+      height: "11",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true"
+    },
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M3 8.5 6.5 12 13 4.5" })
+  );
+}
 function IconDisconnect() {
   return /* @__PURE__ */ _react2.default.createElement(
     "svg",
@@ -824,6 +1190,85 @@ function IconHelp() {
     /* @__PURE__ */ _react2.default.createElement("circle", { cx: "8", cy: "11.5", r: "0.9", fill: "currentColor", stroke: "none" })
   );
 }
+function IconChip() {
+  return /* @__PURE__ */ _react2.default.createElement(
+    "svg",
+    {
+      viewBox: "0 0 16 16",
+      width: "14",
+      height: "14",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "1.4",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true"
+    },
+    /* @__PURE__ */ _react2.default.createElement("rect", { x: "4", y: "4", width: "8", height: "8", rx: "1.2" }),
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M6 1.5v2M10 1.5v2M6 12.5v2M10 12.5v2M1.5 6v-.01M1.5 10v-.01M14.5 6v-.01M14.5 10v-.01M1.5 6h2M1.5 10h2M12.5 6h2M12.5 10h2" })
+  );
+}
+function IconCloud() {
+  return /* @__PURE__ */ _react2.default.createElement(
+    "svg",
+    {
+      viewBox: "0 0 16 16",
+      width: "14",
+      height: "14",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "1.4",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true"
+    },
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M4.5 12.5A3 3 0 0 1 4 6.53 3.5 3.5 0 0 1 11 5.5a2.75 2.75 0 0 1 .5 5.46" }),
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M6.5 12.5h5" }),
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M8 9.5v5M6.25 12.25 8 14.5l1.75-2.25" })
+  );
+}
+function IconBolt() {
+  return /* @__PURE__ */ _react2.default.createElement(
+    "svg",
+    {
+      viewBox: "0 0 16 16",
+      width: "14",
+      height: "14",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "1.4",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true"
+    },
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M8.5 1.5 3 9h4l-1 5.5L13 7H9l-0.5-5.5Z" })
+  );
+}
+function IconLayers() {
+  return /* @__PURE__ */ _react2.default.createElement(
+    "svg",
+    {
+      viewBox: "0 0 16 16",
+      width: "14",
+      height: "14",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "1.4",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true"
+    },
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M8 1.75 14 5 8 8.25 2 5Z" }),
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M2 8 8 11.25 14 8" }),
+    /* @__PURE__ */ _react2.default.createElement("path", { d: "M2 11 8 14.25 14 11" })
+  );
+}
+var FIRMWARE_ICONS = {
+  circuitpy: /* @__PURE__ */ _react2.default.createElement(IconChip, null),
+  ota: /* @__PURE__ */ _react2.default.createElement(IconCloud, null),
+  basic: /* @__PURE__ */ _react2.default.createElement(IconBolt, null),
+  standard: /* @__PURE__ */ _react2.default.createElement(IconLayers, null)
+};
 FlashTool.propTypes = {
   /** Already-compiled firmware image to flash. Ignored if `firmwares` is set. */
   binary: _proptypes2.default.instanceOf(Uint8Array),
@@ -834,19 +1279,36 @@ FlashTool.propTypes = {
     basic: _proptypes2.default.instanceOf(Uint8Array),
     standard: _proptypes2.default.instanceOf(Uint8Array)
   }),
+  /** Same as `firmwareType`, but also accepts friendlier aliases (e.g. "circuitpython" for "circuitpy"). */
+  firmware: _proptypes2.default.oneOf([
+    ...FIRMWARE_TYPES,
+    ...Object.keys(FIRMWARE_ALIASES)
+  ]),
   /** Locks the sketch dropdown to this value and disables it. One of "circuitpy" | "ota" | "basic" | "standard". */
   firmwareType: _proptypes2.default.oneOf(FIRMWARE_TYPES),
   /** Initial dropdown selection when `firmwareType` isn't set (dropdown stays interactive). */
   defaultFirmwareType: _proptypes2.default.oneOf(FIRMWARE_TYPES),
   /** Per-sketch overrides for the esptool flash step, keyed by firmware type. Merges over (and can override) the built-in CircuitPython defaults. */
   firmwareFlashOptions: _proptypes2.default.objectOf(_proptypes2.default.object),
+  /** Per-sketch description shown under the sketch picker, keyed by firmware type: { text, linkText, linkUrl }. Merges over (and can override) the built-in defaults. */
+  firmwareDescriptions: _proptypes2.default.objectOf(
+    _proptypes2.default.shape({
+      text: _proptypes2.default.string,
+      linkText: _proptypes2.default.string,
+      linkUrl: _proptypes2.default.string
+    })
+  ),
   /** USB vendor id used to filter the device picker. Defaults to senseBox (0x303a). */
   usbVendorId: _proptypes2.default.number,
   /** Overrides for the esptool flash step (address, baudrate, flashMode, flashFreq, flashSize, eraseAll, usingUsbOtg). */
   flashOptions: _proptypes2.default.object,
   /** Start flashing automatically once the selected firmware and a connected device are both ready. */
   autoFlash: _proptypes2.default.bool,
-  /** Overrides for the built-in (English) UI strings. */
+  /** Keep the log/terminal view expanded by default and disable the button to collapse it. */
+  expand: _proptypes2.default.bool,
+  /** UI language for the built-in strings. "de" uses the built-in German translation. */
+  language: _proptypes2.default.oneOf(["en", "de"]),
+  /** Overrides for the built-in UI strings (applied on top of `language`). */
   strings: _proptypes2.default.object,
   className: _proptypes2.default.string,
   onConnected: _proptypes2.default.func,