From 0f3fa533e4890d2abf71854f04a445bc307be5c3 Mon Sep 17 00:00:00 2001
From: will wade <willwade@gmail.com>
Date: Wed, 19 Aug 2026 01:26:10 +0100
Subject: [PATCH] Support GoTalk NOW .gotalk-book share exports: nested layout,
 image resolution, format routing

---
 CHANGELOG.md                         |  20 +++
 src/cli/index.ts                     |  23 ++++
 src/core/analyze.ts                  |   1 +
 src/index.browser.ts                 |   8 ++
 src/index.node.ts                    |   8 ++
 src/processors/gotalkNowProcessor.ts | 191 +++++++++++++++++++++++----
 test/cli.comprehensive.test.ts       |  39 ++++++
 test/gotalkNowProcessor.test.ts      | 190 +++++++++++++++++++++++++-
 test/index.entrypoints.test.ts       |  19 +++
 9 files changed, 469 insertions(+), 30 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 11807ca..c350a79 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     `core/analyze`, CLI `detectFormat`, `package.json` exports, and a new
     `GotalkNow` namespace.
   - Conversion utility: `scripts/conversion/convert-gtbz-to-obz.js`.
+- **GoTalk NOW `.gotalk-book` share exports.** Real-world books shared from the
+  app arrive as ZIPs with everything nested under a `<BookName>.gotalk-book/`
+  folder (often `.zip`-suffixed, sometimes with macOS `__MACOSX/` resource-fork
+  entries). The processor now locates the plists in either layout and
+  `processTexts` round-trips the nested structure in place.
+- **GoTalk NOW format routing.** `MyBook.gotalk-book.zip` / `.gotalk-book`
+  names route to the GoTalk processor in `getProcessor` (Node + browser;
+  `.gotalk-book` added to supported extensions), and the CLI sniffs bare
+  `.zip` archives for GoTalk plists.
+- **GoTalk NOW image resolution.** Bundled button images are matched by
+  basename (case-insensitive, with extension guessing) against the archive —
+  `Location`/`QuickRecoveryPath` are iOS container paths that never match entry
+  names. Entries sourced from the app's "GoTalk Image Library" clip-art are
+  skipped in favour of the user's own image, and a pre-rendered
+  `<page>-<button>-<buttonCount>.png` snapshot is the final fallback. Symbol
+  libraries are detected generically (`metacom`/`pcs`/`symbolstix`/`widgit`).
+- **GoTalk NOW semantics.** `JumpTo` sentinels (`0`, `-1`, empty) no longer
+  produce phantom navigation targets; sparse pages without `ButtonCount` are
+  sized by highest button index + 1; non-square counts derive a near-square
+  rectangle (cols = ⌈√n⌉, rows = ⌈n/cols⌉) instead of a forced square.
 
 ### Fixed
 
diff --git a/src/cli/index.ts b/src/cli/index.ts
index bdbc2dc..14eba9e 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -10,6 +10,7 @@ import {
 } from '../utilities/analytics/history';
 import { ComparisonAnalyzer, MetricsCalculator, dumpVocabulary } from '../utilities/analytics';
 import type { VocabularyDump } from '../utilities/analytics';
+import { getZipAdapter } from '../utils/zip';
 import { CellScanningOrder, ScanningSelectionMethod } from '../types/aac';
 import { defaultFileAdapter, extname } from '../utils/io';
 import { readFileSync } from 'node:fs';
@@ -37,6 +38,28 @@ async function detectFormat(filePath: string): Promise<string> {
   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 getZipAdapter(filePath, defaultFileAdapter);
+      const files = zip.listFiles();
+      const hasGoTalkPlists = files.some(
+        (f: string) =>
+          !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 extname(filePath).slice(1);
diff --git a/src/core/analyze.ts b/src/core/analyze.ts
index 8852c54..8a72fad 100644
--- a/src/core/analyze.ts
+++ b/src/core/analyze.ts
@@ -49,6 +49,7 @@ export function getProcessor(format: string, options?: ProcessorOptions): BasePr
     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(options);
     default:
       throw new Error('Unknown format: ' + format);
diff --git a/src/index.browser.ts b/src/index.browser.ts
index 4fe1ccd..a9938b8 100644
--- a/src/index.browser.ts
+++ b/src/index.browser.ts
@@ -65,6 +65,13 @@ export function getProcessor(
     ? 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);
@@ -108,6 +115,7 @@ export function getSupportedExtensions(): string[] {
     '.plist',
     '.grd',
     '.gtbz',
+    '.gotalk-book',
   ];
 }
 
diff --git a/src/index.node.ts b/src/index.node.ts
index fe7542b..e43440d 100644
--- a/src/index.node.ts
+++ b/src/index.node.ts
@@ -86,6 +86,13 @@ export function getProcessor(
     ? 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);
@@ -137,6 +144,7 @@ export function getSupportedExtensions(): string[] {
     '.plist',
     '.grd',
     '.gtbz',
+    '.gotalk-book',
   ];
 }
 
diff --git a/src/processors/gotalkNowProcessor.ts b/src/processors/gotalkNowProcessor.ts
index 2250b62..5f8291b 100644
--- a/src/processors/gotalkNowProcessor.ts
+++ b/src/processors/gotalkNowProcessor.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.
@@ -135,7 +142,8 @@ function buildSemanticAction(
   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,
@@ -144,7 +152,7 @@ function buildSemanticAction(
           platformData: {
             gotalkNow: { buttonType: 'Jump', jumpTo, jumpBook: actionData.JumpBook },
           },
-          fallback: { type: 'NAVIGATE', targetPageId: target },
+          fallback: target ? { type: 'NAVIGATE', targetPageId: target } : { type: 'ACTION' },
         },
         message: '',
         targetPageId: target,
@@ -254,12 +262,67 @@ function buildSemanticAction(
 }
 
 /**
- * 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: number): { rows: number; cols: number } {
-  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: unknown): boolean {
+  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: string | undefined): string | null {
+  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: Map<string, string>,
+  candidates: Array<string | undefined>
+): { entry: string; ext: string } | null {
+  const tried = new Set<string>();
+  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;
 }
 
 // ---------------------------------------------------------------------------
@@ -286,17 +349,33 @@ class GotalkNowProcessor extends BaseProcessor {
     return zip;
   }
 
+  /**
+   * 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(files: string[], basename: string, prefix: string): string | null {
+    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;
+  }
+
   private async readPlistFromZip(
     zip: Awaited<ReturnType<typeof this.options.zipAdapter>>,
     name: string,
+    resolvedName: string | null,
     fallback?: () => PlistValue
   ): Promise<PlistValue> {
-    const files = zip.listFiles();
-    if (!files.includes(name)) {
+    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')
@@ -336,13 +415,23 @@ class GotalkNowProcessor extends BaseProcessor {
 
     try {
       zip = await this.openZip(filePathOrBuffer);
-      pageDataValue = await this.readPlistFromZip(zip, 'PageData.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),
         () => [] as unknown as PlistValue
       );
-      bookInfoValue = await this.readPlistFromZip(zip, 'BookInfo.plist', () => ({}) as PlistValue);
+      bookInfoValue = await this.readPlistFromZip(
+        zip,
+        'BookInfo.plist',
+        this.resolveEntryName(files, 'BookInfo.plist', prefix),
+        () => ({}) as PlistValue
+      );
     } catch (err: any) {
       if (err instanceof ValidationFailureError) throw err;
       const validation = buildValidationResultFromMessage({
@@ -386,6 +475,14 @@ 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<string, string>();
+    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<string>([...Object.keys(pageData), ...orderedPageIds]);
@@ -442,7 +539,11 @@ 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: (AACButton | null)[][] = Array.from({ length: rows }, () =>
@@ -485,17 +586,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.
@@ -567,8 +698,12 @@ class GotalkNowProcessor extends BaseProcessor {
 
     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')
@@ -600,14 +735,14 @@ class GotalkNowProcessor extends BaseProcessor {
 
     // Repack: copy every original entry verbatim, replacing only PageData.plist.
     const outputZip = await this.options.zipAdapter(undefined, this.options.fileAdapter);
-    const files: { name: string; data: string | Uint8Array }[] = [];
+    const filesOut: { name: string; data: string | Uint8Array }[] = [];
     for (const name of originalZip.listFiles()) {
-      if (name === 'PageData.plist') continue;
-      files.push({ name, data: await originalZip.readFile(name) });
+      if (name === pdEntry) continue;
+      filesOut.push({ name, data: await originalZip.readFile(name) });
     }
-    files.push({ name: 'PageData.plist', data: rebuiltPageData });
+    filesOut.push({ name: pdEntry, data: rebuiltPageData });
 
-    const outputBuffer = await outputZip.writeFiles(files);
+    const outputBuffer = await outputZip.writeFiles(filesOut);
     await writeBinaryToPath(outputPath, outputBuffer);
 
     return outputBuffer;
diff --git a/test/cli.comprehensive.test.ts b/test/cli.comprehensive.test.ts
index a0f9b2f..af7ed18 100644
--- a/test/cli.comprehensive.test.ts
+++ b/test/cli.comprehensive.test.ts
@@ -374,6 +374,45 @@ describe('CLI Comprehensive Tests', () => {
         console.log('Skipping test - example.gridset not found');
       }
     });
+
+    it('should route GoTalk NOW share exports (.gotalk-book.zip and bare .zip)', async () => {
+      // Minimal nested share export: plists under <BookName>.gotalk-book/.
+      const AdmZip = require('adm-zip');
+      const plist = require('plist');
+      const zip = new AdmZip();
+      const DIR = 'Demo Book.gotalk-book';
+      const pageData = {
+        1: {
+          ButtonCount: 1,
+          PageTitle: 'Wunsch',
+          Buttons: {
+            '0': { ActionData: { TTSText: '' }, ButtonText: 'Hallo', ButtonType: 'TTS' },
+          },
+        },
+      };
+      zip.addFile(
+        `${DIR}/BookInfo.plist`,
+        Buffer.from(plist.build({ GoTalkBookFormatVersion: 1 }))
+      );
+      zip.addFile(`${DIR}/PageData.plist`, Buffer.from(plist.build(pageData)));
+      zip.addFile(`${DIR}/PageOrder.plist`, Buffer.from(plist.build([1])));
+
+      const bookPath = path.join(tempDir, 'Demo.gotalk-book.zip');
+      const plainZipPath = path.join(tempDir, 'Demo-plain.zip');
+      zip.writeZip(bookPath);
+      fs.copyFileSync(bookPath, plainZipPath);
+
+      // Book-suffix routing and bare-.zip content sniffing both land on the
+      // GoTalk processor and extract the page title + button label.
+      for (const target of [bookPath, plainZipPath]) {
+        const result = execSync(`node ${cliPath} extract ${target}`, {
+          encoding: 'utf8',
+          cwd: tempDir,
+        });
+        expect(result).toContain('Wunsch');
+        expect(result).toContain('Hallo');
+      }
+    });
   });
 
   describe('Error Handling Tests', () => {
diff --git a/test/gotalkNowProcessor.test.ts b/test/gotalkNowProcessor.test.ts
index 9bf1a2a..39337e4 100644
--- a/test/gotalkNowProcessor.test.ts
+++ b/test/gotalkNowProcessor.test.ts
@@ -136,8 +136,8 @@ describe('GotalkNowProcessor', () => {
       const processor = new GotalkNowProcessor();
       const tree = await processor.loadIntoTree(fixturePath);
       const page1 = tree.pages['1'];
-      // ButtonCount 2 → sqrt ceil = 2 → 2x2 grid.
-      expect(page1.grid.length).toBe(2);
+      // ButtonCount 2 → near-square rectangle: 2 cols × 1 row.
+      expect(page1.grid.length).toBe(1);
       expect(page1.grid[0].length).toBe(2);
     });
 
@@ -274,4 +274,190 @@ describe('GotalkNowProcessor', () => {
       expect(decodeNsFont(blob).fontFamily).toBeUndefined();
     });
   });
+
+  // -------------------------------------------------------------------------
+  // .gotalk-book share-export variant: everything nested under
+  // <BookName>.gotalk-book/, __MACOSX cruft, snapshot images, library symbols.
+  // Synthetic fixture modelled on real share exports (no real-user data).
+  // -------------------------------------------------------------------------
+  describe('gotalk-book share export variant', () => {
+    const nestedFixturePath = path.join(__dirname, 'temp_gotalkbook_fixture.gotalk-book.zip');
+    const nestedTranslateOut = path.join(__dirname, 'temp_gotalkbook_translated.zip');
+    const DIR = 'Demo Book.gotalk-book';
+
+    function buildNestedFixture(outPath: string): void {
+      const zip = new AdmZip();
+      const bookInfo = { GoTalkBookFormatVersion: 1 };
+      const pageData = {
+        1: {
+          ButtonCount: 9,
+          PageTitle: 'Wunsch',
+          Buttons: {
+            // Library symbol (Metacom): no bundled file should be resolved.
+            '0': {
+              ActionData: { TTSText: '' },
+              ButtonText: 'trinken',
+              ButtonType: 'TTS',
+              ButtonImages: [
+                {
+                  SourceLibrary: 'Metacom',
+                  SourceImageName: 'symbols/trinken.png',
+                  QuickRecoveryPath: 'var/mobile/Containers/…/trinken.png',
+                },
+              ],
+            },
+            // Bundled user image: QuickRecoveryPath is an iOS container path;
+            // resolution must happen by basename against the archive.
+            '1': {
+              ActionData: { TTSText: '' },
+              ButtonText: 'Hund',
+              ButtonType: 'TTS',
+              ButtonImages: [
+                {
+                  SourceLibrary: '',
+                  QuickRecoveryPath: 'var/mobile/Containers/…/Documents/my-dog.JPG',
+                },
+              ],
+            },
+            // Two entries where the first is app clip-art ("GoTalk Image
+            // Library"): the second entry is the user's snapshot image.
+            '2': {
+              ActionData: { TTSText: '' },
+              ButtonText: 'Pause',
+              ButtonType: 'TTS',
+              ButtonImages: [
+                { SourceLibrary: 'GoTalk Image Library', SourceImageName: 'clipart/break' },
+                { SourceLibrary: '', Location: 'somewhere/1-2-9.png' },
+              ],
+            },
+            // No usable image entry at all -> snapshot fallback <page>-<btn>-<count>.
+            '3': {
+              ActionData: { TTSText: '' },
+              ButtonText: 'fertig',
+              ButtonType: 'TTS',
+              ButtonImages: [{ SourceLibrary: '', Location: 'gone/missing.png' }],
+            },
+            // Jump with the sentinel value 0 -> no navigation target.
+            '4': {
+              ActionData: { JumpTo: 0, TTSText: '' },
+              ButtonText: 'zurück',
+              ButtonType: 'Jump',
+            },
+            // Jump with a real target.
+            '5': {
+              ActionData: { JumpTo: 2, TTSText: '' },
+              ButtonText: 'weiter',
+              ButtonType: 'Jump',
+            },
+          },
+        },
+        // Sparse buttons, no ButtonCount: grid size = max(index)+1 = 3.
+        2: {
+          PageTitle: 'Gefühle',
+          Buttons: {
+            '0': { ActionData: { TTSText: '' }, ButtonText: 'ja', ButtonType: 'TTS' },
+            '2': { ActionData: { TTSText: '' }, ButtonText: 'nein', ButtonType: 'TTS' },
+          },
+        },
+      };
+      const pageOrder = [1, 2];
+
+      const p = (name: string): string => `${DIR}/${name}`;
+      zip.addFile(p('BookInfo.plist'), Buffer.from(plist.build(bookInfo)));
+      zip.addFile(
+        p('PageData.plist'),
+        Buffer.from(plist.build(pageData as unknown as plist.PlistValue))
+      );
+      zip.addFile(p('PageOrder.plist'), Buffer.from(plist.build(pageOrder)));
+      zip.addFile(p('PageHistory.plist'), Buffer.from(plist.build([])));
+      // Bundled images: extension guessing + case-insensitive basename.
+      zip.addFile(p('my-dog.jpg'), Buffer.from('dog-bytes'));
+      // Snapshot render (exact name page-btn-count.png).
+      zip.addFile(p('1-2-9.png'), Buffer.from('snap-1-2'));
+      zip.addFile(p('1-3-9.png'), Buffer.from('snap-1-3'));
+      // macOS resource-fork cruft that must be ignored.
+      zip.addFile(`__MACOSX/${DIR}/._PageData.plist`, Buffer.from('resource fork junk'));
+
+      zip.writeZip(outPath);
+    }
+
+    beforeAll(() => {
+      buildNestedFixture(nestedFixturePath);
+    });
+
+    afterAll(() => {
+      for (const p of [nestedFixturePath, nestedTranslateOut]) {
+        if (fs.existsSync(p)) fs.unlinkSync(p);
+      }
+    });
+
+    it('loads a nested .gotalk-book export (prefix + __MACOSX tolerance)', async () => {
+      const processor = new GotalkNowProcessor();
+      const tree = await processor.loadIntoTree(nestedFixturePath);
+      expect(Object.keys(tree.pages).sort()).toEqual(['1', '2']);
+      expect(tree.metadata.defaultHomePageId).toBe('1');
+      expect(tree.pages['1'].name).toBe('Wunsch');
+    });
+
+    it('resolves bundled images by basename with extension guessing', async () => {
+      const processor = new GotalkNowProcessor();
+      const tree = await processor.loadIntoTree(nestedFixturePath);
+      const btn = tree.pages['1'].buttons.find((b) => b.label === 'Hund');
+      expect(btn!.resolvedImageEntry).toBe(`${DIR}/my-dog.jpg`);
+    });
+
+    it('marks library symbols without resolving a bundled file', async () => {
+      const processor = new GotalkNowProcessor();
+      const tree = await processor.loadIntoTree(nestedFixturePath);
+      const btn = tree.pages['1'].buttons.find((b) => b.label === 'trinken');
+      expect(btn!.symbolLibrary).toBe('Metacom');
+      expect(btn!.symbolPath).toBe('symbols/trinken.png');
+      expect(btn!.resolvedImageEntry).toBeUndefined();
+    });
+
+    it('skips GoTalk Image Library clip-art and picks the user image entry', async () => {
+      const processor = new GotalkNowProcessor();
+      const tree = await processor.loadIntoTree(nestedFixturePath);
+      const btn = tree.pages['1'].buttons.find((b) => b.label === 'Pause');
+      expect(btn!.symbolLibrary).not.toBe('GoTalk Image Library');
+      expect(btn!.resolvedImageEntry).toBe(`${DIR}/1-2-9.png`);
+    });
+
+    it('falls back to the rendered snapshot <page>-<btn>-<count>.png', async () => {
+      const processor = new GotalkNowProcessor();
+      const tree = await processor.loadIntoTree(nestedFixturePath);
+      const btn = tree.pages['1'].buttons.find((b) => b.label === 'fertig');
+      expect(btn!.resolvedImageEntry).toBe(`${DIR}/1-3-9.png`);
+    });
+
+    it('treats JumpTo 0 as no jump but keeps real Jump targets', async () => {
+      const processor = new GotalkNowProcessor();
+      const tree = await processor.loadIntoTree(nestedFixturePath);
+      const back = tree.pages['1'].buttons.find((b) => b.label === 'zurück');
+      const fwd = tree.pages['1'].buttons.find((b) => b.label === 'weiter');
+      expect(back!.targetPageId).toBeUndefined();
+      expect(fwd!.targetPageId).toBe('2');
+    });
+
+    it('sizes sparse pages by max button index + 1', async () => {
+      const processor = new GotalkNowProcessor();
+      const tree = await processor.loadIntoTree(nestedFixturePath);
+      const page2 = tree.pages['2'];
+      // max index 2 -> count 3 -> cols 2, rows 2 (near-square).
+      expect(page2.grid.length).toBe(2);
+      expect(page2.grid[0].length).toBe(2);
+    });
+
+    it('processTexts round-trips a nested export without flattening it', async () => {
+      const processor = new GotalkNowProcessor();
+      const translations = new Map([['ja', 'yes']]);
+      await processor.processTexts(nestedFixturePath, translations, nestedTranslateOut);
+      const out = new AdmZip(nestedTranslateOut);
+      const names = out.getEntries().map((e) => e.entryName);
+      expect(names).toContain(`${DIR}/PageData.plist`);
+      expect(names).toContain(`${DIR}/my-dog.jpg`);
+      expect(names).toContain(`__MACOSX/${DIR}/._PageData.plist`); // cruft preserved
+      expect(names).not.toContain('PageData.plist'); // not hoisted to root
+    });
+  });
 });
diff --git a/test/index.entrypoints.test.ts b/test/index.entrypoints.test.ts
index fc3cc90..b15c448 100644
--- a/test/index.entrypoints.test.ts
+++ b/test/index.entrypoints.test.ts
@@ -2,6 +2,7 @@ import * as browserEntry from '../src/index.browser';
 import * as nodeEntry from '../src/index.node';
 import { DotProcessor } from '../src/processors/dotProcessor';
 import { GridsetProcessor } from '../src/processors/gridsetProcessor';
+import { GotalkNowProcessor } from '../src/processors/gotalkNowProcessor';
 import { SnapProcessor } from '../src/processors/snapProcessor';
 import { TouchChatProcessor } from '../src/processors/touchchatProcessor';
 
@@ -42,4 +43,22 @@ describe('entrypoint exports', () => {
     );
     expect(() => nodeEntry.getProcessor('.unknown')).toThrow();
   });
+
+  it('routes GoTalk NOW share exports by book suffix, not final extension', () => {
+    // "MyBook.gotalk-book.zip" ends in .zip but must route to GotalkNow.
+    const nodeProc = nodeEntry.getProcessor('MyBook.gotalk-book.zip');
+    const browserProc = browserEntry.getProcessor('MyBook.gotalk-book.zip');
+    expect(nodeProc).toBeInstanceOf(GotalkNowProcessor);
+    expect(browserProc).toBeInstanceOf(GotalkNowProcessor);
+
+    // Bare book suffix without an archive extension.
+    expect(nodeEntry.getProcessor('MyBook.gotalk-book')).toBeInstanceOf(GotalkNowProcessor);
+
+    // Declared in the supported-extensions list (upload filters).
+    expect(nodeEntry.isExtensionSupported('.gotalk-book')).toBe(true);
+    expect(browserEntry.isExtensionSupported('.gotalk-book')).toBe(true);
+
+    // Plain .zip files stay unsupported (content sniffing is CLI-only).
+    expect(() => nodeEntry.getProcessor('plain.zip')).toThrow();
+  });
 });