@expofp/offline 0.0.0-experimental.2632d13

package/README.md

@@ -0,0 +1,22 @@
+# @expofp/offline
+
+CLI (`expofp-offline`) that creates self-contained ZIP archives of floor plans — openable in any browser without internet connectivity.
+
+## Usage
+
+```bash
+npx @expofp/offline@<tag-or-version> <manifest-url> [options]
+```
+
+| Option                   | Description                                      | Default                                |
+| ------------------------ | ------------------------------------------------ | -------------------------------------- |
+| `-o`, `--output`         | Output file path                                 | `offline.zip`                          |
+| `--debug-no-offline-map` | Disable automatic MapLibre basemap detection.    |                                        |
+| `--debug-map-source`     | Global PMTiles source URL/path for offline maps. | Latest available Protomaps daily build |
+| `-h`, `--help`           | Show help message                                |                                        |
+
+## Example
+
+```bash
+npx @expofp/offline https://demo.expofp.com/manifest.json -o offline.zip
+```

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { parseArgs } from 'node:util';
+import { resolveFloorplanDir } from './lib/resolve-floorplan-dir.js';
+import { saveOfflineZip } from './lib/save-offline-zip.js';
+const HELP = `
+Usage: expofp-offline <manifest-url> [options]
+
+Create an offline ZIP archive of an ExpoFP floor plan.
+
+Arguments:
+  manifest-url   URL to the floor plan manifest JSON
+
+Options:
+  -o, --output   Output file path (default: offline.zip)
+      --debug-no-offline-map
+                Disable automatic offline MapLibre basemap detection
+      --debug-map-source <source>
+                Global PMTiles source URL/path used for the offline map
+                Defaults to the latest available Protomaps daily build
+  -h, --help     Show this help message
+  -v, --version  Show version number
+`.trim();
+async function main() {
+    const abortController = new AbortController();
+    const abortOnSigint = () => {
+        console.error('\nAborting offline ZIP creation...');
+        abortController.abort(new Error('Aborted by SIGINT'));
+    };
+    process.once('SIGINT', abortOnSigint);
+    const { values, positionals } = parseArgs({
+        args: process.argv.slice(2),
+        allowPositionals: true,
+        options: {
+            output: { type: 'string', short: 'o', default: 'offline.zip' },
+            'debug-no-offline-map': { type: 'boolean', default: false },
+            'debug-map-source': { type: 'string' },
+            help: { type: 'boolean', short: 'h', default: false },
+            version: { type: 'boolean', short: 'v', default: false },
+        },
+    });
+    if (values.help) {
+        console.log(HELP);
+        process.exit(0);
+    }
+    if (values.version) {
+        const require = createRequire(import.meta.url);
+        const pkg = require('../package.json');
+        console.log(pkg.version);
+        process.exit(0);
+    }
+    const manifestUrl = positionals[0];
+    if (!manifestUrl) {
+        console.error('Error: manifest URL is required.\n');
+        console.error(HELP);
+        process.exit(1);
+    }
+    // Validate URL
+    try {
+        new URL(manifestUrl);
+    }
+    catch {
+        console.error(`Error: "${manifestUrl}" is not a valid URL.\n`);
+        process.exit(1);
+    }
+    const outputPath = values.output;
+    if (!outputPath.endsWith('.zip')) {
+        console.error('Error: output path must end with .zip\n');
+        process.exit(1);
+    }
+    if (values['debug-no-offline-map'] && values['debug-map-source']) {
+        console.error('Error: --debug-map-source cannot be used with --debug-no-offline-map\n');
+        process.exit(1);
+    }
+    const offlineMap = values['debug-map-source']
+        ? { mapSource: values['debug-map-source'] }
+        : undefined;
+    const inferOfflineMap = !values['debug-no-offline-map'];
+    console.log(`Resolving @expofp/floorplan runtime...`);
+    const runtimeBaseUrl = await resolveFloorplanDir();
+    console.log(`Creating offline ZIP from ${manifestUrl}...`);
+    try {
+        await saveOfflineZip({ $ref: manifestUrl }, outputPath, {
+            runtimeBaseUrl,
+            offlineMap,
+            inferOfflineMap,
+            signal: abortController.signal,
+        });
+    }
+    finally {
+        process.removeListener('SIGINT', abortOnSigint);
+    }
+    console.log(`Done! Offline ZIP saved to ${outputPath}`);
+}
+main().catch((err) => {
+    console.error('Error:', err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { downloadOfflineZip } from './lib/download-offline-zip.js';
+export { buildOfflineZip } from './lib/generate-offline-data.js';
+export { saveOfflineZip } from './lib/save-offline-zip.js';
+export type { OfflineOptions } from './lib/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+export { downloadOfflineZip } from './lib/download-offline-zip.js';
+export { buildOfflineZip } from './lib/generate-offline-data.js';
+export { saveOfflineZip } from './lib/save-offline-zip.js';

package/dist/lib/abort-signal.d.ts

@@ -0,0 +1,2 @@
+export declare function withTimeout(signal: AbortSignal | undefined, ms: number): AbortSignal;
+//# sourceMappingURL=abort-signal.d.ts.map

package/dist/lib/abort-signal.js

@@ -0,0 +1,6 @@
+export function withTimeout(signal, ms) {
+    if (signal?.aborted)
+        return signal;
+    const timeout = AbortSignal.timeout(ms);
+    return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}

package/dist/lib/data-to-files.d.ts

@@ -0,0 +1,9 @@
+import { type LocalData } from './types.js';
+export declare const FILE_FETCH_TIMEOUT_MS = 60000;
+export declare function dataToFiles(data: AsyncIterable<LocalData>, options?: {
+    signal?: AbortSignal;
+}): AsyncIterable<{
+    path: string;
+    data: Uint8Array;
+}>;
+//# sourceMappingURL=data-to-files.d.ts.map

package/dist/lib/data-to-files.js

@@ -0,0 +1,35 @@
+import { readFileFromUrl } from '@expofp/utils';
+import debug from 'debug';
+import { withTimeout } from './abort-signal.js';
+const log = debug('efp:offline:data-to-files');
+export const FILE_FETCH_TIMEOUT_MS = 60_000;
+export async function* dataToFiles(data, options) {
+    for await (const file of data) {
+        if ('url' in file) {
+            const signal = withTimeout(options?.signal, FILE_FETCH_TIMEOUT_MS);
+            const response = await readFileFromUrl(file.url, { signal });
+            if (!response.ok) {
+                // only expected-missing resources (fabricated variant URLs) may be
+                // skipped — an archive silently missing anything else is broken
+                if (!file.optional) {
+                    throw new Error(`Failed to download ${file.url}`);
+                }
+                console.warn(`Skipping optional file ${file.url} as it could not be downloaded`);
+            }
+            else {
+                log('Bundling file from url', file.targetFilePath);
+                yield {
+                    path: file.targetFilePath,
+                    data: response.data,
+                };
+            }
+        }
+        else {
+            log('Bundling text file', file.targetFilePath);
+            yield {
+                path: file.targetFilePath,
+                data: new TextEncoder().encode(file.text),
+            };
+        }
+    }
+}

package/dist/lib/download-offline-zip.d.ts

@@ -0,0 +1,5 @@
+import { type Manifest } from '@expofp/config';
+import { type Ref } from '@expofp/resolve';
+import { type OfflineOptions } from './types.js';
+export declare function downloadOfflineZip(manifest: Manifest | Ref<Manifest>, options: OfflineOptions): Promise<void>;
+//# sourceMappingURL=download-offline-zip.d.ts.map

package/dist/lib/download-offline-zip.js

@@ -0,0 +1,14 @@
+import { buildOfflineZip } from './generate-offline-data.js';
+export async function downloadOfflineZip(manifest, options) {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        throw new Error('downloadOfflineZip can only be used in a browser environment');
+    }
+    const blob = await buildOfflineZip(manifest, options);
+    const objectUrl = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = objectUrl;
+    a.download = 'offline.zip';
+    a.click();
+    // revoke to prevent race conditions with the download
+    setTimeout(() => URL.revokeObjectURL(objectUrl), 60_000);
+}

package/dist/lib/generate-offline-data.d.ts

@@ -0,0 +1,14 @@
+import { type Manifest } from '@expofp/config';
+import { type Ref } from '@expofp/resolve';
+import { type LocalData, type OfflineOptions } from './types.js';
+/**
+ * An offline copy is nothing but a serialized config: `loadConfig` produces
+ * the complete event data document (refs warm, every asset URL absolute), and
+ * `serializeConfigResources` walks it — this package only decides WHERE
+ * things go (page-relative archive-local paths, so the copy resolves against
+ * wherever `index.html` is mounted) and zips the result with the runtime.
+ */
+export declare function generateOfflineData(inputManifest: Manifest | Ref<Manifest>, options: OfflineOptions): AsyncIterable<LocalData, void>;
+/** Build a complete offline ZIP archive from a manifest. */
+export declare function buildOfflineZip(manifest: Manifest | Ref<Manifest>, options: OfflineOptions): Promise<Blob>;
+//# sourceMappingURL=generate-offline-data.d.ts.map

package/dist/lib/generate-offline-data.js

@@ -0,0 +1,160 @@
+import { loadConfig, serializeConfigResources, } from '@expofp/config';
+import { getResolved, resolve } from '@expofp/resolve';
+import { buildZipArchive, deepClone, makeLocalPath, readFileFromUrl } from '@expofp/utils';
+import debug from 'debug';
+import { withTimeout } from './abort-signal.js';
+import { dataToFiles, FILE_FETCH_TIMEOUT_MS } from './data-to-files.js';
+import { generateOfflineMapData, inferOfflineMapOptions, validateOfflineMapOptions, } from './generate-offline-map-data.js';
+import { generateRuntimeFilesData } from './generate-runtime-files-data.js';
+const log = debug('efp:offline:generate-offline-data');
+/**
+ * An offline copy is nothing but a serialized config: `loadConfig` produces
+ * the complete event data document (refs warm, every asset URL absolute), and
+ * `serializeConfigResources` walks it — this package only decides WHERE
+ * things go (page-relative archive-local paths, so the copy resolves against
+ * wherever `index.html` is mounted) and zips the result with the runtime.
+ */
+export async function* generateOfflineData(inputManifest, options) {
+    const manifest = deepClone(await resolve(inputManifest, { signal: options.signal }));
+    log(`Generating offline files for expo: ${manifest.expo}`);
+    const config = await loadConfig(manifest, {});
+    const pathPrefix = config.expo;
+    // this is a requirement of mobile SDK, paths in the ZIP must be prefixed with the expo name
+    // TODO: make sure SDK works with unprefixed paths, and remove the prefixing logic from this function
+    const prefixPath = (path) => `${pathPrefix}/${path}`;
+    const offlineMap = await resolveOfflineMapOptions(config, options);
+    const { files, localManifest } = await serializeConfig(config, options.signal);
+    for (const d of files) {
+        yield { ...d, targetFilePath: prefixPath(d.targetFilePath) };
+    }
+    if (offlineMap) {
+        const mapData = generateOfflineMapData({
+            ...offlineMap,
+            fpSvgContext: getFpSvgJs(config),
+            signal: options.signal,
+        });
+        for await (const d of mapData.files) {
+            yield { ...d, targetFilePath: prefixPath(d.targetFilePath) };
+        }
+        localManifest.maplibre = { ...mapData.maplibre };
+    }
+    // add runtime files — manually iterate to prefix paths while capturing return value
+    const runtimeGen = generateRuntimeFilesData(options.runtimeBaseUrl);
+    let runtimeResult = await runtimeGen.next();
+    while (!runtimeResult.done) {
+        yield {
+            ...runtimeResult.value,
+            targetFilePath: prefixPath(runtimeResult.value.targetFilePath),
+        };
+        runtimeResult = await runtimeGen.next();
+    }
+    const { entry } = runtimeResult.value;
+    // the archive's manifest — the whole event data document, everything resolved
+    yield {
+        text: JSON.stringify(localManifest, null, 2),
+        targetFilePath: prefixPath('manifest.json'),
+    };
+    // generate index.html
+    yield {
+        text: getIndexHtml(entry, 'manifest.json'),
+        targetFilePath: prefixPath('index.html'),
+    };
+}
+/**
+ * The storage policy behind `serializeConfigResources`: assets land at their
+ * `makeLocalPath`, referenced documents are saved as `.json` files, and
+ * everything is addressed with **page-relative** URLs — bare `makeLocalPath`
+ * output, no leading slash — so the archive resolves wherever `index.html` is
+ * mounted (inside the expo folder, a parent at `/<expo>/`, or the SDK mount)
+ * alike. Non-remote (already-local or `data:`) resources pass through as-is.
+ */
+async function serializeConfig(config, signal) {
+    const files = [];
+    const seenPaths = new Set();
+    const add = (entry) => {
+        if (!seenPaths.has(entry.targetFilePath)) {
+            seenPaths.add(entry.targetFilePath);
+            files.push(entry);
+        }
+    };
+    const isRemote = (url) => /^https?:\/\//i.test(url);
+    const store = {
+        async asset(url, optional) {
+            if (!isRemote(url))
+                return url;
+            const targetFilePath = await makeLocalPath(new URL(url));
+            add({ url: new URL(url), targetFilePath, optional });
+            return targetFilePath;
+        },
+        async document(refUrl, document) {
+            const targetFilePath = documentPath(await makeLocalPath(new URL(refUrl)));
+            add({ text: JSON.stringify(document), targetFilePath });
+            return targetFilePath;
+        },
+        // @import'ed stylesheets (e.g. Google Fonts css2) are spliced into the
+        // importing CSS rather than saved as files — an extension-less saved
+        // stylesheet would be served with the wrong MIME type, and splicing lets
+        // the ordinary asset pass localize the fonts the import pulls in.
+        async stylesheetText(url) {
+            const response = await readFileFromUrl(new URL(url), {
+                signal: withTimeout(signal, FILE_FETCH_TIMEOUT_MS),
+            });
+            if (!response.ok)
+                throw new Error(`Failed to download @import'ed stylesheet ${url}`);
+            return new TextDecoder().decode(response.data);
+        },
+        documentError(refUrl, error) {
+            // The wayfinding graph is optional — an expo without one is normal, so
+            // (like the fabricated __small/__tiny logo variants) warn and drop the
+            // ref. Any other document missing means a broken archive: fail the build.
+            if (refUrl === config.wfDataJsRef?.$ref) {
+                console.warn(`Skipping wayfinding graph ${refUrl} as it could not be resolved`, error);
+                return;
+            }
+            throw error;
+        },
+    };
+    const localManifest = await serializeConfigResources(config, store, { signal });
+    return { files, localManifest };
+}
+/** Saved documents are resolved JSON, whatever the live file was called. */
+function documentPath(localPath) {
+    if (localPath.endsWith('.json'))
+        return localPath;
+    return localPath.replace(/\.js$/i, '') + '.json';
+}
+/** The eagerly-resolved drawing payload (loadConfig warmed the ref). */
+function getFpSvgJs(config) {
+    if (!config.fpSvgJsRef)
+        throw new Error('config has no drawing (fpSvgJsRef)');
+    return getResolved(config.fpSvgJsRef);
+}
+async function resolveOfflineMapOptions(config, options) {
+    if (options.inferOfflineMap) {
+        return await inferOfflineMapOptions(getFpSvgJs(config), options.offlineMap, options.signal);
+    }
+    if (options.offlineMap) {
+        return await validateOfflineMapOptions(options.offlineMap, options.signal);
+    }
+    return undefined;
+}
+/** Build a complete offline ZIP archive from a manifest. */
+export async function buildOfflineZip(manifest, options) {
+    const data = generateOfflineData(manifest, options);
+    const files = dataToFiles(data, { signal: options.signal });
+    return await buildZipArchive(files);
+}
+/** Known path — file lives in `packages/floorplan/public/` and is copied to dist by Vite. */
+const COMPAT_HELPER = 'compat-helper.js';
+function getIndexHtml(entry, manifestRef) {
+    // entry is "./runtime/index.js", derive the runtime base path
+    const runtimeBase = entry.slice(0, entry.lastIndexOf('/') + 1);
+    return `\
+<!DOCTYPE html>
+<script src="${runtimeBase}${COMPAT_HELPER}"></script>
+<script type="module">
+  import { load } from ${JSON.stringify(entry)};
+  await load({ $ref: ${JSON.stringify(manifestRef)} });
+</script>
+`;
+}

package/dist/lib/generate-offline-map-data.d.ts

@@ -0,0 +1,20 @@
+import type { MaplibreOptions } from '@expofp/schema';
+import { type LocalData, type OfflineMapOptions } from './types.js';
+type FpSvgContext = Record<string, unknown>;
+export type ValidatedOfflineMapOptions = OfflineMapOptions & {
+    mapSource: string;
+    fpSvgContext?: FpSvgContext;
+};
+export interface OfflineMapResult {
+    files: AsyncIterable<LocalData>;
+    maplibre: MaplibreOptions;
+}
+export declare function generateOfflineMapData(options: ValidatedOfflineMapOptions & {
+    fpSvgContext: FpSvgContext;
+    signal?: AbortSignal;
+}): OfflineMapResult;
+export declare function validateOfflineMapOptions(options: OfflineMapOptions, signal?: AbortSignal): Promise<ValidatedOfflineMapOptions>;
+/** An offline map applies only when the (already-loaded) drawing is geo-referenced. */
+export declare function inferOfflineMapOptions(fpSvgContext: FpSvgContext, options: OfflineMapOptions | undefined, signal?: AbortSignal): Promise<ValidatedOfflineMapOptions | undefined>;
+export {};
+//# sourceMappingURL=generate-offline-map-data.d.ts.map