bretzel 0.1.0a1__tar.gz

bretzel-0.1.0a1/.claude/bretzel/README.md

@@ -0,0 +1,71 @@
+# Référence Bretzel
+
+Ce dossier explique les mécanismes et les conventions que le code seul ne rend
+pas évidents. Il ne contient ni roadmap, ni inventaire manuel de l'API, ni état
+de chantier.
+
+Pour connaître la surface livrée :
+
+```powershell
+bretzel describe
+bretzel describe button
+bretzel describe ClientBinding
+```
+
+`describe` dérive les signatures, bindings, événements, slots, commandes
+impératives et clés de thème depuis le code. Il remplace les anciens
+`api-index.md` et `inventory.md`.
+
+## Choisir le bon document
+
+| Besoin | Référence |
+|---|---|
+| Créer et livrer un composant | [`creating-a-component.md`](creating-a-component.md) |
+| Comprendre le socle des composants | [`components.md`](components.md) |
+| Décider si une prop est réactive côté client | [`client-reactive-surface.md`](client-reactive-surface.md) |
+| Comprendre le routage des kwargs | [`kwarg-routing.md`](kwarg-routing.md) |
+| Utiliser les commandes `.open()`, `.set()`… | [`imperative-api.md`](imperative-api.md) |
+| Déclarer et persister un état | [`state.md`](state.md) |
+| Écrire un handler | [`handlers.md`](handlers.md) |
+| Comprendre le rendu et les refreshables | [`render.md`](render.md) |
+| Comprendre le runtime `bz-*` | [`runtime.md`](runtime.md) |
+| Composer ou surcharger un thème | [`theme.md`](theme.md) |
+| Vérifier sécurité, cookies et CSP | [`security.md`](security.md) |
+| Structurer une application | [`app-structure.md`](app-structure.md) |
+| Livrer une application | [`livrer-une-app.md`](livrer-une-app.md) |
+| Construire une navigation responsive | [`screen-responsive-nav.md`](screen-responsive-nav.md) |
+| Ajouter une page au playground | [`playground-pattern.md`](playground-pattern.md) |
+| Comprendre la carte d'application | [`app-map-model.md`](app-map-model.md) |
+| Écrire une gate de cohérence | [`gates.md`](gates.md) |
+| Écrire commentaires et docstrings | [`prose-and-comments.md`](prose-and-comments.md) |
+| Retrouver un piège technique précis | [`traps.md`](traps.md) |
+
+Le travail ouvert et les rapports vivent dans [`.claude/work/`](../work/).
+
+## Contrats transverses
+
+1. L'API applicative canonique est en Python. Les directives `bz-*` et les
+   attributs de transport sont produits par le framework.
+2. Une action serveur passe par un paramètre `on_<event>` ; le framework ajoute
+   la route, la signature et les en-têtes nécessaires.
+3. Seules les props déclarées dans `BINDABLE_PROPS` acceptent un
+   `ClientBinding`. `bretzel describe <composant>` les affiche.
+4. Les commandes d'instance sont write-only. Pour partager ou lire une valeur,
+   utiliser un binding explicite.
+5. Un champ de formulaire lié reçoit son `name` automatiquement.
+6. Les modules forment un graphe d'import acyclique. Le socle ne dépend pas des
+   couches applicatives.
+7. Les exemples montrent l'usage public et restent lisibles sans plomberie
+   interne.
+8. Une nouvelle règle structurelle est protégée par une gate qui prouve aussi
+   qu'elle détecte le défaut visé.
+
+## Entretien
+
+- Changement de surface publique : mettre à jour les docstrings introspectées
+  et vérifier avec `bretzel describe`.
+- Changement de mécanisme : mettre à jour la référence de couche concernée.
+- Dette nouvelle : l'ajouter à `.claude/work/todo.md`, avec sa preuve.
+- Fichier de référence ajouté ou supprimé : mettre cet index à jour.
+- Récit daté ou correction terminée : le retirer de la référence vivante ; Git
+  conserve l'historique.

bretzel-0.1.0a1/.claude/bretzel/app-map-model.md

@@ -0,0 +1,151 @@
+# Carte d'app — le modèle v4 (ACTÉ, 2026-07-05)
+
+> Statut : **ACTÉ** — fork socle tranché par l'utilisateur : **Option A**
+> (groupes socle accrochés aux layouts uniquement, jamais aux pages ;
+> le privé-à-une-page remonte au layout avec badge). Le composant
+> ``examples/shared/app_map_view.py`` est construit sur ce modèle.
+
+## Pourquoi une v4 — les défauts constatés (tous vérifiés sur MAD)
+
+1. **Une ligne = deux fonctions.** `_render_node : if kids or socle →
+   _toggle_row` : toute feature avec enfants OU socle devient un
+   chevron-toggle. Cliquer `dashboard` replie au lieu de sélectionner ;
+   le détail de TOUTE ligne à chevron (layouts compris) est inaccessible ;
+   l'icône de kind disparaît → une page se lit comme un layout.
+2. **Placement transitif inexpliqué.** `geo` est placé sous `planning_nav`
+   (LCA de {planning, tournees}, atteints VIA planning_engine) mais le
+   hover et le détail ne montrent que le direct → le lecteur ne peut pas
+   reconstituer le pourquoi. Vérifié : `planning.uses = [planning_engine]`,
+   geo absent des deux pages.
+3. **Donnée sans vue.** Badge « 6 routes » : le compte s'affiche, la liste
+   (`AppGraph.routes`, elle existe) n'est visible nulle part.
+4. **`errors` mélangé aux pages de nav.** Exact au fond (`@error_page(404,
+   layout=shell)` → le 404 SE REND dans le shell) mais présenté comme une
+   page navigable.
+
+**Cause racine** : deux relations de natures différentes — la CONTENANCE
+(un arbre, déclaré par `layout=`/`parent=`) et la DÉPENDANCE (un graphe,
+déclaré par `uses`/`reads`) — fondues dans UNE seule structure spatiale.
+Le LCA est une analyse ; en faire la position produit des placements
+inexplicables, des pages-dossiers et des clics contradictoires.
+
+## Prior art — ce que font les systèmes réels (vérifié sur docs officielles,
+recherche 2026-07-05)
+
+- **Encore.dev** : les frontières (services = dossiers) et les ressources
+  (API/DB/pubsub) sont déclarées en code ; **les arêtes ne sont JAMAIS
+  déclarées — toujours dérivées par analyse statique** (« 100% accuracy…
+  any deviation is caught as a compilation error »). Dans Flow : boxes +
+  flèches (pleine = appel API, tiretée = pubsub). Les « systems » (dossiers)
+  sont explicitement non-sémantiques. Pas de placement par usage.
+- **Backstage** : tout est **déclaré** en YAML ; vocabulaires disjoints
+  contenance (`partOf`/`hasPart`) vs dépendance (`dependsOn`,
+  `consumesApis`) ; visualisation = vues de voisinage par entité avec
+  filtres, pas un arbre global. **Aucune vérification contre le code** —
+  le mode d'échec canonique du catalogue déclaré-seulement.
+- **Nx** : arêtes **dérivées des imports** ; intention **déclarée** (tags) ;
+  `enforce-module-boundaries` (lint) **réconcilie les deux** — le seul des
+  quatre où l'architecture déclarée est machine-vérifiée contre le code.
+  Groupes visuels = dossiers (cosmétique) ; **provenance d'arête** : cliquer
+  une dépendance montre quels fichiers l'ont créée ; traçage de chemin
+  start→end à la demande (pas dessiné par défaut).
+- **C4** : la contenance vit sur l'**axe du zoom** (un diagramme = l'intérieur
+  d'UN système) ; « large diagrams are usually hard to interpret… nobody is
+  going to look at it » ; remède officiel : plusieurs diagrammes simples
+  issus d'**un seul modèle** (Structurizr).
+
+**Leçons appliquées à Bretzel** :
+1. contenance et dépendance = deux axes, jamais fondus (→ Fautes v3) ;
+2. le pattern gagnant = déclaré (intention) + dérivé (réalité) + **lint
+   réconciliateur** (→ L1/L2 ci-dessous — sans L2, `uses=` devient un
+   catalog-info.yaml : un mensonge bien intentionné) ;
+3. la liberté du repo est sûre précisément parce que la vérité ne vient
+   pas des dossiers ;
+4. un modèle, plusieurs vues focalisées — pas de méga-carte ;
+5. **une arête doit pouvoir se prouver** (provenance : quel import/état l'a
+   créée) — à brancher sur L2 quand le lint existera.
+
+**Écart assumé (Option A)** : le prior art strict ne niche jamais par usage ;
+l'Option A place des GROUPES socle dans l'arbre, accrochés aux layouts.
+C'est une projection étiquetée de l'axe dépendance (connecteur tireté +
+eyebrow « socle », jamais sous une page), pas une prétention de contenance —
+choisie sciemment pour l'effet spatial validé par l'utilisateur.
+
+## Le modèle v4 — 3 questions → 3 vues, 1 manifeste arbitré
+
+### Les rôles (l'API `Feature` ne change pas)
+
+Les 10 kinds se répartissent en 3 comportements de modèle :
+
+| rôle | kinds | se comporte comme |
+|---|---|---|
+| **ANCRE** (se rend) | shell, layout, page, error | nœud de l'arbre de rendu |
+| **SOCLE** (se consomme) | data, state, logic, facade, infra | feuille de dépendance |
+| **ENTRÉE** (se déclenche) | job | point d'entrée hors HTTP |
+
+### Le manifeste : contrat ↔ réalité ↔ lint
+
+- **Déclaré** (l'intention, 5 champs) : `name, kind, provides, uses, reads`.
+- **Dérivé** (les faits, gratuits) : arbre de rendu (marks `@page`/`@layout`),
+  routes, fichier par symbole (`__module__` de chaque provide), **portée**
+  (LCA → badge `global | branche <layout> | privé à <page>`), chaînes de
+  consommation transitives (« geo ← planning_engine ← planning, tournées »).
+- **Linté** (la doc ne peut pas mentir) — **LIVRÉ 2026-07-05** :
+  - L1 — `undeclared_provides()` : routable couvert par aucune Feature →
+    WARN au startup + section « ⚠ non déclaré » dans la carte
+    (`app.undeclared_pages`). Silencieux si l'app n'utilise pas les
+    Features (pas de sermon rétroactif).
+  - L2 — `dependency_drift()` : `uses`/`reads` déclarés vs **imports
+    réels** (AST des modules de chaque feature, via `sys.modules`) →
+    WARN dans les deux sens (missing = importé-non-déclaré, stale =
+    déclaré-non-importé). Excusés : soi-même, le parent de RENDU (le lien
+    `layout=` est déclaré par le mark), les modules hors features.
+    Dev-mode only (`config.debug`). Limites documentées : l'union
+    uses∪reads est comparée (la nuance n'est pas dérivable d'un import) ;
+    les imports sous `TYPE_CHECKING` comptent.
+  - Garde permanente : `test_dependency_drift_clean_on_real_examples`
+    force les contrats de mad à coller à leurs imports, pour
+    toujours.
+
+C'est la réponse à « flexible ET manifeste clair » : le repo reste libre
+(les dossiers ne portent AUCUNE sémantique), le manifeste reste 5 champs,
+et le framework **arbitre** contrat contre réalité — c'est ce qui rend la
+doc vivante fiable pour un humain comme pour une IA.
+
+### Vue 1 — INTERFACE : l'arbre de rendu PUR
+
+- shell → layouts → pages. Une page n'est **jamais** un dossier.
+- Les erreurs : micro-groupe distinct « erreurs » sous leur layout
+  (icône ⚠, pas mélangées aux pages de nav).
+- **Grammaire de clic** : clic ligne = TOUJOURS sélection/détail ;
+  le chevron est une petite cible séparée (layouts uniquement).
+
+### Vue 2 — SOCLE : groupé par portée (fork TRANCHÉ — Option A)
+
+Chaque feature socle porte un badge de portée dérivé :
+`global` · `branche <layout>` · `privé à <page>`.
+
+- **Option A — RETENUE** (2026-07-05, par l'utilisateur ; `examples/shared/app_map_view.py` est construit dessus) : les groupes socle restent dans l'arbre mais
+  accrochés aux **layouts uniquement** (shell, planning_nav…) — jamais
+  sous une page ; le privé-à-une-page remonte au layout parent avec badge
+  « privé à dashboard ». Garde l'effet spatial validé
+  (account_data-sous-account_nav) sans pages-dossiers.
+- **Option B** : zone Socle séparée sous l'arbre, groupée par portée.
+  L'arbre reste 100 % rendu ; le lien spatial est remplacé par badges+hover.
+- **Option C** : les deux, avec un toggle de vue.
+
+### Vue 3 — DÉTAIL & FLUX : l'explication
+
+- Détail (clic) : contrat + **fichier par symbole** (chemin cliquable) +
+  **consommateurs transitifs avec la chaîne via** — c'est ce qui rend le
+  placement de `geo` lisible.
+- Hover : éclaire le direct en fort + le transitif en atténué.
+- Badge routes **cliquable** → table `route → feature`.
+- Jobs : listés comme « entrées », avec ce qu'ils déclenchent.
+
+## Ce que la v4 SUPPRIME (simplification du composant)
+
+- L'injection du socle dans la récursion de rendu (la cause de la moitié
+  des bugs) — l'arbre redevient trivial.
+- Le double-rôle du clic — un seul comportement par cible.
+- Les compteurs sans vue.

bretzel-0.1.0a1/.claude/bretzel/app-structure.md

@@ -0,0 +1,319 @@
+# Structure d'une app Bretzel — tout est feature, le contrat est déclaré
+
+**À lire** quand tu démarres une app, ajoutes une feature, ou hésites sur où
+mettre un fichier.
+
+> ⚠️ **Réécrit le 2026-08-01.** La version précédente décrivait un modèle
+> que le code avait dépassé : elle ne mentionnait **nulle part** le contrat
+> `Feature` — qui fait échouer le boot quand il est violé —, prescrivait
+> `h-screen` là où les shells réels faisaient `fixed inset-0` (et où
+> `traps.md` conclut « ne PAS re-reverter » — depuis le 2026-08-23 c'est
+> `ui.viewport` qui le porte), et bannissait `shared/` avec
+> trois contre-exemples vivants. Références vérifiées : `examples/crm`
+> pour la structure, `examples/docs` et `examples/playground` pour le
+> reste.
+>
+> ⚠️ **Troisième app de référence en deux semaines** : une app à plat
+> jusqu'au 2026-09-07, `mad` jusqu'au 2026-09-10, toutes deux parties à
+> l'élagage. Une doc de structure ancrée sur une DÉMO est réécrite
+> chaque fois qu'une démo tombe, et une démo est là pour pouvoir
+> tomber. `crm` est l'instrument d'usage réel — la seule app
+> d'`examples/` qui ne relève pas de la règle d'élagage.
+
+---
+
+## 1. Le principe
+
+**Une feature = un dossier ou un fichier qui se décrit lui-même.** Elle
+déclare ce qu'elle expose, ce dont elle a besoin, et se décore elle-même
+(`@page` / `@layout` / `@error`). Aucune feature n'importe l'instance d'app.
+`main.py` est le seul fichier qui la connaît, et il ne fait qu'une chose :
+`app.include(...)`.
+
+Il n'y a pas de « type spécial » de feature. Un **shell est une feature** qui
+expose une région (`ui.outlet()`). Une source de données est une feature qui
+n'expose aucune page. La hiérarchie ne vit pas dans l'arborescence, elle vit
+dans le **contrat**.
+
+---
+
+## 2. Le contrat `Feature` — le cœur
+
+```python
+from bretzel import Feature
+
+feature = Feature(
+    name="notes",
+    kind="page",
+    provides=[notes_page, NotesDraft],   # ce que les autres peuvent importer
+    uses=["notes_data"],                 # les features dont je dépends
+)
+```
+
+Les six champs : `name`, `kind`, `provides`, `uses`, `reads`, `module`.
+
+**Les 10 `kind`** — `shell` · `layout` · `page` · `error` · `state` · `data`
+· `logic` · `infra` · `facade` · `job`. Un `kind` hors de cette liste est
+refusé.
+
+**`provides` expose des symboles, pas seulement des `State`.** Une feature de
+données publie légitimement son store, ses fonctions et ses vues :
+`examples/crm/features/accounts_data.py` fait
+`provides=[PatientsRev, list_patients, get_patient, add_patient,
+delete_patient]` — un store de révision, trois lectures et deux écritures
+dans le même contrat. C'est le contrat déclaré qui autorise l'import, pas
+le type du symbole.
+
+**Le contrat est validé au démarrage, pas à l'`include`.**
+`validate_features()` tourne dans le lifespan (`server/app.py`) et **fait
+échouer le boot** sur un contrat invalide. Deux linters s'y ajoutent, en
+WARN :
+
+| Lint | Ce qu'il attrape |
+|---|---|
+| `undeclared_provides` | un symbole importé par une autre feature sans être dans son `provides` — l'**oubli** de déclaration |
+| `dependency_drift` | un `uses` déclaré qui ne correspond plus aux imports réels (dérivés par AST) — la **dérive** |
+
+Les deux ensemble : L1 attrape l'oubli, L2 attrape le mensonge.
+
+**`describe_app(features) → AppGraph`** dérive le graphe depuis le contrat ;
+c'est ce qui alimente les pages *app map* de `crm` et
+du playground. Le
+modèle de rendu est dans [`app-map-model.md`](app-map-model.md).
+
+---
+
+## 3. `main.py` — la racine de composition
+
+```python
+from bretzel import Bretzel
+from myapp.core.theme import THEME
+from myapp.features import shell, home, notes, notes_data
+
+app = Bretzel(title="My App", secret_key="…", theme=THEME, mode="dev")
+
+# Ajouter une feature = l'ajouter ici. include() lit les contrats Feature(),
+# monte les provides, et VALIDE le graphe au démarrage.
+app.include(shell, notes_data, home, notes)
+
+if __name__ == "__main__":
+    app.run(port=8000, reload=True)
+```
+
+`app.include(*targets)` accepte **cinq formes** : un module, un **nom** de
+module déjà importé (`app.include(__name__)` pour une app mono-fichier), un
+objet **`Feature`**, un callable marqué par un décorateur, ou un itérable de
+tout ça. Idempotent.
+
+⚠️ **Le shell s'inclut comme le reste.** Dès qu'une app utilise les contrats,
+un layout DOIT être passé à `include` — sinon il manque au graphe.
+`examples/crm/main.py` inclut son `shell` au même titre que ses pages.
+(Seule `examples/docs`, qui n'utilise pas `Feature`, s'en dispense : son
+layout se résout par référence.)
+
+### 3bis. La langue — `lang=` et `texts=`
+
+```python
+app = Bretzel(title="Mon app", secret_key="…", lang="fr", texts={
+    "datatable.clear_filters": "Effacer les filtres",
+    "alert.dismiss": "Fermer l'alerte",
+})
+```
+
+Deux réglages parce qu'il y a **deux natures de texte**, et confondre les
+deux est ce qui produisait la moitié-configurable-moitié-pas :
+
+| | qui le produit | comment on le change |
+|---|---|---|
+| noms de mois et de jours, axes temporels | **dérivable** d'un code de langue | `lang=` seul |
+| « Clear filters », « No results », « Dismiss alert » | des phrases que **Bretzel a écrites** | `texts=` |
+
+`lang=` est une étiquette BCP-47 (`"fr"`, `"pt-BR"`) ; elle pose
+`<html lang>` — un lecteur d'écran y choisit sa voix — et voyage jusqu'aux
+composants. Les quatre composants de date n'ont **plus de table anglaise**
+figée : sans `month_names=` / `weekday_names=`, c'est `Intl` qui nomme,
+dans le navigateur. Python ne peut pas le faire (son module `locale` est
+un état **global au processus**, et Babel serait une dépendance).
+
+`texts=` fusionne sur les valeurs anglaises de
+`bretzel.render.texts.DEFAULT_TEXTS`. **Une clé inconnue lève au
+démarrage** : une faute de frappe dans un dict de traduction ne produit
+aucune erreur, et se manifeste seulement par une phrase restée en anglais
+que l'auteur de la traduction ne relira jamais.
+
+Ce n'est **pas de l'i18n** (hors périmètre v2.0) : pas de catalogue, pas
+d'extraction, pas de négociation `Accept-Language`, et la seule règle de
+pluriel est *un / autre*. Une app multilingue reste à construire par
+l'app.
+
+Côté framework : une phrase neuve dans un composant s'écrit
+`text("mon_composant.ma_clé")` et sa valeur anglaise se pose dans
+`DEFAULT_TEXTS`. L'ordre inverse est interdit par
+`tests/consistency/test_framework_words_go_through_the_table.py`.
+
+---
+
+## 4. L'arborescence
+
+```
+my_app/
+├── main.py             # Bretzel(...) + app.include(...) — le seul à voir l'app
+├── core/
+│   └── theme.py        # THEME = Theme(...) — le seul vrai « global »
+└── features/
+    ├── shell.py        # @layout — expose ui.outlet()
+    ├── home.py         # @page("/") — feature mono-fichier
+    ├── notes/          # feature en dossier
+    │   ├── __init__.py #   ré-exporte `feature` (le contrat)
+    │   ├── feature.py  #   Feature(name=, kind=, provides=, uses=)
+    │   ├── state.py
+    │   ├── logic.py    #   les handlers, module-level
+    │   └── ui.py       #   le rendu + les décorateurs @page
+    └── core/           # les features SANS page, groupées
+        └── notes_data/ #   (state + logic + ui + feature)
+```
+
+**`features/` peut être imbriqué** — regrouper par domaine est permis.
+⚠️ Aucune app ne le fait aujourd'hui : `mad`, qui portait
+`features/planning/`, est partie le 2026-09-10, et `crm` est plat sur
+ses 25 features. La permission reste ; l'exemple vivant a disparu avec
+elle. Le mot « flat »
+qualifie l'absence de couches techniques (`app/`, `views/`, `controllers/`),
+pas une interdiction de regrouper par domaine.
+
+**Mono-fichier ou dossier ?** Dossier au-delà de ~400 LOC, ou dès que le
+contrat devient non trivial. ⚠️ Le seuil est *indicatif* : 37 features
+mono-fichier du playground le dépassent aujourd'hui, dont une à 933 lignes —
+c'est de la dette assumée, pas la règle.
+
+**Un `core/` app-level** pour ce qui est vraiment global (le thème). Un
+`features/core/` pour les features sans page. Les deux coexistent.
+
+---
+
+## 5. Le shell — `ui.viewport` et `ui.pane`
+
+```python
+@layout
+def shell() -> None:
+    with ui.viewport():
+        with ui.sidebar(collapsible="rail"):
+            ui.sidebar_title("Brand", icon=ui.icon("box", size="lg"))
+            with ui.sidebar_section(label="MENU"):
+                ui.sidebar_item("Home", icon="home", href="/")
+        with ui.pane(gap="none", padding="lg"):
+            ui.outlet()
+```
+
+**Écrire `ui.viewport()`, c'est choisir un modèle de défilement.** Deux
+existent, et Bretzel garde le second par DÉFAUT :
+
+| modèle | qui défile | qui le fait |
+|---|---|---|
+| **document gelé** — `ui.viewport` + `ui.pane` | des régions, chacune la sienne | les outils (VS Code, Slack) ; Quasar en mode `container` |
+| **chrome fixe** (le défaut) | le document | le web (Mantine `AppShell`, shadcn `Sidebar`) |
+
+Une page **sans** coque défile normalement, sans que personne n'écrive
+quoi que ce soit. Le modèle gelé s'obtient explicitement, et il se paie :
+il faut une chaîne de hauteurs continue de la racine à la région. Ce qu'il
+achète, c'est **N régions à défilement indépendant** — un maître-détail,
+des colonnes de kanban, un fil de messages à côté d'une liste — que le
+modèle par défaut ne sait pas faire.
+
+⚠️ **Les deux chaînes de classes que ce § prescrivait sont mortes le
+2026-08-23**, absorbées dans les deux composants : `fixed inset-0 w-full
+overflow-hidden` (neuf copies) et `flex-1 min-h-0 overflow-y-auto` (dix-
+sept). Le POURQUOI de chaque utilitaire vit maintenant dans le thème du
+composant concerné, en un seul endroit — dont le `min-h-0` load-bearing
+et le `[&>*]:shrink-0` que personne n'écrivait.
+
+🔴 **Ne pas revenir à `h-screen` sur la racine d'une coque.** Le piège a
+été reverté **deux fois** vers `h-screen`, chaque fois avec une
+justification que la mesure démentait ; `traps.md` conclut « ne PAS
+re-reverter ». ⚠️ Nuance ajoutée le 2026-08-23 : l'inflation
+(`html.scrollHeight` 7 657 pour un `clientHeight` de 800) **ne s'est pas
+reproduite** dans une forme minimale re-testée en Chromium, donc elle
+venait d'autre chose que du seul `h-screen`. Ça ne rouvre pas le sujet —
+`fixed inset-0` est la forme livrée et elle n'a jamais rien cassé — mais
+la justification écrite n'a pas été re-mesurée.
+
+**La nav** (les `sidebar_item`) est listée en dur dans le shell. C'est le
+seul couplage restant, et exactement là que le placement déclaré par chaque
+feature gagnera sa place le jour où on le construira.
+
+---
+
+## 6. Les helpers partagés — autorisés, mais nommés
+
+Un dossier de helpers partagés **dans** l'app est légitime dès qu'il évite la
+copie intra-app :
+
+- `examples/crm/core/ui.py` — la carte KPI, factorisée.
+- `examples/docs/lib/` — `introspect.py` + `blocks.py` ; l'app documente
+  elle-même ce dossier comme partie de son squelette.
+- `examples/shared/app_map_view.py` — partagé **entre** exemples, importé par
+  `crm` et le playground.
+
+*(L'ancienne règle « pas de `shared/` — banni » avait ces trois
+contre-exemples vivants. Ce qui reste vrai : un dossier de helpers n'est pas
+un fourre-tout — s'il grossit, c'est qu'il contient une feature qu'on n'a pas
+nommée.)*
+
+---
+
+## 7. Les erreurs
+
+```python
+@error_page(404, layout=shell)
+def not_found() -> None:
+    ui.empty_state("Page introuvable", icon="search-x")
+```
+
+`abort(403)` (`from bretzel import abort`) lève depuis un handler ou un render pour router vers la page
+d'erreur correspondante.
+
+⚠️ **Le catch-all `Exception` est gouverné par `expose_errors`, pas par le
+mode.** `expose_errors` prend son défaut du `mode` mais reste surchargeable
+seul (`Bretzel(mode="dev", expose_errors=False)`). Vrai par défaut, faux
+comme règle.
+
+---
+
+## 8. Le playground fait exception, et c'est écrit
+
+`examples/playground` garde un `app/` (`routes.py` + `nav.py` + `layout.py`)
+et un `infra/errors.py`, parce qu'il monte **90 routes** écrites une par
+une. Sa convention propre est dans
+[`playground-pattern.md`](playground-pattern.md).
+
+⚠️ La justification a changé le 2026-08-30 : elle disait « ~57 pages
+générées par un sous-système (`features/matrix/`) », et ce
+sous-système a été supprimé. La dérogation tient toujours — un
+catalogue de 90 pages a besoin d'un index écrit — mais plus pour la
+raison qui était écrite ici.
+
+C'est une **dérogation assumée pour un catalogue**, pas le modèle d'une app
+produit. Pour une app, la règle du § 4 tient.
+
+---
+
+## 9. Anti-patterns
+
+- ❌ `from myapp.main import app` dans une feature. Jamais. Les décorateurs
+  sont libres (`from bretzel import page, layout`), `include` fait le reste.
+- ❌ Importer un symbole d'une autre feature sans qu'il soit dans son
+  `provides` — `undeclared_provides` le dira.
+- ❌ Déclarer un `uses` qu'on n'utilise plus — `dependency_drift` le dira.
+- ❌ `h-screen` sur la racine du shell (§ 5).
+- ❌ Recréer une couche technique (`views/`, `controllers/`, un `app/` dans
+  une app produit).
+- ❌ Un handler en lambda ou en closure — cf. [`handlers.md`](handlers.md).
+
+## 10. Checklist — ajouter une feature
+
+1. Un fichier `features/<nom>.py`, ou un dossier si le contrat est gros.
+2. Son `Feature(name=, kind=, provides=, uses=)`.
+3. Ses `@page` / `@layout` / `@error`, en important **seulement** `bretzel`.
+4. La ligne dans `app.include(...)` de `main.py`.
+5. Démarrer : un contrat invalide **fait échouer le boot** et te le dit ; un
+   `provides` oublié ou un `uses` dérivé sort en WARN.