@kimdayoun/hwpx-mcp 0.3.0 → 0.3.3

package/dist/HwpxDocument.d.ts

@@ -59,6 +59,12 @@ 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;
@@ -69,6 +75,12 @@ export declare class HwpxDocument {
     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;
@@ -107,6 +119,13 @@ 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;
@@ -128,6 +147,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 +182,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;
@@ -433,6 +482,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 +623,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;
@@ -880,10 +941,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 +1017,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 +1025,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.
@@ -1063,8 +1195,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;
     /**
@@ -1591,6 +1725,14 @@ export declare class HwpxDocument {
      * @returns Cell XML content and its position, or null if not found
      */
     private findTableCellInXml;
+    /**
+     * 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;
     private applyTableRowInsertsToXml;
     private applyTableRowDeletesToXml;
     private applyTableColumnInsertsToXml;
@@ -1600,8 +1742,6 @@ export declare class HwpxDocument {
      * Returns elements with their complete XML (including closing tags).
      */
     private findTopLevelFullElements;
-    private applyParagraphCopiesToXml;
-    private applyParagraphMovesToXml;
     private applyHeaderFooterUpdatesToXml;
 }
 export {};