@usefragment/core 0.0.0 → 0.1.0

package/README.md

@@ -1,12 +1,8 @@
 # @usefragment/core
 
-Le **contrat de types public** de [Fragment](https://github.com/RebornFlamme/Fragment)
-(alias Promethium) — le module hôte `fragment` que les plugins importent.
+The public **type contract** of [Fragment](https://github.com/RebornFlamme/Fragment) — the `fragment` host module that plugins import.
 
-Package **de types uniquement** : il ne contient aucun JavaScript. À l'exécution,
-l'hôte injecte les vraies valeurs (`fragmentApi`) via son shim `require('fragment')`
-— exactement comme le package `obsidian`. Ton bundler laisse donc `fragment` en
-*external* ; ce package ne sert qu'à ton compilateur pour typer l'import.
+A **types-only** package: it ships no JavaScript. At runtime the host injects the real values (`fragmentApi`) through its `require('fragment')` shim — exactly like the `obsidian` package does. Your bundler therefore keeps `fragment` external; this package exists only so your compiler can type the import.
 
 ## Installation
 
@@ -16,8 +12,7 @@ npm install --save-dev @usefragment/core
 
 ## Configuration
 
-Ajoute le package à `types` dans ton `tsconfig.json` pour charger les modules
-ambiants (`fragment`, et les alias `promethium` / `obsidian`) :
+Add the package to `types` in your `tsconfig.json` so the ambient modules (`fragment`, and the `obsidian` compatibility alias) are loaded:
 
 ```jsonc
 {
@@ -27,28 +22,26 @@ ambiants (`fragment`, et les alias `promethium` / `obsidian`) :
 }
 ```
 
-Et marque `fragment` en external dans ton bundler (esbuild) :
+And mark `fragment` as external in your bundler (esbuild):
 
 ```js
 esbuild.build({ /* … */ external: ['fragment', 'electron', '@codemirror/*'] });
 ```
 
-## Utilisation
+## Usage
 
 ```ts
 import { Plugin, Notice, type Command } from 'fragment';
 
-export default class MonPlugin extends Plugin {
+export default class MyPlugin extends Plugin {
   async onload() {
-    this.addCommand({ id: 'hello', name: 'Dire bonjour', callback: () => new Notice('👋') });
+    this.addCommand({ id: 'hello', name: 'Say hello', callback: () => new Notice('👋') });
   }
 }
 ```
 
-Les auteurs qui écrivent des extensions CodeMirror installent en plus
-`@codemirror/state` (peer dependency optionnelle).
+Authors writing CodeMirror extensions should also install `@codemirror/state` (an optional peer dependency).
 
-## Versionnage
+## Versioning
 
-Publié depuis le monorepo Fragment via [Changesets](https://github.com/changesets/changesets),
-indépendamment des versions du client. Voir le `CHANGELOG.md`.
+Published from the Fragment monorepo via [Changesets](https://github.com/changesets/changesets), independently of the app releases. See `CHANGELOG.md`.

package/dist/index.d.ts

@@ -161,6 +161,10 @@ declare class DragManager extends Events {
 	private moveGhost;
 	endDrag(): void;
 }
+declare class ExternalError extends Error {
+	readonly code: number;
+	constructor(code: number, message: string);
+}
 declare class HotkeyManager {
 	/** id de commande → raccourcis par défaut. Jamais persistés. */
 	defaultKeys: Record<string, Hotkey[]>;
@@ -532,6 +536,12 @@ declare class WorkspaceTabs extends WorkspaceParent {
 	 */
 	private updateTabOutline;
 }
+declare function compileModifiers(modifiers: Modifier[], plateforme?: Plateforme): string;
+declare function decompileModifiers(compiles: string, plateforme?: Plateforme): Modifier[];
+declare function getModifiers(evt: Pick<KeyboardEvent, "ctrlKey" | "metaKey" | "altKey" | "shiftKey">): string;
+declare function isMatch(liaison: Liaison, ctx: KeymapContext): boolean;
+declare function isModifier(evt: Pick<KeyboardEvent, "ctrlKey" | "metaKey" | "altKey" | "shiftKey">, modifier: Modifier, plateforme?: Plateforme): boolean;
+declare function isModifierKey(key: string): boolean;
 declare global {
 	interface Window {
 		app: App;
@@ -817,6 +827,8 @@ export declare class App {
 	 *  Câblé au boot (bootApp.tsx) depuis window.electron.cli ; le cœur et les
 	 *  plugins passent par ici plutôt que de toucher window.electron. */
 	cliHost: CliHost;
+	/** L'identité de cette instance (coffre, userData, version). Voir InstanceInfo. */
+	instance: InstanceInfo;
 	keymap: Keymap;
 	scope: Scope;
 	hotkeyManager: HotkeyManager;
@@ -825,11 +837,10 @@ export declare class App {
 	embedRegistry: Registry<unknown>;
 	commands: CommandManager;
 	icons: Registry<string>;
-	protocolHandlers: Registry<ProtocolHandler>;
 	codeBlockProcessors: Registry<CodeBlockProcessor>;
 	propertyWidgets: Registry<unknown>;
 	layers: Registry<LayerSpec>;
-	cliHandlers: Registry<CliHandlerSpec>;
+	externalCommands: Registry<ExternalCommandSpec>;
 	postProcessors: OrderedRegistry<MarkdownPostProcessor>;
 	editorExtensions: OrderedRegistry<Extension>;
 	ribbonItems: OrderedRegistry<RibbonItem>;
@@ -839,23 +850,18 @@ export declare class App {
 	registries: InspectableRegistry[];
 	lastEvent: Event | null;
 	constructor();
-	/** §15 — une URL arrive, on cherche l'action MAINTENANT dans la table. */
-	handleProtocol(action: string, params: Record<string, string>): void;
+	/**
+	 * §15 — une URL `fragment://<action>?params` arrive. Même port que le CLI
+	 * (`externalCommands`, via dispatchExternal), mais l'URL est fire-and-forget :
+	 * elle IGNORE le code de sortie et ne renvoie rien. Un échec se voit dans la
+	 * console (et, plus tard, via une Notice). Le câblage OS qui APPELLE ceci
+	 * (setAsDefaultProtocolClient, open-url) reste à faire — voir main.ts.
+	 */
+	handleProtocol(action: string, params: ExternalParams): void;
 	private cleLocale;
 	loadLocalStorage(key: string): unknown;
 	saveLocalStorage(key: string, data: unknown): void;
 }
-/**
- * Une erreur qui PORTE un code de sortie.
- *
- * Un handler qui lève n'importe quoi rend EXIT.HANDLER_ERROR (1) avec la pile.
- * Un handler qui lève une CliError choisit son code — « commande introuvable »
- * n'est pas un plantage, c'est un 7, et un script doit pouvoir les distinguer.
- */
-export declare class CliError extends Error {
-	readonly code: number;
-	constructor(code: number, message: string);
-}
 export declare class Component {
 	_children: Component[];
 	_cleanups: (() => void)[];
@@ -921,34 +927,12 @@ export declare class Keymap {
 	popScope(scope: Scope): void;
 	/** Public pour que les tests puissent injecter une frappe sans DOM. */
 	handleKeyEvent(evt: KeyboardEvent): boolean | void;
-	/** Les modificateurs d'un événement, en forme canonique. */
-	static getModifiers(evt: Pick<KeyboardEvent, "ctrlKey" | "metaKey" | "altKey" | "shiftKey">): string;
-	/** `['Mod','Shift']` → `"Ctrl,Shift"`. Résout, trie, joint. */
-	static compileModifiers(modifiers: Modifier[], plateforme?: Plateforme): string;
-	/**
-	 * L'inverse — pour AFFICHER une liaison enregistrée en dur.
-	 *
-	 * Le modificateur natif de la plateforme redevient `Mod`, ce qui est la
-	 * bonne réponse à « comment nommer cette combinaison à l'utilisateur ? ».
-	 */
-	static decompileModifiers(compiles: string, plateforme?: Plateforme): Modifier[];
-	static isModifierKey(key: string): boolean;
-	/** Ce modificateur-là est-il enfoncé ? `Mod` se résout selon la plateforme. */
-	static isModifier(evt: Pick<KeyboardEvent, "ctrlKey" | "metaKey" | "altKey" | "shiftKey">, modifier: Modifier, plateforme?: Plateforme): boolean;
-	/**
-	 * La liaison correspond-elle à la frappe ?
-	 *
-	 * ★ Les modificateurs sont comparés à l'IDENTIQUE, pas par inclusion :
-	 *   `Mod+P` ne se déclenche PAS sur `Mod+Shift+P`. Sans quoi tout raccourci
-	 *   serait le préfixe de tous ses sur-ensembles.
-	 *
-	 * ★ La touche est acceptée sur `vkey` (emplacement physique) OU sur `key`
-	 *   sans tenir compte de la casse. Le second point n'est pas une commodité :
-	 *   `Shift+A` produit `key === 'A'` tandis que `A` seul produit `'a'`, et
-	 *   une liaison écrite `'A'` doit marcher dans les deux cas — la
-	 *   différenciation par Shift est déjà faite par les modificateurs.
-	 */
-	static isMatch(liaison: Liaison, ctx: KeymapContext): boolean;
+	static getModifiers: typeof getModifiers;
+	static compileModifiers: typeof compileModifiers;
+	static decompileModifiers: typeof decompileModifiers;
+	static isModifierKey: typeof isModifierKey;
+	static isModifier: typeof isModifier;
+	static isMatch: typeof isMatch;
 	/**
 	 * §8.5 — l'événement demande-t-il une ouverture ailleurs ?
 	 *
@@ -1920,6 +1904,13 @@ export declare class WorkspaceLeaf extends WorkspaceItem {
 	setPinned(pinned: boolean): void;
 	togglePinned(): void;
 }
+/**
+ * Une erreur qui PORTE un code de sortie — alias d'`ExternalError`, la MÊME classe.
+ * Donc `new CliError(7, '…')` et `err instanceof CliError` marchent partout, et un
+ * plugin Obsidian qui lève une CliError reste compris. Le code de sortie fin
+ * (`command introuvable` = 7…) se choisit ici ; à défaut, un throw donne 1.
+ */
+export declare const CliError: typeof ExternalError;
 /**
  * Les codes de sortie — stables, documentés, testables.
  *
@@ -2011,14 +2002,6 @@ export declare function renderMatches(el: HTMLElement, text: string, matches: Se
  * l'absence est un état normal, même philosophie que les vues (§8.3).
  */
 export declare function setIcon(el: HTMLElement, name: string): void;
-/** Une entrée du registre `app.cliHandlers`. */
-export interface CliHandlerSpec {
-	/** L'id complet : `help`, `commands`, ou `templater:create-from-template`. */
-	command: string;
-	description: string;
-	flags: CliFlags;
-	handler: CliHandler;
-}
 /**
  * Les capacités CLI que le processus principal fournit au renderer. Injecté au
  * boot ; jamais construit par le cœur (qui n'a pas le droit de toucher
@@ -2337,6 +2320,19 @@ export interface EditorTransactionSpec {
 	/** Amène la sélection à l'écran. */
 	scrollIntoView?: boolean;
 }
+/** Une entrée du registre `app.externalCommands`. */
+export interface ExternalCommandSpec {
+	/** L'id complet : `help`, `command`, ou `templater:create` (préfixé pour les plugins). */
+	action: string;
+	description: string;
+	/**
+	 * Doc des paramètres acceptés, pour l'aide : nom → description. Un nom qui se
+	 * termine par `=` attend une valeur (`id=`), sinon c'est un drapeau (`total`).
+	 * Purement documentaire — rien n'est validé contre.
+	 */
+	params: Record<string, string>;
+	handler: ExternalHandler;
+}
 export interface FileStats {
 	ctime: number;
 	mtime: number;
@@ -2366,6 +2362,26 @@ export interface InspectableRegistry {
 		owner: string;
 	}>;
 }
+/**
+ * L'identité de CETTE instance — le coffre ouvert, où sont ses données, quelle
+ * version. Générique (pas CLI) : tout ce qui écrit par-instance ou coordonne des
+ * fenêtres (sync, backup, un jour le multi-fenêtre) lit ici, plutôt que de
+ * reconstruire ces chemins depuis `shared/cli/*`.
+ *
+ * ★ « Fenêtre active » n'est PAS modélisé aujourd'hui : un coffre = une fenêtre =
+ *   une instance (racineDuCoffre vient de process.argv, un seul coffre par
+ *   renderer). Le jour où le multi-fenêtre arrive, ce type s'élargit ici.
+ */
+export interface InstanceInfo {
+	/** La racine absolue du coffre (== racineDuCoffre()). */
+	vaultPath: string;
+	/** Le nom du dossier du coffre (== vault.getName()). */
+	vaultName: string;
+	/** Le dossier userData d'Electron — où vit l'index des instances CLI, p.ex. */
+	userDataDir: string;
+	/** La version de Fragment (== app.version). */
+	appVersion: string;
+}
 export interface Instruction {
 	/** La touche, telle qu'affichée : '↑↓', '↵', 'esc'. */
 	command: string;
@@ -2769,22 +2785,18 @@ export interface WorkspaceLayout {
 export type CliBridge = {
 	[K in keyof IpcInvokeMapping as StripCliPrefix<K>]: IpcInvokeMapping[K];
 };
+/** Ce qu'un handler reçoit : les `clé=valeur`, plus chaque `--drapeau` en `'true'`. */
+export type CliData = ExternalParams;
+export type CliError = ExternalError;
 /**
- * Ce qu'un handler reçoit : les `clé=valeur` de la ligne, plus chaque
- * `--drapeau` sous la forme `drapeau: 'true'`.
- */
-export type CliData = Record<string, string>;
-/**
- * Ce qu'un handler ACCEPTE, pour `help` : nom → description. Un nom qui se
- * termine par `=` attend une valeur (`id=`), sinon c'est un drapeau (`total`).
- * Purement documentaire — rien n'est validé contre.
+ * Ce qu'un handler ACCEPTE, pour `help` : nom → description. Un nom qui se termine
+ * par `=` attend une valeur (`id=`), sinon c'est un drapeau (`total`). Documentaire.
  */
 export type CliFlags = Record<string, string>;
-/**
- * Le handler. Il REND sa sortie — il n'écrit pas dans stdout, il n'a pas de
- * stdout. Ce qu'il rend est imprimé tel quel par le client.
- */
-export type CliHandler = (params: CliData) => string | Promise<string>;
+/** Le handler. Il REND sa sortie — il n'écrit pas dans stdout, il n'en a pas. */
+export type CliHandler = ExternalHandler;
+/** Une entrée du registre `app.externalCommands` (alias fidèle d'ExternalCommandSpec). */
+export type CliHandlerSpec = ExternalCommandSpec;
 /** Ce que le serveur répond. */
 export type CliResult = {
 	ok: true;
@@ -2804,6 +2816,13 @@ export type DragData = {
 	file: TFile;
 };
 export type DropZone = "reorder" | "split-top" | "split-bottom" | "split-left" | "split-right" | "center";
+/**
+ * Le handler. Il REND sa sortie — il n'écrit pas dans stdout, il n'en a pas. Ce
+ * qu'il rend est imprimé tel quel par le CLI ; l'URL, elle, l'ignore.
+ */
+export type ExternalHandler = (params: ExternalParams) => string | Promise<string>;
+/** Les paramètres d'une requête : un dico de chaînes (un drapeau vaut 'true'). */
+export type ExternalParams = Record<string, string>;
 /** De quel côté du texte se trouve une marge. */
 export type GutterSide = "left" | "right";
 // ─── Canaux requête/réponse : ipcRenderer.invoke ↔ ipcMain.handle ───────────
@@ -2859,8 +2878,6 @@ export type IpcInvokeMapping = {
 	// ─── Le retour de la TROISIÈME forme (voir IpcRequestMapping) ──────
 	/** Le renderer rend la réponse à une 'ipc:request', corrélée par son id. */
 	"ipc:reply": (id: string, result: unknown) => Promise<void>;
-	/** Le renderer annonce que boot() est passé et que 'cli:exec' est posé. */
-	"cli:ready": () => Promise<void>;
 	/**
 	 * `fragment eval` : le renderer demande au main d'évaluer `code` DANS le
 	 * renderer lui-même, par webContents.executeJavaScript — qui n'est pas
@@ -2918,8 +2935,6 @@ export type OverlayPlane = "viewport" | "document";
 export type PaneType = "tab" | "split" | "window";
 export type Plateforme = "macOS" | "autre";
 export type PluginConstructor = new (app: App, manifest: PluginManifest) => Plugin$1;
-/** §15 — fragment://<action>?params */
-export type ProtocolHandler = (params: Record<string, string>) => unknown;
 /**
  * La quatrième famille du pont : recevoir des requêtes du main. Pas de
  * préfixe à retirer ici — la seule dérivation utile est celle de
@@ -3055,9 +3070,9 @@ export {};
 //  Pied de page ambient, concaténé en fin de dist/index.d.ts par le build.
 //
 //  Le package expose le contrat comme module `@usefragment/core`, mais l'auteur
-//  d'un plugin importe depuis 'fragment' (ou les alias 'promethium'/'obsidian')
+//  d'un plugin importe depuis 'fragment' (ou l'alias 'obsidian')
 //  qu'il marque en external — l'hôte les résout à l'exécution (resoudreModuleHote).
-//  Ces re-déclarations ambiantes typent ces trois specifiers côté consommateur,
+//  Ces re-déclarations ambiantes typent ces deux specifiers côté consommateur,
 //  qui a @usefragment/core installé. Il ajoute `"types": ["@usefragment/core"]` (ou
 //  un `import '@usefragment/core';`) pour charger ces blocs.
 // ═══════════════════════════════════════════════════════════════════════════
@@ -3066,10 +3081,6 @@ declare module 'fragment' {
   export * from '@usefragment/core';
 }
 
-declare module 'promethium' {
-  export * from '@usefragment/core';
-}
-
 declare module 'obsidian' {
   export * from '@usefragment/core';
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@usefragment/core",
-  "version": "0.0.0",
-  "description": "Contrat de types public de Fragment (Promethium) — le module hôte `fragment` pour les plugins.",
+  "version": "0.1.0",
+  "description": "Public type contract for Fragment — the `fragment` host module that plugins import.",
   "license": "MIT",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -16,7 +16,6 @@
   "sideEffects": false,
   "keywords": [
     "fragment",
-    "promethium",
     "obsidian",
     "plugin",
     "types"