SEQUA-Engine/studio

SEQUA Studio

SEQUA signifie Simulate Environments, Quantify Uncertainty, Adapt : simuler des environnements, quantifier l'incertitude liée à leur représentation et aux traitements, puis adapter les méthodes de calcul et de rendu au contexte. SEQUA Engine réunit quatre couches : Studio (la création), Core (la source de vérité : projet, simulation déterministe, rejeu, intentions, orchestrateur de rendu, confiance), SEQUA 3D (le contrat de données et la synchronisation vers les moteurs) et des moteurs 3D interchangeables (Godot, puis Unreal, à terme un moteur maison). SEQUA possède le projet et pilote les moteurs ; il n'est pas un plugin d'un autre moteur.

Rôle de Studio

Studio est le cœur et le visage du produit : c'est là que l'auteur exprime son intention, règle le ressenti, compose les modes de jeu et compare des variantes. Studio est une application web TypeScript indépendante de tout moteur ; il ne parle au Core que par un protocole (WebSocket et schéma partagé, Protobuf ou FlatBuffers — format non encore choisi). Son conteneur (navigateur, webview système, CEF) est un détail remplaçable.

L'interface est une vue d'un modèle d'état sérialisable : elle ne porte aucune logique produit. Les interactions produisent des événements, l'état évolue uniquement par une fonction pure de réduction, puis la vue est réaffichée.

État actuel

Squelette sans framework UI ni bibliothèque de composants :

• projet Vite + TypeScript strict, tests Vitest ;
• état minimal sérialisable (connection, protocolVersion, version du Core, raison de la dernière déconnexion, liste d'intentions vide) et réduction pure ;
• interface sobre affichant le titre, le statut de connexion, le badge « Core simulé » ou « Core réel », la version du Core et la raison de la dernière déconnexion ;
• connexion simulée par défaut : SimulatedCoreConnection n'ouvre aucune socket et reproduit la séquence connecting → connected avec une version de Core fictive marquée comme simulée ;
• connexion réelle optionnelle : WebSocketCoreConnection utilise l'API WebSocket native du navigateur, sans bibliothèque, et effectue la poignée de main hello → welcome ;
• messages JSON provisoires dans src/protocol/messages.ts, en attendant le schéma partagé (Protobuf ou FlatBuffers, fixé par une ADR) ;
• pas encore de serveur WebSocket côté Core, ni de reconnexion automatique.

Se connecter à un Core

Par défaut, Studio reste en mode simulé. Pour viser un Core réel, ajouter le paramètre d'URL core avec une URL ws:// ou wss:// :

http://localhost:5173/?core=ws://127.0.0.1:8787

Tout autre schéma (ou une URL invalide) est refusé : Studio reste en simulé et affiche la raison. Le Core n'a pas encore de serveur ; cette page décrit donc uniquement le client.

Le format des messages est provisoire et confiné à src/protocol/ :

• enveloppe { "v": 1, "type": "...", "payload": { ... } } ;
• client → Core : hello { protocolVersion, client: "sequa-studio" } ;
• Core → client : welcome { protocolVersion, coreVersion } et error { code, message } ;
• la poignée de main réussit si la version majeure de welcome.protocolVersion est celle de Studio et, tant que cette majeure vaut 0 (API instable selon semver), si la mineure est identique aussi ; un message error, un message indécodable, une version incompatible ou un délai de poignée de main dépassé (5 s par défaut) ferme le socket et affiche la raison.

Ce format sera remplacé par un schéma binaire généré depuis schema/ ; aucun autre module ne doit en dépendre.

Commandes

Prérequis : Node.js 24 recommandé (Vitest 5 accepte ^22.12, ^24 et >=26 ; Vite 8 accepte ^20.19 ou >=22.12).

npm ci          # installation reproductible depuis package-lock.json
npm run dev     # serveur de développement Vite
npm run check   # typecheck, tests, puis build de production

Autres scripts : npm run typecheck (tsc --noEmit), npm run test (vitest run), npm run build (vite build), npm run preview.

Structure

studio/
├── index.html
├── package.json
├── tsconfig.json
├── src/
│   ├── main.ts                 # montage dans #app, câblage connexion ↔ vue
│   ├── style.css               # thème sombre minimal
│   ├── model/state.ts          # StudioState, événements, état initial, reduce pure
│   ├── protocol/
│   │   ├── connection.ts       # interface CoreConnection + connexion SIMULÉE
│   │   ├── messages.ts         # messages JSON provisoires (encode/decode validants)
│   │   └── websocket.ts        # connexion WebSocket réelle (API native)
│   └── ui/app.ts               # rendu de l'état et actions de connexion
└── tests/
    ├── state.test.ts
    ├── connection.test.ts
    ├── messages.test.ts
    └── websocket.test.ts

Licences

SEQUA Studio est distribué sous Mozilla Public License 2.0 (MPL-2.0). Chaque fichier source porte son identifiant SPDX.

Dépendances directes de développement (versions et licences relevées dans node_modules/<paquet>/package.json après installation) :

Paquet	Version	Licence
vite	8.3.6	MIT
typescript	7.0.2	Apache-2.0
vitest	5.1.0	MIT

Ce sont les seules dépendances directes. Les paquets transitifs nécessaires à Vite, TypeScript et Vitest sont verrouillés par package-lock.json et restent des dépendances de développement, absentes du build de production en dehors des fichiers générés par Vite.