@willwade/aac-processors 0.2.14 → 0.2.16

package/dist/browser/processors/gridsetProcessor.js

@@ -2227,9 +2227,8 @@ class GridsetProcessor extends BaseProcessor {
             await writeBinaryToPath(outputPath, originalBuffer);
             return;
         }
-        const AdmZip = (await import('adm-zip')).default;
-        const originalZip = new AdmZip(originalPath);
-        const outputZip = new AdmZip();
+        const originalZip = await this.options.zipAdapter(originalPath);
+        const outputZip = await this.options.zipAdapter();
         // Check if any page has pending mutations
         const hasPendingMutations = Object.values(tree.pages).some((page) => page.pendingMutations.length > 0);
         if (hasPendingMutations) {
@@ -2246,15 +2245,13 @@ class GridsetProcessor extends BaseProcessor {
                 suppressBooleanAttributes: false,
             });
             GridsetSaveHandler.saveWithMutations(tree, originalZip, outputZip, parser, gridBuilder, (page) => this.createBasicGridXml(page));
-            // Copy remaining files
-            for (const entry of originalZip.getEntries()) {
-                if (entry.isDirectory)
-                    continue;
-                if (!outputZip.getEntry(entry.entryName)) {
-                    outputZip.addFile(entry.entryName, entry.getData());
-                }
+            // Copy files
+            const outputFiles = [];
+            for (const name of originalZip.listFiles()) {
+                const data = await originalZip.readFile(name);
+                outputFiles.push({ name, data });
             }
-            const outputBuffer = outputZip.toBuffer();
+            const outputBuffer = await outputZip.writeFiles(outputFiles);
             await writeBinaryToPath(outputPath, outputBuffer);
             return;
         }
@@ -2285,15 +2282,15 @@ class GridsetProcessor extends BaseProcessor {
             const gridPath = `Grids/${page.name}/grid.xml`;
             modifiedGridFiles.add(gridPath);
             // Try to get the original grid.xml file
-            const originalEntry = originalZip.getEntry(gridPath);
-            if (!originalEntry) {
+            const originalEntries = originalZip.listFiles();
+            if (!originalEntries.includes(gridPath)) {
                 // If original doesn't exist, create a new basic grid
                 const basicGrid = this.createBasicGridXml(page);
                 newGridFiles.set(gridPath, basicGrid);
                 continue;
             }
             // Parse the original grid XML
-            const originalContent = originalEntry.getData().toString('utf-8');
+            const originalContent = (await originalZip.readFile(gridPath)).toString();
             const originalGrid = parser.parse(originalContent);
             if (!originalGrid.Grid) {
                 // Invalid grid structure, create a basic one
@@ -2458,22 +2455,22 @@ class GridsetProcessor extends BaseProcessor {
             newGridFiles.set(gridPath, builtXml);
         }
         // Copy all files from original zip, replacing modified grid files
-        for (const entry of originalZip.getEntries()) {
-            if (entry.isDirectory)
-                continue;
+        const outputFiles = [];
+        for (const entry of originalZip.listFiles()) {
             // Skip grid.xml files that we're modifying
-            if (modifiedGridFiles.has(entry.entryName)) {
-                const newContent = newGridFiles.get(entry.entryName);
+            if (modifiedGridFiles.has(entry)) {
+                const newContent = newGridFiles.get(entry);
                 if (newContent) {
-                    outputZip.addFile(entry.entryName, Buffer.from(newContent, 'utf8'));
+                    outputFiles.push({ name: entry, data: Buffer.from(newContent, 'utf8') });
                 }
                 continue;
             }
             // Copy all other files as-is
-            outputZip.addFile(entry.entryName, entry.getData());
+            const data = await originalZip.readFile(entry);
+            outputFiles.push({ name: entry, data });
         }
         // Write the output ZIP
-        const outputBuffer = outputZip.toBuffer();
+        const outputBuffer = await outputZip.writeFiles(outputFiles);
         await writeBinaryToPath(outputPath, outputBuffer);
     }
     /**

package/dist/browser/processors/obfProcessor.js

@@ -741,24 +741,18 @@ class ObfProcessor extends BaseProcessor {
             await writeBinaryToPath(outputPath, originalBuffer);
             return;
         }
-        const AdmZip = (await import('adm-zip')).default;
-        const originalZip = new AdmZip(originalPath);
-        const outputZip = new AdmZip();
-        // Track which .obf files we're modifying
-        const modifiedObfFiles = new Set();
-        // Generate new .obf files for pages in the tree
-        const newObfFiles = new Map();
+        const originalZip = await this.options.zipAdapter(originalPath);
+        const outputZip = await this.options.zipAdapter();
+        const outputFiles = [];
         for (const page of Object.values(tree.pages)) {
-            const obfFilename = this.getPageFilename(page.id, tree.metadata);
-            modifiedObfFiles.add(obfFilename);
+            const name = this.getPageFilename(page.id, tree.metadata);
             // createObfBoardFromPage will automatically apply mutations if present
             const obfBoard = this.createObfBoardFromPage(page, 'Board', tree.metadata);
-            const obfContent = JSON.stringify(obfBoard, null, 2);
-            newObfFiles.set(obfFilename, obfContent);
+            const data = JSON.stringify(obfBoard, null, 2);
+            outputFiles.push({ name, data });
         }
         // Generate updated manifest if we have pages
         if (Object.keys(tree.pages).length > 0) {
-            modifiedObfFiles.add('manifest.json');
             const manifest = {
                 format: OBF_FORMAT_VERSION,
                 root: tree.metadata.defaultHomePageId,
@@ -771,25 +765,18 @@ class ObfProcessor extends BaseProcessor {
                     sounds: {},
                 },
             };
-            newObfFiles.set('manifest.json', JSON.stringify(manifest));
-        }
-        // Copy all files from original zip, replacing modified .obf files
-        for (const entry of originalZip.getEntries()) {
-            if (entry.isDirectory)
-                continue;
-            // Skip .obf files that we're modifying
-            if (modifiedObfFiles.has(entry.entryName)) {
-                const newContent = newObfFiles.get(entry.entryName);
-                if (newContent) {
-                    outputZip.addFile(entry.entryName, Buffer.from(newContent, 'utf8'));
-                }
-                continue;
+            const data = Buffer.from(JSON.stringify(manifest), 'utf8');
+            outputFiles.push({ name: 'manifest.json', data });
+        }
+        // Add remaining .obf from original zip
+        for (const entry of originalZip.listFiles()) {
+            if (!outputFiles.find((file) => file.name === entry)) {
+                const data = await originalZip.readFile(entry);
+                outputFiles.push({ name: entry, data });
             }
-            // Copy all other files as-is (preserves images, sounds, etc.)
-            outputZip.addFile(entry.entryName, entry.getData());
         }
         // Write the output ZIP
-        const outputBuffer = outputZip.toBuffer();
+        const outputBuffer = await outputZip.writeFiles(outputFiles);
         await writeBinaryToPath(outputPath, outputBuffer);
     }
     /**

package/dist/browser/processors/snapProcessor.js

@@ -39,7 +39,7 @@ class SnapProcessor extends BaseProcessor {
         super(options);
         this.capabilities = {
             wordList: 'none',
-            preservesAssetsOnSave: false,
+            preservesAssetsOnSave: true,
             newCellCreation: 'allowed',
         };
         this.symbolResolver = null;
@@ -810,6 +810,324 @@ class SnapProcessor extends BaseProcessor {
         await this.saveFromTree(tree, outputPath);
         return await readBinaryFromInput(outputPath);
     }
+    /**
+     * Save a modified tree while preserving the original SQLite schema and data.
+     *
+     * Strategy: copy the original .sps verbatim, then open the copy and replay
+     * `page.pendingMutations` as targeted SQL UPDATE/INSERT statements. Everything
+     * not in the mutation log (PageLayout, ScanGroup, image blobs, ContentTypeData,
+     * ButtonPageLink, etc.) is preserved byte-for-byte from the original.
+     *
+     * This is the asset-preserving counterpart to `saveFromTree` (which builds a
+     * stripped-down DB from scratch and is unsuitable for round-tripping real
+     * TD Snap page sets).
+     *
+     * Supported mutations:
+     * - updateButton(id, patch)  → UPDATE Button SET Label/Message WHERE Id = ?
+     * - removeButton(id)         → UPDATE ElementPlacement SET Visible = 0 for all
+     *                              placements pointing at the button's ElementReference
+     * - addButton(button)        → INSERT into ElementReference + Button + one
+     *                              ElementPlacement per existing PageLayout for
+     *                              the target page (so the button shows in every
+     *                              layout the user has). Image/audio not yet handled.
+     *
+     * WordList mutations are no-ops on Snap (capabilities.wordList === 'none').
+     */
+    async saveModifiedTree(originalPath, tree, outputPath) {
+        const { pathExists, mkDir, removePath, dirname, readBinaryFromInput, writeBinaryToPath } = this.options.fileAdapter;
+        if (!isNodeRuntime()) {
+            throw new Error('saveModifiedTree is only supported in Node.js for Snap files.');
+        }
+        const outputDir = dirname(outputPath);
+        if (!(await pathExists(outputDir))) {
+            await mkDir(outputDir, { recursive: true });
+        }
+        if (await pathExists(outputPath)) {
+            await removePath(outputPath);
+        }
+        // 1. Copy the original verbatim — preserves all 23+ tables, blobs, settings.
+        const originalBytes = await readBinaryFromInput(originalPath);
+        await writeBinaryToPath(outputPath, originalBytes);
+        // Short-circuit: if no page has any mutations, we're done.
+        const hasAnyMutations = Object.values(tree.pages).some((page) => page.pendingMutations.length > 0);
+        if (!hasAnyMutations) {
+            return;
+        }
+        // 2. Open the copy.
+        const Database = requireBetterSqlite3();
+        const db = new Database(outputPath, { readonly: false });
+        try {
+            // 3. Schema introspection — different Snap versions have different optional columns.
+            const tableColumns = (table) => {
+                try {
+                    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+                    return new Set(rows.map((r) => r.name));
+                }
+                catch {
+                    return new Set();
+                }
+            };
+            const buttonCols = tableColumns('Button');
+            const placementCols = tableColumns('ElementPlacement');
+            const hasPlacementVisible = placementCols.has('Visible');
+            const hasPlacementPageLayoutId = placementCols.has('PageLayoutId');
+            // 4. UniqueId → numeric Page.Id map.
+            const pageRows = db.prepare('SELECT Id, UniqueId FROM Page').all();
+            const uniqueIdToPageId = new Map();
+            for (const row of pageRows) {
+                if (row.UniqueId)
+                    uniqueIdToPageId.set(String(row.UniqueId), row.Id);
+                // Allow lookup by stringified numeric Id too, since loadIntoTree falls back to it.
+                uniqueIdToPageId.set(String(row.Id), row.Id);
+            }
+            const layoutsByPage = new Map();
+            try {
+                const layoutRows = db
+                    .prepare('SELECT Id, PageId, PageLayoutSetting FROM PageLayout')
+                    .all();
+                // Pre-load occupied placements per layout so we can avoid (x,y) collisions.
+                const placementsByLayout = new Map();
+                const placementRows = db
+                    .prepare('SELECT PageLayoutId, GridPosition FROM ElementPlacement WHERE GridPosition IS NOT NULL AND PageLayoutId IS NOT NULL')
+                    .all();
+                for (const r of placementRows) {
+                    let set = placementsByLayout.get(r.PageLayoutId);
+                    if (!set) {
+                        set = new Set();
+                        placementsByLayout.set(r.PageLayoutId, set);
+                    }
+                    set.add(r.GridPosition);
+                }
+                for (const row of layoutRows) {
+                    const parts = String(row.PageLayoutSetting ?? '').split(',');
+                    const cols = parseInt(parts[0], 10) || 4;
+                    const rows = parseInt(parts[1], 10) || 4;
+                    const info = {
+                        id: row.Id,
+                        cols,
+                        rows,
+                        occupied: placementsByLayout.get(row.Id) ?? new Set(),
+                    };
+                    const list = layoutsByPage.get(row.PageId);
+                    if (list)
+                        list.push(info);
+                    else
+                        layoutsByPage.set(row.PageId, [info]);
+                }
+            }
+            catch {
+                // PageLayout table may not exist on older schemas — placements get NULL PageLayoutId.
+            }
+            // Find first empty cell on a layout, starting from a preferred (x,y).
+            // Returns null if the layout is fully occupied.
+            const findFreeCell = (info, prefX, prefY) => {
+                const inBounds = (x, y) => x >= 0 && x < info.cols && y >= 0 && y < info.rows;
+                if (inBounds(prefX, prefY)) {
+                    const key = `${prefX},${prefY}`;
+                    if (!info.occupied.has(key)) {
+                        info.occupied.add(key);
+                        return key;
+                    }
+                }
+                for (let y = 0; y < info.rows; y++) {
+                    for (let x = 0; x < info.cols; x++) {
+                        const key = `${x},${y}`;
+                        if (!info.occupied.has(key)) {
+                            info.occupied.add(key);
+                            return key;
+                        }
+                    }
+                }
+                return null;
+            };
+            // Generate a UUID for new Button.UniqueId. Required: Node has crypto.randomUUID since 14.17.
+            const nodeCrypto = getNodeRequire()?.('crypto');
+            const uuid = () => nodeCrypto?.randomUUID
+                ? nodeCrypto.randomUUID()
+                : // Fallback (very unlikely path, but shouldn't break older Nodes)
+                    'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+                        const r = (Math.random() * 16) | 0;
+                        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+                        return v.toString(16);
+                    });
+            // 5. Next-available IDs for inserts.
+            const nextId = (table) => {
+                const row = db.prepare(`SELECT COALESCE(MAX(Id), 0) AS maxId FROM ${table}`).get();
+                return (row.maxId || 0) + 1;
+            };
+            let nextButtonId = nextId('Button');
+            let nextElementRefId = nextId('ElementReference');
+            let nextPlacementId = nextId('ElementPlacement');
+            // CommandSequence is optional but TD Snap crashes on some pages (e.g. dashboards
+            // like "Google Home Speaker") when a button has no CommandSequence row. Every
+            // button in the original DB has one. We track this only if the table exists.
+            const hasCommandSequence = tableColumns('CommandSequence').size > 0;
+            let nextCommandSequenceId = hasCommandSequence ? nextId('CommandSequence') : 0;
+            // 6. Replay mutations inside one transaction for atomicity + speed.
+            const replay = db.transaction(() => {
+                for (const page of Object.values(tree.pages)) {
+                    if (page.pendingMutations.length === 0)
+                        continue;
+                    const numericPageId = uniqueIdToPageId.get(String(page.id));
+                    if (numericPageId === undefined) {
+                        // eslint-disable-next-line no-console
+                        console.warn(`[Snap] saveModifiedTree: page "${page.name}" (${page.id}) not found in original DB; skipping ${page.pendingMutations.length} mutation(s)`);
+                        continue;
+                    }
+                    for (const mutation of page.pendingMutations) {
+                        switch (mutation.type) {
+                            case 'updateButton': {
+                                const sets = [];
+                                const args = [];
+                                if (mutation.patch.label !== undefined && buttonCols.has('Label')) {
+                                    sets.push('Label = ?');
+                                    args.push(mutation.patch.label);
+                                }
+                                if (mutation.patch.message !== undefined && buttonCols.has('Message')) {
+                                    sets.push('Message = ?');
+                                    args.push(mutation.patch.message);
+                                }
+                                if (sets.length === 0)
+                                    break;
+                                args.push(Number(mutation.buttonId));
+                                db.prepare(`UPDATE Button SET ${sets.join(', ')} WHERE Id = ?`).run(...args);
+                                break;
+                            }
+                            case 'removeButton': {
+                                // Hide all placements that reference the button's ElementReference.
+                                const buttonRow = db
+                                    .prepare('SELECT ElementReferenceId FROM Button WHERE Id = ?')
+                                    .get(Number(mutation.buttonId));
+                                if (!buttonRow || buttonRow.ElementReferenceId == null)
+                                    break;
+                                if (hasPlacementVisible) {
+                                    db.prepare('UPDATE ElementPlacement SET Visible = 0 WHERE ElementReferenceId = ?').run(buttonRow.ElementReferenceId);
+                                }
+                                else {
+                                    // Older schemas without Visible: delete the placements outright.
+                                    db.prepare('DELETE FROM ElementPlacement WHERE ElementReferenceId = ?').run(buttonRow.ElementReferenceId);
+                                }
+                                break;
+                            }
+                            case 'addButton': {
+                                const button = mutation.button;
+                                const elementRefId = nextElementRefId++;
+                                const buttonId = nextButtonId++;
+                                // ElementReference: TD Snap requires ElementType, ForegroundColor,
+                                // BackgroundColor, and AudioCueRecordingId to be non-NULL on render
+                                // — NULL values crash dashboard pages (e.g. "Google Home Speaker").
+                                // Defaults below match the modal values across real Snap files
+                                // (>99% of existing rows in Core First Scanning use them).
+                                const erColumns = tableColumns('ElementReference');
+                                const erCandidates = [
+                                    { col: 'Id', value: elementRefId },
+                                    { col: 'PageId', value: numericPageId },
+                                    { col: 'ElementType', value: 0 }, // 0 = button; only nonzero in 1/20608 rows
+                                    { col: 'ForegroundColor', value: -14934754 }, // dark text default (99.8% of rows)
+                                    { col: 'BackgroundColor', value: -132102 }, // light cell default (85.7% of rows)
+                                    { col: 'AudioCueRecordingId', value: 0 }, // 0 = no audio cue (99.99% of rows)
+                                ];
+                                const erFieldsPresent = erCandidates.filter((f) => erColumns.has(f.col));
+                                db.prepare(`INSERT INTO ElementReference (${erFieldsPresent
+                                    .map((f) => f.col)
+                                    .join(', ')}) VALUES (${erFieldsPresent.map(() => '?').join(', ')})`).run(...erFieldsPresent.map((f) => f.value));
+                                // Button: provide non-NULL defaults for columns TD Snap reads.
+                                // ContentType = 6 (normal speak button), CommandFlags = 8 (standard),
+                                // LabelOwnership / ImageOwnership = 3 (owned by this page set),
+                                // ActiveContentType = 0, BorderThickness = 0, UniqueId = fresh GUID,
+                                // image / sound / symbol IDs = 0 (= "no asset").
+                                const candidateFields = [
+                                    { col: 'Id', value: buttonId },
+                                    { col: 'Label', value: button.label || '' },
+                                    { col: 'Message', value: button.message || button.label || '' },
+                                    { col: 'ElementReferenceId', value: elementRefId },
+                                    { col: 'ContentType', value: 6 },
+                                    { col: 'CommandFlags', value: 8 },
+                                    { col: 'LabelOwnership', value: 3 },
+                                    { col: 'ImageOwnership', value: 3 },
+                                    { col: 'ActiveContentType', value: 0 },
+                                    { col: 'BorderThickness', value: 0 },
+                                    { col: 'UniqueId', value: uuid() },
+                                    { col: 'LibrarySymbolId', value: 0 },
+                                    { col: 'PageSetImageId', value: 0 },
+                                    { col: 'MessageRecordingId', value: 0 },
+                                    // UseMessageRecording: omit. 99.99% of existing rows have NULL,
+                                    // and forcing 0 makes Sarah/Mum the only outliers in the DB.
+                                    { col: 'SymbolColorDataId', value: 0 },
+                                ];
+                                const presentFields = candidateFields.filter((f) => buttonCols.has(f.col));
+                                const sql = `INSERT INTO Button (${presentFields
+                                    .map((f) => f.col)
+                                    .join(', ')}) VALUES (${presentFields.map(() => '?').join(', ')})`;
+                                db.prepare(sql).run(...presentFields.map((f) => f.value));
+                                // Insert a default CommandSequence row that explicitly speaks the
+                                // button's Label ($type:3 = MessageAction, value 0 = speak Label).
+                                // This is the most common pattern in real Snap files (9514 / 19402
+                                // buttons in Core First Scanning). Without an explicit action,
+                                // dashboard pages (e.g. "Google Home Speaker") crash on render —
+                                // empty $values is only used for hidden/help-text buttons.
+                                if (hasCommandSequence) {
+                                    db.prepare('INSERT INTO CommandSequence (Id, SerializedCommands, ButtonId) VALUES (?, ?, ?)').run(nextCommandSequenceId++, '{"$type":"1","$values":[{"$type":"3","MessageAction":0}]}', buttonId);
+                                }
+                                const layouts = layoutsByPage.get(numericPageId) ?? [];
+                                const prefX = button.x ?? 0;
+                                const prefY = button.y ?? 0;
+                                if (layouts.length === 0) {
+                                    const placementId = nextPlacementId++;
+                                    if (hasPlacementPageLayoutId) {
+                                        db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan, PageLayoutId, Visible) VALUES (?, ?, ?, '1,1', NULL, 1)").run(placementId, elementRefId, `${prefX},${prefY}`);
+                                    }
+                                    else {
+                                        db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan, Visible) VALUES (?, ?, ?, '1,1', 1)").run(placementId, elementRefId, `${prefX},${prefY}`);
+                                    }
+                                }
+                                else {
+                                    // INVARIANT: every Button must have exactly one ElementPlacement
+                                    // per PageLayout on its page. Snap renders buttons × layouts and
+                                    // crashes if a (button, layout) pair is missing.
+                                    //
+                                    // Hidden placements (Visible=0) MUST use a position that doesn't
+                                    // collide with an existing visible placement on that layout.
+                                    // The existing convention puts hidden placements at out-of-grid
+                                    // coordinates (e.g. position (2,4) on a 4×3 layout where row 4
+                                    // doesn't exist). We do the same: synthesise (cols, 0) which is
+                                    // guaranteed out of bounds since valid X is 0..cols-1.
+                                    for (const info of layouts) {
+                                        const cell = findFreeCell(info, prefX, prefY);
+                                        const visible = cell !== null ? 1 : 0;
+                                        const gridPosition = cell ?? `${info.cols},0`;
+                                        const placementId = nextPlacementId++;
+                                        if (hasPlacementPageLayoutId && hasPlacementVisible) {
+                                            db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan, PageLayoutId, Visible) VALUES (?, ?, ?, '1,1', ?, ?)").run(placementId, elementRefId, gridPosition, info.id, visible);
+                                        }
+                                        else if (hasPlacementPageLayoutId) {
+                                            db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan, PageLayoutId) VALUES (?, ?, ?, '1,1', ?)").run(placementId, elementRefId, gridPosition, info.id);
+                                        }
+                                        else if (hasPlacementVisible) {
+                                            db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan, Visible) VALUES (?, ?, ?, '1,1', ?)").run(placementId, elementRefId, gridPosition, visible);
+                                        }
+                                        else {
+                                            db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan) VALUES (?, ?, ?, '1,1')").run(placementId, elementRefId, gridPosition);
+                                        }
+                                    }
+                                }
+                                break;
+                            }
+                            case 'addWordListItem':
+                            case 'removeWordListItem':
+                            case 'clearWordList':
+                                // Snap has no WordList concept — these are no-ops by capability contract.
+                                break;
+                        }
+                    }
+                }
+            });
+            replay();
+        }
+        finally {
+            db.close();
+        }
+    }
     async saveFromTree(tree, outputPath) {
         const { pathExists, mkDir, removePath, dirname } = this.options.fileAdapter;
         if (!isNodeRuntime()) {

package/dist/processors/gridsetProcessor.js

@@ -1,27 +1,4 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GridsetProcessor = void 0;
 const baseProcessor_1 = require("../core/baseProcessor");
@@ -2253,9 +2230,8 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
             await writeBinaryToPath(outputPath, originalBuffer);
             return;
         }
-        const AdmZip = (await Promise.resolve().then(() => __importStar(require('adm-zip')))).default;
-        const originalZip = new AdmZip(originalPath);
-        const outputZip = new AdmZip();
+        const originalZip = await this.options.zipAdapter(originalPath);
+        const outputZip = await this.options.zipAdapter();
         // Check if any page has pending mutations
         const hasPendingMutations = Object.values(tree.pages).some((page) => page.pendingMutations.length > 0);
         if (hasPendingMutations) {
@@ -2272,15 +2248,13 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                 suppressBooleanAttributes: false,
             });
             saveMutations_1.GridsetSaveHandler.saveWithMutations(tree, originalZip, outputZip, parser, gridBuilder, (page) => this.createBasicGridXml(page));
-            // Copy remaining files
-            for (const entry of originalZip.getEntries()) {
-                if (entry.isDirectory)
-                    continue;
-                if (!outputZip.getEntry(entry.entryName)) {
-                    outputZip.addFile(entry.entryName, entry.getData());
-                }
+            // Copy files
+            const outputFiles = [];
+            for (const name of originalZip.listFiles()) {
+                const data = await originalZip.readFile(name);
+                outputFiles.push({ name, data });
             }
-            const outputBuffer = outputZip.toBuffer();
+            const outputBuffer = await outputZip.writeFiles(outputFiles);
             await writeBinaryToPath(outputPath, outputBuffer);
             return;
         }
@@ -2311,15 +2285,15 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
             const gridPath = `Grids/${page.name}/grid.xml`;
             modifiedGridFiles.add(gridPath);
             // Try to get the original grid.xml file
-            const originalEntry = originalZip.getEntry(gridPath);
-            if (!originalEntry) {
+            const originalEntries = originalZip.listFiles();
+            if (!originalEntries.includes(gridPath)) {
                 // If original doesn't exist, create a new basic grid
                 const basicGrid = this.createBasicGridXml(page);
                 newGridFiles.set(gridPath, basicGrid);
                 continue;
             }
             // Parse the original grid XML
-            const originalContent = originalEntry.getData().toString('utf-8');
+            const originalContent = (await originalZip.readFile(gridPath)).toString();
             const originalGrid = parser.parse(originalContent);
             if (!originalGrid.Grid) {
                 // Invalid grid structure, create a basic one
@@ -2484,22 +2458,22 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
             newGridFiles.set(gridPath, builtXml);
         }
         // Copy all files from original zip, replacing modified grid files
-        for (const entry of originalZip.getEntries()) {
-            if (entry.isDirectory)
-                continue;
+        const outputFiles = [];
+        for (const entry of originalZip.listFiles()) {
             // Skip grid.xml files that we're modifying
-            if (modifiedGridFiles.has(entry.entryName)) {
-                const newContent = newGridFiles.get(entry.entryName);
+            if (modifiedGridFiles.has(entry)) {
+                const newContent = newGridFiles.get(entry);
                 if (newContent) {
-                    outputZip.addFile(entry.entryName, Buffer.from(newContent, 'utf8'));
+                    outputFiles.push({ name: entry, data: Buffer.from(newContent, 'utf8') });
                 }
                 continue;
             }
             // Copy all other files as-is
-            outputZip.addFile(entry.entryName, entry.getData());
+            const data = await originalZip.readFile(entry);
+            outputFiles.push({ name: entry, data });
         }
         // Write the output ZIP
-        const outputBuffer = outputZip.toBuffer();
+        const outputBuffer = await outputZip.writeFiles(outputFiles);
         await writeBinaryToPath(outputPath, outputBuffer);
     }
     /**

package/dist/processors/obfProcessor.js

@@ -1,27 +1,4 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObfProcessor = void 0;
 const baseProcessor_1 = require("../core/baseProcessor");
@@ -767,24 +744,18 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
             await writeBinaryToPath(outputPath, originalBuffer);
             return;
         }
-        const AdmZip = (await Promise.resolve().then(() => __importStar(require('adm-zip')))).default;
-        const originalZip = new AdmZip(originalPath);
-        const outputZip = new AdmZip();
-        // Track which .obf files we're modifying
-        const modifiedObfFiles = new Set();
-        // Generate new .obf files for pages in the tree
-        const newObfFiles = new Map();
+        const originalZip = await this.options.zipAdapter(originalPath);
+        const outputZip = await this.options.zipAdapter();
+        const outputFiles = [];
         for (const page of Object.values(tree.pages)) {
-            const obfFilename = this.getPageFilename(page.id, tree.metadata);
-            modifiedObfFiles.add(obfFilename);
+            const name = this.getPageFilename(page.id, tree.metadata);
             // createObfBoardFromPage will automatically apply mutations if present
             const obfBoard = this.createObfBoardFromPage(page, 'Board', tree.metadata);
-            const obfContent = JSON.stringify(obfBoard, null, 2);
-            newObfFiles.set(obfFilename, obfContent);
+            const data = JSON.stringify(obfBoard, null, 2);
+            outputFiles.push({ name, data });
         }
         // Generate updated manifest if we have pages
         if (Object.keys(tree.pages).length > 0) {
-            modifiedObfFiles.add('manifest.json');
             const manifest = {
                 format: OBF_FORMAT_VERSION,
                 root: tree.metadata.defaultHomePageId,
@@ -797,25 +768,18 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                     sounds: {},
                 },
             };
-            newObfFiles.set('manifest.json', JSON.stringify(manifest));
-        }
-        // Copy all files from original zip, replacing modified .obf files
-        for (const entry of originalZip.getEntries()) {
-            if (entry.isDirectory)
-                continue;
-            // Skip .obf files that we're modifying
-            if (modifiedObfFiles.has(entry.entryName)) {
-                const newContent = newObfFiles.get(entry.entryName);
-                if (newContent) {
-                    outputZip.addFile(entry.entryName, Buffer.from(newContent, 'utf8'));
-                }
-                continue;
+            const data = Buffer.from(JSON.stringify(manifest), 'utf8');
+            outputFiles.push({ name: 'manifest.json', data });
+        }
+        // Add remaining .obf from original zip
+        for (const entry of originalZip.listFiles()) {
+            if (!outputFiles.find((file) => file.name === entry)) {
+                const data = await originalZip.readFile(entry);
+                outputFiles.push({ name: entry, data });
             }
-            // Copy all other files as-is (preserves images, sounds, etc.)
-            outputZip.addFile(entry.entryName, entry.getData());
         }
         // Write the output ZIP
-        const outputBuffer = outputZip.toBuffer();
+        const outputBuffer = await outputZip.writeFiles(outputFiles);
         await writeBinaryToPath(outputPath, outputBuffer);
     }
     /**

package/dist/processors/snapProcessor.d.ts

@@ -18,6 +18,30 @@ declare class SnapProcessor extends BaseProcessor {
     extractTexts(filePathOrBuffer: ProcessorInput): Promise<string[]>;
     loadIntoTree(filePathOrBuffer: ProcessorInput): Promise<AACTree>;
     processTexts(filePathOrBuffer: ProcessorInput, translations: Map<string, string>, outputPath: string): Promise<Uint8Array>;
+    /**
+     * Save a modified tree while preserving the original SQLite schema and data.
+     *
+     * Strategy: copy the original .sps verbatim, then open the copy and replay
+     * `page.pendingMutations` as targeted SQL UPDATE/INSERT statements. Everything
+     * not in the mutation log (PageLayout, ScanGroup, image blobs, ContentTypeData,
+     * ButtonPageLink, etc.) is preserved byte-for-byte from the original.
+     *
+     * This is the asset-preserving counterpart to `saveFromTree` (which builds a
+     * stripped-down DB from scratch and is unsuitable for round-tripping real
+     * TD Snap page sets).
+     *
+     * Supported mutations:
+     * - updateButton(id, patch)  → UPDATE Button SET Label/Message WHERE Id = ?
+     * - removeButton(id)         → UPDATE ElementPlacement SET Visible = 0 for all
+     *                              placements pointing at the button's ElementReference
+     * - addButton(button)        → INSERT into ElementReference + Button + one
+     *                              ElementPlacement per existing PageLayout for
+     *                              the target page (so the button shows in every
+     *                              layout the user has). Image/audio not yet handled.
+     *
+     * WordList mutations are no-ops on Snap (capabilities.wordList === 'none').
+     */
+    saveModifiedTree(originalPath: string, tree: AACTree, outputPath: string): Promise<void>;
     saveFromTree(tree: AACTree, outputPath: string): Promise<void>;
     /**
      * Add audio recording to a button in the database

package/dist/processors/snapProcessor.js

@@ -42,7 +42,7 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
         super(options);
         this.capabilities = {
             wordList: 'none',
-            preservesAssetsOnSave: false,
+            preservesAssetsOnSave: true,
             newCellCreation: 'allowed',
         };
         this.symbolResolver = null;
@@ -813,6 +813,324 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
         await this.saveFromTree(tree, outputPath);
         return await readBinaryFromInput(outputPath);
     }
+    /**
+     * Save a modified tree while preserving the original SQLite schema and data.
+     *
+     * Strategy: copy the original .sps verbatim, then open the copy and replay
+     * `page.pendingMutations` as targeted SQL UPDATE/INSERT statements. Everything
+     * not in the mutation log (PageLayout, ScanGroup, image blobs, ContentTypeData,
+     * ButtonPageLink, etc.) is preserved byte-for-byte from the original.
+     *
+     * This is the asset-preserving counterpart to `saveFromTree` (which builds a
+     * stripped-down DB from scratch and is unsuitable for round-tripping real
+     * TD Snap page sets).
+     *
+     * Supported mutations:
+     * - updateButton(id, patch)  → UPDATE Button SET Label/Message WHERE Id = ?
+     * - removeButton(id)         → UPDATE ElementPlacement SET Visible = 0 for all
+     *                              placements pointing at the button's ElementReference
+     * - addButton(button)        → INSERT into ElementReference + Button + one
+     *                              ElementPlacement per existing PageLayout for
+     *                              the target page (so the button shows in every
+     *                              layout the user has). Image/audio not yet handled.
+     *
+     * WordList mutations are no-ops on Snap (capabilities.wordList === 'none').
+     */
+    async saveModifiedTree(originalPath, tree, outputPath) {
+        const { pathExists, mkDir, removePath, dirname, readBinaryFromInput, writeBinaryToPath } = this.options.fileAdapter;
+        if (!(0, io_1.isNodeRuntime)()) {
+            throw new Error('saveModifiedTree is only supported in Node.js for Snap files.');
+        }
+        const outputDir = dirname(outputPath);
+        if (!(await pathExists(outputDir))) {
+            await mkDir(outputDir, { recursive: true });
+        }
+        if (await pathExists(outputPath)) {
+            await removePath(outputPath);
+        }
+        // 1. Copy the original verbatim — preserves all 23+ tables, blobs, settings.
+        const originalBytes = await readBinaryFromInput(originalPath);
+        await writeBinaryToPath(outputPath, originalBytes);
+        // Short-circuit: if no page has any mutations, we're done.
+        const hasAnyMutations = Object.values(tree.pages).some((page) => page.pendingMutations.length > 0);
+        if (!hasAnyMutations) {
+            return;
+        }
+        // 2. Open the copy.
+        const Database = (0, sqlite_1.requireBetterSqlite3)();
+        const db = new Database(outputPath, { readonly: false });
+        try {
+            // 3. Schema introspection — different Snap versions have different optional columns.
+            const tableColumns = (table) => {
+                try {
+                    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+                    return new Set(rows.map((r) => r.name));
+                }
+                catch {
+                    return new Set();
+                }
+            };
+            const buttonCols = tableColumns('Button');
+            const placementCols = tableColumns('ElementPlacement');
+            const hasPlacementVisible = placementCols.has('Visible');
+            const hasPlacementPageLayoutId = placementCols.has('PageLayoutId');
+            // 4. UniqueId → numeric Page.Id map.
+            const pageRows = db.prepare('SELECT Id, UniqueId FROM Page').all();
+            const uniqueIdToPageId = new Map();
+            for (const row of pageRows) {
+                if (row.UniqueId)
+                    uniqueIdToPageId.set(String(row.UniqueId), row.Id);
+                // Allow lookup by stringified numeric Id too, since loadIntoTree falls back to it.
+                uniqueIdToPageId.set(String(row.Id), row.Id);
+            }
+            const layoutsByPage = new Map();
+            try {
+                const layoutRows = db
+                    .prepare('SELECT Id, PageId, PageLayoutSetting FROM PageLayout')
+                    .all();
+                // Pre-load occupied placements per layout so we can avoid (x,y) collisions.
+                const placementsByLayout = new Map();
+                const placementRows = db
+                    .prepare('SELECT PageLayoutId, GridPosition FROM ElementPlacement WHERE GridPosition IS NOT NULL AND PageLayoutId IS NOT NULL')
+                    .all();
+                for (const r of placementRows) {
+                    let set = placementsByLayout.get(r.PageLayoutId);
+                    if (!set) {
+                        set = new Set();
+                        placementsByLayout.set(r.PageLayoutId, set);
+                    }
+                    set.add(r.GridPosition);
+                }
+                for (const row of layoutRows) {
+                    const parts = String(row.PageLayoutSetting ?? '').split(',');
+                    const cols = parseInt(parts[0], 10) || 4;
+                    const rows = parseInt(parts[1], 10) || 4;
+                    const info = {
+                        id: row.Id,
+                        cols,
+                        rows,
+                        occupied: placementsByLayout.get(row.Id) ?? new Set(),
+                    };
+                    const list = layoutsByPage.get(row.PageId);
+                    if (list)
+                        list.push(info);
+                    else
+                        layoutsByPage.set(row.PageId, [info]);
+                }
+            }
+            catch {
+                // PageLayout table may not exist on older schemas — placements get NULL PageLayoutId.
+            }
+            // Find first empty cell on a layout, starting from a preferred (x,y).
+            // Returns null if the layout is fully occupied.
+            const findFreeCell = (info, prefX, prefY) => {
+                const inBounds = (x, y) => x >= 0 && x < info.cols && y >= 0 && y < info.rows;
+                if (inBounds(prefX, prefY)) {
+                    const key = `${prefX},${prefY}`;
+                    if (!info.occupied.has(key)) {
+                        info.occupied.add(key);
+                        return key;
+                    }
+                }
+                for (let y = 0; y < info.rows; y++) {
+                    for (let x = 0; x < info.cols; x++) {
+                        const key = `${x},${y}`;
+                        if (!info.occupied.has(key)) {
+                            info.occupied.add(key);
+                            return key;
+                        }
+                    }
+                }
+                return null;
+            };
+            // Generate a UUID for new Button.UniqueId. Required: Node has crypto.randomUUID since 14.17.
+            const nodeCrypto = (0, io_1.getNodeRequire)()?.('crypto');
+            const uuid = () => nodeCrypto?.randomUUID
+                ? nodeCrypto.randomUUID()
+                : // Fallback (very unlikely path, but shouldn't break older Nodes)
+                    'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+                        const r = (Math.random() * 16) | 0;
+                        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+                        return v.toString(16);
+                    });
+            // 5. Next-available IDs for inserts.
+            const nextId = (table) => {
+                const row = db.prepare(`SELECT COALESCE(MAX(Id), 0) AS maxId FROM ${table}`).get();
+                return (row.maxId || 0) + 1;
+            };
+            let nextButtonId = nextId('Button');
+            let nextElementRefId = nextId('ElementReference');
+            let nextPlacementId = nextId('ElementPlacement');
+            // CommandSequence is optional but TD Snap crashes on some pages (e.g. dashboards
+            // like "Google Home Speaker") when a button has no CommandSequence row. Every
+            // button in the original DB has one. We track this only if the table exists.
+            const hasCommandSequence = tableColumns('CommandSequence').size > 0;
+            let nextCommandSequenceId = hasCommandSequence ? nextId('CommandSequence') : 0;
+            // 6. Replay mutations inside one transaction for atomicity + speed.
+            const replay = db.transaction(() => {
+                for (const page of Object.values(tree.pages)) {
+                    if (page.pendingMutations.length === 0)
+                        continue;
+                    const numericPageId = uniqueIdToPageId.get(String(page.id));
+                    if (numericPageId === undefined) {
+                        // eslint-disable-next-line no-console
+                        console.warn(`[Snap] saveModifiedTree: page "${page.name}" (${page.id}) not found in original DB; skipping ${page.pendingMutations.length} mutation(s)`);
+                        continue;
+                    }
+                    for (const mutation of page.pendingMutations) {
+                        switch (mutation.type) {
+                            case 'updateButton': {
+                                const sets = [];
+                                const args = [];
+                                if (mutation.patch.label !== undefined && buttonCols.has('Label')) {
+                                    sets.push('Label = ?');
+                                    args.push(mutation.patch.label);
+                                }
+                                if (mutation.patch.message !== undefined && buttonCols.has('Message')) {
+                                    sets.push('Message = ?');
+                                    args.push(mutation.patch.message);
+                                }
+                                if (sets.length === 0)
+                                    break;
+                                args.push(Number(mutation.buttonId));
+                                db.prepare(`UPDATE Button SET ${sets.join(', ')} WHERE Id = ?`).run(...args);
+                                break;
+                            }
+                            case 'removeButton': {
+                                // Hide all placements that reference the button's ElementReference.
+                                const buttonRow = db
+                                    .prepare('SELECT ElementReferenceId FROM Button WHERE Id = ?')
+                                    .get(Number(mutation.buttonId));
+                                if (!buttonRow || buttonRow.ElementReferenceId == null)
+                                    break;
+                                if (hasPlacementVisible) {
+                                    db.prepare('UPDATE ElementPlacement SET Visible = 0 WHERE ElementReferenceId = ?').run(buttonRow.ElementReferenceId);
+                                }
+                                else {
+                                    // Older schemas without Visible: delete the placements outright.
+                                    db.prepare('DELETE FROM ElementPlacement WHERE ElementReferenceId = ?').run(buttonRow.ElementReferenceId);
+                                }
+                                break;
+                            }
+                            case 'addButton': {
+                                const button = mutation.button;
+                                const elementRefId = nextElementRefId++;
+                                const buttonId = nextButtonId++;
+                                // ElementReference: TD Snap requires ElementType, ForegroundColor,
+                                // BackgroundColor, and AudioCueRecordingId to be non-NULL on render
+                                // — NULL values crash dashboard pages (e.g. "Google Home Speaker").
+                                // Defaults below match the modal values across real Snap files
+                                // (>99% of existing rows in Core First Scanning use them).
+                                const erColumns = tableColumns('ElementReference');
+                                const erCandidates = [
+                                    { col: 'Id', value: elementRefId },
+                                    { col: 'PageId', value: numericPageId },
+                                    { col: 'ElementType', value: 0 }, // 0 = button; only nonzero in 1/20608 rows
+                                    { col: 'ForegroundColor', value: -14934754 }, // dark text default (99.8% of rows)
+                                    { col: 'BackgroundColor', value: -132102 }, // light cell default (85.7% of rows)
+                                    { col: 'AudioCueRecordingId', value: 0 }, // 0 = no audio cue (99.99% of rows)
+                                ];
+                                const erFieldsPresent = erCandidates.filter((f) => erColumns.has(f.col));
+                                db.prepare(`INSERT INTO ElementReference (${erFieldsPresent
+                                    .map((f) => f.col)
+                                    .join(', ')}) VALUES (${erFieldsPresent.map(() => '?').join(', ')})`).run(...erFieldsPresent.map((f) => f.value));
+                                // Button: provide non-NULL defaults for columns TD Snap reads.
+                                // ContentType = 6 (normal speak button), CommandFlags = 8 (standard),
+                                // LabelOwnership / ImageOwnership = 3 (owned by this page set),
+                                // ActiveContentType = 0, BorderThickness = 0, UniqueId = fresh GUID,
+                                // image / sound / symbol IDs = 0 (= "no asset").
+                                const candidateFields = [
+                                    { col: 'Id', value: buttonId },
+                                    { col: 'Label', value: button.label || '' },
+                                    { col: 'Message', value: button.message || button.label || '' },
+                                    { col: 'ElementReferenceId', value: elementRefId },
+                                    { col: 'ContentType', value: 6 },
+                                    { col: 'CommandFlags', value: 8 },
+                                    { col: 'LabelOwnership', value: 3 },
+                                    { col: 'ImageOwnership', value: 3 },
+                                    { col: 'ActiveContentType', value: 0 },
+                                    { col: 'BorderThickness', value: 0 },
+                                    { col: 'UniqueId', value: uuid() },
+                                    { col: 'LibrarySymbolId', value: 0 },
+                                    { col: 'PageSetImageId', value: 0 },
+                                    { col: 'MessageRecordingId', value: 0 },
+                                    // UseMessageRecording: omit. 99.99% of existing rows have NULL,
+                                    // and forcing 0 makes Sarah/Mum the only outliers in the DB.
+                                    { col: 'SymbolColorDataId', value: 0 },
+                                ];
+                                const presentFields = candidateFields.filter((f) => buttonCols.has(f.col));
+                                const sql = `INSERT INTO Button (${presentFields
+                                    .map((f) => f.col)
+                                    .join(', ')}) VALUES (${presentFields.map(() => '?').join(', ')})`;
+                                db.prepare(sql).run(...presentFields.map((f) => f.value));
+                                // Insert a default CommandSequence row that explicitly speaks the
+                                // button's Label ($type:3 = MessageAction, value 0 = speak Label).
+                                // This is the most common pattern in real Snap files (9514 / 19402
+                                // buttons in Core First Scanning). Without an explicit action,
+                                // dashboard pages (e.g. "Google Home Speaker") crash on render —
+                                // empty $values is only used for hidden/help-text buttons.
+                                if (hasCommandSequence) {
+                                    db.prepare('INSERT INTO CommandSequence (Id, SerializedCommands, ButtonId) VALUES (?, ?, ?)').run(nextCommandSequenceId++, '{"$type":"1","$values":[{"$type":"3","MessageAction":0}]}', buttonId);
+                                }
+                                const layouts = layoutsByPage.get(numericPageId) ?? [];
+                                const prefX = button.x ?? 0;
+                                const prefY = button.y ?? 0;
+                                if (layouts.length === 0) {
+                                    const placementId = nextPlacementId++;
+                                    if (hasPlacementPageLayoutId) {
+                                        db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan, PageLayoutId, Visible) VALUES (?, ?, ?, '1,1', NULL, 1)").run(placementId, elementRefId, `${prefX},${prefY}`);
+                                    }
+                                    else {
+                                        db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan, Visible) VALUES (?, ?, ?, '1,1', 1)").run(placementId, elementRefId, `${prefX},${prefY}`);
+                                    }
+                                }
+                                else {
+                                    // INVARIANT: every Button must have exactly one ElementPlacement
+                                    // per PageLayout on its page. Snap renders buttons × layouts and
+                                    // crashes if a (button, layout) pair is missing.
+                                    //
+                                    // Hidden placements (Visible=0) MUST use a position that doesn't
+                                    // collide with an existing visible placement on that layout.
+                                    // The existing convention puts hidden placements at out-of-grid
+                                    // coordinates (e.g. position (2,4) on a 4×3 layout where row 4
+                                    // doesn't exist). We do the same: synthesise (cols, 0) which is
+                                    // guaranteed out of bounds since valid X is 0..cols-1.
+                                    for (const info of layouts) {
+                                        const cell = findFreeCell(info, prefX, prefY);
+                                        const visible = cell !== null ? 1 : 0;
+                                        const gridPosition = cell ?? `${info.cols},0`;
+                                        const placementId = nextPlacementId++;
+                                        if (hasPlacementPageLayoutId && hasPlacementVisible) {
+                                            db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan, PageLayoutId, Visible) VALUES (?, ?, ?, '1,1', ?, ?)").run(placementId, elementRefId, gridPosition, info.id, visible);
+                                        }
+                                        else if (hasPlacementPageLayoutId) {
+                                            db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan, PageLayoutId) VALUES (?, ?, ?, '1,1', ?)").run(placementId, elementRefId, gridPosition, info.id);
+                                        }
+                                        else if (hasPlacementVisible) {
+                                            db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan, Visible) VALUES (?, ?, ?, '1,1', ?)").run(placementId, elementRefId, gridPosition, visible);
+                                        }
+                                        else {
+                                            db.prepare("INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition, GridSpan) VALUES (?, ?, ?, '1,1')").run(placementId, elementRefId, gridPosition);
+                                        }
+                                    }
+                                }
+                                break;
+                            }
+                            case 'addWordListItem':
+                            case 'removeWordListItem':
+                            case 'clearWordList':
+                                // Snap has no WordList concept — these are no-ops by capability contract.
+                                break;
+                        }
+                    }
+                }
+            });
+            replay();
+        }
+        finally {
+            db.close();
+        }
+    }
     async saveFromTree(tree, outputPath) {
         const { pathExists, mkDir, removePath, dirname } = this.options.fileAdapter;
         if (!(0, io_1.isNodeRuntime)()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "A comprehensive TypeScript library for processing AAC (Augmentative and Alternative Communication) file formats with translation support",
   "main": "dist/index.js",
   "browser": "dist/browser/index.browser.js",