@kimdayoun/hwpx-mcp 0.3.0 → 0.3.4

package/dist/HwpxDocument.d.ts

@@ -59,16 +59,34 @@ export declare class HwpxDocument {
     private _zip;
     private _content;
     private _isDirty;
+    /**
+     * True once the section element list has changed shape since the XML was
+     * parsed (insert/delete/copy/move of paragraphs, tables or images).
+     * Parsed XML offsets are unusable from that point until the next save.
+     */
+    private _structureChanged;
     private _format;
     private _undoStack;
     private _redoStack;
     private _pendingTextReplacements;
     private _pendingDirectTextUpdates;
+    /**
+     * `col` is the cell's position in the memory row; `colAddr` is its grid column.
+     * They differ after a merge: memory keeps covered cells, the XML drops them.
+     * The XML writer finds the target by colAddr so a write made after a merge
+     * lands in the right cell (writes now replay in call order).
+     */
     private _pendingTableCellUpdates;
     private _pendingNestedTableInserts;
     private _pendingImageInserts;
     private _pendingCellImageInserts;
     private _pendingTableInserts;
+    /**
+     * Monotonic counter shared by paragraph and table inserts. Both kinds are
+     * replayed into XML in this order so each insert sees exactly the elements
+     * that existed when it was made. Replaying all tables before all paragraphs
+     * wrote "A, table, A-2, table" to disk as "A, A-2, table, table".
+     */
     private _tableInsertCounter;
     private _pendingImageDeletes;
     private _pendingTableDeletes;
@@ -84,10 +102,25 @@ export declare class HwpxDocument {
     private _pendingTableRowDeletes;
     private _pendingTableColumnInserts;
     private _pendingTableColumnDeletes;
+    /**
+     * Call order of every pending edit that names a table cell or row/column by
+     * index. Each such index is relative to the table as it was at call time,
+     * so save must replay these edits in call order (applyTableOpsInCallOrder).
+     * A WeakMap keeps the queue element types unchanged and drops entries with
+     * their ops (undo, section delete).
+     */
+    private _tableOpSeq;
+    private _tableOpCounter;
     private _pendingParagraphCopies;
     private _pendingParagraphMoves;
     private _pendingHeaderUpdates;
     private _pendingFooterUpdates;
+    /**
+     * New sections to materialise as Contents/sectionN.xml on save, in call
+     * order. `templateFrom` is the section whose <hp:secPr> (page size, margins)
+     * the new section copies — Hancom's own "insert section" does the same.
+     */
+    private _pendingSectionOps;
     private _charPrCache;
     private _originalCharPrCount?;
     private constructor();
@@ -107,10 +140,19 @@ export declare class HwpxDocument {
     static createNew(id: string, title?: string, creator?: string): HwpxDocument;
     get id(): string;
     get path(): string;
+    /** True once the document has a real location on disk. */
+    get hasPath(): boolean;
+    /**
+     * Record where the document now lives after a successful write, so the next
+     * save without an explicit path targets the same file.
+     */
+    setPath(newPath: string): void;
     get format(): DocumentFormat;
     get isDirty(): boolean;
     get zip(): JSZip | null;
     get content(): HwpxContent;
+    /** Push a table-structure or table-cell edit and remember its call order. */
+    private queueTableOp;
     private saveState;
     private serializeContent;
     private deserializeContent;
@@ -128,6 +170,32 @@ export declare class HwpxDocument {
      * Call this after any modification that changes document structure or content.
      */
     private markModified;
+    /**
+     * Record that the section element list changed shape. Call from every method
+     * that inserts, removes, copies or moves a section-level element. Once set,
+     * paragraph edits stop trusting offsets cached at parse time and locate their
+     * target in the current XML instead.
+     */
+    private markStructureChanged;
+    /**
+     * Resolve "after element N" into an id-based anchor using the memory model
+     * as it is right now (before the new element is spliced in).
+     *
+     * Returns null for "before everything" (N < 0). Elements without an XML
+     * paragraph/table of their own (images, shapes) are skipped backwards to the
+     * nearest paragraph or table, which is what the XML placement needs.
+     *
+     * The parser turns a paragraph that is only a line of ─/━/═ into an 'hr'
+     * element with a fresh id. That paragraph is still in the XML, so it still
+     * takes an occurrence slot there: skipping it here put later anchors one
+     * paragraph early (measured on Hancom files with divider lines).
+     */
+    private resolveElementAnchor;
+    /**
+     * The XML node a memory element stands for, or null if it has none of its
+     * own. An 'hr' parsed from a divider paragraph stands for that paragraph.
+     */
+    private anchorKeyOf;
     getSerializableContent(): object;
     getAllText(): string;
     getStructure(): object;
@@ -137,11 +205,15 @@ export declare class HwpxDocument {
         index: number;
         text: string;
         style?: ParagraphStyle;
+        paraPrIDRef?: number;
+        charPrIDRef?: number;
     }>;
     getParagraph(sectionIndex: number, paragraphIndex: number): {
         text: string;
         runs: TextRun[];
         style?: ParagraphStyle;
+        paraPrIDRef?: number;
+        charPrIDRef?: number;
     } | null;
     updateParagraphText(sectionIndex: number, elementIndex: number, runIndex: number, text: string): void;
     updateParagraphRuns(sectionIndex: number, elementIndex: number, runs: TextRun[]): void;
@@ -304,9 +376,19 @@ export declare class HwpxDocument {
     /**
      * Get table map with headers - maps table indices to their header paragraphs
      * Returns array of table info including the header text from the preceding paragraph
+     *
+     * Two indices are returned because they differ once a document has more than
+     * one section:
+     *  - `table_index_in_section` — what every table tool (update_table_cell,
+     *    get_table_cell, insert_table_row, …) expects together with
+     *    `section_index`. Use this one.
+     *  - `table_index` — position across the whole document, kept for callers
+     *    that list tables. Passing it to a table tool in section 1+ addresses a
+     *    DIFFERENT table (reported 2026-09-24: map said 5, the tool needed 4).
      */
     getTableMap(): Array<{
         table_index: number;
+        table_index_in_section: number;
         section_index: number;
         header: string;
         rows: number;
@@ -433,6 +515,12 @@ export declare class HwpxDocument {
             col: number;
             value: string;
         }>;
+        failed: Array<{
+            row: number;
+            col: number;
+            value: string;
+            error: string;
+        }>;
         updated: Array<{
             row: number;
             col: number;
@@ -568,6 +656,12 @@ export declare class HwpxDocument {
         text: string;
         cell: TableCell;
     } | null;
+    /**
+     * Find the merged cell that covers (row, col), if that position is not itself
+     * a master cell. A covered cell has no <hp:tc> of its own in the saved XML,
+     * so writing to it succeeds in memory and then silently vanishes on save.
+     */
+    private findCoveringMergedCell;
     updateTableCell(sectionIndex: number, tableIndex: number, row: number, col: number, text: string, charShapeId?: number): boolean;
     setCellProperties(sectionIndex: number, tableIndex: number, row: number, col: number, props: Partial<TableCell>): boolean;
     insertTableRow(sectionIndex: number, tableIndex: number, afterRowIndex: number, cellTexts?: string[]): boolean;
@@ -832,6 +926,12 @@ export declare class HwpxDocument {
         pageSettings: PageSettings;
     }[];
     insertSection(afterSectionIndex: number): number;
+    /**
+     * Add `delta` to every section number held by a pending edit that is >= from.
+     * Covers all pending arrays generically: any numeric field whose name is
+     * sectionIndex or ends in "Section"/"SectionIndex" (source/target pairs).
+     */
+    private shiftPendingSectionIndices;
     deleteSection(sectionIndex: number): boolean;
     getStyles(): {
         id: number;
@@ -880,10 +980,68 @@ export declare class HwpxDocument {
      */
     private applyParagraphDeletesToXml;
     /**
-     * Apply table inserts to XML.
-     * Inserts new tables into the section XML.
+     * Find the end offset of the section-level element an insert anchors to.
+     *
+     * Paragraphs are matched by their own <hp:p id>. Tables are matched by
+     * <hp:tbl id>, either wrapped in a paragraph (the insert goes after that
+     * paragraph) or placed directly in the section (move_table writes them that
+     * way).
+     *
+     * The returned offset is always the end of a TOP-LEVEL element, because that
+     * is the only place a new section-level element may go. But paragraph
+     * occurrences are counted over exactly the paragraphs the parser puts in the
+     * memory model (see parsedParagraphStarts), so they agree with the occurrence
+     * resolveElementAnchor recorded. The parser also lifts paragraphs out of
+     * headers, text boxes and shapes; Hancom reuses id="0" / id="2147483648"
+     * there too. Counting only top-level paragraphs put 47 of 131 sampled Hancom
+     * files' copies and moves on the wrong paragraph.
+     *
+     * Returns -1 if the anchor is not present in the current XML.
+     */
+    private findAnchorEnd;
+    /**
+     * The exact XML range of the memory paragraph a paragraph anchor names,
+     * found by id + occurrence among parsedParagraphStarts. For a paragraph in a
+     * header or text box this is that paragraph alone, not its container.
      */
-    private applyTableInsertsToXml;
+    private findParsedParagraph;
+    /**
+     * Start offsets (in `xml`) of the paragraphs HwpxParser turns into memory
+     * paragraphs, in document order. Mirrors HwpxParser.parseSection:
+     *
+     *  - MEMO fields, footnotes and endnotes are ignored;
+     *  - paragraphs inside any table are skipped;
+     *  - a paragraph that holds a table is kept only if it still has <hp:t>
+     *    once its tables are removed.
+     *
+     * Offsets are mapped back to the original XML, so callers can slice it.
+     */
+    private parsedParagraphStarts;
+    /** Every <hp:tbl> range at any depth (outer tables before their nested ones). */
+    private findAllTablesDeep;
+    /** End offset of the paragraph opening at `start`, counting nested <hp:p>. */
+    private findBalancedParagraphEnd;
+    /** True if this paragraph directly (not via a nested table) holds <hp:tbl id>. */
+    private wrapsTopLevelTable;
+    /**
+     * Offset for an insert with no anchor ("before everything"). The first
+     * paragraph carries <hp:secPr> (page and section settings) and must stay
+     * first, so new content goes right after it.
+     */
+    private findSectionHeadEnd;
+    /** Build the XML for a table inserted by insertTable, wrapped in its own paragraph. */
+    private buildInsertedTableXml;
+    /**
+     * Replay structural edits — paragraph/table inserts and paragraph
+     * copies/moves — into the section XML in the order the calls were made.
+     *
+     * Every edit carries id-based anchors resolved at call time, so it lands
+     * after the same element in the XML that it followed in memory. Replaying in
+     * call order means each anchor already exists (or has already moved) by the
+     * time a later edit needs it. Copies/moves may cross sections, so all
+     * touched sections are held in memory and written once at the end.
+     */
+    private applyStructuralInsertsToXml;
     /**
      * Apply table move/copy operations to XML.
      * Extracts table XML from source and inserts at target position.
@@ -898,11 +1056,6 @@ export declare class HwpxDocument {
      * Returns the position after the closing tag of the element.
      */
     private findInsertPositionForElement;
-    /**
-     * Apply paragraph inserts to XML.
-     * Inserts new paragraphs at the specified positions.
-     */
-    private applyParagraphInsertsToXml;
     /**
      * Apply nested table inserts to XML.
      * Inserts a new table inside a cell of an existing table.
@@ -911,6 +1064,24 @@ export declare class HwpxDocument {
     /**
      * Generate XML for a nested table.
      */
+    /**
+     * Usable width inside a table cell, in hwpunit.
+     *
+     * A cell with hasMargin="0" takes its padding from the table's inMargin, so
+     * the cell's own cellMargin is only authoritative when hasMargin="1".
+     *
+     * Every lookup is scoped to the cell's (or table's) own markup. A nested
+     * table inside the cell carries its own cellSz/cellMargin/inMargin, and a
+     * first-match regex over the whole cell would read those instead — which
+     * sized a second nested table to the first one's column (7086 vs 21260).
+     */
+    private getCellInnerWidth;
+    /**
+     * Generate XML for a nested table.
+     *
+     * @param innerWidth Usable width of the parent cell in hwpunit. The nested
+     *   table is sized to fit it exactly; columns share the width evenly.
+     */
     private generateNestedTableXml;
     /**
      * Insert a nested table XML into a cell XML.
@@ -942,6 +1113,19 @@ export declare class HwpxDocument {
      * Generate an empty cell XML for split operations.
      */
     private generateEmptyCell;
+    /**
+     * Replay every pending table edit (cell text, merge/split, nested table,
+     * cell image, cell hanging indent, row/column insert/delete) in call order.
+     *
+     * Each index an edit carries is relative to the table as it was when the
+     * edit was made. Applying by kind (all cell writes, then all row inserts,
+     * then all column inserts ...) wrote text into the pre-insert layout; and
+     * the row appliers sort their own queue by index, which reorders two
+     * inserts or two deletes on the same table. So edits that change a table's
+     * row/column layout run one at a time. Runs of layout-preserving edits
+     * (cell text, indents, images, nested tables) go to their applier together.
+     */
+    private applyTableOpsInCallOrder;
     /**
      * Apply table cell updates to XML while preserving original structure.
      * This function modifies only the text content of specific cells,
@@ -1063,8 +1247,10 @@ export declare class HwpxDocument {
      */
     private replaceMultipleRunsInElement;
     /**
-     * Calculate the occurrence index for a paragraph with given ID.
-     * Returns how many paragraphs with the same ID appear before this one.
+     * Occurrence index of the paragraph at `elementIndex` among paragraphs with
+     * the same id — counted with the same rule as insert anchors
+     * (resolveElementAnchor), so a text update finds the paragraph that
+     * findParsedParagraph resolves. Divider paragraphs parsed as 'hr' count.
      */
     private getParagraphOccurrence;
     /**
@@ -1096,6 +1282,23 @@ export declare class HwpxDocument {
      * Finds hp:run elements and updates their hp:t content.
      */
     private replaceRunsInParagraphDirect;
+    /** Container elements whose content belongs to OTHER paragraphs or objects. */
+    private static readonly NESTED_CONTENT;
+    /** Direct <hp:run> children of a paragraph (runs of nested paragraphs excluded). */
+    private findDirectChildRuns;
+    /**
+     * A run's own markup with every nested container (table, equation, text box,
+     * note…) blanked out, so its <hp:t> are the run's own text only.
+     */
+    private ownRunText;
+    /**
+     * Apply `fn` to the parts of a run that are its own text, leaving nested
+     * containers byte-for-byte intact. With `blank`, nested containers are
+     * replaced by an empty marker instead (for reading).
+     */
+    private mapOwnRunText;
+    /** End offset of the <hp:name> element opening at `start` (handles nesting and self-closing). */
+    private findElementEnd;
     /**
      * Replace text in a single run directly using pre-computed target location.
      * Simpler version for single-run updates.
@@ -1277,6 +1480,17 @@ export declare class HwpxDocument {
      * Add image entry to content.hpf manifest
      */
     private addImageToContentHpf;
+    /**
+     * Apply section inserts/deletes to Contents/sectionN.xml, in call order.
+     *
+     * File numbers must keep matching memory section indices, so an insert
+     * renames later files up one (section1 → section2 …) and a delete removes
+     * its file and renames later files down one. content.hpf gets a manifest
+     * item and a spine itemref per section, and header.xml's secCnt follows.
+     */
+    private applySectionOpsToZip;
+    /** A section XML holding one empty paragraph with the template's <hp:secPr>. */
+    private buildEmptySectionXml;
     /**
      * Add hp:pic tag to section XML
      */
@@ -1591,6 +1805,57 @@ export declare class HwpxDocument {
      * @returns Cell XML content and its position, or null if not found
      */
     private findTableCellInXml;
+    /**
+     * Scale this table's column widths so they sum to its <hp:sz width>.
+     *
+     * Column widths are read from cells whose colSpan is 1 (the first one seen
+     * per colAddr). Every cell then gets the sum of the scaled widths of the
+     * columns it spans, so merged cells stay aligned. Rounding leftovers go to
+     * the last column so the total is exact. Nested tables are not touched.
+     */
+    private fitColumnsToTableWidth;
+    /**
+     * Locate one of a cell's OWN address/span attributes (`colAddr`, `rowAddr`,
+     * `colSpan`, `rowSpan`) in `cellXml`, returning the value and the absolute
+     * index of its digits so callers can rewrite it in place.
+     *
+     * Hancom writes them on `<hp:cellAddr>`/`<hp:cellSpan>` after the cell's
+     * sub-list (209/209 corpus files). Hand-made files may put them on the
+     * `<hp:tc>` start tag instead, which the parser also accepts. A nested
+     * table's cells live inside the sub-list, so only the tail is searched for
+     * the child form and only the start tag for the attribute form.
+     */
+    private cellOwnAttr;
+    /** Rewrite one of a cell's own attributes (see cellOwnAttr); no-op if absent. */
+    private setCellOwnAttr;
+    /** A cell's own <hp:cellSz width> (after its sub-list, so never a nested table's). */
+    private cellOwnWidth;
+    /** Rewrite a cell's own <hp:cellSz width>; no-op if the cell has none or width <= 0. */
+    private setCellOwnWidth;
+    /**
+     * Add `delta` to the rowAddr of every cell of THIS table whose rowAddr is
+     * >= fromRow. Nested tables inside cells keep their own addresses.
+     */
+    private shiftTableRowAddrs;
+    /**
+     * Clone a table cell for a newly inserted row: same cell attributes, same
+     * first-paragraph formatting, but a single paragraph holding `text`.
+     *
+     * Nested tables and extra paragraphs are dropped. The first run's
+     * charPrIDRef is kept so the new text matches the template cell's font.
+     */
+    private cloneCellWithText;
+    /**
+     * Source cells for a new row inserted after `afterRow`, one per column
+     * position, in column order, covering every column 0..colCnt-1 exactly once.
+     *
+     * For each column: the cell that STARTS there in the template row (keeping
+     * its colSpan so horizontal merges carry over), otherwise the nearest row
+     * above whose own cell starts there. A column no row starts is skipped by the
+     * colSpan of the cell covering it. Returned XML still carries the source
+     * addresses; the caller rewrites rowAddr/rowSpan.
+     */
+    private gridCellsForNewRow;
     private applyTableRowInsertsToXml;
     private applyTableRowDeletesToXml;
     private applyTableColumnInsertsToXml;
@@ -1600,8 +1865,6 @@ export declare class HwpxDocument {
      * Returns elements with their complete XML (including closing tags).
      */
     private findTopLevelFullElements;
-    private applyParagraphCopiesToXml;
-    private applyParagraphMovesToXml;
     private applyHeaderFooterUpdatesToXml;
 }
 export {};