@scratch2latex/scratch-core

Package partagé qui regroupe le cœur Scratch de la chaîne scratch2latex :

• traduction entre formats (sb3 ↔ représentation Scratch/LaTeX),
• rendu visuel des blocs Scratch avec scratchblocks,
• simulation/exécution d’un script Scratch dans le navigateur.

Ce package expose des briques réutilisables, pensées pour être consommées depuis d’autres projets (client web, outils de génération, etc.).

Ce que le package partage

1) ScratchInterpreter

Auteur (@author) : Jean-Claude Lhote.

Import :

import { ScratchInterpreter } from '@scratch2latex/scratch-core/ScratchInterpreter'

Rôle :

• exécuter un script Scratch (format LaTeX Scratch3) pas à pas,
• maintenir un état d’exécution (position, angle, stylo, variables, listes, messages),
• fournir des callbacks pour l’animation et l’interaction utilisateur.

API utile (principale) :

• executeAnimated(code, onUpdate, delayMs, options) : lance l’exécution et retourne un ExecutionResult,
• setExecutionDelay(delayMs) : ajuste la vitesse,
• stopExecution() : arrêt immédiat,
• triggerGreenFlagClick() et triggerKeyPress(key) : simulation d’événements,
• getCurrentState() : snapshot de l’état courant.

Types exposés : ExecutionResult, ScratchTrace, ScratchLookMessage, ScratchLookMessageType, ExecuteAnimatedOptions.

2) ScratchSimulator

Auteur (@author) : Jean-Claude Lhote.

Import :

import {
	ScratchSimulator,
	createScratchSimulatorElement,
} from '@scratch2latex/scratch-core/ScratchSimulator'

Rôle :

• fournir un Web Component <scratch-simulator> prêt à l’emploi,
• afficher le code Scratch rendu + un canvas de simulation,
• piloter l’exécution (play/pause, reset, vitesse, exécution complète),
• synchroniser la mise en évidence du bloc en cours avec l’interpréteur,
• proposer en fin d’exécution des exports de trace en SVG et en TikZ, ainsi qu’une action de copie TikZ.

Point d’entrée pratique :

• createScratchSimulatorElement(code, delayMs, insertProgramme) génère la balise HTML du composant.
• Le style des contrôles du simulateur est embarqué via l’import CSS du module ScratchSimulator.
• Import CSS explicite possible (si nécessaire) : @scratch2latex/scratch-core/styles/scratch-simulator.css.

3) scratchblock

Auteur (@author) : Jean-Claude Lhote.

Import :

import { scratchblock } from '@scratch2latex/scratch-core/scratchblock'

Rôle :

• traduire une chaîne LaTeX Scratch3 en markup scratchblocks encapsulé dans <pre>,
• produire le HTML source ensuite rendu graphiquement par scratchblocks,
• gérer différents styles (block/inline) et un mode contraste renforcé.

Signature :

scratchblock(stringLatex: string, style = 'block', useHighContrast = false): string | false

4) renderScratch

Auteur (@author) : Plusieurs auteurs (Jean-claude Lhote, Rémi Angot, Mickael Guironnet)

Import :

import renderScratch, {
	renderScratchDiv,
} from '@scratch2latex/scratch-core/renderScratch'

Rôle :

• appeler scratchblocks pour transformer le markup (pre.blocks, code.b, pre.blocks2) en SVG,
• charger le dictionnaire français (src/json/scratchFr.json),
• éviter les doubles rendus en retirant les classes de sélection après transformation.

Usage :

• renderScratch(selector) pour un rendu ciblé par sélecteur CSS,
• renderScratchDiv(root) pour rendre un sous-arbre DOM donné.

5) sb3ToLatex

Auteur (@author) : Matthieu Devillers d'après une réflexion de Jean-Claude Lhote.

Import :

import {
	sb3ToLatex,
	humanizeScratchOpcode,
	SIMULATOR_SUPPORTED_OPCODES,
	SIMULATOR_PARTIALLY_SUPPORTED_OPCODES,
	SIMULATOR_UNSUPPORTED_OPCODES,
} from '@scratch2latex/scratch-core/sb3ToLatex'

Rôle :

• convertir un projet Scratch sb3 (JSON) vers un document LaTeX Scratch3,
• mapper les opcodes Scratch vers des instructions lisibles en français,
• exposer des listes d’opcodes supportés / partiellement supportés / non supportés par le simulateur.

Fonctions/constantes clés :

• sb3ToLatex(projectJson) : conversion complète vers un document LaTeX,
• humanizeScratchOpcode(opcode) : libellé humain d’un opcode,
• SIMULATOR_*_OPCODES : état de couverture fonctionnelle côté simulation.

Vue d’ensemble du flux

1. Entrée sb3 → sb3ToLatex produit du LaTeX Scratch3.
2. LaTeX Scratch3 → scratchblock produit du markup HTML (pre.blocks...).
3. Markup HTML → renderScratch / renderScratchDiv produit le rendu visuel SVG.
4. Simulation interactive → ScratchInterpreter (moteur) + ScratchSimulator (UI Web Component).

Exports disponibles

Le package expose uniquement des sous-chemins (pas d’export racine) :

• @scratch2latex/scratch-core/ScratchInterpreter
• @scratch2latex/scratch-core/ScratchSimulator
• @scratch2latex/scratch-core/scratchblock
• @scratch2latex/scratch-core/renderScratch
• @scratch2latex/scratch-core/sb3ToLatex
• @scratch2latex/scratch-core/scratchEditorTemplate
• @scratch2latex/scratch-core/scratchSimulatorTemplate
• @scratch2latex/scratch-core/styles/scratch-simulator.css

Build et publication

Scripts principaux :

• pnpm build : compile TypeScript + copie les assets (json + css) dans dist,
• pnpm preview:templates : reconstruit dist puis sert dist en HTTP sur le port 8080,
• pnpm clean : supprime dist.

Exports de trace (SVG/TikZ)

Dans la fenêtre du ScratchSimulator, à la fin de l’exécution, des actions d’export sont proposées dans la zone d’information :

• Exporter la trace (SVG)
• Exporter la trace (TikZ)
• Copier le TikZ

Ces actions sont affichées uniquement si le programme a réellement produit au moins une trace (stylo posé + déplacement).

Template HTML de test du simulateur

Le template source est dans src/templates/scratch-simulator-template.html et il est copié automatiquement vers dist/scratch-simulator-template.html pendant pnpm build.

Le moteur TypeScript est dans src/scratchSimulatorTemplate.ts et exporté via @scratch2latex/scratch-core/scratchSimulatorTemplate.

Utilisation via l’export package :

import { initScratchSimulatorTemplate } from '@scratch2latex/scratch-core/scratchSimulatorTemplate'

initScratchSimulatorTemplate()

Il fournit :

• un bouton pour importer un fichier .sb3,
• un bouton pour lancer <scratch-simulator> avec le projet importé.

Utilisation rapide :

1. Lancer la prévisualisation : pnpm preview:templates
2. Ouvrir http://localhost:8080/scratch-simulator-template.html

Workflow en 3 étapes :

1. Cliquer sur Importer un fichier .sb3 et sélectionner un projet Scratch.
2. Cliquer sur Lancer le simulator puis exécuter le script dans la modale du simulateur.
3. En fin d’exécution (si des traces existent), utiliser Exporter la trace (SVG), Exporter la trace (TikZ) ou Copier le TikZ.

Template HTML d’éditeur Scratch contraint

Le template source est dans src/templates/scratch-editor-template.html et il est copié automatiquement vers dist/scratch-editor-template.html pendant pnpm build.

Le moteur de l’éditeur est dans src/scratchEditorTemplate.ts et exporté par le package via @scratch2latex/scratch-core/scratchEditorTemplate.

Objectif : proposer un mini éditeur pour les élèves avec une palette limitée de blocs (définie par l’enseignant), une zone de construction par glisser-déposer, puis exécution directe dans le ScratchSimulator.

Fonctionnement :

• palette de blocs autorisés (exemple inclus : répéter, avancer, tourner à droite, stylo en position d'écriture),
• import possible d’une consigne enseignant au format .sb3 pour déduire automatiquement la palette autorisée,
• zone de travail avec dépôt des blocs,
• génération automatique du code LaTeX Scratch,
• bouton Exécuter le programme qui charge et ouvre la modale du simulateur.

Utilisation via l’export package :

import { initScratchEditorTemplate } from '@scratch2latex/scratch-core/scratchEditorTemplate'

initScratchEditorTemplate()

Utilisation rapide :

1. Lancer la prévisualisation : pnpm preview:templates
2. Ouvrir http://localhost:8080/scratch-editor-template.html

Étapes de publication :

1. Copier ce dossier dans le dépôt dédié.
2. Mettre à jour repository et version dans package.json.
3. Publier sur npm / GitHub Packages.