@supersoniks/concorde 5.0.5 → 5.1.0

package/src/core/components/functional/sdui/sdui.ts

@@ -1,8 +1,20 @@
 import default_library from "@supersoniks/concorde/core/components/functional/sdui/default-library.json";
 import SDUIDescriptorTransformer from "@supersoniks/concorde/core/components/functional/sdui/SDUIDescriptorTransformer";
+import { getPublisherFromPath } from "@supersoniks/concorde/core/decorators/subscriber/publisherPath";
 import {
+  createSduiPlaceholder,
+  SDUI_NODE_ID_ATTR,
+} from "@supersoniks/concorde/core/components/functional/sdui/sdui-partial";
+import {
+  formatSafeJsWarning,
+  formatSafeNodeWarning,
+  isUnsafeSduiNode,
+} from "@supersoniks/concorde/core/components/functional/sdui/sdui-safe";
+import {
+  SDUIActionDetail,
   SDUIDescriptor,
   SDUINode,
+  SDUIOp,
   SDUITransformDescription,
 } from "@supersoniks/concorde/core/components/functional/sdui/types";
 import { Fetcher, Subscriber } from "@supersoniks/concorde/mixins";
@@ -21,6 +33,10 @@ const tagName = "sonic-sdui"; // For Astro.build
  * * Le format du JSON est décrit par le type SDUIDescriptor
  * * Un attribut supplémentaire `transformation` permet de transformer le json reçu avant la génération de l'interface utilisateur<br>
  * Son format est décrit par le type SDUITransformDescription
+ * * Attribut opt-in `profile="safe"` : refuse js, markup, innerHTML, prefix et suffix (nœud ignoré + warning).
+ * * Champ de nœud opt-in `action: { name, context }` : au clic, émet `sdui-action` (bubbles + composed).
+ * * Attribut opt-in `partial` : enfants `childNodeIds` absents → placeholder léger (sinon warning + skip).
+ * * Ops incrémentales opt-in : `upsertNode` / `removeNode` / `setData` (chemin à côté du descripteur entier).
  *
  *  * Si le résultat de la requête est un objet, il est imbriqué dans un tableau pour garantir le fonctionnement.<br>
  * *
@@ -32,17 +48,57 @@ export class SonicSDUI extends Fetcher(Subscriber(LitElement)) {
     this.displayContents = true;
     this.isFetchEnabled = this.hasAttribute("fetch");
     super.connectedCallback();
+    if (this.opsDataProvider) this.bindOpsDataProvider();
   }
 
   @property() sduiKey?: string;
   @property() messagesKey?: string;
+  /**
+   * Profil de rendu opt-in. `safe` refuse js / markup / innerHTML / prefix / suffix.
+   * Sans attribut, comportement historique inchangé.
+   */
+  @property({ type: String, reflect: true }) profile?: string;
+  /**
+   * Rendu partiel opt-in : les `childNodeIds` introuvables deviennent des placeholders.
+   * Activé aussi en mode incrémental (ops étape 6).
+   */
+  @property({ type: Boolean, reflect: true }) partial = false;
+  /**
+   * DataProvider optionnel alimenté par un flux d'ops (`SDUIOp` ou `SDUIOp[]`).
+   * Chaque assignation est consommée via `applyOp`.
+   */
+  @property({ type: String }) opsDataProvider?: string;
   private sduiDescriptor: SDUIDescriptor = {};
+  private nodeIndex = new Map<string, SDUINode>();
+  /** Garde-fou cycles childNodeIds. */
+  private renderingStack = new Set<string>();
+  /** Forcé à true par les ops incrémentales. */
+  private incrementalPartial = false;
+  /** Mode ops : descripteur local cloné ; ignore les props publisher. */
+  private incrementalActive = false;
+  private opsUnsub?: () => void;
+
+  private get isSafeProfile(): boolean {
+    return this.profile === "safe";
+  }
+
+  private get isPartialMode(): boolean {
+    return this.partial || this.incrementalPartial;
+  }
 
   /**
    * On peut passer la description sous form de props, sinon il faut utiliser l'attribut fetch
    */
 
   willUpdate(changedProperties: PropertyValues): void {
+    if (changedProperties.has("opsDataProvider")) {
+      this.bindOpsDataProvider();
+    }
+    // Chemin incrémental : ne pas reconstruire depuis props (descripteur local).
+    if (this.incrementalActive) {
+      super.willUpdate(changedProperties);
+      return;
+    }
     if (this.props == null) {
       this.sduiDescriptor = {};
     }
@@ -50,13 +106,26 @@ export class SonicSDUI extends Fetcher(Subscriber(LitElement)) {
       const newSduiDescriptor = this.sduiKey
         ? (this.props as Record<string, SDUIDescriptor>)[this.sduiKey]
         : (this.props as SDUIDescriptor);
-      if (this.sduiDescriptor == newSduiDescriptor) return;
+      const profileChanged = changedProperties.has("profile");
+      const partialChanged = changedProperties.has("partial");
+      if (
+        this.sduiDescriptor == newSduiDescriptor &&
+        !profileChanged &&
+        !partialChanged
+      )
+        return;
       this.sduiDescriptor = newSduiDescriptor;
       this.updateContents();
     }
     super.willUpdate(changedProperties);
   }
 
+  disconnectedCallback(): void {
+    this.opsUnsub?.();
+    this.opsUnsub = undefined;
+    super.disconnectedCallback();
+  }
+
   /**
    * updateContents est déclenché quand les sduiDescriptor sont renseignées
    * Le contenu du composant est regénéré en fonction du descripteur fourni
@@ -69,8 +138,32 @@ export class SonicSDUI extends Fetcher(Subscriber(LitElement)) {
     this.loadAssets();
     await this.loadLibrary();
     await this.transformSDUIDescriptor();
+    this.rebuildNodeIndex();
     this.parseRootNodes();
   }
+
+  /** Index `nodeId` → nœud (nodeById + parcours du tree / library). */
+  private rebuildNodeIndex() {
+    this.nodeIndex.clear();
+    const visit = (node: SDUINode) => {
+      if (node.nodeId) this.nodeIndex.set(node.nodeId, node);
+      node.nodes?.forEach(visit);
+    };
+    if (this.sduiDescriptor.nodeById) {
+      for (const id of Object.keys(this.sduiDescriptor.nodeById)) {
+        const n = this.sduiDescriptor.nodeById[id];
+        if (!n.nodeId) n.nodeId = id;
+        this.nodeIndex.set(id, n);
+        visit(n);
+      }
+    }
+    this.sduiDescriptor.nodes?.forEach(visit);
+    if (this.sduiDescriptor.library) {
+      for (const key of Object.keys(this.sduiDescriptor.library)) {
+        visit(this.sduiDescriptor.library[key]);
+      }
+    }
+  }
   /**
    * Suppressiond du contenu du composant avant le génération de la nouvelle ui
    */
@@ -86,8 +179,12 @@ export class SonicSDUI extends Fetcher(Subscriber(LitElement)) {
    **/
   private loadAssets() {
     if (!this.sduiDescriptor) return;
-    if (this.sduiDescriptor.js) {
-      for (const src of this.sduiDescriptor.js) HTML.loadJS(src);
+    if (this.sduiDescriptor.js?.length) {
+      if (this.isSafeProfile) {
+        console.warn(formatSafeJsWarning(this.sduiDescriptor.js));
+      } else {
+        for (const src of this.sduiDescriptor.js) HTML.loadJS(src);
+      }
     }
     if (this.sduiDescriptor.css) {
       for (const src of this.sduiDescriptor.css) HTML.loadCSS(src);
@@ -128,24 +225,48 @@ export class SonicSDUI extends Fetcher(Subscriber(LitElement)) {
       messageProvider.attributes = { subDataProvider: this.messagesKey };
     }
     nodes.push(messageProvider);
-    nodes.forEach((node) => this.appendChild(this.parseChild(node)));
+    nodes.forEach((node, i) => {
+      const el = this.parseChild(node, `nodes[${i}]`);
+      if (el) this.appendChild(el);
+    });
   }
   /**
    * On parse un noeud ce qui crée un éléments graphique et ses enfants par recursivité via `handleChildNodes`
+   * En profil safe, un nœud avec markup/innerHTML/prefix/suffix est ignoré (null).
    */
-  private parseChild(node: SDUINode) {
-    const tagName = node.tagName || "div";
-    let { element, contentElement } = this.handleLibrary(node, tagName);
-    this.handleAttributes(node, element);
-    element = this.handleMarkup(node, element);
-    if (!contentElement) contentElement = element;
-    this.handleChildNodes(node, contentElement, element);
-    this.handleInnerHTML(node, contentElement);
-    if (node.prefix || node.suffix) {
-      const container = this.handlePrefixSuffix(node, element);
-      return container;
+  private parseChild(node: SDUINode, path = "node"): HTMLElement | null {
+    if (this.isSafeProfile && isUnsafeSduiNode(node)) {
+      console.warn(formatSafeNodeWarning(path, node));
+      return null;
+    }
+    if (node.nodeId && this.renderingStack.has(node.nodeId)) {
+      console.warn(
+        `sonic-sdui : cycle détecté sur nodeId="${node.nodeId}" (${path})`
+      );
+      return this.isPartialMode ? createSduiPlaceholder(node.nodeId) : null;
+    }
+    if (node.nodeId) this.renderingStack.add(node.nodeId);
+    try {
+      const tagName = node.tagName || "div";
+      let { element, contentElement } = this.handleLibrary(node, tagName, path);
+      if (!element) return null;
+      this.handleAttributes(node, element);
+      element = this.handleMarkup(node, element);
+      if (!contentElement) contentElement = element;
+      this.handleChildNodes(node, contentElement, element, path);
+      this.handleTextContent(node, contentElement);
+      this.handleInnerHTML(node, contentElement);
+      let host = element;
+      if (node.prefix || node.suffix) {
+        host = this.handlePrefixSuffix(node, element);
+      }
+      // Après prefix/suffix : innerHTML recrée le DOM, donc binder l'action sur l'hôte final.
+      this.bindAction(node, host);
+      if (node.nodeId) host.setAttribute(SDUI_NODE_ID_ATTR, node.nodeId);
+      return host;
+    } finally {
+      if (node.nodeId) this.renderingStack.delete(node.nodeId);
     }
-    return element;
   }
   /**
    * Si le noeud courant a des propriétés prefix et ou suffix il est entouré des markups fournis dans ces sduiDescriptor.
@@ -158,35 +279,100 @@ export class SonicSDUI extends Fetcher(Subscriber(LitElement)) {
     container.style.display = "contents";
     return container;
   }
+  /**
+   * Branche un clic → CustomEvent `sdui-action` si le nœud déclare `action.name`.
+   * bubbles + composed : un ancêtre (shell, page) peut écouter sans se coller au nœud.
+   */
+  private bindAction(node: SDUINode, element: HTMLElement) {
+    const action = node.action;
+    if (!action?.name) return;
+    element.addEventListener("click", () => {
+      const detail: SDUIActionDetail = {
+        name: action.name,
+        context: action.context ?? {},
+        sourceNodeId: node.nodeId,
+      };
+      this.dispatchEvent(
+        new CustomEvent<SDUIActionDetail>("sdui-action", {
+          detail,
+          bubbles: true,
+          composed: true,
+        })
+      );
+    });
+  }
   /**
    * Création des enfants du noeud courant
    * Si l'enfant à un attribut parentElementSelector, il est ajouté dans le noeud correspondant au sélecteur css associé et non pas dans l'élément directement.
+   * `childNodeIds` résout des nœuds du registre ; absents → placeholder (partial) ou skip.
    */
   private handleChildNodes(
     node: SDUINode,
     contentElement: HTMLElement,
-    element: HTMLElement
+    element: HTMLElement,
+    path: string
   ) {
     if (node.nodes) {
       const children: Array<SDUINode> = node.nodes;
-      for (const child of children) {
-        const childElement = this.parseChild(child);
-        let nodeToAppendOn = contentElement;
-        if (child.parentElementSelector) {
-          nodeToAppendOn =
-            element.querySelector(child.parentElementSelector) ||
-            contentElement;
+      for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const childElement = this.parseChild(child, `${path}.nodes[${i}]`);
+        if (!childElement) continue;
+        this.appendChildElement(child, childElement, contentElement, element);
+      }
+    }
+    if (node.childNodeIds?.length) {
+      for (const childId of node.childNodeIds) {
+        const child = this.nodeIndex.get(childId);
+        if (child) {
+          const childElement = this.parseChild(
+            child,
+            `${path}.childNodeIds[${childId}]`
+          );
+          if (childElement) {
+            this.appendChildElement(
+              child,
+              childElement,
+              contentElement,
+              element
+            );
+          }
+          continue;
+        }
+        if (this.isPartialMode) {
+          this.appendToTarget(
+            contentElement,
+            createSduiPlaceholder(childId)
+          );
+        } else {
+          console.warn(
+            `sonic-sdui : childNodeId "${childId}" introuvable (${path}) — ignoré (activez partial pour un placeholder)`
+          );
         }
-        if (nodeToAppendOn.shadowRoot)
-          nodeToAppendOn.shadowRoot.appendChild(childElement);
-        else if (nodeToAppendOn.tagName.toLocaleLowerCase() == "template") {
-          const template: HTMLTemplateElement =
-            nodeToAppendOn as HTMLTemplateElement;
-          template.content.appendChild(childElement);
-        } else nodeToAppendOn.appendChild(childElement);
       }
     }
   }
+
+  private appendChildElement(
+    child: SDUINode,
+    childElement: HTMLElement,
+    contentElement: HTMLElement,
+    element: HTMLElement
+  ) {
+    let nodeToAppendOn = contentElement;
+    if (child.parentElementSelector) {
+      nodeToAppendOn =
+        element.querySelector(child.parentElementSelector) || contentElement;
+    }
+    this.appendToTarget(nodeToAppendOn, childElement);
+  }
+
+  private appendToTarget(target: HTMLElement, childElement: HTMLElement) {
+    if (target.shadowRoot) target.shadowRoot.appendChild(childElement);
+    else if (target.tagName.toLocaleLowerCase() == "template") {
+      (target as HTMLTemplateElement).content.appendChild(childElement);
+    } else target.appendChild(childElement);
+  }
   /**
    * Gestion de librarie :
    * * Si l'élément référence un élément de la librairie, on se sert de cet élément comme model pour créer le composant graphique.
@@ -194,13 +380,25 @@ export class SonicSDUI extends Fetcher(Subscriber(LitElement)) {
    * * Si contentElementSelector est definit, alors contentElement correspond à l'élément obtenu par selection css d'après la valeurs de contentElementSelector
    * * Les éléments enfants seront ensuite ajoutés dans contentElement
    */
-  private handleLibrary(node: SDUINode, tagName: string) {
-    let element: HTMLElement;
+  private handleLibrary(
+    node: SDUINode,
+    tagName: string,
+    path: string
+  ): { element: HTMLElement | null; contentElement: HTMLElement | undefined } {
+    let element: HTMLElement | null;
     let contentElement: HTMLElement | undefined;
     if (node.libraryKey && this.sduiDescriptor.library) {
+      const libPath = `library.${node.libraryKey}`;
       element = this.parseChild(
-        this.sduiDescriptor.library[node.libraryKey] || { tagName: "div" }
+        this.sduiDescriptor.library[node.libraryKey] || { tagName: "div" },
+        libPath
       );
+      if (!element) {
+        console.warn(
+          `sonic-sdui (profile="safe") : nœud ignoré (${path}) — modèle libraryKey="${node.libraryKey}" refusé`
+        );
+        return { element: null, contentElement: undefined };
+      }
       const selector = (this.sduiDescriptor.library[node.libraryKey] || {})
         .contentElementSelector;
       if (selector)
@@ -233,6 +431,19 @@ export class SonicSDUI extends Fetcher(Subscriber(LitElement)) {
     return element;
   }
 
+  /**
+   * Texte plain via textContent (pas de parse HTML). Autorisé en profile="safe".
+   * Ignoré si le nœud a déjà des enfants déclarés dans `nodes` (évite d'effacer le sous-arbre).
+   */
+  private handleTextContent(
+    node: SDUINode,
+    contentElement: HTMLElement | undefined
+  ) {
+    if (node.textContent == null || !contentElement) return;
+    if (node.nodes?.length || node.childNodeIds?.length) return;
+    contentElement.textContent = node.textContent;
+  }
+
   /**
    * si le noeud à une propriété innerHTML, on l'ajout ay innerHTML de l'élément html en cours de création
    */
@@ -252,4 +463,201 @@ export class SonicSDUI extends Fetcher(Subscriber(LitElement)) {
       contentElement.innerHTML += node.innerHTML;
     }
   }
+
+  // ——— Ops incrémentales (chemin à côté du descripteur entier) ———
+
+  /**
+   * Ajoute ou remplace un nœud par `nodeId` (requis).
+   * Rendu chirurgical : les frères DOM sont préservés.
+   */
+  upsertNode(node: SDUINode, parentId?: string, index?: number): void {
+    if (!node.nodeId) {
+      console.warn('sonic-sdui.upsertNode : "nodeId" est requis');
+      return;
+    }
+    this.beginIncremental();
+    const id = node.nodeId;
+    if (!this.sduiDescriptor.nodeById) this.sduiDescriptor.nodeById = {};
+    this.sduiDescriptor.nodeById[id] = node;
+    this.nodeIndex.set(id, node);
+
+    if (parentId) {
+      let parent =
+        this.nodeIndex.get(parentId) || this.sduiDescriptor.nodeById[parentId];
+      if (!parent) {
+        parent = {
+          nodeId: parentId,
+          tagName: "div",
+          childNodeIds: [],
+        };
+        this.sduiDescriptor.nodeById[parentId] = parent;
+        this.nodeIndex.set(parentId, parent);
+        if (!this.sduiDescriptor.nodes) this.sduiDescriptor.nodes = [];
+        if (!this.sduiDescriptor.nodes.some((n) => n.nodeId === parentId)) {
+          this.sduiDescriptor.nodes.push(parent);
+        }
+      }
+      if (!parent.childNodeIds) parent.childNodeIds = [];
+      const prev = parent.childNodeIds.indexOf(id);
+      if (prev >= 0) parent.childNodeIds.splice(prev, 1);
+      const at =
+        index != null
+          ? Math.max(0, Math.min(index, parent.childNodeIds.length))
+          : parent.childNodeIds.length;
+      parent.childNodeIds.splice(at, 0, id);
+    } else {
+      if (!this.sduiDescriptor.nodes) this.sduiDescriptor.nodes = [];
+      const roots = this.sduiDescriptor.nodes;
+      const ri = roots.findIndex((n) => n.nodeId === id);
+      if (ri >= 0) roots[ri] = node;
+      else if (index != null) {
+        roots.splice(Math.max(0, Math.min(index, roots.length)), 0, node);
+      } else roots.push(node);
+    }
+
+    this.rebuildNodeIndex();
+    this.domUpsertNode(node, parentId, index);
+  }
+
+  /** Supprime un nœud du registre et du DOM (frères préservés). */
+  removeNode(nodeId: string): void {
+    this.beginIncremental();
+    delete this.sduiDescriptor.nodeById?.[nodeId];
+    this.nodeIndex.delete(nodeId);
+    if (this.sduiDescriptor.nodes) {
+      this.sduiDescriptor.nodes = this.sduiDescriptor.nodes.filter(
+        (n) => n.nodeId !== nodeId
+      );
+    }
+    if (this.sduiDescriptor.nodeById) {
+      for (const n of Object.values(this.sduiDescriptor.nodeById)) {
+        if (n.childNodeIds) {
+          n.childNodeIds = n.childNodeIds.filter((id) => id !== nodeId);
+        }
+      }
+    }
+    this.findDomNode(nodeId)?.remove();
+  }
+
+  /**
+   * Met à jour une donnée publisher par chemin (`provider.cle.imbrique` ou relatif
+   * au `dataProvider` du composant si le premier segment ne matche pas).
+   */
+  setData(path: string, value: unknown): void {
+    const direct = getPublisherFromPath(path);
+    if (direct) {
+      direct.set(value);
+      return;
+    }
+    if (this.dataProvider) {
+      const nested = getPublisherFromPath(`${this.dataProvider}.${path}`);
+      if (nested) {
+        nested.set(value);
+        return;
+      }
+    }
+    console.warn(`sonic-sdui.setData : chemin introuvable "${path}"`);
+  }
+
+  /** Applique une op (méthode ou entrée de flux `opsDataProvider`). */
+  applyOp(op: SDUIOp): void {
+    switch (op.op) {
+      case "upsertNode":
+        this.upsertNode(op.node, op.parentId, op.index);
+        break;
+      case "removeNode":
+        this.removeNode(op.nodeId);
+        break;
+      case "setData":
+        this.setData(op.path, op.value);
+        break;
+      default:
+        console.warn("sonic-sdui.applyOp : op inconnue", op);
+    }
+  }
+
+  /** Quitte le mode incrémental ; le prochain `props` refait un rendu complet. */
+  endIncremental(): void {
+    this.incrementalActive = false;
+    this.incrementalPartial = false;
+  }
+
+  private beginIncremental() {
+    if (this.incrementalActive) return;
+    this.sduiDescriptor = structuredClone(this.sduiDescriptor || {});
+    if (!this.sduiDescriptor.nodeById) this.sduiDescriptor.nodeById = {};
+    if (!this.sduiDescriptor.nodes) this.sduiDescriptor.nodes = [];
+    // Fusion library défaut si absente (évite un rebuild complet)
+    if (!this.sduiDescriptor.library) {
+      const library: Record<string, SDUINode> = {};
+      Object.assign(library, default_library);
+      this.sduiDescriptor.library = library;
+    }
+    this.incrementalActive = true;
+    this.incrementalPartial = true;
+    this.rebuildNodeIndex();
+  }
+
+  private findDomNode(nodeId: string): HTMLElement | null {
+    const escaped =
+      typeof CSS !== "undefined" && CSS.escape
+        ? CSS.escape(nodeId)
+        : nodeId.replace(/"/g, '\\"');
+    // Placeholders portent aussi SDUI_NODE_ID_ATTR
+    return this.querySelector(
+      `[${SDUI_NODE_ID_ATTR}="${escaped}"]`
+    ) as HTMLElement | null;
+  }
+
+  private domUpsertNode(
+    node: SDUINode,
+    parentId?: string,
+    index?: number
+  ) {
+    const rendered = this.parseChild(node, `upsert:${node.nodeId}`);
+    if (!rendered) return;
+    const existing = this.findDomNode(node.nodeId!);
+    if (existing && existing !== rendered) {
+      existing.replaceWith(rendered);
+      return;
+    }
+    if (existing === rendered) return;
+
+    if (parentId) {
+      const parentEl = this.findDomNode(parentId);
+      if (parentEl) {
+        const kids = Array.from(parentEl.children);
+        if (index != null && index < kids.length) {
+          parentEl.insertBefore(rendered, kids[index]);
+        } else parentEl.appendChild(rendered);
+        return;
+      }
+    }
+
+    const toast = this.querySelector("sonic-toast-message-subscriber");
+    if (toast) this.insertBefore(rendered, toast);
+    else this.appendChild(rendered);
+  }
+
+  private bindOpsDataProvider() {
+    this.opsUnsub?.();
+    this.opsUnsub = undefined;
+    const id = this.opsDataProvider;
+    if (!id) return;
+    const pub = getPublisherFromPath(id);
+    if (!pub) return;
+    const handler = (payload: unknown) => {
+      if (payload == null) return;
+      const list = Array.isArray(payload) ? payload : [payload];
+      for (const item of list) {
+        if (item && typeof item === "object" && "op" in (item as object)) {
+          this.applyOp(item as SDUIOp);
+        }
+      }
+    };
+    pub.onAssign(handler);
+    this.opsUnsub = () => pub.offAssign(handler);
+    const current = pub.get();
+    if (current != null) handler(current);
+  }
 }

package/src/core/components/functional/sdui/types.ts

@@ -3,18 +3,56 @@ export type SDUIDescriptor = {
   css?: Array<string>;
   library?: Record<string, SDUINode>;
   nodes?: Array<SDUINode>;
+  /**
+   * Registre plat de nœuds indexés par `nodeId` (opt-in).
+   * Permet de référencer des enfants via `childNodeIds` avant qu'ils n'arrivent
+   * (rendu partiel / ops incrémentales).
+   */
+  nodeById?: Record<string, SDUINode>;
 };
+/** Action déclarative sur un nœud — émet l'événement `sdui-action` au clic. */
+export type SDUINodeAction = {
+  name: string;
+  context?: Record<string, unknown>;
+};
+
+/** Detail de l'événement CustomEvent `sdui-action`. */
+export type SDUIActionDetail = {
+  name: string;
+  context: Record<string, unknown>;
+  /** Renseigné plus tard si le nœud porte un `nodeId` (ops incrémentales). */
+  sourceNodeId?: string;
+};
+
 export type SDUINode = {
   libraryKey?: string;
   markup?: string;
   tagName?: string;
   attributes?: Record<string, string>;
   nodes?: Array<SDUINode>;
+  /** Texte plain (pas de parse HTML). Autorisé en profile="safe". Ignoré si `nodes` est non vide. */
+  textContent?: string;
   innerHTML?: string;
   prefix?: string;
   suffix?: string;
   contentElementSelector?: string;
   parentElementSelector?: string;
+  /**
+   * Action déclarative opt-in. Au clic, émet `sdui-action`
+   * (bubbles + composed) avec `{ name, context, sourceNodeId? }`.
+   * N'interfère pas avec sonic-submit / POST formulaire.
+   */
+  action?: SDUINodeAction;
+  /**
+   * Identifiant logique de nœud (pas l'attribut DOM `id`).
+   * Utilisé dans `sdui-action.detail.sourceNodeId` ; ops incrémentales plus tard.
+   */
+  nodeId?: string;
+  /**
+   * Enfants référencés par `nodeId` (registre `descriptor.nodeById` + index du tree).
+   * Si un id est absent : placeholder en mode partial, sinon warning + skip.
+   */
+  childNodeIds?: string[];
 };
 
 export type SDUITransformDescription = {
@@ -32,3 +70,14 @@ export type SDUITransformAction = {
   ui?: SDUINode;
 };
 export type SDUITransformList = Array<{parent: SDUINode; child: SDUINode; index: number}>;
+
+/** Opération incrémentale (méthodes publiques ou flux opsDataProvider). */
+export type SDUIOp =
+  | {
+      op: "upsertNode";
+      node: SDUINode;
+      parentId?: string;
+      index?: number;
+    }
+  | { op: "removeNode"; nodeId: string }
+  | { op: "setData"; path: string; value: unknown };