codepawl/machine-anatomy

Anatomie de machine

Un kit partagé : une nouvelle machine n’écrit que son modèle, sa disposition et son dessin, ses hooks en direct et ses faits. Le kit possède la page, les thèmes et styles, le cadre de zoom, la vue éclatée, le linter de vérité, l’enregistreur, le son et les vérifications. L’exemple de travail est examples/edison-light-bulb/ ; copiez sa structure.

1. Demander une fois, puis construire

Avant tout code, posez à l’utilisateur les questions d’orientation en un seul tour avec l’outil de questions de l’hôte (AskUserQuestion dans Claude Code), chacune avec sa valeur par défaut recommandée, en sautant tout ce qu’il a déjà dit. Puis continuez sans autre barrière. Questions, valeurs par défaut et correspondance avec la configuration : references/intake.md.

2. Rechercher, puis les faits

Lisez des sources réelles (brevet, articles du fabricant, page de musée, encyclopédie). Écrivez reference/notes.md avec les URLs et citations, puis facts.json : une entrée par fait avec text, source, quote ou note, et status (verified ou inferred). Règles et ce que le linter applique : references/truth-control.md. Listez chaque fonction de la machine et son contexte à partir des sources dans functions.

Rassemblez ensuite au moins 3 photos ou dessins réels de la machine et de son contexte dans reference/images/ avec sources.json, et ouvrez chacun avant de dessiner ; chaque assemblage nomme les images dont il est issu. Le linter l’applique et record écrit shots/reference-compare.png pour vérifier : references/reference-images.md.

3. Construire le dossier machine

node cli.mjs new <folder> --title "…" génère la structure à partir de l’exemple Edison. Remplacez dans cet ordre :

1. model.mjs — modèle pur, pas de DOM ; tout le comportement et chaque nombre affiché. test-model.mjs le teste contre des valeurs réelles ou des invariants. Les tests sont obligatoires.
2. layout.mjs — tailles en unités monde et courbes calculées (les chemins suivent les pièces réelles, jamais des cordes).
3. figure.mjs — drawFigure(draw) : dessine les pièces réelles sous forme d’éléments d’assemblages numérotés avec les aides du kit ; retourne label, defs, css, ancres de badge, points de pas et la cible de zoom.
4. live.js — createMachineHooks(kit) : état, dessin des pièces mobiles, contrôles, affichage, actions. Utilisez kit.Motion pour les ressorts, inertie et articulations : references/motion.md.
5. machine.mjs — assemblages avec axes de retrait et provenance, chaque texte visible sous forme { text, facts }, modèles d’affichage, contrôles, scénario du film, voix sonores.

Lisez les fichiers correspondants de l’exemple avant d’écrire chacun d’eux ; ne lisez pas les fichiers *.html générés.

4. Regarder

Le thème et le style de rendu sont des couches indépendantes : references/themes-and-styles.md. Définissez les valeurs par défaut dans machine.mjs (theme, style) ; toute page bascule avec ?theme= et ?style=.

5. Film et son

Le film par défaut est la forme approuvée de 30 s (fonctionnement d’abord, une naissance de zoom, un passage lent étiqueté, fonctionnement normal avec un moment de contraste, démontage décalé, remontage, fin en fonctionnement) : references/film.md. Le son est constitué de tapotements doux en microphone rapproché, sans bips, sans limiteur : references/sound.md. Règles de légende pour publier le film : references/caption.md.

6. Commandes et vérifications (toutes obligatoires avant de remettre)

node cli.mjs lint   <folder>     # textes liés aux faits, sources, superlatifs, provenance
node cli.mjs test   <folder>     # tests du modèle
node cli.mjs build  <folder> [--format 16:9,9:16,square]
node cli.mjs audit  <folder>     # ordre de peinture de la vue éclatée et traversée
node cli.mjs verify <folder>     # page réelle dans Chrome headless, chaque thème et style
node scripts/lines.mjs <folder>/<slug>-anatomy.html   # les lignes de texture aboutissent sur quelque chose
node cli.mjs record <folder> [--format 9:16] [--style dither] [--no-sound]
node cli.mjs remux  <folder>     # changement uniquement du son sur les images enregistrées
npm test                         # tests unitaires du kit

Playwright n’est pas inclus : npm install --no-save playwright, ou définissez MACHINE_ANATOMY_PLAYWRIGHT sur un index.mjs Playwright existant. L’enregistrement s’exécute à priorité normale réduite et sans GPU.

Ouvrez ensuite shots/<variant>/video-sheet.png, trois images fixes, les captures d’écran de vérification et shots/reference-compare.png vous-même ; corrigez les coupures, chevauchements, textes illisibles, motifs ondulants et toute différence avec les images de référence qui n’est pas une simplification déclarée.

Règles établies par le propriétaire (appliquées là où une vérification existe)

• Rien ne cache rien : une vérification de collision dans record et verify (references/film.md) ; déclarez seulement le chevauchement physiquement réel, avec sa raison, dans film.overlapAllowed.
• Montrez la machine dans son contexte réel complet (question d’orientation 10), sourcé, avec provenance.
• Le sujet occupe au moins 25 % de la hauteur du cadre à chaque phase et les événements clés se produisent à l’écran (minimum.subject, film.onScreen) ; une machine en mouvement utilise une caméra avec hooks.camera().
• Les motifs restent verrouillés sur les surfaces et n’ondulent pas ; mesurer avec scripts/swim.mjs (references/themes-and-styles.md).
• Le feu, la vapeur, la fumée et la lueur proviennent de kit/effects.mjs, pilotés par le modèle (references/motion.md).
• Chaque pièce en mouvement est montrée en mouvement ou a une raison énoncée ; pas de mouvement sans cause dessinée active ; le temps compressé est affiché à l’écran (references/completeness-and-causality.md, lint et record).

Rapport

Chemins de la page, fragment de publication et films ; compteurs lint, test, audit, verify et lines ; volume sonore, pic vrai et spectre du film (dire que personne n’a écouté) ; la timeline du film ; chaque fait de légende avec sa source ; ce qui est simplifié, inféré ou non vérifié.

Crédit : construit sur Anatomy par Ryan (github.com/wheresryan22/anatomy, MIT). Voir THIRD_PARTY_NOTICES.md.