@faicad/faijs 0.19.0 → 0.29.3

package/dist/io/fai-zip/container-read.js

@@ -0,0 +1,305 @@
+/**
+ * Unified `.fai.zip` read API (docs/fai-zip-format.md §4–§9).
+ *
+ * Environment-independent by constraint: reading goes through `io/zip.ts`
+ * (`readZipEntries`) plus JSON parsing — no `node:*`, no DOM, no fs, and no
+ * direct ZIP library. Web workers, the weapp worker and node share this code.
+ *
+ * Contract highlights (spec §9 Reader obligations):
+ * - a missing/malformed manifest, `format !== 3`, a malformed `models` array,
+ *   a missing entry, a missing named data member and a duplicate asset key are
+ *   all errors carrying the offending value;
+ * - entry selection is `active` or `models[0]` — never a file-name heuristic;
+ * - members outside the table (§3), unknown manifest fields and unknown
+ *   data-member keys are ignored, never errors, never decision inputs.
+ */
+import { readZipEntries } from '../zip.js';
+import { assetKeyOf, assertDataMemberPath, assertModelMemberPath, assertSafeMemberPath, decodeMemberText, } from './container.js';
+/** Path prefix of every model script member. */
+const MODEL_PREFIX = 'model/';
+/** Path prefix of the imported-file payloads. */
+const FILES_PREFIX = 'files/';
+/** Path prefix of the script-consumed payloads. */
+const ASSETS_PREFIX = 'assets/';
+/**
+ * Unpack the archive; a non-ZIP input is a hard error carrying the original
+ * failure as `cause`. Caps violations keep `io/zip.ts`'s wording.
+ */
+function unzipMembers(bytes, caps) {
+    try {
+        return readZipEntries(bytes, caps);
+    }
+    catch (e) {
+        const inner = (e instanceof Error ? e.message : String(e)).replace(/^zip read failed: /, '');
+        const err = new Error(`[fai-zip] cannot open container as ZIP: ${inner}`);
+        err.cause = e;
+        throw err;
+    }
+}
+/** Normalize a manifest field error into one message naming the offending value. */
+function manifestError(reason, value) {
+    const shown = value === undefined ? '' : ` (observed: ${JSON.stringify(value)})`;
+    return new Error(`[fai-zip] invalid manifest: ${reason}${shown}`);
+}
+/**
+ * Read and validate the container manifest from already-unpacked members.
+ * @param members the unpacked container members
+ * @returns the validated manifest
+ */
+function readManifestFrom(members) {
+    const raw = members.get('manifest.json');
+    if (raw === undefined)
+        throw new Error('[fai-zip] invalid manifest: missing manifest.json — not a .fai.zip container');
+    let parsed;
+    try {
+        parsed = JSON.parse(decodeMemberText(raw));
+    }
+    catch (e) {
+        throw new Error(`[fai-zip] invalid manifest: manifest.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw manifestError('manifest.json must be a JSON object');
+    }
+    const manifest = parsed;
+    if (manifest.format !== 3) {
+        throw manifestError('format must be the integer 3 (this revision); no other value is interpretable', manifest.format);
+    }
+    if (manifest.units !== 'mm') {
+        throw manifestError('units must be "mm"', manifest.units);
+    }
+    if (!Array.isArray(manifest.models) || manifest.models.length === 0) {
+        throw manifestError('models must be a non-empty array', manifest.models);
+    }
+    const models = manifest.models;
+    const seenIds = new Set();
+    const seenEntries = new Set();
+    const normalized = [];
+    for (let i = 0; i < models.length; i++) {
+        const m = models[i];
+        if (typeof m !== 'object' || m === null || Array.isArray(m)) {
+            throw manifestError(`models[${i}] must be an object`, m);
+        }
+        const rec = m;
+        const id = typeof rec.id === 'string' ? rec.id : '';
+        if (id === '')
+            throw manifestError(`models[${i}].id must be a non-empty string`, rec.id);
+        if (id.includes('/') || id.includes('\\'))
+            throw manifestError(`models[${i}].id must not contain "/" or "\\"`, id);
+        if (seenIds.has(id))
+            throw manifestError('models[].id must be unique', id);
+        seenIds.add(id);
+        const entry = typeof rec.entry === 'string' ? rec.entry : '';
+        if (entry === '')
+            throw manifestError(`models[${i}].entry must be a non-empty string`, rec.entry);
+        assertModelMemberPath(entry, `models[${i}].entry`);
+        if (seenEntries.has(entry))
+            throw manifestError('models[].entry must be unique', entry);
+        seenEntries.add(entry);
+        if (!members.has(entry)) {
+            throw manifestError(`models[${i}].entry does not exist in the container`, entry);
+        }
+        const data = typeof rec.data === 'string' ? rec.data : undefined;
+        if (data !== undefined) {
+            assertSafeMemberPath(data, `models[${i}].data`);
+            if (!members.has(data)) {
+                throw manifestError(`models[${i}].data names a member that does not exist`, data);
+            }
+        }
+        normalized.push({
+            id,
+            entry,
+            ...(typeof rec.label === 'string' ? { label: rec.label } : {}),
+            ...(data !== undefined ? { data } : {}),
+        });
+    }
+    let active;
+    if (manifest.active !== undefined) {
+        if (typeof manifest.active !== 'string' || !seenIds.has(manifest.active)) {
+            throw manifestError('active must equal some models[].id', manifest.active);
+        }
+        active = manifest.active;
+    }
+    return {
+        format: 3,
+        units: 'mm',
+        models: normalized,
+        ...(active !== undefined ? { active } : {}),
+        ...(typeof manifest.createdAt === 'string' ? { createdAt: manifest.createdAt } : {}),
+        ...(typeof manifest.appVersion === 'string' ? { appVersion: manifest.appVersion } : {}),
+        ...(typeof manifest.label === 'string' ? { label: manifest.label } : {}),
+        ...(typeof manifest.source === 'object' && manifest.source !== null ? { source: manifest.source } : {}),
+    };
+}
+/**
+ * Collect the payload bytes of already-unpacked members.
+ * Keys are unique across `files/**` and `assets/**` together (spec §7.1);
+ * a duplicate key is an error rather than a pick.
+ * @param members the unpacked container members
+ * @returns the payload entries keyed by asset key
+ */
+function readAssetEntriesFrom(members) {
+    const files = {};
+    const assets = {};
+    const claimed = new Set();
+    for (const [path, body] of members) {
+        const prefix = path.startsWith(FILES_PREFIX)
+            ? FILES_PREFIX
+            : path.startsWith(ASSETS_PREFIX)
+                ? ASSETS_PREFIX
+                : undefined;
+        if (prefix === undefined)
+            continue;
+        const key = assetKeyOf(path, prefix);
+        if (claimed.has(key))
+            throw new Error(`[fai-zip] duplicate asset key across files//assets/: "${key}"`);
+        claimed.add(key);
+        if (prefix === FILES_PREFIX)
+            files[key] = body;
+        else
+            assets[key] = body;
+    }
+    return { files, assets };
+}
+/**
+ * Read and validate the container manifest (spec §4).
+ * @param bytes the .fai.zip archive bytes
+ * @returns the validated manifest
+ * @throws when the archive is not a ZIP, the manifest is missing/malformed,
+ *   `format !== 3`, `units !== "mm"`, `models` is empty/malformed, ids/entries
+ *   are duplicated, an entry is not under `model/` or does not exist, `active`
+ *   is not in `models[].id`, or a named `data` member does not exist.
+ */
+export function readManifest(bytes) {
+    return readManifestFrom(unzipMembers(bytes));
+}
+/**
+ * List the container models (validated). Same validation as readManifest.
+ * @param bytes the .fai.zip archive bytes
+ * @returns the validated model list
+ */
+export function listModels(bytes) {
+    return readManifest(bytes).models;
+}
+/**
+ * List every module under `model/` (keys relative to `model/`, sorted).
+ * Members outside the table are ignored (§3), never an error.
+ * @param bytes the .fai.zip archive bytes
+ * @returns module keys relative to `model/`, sorted
+ */
+export function listModules(bytes) {
+    return listModulesFrom(unzipMembers(bytes));
+}
+/** Module keys (relative to `model/`, sorted) of already-unpacked members. */
+function listModulesFrom(members) {
+    const keys = [];
+    for (const path of members.keys()) {
+        if (path.startsWith(MODEL_PREFIX) && path.endsWith('.fai.js') && path.length > MODEL_PREFIX.length) {
+            keys.push(path.slice(MODEL_PREFIX.length));
+        }
+    }
+    return keys.sort();
+}
+/**
+ * Read one module's source text by module key (relative to `model/`).
+ * @param bytes the .fai.zip archive bytes
+ * @param key the module key relative to `model/` (e.g. `main.fai.js`)
+ * @returns the module source text
+ * @throws for a key outside `model/` or that does not exist
+ */
+export function readModule(bytes, key) {
+    if (typeof key !== 'string' || key === '') {
+        throw new Error('[fai-zip] readModule: key must be a non-empty string');
+    }
+    assertSafeMemberPath(key, 'readModule key');
+    if (!key.endsWith('.fai.js')) {
+        throw new Error(`[fai-zip] readModule: key must name a module under model/ (ends with .fai.js): "${key}"`);
+    }
+    const member = unzipMembers(bytes).get(MODEL_PREFIX + key);
+    if (member === undefined) {
+        throw new Error(`[fai-zip] readModule: module "${key}" does not exist under model/`);
+    }
+    return decodeMemberText(member);
+}
+/**
+ * Read one model data member's JSON text by member path (e.g. `data/main.json`).
+ *
+ * The path must be exactly what `models[].data` declares (spec §4): a safe,
+ * relative member under `data/` ending with `.json`. Content is validated to
+ * parse as JSON — the editor keeps data members pure JSON (§6.1), so a
+ * non-JSON member is a format violation and an error, never a silent skip.
+ *
+ * @param bytes the .fai.zip archive bytes
+ * @param memberPath the member path named by `models[].data`
+ * @returns the raw JSON text
+ * @throws for a non-string/unsafe path, a path outside `data/`, a missing
+ *   member, or content that does not parse as JSON
+ */
+export function readDataMember(bytes, memberPath) {
+    if (typeof memberPath !== 'string' || memberPath === '') {
+        throw new Error('[fai-zip] readDataMember: memberPath must be a non-empty string');
+    }
+    assertDataMemberPath(memberPath, 'readDataMember path');
+    const member = unzipMembers(bytes).get(memberPath);
+    if (member === undefined) {
+        throw new Error(`[fai-zip] readDataMember: member "${memberPath}" does not exist in the container`);
+    }
+    const text = decodeMemberText(member);
+    try {
+        JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`[fai-zip] readDataMember: "${memberPath}" is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+    return text;
+}
+/**
+ * Collect the payload bytes of a container.
+ * Keys are unique across `files/**` and `assets/**` together (spec §7.1);
+ * a duplicate key is an error rather than a pick.
+ * @param bytes the .fai.zip archive bytes
+ * @returns the payload entries keyed by asset key
+ */
+export function readAssetEntries(bytes) {
+    return readAssetEntriesFrom(unzipMembers(bytes));
+}
+/**
+ * Host entry point: open a container and return the manifest, the active
+ * model and a ProjectLoader over its module graph, plus the payloads.
+ *
+ * The archive is unpacked exactly once for the whole call.
+ *
+ * @param bytes the .fai.zip archive bytes
+ * @param opts optional active-model override and `io/zip.ts` read caps
+ * @returns manifest, active model, project loader and payload entries
+ * @throws when the container is invalid, the requested model id is unknown, or
+ *   the read caps are exceeded
+ */
+export function openContainer(bytes, opts = {}) {
+    const members = unzipMembers(bytes, opts.caps);
+    const manifest = readManifestFrom(members);
+    const activeModel = (() => {
+        if (opts.modelId === undefined) {
+            const byActive = manifest.models.find((m) => m.id === manifest.active);
+            return byActive ?? manifest.models[0];
+        }
+        const byParam = manifest.models.find((m) => m.id === opts.modelId);
+        if (byParam === undefined) {
+            throw new Error(`[fai-zip] openContainer: model "${opts.modelId}" is not in models[]`);
+        }
+        return byParam;
+    })();
+    const keys = listModulesFrom(members);
+    const loader = {
+        listModules: () => [...keys],
+        readSource: async (moduleKey) => {
+            const member = members.get(MODEL_PREFIX + moduleKey);
+            if (member === undefined) {
+                throw new Error(`[fai-zip] loader: module "${moduleKey}" does not exist under model/`);
+            }
+            return decodeMemberText(member);
+        },
+    };
+    const { files, assets } = readAssetEntriesFrom(members);
+    return { manifest, activeModel, loader, files, assets };
+}
+//# sourceMappingURL=container-read.js.map

package/dist/io/fai-zip/container-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-read.js","sourceRoot":"","sources":["../../../src/io/fai-zip/container-read.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Unified `.fai.zip` read API (docs/fai-zip-format.md §4–§9).\n *\n * Environment-independent by constraint: reading goes through `io/zip.ts`\n * (`readZipEntries`) plus JSON parsing — no `node:*`, no DOM, no fs, and no\n * direct ZIP library. Web workers, the weapp worker and node share this code.\n *\n * Contract highlights (spec §9 Reader obligations):\n * - a missing/malformed manifest, `format !== 3`, a malformed `models` array,\n *   a missing entry, a missing named data member and a duplicate asset key are\n *   all errors carrying the offending value;\n * - entry selection is `active` or `models[0]` — never a file-name heuristic;\n * - members outside the table (§3), unknown manifest fields and unknown\n *   data-member keys are ignored, never errors, never decision inputs.\n */\nimport { readZipEntries, type ZipReadOptions } from '../zip'\nimport type { ProjectLoader } from '../../cad-runtime/ports'\nimport {\n  assetKeyOf,\n  assertDataMemberPath,\n  assertModelMemberPath,\n  assertSafeMemberPath,\n  decodeMemberText,\n  type ContainerAssetEntries,\n  type ContainerManifest,\n  type ContainerModel,\n} from './container'\n\n/** openContainer options. */\nexport interface OpenContainerOptions {\n  /** override `manifest.active`; default = `manifest.active`, else `models[0]` */\n  modelId?: string\n  /** override the `io/zip.ts` read caps (maxEntries / maxTotalBytes) */\n  caps?: ZipReadOptions\n}\n\n/** openContainer result: manifest, active model, loader and payloads. */\nexport interface OpenContainerResult {\n  manifest: ContainerManifest\n  activeModel: ContainerModel\n  /** project loader over the container's module graph (listModules/readSource) */\n  loader: ProjectLoader\n  files: Record<string, Uint8Array>\n  assets: Record<string, Uint8Array>\n}\n\n/** Unzipped members, keyed by container path. */\ntype MemberMap = Map<string, Uint8Array>\n\n/** Path prefix of every model script member. */\nconst MODEL_PREFIX = 'model/'\n/** Path prefix of the imported-file payloads. */\nconst FILES_PREFIX = 'files/'\n/** Path prefix of the script-consumed payloads. */\nconst ASSETS_PREFIX = 'assets/'\n\n/**\n * Unpack the archive; a non-ZIP input is a hard error carrying the original\n * failure as `cause`. Caps violations keep `io/zip.ts`'s wording.\n */\nfunction unzipMembers(bytes: Uint8Array, caps?: ZipReadOptions): MemberMap {\n  try {\n    return readZipEntries(bytes, caps)\n  } catch (e) {\n    const inner = (e instanceof Error ? e.message : String(e)).replace(/^zip read failed: /, '')\n    const err = new Error(`[fai-zip] cannot open container as ZIP: ${inner}`)\n    ;(err as Error & { cause?: unknown }).cause = e\n    throw err\n  }\n}\n\n/** Normalize a manifest field error into one message naming the offending value. */\nfunction manifestError(reason: string, value?: unknown): Error {\n  const shown = value === undefined ? '' : ` (observed: ${JSON.stringify(value)})`\n  return new Error(`[fai-zip] invalid manifest: ${reason}${shown}`)\n}\n\n/**\n * Read and validate the container manifest from already-unpacked members.\n * @param members the unpacked container members\n * @returns the validated manifest\n */\nfunction readManifestFrom(members: MemberMap): ContainerManifest {\n  const raw = members.get('manifest.json')\n  if (raw === undefined) throw new Error('[fai-zip] invalid manifest: missing manifest.json — not a .fai.zip container')\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(decodeMemberText(raw))\n  } catch (e) {\n    throw new Error(`[fai-zip] invalid manifest: manifest.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, { cause: e })\n  }\n  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n    throw manifestError('manifest.json must be a JSON object')\n  }\n  const manifest = parsed as Record<string, unknown>\n\n  if (manifest.format !== 3) {\n    throw manifestError('format must be the integer 3 (this revision); no other value is interpretable', manifest.format)\n  }\n  if (manifest.units !== 'mm') {\n    throw manifestError('units must be \"mm\"', manifest.units)\n  }\n  if (!Array.isArray(manifest.models) || manifest.models.length === 0) {\n    throw manifestError('models must be a non-empty array', manifest.models)\n  }\n\n  const models = manifest.models as unknown[]\n  const seenIds = new Set<string>()\n  const seenEntries = new Set<string>()\n  const normalized: ContainerModel[] = []\n  for (let i = 0; i < models.length; i++) {\n    const m = models[i]\n    if (typeof m !== 'object' || m === null || Array.isArray(m)) {\n      throw manifestError(`models[${i}] must be an object`, m)\n    }\n    const rec = m as Record<string, unknown>\n    const id = typeof rec.id === 'string' ? rec.id : ''\n    if (id === '') throw manifestError(`models[${i}].id must be a non-empty string`, rec.id)\n    if (id.includes('/') || id.includes('\\\\')) throw manifestError(`models[${i}].id must not contain \"/\" or \"\\\\\"`, id)\n    if (seenIds.has(id)) throw manifestError('models[].id must be unique', id)\n    seenIds.add(id)\n\n    const entry = typeof rec.entry === 'string' ? rec.entry : ''\n    if (entry === '') throw manifestError(`models[${i}].entry must be a non-empty string`, rec.entry)\n    assertModelMemberPath(entry, `models[${i}].entry`)\n    if (seenEntries.has(entry)) throw manifestError('models[].entry must be unique', entry)\n    seenEntries.add(entry)\n    if (!members.has(entry)) {\n      throw manifestError(`models[${i}].entry does not exist in the container`, entry)\n    }\n\n    const data = typeof rec.data === 'string' ? rec.data : undefined\n    if (data !== undefined) {\n      assertSafeMemberPath(data, `models[${i}].data`)\n      if (!members.has(data)) {\n        throw manifestError(`models[${i}].data names a member that does not exist`, data)\n      }\n    }\n\n    normalized.push({\n      id,\n      entry,\n      ...(typeof rec.label === 'string' ? { label: rec.label } : {}),\n      ...(data !== undefined ? { data } : {}),\n    })\n  }\n\n  let active: string | undefined\n  if (manifest.active !== undefined) {\n    if (typeof manifest.active !== 'string' || !seenIds.has(manifest.active)) {\n      throw manifestError('active must equal some models[].id', manifest.active)\n    }\n    active = manifest.active\n  }\n\n  return {\n    format: 3,\n    units: 'mm',\n    models: normalized,\n    ...(active !== undefined ? { active } : {}),\n    ...(typeof manifest.createdAt === 'string' ? { createdAt: manifest.createdAt } : {}),\n    ...(typeof manifest.appVersion === 'string' ? { appVersion: manifest.appVersion } : {}),\n    ...(typeof manifest.label === 'string' ? { label: manifest.label } : {}),\n    ...(typeof manifest.source === 'object' && manifest.source !== null ? { source: manifest.source as ContainerManifest['source'] } : {}),\n  }\n}\n\n/**\n * Collect the payload bytes of already-unpacked members.\n * Keys are unique across `files/**` and `assets/**` together (spec §7.1);\n * a duplicate key is an error rather than a pick.\n * @param members the unpacked container members\n * @returns the payload entries keyed by asset key\n */\nfunction readAssetEntriesFrom(members: MemberMap): ContainerAssetEntries {\n  const files: Record<string, Uint8Array> = {}\n  const assets: Record<string, Uint8Array> = {}\n  const claimed = new Set<string>()\n  for (const [path, body] of members) {\n    const prefix = path.startsWith(FILES_PREFIX)\n      ? FILES_PREFIX\n      : path.startsWith(ASSETS_PREFIX)\n        ? ASSETS_PREFIX\n        : undefined\n    if (prefix === undefined) continue\n    const key = assetKeyOf(path, prefix)\n    if (claimed.has(key)) throw new Error(`[fai-zip] duplicate asset key across files//assets/: \"${key}\"`)\n    claimed.add(key)\n    if (prefix === FILES_PREFIX) files[key] = body\n    else assets[key] = body\n  }\n  return { files, assets }\n}\n\n/**\n * Read and validate the container manifest (spec §4).\n * @param bytes the .fai.zip archive bytes\n * @returns the validated manifest\n * @throws when the archive is not a ZIP, the manifest is missing/malformed,\n *   `format !== 3`, `units !== \"mm\"`, `models` is empty/malformed, ids/entries\n *   are duplicated, an entry is not under `model/` or does not exist, `active`\n *   is not in `models[].id`, or a named `data` member does not exist.\n */\nexport function readManifest(bytes: Uint8Array): ContainerManifest {\n  return readManifestFrom(unzipMembers(bytes))\n}\n\n/**\n * List the container models (validated). Same validation as readManifest.\n * @param bytes the .fai.zip archive bytes\n * @returns the validated model list\n */\nexport function listModels(bytes: Uint8Array): ContainerModel[] {\n  return readManifest(bytes).models\n}\n\n/**\n * List every module under `model/` (keys relative to `model/`, sorted).\n * Members outside the table are ignored (§3), never an error.\n * @param bytes the .fai.zip archive bytes\n * @returns module keys relative to `model/`, sorted\n */\nexport function listModules(bytes: Uint8Array): string[] {\n  return listModulesFrom(unzipMembers(bytes))\n}\n\n/** Module keys (relative to `model/`, sorted) of already-unpacked members. */\nfunction listModulesFrom(members: MemberMap): string[] {\n  const keys: string[] = []\n  for (const path of members.keys()) {\n    if (path.startsWith(MODEL_PREFIX) && path.endsWith('.fai.js') && path.length > MODEL_PREFIX.length) {\n      keys.push(path.slice(MODEL_PREFIX.length))\n    }\n  }\n  return keys.sort()\n}\n\n/**\n * Read one module's source text by module key (relative to `model/`).\n * @param bytes the .fai.zip archive bytes\n * @param key the module key relative to `model/` (e.g. `main.fai.js`)\n * @returns the module source text\n * @throws for a key outside `model/` or that does not exist\n */\nexport function readModule(bytes: Uint8Array, key: string): string {\n  if (typeof key !== 'string' || key === '') {\n    throw new Error('[fai-zip] readModule: key must be a non-empty string')\n  }\n  assertSafeMemberPath(key, 'readModule key')\n  if (!key.endsWith('.fai.js')) {\n    throw new Error(`[fai-zip] readModule: key must name a module under model/ (ends with .fai.js): \"${key}\"`)\n  }\n  const member = unzipMembers(bytes).get(MODEL_PREFIX + key)\n  if (member === undefined) {\n    throw new Error(`[fai-zip] readModule: module \"${key}\" does not exist under model/`)\n  }\n  return decodeMemberText(member)\n}\n\n/**\n * Read one model data member's JSON text by member path (e.g. `data/main.json`).\n *\n * The path must be exactly what `models[].data` declares (spec §4): a safe,\n * relative member under `data/` ending with `.json`. Content is validated to\n * parse as JSON — the editor keeps data members pure JSON (§6.1), so a\n * non-JSON member is a format violation and an error, never a silent skip.\n *\n * @param bytes the .fai.zip archive bytes\n * @param memberPath the member path named by `models[].data`\n * @returns the raw JSON text\n * @throws for a non-string/unsafe path, a path outside `data/`, a missing\n *   member, or content that does not parse as JSON\n */\nexport function readDataMember(bytes: Uint8Array, memberPath: string): string {\n  if (typeof memberPath !== 'string' || memberPath === '') {\n    throw new Error('[fai-zip] readDataMember: memberPath must be a non-empty string')\n  }\n  assertDataMemberPath(memberPath, 'readDataMember path')\n  const member = unzipMembers(bytes).get(memberPath)\n  if (member === undefined) {\n    throw new Error(`[fai-zip] readDataMember: member \"${memberPath}\" does not exist in the container`)\n  }\n  const text = decodeMemberText(member)\n  try {\n    JSON.parse(text)\n  } catch (e) {\n    throw new Error(`[fai-zip] readDataMember: \"${memberPath}\" is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, { cause: e })\n  }\n  return text\n}\n\n/**\n * Collect the payload bytes of a container.\n * Keys are unique across `files/**` and `assets/**` together (spec §7.1);\n * a duplicate key is an error rather than a pick.\n * @param bytes the .fai.zip archive bytes\n * @returns the payload entries keyed by asset key\n */\nexport function readAssetEntries(bytes: Uint8Array): ContainerAssetEntries {\n  return readAssetEntriesFrom(unzipMembers(bytes))\n}\n\n/**\n * Host entry point: open a container and return the manifest, the active\n * model and a ProjectLoader over its module graph, plus the payloads.\n *\n * The archive is unpacked exactly once for the whole call.\n *\n * @param bytes the .fai.zip archive bytes\n * @param opts optional active-model override and `io/zip.ts` read caps\n * @returns manifest, active model, project loader and payload entries\n * @throws when the container is invalid, the requested model id is unknown, or\n *   the read caps are exceeded\n */\nexport function openContainer(bytes: Uint8Array, opts: OpenContainerOptions = {}): OpenContainerResult {\n  const members = unzipMembers(bytes, opts.caps)\n  const manifest = readManifestFrom(members)\n\n  const activeModel: ContainerModel = (() => {\n    if (opts.modelId === undefined) {\n      const byActive = manifest.models.find((m) => m.id === manifest.active)\n      return byActive ?? manifest.models[0]\n    }\n    const byParam = manifest.models.find((m) => m.id === opts.modelId)\n    if (byParam === undefined) {\n      throw new Error(`[fai-zip] openContainer: model \"${opts.modelId}\" is not in models[]`)\n    }\n    return byParam\n  })()\n\n  const keys = listModulesFrom(members)\n\n  const loader: ProjectLoader = {\n    listModules: () => [...keys],\n    readSource: async (moduleKey) => {\n      const member = members.get(MODEL_PREFIX + moduleKey)\n      if (member === undefined) {\n        throw new Error(`[fai-zip] loader: module \"${moduleKey}\" does not exist under model/`)\n      }\n      return decodeMemberText(member)\n    },\n  }\n\n  const { files, assets } = readAssetEntriesFrom(members)\n  return { manifest, activeModel, loader, files, assets }\n}\n"]}

package/dist/io/fai-zip/container-write.d.ts

@@ -0,0 +1,70 @@
+import { type ContainerManifest, type ContainerModel } from './container.js';
+/** Assembly input of a container: no producer concept, only format concepts. */
+export interface ContainerAssembly {
+    /** `manifest.models` — the complete model list (spec §4) */
+    models: ContainerModel[];
+    /** `manifest.active`; must equal some `models[].id` when present */
+    active?: string;
+    /** display-only manifest fields plus §8.2 conversion provenance */
+    meta?: {
+        createdAt?: string;
+        appVersion?: string;
+        label?: string;
+        source?: ContainerManifest['source'];
+    };
+    /** `model/**` members: full container path → source text. Every `models[].entry` must be present */
+    modules: Record<string, string>;
+    /** `data/**` members: full container path → JSON text (spec §6) */
+    dataMembers: Record<string, string>;
+    /** `files/**` payloads: fileId → bytes. Written as `files/<fileId>.bin` */
+    files: Record<string, Uint8Array>;
+    /** `assets/**` payloads: full container path → bytes (e.g. `assets/bracket.brp`) */
+    assets: Record<string, Uint8Array>;
+    /** producer-defined members (spec §3, e.g. `mapping.json`, `freecad/**`), written as-is */
+    producerMembers?: Record<string, Uint8Array>;
+}
+/** Result of `writeContainer`. */
+export interface WriteContainerResult {
+    /** the assembled container bytes */
+    bytes: Uint8Array;
+    /** the manifest that was serialized into the container */
+    manifest: ContainerManifest;
+}
+/**
+ * Build and validate the container manifest — the single implementation of the
+ * §4 schema.
+ *
+ * Structural only: it cannot check that `models[].entry` and `models[].data`
+ * resolve to emitted members, because it never sees the members. That is
+ * `writeContainer`'s job, and it is why conversion pipelines that legitimately
+ * assemble a container in two passes can still reuse this function.
+ *
+ * @param input the model list, the optional active id and display metadata
+ * @returns the manifest, with `format: 3` and `units: "mm"` fixed
+ * @throws when `models` is empty, an id/entry is empty, unsafe or duplicated,
+ *   an `entry` is not a module path under `model/` ending with `.fai.js`, a
+ *   `data` is not a JSON path under `data/`, or `active` names no model
+ */
+export declare function createManifest(input: Pick<ContainerAssembly, 'models' | 'active' | 'meta'>): ContainerManifest;
+/**
+ * Assemble a container from an assembly, enforcing spec §10 before writing any
+ * bytes.
+ *
+ * Enforced (each throws, never silently produces an unreconstructable
+ * container):
+ * 1. `models` is non-empty, ids and entries are unique (`createManifest`);
+ * 2. every `models[].entry` is emitted in `modules`;
+ * 3. every `models[].data` is emitted in `dataMembers`;
+ * 4. `active`, when present, equals some `models[].id` (`createManifest`);
+ * 5. asset keys are unique across `files/**`, `assets/**` and any
+ *    producer-defined member in those namespaces (spec §7.1) — a fileId that
+ *    would not survive the base-name key rule is an error, not a silent rename;
+ * 6. every `entry`/`data`/module/asset path is a safe relative member path in
+ *    its namespace, and no path is emitted twice.
+ *
+ * @param assembly the assembly input (§3.4)
+ * @returns the container bytes and the manifest that was written
+ * @throws when any of the obligations above is violated
+ */
+export declare function writeContainer(assembly: ContainerAssembly): WriteContainerResult;
+//# sourceMappingURL=container-write.d.ts.map

package/dist/io/fai-zip/container-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-write.d.ts","sourceRoot":"","sources":["../../../src/io/fai-zip/container-write.ts"],"names":[],"mappings":"AAgBA,OAAO,EAML,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAA;AAEpB,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mEAAmE;IACnE,IAAI,CAAC,EAAE;QACL,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,MAAM,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAA;KACrC,CAAA;IACD,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACjC,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAClC,2FAA2F;IAC3F,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;CAC7C;AAED,kCAAkC;AAClC,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,KAAK,EAAE,UAAU,CAAA;IACjB,0DAA0D;IAC1D,QAAQ,EAAE,iBAAiB,CAAA;CAC5B;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC,GAAG,iBAAiB,CAoD9G;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,oBAAoB,CAuFhF"}

package/dist/io/fai-zip/container-write.js

@@ -0,0 +1,186 @@
+/**
+ * Unified `.fai.zip` write API (docs/fai-zip-format.md §10, Writer obligations).
+ *
+ * The input is an *assembly* — pure format concepts plus opaque
+ * producer-defined members (§3). Nothing here knows about FCStd, editors or
+ * filesystems.
+ *
+ * Environment-independent: ZIP bytes go through `io/zip.ts`, text goes through
+ * the UTF-8 codec in `./container.js`. No `node:*`, no fflate, no fs.
+ *
+ * The point of this layer is that a container which a reader cannot
+ * reconstruct is never produced: every §10 obligation that can be checked
+ * statically is checked here and throws. A thrown error is always preferable
+ * to a container with a dangling reference (spec §10.7, fail loudly).
+ */
+import { writeZipEntries } from '../zip.js';
+import { assetKeyOf, assertDataMemberPath, assertModelMemberPath, assertSafeMemberPath, encodeMemberText, } from './container.js';
+const FILES_PREFIX = 'files/';
+const ASSETS_PREFIX = 'assets/';
+/**
+ * Build and validate the container manifest — the single implementation of the
+ * §4 schema.
+ *
+ * Structural only: it cannot check that `models[].entry` and `models[].data`
+ * resolve to emitted members, because it never sees the members. That is
+ * `writeContainer`'s job, and it is why conversion pipelines that legitimately
+ * assemble a container in two passes can still reuse this function.
+ *
+ * @param input the model list, the optional active id and display metadata
+ * @returns the manifest, with `format: 3` and `units: "mm"` fixed
+ * @throws when `models` is empty, an id/entry is empty, unsafe or duplicated,
+ *   an `entry` is not a module path under `model/` ending with `.fai.js`, a
+ *   `data` is not a JSON path under `data/`, or `active` names no model
+ */
+export function createManifest(input) {
+    const { models, active, meta = {} } = input;
+    if (!Array.isArray(models) || models.length === 0) {
+        throw new Error('[fai-zip] createManifest: models must be a non-empty array');
+    }
+    const seenIds = new Set();
+    const seenEntries = new Set();
+    const normalized = [];
+    for (let i = 0; i < models.length; i++) {
+        const m = models[i];
+        const id = typeof m.id === 'string' ? m.id : '';
+        if (id === '')
+            throw new Error(`[fai-zip] createManifest: models[${i}].id must be a non-empty string`);
+        if (id.includes('/') || id.includes('\\')) {
+            throw new Error(`[fai-zip] createManifest: models[${i}].id must not contain "/" or "\\": "${id}"`);
+        }
+        if (seenIds.has(id))
+            throw new Error(`[fai-zip] createManifest: models[].id must be unique: "${id}"`);
+        seenIds.add(id);
+        if (typeof m.entry !== 'string' || m.entry === '') {
+            throw new Error(`[fai-zip] createManifest: models[${i}].entry must be a non-empty string`);
+        }
+        assertModelMemberPath(m.entry, `createManifest: models[${i}].entry`);
+        if (seenEntries.has(m.entry)) {
+            throw new Error(`[fai-zip] createManifest: models[].entry must be unique: "${m.entry}"`);
+        }
+        seenEntries.add(m.entry);
+        if (m.data !== undefined)
+            assertDataMemberPath(m.data, `createManifest: models[${i}].data`);
+        normalized.push({
+            id,
+            entry: m.entry,
+            ...(m.label !== undefined ? { label: m.label } : {}),
+            ...(m.data !== undefined ? { data: m.data } : {}),
+        });
+    }
+    if (active !== undefined && !seenIds.has(active)) {
+        throw new Error(`[fai-zip] createManifest: active must equal some models[].id: "${active}"`);
+    }
+    return {
+        format: 3,
+        units: 'mm',
+        models: normalized,
+        ...(active !== undefined ? { active } : {}),
+        ...(meta.createdAt !== undefined ? { createdAt: meta.createdAt } : {}),
+        ...(meta.appVersion !== undefined ? { appVersion: meta.appVersion } : {}),
+        ...(meta.label !== undefined ? { label: meta.label } : {}),
+        ...(meta.source !== undefined ? { source: meta.source } : {}),
+    };
+}
+/**
+ * Assemble a container from an assembly, enforcing spec §10 before writing any
+ * bytes.
+ *
+ * Enforced (each throws, never silently produces an unreconstructable
+ * container):
+ * 1. `models` is non-empty, ids and entries are unique (`createManifest`);
+ * 2. every `models[].entry` is emitted in `modules`;
+ * 3. every `models[].data` is emitted in `dataMembers`;
+ * 4. `active`, when present, equals some `models[].id` (`createManifest`);
+ * 5. asset keys are unique across `files/**`, `assets/**` and any
+ *    producer-defined member in those namespaces (spec §7.1) — a fileId that
+ *    would not survive the base-name key rule is an error, not a silent rename;
+ * 6. every `entry`/`data`/module/asset path is a safe relative member path in
+ *    its namespace, and no path is emitted twice.
+ *
+ * @param assembly the assembly input (§3.4)
+ * @returns the container bytes and the manifest that was written
+ * @throws when any of the obligations above is violated
+ */
+export function writeContainer(assembly) {
+    const { modules, dataMembers, files, assets, producerMembers = {} } = assembly;
+    const manifest = createManifest(assembly);
+    const members = new Map();
+    const claimedKeys = new Map();
+    /** Record an asset key; a second member claiming it is an error (spec §7.1). */
+    const claim = (key, path) => {
+        const prev = claimedKeys.get(key);
+        if (prev !== undefined) {
+            throw new Error(`[fai-zip] writeContainer: duplicate asset key "${key}" (members "${prev}" and "${path}")`);
+        }
+        claimedKeys.set(key, path);
+    };
+    /** Add one member; a duplicate member path is an error. */
+    const put = (path, body) => {
+        if (members.has(path)) {
+            throw new Error(`[fai-zip] writeContainer: duplicate member path "${path}"`);
+        }
+        members.set(path, body);
+    };
+    // manifest.json — always first, always present (spec §10.1)
+    put('manifest.json', encodeMemberText(JSON.stringify(manifest, null, 2)));
+    // model/** — every declared entry must be delivered (spec §10.2, §10.3)
+    for (const [path, source] of Object.entries(modules)) {
+        assertModelMemberPath(path, 'writeContainer: modules key');
+        put(path, encodeMemberText(source));
+    }
+    for (const m of manifest.models) {
+        if (!members.has(m.entry)) {
+            throw new Error(`[fai-zip] writeContainer: models[].entry "${m.entry}" has no module in the assembly`);
+        }
+    }
+    // data/** — a declared data member must be delivered, and must be JSON (spec §6.1)
+    for (const [path, json] of Object.entries(dataMembers)) {
+        assertDataMemberPath(path, 'writeContainer: dataMembers key');
+        try {
+            JSON.parse(json);
+        }
+        catch (e) {
+            throw new Error(`[fai-zip] writeContainer: data member "${path}" is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+        put(path, encodeMemberText(json));
+    }
+    for (const m of manifest.models) {
+        if (m.data !== undefined && !members.has(m.data)) {
+            throw new Error(`[fai-zip] writeContainer: models[].data "${m.data}" has no member in the assembly`);
+        }
+    }
+    // files/** — keyed by fileId, stored as files/<fileId>.bin so the key
+    // round-trips through the base-name rule (spec §7). A fileId containing a
+    // separator would be silently re-keyed on read, so it is rejected here.
+    for (const [fileId, body] of Object.entries(files)) {
+        if (fileId === '' || fileId.includes('/') || fileId.includes('\\')) {
+            throw new Error(`[fai-zip] writeContainer: fileId must be a non-empty base name without separators: "${fileId}"`);
+        }
+        const path = `${FILES_PREFIX}${fileId}.bin`;
+        put(path, body);
+        claim(assetKeyOf(path, FILES_PREFIX), path);
+    }
+    // assets/** — the key is the base name, so two paths may collide (spec §7.1)
+    for (const [path, body] of Object.entries(assets)) {
+        assertSafeMemberPath(path, 'writeContainer: assets key');
+        if (!path.startsWith(ASSETS_PREFIX)) {
+            throw new Error(`[fai-zip] writeContainer: assets key must be under assets/: "${path}"`);
+        }
+        put(path, body);
+        claim(assetKeyOf(path, ASSETS_PREFIX), path);
+    }
+    // producer-defined members (spec §3) — opaque payload, but they still live
+    // in the archive, so a member dropped under files//assets/ takes part in the
+    // key uniqueness rule whether or not the producer thought of it that way.
+    for (const [path, body] of Object.entries(producerMembers)) {
+        assertSafeMemberPath(path, 'writeContainer: producerMembers key');
+        put(path, body);
+        if (path.startsWith(FILES_PREFIX))
+            claim(assetKeyOf(path, FILES_PREFIX), path);
+        else if (path.startsWith(ASSETS_PREFIX))
+            claim(assetKeyOf(path, ASSETS_PREFIX), path);
+    }
+    return { bytes: writeZipEntries(Object.fromEntries(members)), manifest };
+}
+//# sourceMappingURL=container-write.js.map