myrole-docx-editor 0.1.0

package/dist/types/packages/docx-render/src/types.d.ts

@@ -0,0 +1,514 @@
+import type { StyledParagraph, BodyBlock, TableInfo } from '../../docx-model/src/index';
+/** Carte des images pré-chargées, indexée par chemin cible dans le .docx. */
+export type ImageMap = Map<string, ImageBitmap>;
+export declare const PT_PX: number;
+/** Numéro de page courant et total, pour recalculer les champs PAGE/NUMPAGES. */
+export interface PageNums {
+    page: number;
+    total: number;
+    /** `w:pgNumType w:fmt` — `decimal` par défaut, `numberInDash` écrit « - 3 - » */
+    fmt?: string;
+}
+/**
+ * Tout ce dont un dessinateur a besoin, et qu'il fait avancer.
+ *
+ * `y` et `ctx` sont mutables et le RESTENT : après un saut de page, `ctx`
+ * désigne un autre canvas. Un dessinateur qui en garde une copie locale peint
+ * sur la page précédente — c'est le bug le plus coûteux qu'ait connu ce module.
+ */
+export interface DrawCtx {
+    /** on compose DÉJÀ l'intérieur d'un `w:framePr` — ne pas le re-sortir du fil */
+    inFrame?: boolean;
+    /**
+     * Rien n'a encore été dessiné en haut de cette PAGE.
+     *
+     * Word y jette tout l'espacement vertical — l'« après » du paragraphe qui
+     * portait le saut comme l'« avant » de celui qui ouvre la page. Mesuré au
+     * banc, sondes `hautpage-*` : la première ligne de la page 2 tombe à y57,0
+     * dans les trois cas, avec ou sans 8 pt déclarés.
+     *
+     * En tête de COLONNE c'est l'inverse — sondes `hautcol-*` : y69,7 sans
+     * espacement, y77,6 avec, les 8 pt bien posés. D'où ce drapeau plutôt qu'une
+     * règle unique.
+     */
+    atPageTop?: boolean;
+    /**
+     * Bas atteint par les paragraphes ENCADRÉS dont le texte est habillé
+     * (`w:framePr` sans `w:wrap="none"`).
+     *
+     * Un cadre ne fait jamais avancer le fil — Word y fait passer le texte à
+     * côté, pas dessous. Mais la HAUTEUR D'UN EN-TÊTE ou d'un pied, elle, doit
+     * l'englober : sur Vanished, le numéro de page encadré de l'en-tête descend
+     * le corps de 12 pt sur chaque page. Le réserver dans le fil du CORPS, en
+     * revanche, coûtait 52 points à Andersons.
+     */
+    frameBottom?: number;
+    ctx: CanvasRenderingContext2D;
+    def: {
+        font: string;
+        sizePt: number;
+    };
+    y: number;
+    contentLeft: number;
+    contentWidth: number;
+    pageBottom: number;
+    /**
+     * Passe à la page (ou colonne) suivante.
+     *
+     * `force` réclame une vraie PAGE : un `w:br w:type="page"` ne se contente pas
+     * de la colonne d'à côté.
+     */
+    onPageBreak?: (force?: boolean, cause?: string) => void;
+    images?: ImageMap;
+    /** page courante, pour situer les rectangles remontés — 1 par défaut */
+    page?: number;
+    onMark?(rect: MarkRect): void;
+    /**
+     * Un appel de note vient d'être composé sur la page `page`.
+     *
+     * Le moteur s'en sert pour savoir quelles notes vont au bas de quelle page —
+     * ce qui décide de la place qu'il faut leur réserver, donc de tout ce qui
+     * tient sur la page.
+     */
+    onFootnote?(n: number, page: number): void;
+    /**
+     * Bas utile de la page `page`, réserve des notes comprise.
+     *
+     * `pageBottom` est figé à la création du contexte, ce qui suffit au fil
+     * principal — il en refait un par bloc — mais pas à une CELLULE, qui traverse
+     * les pages avec le sien. Sans cette fonction, une cellule qui passe sur une
+     * page portant des notes ignorait leur réserve.
+     */
+    bottomOf?(page: number): number;
+    /** On compose le contenu d'une CELLULE — Word y ignore le saut de page explicite. */
+    inCell?: boolean;
+    /**
+     * Le bas atteint par un rang de tableau IMBRIQUÉ sur chaque page traversée.
+     *
+     * Un rang se ferme sous sa dernière ligne, et la cellule qui le porte ne sait
+     * où celle-ci est tombée que par son propre `onPageBreak` — qu'un tableau
+     * imbriqué ne déclenche JAMAIS, puisqu'il change de page tout seul. Sur
+     * « CREW CINE SKYLARK » page 18, le rang ANNEXE se refermait donc à 502,6 pt
+     * quand ses tableaux imbriqués descendaient à 519,2 : le filet passait
+     * PAR-DESSUS ses deux dernières lignes.
+     */
+    onRowBottom?(page: number, y: number): void;
+    /**
+     * Densité de la surface, pour accrocher les FILETS à la grille de pixels.
+     *
+     * Un trait tracé est CENTRÉ sur son chemin : un filet de 0,5 pt posé sur une
+     * ligne de grille déborde d'un quart de point de chaque côté et tombe à cheval
+     * sur deux rangées de pixels, à n'importe quelle densité. Word ne les trace
+     * pas — son PDF les REMPLIT (108 opérateurs `f`, zéro `w` dans le flux de la
+     * page 1 de « Cascadeur BRIARCLIFF ») — et leurs arêtes tombent sur des
+     * pixels entiers. Connaître la densité ici permet d'en faire autant.
+     */
+    dpr?: number;
+    /** trace de layout — publie chaque ligne dessinée pour comparaison avec Word */
+    onLine?(line: LineTrace): void;
+    /** publie le rectangle de chaque image dessinée — la souris n'a que ça */
+    onImage?(rect: ImageRect): void;
+    /** Chaque TRAIT dessiné — voir `RuleTrace`. */
+    onRule?(rule: RuleTrace): void;
+    /**
+     * Un RANG de tableau composé, avec la hauteur que nous lui donnons.
+     *
+     * Word publie la sienne dans son rendu (l'écart entre la première ligne d'un
+     * rang et celle du suivant) : sans ce rappel, les deux ne se comparaient
+     * qu'indirectement, en changeant une règle et en regardant le score bouger.
+     */
+    onRow?(row: RowTrace): void;
+    /**
+     * Chaque changement de page ou de colonne, avec sa cause.
+     *
+     * Sans elle, un document qui fabrique des pages ne se diagnostique qu'à
+     * tâtons : le rendu tourne dans le navigateur, on ne voit que le résultat. Ce
+     * rapport dit QUI a coupé, et à quelle hauteur — c'est la moitié du travail.
+     */
+    onBreak?(b: {
+        page: number;
+        y: number;
+        cause: string;
+        bloc?: number;
+    }): void;
+    /** Bloc en cours de composition, reporté sur chaque ligne publiée. */
+    blockIdx?: number;
+    /** zone dessinée — 'body' par défaut */
+    part?: 'body' | 'header' | 'footer';
+    /** w:defaultTabStop du document, en points (36 par défaut) */
+    defaultTabPt?: number;
+    /**
+     * `w:doNotExpandShiftReturn` — une ligne justifiée qui finit par un `w:br`
+     * n'est pas étirée à la colonne. 115 des 400 documents mesurés le posent.
+     */
+    noExpandShiftReturn?: boolean;
+    /**
+     * compatibilityMode < 15 — Word 2010 and earlier never condense the blanks
+     * of a justified line to keep its last word; only Word 2013+ does (`keepsWord`).
+     * Measured on 4 400 of Word's own decisions in 39 such documents: the
+     * condensing rule agrees with 75.8 % of them, "send the word down whenever it
+     * overflows" with 98.7 %. 134 corpus documents are in a legacy mode.
+     */
+    legacyWrap?: boolean;
+    /** `w:ulTrailSpace` — le soulignement couvre l'espace de fin de ligne */
+    ulTrailSpace?: boolean;
+    /** numéro de page courant et total, pour les champs PAGE/NUMPAGES */
+    nums?: PageNums;
+    /**
+     * Contexte de la page `idx` (0-based), créée au besoin.
+     *
+     * Un rang de tableau plus haut qu'une page doit continuer sur la suivante,
+     * colonne par colonne : chaque cellule a besoin de revenir sur la même page
+     * que ses voisines. Sans ça, tout ce qui dépassait était dessiné hors du
+     * canvas — donc perdu (mesuré à 680 pt hors page sur un contrat bilingue).
+     */
+    pageAt?(idx: number): {
+        ctx: CanvasRenderingContext2D;
+        top: number;
+    };
+    /**
+     * Annonce le début d'un rang de tableau, et le rang du premier paragraphe
+     * qu'il porte. Un contrat de 42 pages ne compte que dix blocs — sans ce
+     * repère, la composition incrémentale n'aurait aucun point où reprendre.
+     */
+    onRowStart?(row: number, para: number): void;
+    /**
+     * Publie le rectangle d'un TABLEAU, un par page qu'il occupe.
+     *
+     * Un tableau ne s'attrape pas par son texte : le curseur y tombe toujours
+     * dans une cellule. Sans ce rectangle, on ne peut ni le prendre comme un
+     * tout, ni lui poser une poignée. Le rang dans `tables()` est ajouté par le
+     * renderer, qui seul sait quel bloc il dessine.
+     */
+    onTable?(rect: {
+        page: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Le contrôle des orphelines s'applique-t-il dans ce flux ?
+     *
+     * Le renderer le décide pour le corps (il le désactive en multi-colonnes, où
+     * il se bat avec l'équilibrage) ; les cellules en héritent. Sans lui, tout
+     * document dont le corps tient dans un tableau n'avait aucun contrôle des
+     * orphelines — « Vanished » laissait une première ligne seule en bas de page
+     * et perdait une page entière de correspondance.
+     */
+    widowControl?: boolean;
+    /**
+     * `w:spacing w:after` déjà appliqué par le paragraphe précédent.
+     *
+     * Word ne CUMULE pas l'espacement après un paragraphe et celui avant le
+     * suivant : il prend le plus grand des deux (mesuré au banc de sondes —
+     * before=6pt et after=6pt donnent 6 pt, pas 12). On garde donc ce qui a déjà
+     * été posé pour ne compléter que la différence.
+     */
+    prevSpaceAfter?: number;
+    /**
+     * Haut du corps de page, en pixels.
+     *
+     * Sert à savoir ce qu'une page ENTIÈRE peut contenir, et donc si changer de
+     * page servirait à quelque chose : une ligne de tableau plus haute qu'une
+     * page ne tiendra pas mieux sur la suivante.
+     */
+    bodyTop?: number;
+    /** style du paragraphe précédent — `w:contextualSpacing` ne joue qu'entre égaux */
+    prevStyleId?: string;
+    /** le paragraphe précédent déclarait-il `w:contextualSpacing` ? */
+    prevContextual?: boolean;
+    /**
+     * Rang du paragraphe en cours de dessin dans `paragraphs`.
+     *
+     * C'est la moitié de l'adresse qu'un curseur réclame — l'autre moitié est le
+     * rang du caractère, que le jeton porte. `undefined` pour ce qui ne vit pas
+     * dans le fil du corps : en-tête, pied, zone de texte ancrée. Ces
+     * paragraphes-là ne sont pas dans `paragraphs(doc)`, donc pas adressables.
+     */
+    paraIndex?: number;
+    /**
+     * Fichier du zip où vit le paragraphe dessiné — `undefined` pour le corps.
+     *
+     * Un en-tête est fait des mêmes `w:p` dans un autre fichier. Sans ce chemin,
+     * son rang de paragraphe désignerait le corps, et le curseur écrirait dans
+     * un tout autre texte.
+     */
+    partPath?: string;
+    /**
+     * Publier aussi les lignes SANS texte.
+     *
+     * Un paragraphe vide n'a rien à comparer au PDF de Word : le banc l'ignore, et
+     * l'ajouter à ses appariements fausserait ses mesures. L'éditeur, lui, en a
+     * besoin — sans sa géométrie, on ne peut pas poser un curseur sur une ligne
+     * vide, et ces matrices en comptent des centaines.
+     */
+    traceEmpty?: boolean;
+    /**
+     * Facteur correctif Canvas→hmtx par police.
+     *
+     * Canvas (CoreText/macOS) mesure les glyphes ~1% plus large que les avances
+     * du TTF. Multiplier `measureText().width` par ce facteur corrige la mesure
+     * sans toucher au dessin — la justification étire/comprime ensuite.
+     */
+    widthCorrections?: Record<string, number>;
+}
+/** Un rang de tableau composé, pour comparer sa hauteur à celle de Word. */
+export interface RowTrace {
+    /** index du BLOC du corps qui porte ce tableau */
+    bloc?: number;
+    page: number;
+    /** haut du rang, en px CSS */
+    y: number;
+    /** hauteur du rang, en px CSS — trait compris, comme chez Word */
+    height: number;
+    rowIdx: number;
+    rows: number;
+    /** premier texte non vide du rang, pour l'apparier au rendu de Word */
+    text: string;
+}
+/** Une ligne dessinée sur le canvas, pour comparer avec pdftotext -bbox */
+/**
+ * Un TRAIT dessiné — bordure de tableau, de paragraphe, de run, soulignement.
+ *
+ * Ni la bordure ni la fusion de cellules ne produisent de TEXTE : le banc de
+ * référence, qui apparie des lignes de texte, ne peut pas les voir. C'est le
+ * même angle mort que `w:w`, où 1 912 lignes illisibles laissaient le score
+ * inchangé au centième. Le PDF de Word publie ses traits en vectoriel
+ * (`mutool draw -F trace`) ; il fallait que nous publiions les nôtres.
+ */
+export interface RuleTrace {
+    page: number;
+    /** extrémités du trait, en px CSS, comme `LineTrace` */
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    /** épaisseur en px CSS */
+    widthPx: number;
+    kind: 'table' | 'para' | 'run' | 'underline' | 'strike' | 'footnote';
+}
+/** Les notes de bas de page d'un document, prêtes à composer. */
+export interface Footnotes {
+    /** les paragraphes de toutes les notes, à la suite */
+    paragraphs: StyledParagraph[];
+    /** `[start, end)` dans `paragraphs`, indexé par NUMÉRO d'appel — 0 inutilisé */
+    ranges: Array<{
+        start: number;
+        end: number;
+    }>;
+}
+export interface LineTrace {
+    /**
+     * Index du BLOC dont vient cette ligne.
+     *
+     * Sans lui, `bench breaks` ne pouvait imputer un désaccord de page qu'à « la
+     * rupture publiée juste avant », heuristique qui a déjà fait lire deux fois
+     * de suite une cause pour une autre (voir mesure.md). Avec lui, on remonte de
+     * la dernière ligne d'une page de Word au bloc qui la porte, donc à la
+     * rupture qui décide vraiment.
+     */
+    bloc?: number;
+    page: number;
+    /** position Y de la baseline, en px CSS */
+    y: number;
+    /** haut de la boîte de ligne, en px CSS — `pdftotext -bbox` donne un haut de
+     *  glyphe, pas une baseline : comparer l'un à l'autre inventait 8 pt d'écart */
+    top: number;
+    /** hauteur de la boîte de ligne, en px CSS */
+    height: number;
+    /** position X de départ, en px CSS */
+    x: number;
+    /** largeur totale de la ligne */
+    width: number;
+    /**
+     * Largeur NATURELLE de la ligne, avant justification et hors tabulations.
+     *
+     * `width` est la largeur DESSINÉE : sur une ligne justifiée elle vaut la
+     * colonne, et sur une ligne tabulée elle comprend les blancs des taquets.
+     * Aucune des deux ne se compare à la somme des avances que Word publie dans
+     * son PDF — et c'est cette somme-là qui juge nos métriques.
+     */
+    naturalWidth: number;
+    /**
+     * Échelle horizontale des glyphes (`w:rPr/w:w`), 1 par défaut.
+     *
+     * Publiée pour le banc : `mutool` rapporte pour chaque ligne une taille qui
+     * vaut `sqrt(sx × sy)` — la moyenne géométrique du matriciel de texte — donc
+     * PAS le corps composé dès que Word étire les glyphes. Sans elle, 990 lignes
+     * du « Contrat Runner Multilingue » passaient pour composées à 8 pt là où
+     * Word en annonçait 8,8, alors que les deux valent 8.
+     */
+    scaleX?: number;
+    /** texte de la ligne */
+    text: string;
+    /** taille de police dominante */
+    fontPx: number;
+    /**
+     * Famille et couleur DOMINANTES de la ligne — celles du jeton le plus gros.
+     *
+     * Word publie dans son PDF la police qu'il a RÉELLEMENT composée, y compris
+     * quand il en a substitué une (Times y sort en TimesNewRomanPSMT). Sans ces
+     * deux champs de notre côté, la comparaison ne peut porter que sur des
+     * positions : une page rendue dans la mauvaise police, au bon endroit,
+     * marquait cent pour cent.
+     */
+    fontFamily?: string;
+    color?: string;
+    /** zone de la page — `pdftotext` mélange les trois, il faut pouvoir trier */
+    part: 'body' | 'header' | 'footer';
+    /**
+     * Rang du paragraphe dessiné — `undefined` hors du fil du corps.
+     *
+     * Avec l'`off` des mots, c'est ce qui fait de la trace une carte cliquable :
+     * le renderer publie non seulement où il a dessiné, mais QUOI.
+     */
+    para?: number;
+    /** fichier du zip d'où vient ce paragraphe — `undefined` pour le corps */
+    partPath?: string;
+    /**
+     * Position de chaque mot dessiné, en px CSS.
+     *
+     * `pdftotext -bbox` donne la boîte de chaque mot : comparer mot à mot plutôt
+     * que ligne à ligne, c'est la différence entre une mesure qui a un gradient et
+     * une qui n'en a pas. Une césure différente déplace deux ou trois mots, elle
+     * ne rend pas faux tout le paragraphe.
+     *
+     * `off` est le rang du premier caractère du mot dans le texte du paragraphe,
+     * et `font` la police avec laquelle il a été mesuré — de quoi retrouver un
+     * rang de caractère à l'intérieur du mot, sans le redemander au modèle.
+     */
+    words: Array<{
+        x: number;
+        width: number;
+        text: string;
+        off?: number;
+        font?: string;
+    }>;
+}
+/**
+ * Rectangle d'une IMAGE dessinée, en px CSS relatifs à sa page.
+ *
+ * Une image n'occupe aucun caractère : elle n'a donc pas d'adresse où poser un
+ * curseur, et le hit-test du texte ne la trouvera jamais. Sans ce rectangle,
+ * elle est invisible à la souris — on ne peut ni la sélectionner ni la
+ * redimensionner. `index` est son rang parmi les images de son paragraphe,
+ * le même que celui du contexte.
+ */
+export interface ImageRect {
+    para: number;
+    index: number;
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** posée hors du fil (`wp:anchor`) plutôt qu'entre deux mots */
+    anchored: boolean;
+}
+/**
+ * Rectangle d'un TABLEAU sur une page, en px CSS relatifs à elle.
+ *
+ * Un par page : un tableau qui enjambe trois feuilles en produit trois.
+ */
+export interface TableRect {
+    table: number;
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Rectangle dessiné pour un run marqué, en px CSS relatifs à sa page. */
+export interface MarkRect {
+    mark: string;
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** taille de police du run marqué — un calque peut s'y accorder */
+    fontPx: number;
+}
+/**
+ * Zone de texte ancrée, prête à dessiner.
+ *
+ * Posée à ses coordonnées quand on dessine le paragraphe qui porte son ancre :
+ * elle ne prend aucune place dans le fil et ne compte pas dans la pagination.
+ */
+export interface PlacedTextBox {
+    paraIndex: number;
+    xPt: number;
+    yPt: number;
+    relH: string;
+    relV: string;
+    widthPt: number;
+    heightPt: number;
+    /**
+     * Marges INTERNES du cadre (`a:bodyPr`), en points — 7,2 à gauche et à droite,
+     * 3,6 en haut chez Word par défaut. Elles décalent le texte DANS le cadre.
+     */
+    insetLeftPt: number;
+    insetTopPt: number;
+    insetRightPt: number;
+    /** `none` = flotte sans prendre de place ; sinon Word réserve sa hauteur */
+    wrap: 'none' | 'square' | 'topAndBottom' | 'tight' | 'through';
+    paragraphs: StyledParagraph[];
+    /** `wp:inline` : la zone part du RETRAIT de son paragraphe, pas de la marge */
+    inline?: boolean;
+}
+/** Contenu d'une part composé comme un corps : blocs dans l'ordre, plus les tableaux. */
+export interface PartBlocks {
+    blocks: BodyBlock[];
+    tables: TableInfo[];
+}
+/** En-têtes et pieds résolus pour une section, dans l'ordre de `sections`. */
+export interface SectionParts {
+    /**
+     * En-tête de la PREMIÈRE page.
+     *
+     * Word ne le pose que si la section déclare `w:titlePg` ; c'est à l'appelant
+     * de le vérifier avant de le fournir. Le PIED de première page, lui, n'est
+     * pas encore posé — voir docs/boucle-fidelite.md, « Le pied de première
+     * page ».
+     */
+    firstPageHeader?: StyledParagraph[];
+    defaultHeader?: StyledParagraph[];
+    defaultFooter?: StyledParagraph[];
+    /**
+     * Blocs et tableaux de chaque part, quand elle en porte.
+     *
+     * Un en-tête sans tableau se dessine très bien comme une suite de
+     * paragraphes ; un en-tête AVEC tableau, non — ses cellules s'empilent au
+     * lieu de se ranger côte à côte, et sa hauteur double. Ces champs ne sont
+     * donc renseignés que dans ce cas, et le dessinateur retombe sur la liste de
+     * paragraphes quand ils manquent.
+     */
+    firstPageHeaderBlocks?: PartBlocks;
+    /** `w:titlePg` : la première page a ses PROPRES en-tête et pied — AUCUN s'ils ne sont pas déclarés. */
+    titlePg?: boolean;
+    firstPageFooter?: StyledParagraph[];
+    firstPageFooterBoxes?: PlacedTextBox[];
+    /** Parts des pages PAIRES — servies seulement si `w:evenAndOddHeaders`. */
+    evenHeader?: StyledParagraph[];
+    evenHeaderBlocks?: PartBlocks;
+    evenFooter?: StyledParagraph[];
+    evenFooterBoxes?: PlacedTextBox[];
+    defaultHeaderBlocks?: PartBlocks;
+    defaultFooterBlocks?: PartBlocks;
+    /**
+     * Zones de texte ancrées du PIED, posées à leurs coordonnées.
+     *
+     * Le paraphe des contrats en est une. Exclue du fil pour ne pas surgir à
+     * gauche, elle n'était dessinée nulle part et manquait à chaque page.
+     */
+    defaultFooterBoxes?: PlacedTextBox[];
+    /**
+     * Chemins des parts d'en-tête et de pied dans le zip.
+     *
+     * Sans eux, un paragraphe d'en-tête n'a pas d'adresse : son rang désignerait
+     * le corps, et le curseur écrirait dans un tout autre texte.
+     */
+    headerPath?: string;
+    footerPath?: string;
+}

package/dist/types/packages/docx-tags/src/add-comments.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env tsx
+export {};

package/dist/types/packages/docx-tags/src/comments.d.ts

@@ -0,0 +1,19 @@
+import { type DocxDocument } from '../../docx-model/src/index';
+export interface DocxComment {
+    id: string;
+    author: string;
+    initials: string;
+    date: string;
+    text: string;
+    /** indices of the paragraphs the comment range covers */
+    paras: number[];
+}
+/**
+ * Word comments live in `word/comments.xml`; the body carries the anchors
+ * (`w:commentRangeStart` / `w:commentRangeEnd` / `w:commentReference`).
+ *
+ * They are the only place in a matrix where you can write something the reader
+ * of the generated document will never see — which is exactly what the brief
+ * says is missing today.
+ */
+export declare function readComments(doc: DocxDocument): DocxComment[];

package/dist/types/packages/docx-tags/src/grammar.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Canonical LumiClone template grammar.
+ *
+ * Ported from `lumiclone/src/engine/pipeline/{canonical-tags,modifier-parser,tag-parser}.ts`.
+ * LumiClone is the engine that actually renders these matrices; the editor MUST
+ * read them the same way, or it shows the user something the generator will not do.
+ * Keep this file a faithful mirror — behaviour differences belong in a changelog,
+ * not in a silent divergence.
+ *
+ * ponytail: ported rather than imported — LumiClone is a server-side Fastify app
+ * (xmldom, better-sqlite3, exceljs). This is the browser-safe subset.
+ */
+/** Block directives, mapped to a structural role. */
+export declare const DIRECTIVES: {
+    readonly 'conditional-section': "open";
+    readonly 'repeating-section': "open";
+    readonly 'signature-section': "open";
+    readonly 'inline-section': "open";
+    readonly 'style-section': "open";
+    readonly 'else-section': "middle";
+    readonly 'end-section': "close";
+    readonly 'table-start': "open";
+    readonly 'table-end': "close";
+    readonly 'grid-start': "open";
+    readonly 'grid-end': "close";
+    readonly 'repeating-columns': "open";
+    readonly 'end-columns': "close";
+    readonly 'line-break': "standalone";
+    readonly 'page-section': "standalone";
+};
+export type Directive = keyof typeof DIRECTIVES;
+export type Role = (typeof DIRECTIVES)[Directive];
+/** Which close directive terminates which open directive. */
+export declare const CLOSED_BY: Partial<Record<Directive, Directive>>;
+/** Value-tag modifiers. Longest names first — parsing peels from the right. */
+export declare const MODIFIERS: readonly ["default-val", "discard-if-empty", "discard-row-if", "discard-if", "cell-extension", "char-style", "optional", "prefix", "size", "inline", "per-page", "eval", "css"];
+export type ModifierName = (typeof MODIFIERS)[number];
+export interface Modifier {
+    name: string;
+    args: string[];
+}
+/**
+ * Rich-text editors silently substitute ASCII with Unicode lookalikes.
+ * Word turns ' into ’ (JSONata then reads it as a *field name*, with no error,
+ * and the tag renders empty) and inserts NBSP before ? % : (the tokenizer
+ * rejects them).
+ *
+ * Applied to the whole raw content, string literals included — that is what
+ * LumiClone does, so a NBSP typed inside a literal does not survive generation.
+ */
+export declare function normalizeTagContent(raw: string): string;
+/**
+ * Normalise a JSONata expression: stray spaces around dots, and `!` negation
+ * (which JSONata has no operator for) rewritten to `$not(...)`.
+ */
+export declare function normalizeExpression(expr: string): string;
+/** Peel `:modifier(args)` suffixes from the right of a tag body. */
+export declare function parseModifiers(raw: string): {
+    expression: string;
+    modifiers: Modifier[];
+};
+export declare function parseValueTag(content: string): {
+    expression: string;
+    modifiers: Modifier[];
+};
+export declare function parseBlockTag(content: string): {
+    directive: string;
+    expression: string;
+    modifiers: Modifier[];
+};
+export declare const isDirective: (name: string) => name is Directive;

package/dist/types/packages/docx-tags/src/highlight.d.ts

@@ -0,0 +1,22 @@
+import type { Tag } from './scan';
+/**
+ * Surlignage des valeurs substituées — portage de
+ * `lumiclone/src/engine/highlight/highlight-config.ts`.
+ *
+ * Même palette et même règle de classement que le moteur : ce que l'éditeur
+ * colore en aperçu est exactement ce que la génération colorerait avec
+ * `highlight: { enabled: true }`.
+ */
+export type HighlightKind = 'text' | 'calcul' | 'conditional' | 'repeating' | 'signature';
+/** Hex à 6 caractères, sans `#`, comme dans LumiClone. */
+export declare const HIGHLIGHT_PALETTE: Record<HighlightKind, string>;
+export declare const HIGHLIGHT_LABEL: Record<HighlightKind, string>;
+export declare const cssColor: (kind: HighlightKind) => string;
+export declare function categorizeByExpression(expression: string): HighlightKind;
+/**
+ * Genre de surlignage de chaque tag de valeur.
+ *
+ * Le bloc englobant le plus proche l'emporte sur l'expression — c'est la pile
+ * `hlStack` du renderer LumiClone.
+ */
+export declare function highlightKinds(tags: Tag[]): Map<number, HighlightKind>;

package/dist/types/packages/docx-tags/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from './grammar';
+export * from './scan';
+export * from './comments';
+export * from './highlight';

package/dist/types/packages/docx-tags/src/scan.d.ts

@@ -0,0 +1,27 @@
+import { type Role, type Modifier } from './grammar';
+export type TagKind = 'value' | 'signature' | 'block';
+export interface Tag {
+    id: number;
+    para: number;
+    start: number;
+    end: number;
+    raw: string;
+    kind: TagKind;
+    /** block tags only */
+    directive?: string;
+    role?: Role;
+    expression: string;
+    modifiers: Modifier[];
+    /** nesting depth of enclosing blocks */
+    depth: number;
+    /** open ↔ close, and open → else */
+    match?: number;
+    elseId?: number;
+    /** signature target, e.g. `EMPLOYEE` */
+    target?: string;
+    paths: string[];
+    functions: string[];
+    error?: string;
+}
+/** Scan a document's paragraph texts into a flat, paired list of tags. */
+export declare function scanTags(paragraphs: string[]): Tag[];