signalk-charts-provider-simple 2.2.0 → 2.3.0

package/README.md

@@ -7,6 +7,7 @@ A lightweight Signal K server plugin for managing local nautical charts, written
 - **Local Chart Management**: MBTiles (raster and vector), with folder organization and enable/disable toggles
 - **Download Manager**: Built-in download queue with progress tracking and ZIP extraction
 - **Chart Catalog**: Browse and download charts from [chartcatalogs.github.io](https://chartcatalogs.github.io/) with automatic update notifications
+- **NOAA Charts**: Draw a coverage region on a map from NOAA band-4 chart footprints; the plugin bundles the overlapping band-3/4/5 ENCs and converts them into a single vector MBTiles named after your chart set
 - **S-57 ENC Conversion**: Convert IENC/ENC charts to vector MBTiles with full S-52 symbology in Freeboard-SK
 - **BSB Raster Conversion**: Convert BSB/KAP raster charts and Pilot Charts to raster MBTiles
 - **World Basemaps**: GSHHG and OSM coastline basemaps for offline use
@@ -60,7 +61,7 @@ Access the plugin's web interface through your Signal K server:
 http://[your-server]:3000/plugins/signalk-charts-provider-simple/
 ```
 
-The interface provides four tabs:
+The interface provides five tabs:
 
 1. **Manage Charts**:
    - View all charts with metadata (name, bounds, zoom levels, size)
@@ -86,6 +87,15 @@ The interface provides four tabs:
    - Automatic update notifications (Signal K delta + tab badge)
    - Category filtering (MBTiles / RNC / IENC / General)
 
+5. **NOAA Charts**:
+   - Build a named **chart set** of NOAA ENC coverage by clicking band-4 footprints on a map (Leaflet + OpenSeaMap)
+   - Each band-4 selection automatically pulls in the overlapping band-3 and band-5 ENCs
+   - Footprint data from NOAA's [official chart locator](https://www.charts.noaa.gov/InteractiveCatalog/data/enc.geojson)
+   - Download & convert produces one `.mbtiles` per chart set, with live progress and a log
+   - Out-of-date detection when NOAA publishes new editions or your selection changes
+   - Container runtime (`signalk-container`) required, same as other conversions
+   - US waters only — NOAA is the only source of freely-downloadable ENC charts
+
 ### Supported Formats
 
 | Format | Source | Conversion | Output |

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAuExD,OAAO,KAAK,EAGV,iBAAiB,EAMlB,MAAM,YAAY,CAAC;AAepB,QAAA,MAAM,iBAAiB,GAAI,KAAK,iBAAiB,KAAG,MA+0FnD,CAAC;AAiHF,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,MAAM,EAAE,MAAM,qBAAqB,CAAC;AA0GxD,OAAO,KAAK,EAGV,iBAAiB,EAMlB,MAAM,YAAY,CAAC;AAepB,QAAA,MAAM,iBAAiB,GAAI,KAAK,iBAAiB,KAAG,MAi2GnD,CAAC;AAiHF,eAAe,iBAAiB,CAAC"}

package/dist/index.js

@@ -22,7 +22,10 @@ import { parsePluginConfig } from './utils/plugin-config-schema.js';
 import { cleanupQuarantineDir, makeQuarantineDir, promoteQuarantine, sweepStaleQuarantineDirs } from './utils/quarantine.js';
 import { parseBody, parseShape } from './utils/rest-validation.js';
 import { getAllConversionProgress as getAllRncProgress, getConversionProgress as getRncProgress, initRncConverter, processPilotTar, processRncZip, setConversionFailed as setRncFailed } from './utils/rnc-converter.js';
-import { getAllConversionProgress as getAllS57Progress, getConversionProgress as getS57Progress, initS57Converter, processGshhg, processS57Zip, processShpBasemap, setConversionFailed as setS57Failed } from './utils/s57-converter.js';
+import { getAllConversionProgress as getAllS57Progress, getConversionProgress as getS57Progress, initS57Converter, processGshhg, processS57Directory, processS57Zip, processShpBasemap, setConversionFailed as setS57Failed } from './utils/s57-converter.js';
+import { band4MapEntries, computeInclusion, coverageByBox, getFootprintIndex, initNoaaEncFootprints, peekFootprintIndex } from './utils/noaa-enc-footprints.js';
+import { appendCatalogLog, boxStatesForCatalog, clearCatalogCancel, clearCatalogProgress, createCustomCatalog, deleteCustomCatalog, evaluateFreshness, getCatalogDetail, getCatalogProgress, getCustomCatalog, initCustomCatalogManager, isCatalogBusy, isCatalogCancelRequested, isValidCatalogId, listCustomCatalogs, registerCatalogAbort, requestCatalogCancel, saveCustomCatalog, setCatalogBusy, setCatalogDetail, setCatalogFailed, setCatalogProgress } from './utils/custom-catalog-manager.js';
+import { downloadAndExtractEncs } from './utils/custom-catalog-download.js';
 // JSON import with type attribute (NodeNext ESM). package.json's `version`
 // is what the marker file records so users can confirm the running build.
 import packageJson from '../package.json' with { type: 'json' };
@@ -197,7 +200,9 @@ const pluginConstructor = (app) => {
         initChartState(pluginDataDir);
         const dataDir = pluginDataDir;
         initCatalogManager(dataDir, app.debug.bind(app));
-        const tempDirPattern = /^(s57-download-|rnc-download-|pilot-download-|shp-download-|gshhg-|convert-upload-)\d+$/;
+        initNoaaEncFootprints(dataDir, app.debug.bind(app));
+        initCustomCatalogManager(dataDir, app.debug.bind(app));
+        const tempDirPattern = /^(s57-download-|rnc-download-|pilot-download-|shp-download-|gshhg-|convert-upload-|custom-catalog-)\d+$/;
         try {
             const dataDirEntries = fs.readdirSync(dataDir, { withFileTypes: true });
             for (const entry of dataDirEntries) {
@@ -1905,6 +1910,205 @@ const pluginConstructor = (app) => {
                 });
             }
         });
+        // ---- Custom NOAA ENC catalogs ----
+        // Build a named bundle of NOAA band-4 coverage areas selected on a map,
+        // then download all selected band-4 ENCs plus overlapping band-3/5 ENCs
+        // and convert them once into a single MBTiles named after the catalog.
+        const CustomCatalogCreateBody = Type.Object({
+            name: Type.String({ minLength: 1, maxLength: 120 })
+        });
+        const CustomCatalogUpdateBody = Type.Object({
+            name: Type.Optional(Type.String({ minLength: 1, maxLength: 120 })),
+            selectedBand4ChartIds: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 32 })))
+        });
+        // Map data: all NOAA band-4 footprints as selectable bbox areas. This is
+        // the one endpoint that fetches the (large) NOAA enc.geojson; every other
+        // endpoint reads the in-memory index via peekFootprintIndex(). Registered
+        // BEFORE '/custom-catalogs/:id' so the literal path wins over the param.
+        router.get('/custom-catalogs/noaa-enc-footprints', (req, res) => {
+            const forceRefresh = req.query.refresh === '1' || req.query.refresh === 'true';
+            void (async () => {
+                try {
+                    const index = await getFootprintIndex({ forceRefresh });
+                    res.json({
+                        band4: band4MapEntries(index.all),
+                        fetchedAt: index.fetchedAt,
+                        stale: index.stale
+                    });
+                }
+                catch (error) {
+                    res.status(502).json({
+                        error: error instanceof Error ? error.message : 'Failed to load NOAA ENC footprints'
+                    });
+                }
+            })();
+        });
+        router.get('/custom-catalogs', (_req, res) => {
+            res.json(listCustomCatalogs().map((c) => decorateCatalog(c)));
+        });
+        router.post('/custom-catalogs', (req, res) => {
+            const body = parseBody(CustomCatalogCreateBody, req, res);
+            if (!body) {
+                return;
+            }
+            try {
+                const catalog = createCustomCatalog(body.name);
+                res.status(201).json(decorateCatalog(catalog));
+            }
+            catch (error) {
+                res.status(400).json({
+                    success: false,
+                    error: error instanceof Error ? error.message : 'Failed to create catalog'
+                });
+            }
+        });
+        router.get('/custom-catalogs/:id', (req, res) => {
+            const catalog = getCustomCatalog(req.params.id);
+            if (!catalog) {
+                res.status(404).json({ error: 'Custom catalog not found' });
+                return;
+            }
+            res.json(decorateCatalog(catalog));
+        });
+        router.put('/custom-catalogs/:id', (req, res) => {
+            const id = req.params.id;
+            const catalog = getCustomCatalog(id);
+            if (!catalog) {
+                res.status(404).json({ error: 'Custom catalog not found' });
+                return;
+            }
+            if (isCatalogBusy(id)) {
+                res
+                    .status(409)
+                    .json({ error: 'Catalog is downloading/converting; try again when it finishes' });
+                return;
+            }
+            const body = parseBody(CustomCatalogUpdateBody, req, res);
+            if (!body) {
+                return;
+            }
+            if (body.name !== undefined && body.name.trim() !== '') {
+                catalog.name = body.name.trim();
+            }
+            if (body.selectedBand4ChartIds !== undefined) {
+                catalog.selectedBand4ChartIds = Array.from(new Set(body.selectedBand4ChartIds));
+                // Recompute coverage from the cached footprint index when available so
+                // the UI shows an included-chart count immediately. The snapshot in
+                // `chartVersions` is only refreshed at download time.
+                const index = peekFootprintIndex();
+                if (index) {
+                    catalog.includedChartIds = computeInclusion(index.all, catalog.selectedBand4ChartIds).includedChartIds;
+                }
+                // Any selection change requires a rebuild of the single combined chart.
+                catalog.status = catalog.selectedBand4ChartIds.length === 0 ? 'empty' : 'out_of_date';
+            }
+            saveCustomCatalog(catalog);
+            res.json(decorateCatalog(catalog));
+        });
+        router.delete('/custom-catalogs/:id', (req, res) => {
+            const id = req.params.id;
+            if (isCatalogBusy(id)) {
+                res.status(409).json({ error: 'Catalog is downloading/converting; cannot delete now' });
+                return;
+            }
+            if (!deleteCustomCatalog(id)) {
+                res.status(404).json({ error: 'Custom catalog not found' });
+                return;
+            }
+            // The produced .mbtiles (if any) is intentionally left in the chart
+            // library — deleting the catalog definition is non-destructive. The user
+            // can remove the chart itself from the Manage Charts tab.
+            res.json({ success: true });
+        });
+        router.post('/custom-catalogs/:id/download-convert', (req, res) => {
+            const id = req.params.id;
+            const catalog = getCustomCatalog(id);
+            if (!catalog) {
+                res.status(404).json({ error: 'Custom catalog not found' });
+                return;
+            }
+            if (catalog.selectedBand4ChartIds.length === 0) {
+                res.status(400).json({ success: false, error: 'Select at least one coverage area first' });
+                return;
+            }
+            if (isCatalogBusy(id)) {
+                res.status(409).json({ success: false, error: 'Already downloading/converting' });
+                return;
+            }
+            const cm = getContainerManager();
+            if (!cm?.getRuntime()) {
+                res.status(503).json({
+                    success: false,
+                    error: 'signalk-container plugin not available. Install it from the App Store and restart Signal K.'
+                });
+                return;
+            }
+            const budgetMax = getCpuBudget().maxConcurrentConversions;
+            if (getConvertingCount() >= budgetMax) {
+                res.status(429).json({
+                    success: false,
+                    error: `Too many conversions running (max ${budgetMax}). Please wait for one to finish.`
+                });
+                return;
+            }
+            handleCustomCatalogDownloadConvert(catalog);
+            res.json({ success: true, message: 'Download and conversion started' });
+        });
+        router.get('/custom-catalogs/:id/status', (req, res) => {
+            const id = req.params.id;
+            const catalog = getCustomCatalog(id);
+            if (!catalog) {
+                res.status(404).json({ error: 'Custom catalog not found' });
+                return;
+            }
+            res.json({
+                ...decorateCatalog(catalog),
+                busy: isCatalogBusy(id),
+                progress: getCatalogProgress(id),
+                detail: getCatalogDetail(id)
+            });
+        });
+        router.post('/custom-catalogs/:id/cancel', (req, res) => {
+            const id = req.params.id;
+            if (!isValidCatalogId(id)) {
+                res.status(400).json({ success: false, error: 'Invalid catalog id' });
+                return;
+            }
+            if (!isCatalogBusy(id)) {
+                res.json({ success: true, message: 'Nothing running' });
+                return;
+            }
+            requestCatalogCancel(id);
+            setCatalogProgress(id, 'cancelling', 'Cancelling…');
+            // Reflect it in the structured detail immediately so the next /status
+            // poll shows "Cancelling…" rather than the last conversion frame.
+            setCatalogDetail(id, {
+                phase: 'cancelling',
+                sectionLabel: 'Cancelling…',
+                sectionPercent: -1
+            });
+            // Aborts the in-flight container job on signalk-container >= 1.16.0;
+            // downloads stop between charts; older containers stop at a band boundary.
+            res.json({ success: true, message: 'Cancellation requested' });
+        });
+        router.get('/custom-catalogs/:id/log', (req, res) => {
+            const id = req.params.id;
+            if (!isValidCatalogId(id)) {
+                res.status(400).json({ log: [], status: null });
+                return;
+            }
+            const tail = parseInt(req.query.tail) || 200;
+            const managerProgress = getCatalogProgress(id);
+            const s57 = getS57Progress(id);
+            // Manager progress carries the download phase; the S-57 converter carries
+            // the detailed per-band conversion log. Concatenate for the full picture.
+            const log = [...(managerProgress?.log ?? []), ...(s57?.log ?? [])];
+            res.json({
+                log: log.slice(-tail),
+                status: managerProgress?.status ?? s57?.status ?? null,
+                message: managerProgress?.message ?? s57?.message ?? ''
+            });
+        });
     };
     // Helper functions for catalog download routes (extracted to reduce nesting)
     function handleS57Download(res, app, url, chartNumber, catalogFile, zipfileDatetime, targetDir, chartPath, minzoom, maxzoom, chartTitle) {
@@ -2258,6 +2462,281 @@ const pluginConstructor = (app) => {
             message: 'GSHHG basemap conversion started'
         });
     }
+    // Augment a persisted catalog with derived, non-persisted fields the UI
+    // needs: the freshness-aware effective status, the live included-chart
+    // count, and any reasons it's out of date. Freshness is only computed when
+    // the NOAA footprint index is already in memory (the map endpoint loads it);
+    // otherwise we fall back to the stored status so this never blocks on the
+    // network.
+    function decorateCatalog(catalog) {
+        const chartPath = props.chartPath || defaultChartsPath;
+        const index = peekFootprintIndex();
+        if (!index) {
+            return {
+                ...catalog,
+                effectiveStatus: catalog.selectedBand4ChartIds.length === 0 ? 'empty' : catalog.status,
+                includedCount: catalog.includedChartIds.length,
+                updateReasons: [],
+                boxStates: {}
+            };
+        }
+        const mbtilesPresent = catalog.convertedChartPath !== null &&
+            fs.existsSync(path.join(chartPath, catalog.convertedChartPath));
+        const freshness = evaluateFreshness(catalog, index, (rel) => fs.existsSync(path.join(chartPath, rel)));
+        return {
+            ...catalog,
+            effectiveStatus: freshness.effectiveStatus,
+            includedCount: freshness.recomputed.includedChartIds.length,
+            updateReasons: freshness.reasons,
+            // Per-box freshness by NOAA edition. A box is green only when the set is
+            // cleanly converted and its MBTiles exists — a cancelled/failed build or
+            // a deleted output shows red, matching the catalog-level status.
+            boxStates: boxStatesForCatalog(catalog, index, mbtilesPresent)
+        };
+    }
+    // Async download-and-convert flow for a custom catalog. Fetches the current
+    // NOAA footprint index, resolves the band-3/4/5 ENC set, downloads every ZIP
+    // into one combined tree, converts it once via processS57Directory, and
+    // promotes the single MBTiles into the live chart library. The client polls
+    // /custom-catalogs/:id/status and /log for progress.
+    function handleCustomCatalogDownloadConvert(catalog) {
+        const id = catalog.id;
+        const chartPath = props.chartPath || defaultChartsPath;
+        setCatalogBusy(id, true);
+        clearCatalogProgress(id);
+        setCatalogProgress(id, 'preparing', 'Resolving coverage…');
+        setCatalogDetail(id, {
+            phase: 'preparing',
+            overallPercent: 0,
+            sectionLabel: 'Resolving coverage…',
+            sectionPercent: -1,
+            downloadedChartIds: []
+        });
+        const stagedSoFar = [];
+        // Abort controller for mid-job cancel: requestCatalogCancel(id) aborts it,
+        // which kills the in-flight container job on signalk-container >= 1.16.0.
+        const abortController = new AbortController();
+        registerCatalogAbort(id, abortController);
+        const stagingRoot = path.join(app.getDataDirPath(), `custom-catalog-${Date.now()}`);
+        const encDir = path.join(stagingRoot, 'enc');
+        const zipsDir = path.join(stagingRoot, 'zips');
+        void (async () => {
+            let quarantineDir = null;
+            let convertingFlagged = false;
+            try {
+                // Refresh the footprint index so we download the current editions.
+                const index = await getFootprintIndex();
+                const inclusion = computeInclusion(index.all, catalog.selectedBand4ChartIds);
+                if (inclusion.includedChartIds.length === 0) {
+                    throw new Error('No NOAA charts match the selected coverage areas');
+                }
+                appendCatalogLog(id, `Resolved ${inclusion.includedChartIds.length} ENC(s) from ` +
+                    `${catalog.selectedBand4ChartIds.length} selected area(s)`);
+                if (inclusion.missingSelected.length > 0) {
+                    appendCatalogLog(id, `Note: no longer published: ${inclusion.missingSelected.join(', ')}`);
+                }
+                // Per-box coverage so the map can fill each band-4 box by its own
+                // band-4 + nested-band-5 download fraction.
+                setCatalogDetail(id, {
+                    coverageByBox: coverageByBox(index.all, catalog.selectedBand4ChartIds)
+                });
+                // 1. Download + extract every ENC ZIP into one combined input tree.
+                const result = await downloadAndExtractEncs(inclusion.includedChartIds, encDir, zipsDir, {
+                    onProgress: (done, total, chartId) => {
+                        setCatalogProgress(id, 'downloading', `Downloading ${done}/${total}: ${chartId}`);
+                        setCatalogDetail(id, {
+                            phase: 'downloading',
+                            overallPercent: 0,
+                            sectionLabel: `Downloading ${done}/${total}`,
+                            sectionPercent: total > 0 ? Math.round((done / total) * 100) : -1
+                        });
+                    },
+                    // Flip the map area as each ENC lands, rather than all at once.
+                    onStaged: (chartId) => {
+                        stagedSoFar.push(chartId);
+                        setCatalogDetail(id, { downloadedChartIds: [...stagedSoFar] });
+                    },
+                    onLog: (line) => appendCatalogLog(id, line),
+                    isAborted: () => isCatalogCancelRequested(id)
+                });
+                // Cancel during download → stop before converting.
+                if (isCatalogCancelRequested(id)) {
+                    throw new Error('Cancelled by user');
+                }
+                if (result.staged.length === 0) {
+                    throw new Error('All ENC downloads failed — check network connectivity');
+                }
+                appendCatalogLog(id, `Downloaded ${result.staged.length}/${inclusion.includedChartIds.length} ENC(s)` +
+                    (result.failed.length > 0 ? `, ${result.failed.length} failed` : ''));
+                // A partial download yields an MBTiles that omits the failed cells, so
+                // it must not be marked up-to-date (see the status decision after
+                // conversion below).
+                const partialDownload = result.failed.length > 0;
+                if (partialDownload) {
+                    appendCatalogLog(id, `WARNING: ${result.failed.length} cell(s) failed to download: ` +
+                        `${result.failed.map((f) => f.chartId).join(', ')} — the built chart will be ` +
+                        `incomplete and stay flagged for rebuild.`);
+                }
+                // Persist the snapshot of what actually baked into the MBTiles — the
+                // STAGED charts and their editions, not the full requested set. On a
+                // partial download this records only the cells that made it in, so
+                // freshness (recomputed full vs stored staged) flags the missing cells
+                // and per-box edition state shows the affected boxes as needing a
+                // refresh. On a complete download staged == the full set, so nothing
+                // changes for the common case.
+                const staged = new Set(result.staged);
+                catalog.includedChartIds = inclusion.includedChartIds.filter((cid) => staged.has(cid));
+                catalog.chartVersions = Object.fromEntries(Object.entries(inclusion.chartVersions).filter(([cid]) => staged.has(cid)));
+                catalog.downloadedChartIds = result.staged;
+                catalog.lastDownloadedAt = new Date().toISOString();
+                catalog.status = 'downloaded';
+                saveCustomCatalog(catalog);
+                // 2. Convert the combined tree once → one MBTiles in the quarantine.
+                //    Flag converting so the global CPU-budget gate accounts for it.
+                setCatalogProgress(id, 'converting', 'Converting combined ENC set…');
+                setCatalogDetail(id, {
+                    phase: 'converting',
+                    overallPercent: 0,
+                    sectionLabel: 'Starting conversion…',
+                    sectionPercent: -1
+                });
+                // Re-check the conversion budget right before claiming a slot. The
+                // admission check at request time ran before the (long) download, so
+                // several catalogs could have passed it and now be ready to convert
+                // together. This synchronous check + setConvertingState pair is atomic
+                // in the event loop, so it can't over-subscribe maxConcurrentConversions.
+                const convertBudgetMax = getCpuBudget().maxConcurrentConversions;
+                if (getConvertingCount() >= convertBudgetMax) {
+                    throw new Error(`Too many conversions running (max ${convertBudgetMax}). Please retry when one finishes.`);
+                }
+                setConvertingState(id, true);
+                convertingFlagged = true;
+                quarantineDir = makeQuarantineDir(app.getDataDirPath(), id);
+                const conv = await processS57Directory(encDir, quarantineDir, id, (status, message) => setCatalogProgress(id, status, message), {
+                    displayName: catalog.name,
+                    displayDescription: `Custom catalog: ${catalog.name}`,
+                    isAborted: () => isCatalogCancelRequested(id),
+                    // Overall (convert-only) bar treats the per-band tippecanoe passes
+                    // plus the final combine as equal slices, so it rises monotonically
+                    // through the whole conversion. The combine now reports its own %
+                    // (derived from tile-join's tile-coordinate output), so its section
+                    // bar is determinate too.
+                    onProgress: (p) => {
+                        // Once cancel is requested, the in-flight job is being killed but
+                        // may emit a few more progress lines before it dies. Don't let
+                        // those overwrite the "Cancelling…" state — otherwise the UI
+                        // flips back to "running" until the job actually unwinds.
+                        if (isCatalogCancelRequested(id)) {
+                            setCatalogDetail(id, {
+                                phase: 'cancelling',
+                                sectionLabel: 'Cancelling…',
+                                sectionPercent: -1
+                            });
+                            return;
+                        }
+                        const hasJoin = p.bucketCount >= 2;
+                        const denom = p.bucketCount + (hasJoin ? 1 : 0);
+                        const pct = p.bucketPercent >= 0 ? p.bucketPercent : 0;
+                        let overall;
+                        let sectionLabel;
+                        let sectionPercent;
+                        if (p.stage === 'join') {
+                            // Clamp: with a single bucket (no dedicated join slot) the
+                            // join collapses to a file move and emits 100%, which would
+                            // otherwise compute >100 here.
+                            overall =
+                                denom > 0
+                                    ? Math.min(100, Math.round(((p.bucketCount + pct / 100) / denom) * 100))
+                                    : 99;
+                            sectionLabel = `Combining ${p.bucketCount} tile sets`;
+                            sectionPercent = p.bucketPercent;
+                        }
+                        else if (p.stage === 'export') {
+                            overall = denom > 0 ? Math.round(((p.bucketIndex - 1) / denom) * 100) : 0;
+                            sectionLabel = `${p.bucketLabel} — reading charts (${p.bucketIndex} of ${p.bucketCount})`;
+                            sectionPercent = -1;
+                        }
+                        else {
+                            overall =
+                                denom > 0 ? Math.round(((p.bucketIndex - 1 + pct / 100) / denom) * 100) : 0;
+                            sectionLabel = `${p.bucketLabel} — generating tiles (${p.bucketIndex} of ${p.bucketCount})`;
+                            sectionPercent = Math.round(pct);
+                        }
+                        setCatalogDetail(id, {
+                            phase: p.stage === 'join' ? 'joining' : 'converting',
+                            overallPercent: overall,
+                            sectionLabel,
+                            sectionPercent
+                        });
+                    },
+                    signal: abortController.signal
+                }, stagingRoot);
+                // 3. Promote the single output into the live chart library (root).
+                await promoteQuarantine(quarantineDir, [conv.mbtilesFile], chartPath);
+                setChartEnabled(conv.mbtilesFile, true);
+                catalog.convertedChartPath = conv.mbtilesFile;
+                catalog.lastConvertedAt = new Date().toISOString();
+                // Only a complete bundle counts as up-to-date. A partial download
+                // produced a chart that omits some cells, so leave it out_of_date and
+                // the UI flags it for a rebuild (which retries the failed cells).
+                catalog.status = partialDownload ? 'out_of_date' : 'converted';
+                saveCustomCatalog(catalog);
+                await refreshChartProviders();
+                const chartId = conv.mbtilesFile.replace(/\.mbtiles$/, '');
+                if (chartProviders[chartId]) {
+                    emitChartDelta(chartId, sanitizeProvider(chartProviders[chartId], 2));
+                }
+                setCatalogProgress(id, 'completed', `Created ${conv.mbtilesFile}`);
+                setCatalogDetail(id, {
+                    phase: 'completed',
+                    overallPercent: 100,
+                    sectionLabel: `Created ${conv.mbtilesFile}`,
+                    sectionPercent: 100
+                });
+                appendCatalogLog(id, `Done: ${conv.mbtilesFile}`);
+                // Let the completed state linger briefly, then clear so the UI settles
+                // onto the persisted 'converted' status.
+                setTimeout(() => clearCatalogProgress(id), 8000);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                if (isCatalogCancelRequested(id)) {
+                    appendCatalogLog(id, 'Cancelled by user.');
+                    setCatalogProgress(id, 'cancelled', 'Cancelled');
+                    setCatalogDetail(id, {
+                        phase: 'cancelled',
+                        sectionLabel: 'Cancelled',
+                        sectionPercent: -1
+                    });
+                    // Drop the cancelled state after a short linger.
+                    setTimeout(() => clearCatalogProgress(id), 6000);
+                }
+                else {
+                    app.error(`Custom catalog ${id} download/convert failed: ${msg}`);
+                    setCatalogFailed(id, msg);
+                    setCatalogDetail(id, { phase: 'failed', sectionLabel: msg, sectionPercent: -1 });
+                }
+                // Mark out_of_date (unless it had a prior good conversion) so the UI
+                // shows the coverage needs a (re)build.
+                const latest = getCustomCatalog(id);
+                if (latest && latest.selectedBand4ChartIds.length > 0 && latest.status !== 'converted') {
+                    latest.status = 'out_of_date';
+                    saveCustomCatalog(latest);
+                }
+            }
+            finally {
+                if (convertingFlagged) {
+                    setConvertingState(id, false);
+                }
+                if (quarantineDir !== null) {
+                    cleanupQuarantineDir(quarantineDir);
+                }
+                cleanupDir(stagingRoot);
+                clearCatalogCancel(id);
+                setCatalogBusy(id, false);
+            }
+        })();
+    }
     const registerAsProvider = () => {
         app.debug('** Registering as Resource Provider for `charts` **');
         try {