@lotics/cli 0.112.0 → 0.113.0

package/README.md

@@ -156,12 +156,15 @@ The CLI bundles Lotics's own xlsx and docx engines so you can read, write, and e
 ```bash
 # .xlsx
 lotics xlsx read ./report.xlsx                                  # → JSON of sheets, cells, merges
+lotics xlsx read ./report.xlsx --with-format                    # …plus each cell's resolved style
 lotics xlsx write ./out.xlsx '{"sheets":[{"name":"S1","cells":{"A1":"Hi","B1":42}}]}'
 # A cell is a bare value, or an object with numFmt / style / formula:
-lotics xlsx write ./out.xlsx '{"sheets":[{"name":"S1","cells":{
-  "A1":{"value":"Tổng","style":{"fontBold":true}},
-  "B1":{"value":1234567,"numFmt":"#,##0"},
-  "B2":{"formula":"B1*0.1","numFmt":"#,##0"}}}]}'   # unknown cell keys are rejected, not ignored
+lotics xlsx write ./out.xlsx '{"sheets":[{"name":"S1",
+  "colWidths":{"A":34,"B":14}, "rowHeights":{"1":28},
+  "cells":{
+    "A1":{"value":"Tổng","style":{"fontBold":true}},
+    "B1":{"value":1234567,"numFmt":"#,##0"},
+    "B2":{"formula":"B1*0.1","numFmt":"#,##0"}}}]}'  # unknown keys are rejected, not ignored
 lotics xlsx set-cell ./report.xlsx 'Sheet1!A1' '=SUM(B:B)'
 lotics xlsx add-sheet ./report.xlsx 'Summary'
 lotics xlsx merge ./report.xlsx 'Sheet1!A1:C1'

package/dist/src/cli.js

@@ -33334,8 +33334,8 @@ var require_utils2 = __commonJS({
     var { Address } = require_helpers();
     var { Prefix, Postfix, Infix, Operators } = require_operators();
     var Collection = require_collection();
-    var MAX_ROW = 1048576;
-    var MAX_COLUMN = 16384;
+    var MAX_ROW2 = 1048576;
+    var MAX_COLUMN2 = 16384;
     var { NotAllInputParsedException } = require_api();
     var Utils = class {
       constructor(context) {
@@ -33564,7 +33564,7 @@ var require_utils2 = __commonJS({
        // * @return {{ref: {from: {col: number, row: number}, to: {col: number, row: number}}}}
        */
       applyRange(refs) {
-        let res, maxRow = -1, maxCol = -1, minRow = MAX_ROW + 1, minCol = MAX_COLUMN + 1;
+        let res, maxRow = -1, maxCol = -1, minRow = MAX_ROW2 + 1, minCol = MAX_COLUMN2 + 1;
         refs.forEach((ref2) => {
           if (this.isFormulaError(ref2))
             return ref2;
@@ -33574,11 +33574,11 @@ var require_utils2 = __commonJS({
           ref2 = ref2.ref;
           if (ref2.row === void 0) {
             minRow = 1;
-            maxRow = MAX_ROW;
+            maxRow = MAX_ROW2;
           }
           if (ref2.col === void 0) {
             minCol = 1;
-            maxCol = MAX_COLUMN;
+            maxCol = MAX_COLUMN2;
           }
           if (ref2.row > maxRow)
             maxRow = ref2.row;
@@ -34014,8 +34014,8 @@ var require_utils3 = __commonJS({
     var { FormulaHelpers, Types, Address } = require_helpers();
     var { Prefix, Postfix, Infix, Operators } = require_operators();
     var Collection = require_collection();
-    var MAX_ROW = 1048576;
-    var MAX_COLUMN = 16384;
+    var MAX_ROW2 = 1048576;
+    var MAX_COLUMN2 = 16384;
     var Utils = class {
       constructor(context) {
         this.context = context;
@@ -34161,7 +34161,7 @@ var require_utils3 = __commonJS({
        // * @return {{ref: {from: {col: number, row: number}, to: {col: number, row: number}}}}
        */
       applyRange(refs) {
-        let res, maxRow = -1, maxCol = -1, minRow = MAX_ROW + 1, minCol = MAX_COLUMN + 1;
+        let res, maxRow = -1, maxCol = -1, minRow = MAX_ROW2 + 1, minCol = MAX_COLUMN2 + 1;
         refs.forEach((ref2) => {
           if (this.isFormulaError(ref2))
             return ref2;
@@ -34171,11 +34171,11 @@ var require_utils3 = __commonJS({
           ref2 = ref2.ref;
           if (ref2.row === void 0) {
             minRow = 1;
-            maxRow = MAX_ROW;
+            maxRow = MAX_ROW2;
           }
           if (ref2.col === void 0) {
             minCol = 1;
-            maxCol = MAX_COLUMN;
+            maxCol = MAX_COLUMN2;
           }
           if (ref2.row > maxRow)
             maxRow = ref2.row;
@@ -44124,9 +44124,9 @@ var require_load = __commonJS({
 var require_lib4 = __commonJS({
   "../../node_modules/jszip/lib/index.js"(exports2, module2) {
     "use strict";
-    function JSZip4() {
-      if (!(this instanceof JSZip4)) {
-        return new JSZip4();
+    function JSZip5() {
+      if (!(this instanceof JSZip5)) {
+        return new JSZip5();
       }
       if (arguments.length) {
         throw new Error("The constructor with parameters has been removed in JSZip 3.0, please check the upgrade guide.");
@@ -44135,7 +44135,7 @@ var require_lib4 = __commonJS({
       this.comment = null;
       this.root = "";
       this.clone = function() {
-        var newObj = new JSZip4();
+        var newObj = new JSZip5();
         for (var i2 in this) {
           if (typeof this[i2] !== "function") {
             newObj[i2] = this[i2];
@@ -44144,16 +44144,16 @@ var require_lib4 = __commonJS({
         return newObj;
       };
     }
-    JSZip4.prototype = require_object();
-    JSZip4.prototype.loadAsync = require_load();
-    JSZip4.support = require_support();
-    JSZip4.defaults = require_defaults();
-    JSZip4.version = "3.10.1";
-    JSZip4.loadAsync = function(content, options) {
-      return new JSZip4().loadAsync(content, options);
+    JSZip5.prototype = require_object();
+    JSZip5.prototype.loadAsync = require_load();
+    JSZip5.support = require_support();
+    JSZip5.defaults = require_defaults();
+    JSZip5.version = "3.10.1";
+    JSZip5.loadAsync = function(content, options) {
+      return new JSZip5().loadAsync(content, options);
     };
-    JSZip4.external = require_external();
-    module2.exports = JSZip4;
+    JSZip5.external = require_external();
+    module2.exports = JSZip5;
   }
 });
 
@@ -64462,12 +64462,26 @@ var VALID_OPERATORS = {
 var VALID_FILTER_TYPES = Object.keys(VALID_OPERATORS);
 
 // ../shared/src/chat_models.ts
-var CHAT_MODEL_IDS = ["claude-haiku-4-5", "claude-sonnet-5", "claude-opus-5"];
-var LEGACY_CHAT_MODEL_IDS = [];
-var ACCEPTED_CHAT_MODEL_IDS = [...CHAT_MODEL_IDS, ...LEGACY_CHAT_MODEL_IDS];
-var UTILITY_MODEL_ID = "claude-haiku-4-5";
-var PICKER_MODEL_IDS = CHAT_MODEL_IDS.filter(
-  (id) => id !== UTILITY_MODEL_ID
+var MODEL_TIERS = ["haiku", "sonnet", "opus"];
+var TIER_MODELS = {
+  haiku: "claude-haiku-4-5",
+  sonnet: "claude-sonnet-5",
+  opus: "claude-opus-5"
+};
+var RESOLVED_MODEL_IDS = MODEL_TIERS.map(
+  (tier) => TIER_MODELS[tier]
+);
+function tierForModelId(modelId) {
+  for (const tier of MODEL_TIERS) {
+    if (modelId.startsWith(`claude-${tier}-`)) return tier;
+  }
+  return null;
+}
+var DEFAULT_MODEL_TIER = "sonnet";
+var UTILITY_MODEL_TIER = "haiku";
+var DEFAULT_MODEL_ID = TIER_MODELS[DEFAULT_MODEL_TIER];
+var PICKER_MODEL_TIERS = MODEL_TIERS.filter(
+  (tier) => tier !== UTILITY_MODEL_TIER
 );
 var EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 
@@ -64927,11 +64941,20 @@ var appAgentDeclarationSchema = zod_default.object({
   workflow_aliases: zod_default.array(zod_default.string().min(1)).optional().describe(
     "Workflows from this app's manifest the agent may invoke via `run_app_workflow`, validated at declare time against the app's own workflows. This is the agent's ENTIRE write surface \u2014 the same declared mutation path the app's UI uses, so table hooks and side-effect harvesting apply. Omit for a read-only agent."
   ),
-  model_id: zod_default.string().min(1).optional().describe(
-    "Chat model id the agent runs on, validated against ACCEPTED_CHAT_MODEL_IDS. Omit to follow the platform default chat model, resolved at run time \u2014 the preferred choice: the agent tracks model generations with no per-app rewrite. Pin only a deliberate, tested choice."
+  model_tier: zod_default.enum(MODEL_TIERS).optional().describe(
+    "Model tier the agent runs on \u2014 `haiku`, `sonnet`, or `opus`. Omit to follow the platform default tier, resolved at run time: the preferred choice. A tier names capability, not a version, so the generation behind it moves with the platform and this declaration never needs a rewrite. Pin only a deliberate, tested choice."
   ),
+  /**
+   * LEGACY, read-only. A version pin written by a release from before tiers.
+   * Parsed so a declaration an older release wrote during the rollout window
+   * still resolves (via `tierForModelId`) instead of reading as unpinned
+   * and silently dropping to the default. Never written by this release, and
+   * rejected on the write surface. Deleted with the strip migration, once no
+   * deployed release writes it.
+   */
+  model_id: zod_default.string().min(1).optional(),
   effort_level: zod_default.enum(EFFORT_LEVELS).optional().describe(
-    "Reasoning depth for adaptive-thinking models \u2014 one of the chosen model's supported levels (validated against model_id at declare time). Omit to use the model default; ignored on models without adaptive thinking."
+    "Reasoning depth for adaptive-thinking tiers \u2014 one of the chosen tier's supported levels (validated against model_tier at declare time). Omit to use the model default; ignored on tiers without adaptive thinking."
   ),
   inputs: zod_default.record(zod_default.string(), appWorkflowInputSchema).optional().describe(
     "Typed input schema for one run. Keys are input names; values declare type + constraints. The server validates the run payload against this before invoking; CLI codegen emits a typed `useAgentRun<alias>` signature. Omit for an untyped payload."
@@ -65070,6 +65093,8 @@ var agentStepSchema = stepBaseSchema.extend({
   instructions: zod_default.string().min(1),
   input: zod_default.record(zod_default.string(), toolInputValueSchema),
   tool_names: zod_default.array(zod_default.string().min(1)),
+  model_tier: zod_default.enum(MODEL_TIERS).optional(),
+  /** LEGACY, read-only — see `appAgentDeclarationSchema.model_id`. */
   model_id: zod_default.string().min(1).optional(),
   output: agentOutputSpecSchema
 });
@@ -69683,8 +69708,6 @@ function walkAgentInvocation(call, scope, stepId, description) {
   const toolsNode = kw.get("tools");
   if (!toolsNode) fail(arg, "agent requires `tools` (use [] for none).");
   const tool_names = readStaticStringArray(toolsNode, "agent `tools`");
-  const modelNode = kw.get("model");
-  const model_id = modelNode ? readStaticString(modelNode, "agent `model`") : void 0;
   const outputNode = kw.get("output");
   if (!outputNode) fail(arg, "agent requires `output`.");
   const outputResult = agentOutputSpecSchema.safeParse(walkStaticJsonLiteral(outputNode));
@@ -69692,6 +69715,19 @@ function walkAgentInvocation(call, scope, stepId, description) {
     const detail = outputResult.error.issues.map((i2) => `${i2.path.join(".") || "<root>"}: ${i2.message}`).join("; ");
     fail(outputNode, `Invalid agent \`output\`: ${detail}`);
   }
+  const modelNode = kw.get("model");
+  let model_tier;
+  if (modelNode) {
+    const literal2 = readStaticString(modelNode, "agent `model`");
+    const tier = MODEL_TIERS.includes(literal2) ? literal2 : tierForModelId(literal2);
+    if (!tier) {
+      fail(
+        modelNode,
+        `Unknown agent \`model\` "${literal2}" \u2014 expected one of: ${MODEL_TIERS.join(", ")}.`
+      );
+    }
+    model_tier = tier;
+  }
   return {
     id: stepId,
     description: description ?? "agent",
@@ -69699,7 +69735,7 @@ function walkAgentInvocation(call, scope, stepId, description) {
     instructions,
     input,
     tool_names,
-    ...model_id !== void 0 ? { model_id } : {},
+    ...model_tier !== void 0 ? { model_tier } : {},
     output: outputResult.data
   };
 }
@@ -83163,6 +83199,8 @@ function buildSheetXml(sheet, styles, ssIndex, isActive, xfMap, numFmtMap, dxfMa
     }
     arr.push({ col: rc.col, cell });
   }
+  for (const rowNum of sheet.rowHeights.keys()) if (!rowMap.has(rowNum)) rowMap.set(rowNum, []);
+  for (const rowNum of sheet.hiddenRows) if (!rowMap.has(rowNum)) rowMap.set(rowNum, []);
   const sortedRows = Array.from(rowMap.keys()).sort((a, b) => a - b);
   for (const rowNum of sortedRows) {
     const cells = rowMap.get(rowNum);
@@ -83319,11 +83357,12 @@ function buildSheetXml(sheet, styles, ssIndex, isActive, xfMap, numFmtMap, dxfMa
     }
   }
   let dimensionRef = "A1";
-  if (sortedRows.length > 0) {
+  const cellRows = sortedRows.filter((rowNum) => rowMap.get(rowNum).length > 0);
+  if (cellRows.length > 0) {
     let minCol = Infinity, maxCol = 0;
-    const minRow = sortedRows[0];
-    const maxRow = sortedRows[sortedRows.length - 1];
-    for (const rowNum of sortedRows) {
+    const minRow = cellRows[0];
+    const maxRow = cellRows[cellRows.length - 1];
+    for (const rowNum of cellRows) {
       const cells = rowMap.get(rowNum);
       for (const { col } of cells) {
         if (col < minCol) minCol = col;
@@ -92919,6 +92958,9 @@ function adjustMergedCellsForColDelete(sheet, atCol, count) {
 
 // src/xlsx.ts
 var SIMPLE_CELL_KEYS = /* @__PURE__ */ new Set(["value", "formula", "numFmt", "style"]);
+var SIMPLE_SHEET_KEYS = /* @__PURE__ */ new Set(["name", "cells", "merges", "freeze", "colWidths", "rowHeights"]);
+var MAX_COLUMN = 16384;
+var MAX_ROW = 1048576;
 function loadFile(filePath) {
   if (!fs6.existsSync(filePath)) fail2(`File not found: ${filePath}`);
   const buffer = fs6.readFileSync(filePath);
@@ -92970,7 +93012,7 @@ function lazyEngine(workbook) {
     }
   };
 }
-function readToJson(filePath, filter3) {
+function readToJson(filePath, filter3, opts) {
   const buffer = fs6.readFileSync(filePath);
   const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
   const parsed = parseExcelBuffer(arrayBuffer);
@@ -92989,13 +93031,13 @@ function readToJson(filePath, filter3) {
       name: s.name,
       totalRowCount: s.totalRowCount,
       truncated: s.truncated,
-      cells: cellsFromParsedRows(s.rows, filter3?.range),
+      cells: cellsFromParsedRows(s.rows, filter3?.range, opts?.withFormat === true),
       merges: s.mergedCells.map((m) => `${rowColToRef(m.startRow, m.startCol)}:${rowColToRef(m.endRow, m.endCol)}`),
       freeze: s.freezePane ? { row: s.freezePane.frozenRows, col: s.freezePane.frozenCols } : void 0
     }))
   };
 }
-function cellsFromParsedRows(rows, range2) {
+function cellsFromParsedRows(rows, range2, withFormat = false) {
   const out = {};
   for (const row of rows) {
     if (range2 && (row.index < range2.startRow || row.index > range2.endRow)) continue;
@@ -93005,6 +93047,8 @@ function cellsFromParsedRows(rows, range2) {
       const value2 = cell.typedValue ?? cell.value;
       const entry = { value: value2 };
       if (cell.formula) entry.formula = cell.formula;
+      if (cell.numFmtCode && cell.numFmtCode !== "General") entry.numFmt = cell.numFmtCode;
+      if (withFormat && cell.style && Object.keys(cell.style).length > 0) entry.style = cell.style;
       out[ref2] = entry;
     }
   }
@@ -93025,6 +93069,10 @@ function buildWorkbookFromJson(input) {
 }
 function validateSimpleSheet(s, index) {
   if (!s || typeof s !== "object") fail2(`sheets[${index}] must be an object`);
+  const unknown2 = Object.keys(s).filter((k) => !SIMPLE_SHEET_KEYS.has(k));
+  if (unknown2.length > 0) {
+    fail2(`sheets[${index}] has unknown propert${unknown2.length > 1 ? "ies" : "y"}: ${unknown2.join(", ")}. Supported: ${[...SIMPLE_SHEET_KEYS].join(", ")}.`);
+  }
   if (typeof s.name !== "string" || s.name === "") fail2(`sheets[${index}].name must be a non-empty string`);
   if (s.cells !== void 0 && (typeof s.cells !== "object" || s.cells === null || Array.isArray(s.cells))) {
     fail2(`sheets[${index}].cells must be an object keyed by cell ref (e.g. {"A1": "value"})`);
@@ -93038,6 +93086,23 @@ function validateSimpleSheet(s, index) {
       fail2(`sheets[${index}].freeze.row and .col must be numbers`);
     }
   }
+  validateDimensionMap(s.colWidths, `sheets[${index}].colWidths`, "column letter within A..XFD", (k) => {
+    const coord = /^[A-Za-z]+$/.test(k) ? refToRowCol(`${k.toUpperCase()}1`) : void 0;
+    return coord !== void 0 && coord.col <= MAX_COLUMN;
+  });
+  validateDimensionMap(s.rowHeights, `sheets[${index}].rowHeights`, `row number within 1..${MAX_ROW}`, (k) => /^[0-9]+$/.test(k) && Number(k) >= 1 && Number(k) <= MAX_ROW);
+}
+function validateDimensionMap(map3, label, keyHint, keyOk) {
+  if (map3 === void 0) return;
+  if (typeof map3 !== "object" || map3 === null || Array.isArray(map3)) {
+    fail2(`${label} must be an object keyed by ${keyHint}`);
+  }
+  for (const [key, value2] of Object.entries(map3)) {
+    if (!keyOk(key)) fail2(`${label} key "${key}" must be a ${keyHint}`);
+    if (typeof value2 !== "number" || !Number.isFinite(value2) || value2 <= 0) {
+      fail2(`${label}["${key}"] must be a positive number`);
+    }
+  }
 }
 function applySheetCells(workbook, sheetIndex, def) {
   const sheet = workbook.sheets[sheetIndex];
@@ -93070,6 +93135,20 @@ function applySheetCells(workbook, sheetIndex, def) {
   if (def.freeze) {
     sheet.freeze = { row: def.freeze.row, col: def.freeze.col };
   }
+  if (def.colWidths) {
+    for (const [letter, width] of Object.entries(def.colWidths)) {
+      const coord = refToRowCol(`${letter.toUpperCase()}1`);
+      if (!coord) fail2(`Invalid column in sheet "${def.name}".colWidths: ${letter}`);
+      sheet.colWidths.set(coord.col, width);
+    }
+  }
+  if (def.rowHeights) {
+    for (const [rowKey, height] of Object.entries(def.rowHeights)) {
+      const row = Number(rowKey);
+      if (!Number.isInteger(row) || row < 1) fail2(`Invalid row in sheet "${def.name}".rowHeights: ${rowKey}`);
+      sheet.rowHeights.set(row, height);
+    }
+  }
 }
 function normalizeSimpleCell(raw, sheetName, ref2) {
   if (raw && typeof raw === "object" && !Array.isArray(raw)) {
@@ -93100,9 +93179,10 @@ function splitOptionalSheetRef(spec) {
   return { sheet: spec.slice(0, idx), ref: spec.slice(idx + 1) };
 }
 function xlsxRead(filePath, rest2) {
-  if (!filePath) fail2("Usage: lotics xlsx read <file> [--sheet <name>] [--range <sheet>!<A1:G60>]");
+  if (!filePath) fail2("Usage: lotics xlsx read <file> [--sheet <name>] [--range <sheet>!<A1:G60>] [--with-format]");
   const rangeArg = readOptionFlag(rest2, "--range");
   const sheetArg = readOptionFlag(rest2, "--sheet");
+  const withFormat = rest2.includes("--with-format");
   let filter3;
   if (rangeArg !== void 0) {
     const { sheet, ref: ref2 } = splitOptionalSheetRef(rangeArg);
@@ -93114,7 +93194,7 @@ function xlsxRead(filePath, rest2) {
   } else if (sheetArg !== void 0) {
     filter3 = { sheet: sheetArg };
   }
-  const data2 = readToJson(filePath, filter3);
+  const data2 = readToJson(filePath, filter3, { withFormat });
   console.log(JSON.stringify(data2, null, 2));
 }
 function xlsxWrite(filePath, json2) {
@@ -93351,14 +93431,17 @@ function printXlsxHelp() {
   console.error(`Lotics xlsx commands \u2014 manipulate .xlsx files in place.
 Uses Lotics' own xlsx engine; round-trips faithfully with the Lotics editor and templates.
 
-  lotics xlsx read <file> [--sheet <name>] [--range <sheet>!<A1:G60>]
+  lotics xlsx read <file> [--sheet <name>] [--range <sheet>!<A1:G60>] [--with-format]
                                                    Dump file as JSON (sheets, cells, merges, freeze).
                                                    --sheet limits to one sheet; --range to a cell window
                                                    (its <sheet>! prefix is optional when --sheet is given)
+                                                   A cell carries numFmt when it has one; --with-format
+                                                   adds the resolved style (always present, hence a flag)
   lotics xlsx write <file> '<json>'                Create .xlsx from {"sheets":[{"name","cells":{"A1":...}}]}
                                                    A cell is a bare value, or {value|formula, numFmt, style}:
                                                    {"A1":{"value":1234,"numFmt":"#,##0 \\"\u20AB\\"","style":{"fontBold":true}}}
-                                                   Unknown cell properties are rejected, not ignored.
+                                                   A sheet also takes merges, freeze, colWidths ({"A":34}),
+                                                   rowHeights ({"1":44}). Unknown properties are rejected.
   lotics xlsx set-cell <file> <sheet>!<ref> '<v>'  Set cell value (prefix '=' for formula)
   lotics xlsx clear-range <file> <sheet>!<range>   Clear all cells in a range
   lotics xlsx merge <file> <sheet>!<range>         Merge a range into one cell
@@ -95352,7 +95435,7 @@ function parseLegacyDoc(bytes) {
 }
 
 // ../ooxml/src/document.ts
-var import_jszip = __toESM(require_lib4(), 1);
+var import_jszip2 = __toESM(require_lib4(), 1);
 
 // ../ooxml/node_modules/fast-xml-parser/src/util.js
 var nameStartChar2 = ":A-Za-z_\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u02FF\\u0370-\\u037D\\u037F-\\u1FFF\\u200C-\\u200D\\u2070-\\u218F\\u2C00-\\u2FEF\\u3001-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFFD";
@@ -98031,6 +98114,14 @@ async function docModelToDocx(model) {
   return doc;
 }
 
+// ../ooxml/src/opc.ts
+var import_jszip = __toESM(require_lib4(), 1);
+function dropFolderEntries(zip) {
+  for (const [path8, entry] of Object.entries(zip.files)) {
+    if (entry.dir) delete zip.files[path8];
+  }
+}
+
 // ../ooxml/src/document.ts
 var DOCUMENT_ATTRS = {
   "@_xmlns:wpc": "http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas",
@@ -98040,6 +98131,10 @@ var DOCUMENT_ATTRS = {
   "@_xmlns:m": "http://schemas.openxmlformats.org/officeDocument/2006/math",
   "@_xmlns:v": "urn:schemas-microsoft-com:vml",
   "@_xmlns:wp": "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+  // Declared because mc:Ignorable below names it. Markup Compatibility (ECMA-376 Part 3) requires
+  // every prefix listed there to be a declared namespace prefix; an undeclared one made Word
+  // report unreadable content and offer to repair EVERY document this package wrote.
+  "@_xmlns:wp14": "http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing",
   "@_xmlns:w10": "urn:schemas-microsoft-com:office:word",
   "@_xmlns:w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
   "@_xmlns:w14": "http://schemas.microsoft.com/office/word/2010/wordml",
@@ -98135,7 +98230,7 @@ async function loadDocxFromBuffer(buffer) {
   if (isLegacyDoc(buffer)) {
     return docxFromLegacyDoc(buffer);
   }
-  const zip = await import_jszip.default.loadAsync(buffer);
+  const zip = await import_jszip2.default.loadAsync(buffer);
   const docFile = zip.file("word/document.xml");
   if (!docFile) {
     throw new Error("Invalid .docx: missing word/document.xml");
@@ -98168,19 +98263,30 @@ function withTrailingParagraph(body) {
   out.splice(lastBlock + 1, 0, { "w:p": [] });
   return out;
 }
+function pruneIgnorable(attrs) {
+  const listed = (attrs["@_mc:Ignorable"] ?? "").split(/\s+/).filter(Boolean);
+  if (listed.length === 0) return attrs;
+  const kept = listed.filter((prefix) => `@_xmlns:${prefix}` in attrs);
+  if (kept.length === listed.length) return attrs;
+  const next = { ...attrs };
+  if (kept.length === 0) delete next["@_mc:Ignorable"];
+  else next["@_mc:Ignorable"] = kept.join(" ");
+  return next;
+}
 async function saveDocxToBuffer(doc) {
   const bodyChildren = withTrailingParagraph(doc.bodyElements);
   const documentEl = {
     "w:document": [{ "w:body": bodyChildren }],
-    ":@": { ...doc.documentAttrs }
+    ":@": pruneIgnorable(doc.documentAttrs)
   };
   const xml = buildXml([documentEl]);
   doc.zip.file("word/document.xml", xml);
+  dropFolderEntries(doc.zip);
   const buffer = await doc.zip.generateAsync({ type: "nodebuffer", compression: "DEFLATE" });
   return buffer;
 }
 function createBlankDocx(opts) {
-  const zip = new import_jszip.default();
+  const zip = new import_jszip2.default();
   zip.file("[Content_Types].xml", CONTENT_TYPES_XML);
   zip.file("_rels/.rels", RELS_XML);
   zip.file("word/_rels/document.xml.rels", DOCUMENT_RELS_XML);
@@ -98239,9 +98345,9 @@ async function ensureContentTypeOverride(doc, partName, contentType) {
 }
 
 // ../docx/src/parse/parser.ts
-var import_jszip2 = __toESM(require_lib4(), 1);
+var import_jszip3 = __toESM(require_lib4(), 1);
 async function parseDocx(buffer) {
-  const zip = await import_jszip2.default.loadAsync(buffer);
+  const zip = await import_jszip3.default.loadAsync(buffer);
   const parts = /* @__PURE__ */ new Map();
   const filePromises = [];
   zip.forEach((path8, file2) => {
@@ -98376,7 +98482,7 @@ function parseOpaqueRunChild(el) {
 }
 
 // ../docx/src/serialize/serializer.ts
-var import_jszip3 = __toESM(require_lib4(), 1);
+var import_jszip4 = __toESM(require_lib4(), 1);
 
 // ../docx/src/serialize/default_parts.ts
 var encoder = new TextEncoder();
@@ -98490,7 +98596,7 @@ function fillDefaultParts(parts) {
 
 // ../docx/src/serialize/serializer.ts
 async function serializeDocx(doc) {
-  const zip = new import_jszip3.default();
+  const zip = new import_jszip4.default();
   const parts = fillDefaultParts(new Map(doc.parts));
   for (const [path8, bytes] of parts) {
     if (path8 === "word/document.xml") continue;
@@ -98498,6 +98604,7 @@ async function serializeDocx(doc) {
   }
   const documentXml = serializeDocumentXml(doc);
   zip.file("word/document.xml", documentXml);
+  dropFolderEntries(zip);
   const out = await zip.generateAsync({
     type: "uint8array",
     compression: "DEFLATE"

package/docs/cli_reference.md

@@ -45,7 +45,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app rename "<new name>"` | Change the app's display name (launcher/title) via the `update_app` tool. app_id comes from the local `package.json` manifest; the public address (`subdomain`) and code (`deploy`) are unchanged. |
 | `lotics app dev [path] [--port=N] [--vite-port=N] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. The wrapper page embeds the iframe with `sandbox="allow-scripts allow-same-origin"` matching production; postMessage ops (query / workflow / members / context / upload / openExternal / urlState / agentRun) are forwarded to api.lotics.ai using the CLI's API key — file bytes move in **both** directions through the dev server's own relays, never browser↔storage: dev runs against the PROD bucket, whose CORS admits `https://*.lotics.app` and not `http://localhost:<port>`, so a direct browser transfer is blocked — no upload could complete and no preview engine (PDF/Word/Excel all FETCH the bytes) could read a file. `upload` mints a presigned URL and PUTs it **to `PUT /_upload/<file_id>`** (`dev/upload_relay.ts`) from the wrapper page — same-origin, so no preflight and no CORS — and Node forwards it on; every presigned `url`/`thumbnail_url`/`preview_url` on a **file object** in an RPC result is rewritten to **`GET /_file/<token>`** (`dev/file_relay.ts`, absolute — the iframe would resolve a relative path against Vite), which streams the bytes back with `Range` passthrough (206s intact, so PDF seeking works) and an `Access-Control-Allow-Origin` for the Vite origin (the one cross-origin hop left is OUR response to allow). Neither relay ever takes a destination from the client — it gets a `file_id`/token and transfers only to/from a URL it minted or observed itself, so there is no client-controlled target and no SSRF surface. A URL in a record's own text cell is NOT rewritten. Production is unchanged (direct-to-storage, no bytes through the API server); `openExternal` and `urlState.get/set` are handled locally (the latter read/write the wrapper page's own address bar — `set` writes in place via `replaceState` and browser back/forward broadcast a `url-state` message back, so `useUrlState` survives refresh and is shareable in the dev loop; in-app *routing* is the app's own (the iframe owns its url via `@lotics/app-sdk/router`), and the wrapper bakes the saved screen (`_loc`) into the iframe src on load so a refresh restores it, mirroring production); `agentRun` (streaming) is proxied through `POST /_agent_run`, which opens the run's SSE with the CLI key and pipes chunks back to the iframe (`stream-chunk`* → `stream-end`), so `useAgentRun` works in the dev loop just like production; `context` resolves the viewer (`member_id` from `cli/whoami` + `comments_enabled` from the local manifest) and fetches the installation's stored `config` live from the app row, so `useConfig()` renders the same values as production. `--view-as` (global flag; also `LOTICS_VIEW_AS`) threads `x-view-as-member-id` so `is_current_member` + `context` resolve to that member — **admin key only** (the server 403s a non-admin), writes stay attributed to the key owner. Hot reload via Vite; full DevTools / Playwright access via plain localhost. The dev-optimizer pre-bundle list (`optimizeDeps.include`, load-bearing for dev) is imported from `@lotics/ui/vite` (`loticsOptimizeDeps`) rather than hardcoded in the scaffold, so it tracks the installed `@lotics/ui` and can never go stale. Binds **loopback only** (`127.0.0.1`) — `/_rpc` dispatches with the developer's API key, so a socket on every interface would hand anyone on the network full read/write on the workspace. |
 | `LOTICS_UI_SRC=<abs path to packages/ui/src>` (env, not a command) | Dev-link `@lotics/ui` to a monorepo checkout for the length of ONE command, **for every tool at once**. The app's `vite.config.ts` gets its whole `resolve` block from the kit (`resolve: loticsResolve()` — `@lotics/ui/vite`), which reads the variable at call time and adds the `@lotics/ui/*` → working-copy alias, so kit edits go live under `lotics app dev` (HMR) and bundle under `lotics app deploy`. In the same breath, every command that regenerates types (`create`/`pull`/`dev`/`deploy`/`codegen`, all via `writeAppDts`) writes **`.lotics/tsconfig.link.json`** — the matching `paths`, which the app's `tsconfig.json` `extends` — so `tsc`, vitest, eslint and your EDITOR resolve the same copy Vite does. Unset ⇒ every one of them goes back to `node_modules`, and the generated file is rewritten inert. **Why `paths` and not `npm link`:** the kit ships un-built `.tsx`, so a kit file outside `node_modules` resolves its OWN `react`/`react-native` from the monorepo — two copies in one program and every shared type stops matching ("Two different types with this name exist, but they are unrelated"). The generated file therefore also pins every peer @lotics/ui declares to the APP's copy, types-package first (`react` → `@types/react`; pinning the runtime package instead strands tsc on a `.js` with no declarations). The pin set is derived from the installed kit's `peerDependencies`, so it tracks the kit rather than rotting. **Nothing hand-written is touched** — the generated file lives in `.lotics/` (the CLI's own dir) and no config is edited by regex, which is what the deleted `lotics ui link` did when it twice destroyed the load-bearing `react-native` alias along with the array's closing bracket. Identical for a monorepo app and an EXTERNAL one (e.g. `~/lotics_apps`). `app deploy` still warns whenever the variable is set — that the bundle carries kit code from your working copy, or that the app's config predates `loticsResolve()` and never reads it, so the PUBLISHED kit is going out. An app whose `tsconfig.json` already `extends` something else is told rather than rewritten: add `./.lotics/tsconfig.link.json` to the array yourself. |
-| `lotics xlsx <subcmd>` | Local .xlsx read/write/edit using the bundled `@lotics/xlsx` engine (no auth, no network). 14 named subcommands (read, write, set-cell, clear-range, merge, unmerge, add-sheet, delete-sheet, rename-sheet, insert-rows, delete-rows, insert-cols, delete-cols, set-style) + `batch` for applying multiple of the same 14 ops in a single parse/export cycle. `read` also takes `--sheet <name>` (limit output to one sheet — unknown name fails with the available list) and `--range <sheet>!<A1:G60>` (limit to a cell window; the `<sheet>!` prefix is optional when `--sheet` supplies the sheet, a single cell like `S1!B2` is a 1×1 window) to trim a large workbook's JSON — the output shape is unchanged, only the `sheets` array and each sheet's `cells` map are filtered. Atomic in-place write (temp file + rename). |
+| `lotics xlsx <subcmd>` | Local .xlsx read/write/edit using the bundled `@lotics/xlsx` engine (no auth, no network). 14 named subcommands (read, write, set-cell, clear-range, merge, unmerge, add-sheet, delete-sheet, rename-sheet, insert-rows, delete-rows, insert-cols, delete-cols, set-style) + `batch` for applying multiple of the same 14 ops in a single parse/export cycle. `read` also takes `--sheet <name>` (limit output to one sheet — unknown name fails with the available list) and `--range <sheet>!<A1:G60>` (limit to a cell window; the `<sheet>!` prefix is optional when `--sheet` supplies the sheet, a single cell like `S1!B2` is a 1×1 window) to trim a large workbook's JSON — the output shape is unchanged, only the `sheets` array and each sheet's `cells` map are filtered. **`read` reports formatting back, so a generated file is verifiable through this path** rather than by unzipping OOXML: each cell carries `numFmt` when the file gave it one, and `--with-format` adds the resolved `style`. The asymmetry is deliberate — a parsed cell's style is *never* absent (every cell resolves to at least a font — size, name, colour), so emitting it by default would put three noise keys on every plain cell and make “is this styled?” unanswerable by presence; `numFmt` is genuinely absent on an unformatted cell, so it needs no flag. **`write` takes sheet-level `colWidths` (`{"A":34}`) and `rowHeights` (`{"1":44}`)** — without them every column is the default width and a human-facing workbook is unreadable no matter what the cells say. Both are written *pinned* (`customWidth`/`customHeight`), so Excel does not auto-fit them away, and both apply to a row/column that holds no cells (a spacer row's height survives). Keys are a bare column letter and a bare row number, bounded by Excel's grid (`A`…`XFD`, `1`…`1048576`): a key outside it, or a cell ref like `A1` where a column letter belongs, is **rejected** rather than resolved to something adjacent — past the grid the reference is written into the file verbatim, addressing a cell that cannot exist. Unknown **sheet** properties are rejected on the same terms as unknown cell properties — a silently-ignored `columnWidths` typo is a file that looks written and is not. Atomic in-place write (temp file + rename). |
 | `lotics docx <subcmd>` | Local .docx read/write/edit using the bundled `@lotics/docx` engine (OOXML round-trip surface only — no ProseMirror baggage). Subcommands: read, write, append-paragraph, insert-paragraph, delete-block, replace-text, batch. A legacy `.doc` (Word 97–2003 OLE2 binary) is detected in `loadFile` and routed through `@lotics/ooxml`'s `loadDocxFromBuffer` (which re-emits it as real OOXML) before reading — so `lotics docx read` works on a `.doc`, not just a `.docx`. Opaque blocks (tables, custom XML) preserved verbatim. Atomic in-place write. **`replace-text` matches across run boundaries** — Word splits a run at every formatting change, so a `{{marker}}` routinely lands split — and reads straight THROUGH marks that occupy no place in the sentence (`w:proofErr`, `w:footnoteReference`, endnote/comment refs + ranges, `w:bookmarkStart`/`End`, `w:lastRenderedPageBreak`). `w:proofErr` is the one that decides whether this works in practice — Word brackets every word its dictionary rejects, so on non-English text it lands between nearly every pair of runs. It still refuses to join across anything that occupies space in the text — `w:br`, `w:tab`, `w:sym`, a drawing, or any tag not on that allowlist — because the joined string does not represent the glyph and a match there would rewrite text the caller never saw. The SAME rule applies inside a table cell as outside it — both run one `replaceInParagraph` over paragraphs found at any depth, so a marker split by a line break is refused in both rather than rewritten in the cell and skipped in the body under a success message. Zero matches is always a hard error, never a silent no-op, and when the words ARE on the page the error names the block and the splitting mark (`The text IS present at block 1, split by w:br …`) rather than claiming the text is absent. |
 | `lotics file preview <file\|fil_id> [-o out.png]` | (also `lotics preview`) Render a .docx/.xlsx to a PNG using the SAME engines the frontend FilePreview uses (`@lotics/docx` `loadDocxIntoElement` / `@lotics/xlsx` `drawSpreadsheet`) — so what you see matches an operator. Accepts a **local path** OR a stored **`fil_…` id** (`isStoredFileId` — a bare id, no extension): an id is first downloaded to a temp dir via `downloadFileById` (the `signed_url` presign path — same authority as `lotics file download`), rendered, then the transient source is removed; with no `-o` the PNG lands in cwd under the stored file's base name (`defaultPreviewOutputPath`). Drives a headless Chrome over **CDP with only Node built-ins** (`WebSocket`/`fetch`/`http`/`child_process`) — zero npm deps, the CLI stays a single bundled binary. The browser render logic is a separate esbuild **browser** bundle shipped at `dist/render_page.js` (built by `build_cli.mjs`, excluded from the node `tsgo`), served over a throwaway localhost http server and screenshotted full-page. **Requires a Chrome/Chromium on the machine** — detected from `CHROME_PATH`/`LOTICS_CHROME`, then Playwright's installed chromium, then system paths — inherent to rendering these browser formats; a clear "install a browser" error otherwise. PDFs need no render (open them directly). |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.112.0",
+  "version": "0.113.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {