@willwade/aac-processors 0.3.1 → 0.3.3

package/dist/browser/utilities/analytics/metrics/vocabularyDump.js

@@ -0,0 +1,188 @@
+/**
+ * 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.
+ */
+/** Normalise an entry: trim, lowercase, collapse internal whitespace. */
+function normalize(text) {
+    return text.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+const UNTAGGED = 'Unknown';
+/** Per-source tally accumulated while walking the tree. */
+class SourceTally {
+    constructor() {
+        this.entries = 0;
+        this.words = new Set();
+        this.phrases = new Set();
+        this.byPos = new Map();
+    }
+    add(text, pos) {
+        const norm = normalize(text);
+        if (!norm)
+            return;
+        this.entries++;
+        if (/\s/.test(norm))
+            this.phrases.add(norm);
+        else
+            this.words.add(norm);
+        const tag = pos && pos.trim() ? pos.trim() : UNTAGGED;
+        let set = this.byPos.get(tag);
+        if (!set) {
+            set = new Set();
+            this.byPos.set(tag, set);
+        }
+        set.add(norm);
+    }
+    counts() {
+        const byPartOfSpeech = {};
+        for (const tag of Array.from(this.byPos.keys()).sort((a, b) => a.localeCompare(b))) {
+            byPartOfSpeech[tag] = this.byPos.get(tag).size;
+        }
+        return {
+            entries: this.entries,
+            uniqueWords: this.words.size,
+            uniquePhrases: this.phrases.size,
+            byPartOfSpeech,
+        };
+    }
+    get wordSet() {
+        return this.words;
+    }
+    get phraseSet() {
+        return this.phrases;
+    }
+}
+/**
+ * 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 function dumpVocabulary(tree, options) {
+    const pages = Object.values(tree.pages);
+    const buttonTally = new SourceTally();
+    const wordListTally = new SourceTally();
+    const predictionTally = new SourceTally();
+    let wordListCount = 0;
+    let buttonsWithDictionaries = 0;
+    let totalButtons = 0;
+    for (const page of pages) {
+        totalButtons += page.buttons.length;
+        if (page.wordListItems && page.wordListItems.length > 0) {
+            wordListCount++;
+            for (const item of page.wordListItems) {
+                wordListTally.add(item.text, item.partOfSpeech);
+            }
+        }
+        for (const btn of page.buttons) {
+            const label = btn.label?.trim();
+            if (label) {
+                buttonTally.add(label, btn.pos);
+            }
+            // Prediction dictionaries: parameters.predictions keeps the original
+            // Prediction.PredictThis words even after analyze() expands
+            // btn.predictions with morphological forms.
+            const dict = btn.parameters?.predictions;
+            if (Array.isArray(dict) && dict.length > 0) {
+                buttonsWithDictionaries++;
+                for (const w of dict) {
+                    if (typeof w === 'string') {
+                        predictionTally.add(w, btn.pos);
+                    }
+                }
+            }
+        }
+    }
+    // Smart-grammar word forms: inflected forms generated by MetricsCalculator
+    // (is_word_form buttons), excluding the original dictionary words they
+    // were generated from.
+    let wordForms = null;
+    let formTally = null;
+    if (options?.metrics) {
+        const originals = new Set();
+        for (const page of pages) {
+            for (const btn of page.buttons) {
+                const dict = btn.parameters?.predictions;
+                if (Array.isArray(dict)) {
+                    for (const w of dict) {
+                        if (typeof w === 'string') {
+                            const norm = normalize(w);
+                            if (norm)
+                                originals.add(norm);
+                        }
+                    }
+                }
+            }
+        }
+        formTally = new SourceTally();
+        const parents = new Set();
+        const seen = new Set();
+        for (const b of options.metrics.buttons) {
+            if (!b.is_word_form)
+                continue;
+            const norm = normalize(b.label);
+            if (!norm || seen.has(norm) || originals.has(norm))
+                continue;
+            seen.add(norm);
+            formTally.add(b.label, b.pos);
+            if (b.parent_button_id)
+                parents.add(b.parent_button_id);
+        }
+        wordForms = { ...formTally.counts(), parentButtons: parents.size };
+    }
+    const combinedWords = new Set([
+        ...buttonTally.wordSet,
+        ...wordListTally.wordSet,
+        ...predictionTally.wordSet,
+        ...(formTally ? formTally.wordSet : []),
+    ]);
+    const combinedPhrases = new Set([
+        ...buttonTally.phraseSet,
+        ...wordListTally.phraseSet,
+        ...predictionTally.phraseSet,
+    ]);
+    return {
+        schema: 'aac-vocabulary-dump/v1',
+        generatedAt: new Date().toISOString(),
+        source: {
+            format: tree.metadata?.format,
+            name: tree.metadata?.name,
+            locale: tree.metadata?.locale,
+        },
+        summary: {
+            totalBoards: pages.length,
+            totalButtons,
+            buttons: buttonTally.counts(),
+            wordLists: { ...wordListTally.counts(), lists: wordListCount },
+            predictionDictionaries: {
+                ...predictionTally.counts(),
+                buttonsWithDictionaries,
+            },
+            wordForms,
+            combined: {
+                uniqueEntries: combinedWords.size + combinedPhrases.size,
+                uniqueWords: combinedWords.size,
+                uniquePhrases: combinedPhrases.size,
+            },
+        },
+    };
+}

package/dist/cli/index.js

@@ -6,6 +6,7 @@ const prettyPrint_1 = require("./prettyPrint");
 const analyze_1 = require("../core/analyze");
 const history_1 = require("../utilities/analytics/history");
 const analytics_1 = require("../utilities/analytics");
+const zip_1 = require("../utils/zip");
 const aac_1 = require("../types/aac");
 const io_1 = require("../utils/io");
 const node_fs_1 = require("node:fs");
@@ -28,6 +29,26 @@ async function detectFormat(filePath) {
     if (filePath.endsWith('.gtbz')) {
         return 'gotalknow';
     }
+    // GoTalk NOW share exports keep their book suffix before the archive
+    // extension ("MyBook.gotalk-book.zip") — route on the book suffix.
+    if (/\.gotalk-book(\.|$)/i.test(filePath)) {
+        return 'gotalknow';
+    }
+    // Bare .zip: sniff the archive for GoTalk NOW plists (root or nested
+    // <BookName>.gotalk-book/ folder). Other zip-based formats (.obz, .spb,
+    // .gridset) always arrive with their own extension.
+    if (filePath.toLowerCase().endsWith('.zip')) {
+        try {
+            const zip = await (0, zip_1.getZipAdapter)(filePath, io_1.defaultFileAdapter);
+            const files = zip.listFiles();
+            const hasGoTalkPlists = files.some((f) => !f.startsWith('__MACOSX/') && /(^|\/)PageData\.plist$/.test(f.replace(/\\/g, '/')));
+            if (hasGoTalkPlists)
+                return 'gotalknow';
+        }
+        catch {
+            /* not a readable zip — fall through to extension-based detection */
+        }
+    }
     // Otherwise use file extension
     return (0, io_1.extname)(filePath).slice(1);
 }
@@ -438,6 +459,64 @@ commander_1.program
         process.exit(1);
     }
 });
+commander_1.program
+    .command('vocabulary <file>')
+    .description('Counts-only vocabulary inventory: buttons, wordlists, prediction dictionaries and word forms (no word lists are emitted)')
+    .option('--format <format>', 'Format type (auto-detected if not specified)')
+    .option('--out <path>', 'Write output to a file instead of stdout')
+    .option('--preserve-all-buttons', 'Preserve all buttons including navigation/system buttons')
+    .option('--no-exclude-navigation', "Don't exclude navigation buttons (Home, Back)")
+    .option('--no-exclude-system', "Don't exclude system buttons (Delete, Clear, etc.)")
+    .option('--exclude-buttons <list>', 'Comma-separated list of button labels/terms to exclude')
+    .option('--gridset-password <password>', 'Password for encrypted Grid3 archives (.gridsetx)')
+    .option('--no-smart-grammar', 'Skip smart-grammar word-form counts')
+    .action(async (file, options) => {
+    try {
+        const filteringOptions = parseFilteringOptions(options);
+        const format = options.format || (await detectFormat(file));
+        const processor = (0, analyze_1.getProcessor)(format, filteringOptions);
+        // The gridset loader logs debug chatter to stdout; silence it so the
+        // command's stdout is exactly one JSON document.
+        const silenced = Object.entries(console).reduce((acc, [k, fn]) => {
+            acc[k] = fn;
+            return acc;
+        }, {});
+        for (const k of ['log', 'info', 'debug', 'warn']) {
+            console[k] = () => { };
+        }
+        let dump;
+        try {
+            const tree = await processor.loadIntoTree(file);
+            // analyze() first: it expands morphological predictions on the tree,
+            // which dumpVocabulary() needs for the word-form counts.
+            const metrics = new analytics_1.MetricsCalculator().analyze(tree, {
+                useSmartGrammar: options.smartGrammar,
+            });
+            dump = (0, analytics_1.dumpVocabulary)(tree, { metrics });
+        }
+        finally {
+            for (const [k, fn] of Object.entries(silenced)) {
+                console[k] = fn;
+            }
+        }
+        const result = {
+            format,
+            filtering: filteringOptions,
+            vocabulary: dump,
+        };
+        const output = JSON.stringify(result, null, 2);
+        if (options.out) {
+            await writeTextToPath(options.out, output);
+        }
+        else {
+            console.log(output);
+        }
+    }
+    catch (error) {
+        console.error('Error dumping vocabulary:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
 // Show help if no command provided
 if (process.argv.length <= 2) {
     commander_1.program.help();

package/dist/core/analyze.js

@@ -49,6 +49,7 @@ function getProcessor(format, options) {
         case 'gotalknow':
         case 'gotalk':
         case 'gtbz': // GoTalk NOW file extension
+        case 'gotalk-book': // GoTalk NOW share export (e.g. "MyBook.gotalk-book.zip")
             return new gotalkNowProcessor_1.GotalkNowProcessor(options);
         default:
             throw new Error('Unknown format: ' + format);

package/dist/index.browser.js

@@ -96,6 +96,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_2.GotalkNowProcessor(options);
+    }
     switch (extension.toLowerCase()) {
         case '.dot':
             return new dotProcessor_2.DotProcessor(options);
@@ -138,6 +144,7 @@ function getSupportedExtensions() {
         '.plist',
         '.grd',
         '.gtbz',
+        '.gotalk-book',
     ];
 }
 /**

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;
     }