@ifc-lite/bcf 2.0.0 → 3.0.0

package/dist/writer-camera.js

@@ -0,0 +1,131 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { xsdDouble, xsdPointElement } from './numeric.js';
+/**
+ * Enforce each version's rule for how many cameras a viewpoint may carry.
+ *
+ * The two schemas differ, and the emitted ORDER matters in one of them:
+ *
+ * - v2_1/visinfo.xsd puts `OrthogonalCamera` and `PerspectiveCamera` in
+ *   `VisualizationInfo`'s `xs:sequence`, both `minOccurs="0"`. Either, both or
+ *   neither may appear -- but an `xs:sequence` fixes the order, and the
+ *   schema declares the orthogonal camera FIRST. Emitting the perspective
+ *   camera first made a two-camera 2.1 viewpoint schema-invalid
+ *   ("Element 'OrthogonalCamera': This element is not expected"), which is
+ *   why `writer.ts`'s `writeViewpointFiles` now writes orthogonal first for both
+ *   versions -- the order is required by 2.1 and harmless under 3.0's choice.
+ * - v3_0/visinfo.xsd replaced that pair with an `<xs:choice>` carrying no
+ *   `minOccurs` and no `maxOccurs`, so both default to 1: EXACTLY ONE camera,
+ *   and it is required. Two cameras and zero cameras are each invalid there.
+ *
+ * We refuse the 3.0 violations rather than guessing which camera the caller
+ * meant, or inventing one for a viewpoint that has none -- same policy as
+ * {@link requireAspectRatioElement} and the `Topic/@TopicType` checks in
+ * `writer.ts`'s `writeMarkupFile`. Silently dropping one of two cameras would discard
+ * a view the caller chose; silently emitting neither writes an archive that no
+ * conforming BCF 3.0 reader has to accept.
+ */
+export function requireCameraChoice(viewpoint, version) {
+    if (version !== '3.0')
+        return;
+    const count = (viewpoint.orthogonalCamera ? 1 : 0) + (viewpoint.perspectiveCamera ? 1 : 0);
+    if (count === 1)
+        return;
+    throw new Error(`BCF 3.0 requires exactly one camera per viewpoint (viewpoint "${viewpoint.guid}" has ` +
+        `${count === 0 ? 'none' : 'both an orthogonalCamera and a perspectiveCamera'}). ` +
+        `visinfo.xsd declares OrthogonalCamera and PerspectiveCamera as an xs:choice, so ` +
+        `set exactly one before writing a 3.0 file.`);
+}
+/**
+ * Require a FINITE, positive AspectRatio for a BCF 3.0 camera and return the
+ * element to append.
+ *
+ * v3_0/visinfo.xsd adds `<AspectRatio>` (type `PositiveDouble`, i.e.
+ * `xs:double` with `minExclusive value="0"`) as a REQUIRED, no-minOccurs
+ * child of both `OrthogonalCamera` and `PerspectiveCamera`. 2.1 has no such
+ * element. We refuse to invent a value (there is no safe default aspect
+ * ratio) because that would assert a value the caller never chose; instead
+ * we fail the write so the caller supplies one -- same policy as the
+ * `Topic/@TopicType`/`Topic/@TopicStatus` checks in `writer.ts`'s `writeMarkupFile`.
+ *
+ * BOTH halves of `PositiveDouble` are checked here, and the positivity test
+ * alone did not cover them: `Infinity > 0` is `true`, so `Infinity` walked
+ * past this guard and was emitted as `<AspectRatio>Infinity</AspectRatio>`,
+ * which xmllint rejects with "'Infinity' is not a valid value of the atomic
+ * type 'PositiveDouble'". `xsdDouble` is what makes the `xs:double` half of
+ * the claim true; the `> 0` below is the `minExclusive` facet.
+ */
+function requireAspectRatioElement(aspectRatio, viewpointGuid) {
+    const where = `viewpoint "${viewpointGuid}"`;
+    if (aspectRatio === undefined || !(aspectRatio > 0)) {
+        throw new Error(`BCF 3.0 requires a positive Camera/AspectRatio (${where} has ` +
+            `${aspectRatio === undefined ? 'none' : aspectRatio}). ` +
+            `Set the camera's aspectRatio before writing a 3.0 file.`);
+    }
+    return `\n    <AspectRatio>${xsdDouble(aspectRatio, 'Camera/AspectRatio', where)}</AspectRatio>`;
+}
+/**
+ * Require a FINITE FieldOfView within BCF 3.0's `(0, 180)` exclusive facet and
+ * return the text `xsdDouble` will accept for it.
+ *
+ * v3_0/visinfo.xsd's `FieldOfView` simpleType is `xs:double` with
+ * `minExclusive value="0"` and `maxExclusive value="180"`. `xsdDouble` alone
+ * only rejects non-finite values (Infinity/-Infinity/NaN); it says nothing
+ * about a finite value that is merely out of range, so `0`, a negative number,
+ * or `180` and above walked straight through it and were emitted as-is --
+ * schema-invalid the same way an unset `AspectRatio` was before
+ * {@link requireAspectRatioElement} started refusing it. 2.1's own
+ * `FieldOfView` facet (`[45, 60]` inclusive) is deliberately NOT enforced
+ * here: its own schema annotation says "This limitation will be dropped in
+ * the next release and viewers should expect values outside this range in
+ * current implementations", so treating it as a hard constraint would reject
+ * legitimate 2.1 input the schema authors themselves disclaim.
+ */
+function requireFieldOfViewElement(fieldOfView, viewpointGuid) {
+    const where = `viewpoint "${viewpointGuid}"`;
+    if (!(fieldOfView > 0 && fieldOfView < 180)) {
+        throw new Error(`BCF 3.0 requires PerspectiveCamera/FieldOfView in (0, 180) exclusive (${where} has ` +
+            `${fieldOfView}). visinfo.xsd's FieldOfView simpleType declares minExclusive="0" and ` +
+            `maxExclusive="180"; set a value inside that range before writing a 3.0 file.`);
+    }
+    return xsdDouble(fieldOfView, 'PerspectiveCamera/FieldOfView', where);
+}
+/**
+ * Write perspective camera XML
+ */
+export function writePerspectiveCamera(camera, version, viewpointGuid) {
+    const aspectRatioElement = version === '3.0' ? requireAspectRatioElement(camera.aspectRatio, viewpointGuid) : '';
+    const where = `viewpoint "${viewpointGuid}"`;
+    const fieldOfView = version === '3.0'
+        ? requireFieldOfViewElement(camera.fieldOfView, viewpointGuid)
+        : xsdDouble(camera.fieldOfView, 'PerspectiveCamera/FieldOfView', where);
+    return `\n  <PerspectiveCamera>${cameraVectors(camera, where)}
+    <FieldOfView>${fieldOfView}</FieldOfView>${aspectRatioElement}
+  </PerspectiveCamera>`;
+}
+/**
+ * Write orthogonal camera XML
+ */
+export function writeOrthogonalCamera(camera, version, viewpointGuid) {
+    const aspectRatioElement = version === '3.0' ? requireAspectRatioElement(camera.aspectRatio, viewpointGuid) : '';
+    const where = `viewpoint "${viewpointGuid}"`;
+    return `\n  <OrthogonalCamera>${cameraVectors(camera, where)}
+    <ViewToWorldScale>${xsdDouble(camera.viewToWorldScale, 'OrthogonalCamera/ViewToWorldScale', where)}</ViewToWorldScale>${aspectRatioElement}
+  </OrthogonalCamera>`;
+}
+/**
+ * The three vectors both camera types open with, in the order both schemas'
+ * `xs:sequence` declares them.
+ *
+ * Identical in `OrthogonalCamera` and `PerspectiveCamera` and in 2.1 and 3.0 --
+ * the cameras differ only in the single element that follows (`ViewToWorldScale`
+ * vs `FieldOfView`). Writing them once is what makes "every camera coordinate
+ * is checked" a property of the code rather than of six copied templates.
+ */
+function cameraVectors(camera, where) {
+    return (xsdPointElement('CameraViewPoint', camera.cameraViewPoint, '    ', where) +
+        xsdPointElement('CameraDirection', camera.cameraDirection, '    ', where) +
+        xsdPointElement('CameraUpVector', camera.cameraUpVector, '    ', where));
+}
+//# sourceMappingURL=writer-camera.js.map

package/dist/writer-camera.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-camera.js","sourceRoot":"","sources":["../src/writer-camera.ts"],"names":[],"mappings":"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"}

package/dist/writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../src/writer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,UAAU,EAmBX,MAAM,YAAY,CAAC;AAGpB;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBjE"}
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../src/writer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,UAAU,EAiBX,MAAM,YAAY,CAAC;AAgBpB;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBjE"}

package/dist/writer.js

@@ -7,7 +7,11 @@
  * Creates .bcfzip files from BCFProject structure
  */
 import JSZip from 'jszip';
-import { generateUuid } from '@ifc-lite/encoding';
+import { requireCameraChoice, writeOrthogonalCamera, writePerspectiveCamera, } from './writer-camera.js';
+import { xsdDouble, xsdInt, xsdPointElement } from './numeric.js';
+import { escapeXml } from './xml-text.js';
+import { XML_WHITESPACE_ONLY, xsdDateTime, xsdOptionalDateTime, xsdRequiredString, } from './xsd-required-string.js';
+import { generateUuid, uuidFromSeed } from '@ifc-lite/encoding';
 /**
  * Write a BCFProject to a .bcfzip file
  *
@@ -63,21 +67,34 @@ function writeVersionFile(zip, version) {
  * Uses buildingSMART standard format
  *
  * The root element is renamed between versions: 2.1's project.xsd declares
- * root element `<ProjectExtension>` (and requires a following
- * `<ExtensionSchema>` sibling of `<Project>`, which we deliberately do not
- * emit -- out of scope here); 3.0's project.xsd instead declares root
+ * root element `<ProjectExtension>` as the sequence `Project?`,
+ * `ExtensionSchema` -- where `ExtensionSchema` is an `xs:anyURI` with no
+ * `minOccurs`, so it is REQUIRED; 3.0's project.xsd instead declares root
  * element `<ProjectInfo>` containing just a required `<Project>`, and has no
  * `ProjectExtension`/`ExtensionSchema` concept at all. The inner
  * `<Project ProjectId="...">`/`<Name>` shape is unchanged between versions.
+ *
+ * `<ExtensionSchema>` used to be omitted entirely, which made `project.bcfp`
+ * fail 2.1 validation ("Element 'ProjectExtension': Missing child element(s).
+ * Expected is ( ExtensionSchema )") in EVERY 2.1 archive this package writes
+ * -- 2.1 is the default version and `createBCFProject` always sets a project
+ * id, so the file is always present. It is now emitted empty. An empty
+ * `xs:anyURI` is a valid instance of the type (verified against the vendored
+ * schema), and it is the honest value here: this writer ships no
+ * `extensions.xsd`, and `BCFProject.extensions` is not serialized, so there is
+ * no extension schema to point at. Naming a file we do not write would trade
+ * the schema error for a dangling reference; omitting the element keeps the
+ * schema error. Empty does neither.
  */
 function writeProjectFile(zip, project, version) {
     const projectId = project.projectId || generateUuid();
     const nameElement = project.name ? `\n    <Name>${escapeXml(project.name)}</Name>` : '';
     const rootElement = version === '3.0' ? 'ProjectInfo' : 'ProjectExtension';
+    const extensionSchema = version === '3.0' ? '' : '\n  <ExtensionSchema/>';
     const content = `<?xml version="1.0" encoding="UTF-8"?>
 <${rootElement} xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
-  <Project ProjectId="${projectId}">${nameElement}
-  </Project>
+  <Project ProjectId="${escapeXml(projectId)}">${nameElement}
+  </Project>${extensionSchema}
 </${rootElement}>`;
     zip.file('project.bcfp', content);
 }
@@ -90,33 +107,18 @@ function shortGuidHash(guid) {
     }
     return h.toString(16).padStart(8, '0');
 }
-/**
- * Sanitize a topic GUID for use as a zip folder name (zip-slip guard).
- *
- * A topic GUID is parsed unvalidated from untrusted markup XML on read, so it
- * can carry path separators or `..`. Using it verbatim as a zip path component
- * on a read-modify-save would let a crafted GUID (`../../evil`) write outside
- * the archive root. Restrict the name to safe filename characters and collapse
- * any dot-run so it can never traverse. The real GUID is still written verbatim
- * as the markup `<Topic Guid>` attribute, which is what readers key off.
- *
- * Sanitization is lossy, so two distinct GUIDs can map to one name (`a?b` and
- * `a:b` both give `a_b`), which would silently overwrite a topic folder. Any
- * name that sanitization changed gets a hash of the original GUID appended,
- * and `usedNames` catches the remaining collisions with a counter suffix.
- */
-function sanitizeTopicFolderName(guid, usedNames) {
-    return sanitizeZipComponent(guid, usedNames, 'topic');
-}
 /**
  * Sanitize an arbitrary GUID for use as a zip path component (zip-slip guard).
  *
  * Shared by both the topic-folder name and the viewpoint file base name: a
  * viewpoint GUID is parsed just as unvalidated from untrusted markup XML on
  * read (reader.ts `parseViewpointContent`) as a topic GUID is, so it carries
- * the same path-traversal hazard. Restrict the name to safe filename
- * characters and collapse any dot-run so it can never traverse. `fallback` is
- * used when sanitization strips the name to nothing.
+ * the same path-traversal hazard (`../../evil` as a topic GUID would write
+ * outside the archive root). Restrict the name to safe filename characters and
+ * collapse any dot-run so it can never traverse. `fallback` is used when
+ * sanitization strips the name to nothing. The real GUID is still written
+ * verbatim as the markup `<Topic Guid>`/`<Viewpoint Guid>` attribute, which is
+ * what readers key off.
  *
  * Sanitization is lossy, so two distinct GUIDs can map to one name, which
  * would silently overwrite an entry. Any name that sanitization changed gets
@@ -139,13 +141,10 @@ function sanitizeZipComponent(raw, usedNames, fallback) {
     usedNames.add(candidate);
     return candidate;
 }
-/**
- * Write a topic folder with all its contents
- */
+/** Write a topic folder with all its contents. */
 async function writeTopicFolder(zip, topic, version, usedFolderNames) {
-    const folder = zip.folder(sanitizeTopicFolderName(topic.guid, usedFolderNames));
-    if (!folder)
-        return;
+    // Every entry below passes createFolders:false: JSZip otherwise adds a "<guid>/" directory entry, which Solibri refuses (#3612).
+    const folderName = sanitizeZipComponent(topic.guid, usedFolderNames, 'topic');
     // Sanitize each viewpoint GUID once, up front, so the markup <Viewpoint>
     // reference (written below) and the zip entry (written in
     // writeViewpointFiles) always agree on the same file name. A topic-scoped
@@ -154,10 +153,10 @@ async function writeTopicFolder(zip, topic, version, usedFolderNames) {
     const usedViewpointNames = new Set();
     const viewpointBaseNames = topic.viewpoints.map((vp) => sanitizeZipComponent(vp.guid, usedViewpointNames, 'viewpoint'));
     // Write markup.bcf
-    writeMarkupFile(folder, topic, version, viewpointBaseNames);
+    writeMarkupFile(zip, folderName, topic, version, viewpointBaseNames);
     // Write viewpoints
     for (let i = 0; i < topic.viewpoints.length; i++) {
-        await writeViewpointFiles(folder, topic.viewpoints[i], viewpointBaseNames[i], version);
+        await writeViewpointFiles(zip, folderName, topic.viewpoints[i], viewpointBaseNames[i], version);
     }
 }
 /**
@@ -173,17 +172,8 @@ function snapshotExt(viewpoint) {
     }
     return 'png';
 }
-/**
- * Write markup.bcf file
- * Uses buildingSMART standard format
- */
-// BCF 3.0's markup.xsd types `Topic/@TopicType` and `Topic/@TopicStatus` as
-// `NonEmptyOrBlankString`: after XML whitespace (#x9, #xA, #xD, #x20) is
-// collapsed, the value must have length >= 1. A value that is present but
-// consists entirely of XML whitespace collapses to nothing and is therefore
-// as invalid as an absent one.
-const XML_WHITESPACE_ONLY = /^[\t\n\r ]*$/;
-function writeMarkupFile(folder, topic, version, viewpointBaseNames) {
+/** Write markup.bcf -- buildingSMART standard format. */
+function writeMarkupFile(zip, folderName, topic, version, viewpointBaseNames) {
     // BCF 3.0's markup.xsd tightens `Topic/@TopicType` and `Topic/@TopicStatus`
     // from optional (2.1) to `use="required"`. Omitting the attribute -
     // which is what 2.1 output does when the value is unset - produces
@@ -229,7 +219,8 @@ function writeMarkupFile(folder, topic, version, viewpointBaseNames) {
         content += `\n    <Priority>${escapeXml(topic.priority)}</Priority>`;
     }
     if (topic.index !== undefined) {
-        content += `\n    <Index>${topic.index}</Index>`;
+        // `Index` is the writer's only xs:int; see xsdInt for what that excludes.
+        content += `\n    <Index>${xsdInt(topic.index, 'Topic/Index', `topic "${topic.guid}"`)}</Index>`;
     }
     if (topic.labels && topic.labels.length > 0) {
         // BCF 3.0's markup.xsd wraps labels in ONE `<Labels>` container holding
@@ -251,16 +242,18 @@ function writeMarkupFile(folder, topic, version, viewpointBaseNames) {
             }
         }
     }
-    content += `\n    <CreationDate>${escapeXml(topic.creationDate)}</CreationDate>`;
-    content += `\n    <CreationAuthor>${escapeXml(topic.creationAuthor)}</CreationAuthor>`;
-    if (topic.modifiedDate) {
-        content += `\n    <ModifiedDate>${escapeXml(topic.modifiedDate)}</ModifiedDate>`;
+    content += `\n    <CreationDate>${xsdDateTime(topic.creationDate, 'Topic/CreationDate', `topic "${topic.guid}"`)}</CreationDate>`;
+    content += `\n    <CreationAuthor>${xsdRequiredString(topic.creationAuthor, 'Topic/CreationAuthor', `topic "${topic.guid}"`, version)}</CreationAuthor>`;
+    const topicModifiedDate = xsdOptionalDateTime(topic.modifiedDate);
+    if (topicModifiedDate) {
+        content += `\n    <ModifiedDate>${topicModifiedDate}</ModifiedDate>`;
         // BCF spec requires ModifiedAuthor when ModifiedDate is present
         const modifiedAuthor = topic.modifiedAuthor || topic.creationAuthor;
-        content += `\n    <ModifiedAuthor>${escapeXml(modifiedAuthor)}</ModifiedAuthor>`;
+        content += `\n    <ModifiedAuthor>${xsdRequiredString(modifiedAuthor, 'Topic/ModifiedAuthor', `topic "${topic.guid}"`, version)}</ModifiedAuthor>`;
     }
-    if (topic.dueDate) {
-        content += `\n    <DueDate>${escapeXml(topic.dueDate)}</DueDate>`;
+    const dueDate = xsdOptionalDateTime(topic.dueDate);
+    if (dueDate) {
+        content += `\n    <DueDate>${dueDate}</DueDate>`;
     }
     if (topic.assignedTo) {
         content += `\n    <AssignedTo>${escapeXml(topic.assignedTo)}</AssignedTo>`;
@@ -283,8 +276,8 @@ function writeMarkupFile(folder, topic, version, viewpointBaseNames) {
         // directly under <Topic> (buildingSMART/BCF-XML markup.xsd, Topic).
         if (version === '3.0')
             content += `\n    <DocumentReferences>`;
-        for (const docRef of topic.documentReferences) {
-            content += writeDocumentReference(docRef, version);
+        for (let i = 0; i < topic.documentReferences.length; i++) {
+            content += writeDocumentReference(topic.documentReferences[i], version, topic.guid, i);
         }
         if (version === '3.0')
             content += `\n    </DocumentReferences>`;
@@ -308,14 +301,15 @@ function writeMarkupFile(folder, topic, version, viewpointBaseNames) {
     const commentXml = (indent) => topic.comments
         .map((comment) => {
         let c = `\n${indent}<Comment Guid="${escapeXml(comment.guid)}">`;
-        c += `\n${indent}  <Date>${escapeXml(comment.date)}</Date>`;
-        c += `\n${indent}  <Author>${escapeXml(comment.author)}</Author>`;
+        c += `\n${indent}  <Date>${xsdDateTime(comment.date, 'Comment/Date', `comment "${comment.guid}"`)}</Date>`;
+        c += `\n${indent}  <Author>${xsdRequiredString(comment.author, 'Comment/Author', `comment "${comment.guid}"`, version)}</Author>`;
         c += `\n${indent}  <Comment>${escapeXml(comment.comment)}</Comment>`;
         if (comment.viewpointGuid) {
             c += `\n${indent}  <Viewpoint Guid="${escapeXml(comment.viewpointGuid)}"/>`;
         }
-        if (comment.modifiedDate) {
-            c += `\n${indent}  <ModifiedDate>${escapeXml(comment.modifiedDate)}</ModifiedDate>`;
+        const commentModifiedDate = xsdOptionalDateTime(comment.modifiedDate);
+        if (commentModifiedDate) {
+            c += `\n${indent}  <ModifiedDate>${commentModifiedDate}</ModifiedDate>`;
         }
         if (comment.modifiedAuthor) {
             c += `\n${indent}  <ModifiedAuthor>${escapeXml(comment.modifiedAuthor)}</ModifiedAuthor>`;
@@ -375,12 +369,12 @@ function writeMarkupFile(folder, topic, version, viewpointBaseNames) {
         content += viewpointXml('  ');
     }
     content += `\n</Markup>`;
-    folder.file('markup.bcf', content);
+    zip.file(`${folderName}/markup.bcf`, content, { createFolders: false });
 }
 /**
  * Write viewpoint files (bcfv and snapshot)
  */
-async function writeViewpointFiles(folder, viewpoint, baseName, version) {
+async function writeViewpointFiles(zip, folderName, viewpoint, baseName, version) {
     // Use standard buildingSMART naming convention: Viewpoint_<guid>.bcfv, but
     // the file name component is the sanitized base name (zip-slip guard) --
     // the SAME one the caller wrote into the markup <Viewpoint> reference, so
@@ -394,19 +388,24 @@ async function writeViewpointFiles(folder, viewpoint, baseName, version) {
     if (viewpoint.components) {
         content += writeComponents(viewpoint.components, version);
     }
-    // Write perspective camera
-    if (viewpoint.perspectiveCamera) {
-        content += writePerspectiveCamera(viewpoint.perspectiveCamera, version, viewpoint.guid);
-    }
-    // Write orthogonal camera
+    // Every number below reaches an XSD numeric type, so each goes through
+    // `numeric.ts`'s write-side guards; `where` is what puts the offending
+    // viewpoint's guid in the error, as the camera checks already do.
+    const where = `viewpoint "${viewpoint.guid}"`;
+    // Write the cameras. ORTHOGONAL FIRST -- see requireCameraChoice for why the
+    // order is not free, and for the 3.0 cardinality rule enforced here.
+    requireCameraChoice(viewpoint, version);
     if (viewpoint.orthogonalCamera) {
         content += writeOrthogonalCamera(viewpoint.orthogonalCamera, version, viewpoint.guid);
     }
+    if (viewpoint.perspectiveCamera) {
+        content += writePerspectiveCamera(viewpoint.perspectiveCamera, version, viewpoint.guid);
+    }
     // Write lines
     if (viewpoint.lines && viewpoint.lines.length > 0) {
         content += `\n  <Lines>`;
         for (const line of viewpoint.lines) {
-            content += writeLine(line);
+            content += writeLine(line, where);
         }
         content += `\n  </Lines>`;
     }
@@ -414,7 +413,7 @@ async function writeViewpointFiles(folder, viewpoint, baseName, version) {
     if (viewpoint.clippingPlanes && viewpoint.clippingPlanes.length > 0) {
         content += `\n  <ClippingPlanes>`;
         for (const plane of viewpoint.clippingPlanes) {
-            content += writeClippingPlane(plane);
+            content += writeClippingPlane(plane, where);
         }
         content += `\n  </ClippingPlanes>`;
     }
@@ -430,21 +429,21 @@ async function writeViewpointFiles(folder, viewpoint, baseName, version) {
         if (version === '3.0') {
             content += `\n  <Bitmaps>`;
             for (const bitmap of viewpoint.bitmaps) {
-                content += writeBitmap(bitmap, version);
+                content += writeBitmap(bitmap, version, where);
             }
             content += `\n  </Bitmaps>`;
         }
         else {
             for (const bitmap of viewpoint.bitmaps) {
-                content += writeBitmap(bitmap, version);
+                content += writeBitmap(bitmap, version, where);
             }
         }
     }
     content += `\n</VisualizationInfo>`;
-    folder.file(filename, content);
+    zip.file(`${folderName}/${filename}`, content, { createFolders: false });
     // Write snapshot
     if (viewpoint.snapshotData) {
-        folder.file(snapshotName, viewpoint.snapshotData);
+        zip.file(`${folderName}/${snapshotName}`, viewpoint.snapshotData, { createFolders: false });
     }
     else if (viewpoint.snapshot && viewpoint.snapshot.startsWith('data:')) {
         // Convert data URL to binary
@@ -456,7 +455,7 @@ async function writeViewpointFiles(folder, viewpoint, baseName, version) {
                 for (let i = 0; i < binaryString.length; i++) {
                     bytes[i] = binaryString.charCodeAt(i);
                 }
-                folder.file(snapshotName, bytes);
+                zip.file(`${folderName}/${snapshotName}`, bytes, { createFolders: false });
             }
             catch (e) {
                 // Skip a single malformed snapshot data URL rather than aborting the export
@@ -600,105 +599,18 @@ function writeColoringEntry(coloring, version) {
     content += `\n      </Color>`;
     return content;
 }
-/**
- * Require a positive AspectRatio for a BCF 3.0 camera and return the element
- * to append.
- *
- * v3_0/visinfo.xsd adds `<AspectRatio>` (type `PositiveDouble`, i.e.
- * `xs:double` with `minExclusive value="0"`) as a REQUIRED, no-minOccurs
- * child of both `OrthogonalCamera` and `PerspectiveCamera`. 2.1 has no such
- * element. We refuse to invent a value (there is no safe default aspect
- * ratio) because that would assert a value the caller never chose; instead
- * we fail the write so the caller supplies one -- same policy as the
- * `Topic/@TopicType`/`Topic/@TopicStatus` checks in {@link writeMarkupFile}.
- */
-function requireAspectRatioElement(aspectRatio, viewpointGuid) {
-    if (aspectRatio === undefined || !(aspectRatio > 0)) {
-        throw new Error(`BCF 3.0 requires a positive Camera/AspectRatio (viewpoint "${viewpointGuid}" has none). ` +
-            `Set the camera's aspectRatio before writing a 3.0 file.`);
-    }
-    return `\n    <AspectRatio>${aspectRatio}</AspectRatio>`;
-}
-/**
- * Write perspective camera XML
- */
-function writePerspectiveCamera(camera, version, viewpointGuid) {
-    const aspectRatioElement = version === '3.0' ? requireAspectRatioElement(camera.aspectRatio, viewpointGuid) : '';
-    return `\n  <PerspectiveCamera>
-    <CameraViewPoint>
-      <X>${camera.cameraViewPoint.x}</X>
-      <Y>${camera.cameraViewPoint.y}</Y>
-      <Z>${camera.cameraViewPoint.z}</Z>
-    </CameraViewPoint>
-    <CameraDirection>
-      <X>${camera.cameraDirection.x}</X>
-      <Y>${camera.cameraDirection.y}</Y>
-      <Z>${camera.cameraDirection.z}</Z>
-    </CameraDirection>
-    <CameraUpVector>
-      <X>${camera.cameraUpVector.x}</X>
-      <Y>${camera.cameraUpVector.y}</Y>
-      <Z>${camera.cameraUpVector.z}</Z>
-    </CameraUpVector>
-    <FieldOfView>${camera.fieldOfView}</FieldOfView>${aspectRatioElement}
-  </PerspectiveCamera>`;
-}
-/**
- * Write orthogonal camera XML
- */
-function writeOrthogonalCamera(camera, version, viewpointGuid) {
-    const aspectRatioElement = version === '3.0' ? requireAspectRatioElement(camera.aspectRatio, viewpointGuid) : '';
-    return `\n  <OrthogonalCamera>
-    <CameraViewPoint>
-      <X>${camera.cameraViewPoint.x}</X>
-      <Y>${camera.cameraViewPoint.y}</Y>
-      <Z>${camera.cameraViewPoint.z}</Z>
-    </CameraViewPoint>
-    <CameraDirection>
-      <X>${camera.cameraDirection.x}</X>
-      <Y>${camera.cameraDirection.y}</Y>
-      <Z>${camera.cameraDirection.z}</Z>
-    </CameraDirection>
-    <CameraUpVector>
-      <X>${camera.cameraUpVector.x}</X>
-      <Y>${camera.cameraUpVector.y}</Y>
-      <Z>${camera.cameraUpVector.z}</Z>
-    </CameraUpVector>
-    <ViewToWorldScale>${camera.viewToWorldScale}</ViewToWorldScale>${aspectRatioElement}
-  </OrthogonalCamera>`;
-}
 /**
  * Write line XML
  */
-function writeLine(line) {
-    return `\n    <Line>
-      <StartPoint>
-        <X>${line.startPoint.x}</X>
-        <Y>${line.startPoint.y}</Y>
-        <Z>${line.startPoint.z}</Z>
-      </StartPoint>
-      <EndPoint>
-        <X>${line.endPoint.x}</X>
-        <Y>${line.endPoint.y}</Y>
-        <Z>${line.endPoint.z}</Z>
-      </EndPoint>
+function writeLine(line, where) {
+    return `\n    <Line>${xsdPointElement('StartPoint', line.startPoint, '      ', where)}${xsdPointElement('EndPoint', line.endPoint, '      ', where)}
     </Line>`;
 }
 /**
  * Write clipping plane XML
  */
-function writeClippingPlane(plane) {
-    return `\n    <ClippingPlane>
-      <Location>
-        <X>${plane.location.x}</X>
-        <Y>${plane.location.y}</Y>
-        <Z>${plane.location.z}</Z>
-      </Location>
-      <Direction>
-        <X>${plane.direction.x}</X>
-        <Y>${plane.direction.y}</Y>
-        <Z>${plane.direction.z}</Z>
-      </Direction>
+function writeClippingPlane(plane, where) {
+    return `\n    <ClippingPlane>${xsdPointElement('Location', plane.location, '      ', where)}${xsdPointElement('Direction', plane.direction, '      ', where)}
     </ClippingPlane>`;
 }
 /**
@@ -716,28 +628,13 @@ function writeClippingPlane(plane) {
  *   otherwise. `BCFBitmap.format` stays typed `'PNG' | 'JPG'`; we only
  *   lowercase it on the wire for 3.0.
  */
-function writeBitmap(bitmap, version) {
+function writeBitmap(bitmap, version, where) {
     const formatTag = version === '3.0' ? 'Format' : 'Bitmap';
     const formatValue = version === '3.0' ? bitmap.format.toLowerCase() : bitmap.format;
     return `\n    <Bitmap>
       <${formatTag}>${formatValue}</${formatTag}>
-      <Reference>${escapeXml(bitmap.reference)}</Reference>
-      <Location>
-        <X>${bitmap.location.x}</X>
-        <Y>${bitmap.location.y}</Y>
-        <Z>${bitmap.location.z}</Z>
-      </Location>
-      <Normal>
-        <X>${bitmap.normal.x}</X>
-        <Y>${bitmap.normal.y}</Y>
-        <Z>${bitmap.normal.z}</Z>
-      </Normal>
-      <Up>
-        <X>${bitmap.up.x}</X>
-        <Y>${bitmap.up.y}</Y>
-        <Z>${bitmap.up.z}</Z>
-      </Up>
-      <Height>${bitmap.height}</Height>
+      <Reference>${escapeXml(bitmap.reference)}</Reference>${xsdPointElement('Location', bitmap.location, '      ', where)}${xsdPointElement('Normal', bitmap.normal, '      ', where)}${xsdPointElement('Up', bitmap.up, '      ', where)}
+      <Height>${xsdDouble(bitmap.height, 'Bitmap/Height', where)}</Height>
     </Bitmap>`;
 }
 /**
@@ -774,8 +671,9 @@ function writeHeaderFile(file, indent, version) {
     if (file.filename) {
         content += `\n${indent}  <Filename>${escapeXml(file.filename)}</Filename>`;
     }
-    if (file.date) {
-        content += `\n${indent}  <Date>${escapeXml(file.date)}</Date>`;
+    const fileDate = xsdOptionalDateTime(file.date);
+    if (fileDate) {
+        content += `\n${indent}  <Date>${fileDate}</Date>`;
     }
     if (file.reference) {
         content += `\n${indent}  <Reference>${escapeXml(file.reference)}</Reference>`;
@@ -812,8 +710,41 @@ function writeBimSnippet(snippet, version) {
  * the 2.1-shaped fallback so 2.1-authored data written as 3.0 still emits
  * something.
  */
-function writeDocumentReference(docRef, version) {
-    const guidAttr = docRef.guid ? ` Guid="${escapeXml(docRef.guid)}"` : '';
+function writeDocumentReference(docRef, version, topicGuid, index) {
+    // 2.1's markup.xsd declares `Guid` with no `use`, so it is optional there;
+    // 3.0's `DocumentReferenceAttributes` declares it `use="required"`, so
+    // omitting it made every 3.0 topic carrying a guid-less document reference
+    // write an invalid `markup.bcf` -- and markup.bcf IS the issue, so a viewer
+    // that rejects it drops the topic whole (#3612). Mint one rather than
+    // refuse: this guid names only itself (nothing in the archive refers to a
+    // DocumentReference the way `RelatedTopic` refers to a topic), so a
+    // generated value loses nothing. Refusal is reserved for values that assert
+    // something only the caller knows -- `AspectRatio`, `TopicType` -- and would
+    // fail the whole export over a field 2.1 says is optional. 2.1 keeps the
+    // attribute absent: fabricating an identifier there buys no schema
+    // conformance at all, and would put an identifier the caller never chose
+    // into the file a user downloads.
+    //
+    // DERIVED, not random. `generateUuid()` here would make two exports of one
+    // unchanged project differ in bytes -- and differ again on every subsequent
+    // write, because nothing kept the value. `uuidFromSeed` is the same
+    // generator `@ifc-lite/clash` anchors its topic guids with, so the guid is a
+    // pure function of the topic, the document pointed at, and the position
+    // within the topic; all three are in the seed because two references under
+    // one topic can name the same document, and one document can appear under
+    // two topics. `docKey` names the document in the SAME precedence the 3.0
+    // body below uses -- seeding from the url alone left every `documentGuid`
+    // reference on the empty string, so its guid ignored the document entirely
+    // and two references naming different documents could collide. The result
+    // is written back onto `docRef` so the in-memory project agrees with the
+    // file rather than reporting no guid at all.
+    const docKey = docRef.documentGuid ?? docRef.url ?? docRef.referencedDocument ?? '';
+    const guid = version === '3.0'
+        ? docRef.guid || uuidFromSeed(`${topicGuid}|${docKey}|${index}`)
+        : docRef.guid;
+    if (version === '3.0' && !docRef.guid)
+        docRef.guid = guid;
+    const guidAttr = guid ? ` Guid="${escapeXml(guid)}"` : '';
     if (version === '3.0') {
         let content = `\n    <DocumentReference${guidAttr}>`;
         if (docRef.documentGuid) {
@@ -839,15 +770,4 @@ function writeDocumentReference(docRef, version) {
     content += `\n    </DocumentReference>`;
     return content;
 }
-/**
- * Escape XML special characters
- */
-function escapeXml(str) {
-    return str
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&apos;');
-}
 //# sourceMappingURL=writer.js.map