# BINKSY LOGONEXT — MODE D'EMPLOI POUR AGENTS IA
Ce document s'adresse aux agents IA (Claude Code, Codex, ou tout agent qui pilote un navigateur via Playwright / CDP, ou qui exécute du JavaScript dans la page). Il couvre tout l'outil : import d'un logo SVG ou d'un projet `.binksy`, réglages (marque, palette, variantes, formats, versions, QR code), export du ZIP et du projet `.binksynext`, et l'API publique `window.multiformats`.
Il existe en trois endroits, toujours identiques : `/AGENTS.md` (Markdown, français puis anglais), la page `/agent` et l'écran **Agents IA** de l'outil (`#/agents`, pied de l'accueil, barre latérale).
Points d'entrée découvrables sans JavaScript : la page `/` déclare `` qui renvoie ici, et écrit une seule ligne `console.info` au chargement. `/robots.txt` autorise tout et cite `/llms.txt` et `/AGENTS.md`.
---
# 1. RÈGLE FONDAMENTALE
Binksy LogoNext est un **outil de déclinaison pour graphistes**, pas un générateur de logos.
* Le graphiste apporte son logo (SVG, `.binksy` ou `.binksynext`). C'est la **source de référence**. N'invente jamais un logo, un symbole ou une couleur de marque ; ne redessine pas un SVG fourni.
* Sans lien fourni par le graphiste, **pas de QR code** : ne fabrique pas d'URL.
* Aucune clé API, aucun fournisseur d'IA, aucun serveur : tout est calculé dans l'onglet. C'est toi, l'agent, qui décides et vérifies ; l'outil fournit les fonctions.
* Pas de doublon avec **Binksy LogoKit** : les fichiers de base (SVG, PNG HD, PDF, JPEG) se font là-bas. Ici : formats spécialisés seulement.
Après chaque opération : vérifie la valeur réellement enregistrée (`await multiformats.state()`), puis le résultat (`export` → `files`, `kit.read`). **Un appel ou un clic n'est pas une preuve de réussite.**
---
# 2. DÉMARRER
## Lancer l'outil
* C'est un seul fichier `index.html` (plus `AGENTS.md`, `llms.txt`, `robots.txt`, `agent/`). Servir le dossier : `python3 -m http.server 8792` puis http://127.0.0.1:8792/ — ou l'adresse publique fournie.
* `file://` fonctionne aussi (l'API est la même). Ajoute `?fresh` à l'adresse pour ignorer la session enregistrée (localStorage `lmf-session`).
* Routes (hash) : `#/` accueil · `#/outil` l'outil · `#/docs` documentation · `#/agents` cette page (`#/agents/en` en anglais). L'API marche quelle que soit la route ; `load.*` et `export` ne changent pas de page.
## Deux façons de piloter
1. **API JavaScript** (recommandé) : `window.multiformats` dans la page, aussi accessible sous **`window.logonext`** (même objet ; l'outil s'appelle désormais Binksy LogoNext, le nom `multiformats` reste pour la compatibilité). Chaque méthode agit par les mêmes fonctions que l'interface et renvoie du JSON.
2. **Clics** : les commandes clés portent un attribut stable `data-agent` (voir § 8).
```js
await multiformats.ready(); // attend la démo AVORA ou la session
multiformats.version; // "2.4"
multiformats.help(); // [{path, signature, description}]
multiformats.help('load'); // un groupe
await multiformats.state(); // tout l'état
await multiformats.catalog(); // groupes, formats, tailles, modes, règle des noms
```
## Conventions de l'API
* Toutes les méthodes (sauf `help`) sont **async** et renvoient des données JSON simples.
* Erreur = exception claire : `multiformats. : (valeurs autorisées)`. La validation se fait avant d'appliquer : rien n'est appliqué à moitié.
* Entrées de fichiers souples : `Blob`/`File`, `ArrayBuffer`, `Uint8Array`, data URL, base64, ou texte SVG.
* Exports : renvoient `{name, type, size, …}` ; ajoute `{base64: true}` pour recevoir le contenu, `{download: true}` pour déclencher le téléchargement du navigateur. Chaque fichier produit reste disponible dans `multiformats.files` (`list()`, `get(nom)`, `base64(nom)`, `download(nom)`), et chaque fichier du dernier ZIP dans `multiformats.kit` (`list()`, `read(chemin)`).
* Chaque réglage est enregistré dans la session (localStorage) comme depuis l'interface.
---
# 3. PARCOURS TYPE
```js
await multiformats.ready();
// 1. le logo (1 à 8 versions) — ou load.binksy(…)
await multiformats.load.svg([
{ svg: iconeSvgText, name: 'avora-icone', type: 'icone' },
{ svg: horizontalSvgText, name: 'avora-horizontal', type: 'horizontal' },
], { brand: 'AVORA' });
// 2. palette (facultative), mode, formats
await multiformats.setPalette([{ hex: '#ff5500', name: 'Orange', role: 'accent' }, { hex: '#111111', name: 'Noir', role: 'text' }]);
await multiformats.setMode('essentiel');
await multiformats.preset('site'); // ou setFormats({...})
await multiformats.setFormats({ 'g:ticket': true, webm: false });
// 3. QR (seulement avec un lien donné par le graphiste)
await multiformats.setQR({ url: 'https://avora.studio', logo: true, modules: 'arrondi', eyes: 'arrondi' });
// 4. contrôle avant export
const plan = await multiformats.plan(); // {mode, tasks, folders[]}
// 5. export
const kit = await multiformats.export({ base64: true }); // {name, size, count, files[], base64}
const readme = await multiformats.kit.read('avora-kit/LISEZMOI.txt', { text: true });
const bx = await multiformats.exportBinksynext({ base64: true }); // avora.binksynext, réouvrable ici (renommé .binksy : LogoKit)
```
Avec Playwright (Python), le contenu d'un fichier local se passe en base64 :
```python
import base64
svg = open('logo.svg').read()
page.goto('http://127.0.0.1:8792/#/outil')
page.wait_for_function('window.multiformats')
page.evaluate('multiformats.ready()')
page.evaluate('(s) => multiformats.load.svg(s, {brand: "AVORA"})', svg)
bx = base64.b64encode(open('projet.binksy', 'rb').read()).decode()
page.evaluate('(b) => multiformats.load.binksy(b, {name: "projet.binksy"})', bx)
r = page.evaluate('multiformats.export({base64: true, list: false})')
open(r['name'], 'wb').write(base64.b64decode(r['base64']))
```
Ou par l'interface : `page.set_input_files('#file', 'logo.svg')` (SVG) et `page.set_input_files('#bxFile', 'projet.binksy')` (accepte `.binksy` et `.binksynext`).
---
# 4. RÉFÉRENCE DE L'API
| Méthode | Rôle | Retour |
| --- | --- | --- |
| `ready({timeout?})` | Attend que l'outil soit prêt | `{version, api, route, hasLogo}` |
| `help(prefix?)` | Signatures (synchrone) | `[{path, signature, description}]` |
| `state()` | État complet | voir ci-dessous |
| `catalog()` | Groupes et formats (usage, où, tailles, dossier, couleurs Essentiel), modes, préréglages, types de version, rôles, règle des noms | objet |
| `plan({mode?})` | Ce que l'export produira, sans rien rendre | `{mode, tasks, folders:[{format, group, version, versionName, color, colorName, folder}]}` |
| `route(name?)` | Lit ou change la page (`accueil`, `outil`, `docs`, `agents`) | route |
| `load.svg(input, {replace=true, brand?, palette?, name?, type?})` | Charge 1 à 8 versions. `input` : un SVG ou une liste ; un élément peut être `{svg, name, type}` | `versions` |
| `load.binksy(data, {name?})` | Ouvre un `.binksy` (LogoKit, v2 ZIP ou ancien JSON) ou un `.binksynext` (cet outil) ; le contenu est détecté, l'extension ne compte pas | `{brand, versions, palette, source, restored?, state}` |
| `load.demo()` | Démo AVORA : 4 versions (Horizontal, Vertical, Icône, Logotype) et palette nommée de 4 couleurs (Noir/Texte, Orange/Accent, Craie/Fond, Marron/Texte secondaire), comme l'import de son .binksy ; `state().isDemo` = `true`. Le prochain `load.svg` (remplacement) ou `load.binksy` la remplace, palette comprise | `versions` |
| `addVersions(input, {name?, type?})` | Ajoute des versions | `versions` |
| `setVersion(id, {name?, type?})` / `removeVersion(id)` | Renomme, retype, retire | version / `versions` |
| `setBrand(name)` | Nom de la marque (préfixe des fichiers) | `{brand, slug}` |
| `setMode('essentiel' \| 'complet')` | Contenu du ZIP | mode |
| `setPalette(list)` | Palette, 8 max : `["#hex"]` ou `[{hex, name?, role?}]` | `palette` |
| `setVariants({cle: bool})` | Coche / décoche des variantes de couleur | `variants` |
| `preset(id)` | `site`, `shop`, `app`, `all` | ids des formats actifs |
| `setFormats({id \| "g:groupe": bool})` | Active / coupe formats et groupes | `[{id, on, available}]` |
| `setFormatVersions(formatId, ids \| null)` | Versions d'un format ; `null` = conseil | `{format, versions, custom}` |
| `setQR({url?, fg?, bg?, logo?, modules?, eyes?, quiet?})` | QR code | `qr` |
| `setSettings({bg?, size?, gradMode?, knock?, darkMode?, thermal?})` | Réglages | `settings` |
| `export({mode?, base64?, download?, list?})` | Fabrique le ZIP | `{name, type, size, mode, count, ms, errors, files, base64?}` |
| `exportBinksynext({base64?, download?})` | Projet `marque.binksynext` (format `.binksy` v2, type `application/x-binksynext`) | `{name, type, size, base64?}` |
| `exportBinksy(…)` | Ancien nom de `exportBinksynext` (même fichier `.binksynext`) | idem |
| `kit.list()` / `kit.read(path, {text?})` | Fichiers du dernier ZIP | `[{path, size}]` / `{path, name, type, size, base64 \| text}` |
| `files.list() / get / base64 / download` | Fichiers produits (ZIP, .binksynext) | |
Valeurs autorisées :
* Types de version : `icone`, `horizontal`, `vertical`, `logotype`, `monogramme` (deviné au ratio si absent).
* Rôles de palette (clés LogoKit) : `text`, `secondary-text`, `accent`, `background`, `primary`, `secondary`… (liste exacte : `catalog().paletteRoles`).
* Variantes (`state().variants[].key`) : `original`, `noir`, `blanc`, `gris`, `sombre`, `aplat`, `map`, `mono-`, `inv-`, duos… — selon le logo et la palette.
* Formats : `favicon-ico`, `favicon-svg`, `apple-touch`, `android-chrome`, `maskable`, `manifest`, `og`, `ios`, `android`, `play`, `macos`, `windows`, `bmp58`, `bmp80`, `zpl`, `cut`, `eps`, `profiles`, `discord`, `slack`, `banners`, `visio`, `signature`, `bimi`, `watermark`, `qr`, `webm`. Groupes : `g:web`, `g:apps`, `g:ticket`, `g:fab`, `g:social`, `g:qr`, `g:video`.
* QR : `modules` `carre` \| `arrondi` \| `points` ; `eyes` `carre` \| `arrondi` \| `rond` ; `quiet` 2 à 8 ; `fg`/`bg` en `#rrggbb`. Sans `url`, aucun QR (le format `qr` est `available: false`). Contraste < 4:1 → `safe: false` et l'export retombe en noir sur blanc.
* Réglages : `bg` `auto` ou `#rrggbb` ; `size` 0.6 à 1 ; `gradMode` `keep` \| `avg` \| `mono` ; `knock` booléen (blanc = trou) ; `darkMode` `plate` \| `outline` ; `thermal` `{mode: threshold|floyd|atkinson, thr: 30..225}`.
* `webm` n'est `available` que si le navigateur sait enregistrer du WebM (pas Safari) ; il est coupé par défaut (3 s d'enregistrement en temps réel par couleur).
`state()` renvoie : `{app, version, api, route, ready, brand, slug, isDemo, mode, preset, versions:[{id, name, type, folder, kind, width, height, colors, warnings, legibleAt16px}], palette:[{hex, name, role}], variants:[{key, name, folder, group, on, locked, background, ink}], groups:[{id, name, folder, on}], formats:[{id, group, name, on, available, folder, versions, customVersions, essentiel}], qr:{url, text, active, fg, bg, logo, modules, eyes, quiet, contrast, safe}, settings:{…}, webm, binksyImport}`.
---
# 5. LE FORMAT .binksy ET `modules.multiformats`
Le `.binksy` est le fichier projet de Binksy LogoKit. Cet outil enregistre le **même format** sous l'extension **`.binksynext`** (pour le distinguer d'un projet LogoKit) ; à l'import, `.binksy` et `.binksynext` sont acceptés tous les deux (y compris les anciens `.binksy` enregistrés ici). Pour ouvrir un `.binksynext` dans LogoKit, renomme-le en `.binksy`. Version 2 = archive ZIP :
* `manifest.json` : `{format: "binksy", version: 2, kind: "multiformats" (export de cet outil seulement ; ignoré par LogoKit), app, appVersion, createdAt, savedAt, projectId, name, modules: {…, multiformats: true}, files: [{path, id, size, sha256}], notEmbedded: []}`.
* `project.json` : `{format: "binksy-project", version: 2, id, name, brand, createdAt, updatedAt, assets, roles, extras, palette, customColorRoles, typography, variants, mockups, modules, missing}`.
* `assets[id]` : `{id, hash, mime: "image/svg+xml", size, kind: "svg", name, w, h, origin: "multiformats", file: "assets/svg/.svg", embedded: true}` ; `id` = `a` + 20 premiers caractères du SHA-256 du SVG.
* `roles` : `{logo, icon, wordmark}` (icône = Icône sinon Monogramme ; logotype = Logotype ; logo = Horizontal sinon Vertical sinon une autre version) ; les autres versions dans `extras`.
* `variants` : `[{id: horizontal|vertical|icon|wordmark|mf-N, name, asset, kind: composition|icon|wordmark}]`.
* `palette` : `[{id, name, hex, role}]` (rôles en clés LogoKit ; rôles personnalisés listés dans `customColorRoles`).
* `assets/svg/.svg` : le SVG d'origine de chaque version.
À l'import, l'outil lit : `brand` (sinon `name`), `variants[]` sinon `roles` (+ `extras`), sinon l'ancien `modules.logokit` ; `palette[]` (8 max) ; les anciens `.binksy` JSON V1–V5 (versions recomposées comme LogoKit). Le lecteur ZIP ne lit que l'index central et les fichiers utiles (deflate via `DecompressionStream`), ZIP64 compris.
## `modules.multiformats`
Ajouté par « Exporter en .binksynext » ; LogoKit le conserve tel quel. S'il est présent à l'import, **tout l'état revient** (et seules les versions sont lues dans `assets`).
```json
{
"app": "Binksy LogoNext", "v": 1, "savedAt": "2026-10-29T10:00:00.000Z",
"session": {
"v": 2,
"shapes": [{ "name": "Icône", "type": "icone", "file": "avora-icone", "asset": "a1b2c3…" }],
"kitName": "AVORA", "isDemo": false, "mode": "essentiel", "preset": "custom",
"palette": ["#ff5500", "#111111"],
"palLabels": { "#ff5500": { "name": "Orange", "role": "Accent" } },
"map": {}, "mapTouched": false,
"off": ["gris"], "fmtOff": ["g:video", "webm"], "fmtShapes": { "banners": [1] },
"ctxVar": "auto", "gradMode": "keep", "knock": true, "darkMode": "plate",
"bg": "auto", "size": 0.8, "thermal": { "mode": "atkinson", "thr": 128 },
"qr": { "url": "https://avora.studio", "fg": "#111111", "bg": "#ffffff", "logo": true, "modules": "carre", "eyes": "carre", "quiet": 4 }
}
}
```
* `shapes[].asset` pointe vers `assets[id]` ; `fmtShapes` donne, par format, les **index** des versions choisies.
* `off` : clés de variantes décochées ; `fmtOff` : formats (`id`) et groupes (`g:`) coupés.
* `palLabels[hex].role` est le libellé français (Texte, Accent, Fond…) ; dans `project.json`, `palette[].role` porte la clé LogoKit.
---
# 6. LE ZIP
Nom : `-kit-.zip` (ex. `avora-kit-essentiel.zip`). Racine : `-kit/`.
```
-kit/
LISEZMOI.txt UTF-8 avec BOM, CRLF
1-web/favicons/[/]/ favicon.ico, _favicon_.svg, apple-touch-icon.png,
_android-chrome-192x192_.png, …-512x512…, _maskable-192x192_.png,
…-512x512…, site.webmanifest, _a-coller-dans-head_.html
1-web/image-de-partage/… _og-image-1200x630_.png
2-apps/ios/…/AppIcon.appiconset/ AppIcon-1024.png, AppIcon-1024-dark.png, AppIcon-1024-tinted.png, Contents.json
2-apps/android/…/res/ mipmap-{mdpi…xxxhdpi}/ic_launcher{,_round,_foreground,_background,_monochrome}.png,
mipmap-anydpi-v26/ic_launcher{,_round}.xml, values/ic_launcher_background.xml
2-apps/google-play/… macos/… windows/… _google-play-512_.png, _macos_.icns, _macos-1024_.png, _windows_.ico
3-ticket/ticket-58mm|ticket-80mm/…/noir/ _ticket-58mm-384px_noir.bmp (+ -apercu .png), 80 mm = 576px
3-ticket/etiquette-zebra/…/noir/ _etiquette-zebra-203dpi_noir.zpl
4-fabrication/decoupe|eps/// _decoupe[_]_.svg, _logo[_]_.eps
5-reseaux/photos-de-profil/… instagram-320, instagram-1080, linkedin-400, x-400, whatsapp-business-640,
youtube-800, facebook-720, google-business-720 (.png)
5-reseaux/bannieres/… youtube-banniere-2560x1440, linkedin-banniere-1584x396, x-banniere-1500x500,
facebook-couverture-1640x624, twitch-banniere-1200x480, google-business-couverture-1024x576
5-reseaux/discord|slack|fond-visio/… discord-512, slack-emoji-128, fond-visio-1920x1080
5-reseaux/signature-email/… _signature-email-px_.png + _signature-email_.html
5-reseaux/bimi/… _bimi-tiny-ps_.svg
6-qr-code/qr-code/