@walkthru-earth/objex 0.1.0

package/dist/stores/tabs.svelte.js

@@ -0,0 +1,110 @@
+import { tabResources } from './tab-resources.svelte.js';
+/** Maximum number of viewer instances kept alive (mounted but hidden). */
+const MAX_ALIVE = 5;
+function releaseDuckDbMemory() {
+    import('../query/index.js')
+        .then(({ getQueryEngine }) => getQueryEngine().then((engine) => engine.releaseMemory()))
+        .catch(() => { });
+}
+function createTabsStore() {
+    let tabs = $state([]);
+    let activeTabId = $state(null);
+    // LRU order: most recently activated tab IDs first.
+    // Used to decide which tabs stay alive in the DOM.
+    let recentOrder = $state([]);
+    function touchRecent(id) {
+        recentOrder = [id, ...recentOrder.filter((r) => r !== id)];
+        // Dispose resources for tabs that fell out of the alive window.
+        // This fires asynchronously to avoid blocking the tab switch.
+        const evicted = recentOrder.slice(MAX_ALIVE);
+        for (const evictedId of evicted) {
+            if (tabResources.has(evictedId)) {
+                tabResources.dispose(evictedId);
+            }
+        }
+    }
+    function pruneRecent() {
+        // Remove IDs that no longer exist in tabs
+        const ids = new Set(tabs.map((t) => t.id));
+        recentOrder = recentOrder.filter((r) => ids.has(r));
+    }
+    return {
+        get items() {
+            return tabs;
+        },
+        get activeTabId() {
+            return activeTabId;
+        },
+        get active() {
+            if (!activeTabId)
+                return undefined;
+            return tabs.find((t) => t.id === activeTabId);
+        },
+        /**
+         * Tabs that should be kept alive in the DOM (mounted but hidden if inactive).
+         * Returns up to MAX_ALIVE tabs in MRU order. The active tab is always included.
+         */
+        get aliveTabs() {
+            const aliveIds = recentOrder.slice(0, MAX_ALIVE);
+            // Ensure active tab is always included
+            if (activeTabId && !aliveIds.includes(activeTabId)) {
+                aliveIds.pop();
+                aliveIds.unshift(activeTabId);
+            }
+            const idSet = new Set(aliveIds);
+            return tabs.filter((t) => idSet.has(t.id));
+        },
+        open(tab) {
+            // If a tab with the same id is already open, just activate it
+            const existing = tabs.find((t) => t.id === tab.id);
+            if (existing) {
+                activeTabId = tab.id;
+                touchRecent(tab.id);
+                return;
+            }
+            tabs = [...tabs, tab];
+            activeTabId = tab.id;
+            touchRecent(tab.id);
+        },
+        async close(id) {
+            const index = tabs.findIndex((t) => t.id === id);
+            if (index === -1)
+                return;
+            // Dispose viewer resources (maps, abort controllers, cached data)
+            await tabResources.dispose(id);
+            tabs = tabs.filter((t) => t.id !== id);
+            pruneRecent();
+            // If we closed the active tab, activate an adjacent one
+            if (activeTabId === id) {
+                if (tabs.length === 0) {
+                    activeTabId = null;
+                }
+                else {
+                    // Prefer the most recently used tab, or the tab at the same index
+                    const nextId = recentOrder[0] ?? tabs[Math.min(index, tabs.length - 1)]?.id;
+                    activeTabId = nextId ?? null;
+                }
+            }
+            releaseDuckDbMemory();
+        },
+        async closeOthers(id) {
+            // Dispose resources for all tabs except the kept one
+            await tabResources.disposeAllExcept(id);
+            tabs = tabs.filter((t) => t.id === id);
+            activeTabId = id;
+            recentOrder = [id];
+            releaseDuckDbMemory();
+        },
+        setActive(id) {
+            if (tabs.find((t) => t.id === id)) {
+                activeTabId = id;
+                touchRecent(id);
+            }
+        },
+        update(id, partial) {
+            tabs = tabs.map((t) => (t.id === id ? { ...t, ...partial } : t));
+        }
+    };
+}
+export const tabStore = createTabsStore();
+export { tabStore as tabs };

package/dist/types/notebookjs.d.ts

@@ -0,0 +1,14 @@
+declare module 'notebookjs' {
+	interface Notebook {
+		render(): HTMLElement;
+	}
+	const nb: {
+		prefix: string;
+		markdown: (md: string) => string;
+		ansi: (text: string) => string;
+		highlighter: (code: string, lang: string) => string;
+		sanitizer: (html: string) => string;
+		parse(json: unknown): Notebook;
+	};
+	export default nb;
+}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export interface FileEntry {
+    name: string;
+    path: string;
+    is_dir: boolean;
+    size: number;
+    modified: number;
+    extension: string;
+}
+export interface Connection {
+    id: string;
+    name: string;
+    provider: 's3' | 'gcs' | 'r2' | 'minio' | 'azure' | 'storj';
+    endpoint: string;
+    bucket: string;
+    region: string;
+    anonymous: boolean;
+    authMethod?: 'sigv4' | 'sas-token';
+    rootPrefix?: string;
+}
+export interface ConnectionConfig {
+    name: string;
+    provider: 's3' | 'gcs' | 'r2' | 'minio' | 'azure' | 'storj';
+    endpoint: string;
+    bucket: string;
+    region: string;
+    access_key?: string;
+    secret_key?: string;
+    sas_token?: string;
+    anonymous: boolean;
+    authMethod?: 'sigv4' | 'sas-token';
+    rootPrefix?: string;
+}
+export interface Tab {
+    id: string;
+    name: string;
+    path: string;
+    source: 'remote' | 'url';
+    connectionId?: string;
+    extension: string;
+    size?: number;
+}
+export interface WriteResult {
+    key: string;
+    size: number;
+    e_tag?: string;
+}
+export type Theme = 'light' | 'dark' | 'system';

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/CLAUDE.md

@@ -0,0 +1,54 @@
+# utils/
+
+Pure utility modules. No Svelte dependency except `url-state.ts` and `analytics.ts`.
+
+```mermaid
+graph TD
+    subgraph "Published (npm)"
+        WKB[wkb.ts<br/>parseWKB, findGeoColumn]
+        GA[geoarrow.ts<br/>buildGeoArrowTables]
+        SU[storage-url.ts<br/>parseStorageUrl]
+        PM[parquet-metadata.ts<br/>readParquetMetadata]
+        FMT[format.ts<br/>formatFileSize, formatDate]
+        HEX[hex.ts<br/>generateHexDump]
+        CT[column-types.ts<br/>classifyType]
+    end
+    subgraph "Internal only"
+        DECK[deck.ts<br/>createDeckOverlay, createGeoArrowOverlay]
+        URL[url.ts<br/>buildHttpsUrl, buildDuckDbUrl]
+        US[url-state.ts<br/>syncUrlParam — uses $app]
+        ARC[archive.ts<br/>streamZip/Tar]
+        PMT[pmtiles.ts<br/>loadPmtiles]
+        SHIKI[shiki.ts<br/>highlightCode]
+        ZARR[zarr.ts<br/>fetchConsolidated]
+    end
+    WKB --> GA
+    PM --> GA
+    GA --> DECK
+```
+
+| File | Key Exports | Used by |
+|------|-------------|---------|
+| `wkb.ts` | `parseWKB()`, `toBinary()`, `findGeoColumn()`, `findGeoColumnFromRows()` | TableViewer, GeoParquetMapViewer, lib/index.ts |
+| `geoarrow.ts` | `buildGeoArrowTables()`, `normalizeGeomType()` | TableViewer, GeoParquetMapViewer, lib/index.ts |
+| `storage-url.ts` | `parseStorageUrl()`, `looksLikeUrl()`, `Defaults` | ConnectionDialog, Sidebar, lib/index.ts |
+| `parquet-metadata.ts` | `readParquetMetadata()`, `extractEpsgFromGeoMeta()`, `extractBounds()` | TableViewer, lib/index.ts |
+| `format.ts` | `formatFileSize()`, `formatDate()`, `getFileExtension()` | StatusBar, FileRow, ArchiveViewer, RawViewer, lib/index.ts |
+| `hex.ts` | `generateHexDump()` | RawViewer, lib/index.ts |
+| `column-types.ts` | `classifyType()`, `typeColor()`, `typeLabel()` | TableGrid, lib/index.ts |
+| `deck.ts` | `createDeckOverlay()`, `createGeoArrowOverlay()`, `createGeoArrowLayers()` | FlatGeobufViewer, GeoParquetMapViewer |
+| `url.ts` | `buildHttpsUrl()`, `buildDuckDbUrl()`, `canStreamDirectly()` | TabBar, FileTreeSidebar, CogViewer, TableViewer, FlatGeobufViewer, ArchiveViewer, MediaViewer, CopcViewer, PdfViewer, ZarrMapViewer, StacMapViewer, ZarrViewer, CodeViewer, ImageViewer, PmtilesViewer, TableToolbar |
+| `archive.ts` | `streamZipEntriesFromUrl()`, `streamTarEntriesFromUrl()`, `listContents()` | ArchiveViewer |
+| `pmtiles.ts` | `loadPmtiles()`, `buildPmtilesLayers()` | PmtilesMapView, PmtilesArchiveView, PmtilesViewer |
+| `shiki.ts` | `highlightCode()`, `extensionToShikiLang()` | PmtilesArchiveView, NotebookViewer, CodeViewer |
+| `zarr.ts` | `fetchConsolidated()`, `probeWithZarrita()` | ZarrViewer |
+| `url-state.ts` | `syncUrlParam()`, `updateUrlView()` | Sidebar, FileTreeSidebar, TableViewer, ZarrViewer, CodeViewer, PmtilesViewer, +page.svelte |
+| `analytics.ts` | `initAnalytics()`, `capturePageview()` | +layout.svelte |
+| `export.ts` | `exportToCsv()`, `exportToJson()` | TableStatusBar |
+| `pdf.ts` | `loadPdfDocument()` | PdfViewer |
+| `model3d.ts` | `createModelScene()`, `loadModel()` | ModelViewer |
+| `markdown.ts` | `renderMarkdown()`, `detectRTL()` | MarkdownViewer |
+| `map-selection.ts` | `setupSelectionLayer()`, `updateSelection()` | PmtilesMapView, MapViewer |
+| `host-detection.ts` | `detectHostBucket()` | stores/connections, Sidebar |
+| `markdown-sql.ts` | `parseMarkdownDocument()`, `interpolateTemplates()` | MarkdownViewer |
+| `evidence-context.ts` | `EvidenceContext` | MarkdownViewer |

package/dist/utils/analytics.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PostHog analytics — cookieless by default (memory persistence).
+ *
+ * Env vars (PUBLIC_ prefix = available client-side in SvelteKit):
+ *   PUBLIC_POSTHOG_KEY  — project API key
+ *   PUBLIC_POSTHOG_HOST — ingestion endpoint (default: EU cloud)
+ */
+export declare function initAnalytics(): void;
+export declare function capturePageview(url: string): void;
+export declare function capturePageleave(): void;

package/dist/utils/analytics.js

@@ -0,0 +1,38 @@
+/**
+ * PostHog analytics — cookieless by default (memory persistence).
+ *
+ * Env vars (PUBLIC_ prefix = available client-side in SvelteKit):
+ *   PUBLIC_POSTHOG_KEY  — project API key
+ *   PUBLIC_POSTHOG_HOST — ingestion endpoint (default: EU cloud)
+ */
+import posthog from 'posthog-js';
+import { browser } from '$app/environment';
+import { env } from '$env/dynamic/public';
+let initialized = false;
+export function initAnalytics() {
+    if (!browser || initialized)
+        return;
+    const key = env.PUBLIC_POSTHOG_KEY;
+    if (!key)
+        return; // silently skip if no key configured
+    const host = env.PUBLIC_POSTHOG_HOST || 'https://eu.i.posthog.com';
+    posthog.init(key, {
+        api_host: host,
+        person_profiles: 'identified_only',
+        capture_pageview: false, // we track manually via afterNavigate
+        capture_pageleave: true,
+        persistence: 'memory', // cookieless — no consent banner needed
+        autocapture: true
+    });
+    initialized = true;
+}
+export function capturePageview(url) {
+    if (!initialized)
+        return;
+    posthog.capture('$pageview', { $current_url: url });
+}
+export function capturePageleave() {
+    if (!initialized)
+        return;
+    posthog.capture('$pageleave');
+}

package/dist/utils/archive.d.ts

@@ -0,0 +1,70 @@
+import { type Entry } from '@zip.js/zip.js';
+export interface ArchiveEntry {
+    filename: string;
+    directory: boolean;
+    compressedSize: number;
+    uncompressedSize: number;
+    lastModified: Date;
+    /** TAR only: byte offset of the file data within the archive */
+    dataOffset?: number;
+}
+export type ArchiveFormat = 'zip' | 'tar' | 'tar.gz' | 'unsupported';
+export declare function detectArchiveFormat(filename: string): ArchiveFormat;
+/**
+ * Stream ZIP entries from a URL using HTTP range requests.
+ * Uses getEntriesGenerator() so the UI can render progressively.
+ */
+export declare function streamZipEntriesFromUrl(url: string, signal?: AbortSignal): AsyncGenerator<{
+    zipEntries: Entry[];
+    archiveEntries: ArchiveEntry[];
+}>;
+/**
+ * Read ZIP entries from an in-memory buffer (non-streaming, fast).
+ */
+export declare function readZipEntriesFromBuffer(data: Uint8Array): Promise<{
+    entries: Entry[];
+    entryList: ArchiveEntry[];
+}>;
+/**
+ * Stream TAR entries from a URL using batched HTTP range requests.
+ * Yields a batch of entries after each chunk is processed,
+ * so the UI can render progressively while scanning continues.
+ */
+export declare function streamTarEntriesFromUrl(url: string, signal?: AbortSignal): AsyncGenerator<ArchiveEntry[]>;
+/**
+ * Read TAR entries from an in-memory buffer (non-streaming, fast).
+ */
+export declare function readTarEntriesFromBuffer(data: Uint8Array): {
+    entryList: ArchiveEntry[];
+};
+/**
+ * Decompress gzip data using the browser's DecompressionStream.
+ * Requires full download — gzip does not support random access.
+ */
+export declare function decompressGzip(data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Stream tar.gz entries by fetching the URL, piping through DecompressionStream,
+ * and parsing tar headers progressively as decompressed chunks arrive.
+ *
+ * Gzip doesn't support random access, so we must download sequentially,
+ * but entries appear immediately — no waiting for the full download.
+ *
+ * Yields { entries, chunk } so the caller can optionally accumulate raw
+ * decompressed data for later file extraction.
+ */
+export declare function streamTarGzEntriesFromUrl(url: string, signal?: AbortSignal): AsyncGenerator<{
+    entries: ArchiveEntry[];
+    chunk: Uint8Array;
+}>;
+/**
+ * List directory contents at a given prefix.
+ * Returns immediate children: directories (as path strings) and files.
+ */
+export declare function listContents(entryList: ArchiveEntry[], prefix: string): {
+    directories: string[];
+    files: ArchiveEntry[];
+};
+export declare function clampPrefix(prefix: string, maxDepth?: number): string;
+export declare function downloadZipEntry(entry: Entry): Promise<void>;
+export declare function downloadTarEntryFromUrl(url: string, entry: ArchiveEntry): Promise<void>;
+export declare function downloadTarEntryFromBuffer(data: Uint8Array, entry: ArchiveEntry): void;

package/dist/utils/archive.js

@@ -0,0 +1,333 @@
+import { BlobReader, configure, HttpReader, ZipReader } from '@zip.js/zip.js';
+// Enable web workers for non-blocking ZIP parsing
+configure({ useWebWorkers: true });
+// ── Format Detection ───────────────────────────────────────────────────
+export function detectArchiveFormat(filename) {
+    const lower = filename.toLowerCase();
+    if (lower.endsWith('.zip'))
+        return 'zip';
+    if (lower.endsWith('.tar.gz') || lower.endsWith('.tgz'))
+        return 'tar.gz';
+    if (lower.endsWith('.tar'))
+        return 'tar';
+    if (lower.endsWith('.gz'))
+        return 'tar.gz';
+    return 'unsupported';
+}
+// ── ZIP (streaming) ────────────────────────────────────────────────────
+const ZIP_BATCH_SIZE = 500;
+/**
+ * Stream ZIP entries from a URL using HTTP range requests.
+ * Uses getEntriesGenerator() so the UI can render progressively.
+ */
+export async function* streamZipEntriesFromUrl(url, signal) {
+    const httpReader = new HttpReader(url, { forceRangeRequests: true });
+    const reader = new ZipReader(httpReader);
+    let zBatch = [];
+    let aBatch = [];
+    try {
+        for await (const entry of reader.getEntriesGenerator()) {
+            if (signal?.aborted)
+                return;
+            zBatch.push(entry);
+            aBatch.push({
+                filename: entry.filename,
+                directory: entry.directory,
+                compressedSize: entry.compressedSize,
+                uncompressedSize: entry.uncompressedSize,
+                lastModified: entry.lastModDate
+            });
+            if (zBatch.length >= ZIP_BATCH_SIZE) {
+                yield { zipEntries: zBatch, archiveEntries: aBatch };
+                zBatch = [];
+                aBatch = [];
+            }
+        }
+        if (zBatch.length > 0) {
+            yield { zipEntries: zBatch, archiveEntries: aBatch };
+        }
+    }
+    finally {
+        await reader.close();
+    }
+}
+/**
+ * Read ZIP entries from an in-memory buffer (non-streaming, fast).
+ */
+export async function readZipEntriesFromBuffer(data) {
+    const blob = new Blob([data]);
+    const reader = new ZipReader(new BlobReader(blob));
+    const entries = await reader.getEntries();
+    return {
+        entries,
+        entryList: entries.map((e) => ({
+            filename: e.filename,
+            directory: e.directory,
+            compressedSize: e.compressedSize,
+            uncompressedSize: e.uncompressedSize,
+            lastModified: e.lastModDate
+        }))
+    };
+}
+// ── TAR (streaming) ────────────────────────────────────────────────────
+const TAR_HEADER_SIZE = 512;
+const TAR_CHUNK_SIZE = 256 * 1024; // 256 KB per range request
+/**
+ * Parse a single 512-byte TAR header.
+ * Returns null for end-of-archive (all-zero block).
+ */
+function parseTarHeader(header) {
+    if (header.every((b) => b === 0))
+        return null;
+    const dec = new TextDecoder('ascii');
+    const name = dec.decode(header.slice(0, 100)).replace(/\0+$/, '');
+    const prefix = dec.decode(header.slice(345, 500)).replace(/\0+$/, '');
+    let fullName = prefix ? `${prefix}/${name}` : name;
+    // Normalize: strip leading ./ (common in tarballs created with `tar -czf`)
+    if (fullName.startsWith('./'))
+        fullName = fullName.slice(2);
+    const sizeStr = dec.decode(header.slice(124, 136)).replace(/\0+$/, '').trim();
+    const size = parseInt(sizeStr, 8) || 0;
+    const mtimeStr = dec.decode(header.slice(136, 148)).replace(/\0+$/, '').trim();
+    const mtime = new Date((parseInt(mtimeStr, 8) || 0) * 1000);
+    const typeFlag = String.fromCharCode(header[156]);
+    const isDir = typeFlag === '5' || fullName.endsWith('/');
+    return {
+        filename: fullName,
+        directory: isDir,
+        compressedSize: size,
+        uncompressedSize: size,
+        lastModified: mtime,
+        dataOffset: 0
+    };
+}
+/** Returns true for bare root entries (e.g. ".", "") that should be skipped. */
+function isRootEntry(entry) {
+    const f = entry.filename.replace(/\/+$/, '');
+    return f === '' || f === '.';
+}
+/**
+ * Stream TAR entries from a URL using batched HTTP range requests.
+ * Yields a batch of entries after each chunk is processed,
+ * so the UI can render progressively while scanning continues.
+ */
+export async function* streamTarEntriesFromUrl(url, signal) {
+    const head = await fetch(url, { method: 'HEAD', signal });
+    const totalSize = Number(head.headers.get('content-length'));
+    if (!totalSize || totalSize <= 0)
+        throw new Error('Cannot determine TAR file size');
+    let offset = 0;
+    while (offset < totalSize) {
+        if (signal?.aborted)
+            return;
+        const end = Math.min(offset + TAR_CHUNK_SIZE - 1, totalSize - 1);
+        const res = await fetch(url, {
+            headers: { Range: `bytes=${offset}-${end}` },
+            signal
+        });
+        const chunk = new Uint8Array(await res.arrayBuffer());
+        const batch = [];
+        let localOffset = 0;
+        while (localOffset + TAR_HEADER_SIZE <= chunk.length) {
+            const header = chunk.slice(localOffset, localOffset + TAR_HEADER_SIZE);
+            const entry = parseTarHeader(header);
+            if (!entry) {
+                if (batch.length > 0)
+                    yield batch;
+                return;
+            }
+            const dataBlocks = Math.ceil(entry.uncompressedSize / TAR_HEADER_SIZE);
+            const entryTotalSize = TAR_HEADER_SIZE + dataBlocks * TAR_HEADER_SIZE;
+            if (!isRootEntry(entry)) {
+                entry.dataOffset = offset + localOffset + TAR_HEADER_SIZE;
+                batch.push(entry);
+            }
+            if (localOffset + entryTotalSize > chunk.length) {
+                offset += localOffset + entryTotalSize;
+                localOffset = chunk.length;
+            }
+            else {
+                localOffset += entryTotalSize;
+            }
+        }
+        if (batch.length > 0)
+            yield batch;
+        if (localOffset <= chunk.length) {
+            offset += localOffset || TAR_CHUNK_SIZE;
+        }
+    }
+}
+/**
+ * Read TAR entries from an in-memory buffer (non-streaming, fast).
+ */
+export function readTarEntriesFromBuffer(data) {
+    const entries = [];
+    let offset = 0;
+    while (offset + TAR_HEADER_SIZE <= data.length) {
+        const header = data.slice(offset, offset + TAR_HEADER_SIZE);
+        const entry = parseTarHeader(header);
+        if (!entry)
+            break;
+        const dataBlocks = Math.ceil(entry.uncompressedSize / TAR_HEADER_SIZE);
+        if (!isRootEntry(entry)) {
+            entry.dataOffset = offset + TAR_HEADER_SIZE;
+            entries.push(entry);
+        }
+        offset += TAR_HEADER_SIZE + dataBlocks * TAR_HEADER_SIZE;
+    }
+    return { entryList: entries };
+}
+// ── TAR.GZ ─────────────────────────────────────────────────────────────
+/**
+ * Decompress gzip data using the browser's DecompressionStream.
+ * Requires full download — gzip does not support random access.
+ */
+export async function decompressGzip(data) {
+    const ds = new DecompressionStream('gzip');
+    const decompressedStream = new Blob([data]).stream().pipeThrough(ds);
+    const buf = await new Response(decompressedStream).arrayBuffer();
+    return new Uint8Array(buf);
+}
+const TAR_GZ_BATCH_SIZE = 200;
+/**
+ * Stream tar.gz entries by fetching the URL, piping through DecompressionStream,
+ * and parsing tar headers progressively as decompressed chunks arrive.
+ *
+ * Gzip doesn't support random access, so we must download sequentially,
+ * but entries appear immediately — no waiting for the full download.
+ *
+ * Yields { entries, chunk } so the caller can optionally accumulate raw
+ * decompressed data for later file extraction.
+ */
+export async function* streamTarGzEntriesFromUrl(url, signal) {
+    const response = await fetch(url, { signal });
+    if (!response.body)
+        throw new Error('No response body');
+    const ds = new DecompressionStream('gzip');
+    const decompressed = response.body.pipeThrough(ds);
+    const reader = decompressed.getReader();
+    let buffer = new Uint8Array(0);
+    let tarOffset = 0; // absolute byte offset in decompressed tar stream
+    while (true) {
+        if (signal?.aborted)
+            return;
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        // Append new decompressed chunk to working buffer
+        const prev = buffer;
+        buffer = new Uint8Array(prev.length + value.length);
+        buffer.set(prev);
+        buffer.set(value, prev.length);
+        const batch = [];
+        let consumed = 0;
+        // Parse as many complete tar entries as possible
+        while (buffer.length - consumed >= TAR_HEADER_SIZE) {
+            const header = buffer.slice(consumed, consumed + TAR_HEADER_SIZE);
+            const entry = parseTarHeader(header);
+            if (!entry) {
+                // End-of-archive marker (two 512-byte zero blocks)
+                if (batch.length > 0) {
+                    yield { entries: batch, chunk: buffer.slice(0, consumed) };
+                }
+                return;
+            }
+            const dataBlocks = Math.ceil(entry.uncompressedSize / TAR_HEADER_SIZE);
+            const entryTotalSize = TAR_HEADER_SIZE + dataBlocks * TAR_HEADER_SIZE;
+            if (buffer.length - consumed < entryTotalSize) {
+                // Not enough data yet for header + file data, wait for more
+                break;
+            }
+            if (!isRootEntry(entry)) {
+                entry.dataOffset = tarOffset + consumed + TAR_HEADER_SIZE;
+                batch.push(entry);
+            }
+            consumed += entryTotalSize;
+            if (batch.length >= TAR_GZ_BATCH_SIZE) {
+                yield { entries: batch.splice(0), chunk: buffer.slice(0, consumed) };
+            }
+        }
+        // Yield any remaining entries in this chunk
+        if (batch.length > 0) {
+            yield { entries: batch, chunk: buffer.slice(0, consumed) };
+        }
+        tarOffset += consumed;
+        buffer = buffer.slice(consumed);
+    }
+}
+// ── Listing (universal) ────────────────────────────────────────────────
+const MAX_BROWSE_DEPTH = 10;
+/**
+ * List directory contents at a given prefix.
+ * Returns immediate children: directories (as path strings) and files.
+ */
+export function listContents(entryList, prefix) {
+    const canonical = prefix.length > 0 && !prefix.endsWith('/') ? `${prefix}/` : prefix;
+    const files = [];
+    const directories = new Set();
+    for (const entry of entryList) {
+        if (!entry.filename.startsWith(canonical))
+            continue;
+        const remainder = entry.filename.slice(canonical.length);
+        if (remainder.length === 0)
+            continue;
+        const slashIndex = remainder.indexOf('/');
+        if (slashIndex === -1) {
+            if (!entry.directory)
+                files.push(entry);
+        }
+        else {
+            const dirName = remainder.slice(0, slashIndex);
+            const dirPath = `${canonical}${dirName}`;
+            if (dirName.length > 0)
+                directories.add(dirPath);
+        }
+    }
+    return {
+        directories: [...directories].sort(),
+        files: files.sort((a, b) => a.filename.localeCompare(b.filename))
+    };
+}
+export function clampPrefix(prefix, maxDepth = MAX_BROWSE_DEPTH) {
+    const parts = prefix.split('/').filter(Boolean);
+    if (parts.length <= maxDepth)
+        return prefix;
+    return parts.slice(0, maxDepth).join('/');
+}
+// ── Download ───────────────────────────────────────────────────────────
+export async function downloadZipEntry(entry) {
+    if (entry.directory || !entry.getData)
+        return;
+    const { BlobWriter, getMimeType } = await import('@zip.js/zip.js');
+    const mimeType = getMimeType(entry.filename);
+    const blob = await entry.getData(new BlobWriter(mimeType));
+    triggerBlobDownload(blob, entry.filename.split('/').pop() || 'file');
+}
+export async function downloadTarEntryFromUrl(url, entry) {
+    if (entry.directory || entry.dataOffset == null)
+        return;
+    const res = await fetch(url, {
+        headers: {
+            Range: `bytes=${entry.dataOffset}-${entry.dataOffset + entry.uncompressedSize - 1}`
+        }
+    });
+    const blob = await res.blob();
+    triggerBlobDownload(blob, entry.filename.split('/').pop() || 'file');
+}
+export function downloadTarEntryFromBuffer(data, entry) {
+    if (entry.directory || entry.dataOffset == null)
+        return;
+    const slice = data.slice(entry.dataOffset, entry.dataOffset + entry.uncompressedSize);
+    const blob = new Blob([slice]);
+    triggerBlobDownload(blob, entry.filename.split('/').pop() || 'file');
+}
+function triggerBlobDownload(blob, filename) {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}