open-board-format 1.0.2 → 1.0.4

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

@@ -12,7 +12,7 @@ import { z } from "zod";
 * @author Shay Cojocaru
 * @license MIT
 */
-/** Unique identifier as a string. Must be a non-empty string or number (coerced to string). */
+/** Unique board-element identifier, coerced to a non-empty string. */
 declare const OBFIDSchema: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>, z.ZodString>;
 type OBFID = z.infer<typeof OBFIDSchema>;
 /**
@@ -26,35 +26,35 @@ type OBFFormatVersion = z.infer<typeof OBFFormatVersionSchema>;
 declare const OBFLocaleCodeSchema: z.ZodString;
 type OBFLocaleCode = z.infer<typeof OBFLocaleCodeSchema>;
 /**
- * Mapping of string keys to localized string values.
+ * Key–value pairs mapping symbolic names to their translations in a single locale.
  */
 declare const OBFLocalizedStringsSchema: z.ZodRecord<z.ZodString, z.ZodString>;
 type OBFLocalizedStrings = z.infer<typeof OBFLocalizedStringsSchema>;
 /**
- * String translations for multiple locales.
+ * Locale-keyed dictionary of translated strings,
+ * e.g., `{ en: { greeting: "Hello" }, fr: { greeting: "Bonjour" } }`.
  */
 declare const OBFStringsSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
 type OBFStrings = z.infer<typeof OBFStringsSchema>;
 /**
- * Represents custom actions for spelling.
- * Prefixed with '+' followed by the text to append.
+ * Spelling action: a `+` prefix followed by the text to append,
+ * e.g., `"+hello"`.
  */
 declare const OBFSpellingActionSchema: z.ZodString;
 type OBFSpellingAction = z.infer<typeof OBFSpellingActionSchema>;
 /**
- * Represents specialty actions.
- * Standard actions are prefixed with ':'.
- * Custom actions start with ':ext_'.
+ * Specialty action prefixed with `:`, e.g., `":clear"`.
+ * Custom extensions use the `:ext_` prefix.
  */
 declare const OBFSpecialtyActionSchema: z.ZodString;
 type OBFSpecialtyAction = z.infer<typeof OBFSpecialtyActionSchema>;
 /**
- * Possible actions associated with a button.
+ * Union of spelling and specialty actions that a button can trigger.
  */
 declare const OBFButtonActionSchema: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
 type OBFButtonAction = z.infer<typeof OBFButtonActionSchema>;
 /**
- * Licensing information for a resource.
+ * License terms and attribution for a resource.
  */
 declare const OBFLicenseSchema: z.ZodObject<{
   type: z.ZodString;
@@ -91,7 +91,7 @@ declare const OBFMediaSchema: z.ZodObject<{
 }, z.core.$strip>;
 type OBFMedia = z.infer<typeof OBFMediaSchema>;
 /**
- * Information about a symbol from a proprietary symbol set.
+ * Reference to a symbol in a proprietary symbol set (e.g., SymbolStix).
  */
 declare const OBFSymbolInfoSchema: z.ZodObject<{
   set: z.ZodString;
@@ -99,13 +99,14 @@ declare const OBFSymbolInfoSchema: z.ZodObject<{
 }, z.core.$strip>;
 type OBFSymbolInfo = z.infer<typeof OBFSymbolInfoSchema>;
 /**
- * Represents an image resource.
+ * Image resource, extending {@link OBFMediaSchema} with optional
+ * symbol and dimension properties.
  *
- * When resolving the image, if multiple references are provided, they should be used in the following order:
- * 1. data
- * 2. path
- * 3. url
- * 4. symbol
+ * When resolving the image, consumers should prefer sources in this order:
+ * 1. `data`
+ * 2. `path`
+ * 3. `url`
+ * 4. `symbol`
  */
 declare const OBFImageSchema: z.ZodIntersection<z.ZodObject<{
   id: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>, z.ZodString>;
@@ -132,7 +133,7 @@ declare const OBFImageSchema: z.ZodIntersection<z.ZodObject<{
 }, z.core.$strip>>;
 type OBFImage = z.infer<typeof OBFImageSchema>;
 /**
- * Represents a sound resource.
+ * Audio resource. Identical to {@link OBFMediaSchema} — no additional properties.
  */
 declare const OBFSoundSchema: z.ZodObject<{
   id: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>, z.ZodString>;
@@ -152,7 +153,7 @@ declare const OBFSoundSchema: z.ZodObject<{
 }, z.core.$strip>;
 type OBFSound = z.infer<typeof OBFSoundSchema>;
 /**
- * Information needed to load another board.
+ * Reference to another board, resolved by ID, path, or URL.
  */
 declare const OBFLoadBoardSchema: z.ZodObject<{
   id: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string | undefined, string | number>>>;
@@ -163,7 +164,7 @@ declare const OBFLoadBoardSchema: z.ZodObject<{
 }, z.core.$strip>;
 type OBFLoadBoard = z.infer<typeof OBFLoadBoardSchema>;
 /**
- * Represents a button on the board.
+ * Interactive element on a board, optionally linked to images, sounds, and actions.
  */
 declare const OBFButtonSchema: z.ZodObject<{
   id: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>, z.ZodString>;
@@ -189,7 +190,7 @@ declare const OBFButtonSchema: z.ZodObject<{
 }, z.core.$strip>;
 type OBFButton = z.infer<typeof OBFButtonSchema>;
 /**
- * Grid layout information for the board.
+ * Row-and-column layout that arranges buttons by their IDs.
  */
 declare const OBFGridSchema: z.ZodObject<{
   rows: z.ZodNumber;
@@ -198,7 +199,7 @@ declare const OBFGridSchema: z.ZodObject<{
 }, z.core.$strip>;
 type OBFGrid = z.infer<typeof OBFGridSchema>;
 /**
- * Represents the root object of an OBF file, defining the structure and layout of a board.
+ * Root object of an `.obf` file: the complete definition of a single communication board.
  */
 declare const OBFBoardSchema: z.ZodObject<{
   format: z.ZodString;
@@ -285,7 +286,7 @@ declare const OBFBoardSchema: z.ZodObject<{
 }, z.core.$strip>;
 type OBFBoard = z.infer<typeof OBFBoardSchema>;
 /**
- * Manifest file in an .obz package.
+ * Table of contents for an `.obz` package, mapping resource IDs to their archive paths.
  */
 declare const OBFManifestSchema: z.ZodObject<{
   format: z.ZodString;
@@ -299,47 +300,137 @@ 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.
+ *
+ * Strips an optional UTF-8 BOM prefix before parsing and throws a
+ * descriptive error if the input is malformed or fails schema validation.
+ *
+ * @param json - The JSON string to parse.
+ * @returns The validated board object.
+ *
+ * @throws {Error} If the JSON is malformed or does not conform to the OBF schema.
+ */
 declare function parseOBF(json: string): OBFBoard;
+/**
+ * Read a `File` and parse its contents as a validated 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.
+ *
+ * @param file - A `File` handle pointing to an `.obf` file.
+ * @returns The validated board object.
+ *
+ * @throws {Error} If the file content is malformed or fails schema validation.
+ */
 declare function loadOBF(file: File): Promise<OBFBoard>;
+/**
+ * Validate an unknown value against the OBF board schema.
+ *
+ * @param data - The value to validate.
+ * @returns The validated board object.
+ *
+ * @throws {Error} If the value does not conform to the OBF schema.
+ */
 declare function validateOBF(data: unknown): OBFBoard;
+/**
+ * Stringify an OBF board to a pretty-printed JSON string.
+ *
+ * @param board - The board to stringify.
+ * @returns A JSON string with two-space indentation.
+ */
 declare function stringifyOBF(board: OBFBoard): string;
 //#endregion
 //#region src/obz.d.ts
+/**
+ * Fully extracted contents of an `.obz` archive.
+ *
+ * @property manifest  - The package table of contents.
+ * @property boards    - Board ID → validated board object.
+ * @property resources - Archive path → raw binary content (images, sounds, etc.).
+ */
 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
+ * Read a `File` and extract its contents as a parsed OBZ package.
+ *
+ * This relies on the browser `File` API; for Node environments,
+ * read the file to an `ArrayBuffer` and pass it to {@link extractOBZ} instead.
+ *
+ * @param file - A `File` handle pointing to an `.obz` archive.
+ * @returns The parsed manifest, boards, and binary resources.
+ *
+ * @throws {Error} If the file is not a valid ZIP or the manifest is missing.
  */
 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
+ * Decompress an OBZ archive and return its manifest, boards, and resources.
+ *
+ * @param archive - The OBZ archive as an `ArrayBuffer`.
+ * @returns The parsed manifest, a map of board IDs to validated boards,
+ *          and a map of file paths to their binary content.
+ *
+ * @throws {Error} If the archive is not a valid ZIP or the manifest is missing.
  */
-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 an OBZ manifest — the table of contents that maps
+ * board IDs to their file paths within the archive.
+ *
+ * @param json - A JSON string representing the manifest.
+ * @returns The validated manifest object.
+ *
+ * @throws {Error} If the JSON is malformed or fails schema validation.
  */
 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 compressed OBZ archive.
+ *
+ * A manifest is generated automatically from the supplied boards,
+ * using the `rootBoardId` to designate the entry-point board.
+ *
+ * @param boards - The boards to include in the archive.
+ * @param rootBoardId - The ID of the board that serves as the archive's entry point.
+ * @param resources - Optional map of file paths to binary content (images, sounds, etc.).
+ * @returns A `Blob` containing the compressed OBZ archive.
+ *
+ * @throws {Error} If `rootBoardId` does not match any of the supplied boards.
  */
 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 ZIP archive as an `ArrayBuffer`.
+ * @returns A map of file paths to their decompressed content.
+ *
+ * @throws {Error} If decompression fails.
+ */
+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 {@link unzip} directly or supply raw `ArrayBuffer`s
+ * without converting first.
+ *
+ * @param entries - A map of file paths to their content bytes.
+ * @returns The compressed archive as a `Uint8Array`.
+ *
+ * @throws {Error} If compression fails.
+ */
+declare function zip(entries: Map<string, Uint8Array | ArrayBuffer>): Promise<Uint8Array>;
+/**
+ * Test whether an `ArrayBuffer` begins with the two-byte ZIP magic
+ * prefix (`PK`).
+ *
+ * @param archive - The buffer to inspect.
+ * @returns `true` if the buffer starts with the ZIP signature.
+ */
+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

@@ -22,7 +22,7 @@ const OBFOptionalIDSchema = z.union([z.string(), z.number()]).transform((val) =>
 	const str = String(val);
 	return str === "" ? void 0 : str;
 }).optional();
-/** Unique identifier as a string. Must be a non-empty string or number (coerced to string). */
+/** Unique board-element identifier, coerced to a non-empty string. */
 const OBFIDSchema = z.union([z.string(), z.number()]).transform((val) => String(val)).pipe(z.string().min(1));
 /**
 * Format version of the Open Board Format, e.g., 'open-board-0.1'.
@@ -33,30 +33,30 @@ const OBFFormatVersionSchema = z.string().regex(/^open-board-.+$/);
 */
 const OBFLocaleCodeSchema = z.string();
 /**
-* Mapping of string keys to localized string values.
+* Key–value pairs mapping symbolic names to their translations in a single locale.
 */
 const OBFLocalizedStringsSchema = z.record(z.string(), z.string());
 /**
-* String translations for multiple locales.
+* Locale-keyed dictionary of translated strings,
+* e.g., `{ en: { greeting: "Hello" }, fr: { greeting: "Bonjour" } }`.
 */
 const OBFStringsSchema = z.record(z.string(), OBFLocalizedStringsSchema);
 /**
-* Represents custom actions for spelling.
-* Prefixed with '+' followed by the text to append.
+* Spelling action: a `+` prefix followed by the text to append,
+* e.g., `"+hello"`.
 */
 const OBFSpellingActionSchema = z.string().regex(/^\+.+$/);
 /**
-* Represents specialty actions.
-* Standard actions are prefixed with ':'.
-* Custom actions start with ':ext_'.
+* Specialty action prefixed with `:`, e.g., `":clear"`.
+* Custom extensions use the `:ext_` prefix.
 */
 const OBFSpecialtyActionSchema = z.string().regex(/^:[a-z][a-z0-9_-]*$/i);
 /**
-* Possible actions associated with a button.
+* Union of spelling and specialty actions that a button can trigger.
 */
 const OBFButtonActionSchema = z.union([OBFSpellingActionSchema, OBFSpecialtyActionSchema]);
 /**
-* Licensing information for a resource.
+* License terms and attribution for a resource.
 */
 const OBFLicenseSchema = z.object({
 	type: z.string(),
@@ -84,20 +84,21 @@ const OBFMediaSchema = z.object({
 	license: OBFLicenseSchema.optional()
 });
 /**
-* Information about a symbol from a proprietary symbol set.
+* Reference to a symbol in a proprietary symbol set (e.g., SymbolStix).
 */
 const OBFSymbolInfoSchema = z.object({
 	set: z.string(),
 	filename: z.string()
 });
 /**
-* Represents an image resource.
+* Image resource, extending {@link OBFMediaSchema} with optional
+* symbol and dimension properties.
 *
-* When resolving the image, if multiple references are provided, they should be used in the following order:
-* 1. data
-* 2. path
-* 3. url
-* 4. symbol
+* When resolving the image, consumers should prefer sources in this order:
+* 1. `data`
+* 2. `path`
+* 3. `url`
+* 4. `symbol`
 */
 const OBFImageSchema = OBFMediaSchema.and(z.object({
 	symbol: OBFSymbolInfoSchema.optional(),
@@ -105,11 +106,11 @@ const OBFImageSchema = OBFMediaSchema.and(z.object({
 	height: z.number().optional()
 }));
 /**
-* Represents a sound resource.
+* Audio resource. Identical to {@link OBFMediaSchema} — no additional properties.
 */
 const OBFSoundSchema = OBFMediaSchema;
 /**
-* Information needed to load another board.
+* Reference to another board, resolved by ID, path, or URL.
 */
 const OBFLoadBoardSchema = z.object({
 	id: OBFOptionalIDSchema,
@@ -119,7 +120,7 @@ const OBFLoadBoardSchema = z.object({
 	path: z.string().optional()
 });
 /**
-* Represents a button on the board.
+* Interactive element on a board, optionally linked to images, sounds, and actions.
 */
 const OBFButtonSchema = z.object({
 	id: OBFIDSchema,
@@ -138,7 +139,7 @@ const OBFButtonSchema = z.object({
 	height: z.number().min(0).max(1).optional()
 });
 /**
-* Grid layout information for the board.
+* Row-and-column layout that arranges buttons by their IDs.
 */
 const OBFGridSchema = z.object({
 	rows: z.number().int().min(1),
@@ -146,7 +147,7 @@ const OBFGridSchema = z.object({
 	order: z.array(z.array(z.union([OBFIDSchema, z.null()])))
 }).refine((g) => g.order.length === g.rows, { message: "Grid order length must match rows" }).refine((g) => g.order.every((row) => row.length === g.columns), { message: "Each grid row must have length equal to columns" });
 /**
-* Represents the root object of an OBF file, defining the structure and layout of a board.
+* Root object of an `.obf` file: the complete definition of a single communication board.
 */
 const OBFBoardSchema = z.object({
 	format: OBFFormatVersionSchema,
@@ -163,7 +164,7 @@ const OBFBoardSchema = z.object({
 	strings: OBFStringsSchema.optional()
 });
 /**
-* Manifest file in an .obz package.
+* Table of contents for an `.obz` package, mapping resource IDs to their archive paths.
 */
 const OBFManifestSchema = z.object({
 	format: OBFFormatVersionSchema,
@@ -178,48 +179,121 @@ 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.
+*
+* Strips an optional UTF-8 BOM prefix before parsing and throws a
+* descriptive error if the input is malformed or fails schema validation.
+*
+* @param json - The JSON string to parse.
+* @returns The validated board object.
+*
+* @throws {Error} If the JSON is malformed or does not conform to the OBF schema.
+*/
 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` and parse its contents as a validated 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.
+*
+* @param file - A `File` handle pointing to an `.obf` file.
+* @returns The validated board object.
+*
+* @throws {Error} If the file content is malformed or fails schema validation.
+*/
 async function loadOBF(file) {
 	return parseOBF(await file.text());
 }
+/**
+* Validate an unknown value against the OBF board schema.
+*
+* @param data - The value to validate.
+* @returns The validated board object.
+*
+* @throws {Error} If the value does not conform to the OBF schema.
+*/
 function validateOBF(data) {
 	const result = OBFBoardSchema.safeParse(data);
 	if (!result.success) throw new Error(`Invalid OBF: ${result.error.message}`);
 	return result.data;
 }
+/**
+* Stringify an OBF board to a pretty-printed JSON string.
+*
+* @param board - The board to stringify.
+* @returns A JSON string with two-space indentation.
+*/
 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 ZIP archive as an `ArrayBuffer`.
+* @returns A map of file paths to their decompressed content.
+*
+* @throws {Error} If decompression fails.
+*/
+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 {@link unzip} directly or supply raw `ArrayBuffer`s
+* without converting first.
+*
+* @param entries - A map of file paths to their content bytes.
+* @returns The compressed archive as a `Uint8Array`.
+*
+* @throws {Error} If compression fails.
+*/
+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 +302,122 @@ 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 two-byte ZIP magic
+* prefix (`PK`).
+*
+* @param archive - The buffer to inspect.
+* @returns `true` if the buffer starts with the ZIP signature.
+*/
+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
+* Read a `File` and extract its contents as a parsed OBZ package.
+*
+* This relies on the browser `File` API; for Node environments,
+* read the file to an `ArrayBuffer` and pass it to {@link extractOBZ} instead.
+*
+* @param file - A `File` handle pointing to an `.obz` archive.
+* @returns The parsed manifest, boards, and binary resources.
+*
+* @throws {Error} If the file is not a valid ZIP or the manifest is missing.
 */
 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
+* Decompress an OBZ archive and return its manifest, boards, and resources.
+*
+* @param archive - The OBZ archive as an `ArrayBuffer`.
+* @returns The parsed manifest, a map of board IDs to validated boards,
+*          and a map of file paths to their binary content.
+*
+* @throws {Error} If the archive is not a valid ZIP or the manifest is missing.
 */
-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 an OBZ manifest — the table of contents that maps
+* board IDs to their file paths within the archive.
+*
+* @param json - A JSON string representing the manifest.
+* @returns The validated manifest object.
+*
+* @throws {Error} If the JSON is malformed or fails schema validation.
 */
 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 compressed OBZ archive.
+*
+* A manifest is generated automatically from the supplied boards,
+* using the `rootBoardId` to designate the entry-point board.
+*
+* @param boards - The boards to include in the archive.
+* @param rootBoardId - The ID of the board that serves as the archive's entry point.
+* @param resources - Optional map of file paths to binary content (images, sounds, etc.).
+* @returns A `Blob` containing the compressed OBZ archive.
+*
+* @throws {Error} If `rootBoardId` does not match any of the supplied boards.
 */
 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.4",
   "description": "Parse, validate, and create Open Board Format (OBF/OBZ) files for AAC applications.",
   "author": "Shay Cojocaru <shayc@outlook.com>",
   "license": "MIT",