myrole-docx-editor 0.1.0

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

@@ -0,0 +1,251 @@
+import type { StyledParagraph, PageSetup, ListInfo, TableInfo, BodyBlock } from '../../docx-model/src/index';
+import { type Footnotes, type ImageMap, type ImageRect, type LineTrace, type MarkRect, type PlacedTextBox, type RowTrace, type RuleTrace, type SectionParts, type TableRect } from './types';
+export interface RenderInput extends RenderOptions {
+    /** Où accrocher les `<canvas>`. Inutile si `newPage` est fourni. */
+    container?: HTMLElement;
+    paragraphs: StyledParagraph[];
+    page: PageSetup;
+    blocks: BodyBlock[];
+    tables: TableInfo[];
+    numbering?: (ListInfo | undefined)[];
+    /**
+     * Sections du document. Sans elles, un document multi-sections se rend
+     * entièrement au format de la première — marges, orientation et colonnes des
+     * suivantes sont perdues.
+     */
+    sections?: PageSetup[];
+    /** Les notes de bas de page, si le document en a. */
+    footnotes?: Footnotes;
+    /**
+     * Où chaque note atterrit, relevé par la PASSE DE MESURE.
+     *
+     * Une note se pose au bas de la page où tombe son renvoi, et cette place
+     * enlevée au corps déplace le renvoi lui-même : c'est un point fixe. On le
+     * résout en composant deux fois — la première dit les pages, la seconde
+     * réserve la place. Une seule itération : c'est ce que fait Word dans les
+     * cas simples, et les quatre documents à notes du corpus en sont.
+     */
+    notesOnPage?: Map<number, number[]>;
+}
+export interface RenderOptions {
+    /** Chaque changement de page ou de colonne, avec sa cause — voir `DrawCtx.onBreak`. */
+    onBreak?(b: {
+        page: number;
+        y: number;
+        cause: string;
+        bloc?: number;
+    }): void;
+    headerDistPt?: number;
+    footerDistPt?: number;
+    firstPageHeader?: StyledParagraph[];
+    defaultHeader?: StyledParagraph[];
+    defaultFooter?: StyledParagraph[];
+    /**
+     * En-têtes/pieds par section, indexés comme `sections`.
+     *
+     * Word laisse chaque section déclarer les siens, et une section muette hérite
+     * de la précédente. N'utiliser que ceux de la première section coûtait 30 pt
+     * en haut de chaque page dès la deuxième sur Colo 2 : sa section 1 pose son
+     * en-tête à 0 pt du bord, les suivantes à 36 pt.
+     */
+    sectionParts?: SectionParts[];
+    images?: ImageMap;
+    /**
+     * Appelé pour chaque morceau dessiné d'un run marqué.
+     *
+     * Un run coupé par un retour à la ligne produit plusieurs rectangles ; c'est
+     * à l'appelant de les réunir. Le renderer ne sait pas ce que le marqueur
+     * désigne et n'a pas à le savoir.
+     */
+    onMark?(rect: MarkRect): void;
+    /**
+     * Trace de layout — appelé pour chaque ligne dessinée.
+     *
+     * Permet de comparer les positions calculées par le renderer avec celles
+     * extraites du PDF Word (pdftotext -bbox), sans passer par le pixel diff.
+     */
+    onLine?(line: LineTrace): void;
+    /**
+     * Appelé pour chaque image dessinée, avec son rectangle.
+     *
+     * Une image n'occupe aucun caractère : le hit-test du texte ne la trouvera
+     * jamais. Sans ce rectangle elle est invisible à la souris.
+     */
+    onImage?(rect: ImageRect): void;
+    /**
+     * Appelé pour chaque page qu'un tableau occupe, avec son rectangle.
+     *
+     * Un tableau ne s'attrape pas par son texte — le curseur y tombe toujours
+     * dans une cellule. C'est ce rectangle qui permet de le prendre comme un tout.
+     */
+    onTable?(rect: TableRect): void;
+    /**
+     * Publier aussi les lignes vides dans la trace.
+     *
+     * L'éditeur en a besoin pour poser un curseur sur une ligne vide ; le banc de
+     * mesure ne doit PAS les voir, il apparie ses lignes par le texte.
+     */
+    traceEmpty?: boolean;
+    /** Chaque TRAIT dessiné — voir `RuleTrace`. */
+    onRule?(rule: RuleTrace): void;
+    onRow?(row: RowTrace): void;
+    /** Passe de MESURE seulement : sur quelle page tombe le renvoi de la note n. */
+    onFootnoteAt?(n: number, page: number): void;
+    /** w:defaultTabStop du document, en points */
+    defaultTabPt?: number;
+    /** `w:doNotExpandShiftReturn` — voir `DrawCtx` */
+    noExpandShiftReturn?: boolean;
+    /** compatibilityMode < 15 — voir `DrawCtx` */
+    legacyWrap?: boolean;
+    /** `w:ulTrailSpace` — voir `DrawCtx` */
+    ulTrailSpace?: boolean;
+    /**
+     * Zones de texte ancrées, indexées par le paragraphe qui les porte.
+     *
+     * Word les pose à leurs coordonnées, hors du fil. Les ignorer perdait leur
+     * contenu — et sur un contrat, l'absence d'un bloc décalait la frontière de
+     * page qui suit, donc tout le reste du document.
+     */
+    textBoxes?: PlacedTextBox[];
+    /**
+     * Hauteurs de ligne par police, lues dans les fichiers réellement servis.
+     *
+     * Une table écrite à la main laisse toujours une police dehors, et celle-là
+     * compose 6 % trop court sans que rien ne le signale.
+     */
+    lineRatios?: Record<string, number>;
+    /**
+     * Première page à REPEINDRE, 1-based. Les précédentes gardent leurs pixels.
+     *
+     * Une frappe au milieu d'un document ne change rien à ce qui la précède : la
+     * mise en page y est déterministe et ne dépend que du contenu d'avant. On la
+     * calcule donc quand même — il faut bien savoir où l'on en est — mais on ne
+     * la peint pas.
+     *
+     * Mesuré sur une trace de session réelle : `fillText` pesait 915 ms et le
+     * téléversement des textures 680 ms de plus, pour neuf pages redessinées à
+     * chaque lettre.
+     *
+     * L'appelant est responsable de n'en profiter que quand c'est vrai : la page
+     * doit être celle où commence le paragraphe modifié, et un changement du
+     * NOMBRE de pages oblige à tout repeindre (les pieds portent « page X sur Y »).
+     */
+    paintFrom?: number;
+    /**
+     * Reprise incrémentale : ne recomposer qu'à partir de la page modifiée.
+     *
+     * L'appelant crée l'objet une fois et le REND tel quel à chaque composition —
+     * le renderer y range ses points de reprise et y écrit ce qu'il a refait.
+     */
+    resume?: ResumeState;
+    /**
+     * Facteur correctif Canvas→hmtx par police.
+     *
+     * Canvas mesure les glyphes ~1% plus large que les avances du TTF. Ce
+     * facteur corrige la mesure des tokens pour la césure.
+     */
+    widthCorrections?: Record<string, number>;
+    /**
+     * Nombre de pages maximal. Quand le renderer veut créer une page de plus,
+     * il la saute et continue sur la page courante (le contenu peut déborder
+     * dans la marge basse).
+     *
+     * C'est un GARDE-FOU, pas un alignement : le régler sur le compte de pages
+     * de Word rendait toute erreur de pagination invisible, le surplus étant
+     * peint par-dessus la dernière page au lieu d'en ouvrir une. Le banc y met
+     * le double plus cinq.
+     */
+    maxPages?: number;
+    /**
+     * Fabrique la surface d'une page, à la place d'un `<canvas>` du DOM.
+     *
+     * Le moteur n'a besoin du navigateur que pour DESSINER ; toutes ses décisions
+     * de mise en page passent par `measureText`. En laissant l'appelant fournir
+     * la surface, le même code compose un document dans Node — sans Vite, sans
+     * Chrome, sans capture d'écran — contre une surface qui mesure les glyphes
+     * dans les TTF servis et jette la peinture.
+     *
+     * Mesuré : 200 documents du corpus, 63 ms chacun contre 730 ms par le
+     * navigateur, pour une mise en page identique à 0,225 pt près en médiane —
+     * cent pour cent des lignes dans la tolérance de 2 pt du banc.
+     */
+    newPage?(wPx: number, hPx: number, dpr: number): CanvasRenderingContext2D;
+    /** Densité de la surface. `window.devicePixelRatio` par défaut. */
+    devicePixelRatio?: number;
+}
+/** Tout ce qu'il faut pour reprendre — ou reconnaître — une mise en page. */
+interface LayoutState {
+    y: number;
+    page: number;
+    block: number;
+    /** Rang de tableau où l'on en est — 0 hors tableau. */
+    row: number;
+    /** Premier paragraphe qui reste à composer. */
+    para: number;
+    bodyStart: number;
+    sectionIdx: number;
+    /**
+     * Section sous laquelle la PAGE a été ouverte — pas forcément la section
+     * courante : une rupture continue peut changer de section au milieu d'une
+     * feuille, et c'est l'en-tête et le pied de l'OUVERTURE qui y sont posés.
+     */
+    pageSect: number;
+    /**
+     * Première page de la section — `applySection` la recalcule depuis
+     * `pageCount`, ce qui est FAUX à la reprise : on reprend au milieu d'une
+     * section et sa vraie première page est plus haut. `balanceFrom` s'en sert
+     * (`pageCount > sectionStartPage`), donc l'équilibrage des colonnes changeait
+     * et le document rendait deux lignes de moins qu'en composition complète.
+     */
+    sectionStartPage: number;
+    balancedBottom: number | undefined;
+    wrapFloor: number | undefined;
+    prevSpaceAfter: number | undefined;
+    prevStyleId: string | undefined;
+    prevContextual: boolean | undefined;
+}
+export interface ResumeState {
+    /** Paragraphe modifié. La composition reprend juste avant lui. */
+    at?: number;
+    /**
+     * Points de REPRISE : paragraphe → état au SOMMET de la page qu'il ouvre.
+     *
+     * Indexés par PARAGRAPHE et non par bloc : un contrat de 42 pages ne compte
+     * que dix blocs, ses tableaux enjambant les pages par dizaines. Un rang de
+     * tableau est un point de reprise comme un autre.
+     *
+     * Seuls les sommets de page en sont : reprendre à mi-page voudrait dire
+     * effacer ce qui vient dessous, et un rectangle ne sait pas distinguer la
+     * queue d'un jambage de l'encre qu'on remplace — la rangée du point de reprise
+     * n'était jamais tout à fait la bonne. Une page se reprend donc entière,
+     * en-tête compris.
+     */
+    snaps?: Map<number, LayoutState>;
+    /**
+     * Points de CONVERGENCE : page → état juste avant de l'ouvrir. Y retomber
+     * signifie que cette page et toutes les suivantes sont déjà à l'écran.
+     */
+    bounds?: Map<number, LayoutState>;
+    /** Nombre de blocs et de pages de la composition précédente. */
+    blocks?: number;
+    pages?: number;
+    /**
+     * Première et dernière page réellement recomposées — écrites par le renderer.
+     *
+     * Les pages de cet intervalle sont refaites ENTIÈREMENT, en-tête et pied
+     * compris ; celles d'avant et d'après gardent leurs pixels et leur trace.
+     */
+    from?: number;
+    to?: number;
+}
+/** Compose le document dans le conteneur et renvoie le nombre de pages. */
+/**
+ * Compose le document dans le conteneur et renvoie le nombre de pages.
+ *
+ * Un document À NOTES est composé DEUX FOIS : la première pour savoir sur
+ * quelle page tombe chaque renvoi, la seconde pour réserver la place des notes
+ * au bas de ces pages-là. Un document sans notes — 1332 des 1336 du corpus —
+ * ne passe pas par là et ne paie rien.
+ */
+export declare function render(input: RenderInput): number;
+export {};

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

@@ -0,0 +1,15 @@
+import type { ListInfo, StyledParagraph, TableInfo } from '../../docx-model/src/index';
+import { type DrawCtx } from './types';
+export declare function drawTable(dc: DrawCtx, table: TableInfo, paras: StyledParagraph[], paraStart: number, 
+/** Reprise : premier rang à composer, et le paragraphe où il commence. */
+fromRow?: number, fromPara?: number, 
+/**
+ * Marqueurs de liste du document, indexés comme `paras`.
+ *
+ * Une cellule contient des paragraphes comme les autres, et rien n'empêche
+ * qu'ils soient numérotés. Ne pas les transmettre coûtait la puce ET le
+ * décalage du texte qu'elle entraîne : sur « Vanished », dont tout le corps
+ * tient dans une cellule, cinq « a) » manquaient et chaque paragraphe
+ * numéroté partait un mot en avance sur celui de Word jusqu'à sa fin.
+ */
+numbering?: Array<ListInfo | undefined>): void;

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

@@ -0,0 +1,396 @@
+import { type RunStyle, type StyledParagraph, type ListInfo } from '../../docx-model/src/index';
+import { type ImageMap, type PageNums } from './types';
+/**
+ * Composition d'une ligne : mesure des glyphes, découpage en unités
+ * insécables, et les quelques règles de Word qui s'y appliquent.
+ */
+/**
+ * Échelle horizontale d'un run (`w:rPr/w:w`), en facteur.
+ *
+ * Word resserre ou étire chaque glyphe SANS toucher à sa hauteur. Le canvas ne
+ * l'exprime pas directement : on corrige les largeurs mesurées, ce qui suffit
+ * à la césure et au placement — le DESSIN reste à l'échelle 1, faute de quoi
+ * il faudrait une transformation par jeton.
+ */
+export declare const scaleOf: (style: Partial<RunStyle>) => number;
+export declare function canvasFont(style: Partial<RunStyle>, def: {
+    font: string;
+    sizePt: number;
+}): string;
+/**
+ * Pose police ET interlettrage d'un coup.
+ *
+ * `ctx.letterSpacing` est rémanent : le laisser d'un jeton à l'autre teintait
+ * tout le reste de la ligne. On le remet donc à zéro par défaut.
+ */
+export declare function setFont(ctx: CanvasRenderingContext2D, font: string, ls?: string): void;
+export declare function alignX(align: string | undefined, left: number, avail: number, w: number): number;
+/**
+ * Les seize valeurs de `w:highlight`, plus `white`.
+ *
+ * `white` et `none` ne sont pas des absences : ce sont des valeurs légales que
+ * Word peint (ou non) sans rien changer à l'œil. Une valeur inconnue ne peint
+ * rien non plus — inventer une couleur, c'est afficher une information que le
+ * document ne porte pas. `dev-fixture.docx` porte `white` sur 194 de ses 202
+ * runs : avec un défaut jaune, la page entière était surlignée.
+ */
+export declare const HL_COLORS: Record<string, string>;
+export interface Tok {
+    /**
+     * Largeur sans l'espace finale.
+     *
+     * Word ne compte pas l'espace de fin de ligne quand il décide du retour :
+     * « mot » suivi d'une espace tient là où « mot␣ » déborderait.
+     */
+    inkWidth?: number;
+    /**
+     * Ce jeton prolonge le précédent au sein d'un même mot : aucune coupure
+     * n'est permise entre les deux.
+     *
+     * Word découpe ses runs où il veut — au gré des révisions et du correcteur
+     * orthographique — et une frontière de run tombe au milieu d'un mot une fois
+     * sur quatre dans ces matrices : « Sal|a|rié.e », « l|’|exploitation »,
+     * « stipul|e ». Chacune était pour nous une occasion de couper la ligne là
+     * où Word ne le ferait jamais.
+     */
+    noBreakBefore?: boolean;
+    text: string;
+    width: number;
+    font: string;
+    color: string;
+    /**
+     * `w:rPr/w:w` — l'échelle HORIZONTALE des glyphes, en fraction.
+     *
+     * Elle était appliquée à la MESURE (`scaleOf` dans `corr`) et pas au DESSIN :
+     * l'avance valait 90 % de la largeur naturelle, les glyphes 100 %, et les
+     * mots se recouvraient. 268 documents du corpus la posent, 97 433 fois, et
+     * `MATRICES QUAD ETE 36` en avait 209 lignes sur 304 illisibles — que le banc
+     * de référence comptait PLACÉES, puisqu'il ne lit que le texte et l'abscisse
+     * de départ.
+     */
+    scaleX?: number;
+    sizePx: number;
+    underline: boolean;
+    strike: boolean;
+    highlight?: string;
+    /** `w:lvlPicBulletId` — puce IMAGE : on peint le bitmap au lieu du glyphe */
+    markerBitmap?: CanvasImageSource;
+    markerImageSize?: {
+        w: number;
+        h: number;
+    };
+    /** `w:bdr` — cadre autour du run ; les jetons voisins qui le partagent n'en font qu'un */
+    border?: RunStyle['border'];
+    lineBreak?: boolean;
+    /** `w:br w:type="page"` ou `"column"` — force une nouvelle page/colonne */
+    pageBreak?: boolean;
+    /** `w:br w:type="column"` — passe à la colonne suivante, pas à la page */
+    columnBreak?: boolean;
+    /** puce ou numéro de liste — un mot à part, jamais collé au texte qui suit */
+    isListMarker?: boolean;
+    /**
+     * Texte réellement DESSINÉ, s'il diffère de la source.
+     *
+     * En petites capitales, Word compose des CAPITALES à deux corps : c'est cela
+     * qu'un lecteur voit et que `pdftotext` extrait. Publier la source dans la
+     * trace faisait compter chaque titre comme absent — dix lignes sur soixante
+     * rien qu'en page 6 de Colo 2 — alors qu'il était dessiné au bon endroit.
+     * On garde la source pour MESURER (elle seule dit quelles lettres sont
+     * petites) et on publie la forme dessinée.
+     */
+    drawnText?: string;
+    /** rang de l'image dans son paragraphe — le même que celui du contexte */
+    imgIndex?: number;
+    /**
+     * Image EN LIGNE : occupe sa place dans le fil, qu'on sache la peindre ou non.
+     *
+     * `bitmap` est FACULTATIF, et c'est tout l'intérêt. Ses dimensions viennent
+     * de `wp:extent`, donc du document — pas du fichier image. Ne poser le jeton
+     * que lorsqu'on avait su décoder les pixels faisait qu'une image illisible
+     * (EMF et WMF, que Word sème partout, et toute image sur un chemin sans
+     * décodeur) ne réservait AUCUNE place : le logo d'un en-tête disparaissait et
+     * le corps remontait de sa hauteur — sur toutes les pages du document.
+     */
+    image?: {
+        bitmap?: ImageBitmap;
+        widthPx: number;
+        heightPx: number;
+        crop?: {
+            l: number;
+            t: number;
+            r: number;
+            b: number;
+        };
+    };
+    /** boîte réservée pour un affichage tiers : occupe la place, ne peint rien */
+    box?: boolean;
+    /** tabulation : largeur calculée à la position de dessin (prochain tab stop) */
+    isTab?: boolean;
+    /** `w:ptab` — la position du taquet est ABSOLUE, pas cherchée dans la liste */
+    ptabAlign?: 'center' | 'right';
+    /** marqueur du run d'origine, recopié tel quel */
+    mark?: string;
+    /** petites capitales : police réduite pour les lettres qui étaient minuscules */
+    fontSmall?: string;
+    /** exposant/indice : décalage vertical en px (négatif = vers le haut) */
+    rise?: number;
+    /**
+     * Rang du premier caractère de ce jeton dans le TEXTE du paragraphe.
+     *
+     * C'est l'adresse du modèle (`runSpans`), pas un rang de jeton : elle survit
+     * au découpage en mots, à la césure et aux frontières de run. C'est elle qui
+     * permet de rendre un clic sous forme de position éditable — sans elle, le
+     * renderer sait où il a dessiné, mais pas QUOI.
+     *
+     * `undefined` quand le jeton ne correspond à aucun caractère du modèle : le
+     * marqueur d'une liste, un champ dont on a recalculé la valeur, une boîte
+     * d'extension. Un curseur ne s'y pose pas.
+     */
+    off?: number;
+    /** interlettrage CSS (`w:rPr/w:spacing`), ex. `0.13px` */
+    letterSpacing?: string;
+}
+/**
+ * Word compose exposants et indices à 65 % du corps, l'exposant remonté d'un
+ * tiers du corps et l'indice descendu d'un sixième. Les rendre en taille pleine
+ * élargit la ligne — « L1242-3ᵉ » débordait et cassait la césure une syllabe
+ * trop tôt, décalant tout le paragraphe.
+ */
+export declare const VERT_ALIGN_RATIO = 0.65;
+export declare const SUPER_RISE: number;
+export declare const SUB_RISE: number;
+/**
+ * Resserrement des espaces qu'on refuse quoi qu'il arrive.
+ *
+ * Le choix du moindre mal (voir `keepsWord`) suffit presque toujours ; ce
+ * plafond n'est là que pour les lignes à deux ou trois espaces, où le rapport
+ * des distorsions n'a plus de sens et où Word renvoie le mot sans discuter.
+ */
+export declare const MAX_SHRINK = 0.25;
+/**
+ * Débordement TOLÉRÉ sur une ligne non justifiée, en points.
+ *
+ * Le texte aligné à gauche coupe au dernier mot qui tient, sans marchander —
+ * mais « tient » se juge avec NOS largeurs, qui s'écartent de celles de Word de
+ * quelques dixièmes de pour cent (`widthtail.ts` : q05 0,9997, q95 1,0005).
+ * Un mot qui déborde de deux points sur une colonne de 550 déborde de 0,4 %,
+ * c'est-à-dire de rien. L'hypothèse était donc qu'une tolérance ABSOLUE
+ * absorberait l'écart de mesure sans marchander comme le fait le justifié.
+ *
+ * MESURÉE ET PERDANTE, sur les 400 documents :
+ *
+ * DEUX FORMES essayées, les deux perdantes sur les 400 documents.
+ *
+ * En POINTS :  0 -> 39,15 · 1 -> 38,97 · 2 -> 38,96 · 3 -> 38,55 (pondéré ligne)
+ * En EM    :   0 -> 39,15 · 0,10 -> 38,91 · 0,20 -> 38,75 · 0,30 -> 38,53
+ *
+ * Décroissance monotone dans les deux cas. Et on sait maintenant POURQUOI, ce
+ * qui est plus utile que le chiffre.
+ *
+ * Sur la ligne qui a lancé l'enquête — « CONTRAT CASCADEURS », douze blocs
+ * cassés un mot trop tôt :
+ *
+ *   somme des avances de Word   554,31 pt
+ *   la même chaîne chez nous    554,41 pt   (0,02 % d'écart : nos métriques
+ *                                            sont exactes, voir `advdiff.ts`)
+ *   colonne de la cellule       551,70 pt
+ *   ENCRE de la ligne chez Word 551,70 pt
+ *
+ * Word dépasse sa colonne de 2,61 pt en AVANCE et la remplit exactement en
+ * ENCRE. **Il coupe donc sur l'encre, nous sur l'avance** — la différence est
+ * l'approche du premier et du dernier glyphe, qui pend dans la marge.
+ *
+ * Une tolérance, plate ou proportionnelle, accorde cette permission à TOUTES
+ * les lignes ; Word ne l'accorde qu'à celles dont le dernier glyphe a vraiment
+ * une approche à donner. D'où la décroissance monotone : on garde plus de mots
+ * à tort qu'à raison.
+ *
+ * Le correctif juste demanderait la BOÎTE D'ENCRE du dernier glyphe —
+ * `glyf`/`CFF` dans `advances.ts`, que le mesureur ne lit pas. Gardé à zéro
+ * avec sa mesure, et la piste nommée.
+ */
+export declare const TOL_MESURE_EM = 0;
+/**
+ * Resserrement toléré sur la DERNIÈRE ligne d'un paragraphe.
+ *
+ * Elle n'est pas justifiée : rien ne viendra rattraper un dépassement, il
+ * sortira tel quel dans la marge. Le budget y est donc bien plus étroit
+ * qu'ailleurs — mais pas nul, car nos largeurs naturelles s'écartent de celles
+ * de Word de quelques dixièmes de point sur une ligne pleine.
+ *
+ * La valeur venait de DEUX observations : Colo 2, « Additionnels »). » demande
+ * 24 % et Word le renvoie ; l'Avenant, « d'essai. » demande 8 % et Word le
+ * garde. Deux points ne font pas une courbe, et le 0,15 qu'ils suggéraient
+ * était loin de l'optimum.
+ *
+ * BALAYÉ sur les 400 documents du banc :
+ *
+ *   valeur   par document   pondéré ligne
+ *   0,05        41,82          34,94
+ *   0,15        43,47          36,84     ← les deux observations
+ *   0,20        44,61          37,89
+ *   0,23        45,30          38,96
+ *   0,25        45,26          39,08     ← pic
+ *   0,26        44,69          38,56
+ *   0,28        43,47          37,41
+ *   0,32        42,38          36,00
+ *   0,40        40,48          34,07
+ *
+ * Word tolère donc BEAUCOUP plus de resserrement sur une dernière ligne qu'on
+ * ne le croyait — un quart, pas un septième. Et les deux constantes
+ * interagissent : `STRETCH_RATIO` a été rebalayé à cette valeur et reste à
+ * 0,50 (0,45 donne 38,35, 0,55 donne 38,34). Le couple est un optimum conjoint.
+ *
+ * 60 documents en hausse, 33 en baisse, et AUCUN des 33 ne change de
+ * pagination — ce sont des déplacements de lignes, pas des ruptures. Les
+ * documents au bon nombre de pages passent de 306 à 308.
+ */
+export declare const FINAL_LINE_SHRINK = 0.25;
+/**
+ * Découpage GLOBAL des paragraphes justifiés — voir `optimalBreaks`.
+ *
+ * MESURÉ, ET PERDANT. `optimalBreaks` est vérifié correct (test synthétique) et
+ * ses coupures sont plausibles, mais il reproduit Word NETTEMENT moins bien que
+ * le glouton `keepsWord`, et pour toute pénalité :
+ *
+ *              glouton   pén. 0,1   pén. 1,0   pén. 4,5
+ *   Colo 2      95,95      37,6       38,2       45,1
+ *   FIEF        96,42      66,6       72,5       80,3
+ *   Stagiaire   95,54      71,4       71,4       79,7
+ *
+ * L'écart est structurel : le modèle global échange une bonne ligne contre une
+ * meilleure suivante, Word non — il coupe au dernier mot qui tient et ne
+ * marchande QUE le resserrement de la ligne courante. Les brevets décrivent un
+ * optimiseur global ; ce Word-là ne l'applique pas au découpage des lignes.
+ *
+ * REVÉRIFIÉ sur les 400 documents du banc, avec les constantes recalibrées —
+ * les trois chiffres ci-dessus venaient de TROIS documents :
+ *
+ *   glouton              45,27 par document, 39,15 pondéré ligne
+ *   global, pénalité 1,0  37,05                30,50
+ *   global, pénalité 4,5  39,44                32,50
+ *   global, pénalité 12   38,16                31,51
+ *
+ * Six points et demi d'écart à l'optimum du global. La réfutation tient, et
+ * elle tient maintenant sur le corpus.
+ *
+ * Gardé désactivé plutôt que supprimé : c'est la TROISIÈME tentative de modèle
+ * global, et sans cette mesure il y en aura une quatrième.
+ */
+export declare const OPTIMAL_WRAP = false;
+export declare const SHRINK_PENALTY = 4.5;
+/**
+ * Étirement en deçà duquel Word ne resserre jamais.
+ *
+ * Une ligne justifiée trop courte s'étire, une ligne trop longue se resserre.
+ * Word ne marchande pas : il coupe au dernier mot qui tient et étire. Il ne
+ * resserre que lorsque l'étirement deviendrait grotesque.
+ *
+ * Deux décisions de Word sur Colo 2, au resserrement quasi identique et
+ * pourtant opposées, situent la frontière sur l'ÉTIREMENT et non sur le
+ * resserrement :
+ *
+ *   « L7124- »  resserrer 13,7 %  ou étirer 159,6 %  → Word garde
+ *   « ceux »    resserrer 15,1 %  ou étirer  22,9 %  → Word renvoie
+ */
+export declare const MIN_STRETCH = 0;
+/**
+ * Part de l'étirement en deçà de laquelle le resserrement l'emporte.
+ *
+ * `bench trace --rule` balayait la famille « plafond × ratio » sur les 116
+ * décisions de Colo 2 : le maximum y était à 0,75 (87,1 % de bonne
+ * classification) contre 1,00 (86,2 %). Word penche donc du côté du renvoi.
+ *
+ * REBALAYÉ sur les 400 documents du banc, ce qui est un tout autre échantillon
+ * que 116 décisions d'un seul contrat :
+ *
+ *   ratio    par document   pondéré ligne
+ *   0,40        41,41          34,88
+ *   0,47        42,79          36,41     ← la valeur précédente
+ *   0,49        43,10          36,62
+ *   0,50        43,47          36,84     ← pic, les deux axes d'accord
+ *   0,51        43,37          36,76
+ *   0,52        43,20          36,52
+ *   0,55        42,95          36,24
+ *   0,65        42,04          35,34
+ *
+ * Courbe lisse, pic unique, voisins immédiats en dessous : c'est un optimum et
+ * non un accident de grille. 83 documents en hausse, 6 en baisse.
+ *
+ * Son voisin `MAX_SHRINK` a été balayé du même coup et reste à 0,25 : 0,20
+ * donne 33,33 et 0,30 donne 34,69 en pondéré ligne, contre 36,84. Le plafond
+ * est déjà juste, et il est RAIDE — un vingtième coûte un à trois points.
+ */
+export declare const STRETCH_RATIO = 0.5;
+/**
+ * Word garde-t-il ce mot sur la ligne, au prix d'un resserrement ?
+ *
+ * Oui si le resserrement demandé est PLUS FAIBLE que l'étirement qu'imposerait
+ * son renvoi — mais seulement lorsque cet étirement dépasse `MIN_STRETCH` : en
+ * deçà, Word se contente d'étirer, même si resserrer déformerait moins.
+ *
+ * @param over    dépassement si l'on garde le mot
+ * @param under   creux si on le renvoie
+ * @param gapsIn  largeur totale des espaces, le mot gardé
+ * @param gapsOut largeur totale des espaces, le mot renvoyé
+ */
+/**
+ * `ratio` est paramétrable pour un balayage séparé — celui des CELLULES a été
+ * fait le 28 août et donne le MÊME optimum que le fil : 0,40 → 48,04 ·
+ * **0,50 → 48,11** · 0,60 → 48,03 · 0,70 → 47,94 par document. La colonne
+ * étroite d'un tableau ne demande donc pas d'autre réglage que le fil ; c'est
+ * le NOMBRE de décisions qui l'expose, pas leur seuil.
+ */
+export declare function keepsWord(over: number, under: number, gapsIn: number, gapsOut: number, ratio?: number): boolean;
+/** Word compose les petites capitales à ~80 % du corps. */
+export declare const SMALL_CAPS_RATIO = 0.8;
+/**
+ * Coupe un mot après ses traits d'union : ce sont des points de césure.
+ *
+ * Word passe à la ligne après le tiret de « rendez-vous », pas nous — un mot
+ * composé de trop repoussait tout un paragraphe d'une ligne, et ces contrats en
+ * sont pleins (« Primo-Diffuseur », « post-synchronisation »). Sur les 1047
+ * lignes du rendu Word de Colo 2, treize finissent par un tiret.
+ *
+ * On exige au moins deux caractères avant et un après, pour ne pas isoler le
+ * tiret d'un « -113 » ou d'une puce.
+ *
+ * ponytail: la barre oblique est aussi une coupure possible chez Word (quatre
+ * lignes sur ce document), mais en DERNIER recours — il préfère renvoyer tout
+ * « interdiction/restriction/incapacité » à la ligne suivante. Notre césure
+ * gloutonne traite toutes les coupures à égalité et couperait trop tôt : à
+ * reprendre quand la césure saura hiérarchiser ses opportunités.
+ */
+export declare function hyphenPieces(word: string): string[];
+/** Découpe un texte en segments « était minuscule » / « était déjà capitale ». */
+export declare function scSegments(text: string): Array<{
+    text: string;
+    small: boolean;
+}>;
+/**
+ * Découpage GLOBAL d'un paragraphe justifié — le modèle des brevets de Word
+ * (US 7444586, US 7783969) : au lieu de décider mot à mot, on choisit
+ * l'ensemble des coupures qui minimise la somme des carrés de l'ajustement.
+ *
+ * Pourquoi y revenir : sur 9 381 décisions réelles de Word, AUCUN trait local
+ * ne sépare les cas où il garde un mot de ceux où il le renvoie — resserrement,
+ * étirement, intervalles, largeur du mot, corps, interligne sont tous au niveau
+ * du témoin trivial. La décision dépend donc de ce qui vient APRÈS dans le
+ * paragraphe, ce qui est la définition d'un optimum global.
+ *
+ * Renvoie l'ensemble des index de jetons qui OUVRENT une ligne, ou `undefined`
+ * quand le paragraphe ne s'y prête pas — tabulation, saut, image, puce : leur
+ * largeur dépend de la position et le calcul n'a plus de sens.
+ */
+export declare function optimalBreaks(toks: Tok[], availPremiere: number, availSuite: number, opts: {
+    maxShrink: number;
+    shrinkPenalty: number;
+    finalShrink: number;
+}): Set<number> | undefined;
+export declare function tokenize(ctx: CanvasRenderingContext2D, para: StyledParagraph, def: {
+    font: string;
+    sizePt: number;
+}, listInfo?: ListInfo, images?: ImageMap, nums?: PageNums, 
+/** Facteur correctif Canvas→hmtx par police. `ctx.measureText` × ce ratio =
+ *  largeur que Word utiliserait. Voir `canvasCorrection` dans @myrole/fonts. */
+widthCorrections?: Record<string, number>): Tok[];