@willwade/aac-processors 0.3.1 → 0.3.3

package/dist/analytics.d.ts

@@ -5,3 +5,4 @@
  * This is separate from pageset metrics.
  */
 export * from './utilities/analytics/history';
+export * from './utilities/analytics/competence';

package/dist/analytics.js

@@ -21,3 +21,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./utilities/analytics/history"), exports);
+__exportStar(require("./utilities/analytics/competence"), exports);

package/dist/browser/index.browser.js

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

package/dist/browser/metrics.js

@@ -10,6 +10,7 @@ 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 { SentenceAnalyzer } from './utilities/analytics/metrics/sentence';
 export { ComparisonAnalyzer } from './utilities/analytics/metrics/comparison';
 export { MorphologyEngine } from './utilities/analytics/morphology';

package/dist/browser/processors/gotalkNowProcessor.js

@@ -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.
@@ -39,7 +46,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: AACSemanticCategory.NAVIGATION,
@@ -48,7 +56,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,
@@ -157,12 +165,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
@@ -181,14 +239,27 @@ class GotalkNowProcessor extends 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);
@@ -221,9 +292,13 @@ class GotalkNowProcessor extends 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 ValidationFailureError)
@@ -262,6 +337,16 @@ class GotalkNowProcessor extends 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.
@@ -311,7 +396,10 @@ class GotalkNowProcessor extends 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) => {
@@ -341,19 +429,47 @@ class GotalkNowProcessor extends 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) {
@@ -407,8 +523,12 @@ class GotalkNowProcessor extends 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);
@@ -435,14 +555,14 @@ class GotalkNowProcessor extends BaseProcessor {
         const rebuiltPageData = plist.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;
     }