open-board-format 1.0.2 → 1.0.3

package/README.md

@@ -46,14 +46,14 @@ const fromFile = await loadOBF(file);
 import { loadOBZ, extractOBZ } from "open-board-format";
 
 // From a File (e.g. drag-and-drop)
-const { manifest, boards, files } = await loadOBZ(file);
+const { manifest, boards, resources } = await loadOBZ(file);
 
 // Or from an ArrayBuffer (e.g. fetch response)
 const parsed = await extractOBZ(buffer);
 
-// Access boards and raw files
+// Access boards and resources
 const homeBoard = parsed.boards.get("1");
-const imageBytes = parsed.files.get("images/logo.png");
+const imageBytes = parsed.resources.get("images/logo.png");
 ```
 
 ### Create an OBZ package
@@ -106,7 +106,7 @@ if (result.success) {
 | Function                                | Description                                                   |
 | --------------------------------------- | ------------------------------------------------------------- |
 | `loadOBZ(file)`                         | Load an OBZ package from a browser `File`                     |
-| `extractOBZ(buffer)`                    | Extract boards, manifest, and files from an `ArrayBuffer`     |
+| `extractOBZ(archive)`                   | Extract boards, manifest, and resources from an `ArrayBuffer` |
 | `createOBZ(boards, rootId, resources?)` | Create an OBZ package as a `Blob`                             |
 | `parseManifest(json)`                   | Parse a `manifest.json` string into a validated `OBFManifest` |
 
@@ -114,9 +114,9 @@ if (result.success) {
 
 | Function        | Description                                              |
 | --------------- | -------------------------------------------------------- |
-| `isZip(buffer)` | Check if an `ArrayBuffer` starts with a ZIP magic number |
-| `zip(files)`    | Create a ZIP from a map of paths to buffers              |
-| `unzip(buffer)` | Extract a ZIP into a map of paths to `Uint8Array`        |
+| `isZip(archive)` | Check if an `ArrayBuffer` starts with a ZIP magic number |
+| `zip(entries)`   | Create a ZIP from a map of paths to buffers              |
+| `unzip(archive)` | Extract a ZIP into a map of paths to `Uint8Array`        |
 
 ### Types
 
@@ -134,7 +134,7 @@ if (result.success) {
 | `OBFSound`            | A sound resource (extends `OBFMedia`)                                   |
 | `OBFSymbolInfo`       | Symbol set reference                                                    |
 | `OBFManifest`         | OBZ package manifest                                                    |
-| `ParsedOBZ`           | Return type of `extractOBZ` / `loadOBZ` — `{ manifest, boards, files }` |
+| `ParsedOBZ`           | Return type of `extractOBZ` / `loadOBZ` — `{ manifest, boards, resources }` |
 | `OBFID`               | Unique identifier (string, coerced from number)                         |
 | `OBFFormatVersion`    | Format version string (e.g., `open-board-0.1`)                          |
 | `OBFLicense`          | Licensing information                                                   |

package/dist/index.d.mts

@@ -299,47 +299,75 @@ declare const OBFManifestSchema: z.ZodObject<{
 type OBFManifest = z.infer<typeof OBFManifestSchema>;
 //#endregion
 //#region src/obf.d.ts
+/**
+ * Parse a JSON string into a validated OBF board.
+ *
+ * Handles an optional UTF-8 BOM prefix and throws a descriptive
+ * error if the input is malformed or fails schema validation.
+ */
 declare function parseOBF(json: string): OBFBoard;
+/**
+ * Read a `File` handle and parse its contents as an OBF board.
+ *
+ * This relies on the browser `File` API; for Node environments,
+ * read the file to a string and pass it to {@link parseOBF} instead.
+ */
 declare function loadOBF(file: File): Promise<OBFBoard>;
+/**
+ * Validate an unknown value against the OBF board schema.
+ *
+ * @throws {Error} If the value does not conform to the schema.
+ */
 declare function validateOBF(data: unknown): OBFBoard;
+/**
+ * Serialize an OBF board to a pretty-printed JSON string.
+ */
 declare function stringifyOBF(board: OBFBoard): string;
 //#endregion
 //#region src/obz.d.ts
 interface ParsedOBZ {
   manifest: OBFManifest;
   boards: Map<string, OBFBoard>;
-  files: Map<string, Uint8Array>;
+  resources: Map<string, Uint8Array>;
 }
 /**
- * Load OBZ package from File
- * @param file - File object
- * @returns Parsed OBZ with manifest, boards, and files
+ * Load an OBZ archive from a user-selected file.
  */
 declare function loadOBZ(file: File): Promise<ParsedOBZ>;
 /**
- * Extract OBZ package from ArrayBuffer
- * @param buffer - OBZ file as ArrayBuffer
- * @returns Parsed OBZ with manifest, boards, and files
+ * Extract boards and resources from a raw OBZ archive.
  */
-declare function extractOBZ(buffer: ArrayBuffer): Promise<ParsedOBZ>;
+declare function extractOBZ(archive: ArrayBuffer): Promise<ParsedOBZ>;
 /**
- * Parse manifest.json from OBZ package
- * @param json - Manifest JSON string
- * @returns Validated Manifest object
+ * Parse and validate a manifest JSON string.
  */
 declare function parseManifest(json: string): OBFManifest;
 /**
- * Create OBZ package from boards and resources
- * @param boards - Array of Board objects
- * @param rootBoardId - ID of the root board
- * @param resources - Optional map of resource paths to buffers
- * @returns OBZ package as Blob
+ * Bundle boards and optional resources into a downloadable OBZ archive.
  */
 declare function createOBZ(boards: OBFBoard[], rootBoardId: string, resources?: Map<string, Uint8Array | ArrayBuffer>): Promise<Blob>;
 //#endregion
 //#region src/zip.d.ts
-declare function unzip(buffer: ArrayBuffer): Promise<Map<string, Uint8Array>>;
-declare function zip(files: Map<string, Uint8Array | ArrayBuffer>): Promise<Uint8Array>;
-declare function isZip(buffer: ArrayBuffer): boolean;
+/**
+ * Decompress a ZIP archive into a map of file paths to raw bytes.
+ *
+ * @param archive - The raw ZIP bytes to decompress.
+ */
+declare function unzip(archive: ArrayBuffer): Promise<Map<string, Uint8Array>>;
+/**
+ * Compress a map of file paths and contents into a single ZIP archive.
+ *
+ * Accepts both `Uint8Array` and `ArrayBuffer` values so callers can
+ * pass the output of `unzip` directly or supply raw `ArrayBuffer`s
+ * without converting first.
+ *
+ * @param entries - A map of file paths to their content bytes.
+ */
+declare function zip(entries: Map<string, Uint8Array | ArrayBuffer>): Promise<Uint8Array>;
+/**
+ * Test whether an `ArrayBuffer` begins with the 2-byte ZIP
+ * magic prefix (`PK`).
+ */
+declare function isZip(archive: ArrayBuffer): boolean;
 //#endregion
 export { type OBFBoard, OBFBoardSchema, type OBFButton, type OBFButtonAction, OBFButtonActionSchema, OBFButtonSchema, type OBFFormatVersion, OBFFormatVersionSchema, type OBFGrid, OBFGridSchema, type OBFID, OBFIDSchema, type OBFImage, OBFImageSchema, type OBFLicense, OBFLicenseSchema, type OBFLoadBoard, OBFLoadBoardSchema, type OBFLocaleCode, OBFLocaleCodeSchema, type OBFLocalizedStrings, OBFLocalizedStringsSchema, type OBFManifest, OBFManifestSchema, type OBFMedia, OBFMediaSchema, type OBFSound, OBFSoundSchema, type OBFSpecialtyAction, OBFSpecialtyActionSchema, type OBFSpellingAction, OBFSpellingActionSchema, type OBFStrings, OBFStringsSchema, type OBFSymbolInfo, OBFSymbolInfoSchema, type ParsedOBZ, createOBZ, extractOBZ, isZip, loadOBF, loadOBZ, parseManifest, parseOBF, stringifyOBF, unzip, validateOBF, zip };

package/dist/index.mjs

@@ -178,48 +178,99 @@ const OBFManifestSchema = z.object({
 //#endregion
 //#region src/obf.ts
 const UTF8_BOM = "";
+/** Strip a leading UTF-8 BOM, which some editors silently prepend. */
+function stripBom(text) {
+	return text.startsWith(UTF8_BOM) ? text.slice(1) : text;
+}
+/** Build a descriptive parse-failure message, preserving the engine's reason when available. */
+function buildParseErrorMessage(error) {
+	const reason = error instanceof Error ? error.message : "";
+	return reason ? `Invalid OBF: JSON parse failed — ${reason}` : "Invalid OBF: JSON parse failed";
+}
+/**
+* Parse a JSON string into a validated OBF board.
+*
+* Handles an optional UTF-8 BOM prefix and throws a descriptive
+* error if the input is malformed or fails schema validation.
+*/
 function parseOBF(json) {
-	const trimmed = json.startsWith(UTF8_BOM) ? json.slice(1) : json;
-	let data;
+	const sanitized = stripBom(json);
+	let rawBoard;
 	try {
-		data = JSON.parse(trimmed);
+		rawBoard = JSON.parse(sanitized);
 	} catch (error) {
-		throw new Error(`Invalid OBF: JSON parse failed${error?.message ? ` — ${error.message}` : ""}`);
+		throw new Error(buildParseErrorMessage(error));
 	}
-	return validateOBF(data);
+	return validateOBF(rawBoard);
 }
+/**
+* Read a `File` handle and parse its contents as an OBF board.
+*
+* This relies on the browser `File` API; for Node environments,
+* read the file to a string and pass it to {@link parseOBF} instead.
+*/
 async function loadOBF(file) {
 	return parseOBF(await file.text());
 }
+/**
+* Validate an unknown value against the OBF board schema.
+*
+* @throws {Error} If the value does not conform to the schema.
+*/
 function validateOBF(data) {
 	const result = OBFBoardSchema.safeParse(data);
 	if (!result.success) throw new Error(`Invalid OBF: ${result.error.message}`);
 	return result.data;
 }
+/**
+* Serialize an OBF board to a pretty-printed JSON string.
+*/
 function stringifyOBF(board) {
 	return JSON.stringify(board, null, 2);
 }
 
 //#endregion
 //#region src/zip.ts
-function unzip(buffer) {
+/**
+* First two bytes of every ZIP archive — the ASCII letters `PK`,
+* after Phil Katz, creator of the format.
+*
+* Only the 2-byte prefix is checked intentionally: this keeps the
+* test lightweight and sufficient for distinguishing ZIP from JSON.
+*/
+const ZIP_MAGIC = [80, 75];
+/** Balanced speed-vs-size deflate level used by fflate (1–9 scale). */
+const COMPRESSION_LEVEL = 6;
+/**
+* Decompress a ZIP archive into a map of file paths to raw bytes.
+*
+* @param archive - The raw ZIP bytes to decompress.
+*/
+function unzip(archive) {
 	return new Promise((resolve, reject) => {
-		unzip$1(new Uint8Array(buffer), (error, result) => {
+		unzip$1(new Uint8Array(archive), (error, entries) => {
 			if (error) {
 				reject(/* @__PURE__ */ new Error(`Failed to unzip: ${error.message ?? String(error)}`));
 				return;
 			}
-			const files = /* @__PURE__ */ new Map();
-			for (const [path, bytes] of Object.entries(result)) files.set(path, bytes);
-			resolve(files);
+			resolve(new Map(Object.entries(entries)));
 		});
 	});
 }
-function zip(files) {
+/**
+* Compress a map of file paths and contents into a single ZIP archive.
+*
+* Accepts both `Uint8Array` and `ArrayBuffer` values so callers can
+* pass the output of `unzip` directly or supply raw `ArrayBuffer`s
+* without converting first.
+*
+* @param entries - A map of file paths to their content bytes.
+*/
+function zip(entries) {
 	return new Promise((resolve, reject) => {
-		const input = {};
-		for (const [path, content] of files) input[path] = content instanceof Uint8Array ? content : new Uint8Array(content);
-		zip$1(input, { level: 6 }, (error, result) => {
+		const pathToBytes = {};
+		for (const [path, content] of entries) pathToBytes[path] = content instanceof Uint8Array ? content : new Uint8Array(content);
+		zip$1(pathToBytes, { level: COMPRESSION_LEVEL }, (error, result) => {
 			if (error) {
 				reject(/* @__PURE__ */ new Error(`Failed to zip: ${error.message ?? String(error)}`));
 				return;
@@ -228,87 +279,89 @@ function zip(files) {
 		});
 	});
 }
-function isZip(buffer) {
-	const view = new Uint8Array(buffer);
-	return view.length >= 2 && view[0] === 80 && view[1] === 75;
+/**
+* Test whether an `ArrayBuffer` begins with the 2-byte ZIP
+* magic prefix (`PK`).
+*/
+function isZip(archive) {
+	const bytes = new Uint8Array(archive);
+	return bytes.length >= ZIP_MAGIC.length && ZIP_MAGIC.every((byte, index) => bytes[index] === byte);
 }
 
 //#endregion
 //#region src/obz.ts
 /**
-* Load OBZ package from File
-* @param file - File object
-* @returns Parsed OBZ with manifest, boards, and files
+* Load an OBZ archive from a user-selected file.
 */
 async function loadOBZ(file) {
 	return extractOBZ(await file.arrayBuffer());
 }
 /**
-* Extract OBZ package from ArrayBuffer
-* @param buffer - OBZ file as ArrayBuffer
-* @returns Parsed OBZ with manifest, boards, and files
+* Extract boards and resources from a raw OBZ archive.
 */
-async function extractOBZ(buffer) {
-	if (!isZip(buffer)) throw new Error("Invalid OBZ: not a ZIP file");
-	const files = await unzip(buffer);
-	const manifestBuffer = files.get("manifest.json");
-	if (!manifestBuffer) throw new Error("Invalid OBZ: missing manifest.json");
-	const manifest = parseManifest(new TextDecoder().decode(manifestBuffer));
-	const boards = /* @__PURE__ */ new Map();
-	for (const [id, path] of Object.entries(manifest.paths.boards)) {
-		const boardBuffer = files.get(path);
-		if (!boardBuffer) {
-			console.warn(`Board ${id} not found at ${path}`);
-			continue;
-		}
-		const board = parseOBF(new TextDecoder().decode(boardBuffer));
-		boards.set(id, board);
-	}
+async function extractOBZ(archive) {
+	if (!isZip(archive)) throw new Error("Invalid OBZ: not a ZIP file");
+	const entries = await unzip(archive);
+	const manifest = extractManifest(entries);
 	return {
 		manifest,
-		boards,
-		files
+		boards: extractBoards(manifest, entries),
+		resources: entries
 	};
 }
 /**
-* Parse manifest.json from OBZ package
-* @param json - Manifest JSON string
-* @returns Validated Manifest object
+* Parse and validate a manifest JSON string.
 */
 function parseManifest(json) {
-	const data = JSON.parse(json);
+	let data;
+	try {
+		data = JSON.parse(json);
+	} catch (error) {
+		throw new Error(`Invalid manifest: JSON parse failed${error?.message ? ` — ${error.message}` : ""}`);
+	}
 	const result = OBFManifestSchema.safeParse(data);
 	if (!result.success) throw new Error(`Invalid manifest: ${result.error.message}`);
 	return result.data;
 }
 /**
-* Create OBZ package from boards and resources
-* @param boards - Array of Board objects
-* @param rootBoardId - ID of the root board
-* @param resources - Optional map of resource paths to buffers
-* @returns OBZ package as Blob
+* Bundle boards and optional resources into a downloadable OBZ archive.
 */
 async function createOBZ(boards, rootBoardId, resources) {
-	const files = /* @__PURE__ */ new Map();
+	const entries = /* @__PURE__ */ new Map();
+	const boardPaths = Object.fromEntries(boards.map((board) => [board.id, `boards/${board.id}.obf`]));
 	const manifest = OBFManifestSchema.parse({
 		format: "open-board-0.1",
 		root: `boards/${rootBoardId}.obf`,
 		paths: {
-			boards: Object.fromEntries(boards.map((board) => [board.id, `boards/${board.id}.obf`])),
+			boards: boardPaths,
 			images: {},
 			sounds: {}
 		}
 	});
-	const manifestJSON = JSON.stringify(manifest, null, 2);
-	files.set("manifest.json", new TextEncoder().encode(manifestJSON).buffer);
+	const encoder = new TextEncoder();
+	entries.set("manifest.json", encoder.encode(JSON.stringify(manifest, null, 2)));
 	for (const board of boards) {
-		const boardJSON = JSON.stringify(board, null, 2);
 		const path = `boards/${board.id}.obf`;
-		files.set(path, new TextEncoder().encode(boardJSON).buffer);
+		entries.set(path, encoder.encode(JSON.stringify(board, null, 2)));
+	}
+	if (resources) for (const [path, bytes] of resources) entries.set(path, bytes);
+	const compressed = await zip(entries);
+	return new Blob([new Uint8Array(compressed)], { type: "application/zip" });
+}
+function extractManifest(entries) {
+	const manifestBytes = entries.get("manifest.json");
+	if (!manifestBytes) throw new Error("Invalid OBZ: missing manifest.json");
+	return parseManifest(new TextDecoder().decode(manifestBytes));
+}
+function extractBoards(manifest, entries) {
+	const boards = /* @__PURE__ */ new Map();
+	for (const [id, path] of Object.entries(manifest.paths.boards)) {
+		const boardBytes = entries.get(path);
+		if (!boardBytes) throw new Error(`Board "${id}" declared in manifest but missing at path "${path}"`);
+		const boardJson = new TextDecoder().decode(boardBytes);
+		boards.set(id, parseOBF(boardJson));
 	}
-	if (resources) for (const [path, buffer] of resources.entries()) files.set(path, buffer);
-	const zipBuffer = await zip(files);
-	return new Blob([new Uint8Array(zipBuffer)], { type: "application/zip" });
+	return boards;
 }
 
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "open-board-format",
   "type": "module",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Parse, validate, and create Open Board Format (OBF/OBZ) files for AAC applications.",
   "author": "Shay Cojocaru <shayc@outlook.com>",
   "license": "MIT",