@willwade/aac-processors 0.3.2 → 0.3.4

package/dist/index.node.js

@@ -102,6 +102,12 @@ function getProcessor(filePathOrExtension, options) {
     const extension = filePathOrExtension.includes('.')
         ? filePathOrExtension.substring(filePathOrExtension.lastIndexOf('.'))
         : filePathOrExtension;
+    // GoTalk NOW share exports keep their book suffix before the archive
+    // extension (e.g. "MyBook.gotalk-book.zip"), so match on the name, not the
+    // final extension.
+    if (/\.gotalk-book(\.|$)/i.test(filePathOrExtension)) {
+        return new gotalkNowProcessor_1.GotalkNowProcessor(options);
+    }
     switch (extension.toLowerCase()) {
         case '.dot':
             return new dotProcessor_1.DotProcessor(options);
@@ -152,6 +158,7 @@ function getSupportedExtensions() {
         '.plist',
         '.grd',
         '.gtbz',
+        '.gotalk-book',
     ];
 }
 /**

package/dist/metrics.d.ts

@@ -10,6 +10,8 @@ export * from './utilities/analytics/metrics/obl-types';
 export { OblUtil, OblAnonymizer } from './utilities/analytics/metrics/obl';
 export { MetricsCalculator } from './utilities/analytics/metrics/core';
 export { VocabularyAnalyzer } from './utilities/analytics/metrics/vocabulary';
+export { dumpVocabulary } from './utilities/analytics/metrics/vocabularyDump';
+export type { VocabularyDump, VocabularyDumpOptions, VocabularySourceCounts, VocabularySummary, } from './utilities/analytics/metrics/vocabularyDump';
 export { SentenceAnalyzer } from './utilities/analytics/metrics/sentence';
 export { ComparisonAnalyzer } from './utilities/analytics/metrics/comparison';
 export { MorphologyEngine } from './utilities/analytics/morphology';

package/dist/metrics.js

@@ -20,7 +20,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadReferenceDataFromUrl = exports.createBrowserReferenceLoader = exports.InMemoryReferenceLoader = exports.ReferenceLoader = exports.WordFormGenerator = exports.MorphologyEngine = exports.ComparisonAnalyzer = exports.SentenceAnalyzer = exports.VocabularyAnalyzer = exports.MetricsCalculator = exports.OblAnonymizer = exports.OblUtil = void 0;
+exports.loadReferenceDataFromUrl = exports.createBrowserReferenceLoader = exports.InMemoryReferenceLoader = exports.ReferenceLoader = exports.WordFormGenerator = exports.MorphologyEngine = exports.ComparisonAnalyzer = exports.SentenceAnalyzer = exports.dumpVocabulary = exports.VocabularyAnalyzer = exports.MetricsCalculator = exports.OblAnonymizer = exports.OblUtil = void 0;
 __exportStar(require("./utilities/analytics/metrics/types"), exports);
 __exportStar(require("./utilities/analytics/metrics/effort"), exports);
 __exportStar(require("./utilities/analytics/metrics/obl-types"), exports);
@@ -31,6 +31,8 @@ var core_1 = require("./utilities/analytics/metrics/core");
 Object.defineProperty(exports, "MetricsCalculator", { enumerable: true, get: function () { return core_1.MetricsCalculator; } });
 var vocabulary_1 = require("./utilities/analytics/metrics/vocabulary");
 Object.defineProperty(exports, "VocabularyAnalyzer", { enumerable: true, get: function () { return vocabulary_1.VocabularyAnalyzer; } });
+var vocabularyDump_1 = require("./utilities/analytics/metrics/vocabularyDump");
+Object.defineProperty(exports, "dumpVocabulary", { enumerable: true, get: function () { return vocabularyDump_1.dumpVocabulary; } });
 var sentence_1 = require("./utilities/analytics/metrics/sentence");
 Object.defineProperty(exports, "SentenceAnalyzer", { enumerable: true, get: function () { return sentence_1.SentenceAnalyzer; } });
 var comparison_1 = require("./utilities/analytics/metrics/comparison");

package/dist/processors/gotalkNowProcessor.d.ts

@@ -17,6 +17,13 @@
  *   - Backup-<n>.zip        – rolling backups
  *   - REQUIRESREGEN         – marker file
  *
+ * Two on-disk variants exist and both are accepted:
+ *   - `.gtbz` app backups: plists at the ZIP root.
+ *   - `.gotalk-book` share exports (often `.zip`-suffixed): everything nested
+ *     under a `<BookName>.gotalk-book/` folder, possibly alongside `__MACOSX/`
+ *     resource-fork entries (ignored). Button images are pre-rendered
+ *     snapshots named `<page>-<button>-<buttonCount>.png`.
+ *
  * Colours and fonts in PageData are NSKeyedArchiver-encoded binary plists
  * carried inside `<data>` tags. They are treated as opaque blobs and preserved
  * verbatim so that only text fields are touched during translation.
@@ -32,6 +39,13 @@ declare class GotalkNowProcessor extends BaseProcessor {
     };
     constructor(options?: ProcessorOptions);
     private openZip;
+    /**
+     * Resolve a plist entry name inside the archive, tolerating both layout
+     * variants: `.gtbz` (plists at ZIP root) and `.gotalk-book` share exports
+     * (plists nested under a `<BookName>.gotalk-book/` folder). `__MACOSX`
+     * resource-fork entries are ignored. Returns the full entry name, or null.
+     */
+    private resolveEntryName;
     private readPlistFromZip;
     extractTexts(filePathOrBuffer: ProcessorInput): Promise<string[]>;
     loadIntoTree(filePathOrBuffer: ProcessorInput): Promise<AACTree>;

package/dist/processors/gotalkNowProcessor.js

@@ -18,6 +18,13 @@
  *   - Backup-<n>.zip        – rolling backups
  *   - REQUIRESREGEN         – marker file
  *
+ * Two on-disk variants exist and both are accepted:
+ *   - `.gtbz` app backups: plists at the ZIP root.
+ *   - `.gotalk-book` share exports (often `.zip`-suffixed): everything nested
+ *     under a `<BookName>.gotalk-book/` folder, possibly alongside `__MACOSX/`
+ *     resource-fork entries (ignored). Button images are pre-rendered
+ *     snapshots named `<page>-<button>-<buttonCount>.png`.
+ *
  * Colours and fonts in PageData are NSKeyedArchiver-encoded binary plists
  * carried inside `<data>` tags. They are treated as opaque blobs and preserved
  * verbatim so that only text fields are touched during translation.
@@ -45,7 +52,8 @@ function buildSemanticAction(rawButton, pageId, buttonIndex) {
     switch (buttonType) {
         case 'Jump': {
             const jumpTo = actionData.JumpTo;
-            const target = jumpTo !== undefined ? String(jumpTo) : undefined;
+            // GoTalk treats 0 / -1 / "" as "no jump configured".
+            const target = !isNoJumpTarget(jumpTo) ? String(jumpTo) : undefined;
             return {
                 semanticAction: {
                     category: treeStructure_1.AACSemanticCategory.NAVIGATION,
@@ -54,7 +62,7 @@ function buildSemanticAction(rawButton, pageId, buttonIndex) {
                     platformData: {
                         gotalkNow: { buttonType: 'Jump', jumpTo, jumpBook: actionData.JumpBook },
                     },
-                    fallback: { type: 'NAVIGATE', targetPageId: target },
+                    fallback: target ? { type: 'NAVIGATE', targetPageId: target } : { type: 'ACTION' },
                 },
                 message: '',
                 targetPageId: target,
@@ -163,12 +171,62 @@ function buildSemanticAction(rawButton, pageId, buttonIndex) {
     }
 }
 /**
- * Derive a square-ish grid layout from the declared button count.
- * GoTalk NOW uses fixed layouts (1, 4, 9, 16, 25, 36 …).
+ * Derive a GoTalk NOW layout from the declared button count.
+ * GoTalk NOW uses fixed square layouts (1, 4, 9, 16, 25, 36 …); when the
+ * count is not a perfect square (alternate/custom layouts), fall back to a
+ * near-square rectangle: cols = ceil(sqrt(n)), rows = ceil(n / cols).
  */
 function gridDimensionsFromButtonCount(count) {
-    const side = Math.max(1, Math.ceil(Math.sqrt(Math.max(count, 1))));
-    return { rows: side, cols: side };
+    const n = Math.max(count, 1);
+    const side = Math.ceil(Math.sqrt(n));
+    return { rows: Math.ceil(n / side), cols: side };
+}
+/** GoTalk treats JumpTo 0 / -1 / "" as "no jump". */
+function isNoJumpTarget(value) {
+    return (value === undefined ||
+        value === null ||
+        value === 0 ||
+        value === -1 ||
+        value === '' ||
+        value === '0' ||
+        value === '-1');
+}
+/** Normalise a zip or iOS-container path to a lowercase basename. */
+function basenameLower(p) {
+    if (!p)
+        return null;
+    const base = p.replace(/\\/g, '/').split('/').pop() || '';
+    const trimmed = base.trim().toLowerCase();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Resolve a bundled image for a button against the archive's file list.
+ *
+ * `Location`/`QuickRecoveryPath` values are iOS app-container paths that never
+ * match archive entry names verbatim, so candidates are matched by basename
+ * (case-insensitive), with extension guessing when the name has none.
+ */
+function findZipImageEntry(zipBasenames, candidates) {
+    const tried = new Set();
+    for (const candidate of candidates) {
+        const base = basenameLower(candidate);
+        if (!base || tried.has(base))
+            continue;
+        tried.add(base);
+        // 1. Exact basename match.
+        const direct = zipBasenames.get(base);
+        if (direct) {
+            const ext = base.includes('.') ? base.slice(base.lastIndexOf('.')) : '.png';
+            return { entry: direct, ext };
+        }
+        // 2. Try common image extensions.
+        for (const ext of ['.png', '.jpg', '.jpeg', '.bmp']) {
+            const hit = zipBasenames.get(base + ext);
+            if (hit)
+                return { entry: hit, ext };
+        }
+    }
+    return null;
 }
 // ---------------------------------------------------------------------------
 // Processor
@@ -187,14 +245,27 @@ class GotalkNowProcessor extends baseProcessor_1.BaseProcessor {
         const zip = await this.options.zipAdapter(filePathOrBuffer, this.options.fileAdapter);
         return zip;
     }
-    async readPlistFromZip(zip, name, fallback) {
-        const files = zip.listFiles();
-        if (!files.includes(name)) {
+    /**
+     * Resolve a plist entry name inside the archive, tolerating both layout
+     * variants: `.gtbz` (plists at ZIP root) and `.gotalk-book` share exports
+     * (plists nested under a `<BookName>.gotalk-book/` folder). `__MACOSX`
+     * resource-fork entries are ignored. Returns the full entry name, or null.
+     */
+    resolveEntryName(files, basename, prefix) {
+        const rooted = `${prefix}${basename}`;
+        if (files.includes(rooted))
+            return rooted;
+        // Nested variant: find the (non-__MACOSX) entry ending in /<basename>.
+        const matches = files.filter((f) => f !== `__MACOSX` && !f.startsWith('__MACOSX/') && f.endsWith(`/${basename}`));
+        return matches.length > 0 ? matches[0] : null;
+    }
+    async readPlistFromZip(zip, name, resolvedName, fallback) {
+        if (!resolvedName) {
             if (fallback)
                 return fallback();
             throw new Error(`GoTalk NOW archive is missing ${name}`);
         }
-        const bytes = await zip.readFile(name);
+        const bytes = await zip.readFile(resolvedName);
         const text = typeof Buffer !== 'undefined' && Buffer.isBuffer(bytes)
             ? bytes.toString('utf8')
             : new TextDecoder().decode(bytes);
@@ -227,9 +298,13 @@ class GotalkNowProcessor extends baseProcessor_1.BaseProcessor {
         let bookInfoValue;
         try {
             zip = await this.openZip(filePathOrBuffer);
-            pageDataValue = await this.readPlistFromZip(zip, 'PageData.plist');
-            pageOrderValue = await this.readPlistFromZip(zip, 'PageOrder.plist', () => []);
-            bookInfoValue = await this.readPlistFromZip(zip, 'BookInfo.plist', () => ({}));
+            // Resolve plist locations once; shared by load/processTexts round-trip.
+            const files = zip.listFiles();
+            const pdEntry = this.resolveEntryName(files, 'PageData.plist', '');
+            const prefix = pdEntry ? pdEntry.slice(0, -'PageData.plist'.length) : '';
+            pageDataValue = await this.readPlistFromZip(zip, 'PageData.plist', pdEntry);
+            pageOrderValue = await this.readPlistFromZip(zip, 'PageOrder.plist', this.resolveEntryName(files, 'PageOrder.plist', prefix), () => []);
+            bookInfoValue = await this.readPlistFromZip(zip, 'BookInfo.plist', this.resolveEntryName(files, 'BookInfo.plist', prefix), () => ({}));
         }
         catch (err) {
             if (err instanceof validationTypes_1.ValidationFailureError)
@@ -268,6 +343,16 @@ class GotalkNowProcessor extends baseProcessor_1.BaseProcessor {
         }
         // Track available image files so we can resolve ButtonImages locations.
         const zipFiles = new Set(zip.listFiles());
+        // Basename (lowercase, non-__MACOSX) -> full entry name, for tolerant
+        // matching of bundled images in .gotalk-book share exports.
+        const zipBasenames = new Map();
+        for (const f of zipFiles) {
+            if (f.startsWith('__MACOSX/') || f.endsWith('/'))
+                continue;
+            const base = basenameLower(f);
+            if (base && !zipBasenames.has(base))
+                zipBasenames.set(base, f);
+        }
         // Build pages. Use the union of PageData keys and PageOrder ids.
         const allPageIds = new Set([...Object.keys(pageData), ...orderedPageIds]);
         // Deterministic ordering: ordered pages first (in order), then any extras sorted numerically.
@@ -317,7 +402,10 @@ class GotalkNowProcessor extends baseProcessor_1.BaseProcessor {
             const buttonsById = rawPage.Buttons || {};
             // Numeric sort of button indices ("0","1",…,"10",…)
             const buttonIndices = Object.keys(buttonsById).sort((a, b) => Number(a) - Number(b));
-            const buttonCount = rawPage.ButtonCount ?? buttonIndices.length;
+            // Sparse button maps: the grid size is max(index)+1, not the number of
+            // keys (GoTalk snapshots and layouts are sized by the highest slot).
+            const buttonCount = rawPage.ButtonCount ??
+                (buttonIndices.length > 0 ? Math.max(...buttonIndices.map(Number)) + 1 : 0);
             const { rows, cols } = gridDimensionsFromButtonCount(buttonCount);
             const gridLayout = Array.from({ length: rows }, () => Array.from({ length: cols }, () => null));
             buttonIndices.forEach((btnIndex, i) => {
@@ -347,19 +435,47 @@ class GotalkNowProcessor extends baseProcessor_1.BaseProcessor {
                     };
                 }
                 // Resolve image metadata.
-                const images = rawButton.ButtonImages;
-                if (Array.isArray(images) && images.length > 0) {
-                    const first = images[0];
-                    if (first?.Location) {
-                        button.image = first.Location;
-                        if (zipFiles.has(first.Location)) {
-                            button.resolvedImageEntry = first.Location;
+                // Heuristics (from real .gotalk-book share exports):
+                //   - entries sourced from the app's bundled "GoTalk Image Library"
+                //     are clip-art, not user content — skip them;
+                //   - prefer the entry carrying QuickRecoveryPath; with multiple
+                //     entries the second one is the user's image;
+                //   - bundled files are matched by basename (Location/QRP are iOS
+                //     container paths, never archive entry names);
+                //   - last resort: the pre-rendered snapshot <page>-<btn>-<count>.png.
+                const imagesAll = rawButton.ButtonImages;
+                const images = Array.isArray(imagesAll)
+                    ? imagesAll.filter((im) => (im?.SourceLibrary || '') !== 'GoTalk Image Library')
+                    : [];
+                if (images.length > 0) {
+                    const selected = images.find((im) => im.QuickRecoveryPath !== undefined) ??
+                        (images.length >= 2 ? images[1] : images[0]);
+                    if (selected) {
+                        const sourceLibrary = (selected.SourceLibrary || '').toLowerCase();
+                        const sourceImageName = selected.SourceImageName || '';
+                        const isLibrarySymbol = /metacom|pcs|symbolstix|widgit/.test(sourceLibrary) && sourceImageName.length > 0;
+                        if (selected.Location)
+                            button.image = selected.Location;
+                        if (selected.SourceLibrary)
+                            button.symbolLibrary = selected.SourceLibrary;
+                        if (sourceImageName)
+                            button.symbolPath = sourceImageName;
+                        if (!isLibrarySymbol) {
+                            const bundled = findZipImageEntry(zipBasenames, [
+                                selected.QuickRecoveryPath,
+                                selected.Location,
+                                selected.SourceImageName,
+                                `${pageId}-${btnIndex}-${buttonCount}.png`,
+                            ]);
+                            if (bundled) {
+                                button.image = bundled.entry;
+                                button.resolvedImageEntry = bundled.entry;
+                            }
+                        }
+                        else if (zipFiles.has(selected.Location || '')) {
+                            button.resolvedImageEntry = selected.Location;
                         }
                     }
-                    if (first?.SourceLibrary)
-                        button.symbolLibrary = first.SourceLibrary;
-                    if (first?.SourceImageName)
-                        button.symbolPath = first.SourceImageName;
                 }
                 // Visibility: GoTalk buttons can be disabled via either field.
                 if (rawButton.Enabled === false || rawButton.Disabled === true) {
@@ -413,8 +529,12 @@ class GotalkNowProcessor extends baseProcessor_1.BaseProcessor {
     async processTexts(filePathOrBuffer, translations, outputPath) {
         const { writeBinaryToPath } = this.options.fileAdapter;
         const originalZip = await this.openZip(filePathOrBuffer);
-        // Parse PageData and apply translations in place.
-        const pageDataBytes = await originalZip.readFile('PageData.plist');
+        // Parse PageData and apply translations in place. Locate the plist the
+        // same tolerant way loadIntoTree does (root or nested .gotalk-book folder)
+        // and write it back under its original entry name so the layout survives.
+        const files = originalZip.listFiles();
+        const pdEntry = this.resolveEntryName(files, 'PageData.plist', '') ?? 'PageData.plist';
+        const pageDataBytes = await originalZip.readFile(pdEntry);
         const pageDataText = typeof Buffer !== 'undefined' && Buffer.isBuffer(pageDataBytes)
             ? pageDataBytes.toString('utf8')
             : new TextDecoder().decode(pageDataBytes);
@@ -441,14 +561,14 @@ class GotalkNowProcessor extends baseProcessor_1.BaseProcessor {
         const rebuiltPageData = plist_1.default.build(pageData);
         // Repack: copy every original entry verbatim, replacing only PageData.plist.
         const outputZip = await this.options.zipAdapter(undefined, this.options.fileAdapter);
-        const files = [];
+        const filesOut = [];
         for (const name of originalZip.listFiles()) {
-            if (name === 'PageData.plist')
+            if (name === pdEntry)
                 continue;
-            files.push({ name, data: await originalZip.readFile(name) });
+            filesOut.push({ name, data: await originalZip.readFile(name) });
         }
-        files.push({ name: 'PageData.plist', data: rebuiltPageData });
-        const outputBuffer = await outputZip.writeFiles(files);
+        filesOut.push({ name: pdEntry, data: rebuiltPageData });
+        const outputBuffer = await outputZip.writeFiles(filesOut);
         await writeBinaryToPath(outputPath, outputBuffer);
         return outputBuffer;
     }

package/dist/types/aac.d.ts

@@ -126,6 +126,7 @@ export interface AACPage {
     descriptionHtml?: string;
     images?: any[];
     sounds?: any[];
+    wordListItems?: AACWordListItem[];
     semantic_ids?: string[];
     clone_ids?: string[];
     scanningConfig?: ScanningConfig;

package/dist/utilities/analytics/competence.d.ts

@@ -34,6 +34,7 @@
  * conflates linguistic/operational/strategic/social competence in AAC); it is
  * reported only as a distribution.
  */
+import type { VocabularySummary } from './metrics/vocabularyDump';
 /** A single spoken utterance with a production timestamp (epoch ms). */
 export interface CompetenceUtterance {
     text: string;
@@ -117,6 +118,19 @@ export declare function morphologicalDiversity(words: WordStream, options?: Dive
  * Returns null (unavailable) if no dictionary is provided.
  */
 export declare function spellingValidity(words: WordStream, dictionary?: Set<string>): number | null;
+export interface LexicalRichness {
+    /** Brunet's index W = N · V^(-0.165). Range ~10–30; LOWER = richer. */
+    brunetsW: number | null;
+    /** Honoré's statistic R = 100·ln N / (1 − V1/V). HIGHER = richer. */
+    honoresR: number | null;
+    /** Hapax legomena (words used exactly once) — count only. */
+    hapax: number;
+    /** Number of distinct words (V). */
+    types: number;
+    /** Number of tokens (N). */
+    tokens: number;
+}
+export declare function lexicalRichness(words: WordStream): LexicalRichness;
 export interface DistributionStats {
     median: number | null;
     mean: number | null;
@@ -150,6 +164,8 @@ export interface MonthBin {
     morphologicalDiversity: DiversityResult;
     /** Phonological — only when a dictionary is supplied. */
     spellingValidity: number | null;
+    /** Lexical richness indices (Brunet's W, Honoré's R) — always available. */
+    lexicalRichness: LexicalRichness;
     /** True when the month has too little data to trust the diversity figures. */
     suppressed: boolean;
     suppressReason: string | null;
@@ -185,6 +201,12 @@ export interface PagesetSummary {
         base: number | null;
         perLetter: number | null;
     };
+    /**
+     * Counts-only vocabulary inventory (buttons, wordlists, prediction
+     * dictionaries, smart-grammar word forms) — see dumpVocabulary().
+     * Null/undefined when the caller did not compute it. Contains counts only.
+     */
+    vocabulary?: VocabularySummary | null;
     error?: string;
 }
 export interface UserSettingsSummary {

package/dist/utilities/analytics/competence.js

@@ -42,6 +42,7 @@ exports.lexicalDiversity = lexicalDiversity;
 exports.syntacticDiversity = syntacticDiversity;
 exports.morphologicalDiversity = morphologicalDiversity;
 exports.spellingValidity = spellingValidity;
+exports.lexicalRichness = lexicalRichness;
 exports.summarizeActivity = summarizeActivity;
 exports.analyzeTimeline = analyzeTimeline;
 /* ------------------------------------------------------------------ *
@@ -277,6 +278,21 @@ function spellingValidity(words, dictionary) {
     }
     return checked === 0 ? null : correct / checked;
 }
+function lexicalRichness(words) {
+    const n = words.length;
+    const freq = new Map();
+    for (const w of words)
+        freq.set(w, (freq.get(w) ?? 0) + 1);
+    const v = freq.size;
+    let v1 = 0;
+    for (const c of freq.values())
+        if (c === 1)
+            v1++;
+    const brunetsW = n > 0 && v > 0 ? n * Math.pow(v, -0.165) : null;
+    // Honoré's R is undefined when every word is a hapax (V1 = V) or N <= 1.
+    const honoresR = n > 1 && v > 0 && v1 < v ? (100 * Math.log(n)) / (1 - v1 / v) : null;
+    return { brunetsW, honoresR, hapax: v1, types: v, tokens: n };
+}
 function distribution(values) {
     return {
         median: median(values),
@@ -391,6 +407,9 @@ function analyzeTimeline(utterances, options = {}) {
                 classifyInflection: resources.classifyInflection,
             });
         const spell = suppressed ? null : spellingValidity(stream, dictionary);
+        const rich = suppressed
+            ? { brunetsW: null, honoresR: null, hapax: 0, types: 0, tokens: 0 }
+            : lexicalRichness(stream);
         timeline.push({
             month: key,
             utterances: activity.utterances,
@@ -402,6 +421,7 @@ function analyzeTimeline(utterances, options = {}) {
             syntacticDiversity: syn,
             morphologicalDiversity: mor,
             spellingValidity: spell,
+            lexicalRichness: rich,
             suppressed,
             suppressReason,
         });

package/dist/utilities/analytics/index.d.ts

@@ -18,6 +18,8 @@ export * from './metrics/obl-types';
 export { OblUtil, OblAnonymizer } from './metrics/obl';
 export { MetricsCalculator } from './metrics/core';
 export { VocabularyAnalyzer } from './metrics/vocabulary';
+export { dumpVocabulary } from './metrics/vocabularyDump';
+export type { VocabularyDump, VocabularyDumpOptions, VocabularySourceCounts, VocabularySummary, } from './metrics/vocabularyDump';
 export { SentenceAnalyzer } from './metrics/sentence';
 export { ComparisonAnalyzer } from './metrics/comparison';
 export { ReferenceLoader } from './reference';

package/dist/utilities/analytics/index.js

@@ -25,7 +25,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReferenceLoader = exports.ComparisonAnalyzer = exports.SentenceAnalyzer = exports.VocabularyAnalyzer = exports.MetricsCalculator = exports.OblAnonymizer = exports.OblUtil = void 0;
+exports.ReferenceLoader = exports.ComparisonAnalyzer = exports.SentenceAnalyzer = exports.dumpVocabulary = exports.VocabularyAnalyzer = exports.MetricsCalculator = exports.OblAnonymizer = exports.OblUtil = void 0;
 exports.getReferenceDataPath = getReferenceDataPath;
 exports.hasReferenceData = hasReferenceData;
 const io_1 = require("../../utils/io");
@@ -46,6 +46,8 @@ Object.defineProperty(exports, "MetricsCalculator", { enumerable: true, get: fun
 // Export vocabulary and comparison analyzers
 var vocabulary_1 = require("./metrics/vocabulary");
 Object.defineProperty(exports, "VocabularyAnalyzer", { enumerable: true, get: function () { return vocabulary_1.VocabularyAnalyzer; } });
+var vocabularyDump_1 = require("./metrics/vocabularyDump");
+Object.defineProperty(exports, "dumpVocabulary", { enumerable: true, get: function () { return vocabularyDump_1.dumpVocabulary; } });
 var sentence_1 = require("./metrics/sentence");
 Object.defineProperty(exports, "SentenceAnalyzer", { enumerable: true, get: function () { return sentence_1.SentenceAnalyzer; } });
 var comparison_1 = require("./metrics/comparison");

package/dist/utilities/analytics/metrics/vocabularyDump.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Vocabulary Dump (counts-only)
+ *
+ * Inventory of the vocabulary available in an AAC pageset, aggregated by
+ * source and part of speech. Only counts are emitted — never word lists —
+ * so the output is safe to embed in privacy-preserving reports.
+ *
+ * Sources counted:
+ *   buttons              — labelled buttons (the static on-board vocabulary)
+ *   wordLists            — page WordLists feeding dynamic AutoContent cells
+ *                          (Grid 3 `<WordList>`; absent in other formats)
+ *   predictionDictionaries — prediction wordlists attached to prediction cells
+ *                          (Grid 3 `Prediction.PredictThis` dictionaries)
+ *   wordForms            — smart-grammar inflections generated by
+ *                          MetricsCalculator (only when a MetricsResult is
+ *                          supplied)
+ *
+ * Non-Grid 3 formats simply report zeros for the Grid 3-specific sources.
+ */
+import type { AACTree } from '../../../types/aac';
+import type { MetricsResult } from './types';
+/** Counts for one vocabulary source. */
+export interface VocabularySourceCounts {
+    /** Total entries found in this source (before deduplication). */
+    entries: number;
+    /** Unique single words after normalisation. */
+    uniqueWords: number;
+    /** Unique multi-word phrases after normalisation (e.g. "thank you"). */
+    uniquePhrases: number;
+    /** Unique entries per part-of-speech tag ('Unknown' when untagged). */
+    byPartOfSpeech: Record<string, number>;
+}
+/** Aggregated, counts-only vocabulary inventory. */
+export interface VocabularySummary {
+    totalBoards: number;
+    totalButtons: number;
+    /** Vocabulary carried by labelled buttons. */
+    buttons: VocabularySourceCounts;
+    /** Page WordLists (dynamic content cells; Grid 3). */
+    wordLists: VocabularySourceCounts & {
+        lists: number;
+    };
+    /** Prediction dictionaries attached to prediction cells (Grid 3). */
+    predictionDictionaries: VocabularySourceCounts & {
+        buttonsWithDictionaries: number;
+    };
+    /** Smart-grammar inflections; null when no MetricsResult was supplied. */
+    wordForms: (VocabularySourceCounts & {
+        parentButtons: number;
+    }) | null;
+    /** Unique entries across all sources combined. */
+    combined: {
+        uniqueEntries: number;
+        uniqueWords: number;
+        uniquePhrases: number;
+    };
+}
+/** Full vocabulary dump document (schema-versioned). */
+export interface VocabularyDump {
+    schema: 'aac-vocabulary-dump/v1';
+    generatedAt: string;
+    source: {
+        format?: string;
+        name?: string;
+        locale?: string;
+    };
+    summary: VocabularySummary;
+}
+export interface VocabularyDumpOptions {
+    /**
+     * Precomputed metrics (MetricsCalculator.analyze). Enables the
+     * smart-grammar word-form counts. Run analyze() BEFORE dumpVocabulary():
+     * analyze() expands morphological predictions on the tree.
+     */
+    metrics?: MetricsResult;
+}
+/**
+ * Count the vocabulary available in a pageset, by source and part of speech.
+ * Emits counts only — no word lists.
+ *
+ * @example
+ * const processor = new GridsetProcessor();
+ * const tree = await processor.loadIntoTree('my.gridset');
+ * const metrics = new MetricsCalculator().analyze(tree);
+ * const dump = dumpVocabulary(tree, { metrics });
+ * console.log(dump.summary.wordLists.lists, 'wordlists');
+ */
+export declare function dumpVocabulary(tree: AACTree, options?: VocabularyDumpOptions): VocabularyDump;