discovery-media-player 0.1.124 → 0.1.126

package/context/standalone.js

@@ -633,7 +633,15 @@ function createStandaloneContext(env = process.env) {
        *
        * ⚠️ Sert à fabriquer les liens qui partent par email. L'en-tête `Host` ne convient pas :
        * il est choisi par le client, donc un lecteur pouvait faire envoyer un message signé de
-       * l'hôte dont le bouton pointe ailleurs. Vide ⇒ repli sur `Host`, mais signalé.
+       * l'hôte dont le bouton pointe ailleurs.
+       *
+       * ⚠️ VIDE ⇒ RIEN NE PART. Ce commentaire a annoncé « repli sur `Host`, mais signalé »
+       * pendant tout le temps où le code refusait déjà l'envoi (`public-url-unconfigured`,
+       * routes-liens.js) — la 0.1.21 posait ce repli, la seconde passe d'audit l'a fermé, et
+       * trois textes sur quatre ont continué à le promettre (troisième audit externe, 21/08).
+       * Ce getter rend "" ; son unique consommateur retient le courrier, journalise le motif,
+       * et crée quand même le lien. Un commentaire qui décrit un comportement retiré est pire
+       * qu'une absence de commentaire : il fait renoncer à vérifier.
        */
       get publicUrl() {
         const v = sansBarreFinale(env.PLAYER_PUBLIC_URL).trim();

package/context/storage.js

@@ -191,6 +191,20 @@ async function lireDepuis(fh, stat, cible, range) {
     return reponse(413, {}, Buffer.alloc(0));
   }
 
+  // ⚠️ UN FICHIER VIDE N'A PAS DE PLAGE À DIFFUSER — et c'est une régression que le passage au flux
+  // a introduite. Avec `total === 0`, la borne haute vaut `total - 1`, soit -1 : `createReadStream`
+  // reçoit alors `{ start: 0, end: -1 }` et meurt en `TypeError` à la fermeture du descripteur.
+  // Le tampon d'avant tolérait `Buffer.alloc(0)` sans rien dire ; le flux, non.
+  //
+  // Un PDF de zéro octet est évidemment invalide — mais il doit produire une RÉPONSE, pas une
+  // exception serveur : c'est le lecteur qui décidera qu'il n'y a rien à afficher, et un 500 lui
+  // dirait « notre faute » au lieu de « ce fichier est vide ». Le cas AVEC `Range` est déjà traité
+  // plus haut : `debut < total` est faux, donc 416. (Relevé par un audit externe.)
+  if (total === 0) {
+    await fh.close().catch(() => {});
+    return reponse(200, { "content-type": type, "content-length": "0" }, Buffer.alloc(0));
+  }
+
   // ⚠️ ON DIFFUSE, ON N'ALLOUE PLUS — et le plafond ne suffisait pas à rendre l'allocation sûre.
   //
   // `Buffer.alloc(fin - debut + 1)` réservait la plage DEMANDÉE en une fois : jusqu'à 60 Mio par

package/docs/README.md

@@ -19,6 +19,14 @@ no document assumes you have read the others.
 | [`MIGRATIONS.md`](MIGRATIONS.md) | What happens to a database **already in service** when the player expects a newer schema. (French.) |
 | [`RETENTION.md`](RETENTION.md) | The declared perimeter of data retention: every personal-data column has a written policy, and CI enforces that the list is complete. Also an export of the package: `require.resolve("discovery-media-player/retention")`. (French.) |
 
+## You are contributing, or publishing a version
+
+| Document | What it gives you |
+|---|---|
+| [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | how to run the benches, what review looks for, and the one rule: a behaviour worth keeping is worth a test that fails without it. |
+| [`../AGENTS.md`](../AGENTS.md) | the conventions that are not obvious from the file tree — which ones a guard enforces, and which ones only review does. |
+| [`RELEASING.md`](RELEASING.md) | the release train, freezing the candidate SHA, the read-only preflight to run **before** the tag, and what to do when a tag lands on the wrong commit. |
+
 ## You are evaluating the project
 
 The external audit trail is public, unedited, and kept in the state it was received —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.124",
+  "version": "0.1.126",
   "description": "Self-hosted document viewer: per-recipient tracked links, reading analytics, live presentation. The core knows nothing about the application hosting it — everything it borrows arrives through an injected context.",
   "keywords": [
     "pdf-viewer",
@@ -32,6 +32,7 @@
     "dist",
     "server",
     "supabase",
+    "types",
     "README.md",
     "LICENSE",
     "LICENSE-MIT",
@@ -40,13 +41,19 @@
     "!**/__tests__"
   ],
   "exports": {
-    ".": "./server/handler.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./server/handler.js"
+    },
     "./shares": "./server/shares.js",
     "./presentations": "./server/presentations.js",
     "./brands": "./server/brands.js",
     "./contrat": "./docs/HOST-CONTRACT.md",
     "./retention": "./docs/RETENTION.md",
-    "./context/standalone": "./context/standalone.js",
+    "./context/standalone": {
+      "types": "./types/standalone.d.ts",
+      "default": "./context/standalone.js"
+    },
     "./context/storage": "./context/storage.js",
     "./bridge": {
       "types": "./dist/bridge.d.ts",
@@ -67,7 +74,8 @@
     "prepublishOnly": "npm run build && npm test",
     "test:e2e": "node -e \"require('fs').existsSync('vitest.e2e.config.mjs')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run --config vitest.e2e.config.mjs",
     "test:base": "node -e \"require('fs').existsSync('vitest.base.config.mjs')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run --config vitest.base.config.mjs",
-    "test:charge": "node -e \"require('fs').existsSync('vitest.charge.config.mjs')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run --config vitest.charge.config.mjs"
+    "test:charge": "node -e \"require('fs').existsSync('vitest.charge.config.mjs')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run --config vitest.charge.config.mjs",
+    "test:campagne": "node -e \"require('fs').existsSync('vitest.campagne.config.mjs')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run --config vitest.campagne.config.mjs"
   },
   "engines": {
     "node": ">=22"

package/server/page-visionneuse.js

@@ -322,6 +322,11 @@ ${LEGAL_CSS}
     var taches={};            // n -> RenderTask, pour pouvoir ANNULER
     var enCours={};           // n -> 1 tant que la page n a pas abouti
     var MARGE_PAGES=2;        // on garde la page courante et deux de chaque cote
+    // ATTENTION : UNE GENERATION PAR PAGE. La generation globale (renderGen) ne bouge qu au build ;
+    // une page liberee PENDANT que son rendu ou sa couche texte est en vol gardait donc la meme
+    // generation, et le resultat tardif se posait sur une page remise en reserve. On incremente
+    // donc a chaque liberation, et chaque callback verifie SA page.
+    var genPage=Object.create(null);
     var DPR_MAX=2;            // au-dela, le gain visuel est nul et le cout quadratique
     var PIXELS_MAX=4e6;       // plafond par canvas : ~4 M pixels = ~16 Mo de tampon
     var onePage=false, soloOffered=false; // mode « une seule page » (présentation guidée) + offre de découverte solo
@@ -754,6 +759,7 @@ ${LEGAL_CSS}
     // Rend une page a l etat de reserve : on retire le canvas et la couche texte, on remet la boite
     // avec sa hauteur estimee. Le defilement ne bouge pas, et la page se re-rendra si on y revient.
     function libererPage(n){
+      genPage[n]=(genPage[n]||0)+1;             // invalide tout callback en vol pour CETTE page
       var el=pagesEl.querySelector('.page[data-p="'+n+'"]'); if(!el)return;
       if(taches[n]){ try{ taches[n].cancel(); }catch(e){} delete taches[n]; }
       var w=Math.round(targetWidth());
@@ -766,10 +772,25 @@ ${LEGAL_CSS}
     // passer le cas qui fait tomber l onglet. On garde donc la fenetre courante, et on evince
     // au-dela — le nombre de canvas reste borne quel que soit le parcours du document.
     function evincerLoin(centre){
-      if(onePage) return;                       // une seule page affichee : rien a evincer
-      for(var k in rendered){
+      // ATTENTION : LE MODE UNE-PAGE EVINCAIT ZERO, ET MON COMMENTAIRE DISAIT POURQUOI — A TORT.
+      //
+      // Il portait « une seule page affichee : rien a evincer ». Une seule est AFFICHEE, mais
+      // showPage() rend la page courante ET la suivante a chaque navigation, et toutes les
+      // precedentes restent dans le DOM. Une presentation guidee de 100 pages finissait donc avec
+      // pres de 100 canvas — exactement le defaut que la fenetre glissante ferme ailleurs.
+      // Un raisonnement faux ecrit avec assurance fait passer un defaut pour une intention.
+      // (Releve par un audit externe.)
+      var marge = onePage ? 1 : MARGE_PAGES;    // une-page : courante, suivante, precedente
+      // ATTENTION : ON PARCOURT L UNION DES TROIS REGISTRES. rendered seul ignore ce qui est EN
+      // VOL : une page eloignee dont le getPage n est pas resolu continuait a travailler, et sa
+      // couche texte pouvait se poser plus tard sur une page deja liberee.
+      var vus = Object.create(null);
+      for(var a in rendered) vus[a]=1;
+      for(var b in enCours) vus[b]=1;
+      for(var c in taches) vus[c]=1;
+      for(var k in vus){
         var n=+k;
-        if(n<centre-MARGE_PAGES || n>centre+MARGE_PAGES) libererPage(n);
+        if(n<centre-marge || n>centre+marge) libererPage(n);
       }
     }
     function renderPage(n,el){
@@ -778,7 +799,7 @@ ${LEGAL_CSS}
       // donc un echec de getPage ou de render laissait la page marquee pour toujours : elle ne se
       // retentait jamais et restait vide. On distingue « en cours » de « aboutie ».
       enCours[n]=1;
-      var gen=renderGen;
+      var gen=renderGen, monGenPage=genPage[n]||0;
       if(IS_IMG){
         var w=Math.round(targetWidth());
         var im=document.createElement('img');
@@ -791,17 +812,28 @@ ${LEGAL_CSS}
         return;
       }
       pdfDoc.getPage(n).then(function(page){
-      if(gen!==renderGen){ delete enCours[n]; return; }   // un build() est passe : ce rendu n est plus attendu
+      // Un build() est passe (generation globale), ou CETTE page a ete liberee entre-temps.
+      if(gen!==renderGen || monGenPage!==(genPage[n]||0)){ delete enCours[n]; return; }
       // ATTENTION : LE DPR N ETAIT PAS PLAFONNE. Sur un ecran ×3, une page de 900 px de large fait
       // pres de 10 M pixels, soit environ 39 Mo de tampon pour UNE page — le gain visuel au-dela de
       // ×2 est nul, le cout est quadratique. On plafonne le DPR, puis on plafonne le NOMBRE DE
       // PIXELS du canvas : deux bornes, parce que le zoom peut faire grandir la page independamment
       // de la densite de l ecran.
-      var dpr=Math.min(DPR_MAX, window.devicePixelRatio||1);
       var scale=Math.min(5,targetWidth()/page.getViewport({scale:1}).width);
       var v=page.getViewport({scale:scale});
-      var pixels=Math.floor(v.width*dpr)*Math.floor(v.height*dpr);
-      if(pixels>PIXELS_MAX) dpr=Math.max(1, dpr*Math.sqrt(PIXELS_MAX/pixels));
+      // ATTENTION : LE PLANCHER A 1 CREVAIT LE BUDGET, ET LE BUDGET ETAIT ANNONCE.
+      //
+      // L ancienne formule reduisait le DPR sans jamais le laisser descendre SOUS 1. Or au zoom
+      // maximal la taille CSS a elle seule depasse le budget : a 300 %, une page de 4110×5319 CSS
+      // faisait 21,9 M pixels — soit ×5,5 le plafond annonce, environ 83 Mo de tampon pour UNE
+      // page. Le plancher visait la nettete ; il annulait la borne exactement quand elle servait.
+      //
+      // Le facteur se calcule donc depuis la taille CSS, borne par trois choses a la fois : le
+      // plafond de densite, la densite REELLE de l ecran (ne jamais sur-rendre), et le budget de
+      // pixels — qui peut le faire descendre sous 1. Verifie par calcul sur cinq configurations
+      // avant d etre ecrit. (Releve par un audit externe.)
+      var pixelsCss=Math.max(1, v.width*v.height);
+      var dpr=Math.min(DPR_MAX, window.devicePixelRatio||1, Math.sqrt(PIXELS_MAX/pixelsCss));
       var c=document.createElement('canvas');
       c.setAttribute('role','img'); c.setAttribute('aria-label','Page '+n);
       c.width=Math.floor(v.width*dpr); c.height=Math.floor(v.height*dpr);   // backing store HD → net comme du natif
@@ -811,7 +843,7 @@ ${LEGAL_CSS}
       taches[n]=tache;
       tache.promise.then(function(){
         if(taches[n]===tache) delete taches[n];
-        if(gen!==renderGen){ delete enCours[n]; return; }
+        if(gen!==renderGen || monGenPage!==(genPage[n]||0)){ delete enCours[n]; return; }
         delete enCours[n]; rendered[n]=1;                  // AVEREE, pas seulement demandee
         hideLoader(); if(n===cur)setTimeout(vsplitTint,60);
       },function(){
@@ -822,6 +854,10 @@ ${LEGAL_CSS}
       // Couche texte (sélection). En pdf.js v3, les spans utilisent font-size:calc(var(--scale-factor)*Npx)
       // → SANS --scale-factor, taille nulle = pas de sélection. On le pose sur le conteneur.
       try{ page.getTextContent().then(function(tc){
+        // ATTENTION : LA COUCHE TEXTE ARRIVE APRES, ET SE POSAIT SUR UNE PAGE LIBEREE. Elle
+        // ressuscitait alors une page remise en reserve — visible comme un bloc de texte
+        // selectionnable flottant sur un cadre vide.
+        if(gen!==renderGen || monGenPage!==(genPage[n]||0)) return;
         var tl=document.createElement('div'); tl.className='textLayer';
         tl.style.width=v.width+'px'; tl.style.height=v.height+'px'; tl.style.setProperty('--scale-factor', scale);
         el.appendChild(tl);

package/types/context.d.ts

@@ -0,0 +1,154 @@
+/**
+ * CE QU'UNE APPLICATION HÔTE FOURNIT AU PLAYER.
+ *
+ * ⚠️ Le cœur ne sait rien de l'application qui l'héberge : tout ce qu'il emprunte — stockage,
+ * base, identité, limites, marque, journalisation — arrive par cet objet, injecté une fois via
+ * `init(context)`. C'est la seule frontière, et ces types la DÉCRIVENT ; ils ne la déplacent pas.
+ *
+ * ⚠️ LA RÉFÉRENCE RESTE `docs/HOST-CONTRACT.md`. Ce fichier est une aide de frappe, pas le
+ * contrat : quand les deux divergent, le contrat gagne — et c'est ce fichier qu'il faut corriger.
+ * Les champs marqués optionnels le sont RÉELLEMENT : leur absence ferme une fonction en le
+ * disant, elle ne casse pas l'instance.
+ */
+
+/** Une requête HTTP entrante, telle que le player en a besoin. Volontairement minimale :
+ *  le player lit `req.query` quand la plateforme le fournit, et retombe sur `req.url` sinon —
+ *  un `http.createServer` nu marche donc sans adaptateur. */
+export interface RequeteEntrante {
+  url?: string;
+  method?: string;
+  headers: Record<string, string | string[] | undefined>;
+  query?: Record<string, unknown>;
+  body?: unknown;
+  socket?: { remoteAddress?: string };
+  on?(evenement: string, ecouteur: (...args: never[]) => void): unknown;
+}
+
+/** La réponse, côté Node. Le player écrit le statut, les en-têtes, puis le corps. */
+export interface ReponseSortante {
+  statusCode: number;
+  setHeader(nom: string, valeur: string | number | readonly string[]): unknown;
+  end(corps?: unknown): unknown;
+  write?(morceau: unknown): unknown;
+  writableEnded?: boolean;
+}
+
+export interface Plage { start: number; end?: number }
+
+/** Un flux lisible, décrit STRUCTURELLEMENT : ce paquet ne dépend pas de `@types/node`, et
+ *  exiger cette dépendance d'un consommateur pour lire un type serait une taxe déguisée. */
+export interface FluxLisible {
+  pipe?(destination: unknown): unknown;
+  on?(evenement: string, ecouteur: (...args: never[]) => void): unknown;
+  [Symbol.asyncIterator]?(): AsyncIterator<unknown>;
+}
+
+export interface FichierRelaye {
+  body: FluxLisible | Uint8Array | null;
+  status?: number;
+  headers?: Record<string, string>;
+}
+
+export interface Stockage {
+  /** Refus par défaut : ce qui n'est pas explicitement permis ne se relaie pas. */
+  isAllowedUrl(url: string): boolean;
+  fetchFile(url: string, options?: { range?: Plage }): Promise<FichierRelaye | null>;
+  put(seau: string, chemin: string, contenu: Uint8Array, type: string): Promise<boolean>;
+  /** Optionnel : sans lui, les pièces jointes du chat sont refusées — et le player le dit.
+   *  Le cœur ne doit jamais détenir la clé qui signe. */
+  signUpload?(seau: string, chemin: string): Promise<{ token: string; publicUrl: string } | null>;
+}
+
+export interface BaseDeDonnees {
+  /** Forme PostgREST : `table?colonne=eq.valeur`. Volontairement sans jointure imbriquée ni
+   *  arbre booléen — c'est ce qui garde un portage à la traduction plutôt qu'à la réécriture. */
+  request(chemin: string, options?: { method?: string; body?: unknown; headers?: Record<string, string> }): Promise<unknown>;
+  selectAll(chemin: string): Promise<unknown[]>;
+}
+
+export interface Identite {
+  verifyToken(entete: string | undefined): Promise<unknown | null>;
+  roleOf(utilisateur: unknown): Promise<string | null> | string | null;
+  isAdmin(utilisateur: unknown): Promise<boolean> | boolean;
+  /**
+   * Le player vérifie le jeton ; VOUS décidez des droits. Pas de réponse, ou une règle qui
+   * échoue, valent refus. L'action est passée parce que les hôtes séparent l'envoi ordinaire
+   * de l'administration.
+   */
+  canManageShares(utilisateur: unknown, action: string): Promise<boolean> | boolean;
+  /** Optionnel : autorise VOTRE serveur à créer un lien en son nom propre. Absent ⇒ ce chemin
+   *  n'existe pas. Le cœur ne voit jamais le secret : il demande, vous répondez. */
+  isTrustedHostCall?(entetes: Record<string, string | string[] | undefined>): Promise<boolean> | boolean;
+}
+
+export interface MarqueResolue { logo: string; name: string; dark?: boolean }
+
+export interface Marque {
+  name: string;
+  poweredBy: string;
+  loaderName: string;
+  logo(): Promise<string> | string;
+  /** `name` est le repli quand le logo ne charge pas — le champ le plus oublié, et le seul
+   *  qui aide quand tout le reste échoue. */
+  forKey(cle: string): Promise<MarqueResolue | null>;
+  title(base: string, qualificatif?: string): string;
+}
+
+export interface Limites {
+  /** ⚠️ Fail-open : un limiteur en panne ne doit pas tuer un lecteur. */
+  allow(cle: string, max: number, fenetreSecondes: number): Promise<boolean>;
+}
+
+export interface Courriel {
+  to: string;
+  subject: string;
+  html?: string;
+  text?: string;
+  [autre: string]: unknown;
+}
+
+export interface Mentions {
+  sourceUrl: string;
+  legalUrl: string;
+  privacyUrl: string;
+  trackingNotice: string;
+  /** Optionnel : la mention d'un lien que PERSONNE n'a envoyé. Absente ⇒ repli sur la première,
+   *  plutôt que de n'en afficher aucune. */
+  trackingNoticeAnonymous?: string;
+  /** ⚠️ Vide ⇒ AUCUN courriel ne part : la route répond `sendRefused: "public-url-unconfigured"`
+   *  et journalise. L'en-tête `Host` ne convient pas — le client le choisit. */
+  publicUrl?: string;
+}
+
+export interface Reglages {
+  /** Consommé tel quel, SANS barre finale : le cœur ne renormalise plus. */
+  supabaseUrl: string;
+  supabasePublishableKey: string;
+  mapsKey: string;
+  extraFrameAncestors: string[];
+  /** Ce qui est POSÉ, à côté de ce que le code SAIT faire : la carte d'identité publie les deux,
+   *  parce qu'une capacité disponible mais non configurée se comporte comme une absence. */
+  separateIssuer?: boolean;
+  hostShare?: boolean;
+  hostMail?: boolean;
+  retentionSweep?: boolean;
+  hostAuthStorageKey?: string;
+  [autre: string]: unknown;
+}
+
+export interface ContextePlayer {
+  storage: Stockage;
+  db: BaseDeDonnees;
+  identity: Identite;
+  branding: Marque;
+  limits: Limites;
+  legal: Mentions;
+  config: Reglages;
+  errors: { capture(erreur: unknown, meta?: Record<string, unknown>): unknown };
+  mail: { send(message: Courriel): Promise<{ sent: true } | null> };
+  /** Greffons appartenant à l'hôte. Le cœur affiche, trace et présente sans aucun — c'est testé. */
+  plugins: Record<string, unknown>;
+  /** Dit si un greffon est présent, sans le charger. */
+  has(nom: string): boolean;
+  schema?: unknown;
+}

package/types/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `discovery-media-player` — le point d'entrée.
+ *
+ * Le player est un GESTIONNAIRE DE REQUÊTES, pas un cadriciel : vous le montez où vous voulez,
+ * les chemins sont les vôtres. Tout ce qu'il emprunte arrive par `init(context)`.
+ *
+ *     const player = require("discovery-media-player");
+ *     const { createStandaloneContext } = require("discovery-media-player/context/standalone");
+ *     player.init(createStandaloneContext(process.env));
+ *     app.use("/api/doc", (req, res) => player.handler(req, res));
+ */
+
+import type { ContextePlayer, RequeteEntrante, ReponseSortante } from "./context.js";
+
+export type { ContextePlayer, RequeteEntrante, ReponseSortante };
+export * from "./context.js";
+
+/**
+ * Injecte le contexte. À appeler UNE FOIS, avant la première requête.
+ *
+ * ⚠️ Le cœur garde ce contexte dans un état de module : deux instances chargées dans le même
+ * processus partagent donc ce qu'on leur injecte. Une fabrique multi-instances est un chantier
+ * ouvert ; jusque-là, une instance par processus.
+ */
+export function init(contexte: ContextePlayer): void;
+
+/**
+ * Sert une requête. Lit `req.query` quand la plateforme le fournit (serverless, Express) et
+ * retombe sur `req.url` sinon — un `http.createServer` nu marche sans adaptateur.
+ */
+export function handler(requete: RequeteEntrante, reponse: ReponseSortante): Promise<void>;
+
+/** Un script tiers épinglé : version exacte dans l'URL, empreinte SRI à côté. */
+export interface Tiers { url: string; sri: string }
+
+/**
+ * ⚠️ EXPORTÉ POUR ÊTRE CONFRONTÉ, PAS POUR ÊTRE UTILISÉ. Le banc navigateur et la garde de forge
+ * partent de cet inventaire pour vérifier qu'aucune URL de script du gabarit ne lui échappe.
+ * Un hôte n'a rien à en faire — s'il en dépend, c'est le signe d'un manque ailleurs.
+ */
+export const TIERS: Record<string, Tiers>;

package/types/standalone.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `discovery-media-player/context/standalone` — un contexte complet, construit depuis
+ * l'environnement.
+ *
+ * C'est le chemin le plus court vers une instance qui marche : un dossier de documents, et rien
+ * d'autre. Chaque réglage est une variable d'environnement, décrite dans `docs/CONFIGURATION.md`
+ * — il n'y a pas de fichier de configuration, exprès : une instance est décrite entièrement par
+ * son environnement.
+ */
+
+import type { ContextePlayer, BaseDeDonnees, Limites } from "./context.js";
+
+/**
+ * Construit le contexte. `env` vaut `process.env` par défaut ; le passer explicitement permet
+ * de servir deux marques depuis un même processus, ou d'éprouver une configuration sans la poser.
+ *
+ * ⚠️ Ce qui n'est pas configuré est FERMÉ, pas deviné : sans base, les liens tracés n'existent
+ * pas ; sans `PLAYER_PUBLIC_URL`, aucun courriel ne part. Un refus nommé vaut mieux qu'un repli
+ * silencieux.
+ */
+export function createStandaloneContext(env?: Record<string, string | undefined>): ContextePlayer;
+
+/**
+ * Le limiteur de débit du contexte autonome, exposé pour qui compose son propre contexte.
+ *
+ * ⚠️ Fail-open, délibérément : un limiteur en panne ne doit pas empêcher un lecteur d'ouvrir son
+ * document. Il protège d'un abus, il ne garde pas une porte.
+ */
+export function creerLimites(db: BaseDeDonnees, journal: { capture(erreur: unknown, meta?: Record<string, unknown>): unknown }): Limites;