@shayc/open-board-format 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @shayc/open-board-format
 
+## 0.4.2
+
+### Patch Changes
+
+- d2beda3: docs: ship the OBF spec mirror (`docs/external/open-board-format.md`) in the npm package
+
+  The README already points at this file; including it makes that link resolve
+  inside `node_modules` and gives offline tooling and coding agents the full
+  format semantics (specialty actions, string-list fallback, ID uniqueness)
+  that type declarations can't carry.
+
+## 0.4.1
+
+### Patch Changes
+
+- e7c9b47: docs: polish public API JSDoc for better IntelliSense
+
+  - Document every exported type alias (`OBFBoard`, `OBFButton`, …) so hover tooltips show a description instead of just the expanded type
+  - Move `ParsedOBZ` field docs from `@property` tags onto the fields themselves so they surface in editors
+  - Clarify `data_url` as an API endpoint (not a `data:` URI) and note it is outside the `data` → `path` → `url` fallback chain
+  - Document `action` vs `actions` precedence per the OBF spec
+  - Correct fflate compression-level scale (0–9), standardize `@throws` phrasing, example quoting, and module headers; tag `buildJsonParseErrorMessage` as `@internal`
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -210,7 +210,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup (Node 22+, Vitest,
 
 ## Related
 
-- [Open Board Format specification](https://www.openboardformat.org/docs) — the official standard and format documentation.
+- [Open Board Format specification](https://www.openboardformat.org/docs) — the official standard and format documentation. A 1:1 mirror is kept at [docs/external/open-board-format.md](docs/external/open-board-format.md) for offline reference.
 - [AAC Board AI](https://github.com/shayc/aac-board-ai) — an offline-first AAC web app built on this package, using on-device browser AI for grammar, tone, and translation ([live app](https://aacboard.app)).
 
 ## License

package/dist/index.d.mts

@@ -1,62 +1,78 @@
 import { z } from "zod";
 
 //#region src/schema.d.ts
-/**
-* Open Board Format (OBF) Zod Schemas
-*
-* These schemas represent the Open Board Format, designed for sharing communication boards and board sets
-* between Augmentative and Alternative Communication (AAC) applications.
-*
-* Official OBF specification: https://www.openboardformat.org/docs
-*
-* @author Shay Cojocaru
-* @license MIT
-*/
 /** 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>;
 /**
- * Format version of the Open Board Format, e.g., 'open-board-0.1'.
+ * Unique board-element identifier, coerced to a non-empty string.
+ * See {@link OBFIDSchema}.
  */
+type OBFID = z.infer<typeof OBFIDSchema>;
+/** Format version of the Open Board Format, e.g., `open-board-0.1`. */
 declare const OBFFormatVersionSchema: z.ZodString;
+/**
+ * Format version of the Open Board Format, e.g., `open-board-0.1`.
+ * See {@link OBFFormatVersionSchema}.
+ */
 type OBFFormatVersion = z.infer<typeof OBFFormatVersionSchema>;
 /**
- * Locale identifier, typically a BCP 47 language tag (e.g., 'en', 'en-US', 'fr-CA').
- * Not strictly validated — any string is accepted.
+ * Locale identifier, typically a BCP 47 language tag (e.g., `en`, `en-US`,
+ * `fr-CA`). Not strictly validated — any string is accepted.
  */
 declare const OBFLocaleCodeSchema: z.ZodString;
+/**
+ * Locale identifier, typically a BCP 47 language tag, e.g., `en`, `en-US`.
+ * See {@link OBFLocaleCodeSchema}.
+ */
 type OBFLocaleCode = z.infer<typeof OBFLocaleCodeSchema>;
 /**
- * Key–value pairs mapping symbolic names to their translations in a single locale.
+ * Translations for a single locale, keyed by the source string,
+ * e.g., `{ "hello": "hola" }`.
  */
 declare const OBFLocalizedStringsSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/**
+ * Translations for a single locale, keyed by the source string.
+ * See {@link OBFLocalizedStringsSchema}.
+ */
 type OBFLocalizedStrings = z.infer<typeof OBFLocalizedStringsSchema>;
 /**
  * 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>>;
+/**
+ * Locale-keyed dictionary of translated strings.
+ * See {@link OBFStringsSchema}.
+ */
 type OBFStrings = z.infer<typeof OBFStringsSchema>;
 /**
  * Spelling action: a `+` prefix followed by the text to append,
- * e.g., `"+hello"`.
+ * e.g., `+hello`.
  */
 declare const OBFSpellingActionSchema: z.ZodString;
+/**
+ * Spelling action: a `+` prefix followed by the text to append, e.g., `+hello`.
+ * See {@link OBFSpellingActionSchema}.
+ */
 type OBFSpellingAction = z.infer<typeof OBFSpellingActionSchema>;
 /**
- * Specialty action prefixed with `:`, e.g., `":clear"`.
+ * Specialty action prefixed with `:`, e.g., `:clear`.
  * Custom extensions use the `:ext_` prefix.
  */
 declare const OBFSpecialtyActionSchema: z.ZodString;
-type OBFSpecialtyAction = z.infer<typeof OBFSpecialtyActionSchema>;
 /**
- * Union of spelling and specialty actions that a button can trigger.
+ * Specialty action prefixed with `:`, e.g., `:clear`.
+ * See {@link OBFSpecialtyActionSchema}.
  */
+type OBFSpecialtyAction = z.infer<typeof OBFSpecialtyActionSchema>;
+/** 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>;
 /**
- * License terms and attribution for a resource.
+ * Union of spelling and specialty actions that a button can trigger.
+ * See {@link OBFButtonActionSchema}.
  */
+type OBFButtonAction = z.infer<typeof OBFButtonActionSchema>;
+/** License terms and attribution for a resource. */
 declare const OBFLicenseSchema: z.ZodObject<{
   type: z.ZodString;
   copyright_notice_url: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodURL, z.ZodLiteral<"">]>, z.ZodTransform<string | undefined, string>>>;
@@ -65,14 +81,22 @@ declare const OBFLicenseSchema: z.ZodObject<{
   author_url: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodURL, z.ZodLiteral<"">]>, z.ZodTransform<string | undefined, string>>>;
   author_email: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodEmail, z.ZodLiteral<"">]>, z.ZodTransform<string | undefined, string>>>;
 }, z.core.$loose>;
+/**
+ * License terms and attribution for a resource.
+ * See {@link OBFLicenseSchema}.
+ */
 type OBFLicense = z.infer<typeof OBFLicenseSchema>;
 /**
  * Common properties for media resources (images and sounds).
  *
  * When multiple references are provided, they should be used in the following order:
- * 1. data
- * 2. path
- * 3. url
+ * 1. `data`
+ * 2. `path`
+ * 3. `url`
+ *
+ * `data_url` is not part of this fallback chain — it is an API endpoint for
+ * retrieving information about the resource, not an alternative source of
+ * the media bytes.
  */
 declare const OBFMediaSchema: z.ZodObject<{
   id: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>, z.ZodString>;
@@ -90,14 +114,20 @@ declare const OBFMediaSchema: z.ZodObject<{
     author_email: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodEmail, z.ZodLiteral<"">]>, z.ZodTransform<string | undefined, string>>>;
   }, z.core.$loose>>;
 }, z.core.$loose>;
-type OBFMedia = z.infer<typeof OBFMediaSchema>;
 /**
- * Reference to a symbol in a proprietary symbol set (e.g., SymbolStix).
+ * Common properties for media resources (images and sounds).
+ * See {@link OBFMediaSchema}.
  */
+type OBFMedia = z.infer<typeof OBFMediaSchema>;
+/** Reference to a symbol in a proprietary symbol set (e.g., SymbolStix). */
 declare const OBFSymbolInfoSchema: z.ZodObject<{
   set: z.ZodString;
   filename: z.ZodString;
 }, z.core.$loose>;
+/**
+ * Reference to a symbol in a proprietary symbol set.
+ * See {@link OBFSymbolInfoSchema}.
+ */
 type OBFSymbolInfo = z.infer<typeof OBFSymbolInfoSchema>;
 /**
  * Image resource, extending {@link OBFMediaSchema} with optional
@@ -131,6 +161,10 @@ declare const OBFImageSchema: z.ZodObject<{
   width: z.ZodOptional<z.ZodNumber>;
   height: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
+/**
+ * Image resource with optional symbol and dimension properties.
+ * See {@link OBFImageSchema}.
+ */
 type OBFImage = z.infer<typeof OBFImageSchema>;
 /**
  * Audio resource. Identical to {@link OBFMediaSchema} — no additional properties.
@@ -151,10 +185,12 @@ declare const OBFSoundSchema: z.ZodObject<{
     author_email: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodEmail, z.ZodLiteral<"">]>, z.ZodTransform<string | undefined, string>>>;
   }, z.core.$loose>>;
 }, z.core.$loose>;
-type OBFSound = z.infer<typeof OBFSoundSchema>;
 /**
- * Reference to another board, resolved by ID, path, or URL.
+ * Audio resource, identical to {@link OBFMedia}.
+ * See {@link OBFSoundSchema}.
  */
+type OBFSound = z.infer<typeof OBFSoundSchema>;
+/** 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>>>;
   name: z.ZodOptional<z.ZodString>;
@@ -162,6 +198,10 @@ declare const OBFLoadBoardSchema: z.ZodObject<{
   url: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodURL, z.ZodLiteral<"">]>, z.ZodTransform<string | undefined, string>>>;
   path: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
+/**
+ * Reference to another board, resolved by ID, path, or URL.
+ * See {@link OBFLoadBoardSchema}.
+ */
 type OBFLoadBoard = z.infer<typeof OBFLoadBoardSchema>;
 /**
  * Interactive element on a board, optionally linked to images, sounds, and actions.
@@ -188,6 +228,10 @@ declare const OBFButtonSchema: z.ZodObject<{
   width: z.ZodOptional<z.ZodNumber>;
   height: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
+/**
+ * Interactive element on a board, optionally linked to images, sounds, and
+ * actions. See {@link OBFButtonSchema}.
+ */
 type OBFButton = z.infer<typeof OBFButtonSchema>;
 /**
  * Row-and-column layout that arranges buttons by their IDs.
@@ -197,6 +241,10 @@ declare const OBFGridSchema: z.ZodObject<{
   columns: z.ZodNumber;
   order: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>, z.ZodString>, z.ZodNull]>>>;
 }, z.core.$loose>;
+/**
+ * Row-and-column layout that arranges buttons by their IDs.
+ * See {@link OBFGridSchema}.
+ */
 type OBFGrid = z.infer<typeof OBFGridSchema>;
 /**
  * Root object of an `.obf` file: the complete definition of a single communication board.
@@ -283,6 +331,10 @@ declare const OBFBoardSchema: z.ZodObject<{
   }, z.core.$loose>>;
   strings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>>;
 }, z.core.$loose>;
+/**
+ * The complete definition of a single communication board — root object of
+ * an `.obf` file. See {@link OBFBoardSchema}.
+ */
 type OBFBoard = z.infer<typeof OBFBoardSchema>;
 /**
  * Table of contents for an `.obz` package, mapping resource IDs to their archive paths.
@@ -296,6 +348,10 @@ declare const OBFManifestSchema: z.ZodObject<{
     sounds: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   }, z.core.$loose>;
 }, z.core.$loose>;
+/**
+ * Table of contents for an `.obz` package, mapping resource IDs to their
+ * archive paths. See {@link OBFManifestSchema}.
+ */
 type OBFManifest = z.infer<typeof OBFManifestSchema>;
 //#endregion
 //#region src/obf.d.ts
@@ -308,7 +364,7 @@ type OBFManifest = z.infer<typeof OBFManifestSchema>;
  * @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.
+ * @throws {Error} If the JSON is malformed or fails schema validation.
  */
 declare function parseOBF(json: string): OBFBoard;
 /**
@@ -329,7 +385,7 @@ declare function loadOBF(file: File): Promise<OBFBoard>;
  * @param data - The value to validate.
  * @returns The validated board object.
  *
- * @throws {Error} If the value does not conform to the OBF schema.
+ * @throws {Error} If the value fails schema validation.
  */
 declare function validateOBF(data: unknown): OBFBoard;
 /**
@@ -343,20 +399,22 @@ declare function stringifyOBF(board: OBFBoard): string;
 //#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 rootBoard - The package's entry-point board — the one `manifest.root`
- *                       points at, already resolved. Same object as
- *                       `boards.get(rootBoard.id)`.
- * @property resources - Archive path → raw bytes for every entry in the archive,
- *                       including `manifest.json` and the `.obf` boards as well as
- *                       media such as images and sounds.
  */
 interface ParsedOBZ {
+  /** The package's table of contents. */
   manifest: OBFManifest;
+  /** Validated board objects keyed by board ID. */
   boards: Map<string, OBFBoard>;
+  /**
+   * The package's entry-point board — the one `manifest.root` points at,
+   * already resolved. Same object as `boards.get(rootBoard.id)`.
+   */
   rootBoard: OBFBoard;
+  /**
+   * Raw bytes for every entry in the archive, keyed by archive path —
+   * including `manifest.json` and the `.obf` boards as well as media
+   * such as images and sounds.
+   */
   resources: Map<string, Uint8Array>;
 }
 /**
@@ -406,9 +464,9 @@ declare function parseManifest(json: string): OBFManifest;
  * @returns A `Blob` containing the compressed OBZ archive.
  *
  * @throws {Error} If `rootBoardId` does not match any of the supplied boards.
- * @throws {Error} If two supplied boards share the same id.
+ * @throws {Error} If two supplied boards share the same ID.
  * @throws {Error} If a supplied board fails schema validation.
- * @throws {Error} If two boards declare the same media id with conflicting paths.
+ * @throws {Error} If two boards declare the same media ID with conflicting paths.
  * @throws {Error} If a board declares an image or sound `path` with no matching entry in `resources`.
  * @throws {Error} If a `resources` entry would overwrite the generated `manifest.json` or a board file.
  */
@@ -441,11 +499,11 @@ type LoadedBoard = {
  * Detect whether the input is a single OBF board or an OBZ package and load it
  * accordingly.
  *
- * The input is read once and its leading bytes are sniffed for the ZIP magic
- * prefix: a ZIP is treated as an `.obz` package, anything else as an `.obf`
- * board. This lets consumers accept either format from a single drag-and-drop,
- * file picker, or fetch response without inspecting the file extension or
- * re-deriving the OBF-vs-OBZ distinction themselves.
+ * Input that begins with the ZIP magic prefix is treated as an `.obz` package;
+ * anything else is parsed as an `.obf` board. The input is read once, so
+ * consumers can accept either format from a single drag-and-drop, file picker,
+ * or fetch response without inspecting the file extension or re-deriving the
+ * OBF-vs-OBZ distinction themselves.
  *
  * @param input - A `File` handle or `ArrayBuffer` holding `.obf` or `.obz` content.
  * @returns A discriminated union tagged by `format`.
@@ -456,13 +514,16 @@ type LoadedBoard = {
 declare function loadBoard(input: File | ArrayBuffer): Promise<LoadedBoard>;
 //#endregion
 //#region src/zip.d.ts
+/**
+ * Minimal ZIP helpers over fflate: signature sniffing, unzip, and zip.
+ */
 /**
  * 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.
+ * @throws {Error} If the archive is corrupt or cannot be decompressed.
  */
 declare function unzip(archive: ArrayBuffer): Promise<Map<string, Uint8Array>>;
 /**
@@ -475,7 +536,7 @@ declare function unzip(archive: ArrayBuffer): Promise<Map<string, Uint8Array>>;
  * @param entries - A map of file paths to their content bytes.
  * @returns The compressed archive as a `Uint8Array`.
  *
- * @throws {Error} If compression fails.
+ * @throws {Error} If fflate fails to compress an entry.
  */
 declare function zip(entries: Map<string, Uint8Array | ArrayBuffer>): Promise<Uint8Array>;
 /**