open-board-format 1.0.3 → 1.0.5

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;
@@ -302,48 +303,101 @@ type OBFManifest = z.infer<typeof OBFManifestSchema>;
 /**
  * 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.
+ * 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` handle and parse its contents as an OBF board.
+ * 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.
  *
- * @throws {Error} If the value does not conform to the 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;
 /**
- * Serialize an OBF board to a pretty-printed JSON string.
+ * 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>;
   resources: Map<string, Uint8Array>;
 }
 /**
- * Load an OBZ archive from a user-selected file.
+ * 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 boards and resources from a raw OBZ archive.
+ * 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(archive: ArrayBuffer): Promise<ParsedOBZ>;
 /**
- * Parse and validate a manifest JSON string.
+ * 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;
 /**
- * Bundle boards and optional resources into a downloadable OBZ archive.
+ * 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
@@ -351,22 +405,31 @@ declare function createOBZ(boards: OBFBoard[], rootBoardId: string, resources?:
 /**
  * Decompress a ZIP archive into a map of file paths to raw bytes.
  *
- * @param archive - The raw ZIP bytes to decompress.
+ * @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 `unzip` directly or supply raw `ArrayBuffer`s
+ * 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 2-byte ZIP
- * magic prefix (`PK`).
+ * 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

package/dist/index.mjs

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import { unzip as unzip$1, zip as zip$1 } from "fflate";
-
 //#region src/schema.ts
 /**
 * Open Board Format (OBF) Zod Schemas
@@ -22,7 +21,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,37 +32,43 @@ 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 of the license, e.g., 'CC-BY-SA'. */
 	type: z.string(),
+	/** URL to the license terms. */
 	copyright_notice_url: OBFOptionalUrlSchema,
+	/** Source URL of the resource. */
 	source_url: OBFOptionalUrlSchema,
+	/** Name of the author. */
 	author_name: z.string().optional(),
+	/** URL of the author's webpage. */
 	author_url: OBFOptionalUrlSchema,
+	/** Email address of the author. */
 	author_email: OBFOptionalEmailSchema
 });
 /**
@@ -75,106 +80,161 @@ const OBFLicenseSchema = z.object({
 * 3. url
 */
 const OBFMediaSchema = z.object({
+	/** Unique identifier for the media resource. */
 	id: OBFIDSchema,
+	/** Data URI containing the media data. */
 	data: z.string().optional(),
+	/** Path to the media file within an .obz package. */
 	path: z.string().optional(),
+	/** Data URL to fetch the media programmatically. */
 	data_url: OBFOptionalUrlSchema,
+	/** URL to the media resource. */
 	url: OBFOptionalUrlSchema,
+	/** MIME type of the media, e.g., 'image/png', 'audio/mpeg'. */
 	content_type: z.string().optional(),
+	/** Licensing information for the media. */
 	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({
+	/** Name of the symbol set, e.g., 'symbolstix'. */
 	set: z.string(),
+	/** Filename of the symbol within the set. */
 	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({
+	/** Information about a symbol from a proprietary symbol set. */
 	symbol: OBFSymbolInfoSchema.optional(),
+	/** Width of the image in pixels. */
 	width: z.number().optional(),
+	/** Height of the image in pixels. */
 	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({
+	/** Unique identifier of the board to load. */
 	id: OBFOptionalIDSchema,
+	/** Name of the board to load. */
 	name: z.string().optional(),
+	/** Data URL to fetch the board programmatically. */
 	data_url: OBFOptionalUrlSchema,
+	/** URL to access the board via a web browser. */
 	url: OBFOptionalUrlSchema,
+	/** Path to the board within an .obz package. */
 	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({
+	/** Unique identifier for the button. */
 	id: OBFIDSchema,
+	/** Label text displayed on the button. */
 	label: z.string().optional(),
+	/** Alternative text for vocalization when the button is activated. */
 	vocalization: z.string().optional(),
+	/** Identifier of the image associated with the button. */
 	image_id: OBFOptionalIDSchema,
+	/** Identifier of the sound associated with the button. */
 	sound_id: OBFOptionalIDSchema,
+	/** Action associated with the button. */
 	action: OBFButtonActionSchema.optional(),
+	/** List of multiple actions for the button, executed in order. */
 	actions: z.array(OBFButtonActionSchema).optional(),
+	/** Information to load another board when this button is activated. */
 	load_board: OBFLoadBoardSchema.optional(),
+	/** Background color of the button in 'rgb' or 'rgba' format. */
 	background_color: z.string().optional(),
+	/** Border color of the button in 'rgb' or 'rgba' format. */
 	border_color: z.string().optional(),
+	/** Vertical position for absolute positioning (0.0 to 1.0). */
 	top: z.number().min(0).max(1).optional(),
+	/** Horizontal position for absolute positioning (0.0 to 1.0). */
 	left: z.number().min(0).max(1).optional(),
+	/** Width of the button for absolute positioning (0.0 to 1.0). */
 	width: z.number().min(0).max(1).optional(),
+	/** Height of the button for absolute positioning (0.0 to 1.0). */
 	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({
+	/** Number of rows in the grid. */
 	rows: z.number().int().min(1),
+	/** Number of columns in the grid. */
 	columns: z.number().int().min(1),
+	/**
+	* 2D array representing the order of buttons by their IDs.
+	* Each sub-array corresponds to a row, and each element is a button ID or null for empty slots.
+	*/
 	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 version of the Open Board Format, e.g., 'open-board-0.1'. */
 	format: OBFFormatVersionSchema,
+	/** Unique identifier for the board. */
 	id: OBFIDSchema,
+	/** Locale of the board as a BCP 47 language tag, e.g., 'en', 'en-US'. */
 	locale: OBFLocaleCodeSchema.optional(),
+	/** List of buttons on the board. */
 	buttons: z.array(OBFButtonSchema),
+	/** URL where the board can be accessed or downloaded. */
 	url: OBFOptionalUrlSchema,
+	/** Name of the board. */
 	name: z.string().optional(),
+	/** Description of the board in HTML format. */
 	description_html: z.string().optional(),
+	/** Grid layout information for arranging buttons. */
 	grid: OBFGridSchema,
+	/** List of images used in the board. */
 	images: z.array(OBFImageSchema).optional(),
+	/** List of sounds used in the board. */
 	sounds: z.array(OBFSoundSchema).optional(),
+	/** Licensing information for the board. */
 	license: OBFLicenseSchema.optional(),
+	/** String translations for multiple locales. */
 	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 version of the Open Board Format, e.g., 'open-board-0.1'. */
 	format: OBFFormatVersionSchema,
+	/** Path to the root board within the .obz package. */
 	root: z.string(),
+	/** Mapping of IDs to paths for boards, images, and sounds. */
 	paths: z.object({
+		/** Mapping of board IDs to their file paths. */
 		boards: z.record(z.string(), z.string()),
+		/** Mapping of image IDs to their file paths. */
 		images: z.record(z.string(), z.string()),
+		/** Mapping of sound IDs to their file paths. */
 		sounds: z.record(z.string(), z.string()).optional()
 	})
 });
-
 //#endregion
 //#region src/obf.ts
 const UTF8_BOM = "";
@@ -190,8 +250,13 @@ function buildParseErrorMessage(error) {
 /**
 * 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.
+* 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 sanitized = stripBom(json);
@@ -204,10 +269,15 @@ function parseOBF(json) {
 	return validateOBF(rawBoard);
 }
 /**
-* Read a `File` handle and parse its contents as an OBF board.
+* 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());
@@ -215,7 +285,10 @@ async function loadOBF(file) {
 /**
 * Validate an unknown value against the OBF board schema.
 *
-* @throws {Error} If the value does not conform to the 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);
@@ -223,12 +296,14 @@ function validateOBF(data) {
 	return result.data;
 }
 /**
-* Serialize an OBF board to a pretty-printed JSON string.
+* 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
 /**
@@ -244,7 +319,10 @@ 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.
+* @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) => {
@@ -261,10 +339,13 @@ function unzip(archive) {
 * 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
+* 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) => {
@@ -280,24 +361,40 @@ function zip(entries) {
 	});
 }
 /**
-* Test whether an `ArrayBuffer` begins with the 2-byte ZIP
-* magic prefix (`PK`).
+* 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 an OBZ archive from a user-selected file.
+* 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 boards and resources from a raw OBZ archive.
+* 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(archive) {
 	if (!isZip(archive)) throw new Error("Invalid OBZ: not a ZIP file");
@@ -310,7 +407,13 @@ async function extractOBZ(archive) {
 	};
 }
 /**
-* Parse and validate a manifest JSON string.
+* 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) {
 	let data;
@@ -324,7 +427,17 @@ function parseManifest(json) {
 	return result.data;
 }
 /**
-* Bundle boards and optional resources into a downloadable OBZ archive.
+* 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 entries = /* @__PURE__ */ new Map();
@@ -363,6 +476,5 @@ function extractBoards(manifest, entries) {
 	}
 	return boards;
 }
-
 //#endregion
-export { OBFBoardSchema, OBFButtonActionSchema, OBFButtonSchema, OBFFormatVersionSchema, OBFGridSchema, OBFIDSchema, OBFImageSchema, OBFLicenseSchema, OBFLoadBoardSchema, OBFLocaleCodeSchema, OBFLocalizedStringsSchema, OBFManifestSchema, OBFMediaSchema, OBFSoundSchema, OBFSpecialtyActionSchema, OBFSpellingActionSchema, OBFStringsSchema, OBFSymbolInfoSchema, createOBZ, extractOBZ, isZip, loadOBF, loadOBZ, parseManifest, parseOBF, stringifyOBF, unzip, validateOBF, zip };
+export { OBFBoardSchema, OBFButtonActionSchema, OBFButtonSchema, OBFFormatVersionSchema, OBFGridSchema, OBFIDSchema, OBFImageSchema, OBFLicenseSchema, OBFLoadBoardSchema, OBFLocaleCodeSchema, OBFLocalizedStringsSchema, OBFManifestSchema, OBFMediaSchema, OBFSoundSchema, OBFSpecialtyActionSchema, OBFSpellingActionSchema, OBFStringsSchema, OBFSymbolInfoSchema, createOBZ, extractOBZ, isZip, loadOBF, loadOBZ, parseManifest, parseOBF, stringifyOBF, unzip, validateOBF, zip };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "open-board-format",
   "type": "module",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Parse, validate, and create Open Board Format (OBF/OBZ) files for AAC applications.",
   "author": "Shay Cojocaru <shayc@outlook.com>",
   "license": "MIT",
@@ -35,14 +35,14 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
-    "@types/node": "^25.3.0",
-    "bumpp": "^10.4.1",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "@types/node": "^25.7.0",
+    "bumpp": "^11.1.0",
+    "tsdown": "^0.22.0",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.6"
   },
   "dependencies": {
     "fflate": "^0.8.2",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   }
 }