szcharlesji/tikz-live

Figures TikZ live

Une figure live est un dessin TikZ que le lecteur peut modifier. L'idée est la même que pour une figure statique dans tikz-dl-visualizer (une idée, rendue évidente), mais le lecteur fait quelque chose et regarde l'idée réagir : il fait glisser le point de départ et voit l'élan annuler le zigzag, il abaisse la température et voit softmax s'effondrer en argmax.

Chaque figure a deux moitiés :

fichier	contient	compilé par
figure.tex	tout ce qui ne change jamais : axes, contours, grilles, matrices de valeurs fixées, étiquettes, l'équation, et les emplacements pour le texte live	pdflatex, une fois
figure.js	tout ce qui change : paramètres, poignées, zones sensibles, un compute(state) pur, et draw(d, state, c)	le navigateur, à chaque changement

scripts/build.py compile le .tex deux fois (une fois normalement, une fois avec le texte live dans des couleurs d'ID pour pouvoir découper ces glyphes), exporte le repère de coordonnées TikZ et les boîtes nommées des nœuds, exécute la spécification sous node, et écrit :

• figure.html : une page autonome (sans réseau). Ouvrez-la, intégrez-la dans une iframe ou publiez-la.
• figure.png et figure.<instantané>.png : l'état par défaut et chaque instantané, rendus sans navigateur. C'est ainsi que vous voyez votre propre travail.
• figure.svg : l'état par défaut en SVG statique, pour les articles et les solutions de repli.

Inclus :

• assets/dlviz.sty : la palette et les styles TikZ (même fichier que tikz-dl-visualizer).
• assets/dllive.sty : côté TeX, les clés export et live= et \dlnum.
• assets/dllive.js : moteur d'exécution : correspondance des coordonnées, API de dessin, curseurs, poignées, zones sensibles, lecture.
• assets/examples/momentum/ : paramètres, une poignée déplaçable, un bouton de lecture, des nombres live, une étiquette mobile.
• assets/examples/attention/ : cellules exportées, zones sensibles au survol, une carte de chaleur, 29 nombres live, des courbes.
• references/api.md : l'API complète (clés TeX, champs de spécification, appels de dessin). Lisez-la avant d'écrire votre première spécification dans une session.
• references/gotchas.md : les problèmes rencontrés et leurs solutions. Lisez-la quand quelque chose semble étrange.

Pour le langage visuel lui-même (rôles des couleurs, notation, disposition, annotations), suivez tikz-dl-visualizer : ses references/visual-language.md et references/archetypes.md s'appliquent sans changement. Lisez-les si vous ne l'avez pas fait dans cette session.

Flux de travail

1. Écrire la phrase d'interaction

Avant tout code, écrivez une phrase de la forme « le lecteur fait X et voit Y, ce qui montre Z » :

• « Faites glisser le point de départ et changez β : le zigzag à travers la vallée s'annule tandis que le mouvement le long de celle-ci s'accumule ; un β trop grand dépasse. »
• « Survolez un jeton : sa ligne de A est l'ensemble des poids, et sa ligne de sortie est cette moyenne pondérée des lignes de V. Abaissez τ et les poids s'effondrent sur une seule ligne. »

Si Y serait tout aussi clair dans une figure statique, créez une figure statique (tikz-dl-visualizer). Utilisez un à trois contrôles. Chaque contrôle doit changer quelque chose que l'œil peut suivre ; un curseur dont l'effet est invisible est du bruit.

2. Séparer le statique du live

Dessinez sur papier ce qui change. Tout le reste va dans le .tex. Séparations typiques :

• Statique : axes, contours, grilles, contours de cellules, matrices fixes, étiquettes de jetons, l'équation, les étiquettes de lecture comme \(\beta = {}\), les traits de légende.
• Live : chemins, points, surbrillances, remplissages de carte de chaleur, flèches, atténuation, et les nombres (comme emplacements \dlnum, pour qu'ils restent de vrais glyphes TeX).
• Une étiquette qui doit se déplacer (par exemple attachée à une poignée) est aussi un nœud live=, déplacé avec d.label(id, {from, to}).

3. Écrire figure.tex

Partez de l'exemple le plus proche. Obligatoire :

\documentclass[tikz,border=8pt]{standalone}
\usepackage[dark]{dlviz}     % [light] pour les pages blanches
\usepackage{dllive}
\begin{document}
\begin{tikzpicture}[x=1.15cm, y=1.15cm]
  \useasboundingbox (xmin,ymin) rectangle (xmax,ymax);   % TOUJOURS : le dessin live doit tenir à l'intérieur
  ...dessin statique...
  \node[cell=coloraqua, export] (A-1-1) at (..) {};       % export : JS peut adresser cette boîte
  \node[fit=(Q-1-1)(Q-1-3), inner sep=0, export] (Qrow-1) {};   % boîte invisible pour une zone sensible
  \node[anchor=base west, inner sep=0, text=coloraqua] (b) at (..) {\(\beta = {}\)};
  \node[live=beta, anchor=base west, inner sep=0, text=coloraqua] at (b.base east) {\dlnum};
\end{tikzpicture}
\end{document}

• Définissez l'échelle avec x=/y= (pas scale=), pour que 1 unité en JS soit 1 unité en TikZ.
• Un nœud nombre live contient exactement \dlnum. Définissez sa couleur avec text= et sa taille avec font= ; les commandes de couleur à l'intérieur du nœud le cassent.
• Placez les nombres dans les cellules d'un tableau avec anchor=mid west au centre de la cellule, puis d.number(id, v, {at: "cell"}) les centre. Dans une \matrix ou partout où la disposition compte, utilisez \dlnumin{2em} pour que l'emplacement ne réserve que cette largeur.
• Si la figure n'a de sens qu'avec quelque chose de sélectionné, ouvrez-la dans cet état : initial: {hover: "..."} plus stickyHover: true.
• Nommez les choses pour que le JS puisse boucler dessus (A-\i-\j, Qrow-\i).
• Mettez un commentaire % Caption: en haut, comme dans tikz-dl-visualizer.

4. Écrire figure.js

DLLive.figure({
  title: "...", caption: "...comment interagir, une ou deux phrases...",
  params:  { beta: { label: "β", min: 0, max: 0.99, step: 0.01, value: 0.6 } },
  handles: { w0: { value: [-4, 1.5], min: [-5.2, -1.85], max: [5.2, 1.85] } },
  hotspots: /^Qrow-\d$/,                 // nœuds exportés qui définissent state.hover
  play: { param: "t", ms: 110 },         // optionnel : animer un paramètre (caché)
  compute: (s) => ({ path: run(s.beta, s.w0) }),          // maths pures, mémisées
  draw(d, s, c) {                                          // unités TikZ, couleurs dlviz
    d.path(c.path, { color: "aqua", width: "thick", dots: true });
    d.number("beta", s.beta, { digits: 2 });
  },
  snapshots: [{ name: "overshoot", beta: 0.95 }],          // PNG supplémentaires à vérifier
  tests: [{ name: "correspond à numpy", state: { beta: 0.4 }, check: (c) => Math.abs(c.path[30][0] - 1.036e-5) < 1e-8 || `obtenu ${c.path[30]}` }],
});

• Les maths vivent dans compute, et elles doivent être justes. Écrivez d'abord une référence en Python (numpy), puis ajoutez une entrée tests qui compare le JS à un nombre que vous avez calculé en Python. Ne faites jamais confiance à des maths écrites dans votre tête.
• draw ne fait que dessiner : pas de changement d'état, pas d'aléatoire (utilisez un RNG à graine dans compute si vous avez besoin de bruit), et s'exécute à chaque image.
• Utilisez les rôles de couleurs dlviz (aqua, red, orange!55!bg...) et les largeurs TikZ (thin, thick, very thick), pour que la superposition ressemble à l'échafaudage.
• Ajoutez un instantané pour chaque état important : un extrême de chaque curseur, un survol, un milieu d'animation. C'est là que les chevauchements se cachent.

5. Builder

uv run --with pymupdf python <chemin-du-skill>/scripts/build.py chemin/vers/figure.tex

Cela affiche les noms des nœuds exportés et des emplacements live, combien de nœuds les zones sensibles ont trouvé, PASS/FAIL pour chaque test, et WARN pour le dessin en dehors de la page ou le texte TeX coupé à son bord. Les erreurs nomment l'emplacement, le nœud ou le paramètre en cause. Après un changement du .js uniquement, ajoutez --no-tex (environ 1 seconde).

6. Regarder, critiquer, itérer

Ouvrez chaque PNG écrit (outil Read) et vérifiez, comme pour une figure statique :

1. La partie live s'aligne-t-elle avec l'échafaudage (les chemins commencent au bon point, les nombres sont dans leurs cellules, les surbrillances entourent leurs lignes) ?
2. Dans chaque instantané, y a-t-il un chevauchement : un chemin à travers une lecture, une courbe traversant des nombres, du texte sortant de sa cellule, quelque chose coupé au bord ?
3. Les extrêmes des contrôles sont-ils encore lisibles (β = 0.99, τ = 0.2, une poignée dans un coin) ?
4. L'œil peut-il trouver l'idée en trois secondes dans l'état par défaut ? L'état par défaut est ce que voient une vignette et un lecteur qui survole.
5. Les couleurs conservent-elles leurs rôles tant dans l'échafaudage que dans la superposition ?

Corrigez et reconstruisez. Deux ou trois cycles sont normaux.

Ensuite, essayez la vraie page si vous avez un navigateur (le panneau Browser intégré) : il refuse généralement file://, alors servez le dossier, par exemple avec une entrée .claude/launch.json {"name": "fig", "runtimeExecutable": "python3", "runtimeArgs": ["-m", "http.server", "8800", "--directory", "<dossier>"], "port": 8800} et preview_start. Faites glisser, glissez, survolez et jouez ; dans la console, DLLive.state() montre l'état actuel. Les instantanés n'affichent pas les tirets ni les curseurs de survol.

7. Livrer

Donnez à l'utilisateur le PNG (état par défaut), le chemin vers figure.html, et un court guide de lecture : par quoi commencer et quoi observer (« Faites glisser w₀ dans la direction raide, puis augmentez β... »). S'il veut un lien partageable, publiez le HTML en tant qu'Artifact ; il est autonome, donc aucun fichier supplémentaire n'est nécessaire. Mentionnez le contrôle ou la figure naturelle suivante en une ligne.

Intégration

• Plusieurs figures sur une même page, ou une page avec son propre thème clair/sombre (tikz-explorer-book le fait via son tools/fig.sh) : construisez avec --themes dark,light --embed. Cela compile l'échafaudage dans les deux thèmes et écrit figure.live.html, un fragment (<div class="dl-live"> plus un <script>DLLive.load("name", ...)</script>). La page hôte inclut assets/dllive.js une fois avant les fragments, et les règles CSS marquées « live figure » dans assets/template.html. Elle affiche l'échafaudage pour le thème actuel avec --show-d / --show-l. Le moteur d'exécution suit le thème de la page (data-theme="dark|light" sur <html>, ou le réglage système) et recolore la superposition. Un -light.png est aussi écrit.
• Autonome ou un Artifact : figure.html tel quel. Avec --themes dark,light, il suit le thème du spectateur ; sinon, il conserve le thème du .tex.
• Slides : utilisez figure.png / figure.svg pour le slide statique, et liez le HTML.
• Article : utilisez figure.svg ou le PDF de l'échafaudage dans .dllive/ ; l'état statique par défaut est une figure complète en soi. Pour les figures exclusivement imprimées, tikz-dl-visualizer est l'outil le plus adapté.