archicratie-edition/docs/MANUEL_REFERENCE.md

# Manuel de référence — Archicratie Web Edition (Site + Gitea + Runner)

Ce manuel explique comment utiliser et maintenir l’outil d’édition :
- Site Astro “Archicratie – Web Edition”
- Proposer (tickets Gitea pré-remplis)
- Apply-ticket (application semi-automatique dans le contenu)
- Contrat d’ancres (citabilité) + tests
- CI Gitea Actions + ds220-runner (DS220+)

> Objectif : une boucle éditoriale reproductible, opposable, sûre, et testée.

---

## 0) Glossaire minimal (anti-jargon)
- **PR** (Pull Request) : demande de fusion d’une branche vers `master`.
- **PAT** (Personal Access Token) : jeton d’accès Gitea utilisé comme “mot de passe” pour API/Git.
- **Anchor / Ancre** : identifiant stable d’un paragraphe (ex: `p-8-0e65838d`) utilisable dans une URL `#...`.
- **Churn** : variation des ancres d’une page entre deux builds (mesure de stabilité).
- **dist/** : sortie buildée (artefact), jamais la “source de vérité”.
- **CI** : automatisation (build + tests) à chaque push/PR.

---

## 1) Pré-requis (poste local)
### Outils
- Node.js + npm
- Git
- (Optionnel) Python3 pour scripts de debug ponctuels

### Accès
- Compte Gitea avec droits sur le repo
- Un **PAT** Gitea
- Accès au site local (dev) et/ou build (dist)

---

## 2) Vue d’ensemble : la boucle éditoriale (rituel)
### Boucle standard (la “cadence courte”)
1) Sur le site, cliquer **Proposer** sur un paragraphe.
2) Choisir Type (Correction / Fact-check), puis Category.
3) Gitea ouvre un ticket pré-rempli (Chemin/URL/Ancre + texte actuel).
4) Rédiger la **Proposition (remplacer par)** + Justification.
5) En local :
   - `node scripts/apply-ticket.mjs <num>` (d’abord `--dry-run`)
   - `npm run test:anchors`
   - `npm run build`
6) Commit + push + PR si nécessaire.

---

## 3) Le site “Proposer / Citer / ¶” (para-tools)
### Où ça vit ?
- `src/layouts/EditionLayout.astro` injecte un script qui :
  - ajoute “¶” (lien d’ancre), “Citer”, “Proposer”
  - construit l’URL de création d’issue Gitea
  - embarque si possible le **paragraphe exact** (sinon un extrait)

- `src/components/ProposeModal.astro` gère la modal 2 étapes :
  - Type (correction/fact-check)
  - Category (cat/style, cat/lexique, etc.)
  - ouvre ensuite l’issue en **nouvel onglet** sans quitter le site

### Invariants (non négociables)
- **Ancre + URL + Chemin** doivent toujours être présents.
- Le mode “texte exact” est *best effort* :
  - si trop long → fallback extrait + note
  - priorité absolue : rester robuste et cliquable.

### Limites / règles de taille
- **FULL_TEXT_SOFT_LIMIT** : taille max pour tenter d’embarquer “copie exacte”
- **URL_HARD_LIMIT** : si l’URL devient trop longue → repasse en extrait

> But : éviter des issues amputées + éviter des URLs trop longues / fragiles.

---

## 4) Format des tickets (machine-readable)
Le parsing des tickets est fait par `scripts/apply-ticket.mjs` + workflow auto-label.
Donc le contenu doit rester “parsable”.

Sections attendues (au minimum) :
- `Chemin: /.../`
- `Ancre: #p-...`
- `Texte actuel (...)` (idéalement “copie exacte”, sinon “extrait”)
- `Proposition (remplacer par): ...`
- `Justification: ...` (peut être vide, mais le champ doit exister si possible)

> Voir aussi : docs/CONTRAT_TICKETS.md

---

## 5) Appliquer un ticket en local : `apply-ticket`
### Commandes
- Dry run (recommandé) :
  - `node scripts/apply-ticket.mjs <N> --dry-run`

- Application réelle :
  - `node scripts/apply-ticket.mjs <N>`

### Comportements de sûreté (guardrails)
- `--dry-run` :
  - **aucun fichier écrit**
  - **aucun backup créé**
  - affiche BEFORE/AFTER (extrait)

- Mode écriture :
  - crée un backup `.bak.issue-<N>` uniquement si écriture
  - match “best effort” mais refuse si score insuffisant

### Après application
- `git diff -- <fichier>`
- `git add <fichier>`
- `git commit -m "edit: apply ticket #N (...)"`

---

## 6) Contrat de citabilité : ancres + churn test
### Pourquoi ?
Les ancres sont le “socle de citabilité”. On veut prévenir les liens morts.

### Scripts
- `npm run test:anchors`
  - compare les ancres de `dist/` avec une baseline
  - calcule le churn et signale les pages modifiées

- `npm run test:anchors:update`
  - met à jour la baseline (à faire seulement quand c’est volontaire)

> Important : `dist/` est un artefact ; la baseline sert à mesurer, pas à “éditer dist”.

---

## 7) Garde-fou JS inline : `check-inline-js`
Pourquoi : éviter qu’un JS inline cassé supprime les boutons et fasse disparaître “Proposer/Citer”.

- `node scripts/check-inline-js.mjs`
- intégré dans `npm test`

---

## 8) CI (Gitea Actions)
### Objectif
Sur chaque push/PR : vérifier automatiquement que :
- build OK
- ancres OK
- JS inline OK

### Workflow
- `.gitea/workflows/ci.yml`

### Commande “contrat”
- `npm test`
  - exécute : build + anchors + inline-js

---

## 9) ds220-runner (DS220+ / Gitea act-runner)
### Comportement normal
Le runner lance des jobs dans des conteneurs éphémères qui démarrent/stop.
DSM peut notifier “conteneur arrêté de manière inattendue” : c’est souvent un faux positif “bruyant”.

### À surveiller vraiment
- Jobs en échec côté Gitea Actions
- logs mentionnant :
  - auth API (401)
  - labels manquants
  - npm ci/build en échec

---

## 10) Dépannage (symptômes → causes fréquentes)
### “Proposer” ouvre deux onglets / remplace l’onglet courant
Cause : double handler click / manque de `stopPropagation` / mauvais fallback.
Fix : le flux doit ouvrir **nouvel onglet uniquement**, et sinon prompt.

### “Proposer/Citer/¶” disparaissent
Cause : JS inline cassé → exception ou erreur syntaxe.
Fix : `node scripts/check-inline-js.mjs` + vérifier `dist/.../index.html` console.

### apply-ticket : “Proposition introuvable”
Cause : ticket sans section “Proposition (remplacer par):”.
Fix : respecter le contrat de ticket.

### apply-ticket : “Match trop faible”
Cause : texte actuel absent / trop tronqué / mismatch.
Fix :
- privilégier “Texte actuel (copie exacte du paragraphe)”
- sinon le script récupère via `dist` (si possible).

---

## 11) Règles de contribution (discipline de repo)
- Toute modif éditoriale passe par ticket → apply-ticket → tests.
- Toute modif structurelle (layouts, rendu, MDX) doit être suivie de :
  - `npm test`
  - éventuellement `npm run test:anchors:update` si changement volontaire d’ancres.
- Ne jamais éditer `dist/` à la main.

---

## 12) Commandes utiles (raccourcis)
- Dev : `npm run dev`
- Build : `npm run build`
- Tests : `npm test`
- Anchors : `npm run test:anchors`
- Apply ticket : `node scripts/apply-ticket.mjs <N> --dry-run`

## 13) UI de lecture outillée (EditionLayout / Reading)

Cette section documente les comportements “front” qui ont été verrouillés et qui peuvent casser si on refactorise le layout, le CSS ou les scripts inline.

### 13.1 — Structure DOM (contrat)
Le layout d’édition repose sur cette structure (simplifiée) :

- `src/layouts/EditionLayout.astro`
  - `<aside class="page-aside">`
    - `<div class="page-aside__scroll">`
      - `<slot name="aside" />` (TOC global + TOC local)
  - `<article class="reading" data-pagefind-body>`
    - contenu (paragraphes + headings)
    - `<BuildStamp />`
  - `<div id="reading-follow" class="reading-follow">` (bandeau H1/H2/H3)
  - `<ProposeModal />` (dialog)

Important :
- Les styles `.page-aside` / `.page-aside__scroll` sont **dans EditionLayout.astro** (balise `<style>`), pas dans `global.css`.
- `global.css` contient les styles transverses (reading, offsets, reading-follow, tools boutons…).

### 13.2 — Scrollbar “left-side” (TOC global + TOC local)
But : **un seul scroll** qui englobe tout le panneau gauche.

Contrat :
- `.page-aside` est sticky (collé sous le header).
- Le scroll est **uniquement** sur `.page-aside__scroll` :
  - `max-height: calc(100vh - (...))`
  - `overflow: auto`
- Sur mobile (`max-width: 860px`) :
  - aside redevient “dans le flux” (plus sticky)
  - plus de scroll interne

Symptôme si ça casse :
- deux scrollbars (aside + un sous-bloc), ou
- le TOC local défile mais pas le global (ou inversement).

### 13.3 — Offsets d’ancrage (header + bandeau)
Objectif : quand on va vers `#p-…`, `#h2…`, `#h3…`, l’élément visé **n’est jamais caché** derrière le header ou le bandeau.

Contrat CSS (dans `src/styles/global.css`) :
- `--sticky-offset = calc(--sticky-header-h + --followbar-h)`
- `scroll-margin-top: var(--sticky-offset)` sur :
  - `.reading p[id]`
  - `.reading h1`, `.reading h2[id]`, `.reading h3[id]`
  - `.details-anchor`, `.para-alias` (ancres techniques)

Contrat JS (inline dans `EditionLayout.astro`) :
- mesure `header` et met à jour `--sticky-header-h`
- mesure la hauteur réelle du bandeau et met à jour :
  - `--followbar-h` (CSS)
  - `--sticky-offset-px` (utilisé par les scroll JS `scrollToElWithOffset()`)

### 13.4 — Bandeau “reading-follow” (H1/H2/H3)
But : afficher un rappel de contexte (H1/H2/H3) aligné sur la largeur du reading, avec navigation.

Contrat :
- CSS : `.reading-follow` s’aligne via
  - `left: var(--reading-left)`
  - `width: var(--reading-width)`
- JS :
  - calcule `--reading-left` / `--reading-width` à partir du `getBoundingClientRect()` de `article.reading`
  - maintient l’état courant H2/H3 (y compris dans des `<details>` ouverts/fermés)
  - expose 2 actions :
    - “haut du chapitre” (H1)
    - “haut de la section” (H2 courant)

Note : une micro-hystérésis (`HYST`) évite le clignotement quand on scroll à la limite.

### 13.5 — Outils par paragraphe (¶ / Citer / Proposer / Marque-page)
Le script inline injecte, pour chaque `.reading p[id^="p-"]`, une UI de tools.

Boutons :
- `¶` : lien direct vers l’ancre
- `Citer` : copie une citation structurée : `Titre (vX) — URL#ancre`
- `Proposer` : si Gitea configuré, ouvre un ticket pré-rempli (via modal)
- `Marque-page` : épingle un “pinned bookmark”

Stockage local :
- pinned : `archicratie:bookmark:pinned`
- dernier lu (par page) : `archicratie:bookmark:last:<pathname>`

Le bouton header “Reprendre la lecture” (`#resume-btn`) :
- se base sur pinned, sinon sur last
- si on est déjà sur la même page, il scroll vers l’ancre au bon offset (sans recharger)

### 13.6 — Boucle “Proposer” + modal (2 étapes)
Fichiers :
- génération du lien : `src/layouts/EditionLayout.astro` (inline script)
- modal + logique : `src/components/ProposeModal.astro`

Contrat côté lien “Proposer” :
- le lien DOIT porter :
  - `data-propose="1"` (ou présent en tant qu’attribut `data-propose`)
  - `data-url="<URL Gitea issues/new?...>"`
  - optionnel : `data-full="<texte complet>"` (permet upgrade du body)
- fallback “sans JS” :
  - le lien a `target="_blank"` et ouvre quand même Gitea

Contrat modal :
- Interception par délégation : `document.addEventListener("click", ...)` sur `a[data-propose]`
- Step 1 : choix du type (`correction` / `fact`)
  - met à jour `Type:` et `State:` dans le body
  - préfixe le title (`[Correction]` / `[Fact-check]`)
- Step 2 : choix de `Category:` (ou vide)
  - ajoute/retire la ligne `Category: ...`
  - ouvre l’issue en **nouvel onglet** (sans remplacer la page)

Garde-fou URL :
- `URL_HARD_LIMIT` (modal) empêche d’exploser la taille d’URL quand on tente d’injecter le texte complet dans `body=`.

---

## 14) Dépannage rapide (Firefox DevTools) — “tout comprendre” sans magie

### 14.1 — Ouvrir la console correctement (Firefox)
- Ouvre les DevTools : `F12` (ou `Ctrl+Shift+I`)
- Va dans l’onglet **Console**
- Tu peux exécuter du JS directement (comme tu l’as fait).

### 14.2 — Check “ProposeModal est là et vivant”
À exécuter dans la console :

- Le dialog existe :
  - `document.getElementById("propose-modal")`
- Le navigateur supporte bien les dialogs :
  - `typeof document.getElementById("propose-modal")?.showModal`
  - attendu : `"function"`
- Test affichage :
  - `document.getElementById("propose-modal")?.showModal()`
  - puis : `document.getElementById("propose-modal")?.close()`

### 14.3 — Check “les liens Proposer sont bien marqués”
- Combien de liens interceptables :
  - `document.querySelectorAll('a[data-propose]').length`
- Inspecter un exemple :
  - `document.querySelector('a[data-propose]')?.dataset`
  - attendu : au minimum `propose` et `url`
  - optionnel : `full`

Si `a[data-propose]` = 0 :
- le script d’injection côté paragraphes n’a pas ajouté les attributs,
- ou le selector diffère (`data-propose` absent / renommé),
- ou tu n’es pas sur une page “reading” (pas de `.reading p[id^="p-"]`).

### 14.4 — Check “le click est bien intercepté”
Tu peux provoquer un click “manuel” via :
- `document.querySelector('a[data-propose]')?.click()`

Résultat attendu :
- le modal s’ouvre (step 1),
- puis après choix step1 + step2 : nouvel onglet Gitea.

Si ça ouvre directement Gitea sans modal :
- soit `data-propose` / `data-url` manquent,
- soit un autre handler stoppe l’interception,
- soit le script modal n’est pas exécuté (erreur JS en console).

### 14.5 — Check “offsets d’ancrage”
Pour lire les variables calculées :
- `getComputedStyle(document.documentElement).getPropertyValue("--sticky-header-h")`
- `getComputedStyle(document.documentElement).getPropertyValue("--followbar-h")`
- `getComputedStyle(document.documentElement).getPropertyValue("--sticky-offset")`
- `getComputedStyle(document.documentElement).getPropertyValue("--sticky-offset-px")`

Symptôme si mauvais :
- clic sur une ancre -> heading/para caché derrière le header.

### 14.6 — Check “scroll du panneau gauche”
Dans l’inspecteur, sélectionne `.page-aside__scroll` et vérifie les styles calculés :
- `overflow: auto`
- `max-height: ...`

Si le scroll est ailleurs :
- `.page-aside` a récupéré `overflow` / `max-height` (mauvais endroit)
- ou une règle CSS globale a repris la main.

### 14.7 — Commandes terminal “sanity checks”
Toujours lancer depuis la racine du site (là où est `package.json`), ex :

- Rechercher les patterns sensibles :
  - `rg -n --hidden --glob '!node_modules/**' 'page-aside__scroll|reading-follow|data-propose|sticky-offset' src`
- Après build : vérifier qu’on n’a pas de règles “dangereuses” injectées dans `dist/` :
  - `npm run build`
  - `rg -n 'scroll-margin-top:\s*var\(--scroll-margin-top|overflow:\s*visible\s*!important|max-height:\s*none\s*!important' dist || echo "OK"`