@widgetic/editor 4.0.10 → 4.1.0

package/dist/components/ic/VectorInputController.svelte

@@ -55,6 +55,11 @@
   import { SearchInput } from '@widgetic/design-system/components';
   import CategoryTabs from './shared/CategoryTabs.svelte';
   import { RecentItemsSection, ItemGrid } from './shared';
+  import { useEditorLanguage } from '../../i18n/language';
+  import { categoryLabel } from '../../i18n/labels';
+
+  // The words of the editor in the language of the page.
+  const { t } = useEditorLanguage();
   
   // Utils imports
   import { 
@@ -66,6 +71,9 @@
   } from '../../utils/vectorUtils';
   import type { VectorData } from '../../utils/VectorManager';
   import VectorManager from '../../utils/VectorManager';
+  import { escapeHtml } from '../../utils/htmlSafety';
+  import { listenForScroll, queryInTreeOf } from '../../utils/shadowDom';
+  import { readEditorStorageValue, writeEditorStorageValue } from '../../utils/editorStorage';
   
   // Constants
   const VECTOR_FILTER_KEY = (id: string) => `vector-specific-filter-state-${id}`;
@@ -109,6 +117,8 @@
 
   // Vector loading optimization
   let vectorListContainer: HTMLElement;
+  // The control's own element: it says which tree (the page or a module's shadow root) to listen for scrolling in
+  let controllerElement: HTMLDivElement | undefined;
   let vectorObserver = new IntersectionObserver(() => {});
   
   // Initialize VectorManager instance
@@ -175,6 +185,15 @@
     `;
   }
 
+  /**
+   * The sticky header of the vector list. It is looked up in the tree the list lives in (inside a module that is a
+   * shadow root, which `document.querySelector` cannot see into), and the id is escaped so that one with dots or
+   * brackets in it is found too.
+   */
+  function findStickyHeader(): Element | null {
+    return queryInTreeOf(vectorListContainer, `#${CSS.escape(`vector-header-${controllerId}`)}`);
+  }
+
   // Function to update scroll state
   function updateScrollState() {
     if (vectorListContainer) {
@@ -183,7 +202,7 @@
       
       // If we're transitioning from scrolled to not scrolled, remove transition
       if (wasScrolled && !isScrolled) {
-        const stickyHeader = document.querySelector(`#vector-header-${controllerId}`);
+        const stickyHeader = findStickyHeader();
         if (stickyHeader) {
           stickyHeader.classList.remove('transition-border');
           // Force a reflow to ensure the transition class removal takes effect
@@ -191,7 +210,7 @@
         }
       } else if (!wasScrolled && isScrolled) {
         // Add transition class when starting to scroll
-        const stickyHeader = document.querySelector(`#vector-header-${controllerId}`);
+        const stickyHeader = findStickyHeader();
         if (stickyHeader) {
           stickyHeader.classList.add('transition-border');
         }
@@ -314,31 +333,14 @@
       await handleSearch(event);
     }, 300); // 300ms debounce time
     
-    // Setup global error handler for SVG loading errors
-    const vectorErrorHandler = (event: Event) => {
-      if (event instanceof CustomEvent && event.detail) {
-        const vectorName = event.detail;
-        // Check if we can get the vector URL from allVectors
-        const vectorData = allVectors.find(v => v.name === vectorName);
-        const vectorUrl = vectorData?.url || 'unknown';
-        
-        console.error(`❌ [VectorInput] Failed to load SVG: "${vectorName}" from URL: ${vectorUrl}`);
-        svgLoadErrors.set(vectorName, true);
-        // Force component update
-        svgLoadErrors = new Map(svgLoadErrors);
-      }
-    };
-    
-    // Add the event listener
-    document.addEventListener('vector-load-error', vectorErrorHandler);
-
-    // Store the handler reference for cleanup in onDestroy
-    (window as any)['vectorErrorHandler'] = vectorErrorHandler;
+    // SVG loading errors are noticed by the watchVectorImageErrors action on the list of pictures. They used to be
+    // announced on `document` by an inline onerror handler and caught here; with the editor inside a partner's page
+    // that was an event on the partner's document and a handler stored on the partner's `window`.
 
     try {
       if (browser) {
         // Load saved filter
-        const savedFilter = localStorage.getItem(VECTOR_FILTER_KEY(controllerId));
+        const savedFilter = readEditorStorageValue(VECTOR_FILTER_KEY(controllerId));
         if (savedFilter) {
           currentFilter = savedFilter as FilterType;
         }
@@ -493,7 +495,7 @@
         lastActiveFilter = currentFilter;
         currentFilter = 'All'; // Reset to All when starting a search
         if (browser) {
-          localStorage.setItem(VECTOR_FILTER_KEY(controllerId), 'All');
+          writeEditorStorageValue(VECTOR_FILTER_KEY(controllerId), 'All');
         }
       }
       
@@ -970,16 +972,7 @@
   }
 
   onDestroy(() => {
-    window.removeEventListener('scroll', handleGlobalScroll, true);
-    window.removeEventListener('touchstart', () => {});
-    window.removeEventListener('touchmove', () => {});
-    
-    // Remove vector load error listener using the stored reference
-    const vectorErrorHandler = (window as any)['vectorErrorHandler'];
-    if (vectorErrorHandler) {
-      document.removeEventListener('vector-load-error', vectorErrorHandler);
-      delete (window as any)['vectorErrorHandler'];
-    }
+    stopListeningForScroll();
     
     if (vectorObserver) {
       vectorObserver.disconnect();
@@ -1030,7 +1023,7 @@
       lastActiveFilter = filter; // Remember the last active filter
       
       if (browser) {
-        localStorage.setItem(VECTOR_FILTER_KEY(controllerId), filter);
+        writeEditorStorageValue(VECTOR_FILTER_KEY(controllerId), filter);
       }
       
       if (vectorManagerInstance) {
@@ -1104,25 +1097,26 @@
   }
 
   /**
-   * Highlights search term matches in vector names
+   * Highlights search term matches in vector names.
+   * The result is meant for {@html}, so every piece of the name is escaped as it is put in.
    */
   function highlightMatch(name: string, term: string) {
-    if (!term) return name;
+    if (!term) return escapeHtml(name);
     const nameLower = name.toLowerCase();
     const termLower = term.toLowerCase().trim();
     
     // If the name contains the search term, highlight that part in blue
     if (termLower && nameLower.includes(termLower)) {
       const index = nameLower.indexOf(termLower);
-      const beforeMatch = name.slice(0, index);
-      const match = name.slice(index, index + termLower.length);
-      const afterMatch = name.slice(index + termLower.length);
+      const beforeMatch = escapeHtml(name.slice(0, index));
+      const match = escapeHtml(name.slice(index, index + termLower.length));
+      const afterMatch = escapeHtml(name.slice(index + termLower.length));
       
       return `<span style="color: hsl(var(--grey7))">${beforeMatch}<span style="color: #45BCFE">${match}</span>${afterMatch}</span>`;
     }
     
     // Default case - just return the name in grey7 color
-    return `<span style="color: hsl(var(--grey7))">${name}</span>`;
+    return `<span style="color: hsl(var(--grey7))">${escapeHtml(name)}</span>`;
   }
   
 
@@ -1173,15 +1167,16 @@
     }
   }
 
-  // Add scroll listener with passive option
-  window.addEventListener('scroll', handleGlobalScroll, {
-    capture: true,
-    passive: true
+  // Add scroll listener with passive option. It listens to the page and, inside a module, to the module's own panels
+  // (a scroll never leaves a shadow root, so a listener on the window alone does not hear about those).
+  let stopListeningForScroll: () => void = () => {};
+  onMount(() => {
+    stopListeningForScroll = listenForScroll(controllerElement, handleGlobalScroll, { passive: true });
   });
 
-  // Add touch listeners with passive option
-  window.addEventListener('touchstart', () => {}, { passive: true });
-  window.addEventListener('touchmove', () => {}, { passive: true });
+  // (Two touchstart/touchmove listeners that did nothing used to be added to the window here, and could never be
+  // removed: each input left two more on the customer's page every time it was shown. They did nothing, so they are
+  // gone.)
 
   // Add to VectorInputController.svelte
   function handleToggle() {
@@ -1299,6 +1294,37 @@
     removeVector(vector.name);
   }
 
+  /**
+   * Svelte action for the list that holds the vector pictures: notices a picture that does not load and shows the
+   * "Failed to load" state for that vector. `error` events do not bubble, so it listens in the capture phase; a
+   * picture is found by its data-vector-name (see renderVectorItem). It replaces an inline onerror attribute that
+   * reported through `document`, which is the partner's page when the editor runs inside one.
+   */
+  function watchVectorImageErrors(node: HTMLElement) {
+    const onImageError = (event: Event) => {
+      const image = event.target;
+      if (!(image instanceof HTMLImageElement)) return;
+      const vectorName = image.dataset.vectorName;
+      if (!vectorName) return;
+      image.style.display = 'none';
+      // Reported once per vector, however many pictures of it are on screen.
+      if (hasSvgLoadError(vectorName)) return;
+      const vectorData = allVectors.find(vector => vector.name === vectorName);
+      console.error(`❌ [VectorInput] Failed to load SVG: "${vectorName}" from URL: ${vectorData?.url || image.src || 'unknown'}`);
+      svgLoadErrors.set(vectorName, true);
+      // Force component update
+      svgLoadErrors = new Map(svgLoadErrors);
+    };
+
+    node.addEventListener('error', onImageError, true);
+
+    return {
+      destroy() {
+        node.removeEventListener('error', onImageError, true);
+      }
+    };
+  }
+
   // Create a Svelte action to handle image error events
   function handleImageError(node: HTMLElement, vectorName: string) {
     const errorHandler = (event: Event) => {
@@ -1345,15 +1371,19 @@
       };
     }
         
+    // The result is used as HTML by RecentItemsSection and ItemGrid: the name and the address of a vector (a custom
+    // one is named after the person's own file) are escaped as they are put in. A picture that does not load is
+    // noticed by watchVectorImageErrors, which finds it by data-vector-name; an inline onerror="..." would not run
+    // under a strict Content-Security-Policy.
     return {
       html: `
         <div class="flex items-center justify-center w-full h-full vector-img-container">
           <img 
-            src="${vector.url}" 
-            alt="${vector.name}"
+            src="${escapeHtml(vector.url)}" 
+            alt="${escapeHtml(vector.name)}"
+            data-vector-name="${escapeHtml(vector.name)}"
             class="w-[72px] h-[72px] object-contain"
             draggable="false"
-            onerror="this.style.display='none'; document.dispatchEvent(new CustomEvent('vector-load-error', {detail: this.alt, bubbles: true})); console.error('❌ [VectorInput] Vector failed to load:', this.alt, 'URL:', this.src);"
           />
         </div>
       `
@@ -1399,7 +1429,7 @@
       lastActiveFilter = currentFilter;
       currentFilter = 'All'; // Reset to All when starting a search
       if (browser) {
-        localStorage.setItem(VECTOR_FILTER_KEY(controllerId), 'All');
+        writeEditorStorageValue(VECTOR_FILTER_KEY(controllerId), 'All');
       }
     }
     
@@ -1472,16 +1502,16 @@
   }
 </script>
 
-<div class="flex flex-col gap-2 widgetic-colors">
+<div bind:this={controllerElement} class="flex flex-col gap-2 widgetic-colors">
   <div class="flex items-center w-full relative">
-    <div class="w-[185px] flex-shrink-0 ml-auto">
+    <div class="w-[185px] flex-shrink-0 ms-auto">
       <InputControllerHeader 
         label={label}
         helpText={description}
       />
     </div>
     
-    <div class="absolute right-0">
+    <div class="absolute end-0">
       <div 
         class="h-[48px] w-[185px] rounded-large border border-grey2 flex items-center bg-grey1 transition-colors duration-200 hover:border-forest-green"
         onfocusin={onFocus}
@@ -1527,7 +1557,7 @@
           }}
         >
           <Popover.Trigger 
-            class="w-full h-full flex items-center border-0 bg-transparent hover:bg-transparent focus:bg-transparent pl-3 pr-[16px] group"
+            class="w-full h-full flex items-center border-0 bg-transparent hover:bg-transparent focus:bg-transparent ps-3 pe-[16px] group"
             onclick={handleButtonClick}
             onkeydown={handleKeyDown}
             onmouseenter={() => {
@@ -1552,8 +1582,8 @@
                       <path d="M12 17h.01"></path>
                     </svg>
                   </div>
-                  <span class="truncate text-left capitalize subtext text-grey7">
-                    {value?.name || "Select vector..."}
+                  <span class="truncate text-start capitalize subtext text-grey7">
+                    {value?.name || $t('editor.vector.select')}
                   </span>
                 {:else}
                   <!-- Use a simple img tag with Svelte action for error handling -->
@@ -1563,13 +1593,13 @@
                     class="w-5 h-5 object-contain"
                     use:handleImageError={value.name}
                   />
-                  <span class="truncate text-left capitalize subtext text-grey7">
-                    {value?.name || "Select vector..."}
+                  <span class="truncate text-start capitalize subtext text-grey7">
+                    {value?.name || $t('editor.vector.select')}
                   </span>
                 {/if}
               {:else}
-                <span class="truncate text-left subtext text-grey7">
-                  Select vector...
+                <span class="truncate text-start subtext text-grey7">
+                  {$t('editor.vector.select')}
                 </span>
               {/if}
             </div>
@@ -1580,10 +1610,10 @@
             <div class="flex flex-col h-full vector-popover-content">
               <!-- Title and upload icon -->
               <div class="relative pt-6 pb-[8px] px-4">
-                <div class="h5 text-grey7 widgetic-colors">Vectors</div>
+                <div class="h5 text-grey7 widgetic-colors">{$t('editor.vector.title')}</div>
                 <button 
                   type="button" 
-                  class="absolute right-6 top-[26px] bg-transparent border-0 cursor-pointer p-0 rounded-full hover:bg-grey3 transition-all duration-300"
+                  class="absolute end-6 top-[26px] bg-transparent border-0 cursor-pointer p-0 rounded-full hover:bg-grey3 transition-all duration-300"
                   onclick={() => {
                     try {
                       openFileBrowser();
@@ -1603,7 +1633,7 @@
               <!-- Search input -->
               <div class="relative px-4">
                 <SearchInput
-                  placeholder="Search vectors..."
+                  placeholder={$t('editor.vector.search')}
                   bind:value={searchTerm}
                   onInput={(e: Event) => {
                     // Use debounced search for better performance
@@ -1617,7 +1647,7 @@
                     // Restore the previous filter when clearing search
                     currentFilter = lastActiveFilter;
                     if (browser) {
-                      localStorage.setItem(VECTOR_FILTER_KEY(controllerId), lastActiveFilter);
+                      writeEditorStorageValue(VECTOR_FILTER_KEY(controllerId), lastActiveFilter);
                     }
                     
                     // Reset batch index to start fresh
@@ -1682,6 +1712,7 @@
                     categories={filterOptions}
                     activeCategory={currentFilter}
                     onCategorySelect={handleFilterChange}
+                    getCategoryLabel={(category) => categoryLabel(category, $t)}
                     filterVisible={!searchTerm}
                   />
                 </div>
@@ -1691,6 +1722,7 @@
               <div 
                 class="flex-1 {filteredVectors.length > 0 ? 'overflow-y-auto' : 'overflow-hidden'} min-h-0 vector-list-container"
                 bind:this={vectorListContainer}
+                use:watchVectorImageErrors
                 onscroll={(e: Event) => {
                   e.stopPropagation();
                   handleVectorListScroll(e);
@@ -1698,14 +1730,13 @@
                 }}
                 id={`vector-list-${controllerId}`}
                 role="listbox"
-                aria-label="Vector list"
+                aria-label={$t('editor.vector.list')}
               >
                 <div class="space-y-0">
                   <!-- Recently used section - only show when not searching -->
                   {#if recentVectors.length > 0 && !searchTerm}
                     <RecentItemsSection
                       recentItems={recentVectors}
-                      title="Recently used"
                       onItemSelect={handleVectorSelect}
                       onItemDelete={handleVectorDelete}
                       isItemSelected={isVectorSelected}
@@ -1724,7 +1755,7 @@
                     {#if filteredVectors.length > 0}
                       <div id="vector-header-{controllerId}" class="sticky top-0 -mt-2 bg-white z-10 pt-2 {isScrolled ? 'border-b border-grey2' : 'border-b border-transparent'} transition-border">
                         <h3 class="subtext text-grey7 px-4 pb-2">
-                          {searchTerm ? 'Search results' : 'More'}
+                          {searchTerm ? $t('editor.list.searchResults') : $t('editor.list.more')}
                         </h3>
                       </div>
                     {/if}
@@ -1732,7 +1763,7 @@
                     {#if filteredVectors.length === 0}
                       <div class="empty-state-wrapper">
                         <EmptyState 
-                          message={searchTerm ? 'No vectors found' : 'No vectors available'} 
+                          message={searchTerm ? $t('editor.vector.noneFound') : $t('editor.vector.noneAvailable')} 
                           height="auto"
                         />
                       </div>

package/dist/components/ic/shared/ItemGrid.svelte

@@ -8,9 +8,17 @@
  * - Handles item selection
  * - Supports custom item rendering
  * - Optimized with intersection observer
+ *
+ * `renderItem` may return a plain string (shown as text) or `{ html }`. The `html` is put on the page as it is, so the
+ * function that makes it must escape everything that comes from outside (names, addresses): see escapeHtml.
  -->
 <script lang="ts">
   import { Check } from '@widgetic/design-system/icons';
+  import { escapeHtml } from '../../../utils/htmlSafety';
+  import { useEditorLanguage } from '../../../i18n/language';
+
+  // The words of the editor in the language of the page.
+  const { t } = useEditorLanguage();
   
   export let items: any[] = [];
   export let containerRef: (node: HTMLElement) => void;
@@ -41,7 +49,7 @@
   function renderContent(item: any) {
     const rendered = renderItem(item);
     if (typeof rendered === 'string') {
-      return `<span>${rendered}</span>`;
+      return `<span>${escapeHtml(rendered)}</span>`;
     }
     
     if (rendered && typeof rendered === 'object' && 'html' in rendered) {
@@ -113,7 +121,7 @@
             data-item-type="font"
           >
             <div class="flex items-center flex-1 min-w-0 group">
-              <Check class="mr-2 h-6 w-6 flex-shrink-0 {isItemSelected(item) ? 'text-white' : 'text-sage-green opacity-0'}"/>
+              <Check class="me-2 h-6 w-6 flex-shrink-0 {isItemSelected(item) ? 'text-white' : 'text-sage-green opacity-0'}"/>
               <div class="flex-1 overflow-hidden">
                 {@html renderContent(item)}
               </div>
@@ -132,7 +140,7 @@
             data-item-type="font"
           >
             <div class="flex items-center flex-1 min-w-0 group">
-              <Check class="mr-2 h-6 w-6 flex-shrink-0 {isItemSelected(item) ? 'text-white' : 'text-sage-green opacity-0'}"/>
+              <Check class="me-2 h-6 w-6 flex-shrink-0 {isItemSelected(item) ? 'text-white' : 'text-sage-green opacity-0'}"/>
               <div class="flex-1 overflow-hidden">
                 {@html renderContent(item)}
               </div>
@@ -145,7 +153,7 @@
 
   {#if loadingMore}
     <div class="py-4 subtext text-center text-grey5">
-      Loading more items...
+      {$t('editor.list.loadingMore')}
     </div>
   {/if}
 </div>

package/dist/components/ic/shared/RecentItemsSection.svelte

@@ -13,9 +13,14 @@
   // Import Check icon from design system
   import { Check } from '@widgetic/design-system/icons';
   import icTrash from '../../../assets/icons/ic-browser/trash.svg?url';
-  
+  import { useEditorLanguage } from '../../../i18n/language';
+
+  // The words of the editor in the language of the page.
+  const { t } = useEditorLanguage();
+
   export let recentItems: any[] = [];
-  export let title = "Recently used";
+  /** The title of the section. Without one, the editor's own word, in the language of the page. */
+  export let title: string | undefined = undefined;
   export let onItemSelect: (item: any) => void;
   export let onItemDelete: (item: any, event: Event) => void;
   export let isItemSelected: (item: any) => boolean;
@@ -36,7 +41,7 @@
 
 {#if recentItems.length > 0}
   <div class="px-4 pt-4 pb-4 widgetic-colors">
-    <h5 class="subtext text-grey7">{title}</h5>
+    <h5 class="subtext text-grey7">{title ?? $t('editor.list.recentlyUsed')}</h5>
     
     {#if displayMode === 'list'}
       <div class="grid grid-cols-1">
@@ -59,7 +64,7 @@
               data-item={getItemKey(item)}
             >
               <div class="flex items-center flex-1 min-w-0 group">
-                <Check class="mr-2 h-6 w-6 flex-shrink-0 {selected ? 'text-white' : 'text-sage-green opacity-0'}"/>
+                <Check class="me-2 h-6 w-6 flex-shrink-0 {selected ? 'text-white' : 'text-sage-green opacity-0'}"/>
                 <div class="flex-1 overflow-hidden">
                   {#if typeof renderedItem === 'string'}
                     <span class="text-[24px]">{renderedItem}</span>
@@ -78,7 +83,7 @@
                       onItemDelete(item, e);
                     }}
                   >
-                    <img src={icTrash} alt="Delete" class="w-4 h-4" />
+                    <img src={icTrash} alt={$t('editor.list.deleteItem')} class="w-4 h-4" />
                   </button>
                 {/if}
               </div>
@@ -97,7 +102,7 @@
               data-item={getItemKey(item)}
             >
               <div class="flex items-center flex-1 min-w-0 group">
-                <Check class="mr-2 h-6 w-6 flex-shrink-0 {selected ? 'text-white' : 'text-sage-green opacity-0'}"/>
+                <Check class="me-2 h-6 w-6 flex-shrink-0 {selected ? 'text-white' : 'text-sage-green opacity-0'}"/>
                 <div class="flex-1 overflow-hidden">
                   {#if typeof renderedItem === 'string'}
                     <span class="text-[24px]">{renderedItem}</span>
@@ -116,7 +121,7 @@
                       onItemDelete(item, e);
                     }}
                   >
-                    <img src={icTrash} alt="Delete" class="w-4 h-4" />
+                    <img src={icTrash} alt={$t('editor.list.deleteItem')} class="w-4 h-4" />
                   </button>
                 {/if}
               </div>
@@ -157,14 +162,14 @@
                 {#if isCustomItem(item) && !hideTrashIcon}
                   <button 
                     type="button"
-                    class="absolute top-1 right-1 p-1 rounded-full hover:bg-red-100 hover:text-red-500 transition-colors bg-white"
+                    class="absolute top-1 end-1 p-1 rounded-full hover:bg-red-100 hover:text-red-500 transition-colors bg-white"
                     tabindex="-1"
                     onclick={(e) => {
                       e.stopPropagation();
                       onItemDelete(item, e);
                     }}
                   >
-                    <img src={icTrash} alt="Delete" class="w-3 h-3" />
+                    <img src={icTrash} alt={$t('editor.list.deleteItem')} class="w-3 h-3" />
                   </button>
                 {/if}
               </div>
@@ -195,14 +200,14 @@
                 {#if isCustomItem(item) && !hideTrashIcon}
                   <button 
                     type="button"
-                    class="absolute top-1 right-1 p-1 rounded-full hover:bg-red-100 hover:text-red-500 transition-colors bg-white"
+                    class="absolute top-1 end-1 p-1 rounded-full hover:bg-red-100 hover:text-red-500 transition-colors bg-white"
                     tabindex="-1"
                     onclick={(e) => {
                       e.stopPropagation();
                       onItemDelete(item, e);
                     }}
                   >
-                    <img src={icTrash} alt="Delete" class="w-3 h-3" />
+                    <img src={icTrash} alt={$t('editor.list.deleteItem')} class="w-3 h-3" />
                   </button>
                 {/if}
               </div>

package/dist/components/ic/shared/RecentItemsSection.svelte.d.ts

@@ -13,7 +13,7 @@ interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> =
 }
 declare const RecentItemsSection: $$__sveltets_2_IsomorphicComponent<{
     recentItems?: any[];
-    title?: string;
+    /** The title of the section. Without one, the editor's own word, in the language of the page. */ title?: string | undefined;
     onItemSelect: (item: any) => void;
     onItemDelete: (item: any, event: Event) => void;
     isItemSelected: (item: any) => boolean;

package/dist/composition/compositionApi.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The calls an embedded composition editor makes to the Widgetic API, over `fetch`.
+ *
+ * Why not the generated SDK: the editor runs in a customer's browser and may only call a short list of routes
+ * (those an editor session allows), the list is fixed, and it must work with whatever token the host page gives it.
+ * A client of its own keeps the editor small and independent of the SDK's release cycle, and it keeps the few
+ * rules that matter in one place:
+ *
+ *   - the token is asked from the host page before each request (`getAccessToken('initial')`); when the API
+ *     answers 401 it is asked again (`'expired'`) and the request is sent once more with a token that is new;
+ *   - a save carries an `Idempotency-Key` (the API requires one on every PUT from a session), kept the same when
+ *     the request is sent again after a 401, so one save is never applied twice;
+ *   - only the fields editing changes can be sent (`SaveCompositionBody`); a session is refused any other;
+ *   - every failure is a `CompositionApiError` with the API's own code, so the host can tell an ended session
+ *     (`EDITOR_SESSION_EXPIRED`...) from a missing composition (`NOT_FOUND`) from a widget that was never
+ *     published (`WIDGET_NOT_PUBLISHED`);
+ *   - a request that gets no answer does not hang the editor: it fails with `TIMEOUT` after a set time.
+ */
+import { type JsonRecord } from './compositionHelpers.js';
+/** Why the token is being asked for. `expired` means the API just refused the previous one. */
+export type TokenReason = 'initial' | 'expired';
+/** The fields of a composition an editor may change. Anything else is refused by the API for an editor session. */
+export interface SaveCompositionBody {
+    name?: string;
+    content?: JsonRecord;
+    design?: JsonRecord;
+    embedSettings?: JsonRecord;
+}
+/** Where to show a composition: the widget build the preview frame loads (`GET /compositions/{id}/preview`). */
+export interface CompositionPreviewInfo {
+    compositionId: string;
+    widgetId: string;
+    version: number;
+    previewUrl: string;
+}
+export interface CompositionApiOptions {
+    /** The API's address including the version, like `https://api.widgetic.com/v1`. */
+    apiBasePath: string;
+    /**
+     * Gives the token to call the API with. Called before every request, so a host that keeps its token fresh is
+     * always used up to date; called again with `'expired'` when the API answers 401, after which the request is
+     * sent once more if (and only if) the token that comes back is a different one. That second call also gets the
+     * token that was refused, so a host can tell the refusal of its current token (get a new one) from the late
+     * refusal of one it has already replaced (hand out the new one) when several requests are refused together.
+     */
+    getAccessToken: (reason: TokenReason, refusedToken?: string) => Promise<string> | string;
+    /** The `fetch` to use. Default: the page's own. */
+    fetch?: typeof fetch;
+    /** Makes the key a save is identified by (8 to 50 letters, digits, dashes and underscores). Default: a random UUID. */
+    createIdempotencyKey?: () => string;
+    /** How long to wait for an answer before giving up with `TIMEOUT`, in milliseconds. Default: 30 seconds. */
+    requestTimeoutMs?: number;
+}
+/** Options of one call. */
+export interface CompositionRequestOptions {
+    /** Cancels the request: the call then fails with `ABORTED`. */
+    signal?: AbortSignal;
+}
+export interface SaveCompositionOptions extends CompositionRequestOptions {
+    /** Identifies this save. Give the same key to send the same save again; default: a new one. */
+    idempotencyKey?: string;
+}
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/** Codes the client itself reports (the API's own codes, such as `NOT_FOUND`, are passed through as they are). */
+export type ClientErrorCode = 'NETWORK' | 'TIMEOUT' | 'ABORTED' | 'TOKEN_UNAVAILABLE' | 'INVALID_RESPONSE';
+/** A request to the API that did not give the answer wanted. */
+export declare class CompositionApiError extends Error {
+    /** The HTTP status; `0` when no answer arrived (network, timeout, abort, or no token to send). */
+    readonly status: number;
+    /** The API's error code (`NOT_FOUND`, `EDITOR_SESSION_EXPIRED`...), or one of {@link ClientErrorCode}. */
+    readonly code: string;
+    /** The API's correlation id for the failed request, to quote in a support request. */
+    readonly correlationId?: string;
+    constructor(message: string, details: {
+        status: number;
+        code: string;
+        correlationId?: string;
+    });
+    /** True when the editor session cannot be used any more: the host page has to give a new one. */
+    get sessionEnded(): boolean;
+    /** True when sending the same request again later may work: nothing was refused, the network or the server failed. */
+    get retryable(): boolean;
+}
+/** What a client of the composition routes can do. */
+export interface CompositionApi {
+    getComposition(compositionId: string, options?: CompositionRequestOptions): Promise<JsonRecord>;
+    getPreview(compositionId: string, options?: CompositionRequestOptions): Promise<CompositionPreviewInfo>;
+    getContentSchema(compositionId: string, options?: CompositionRequestOptions): Promise<unknown>;
+    getDesignSchema(compositionId: string, options?: CompositionRequestOptions): Promise<unknown>;
+    saveComposition(compositionId: string, body: SaveCompositionBody, options?: SaveCompositionOptions): Promise<JsonRecord>;
+}
+/** A key that is unique, not secret: the page's `crypto.randomUUID`, else random bytes, else the clock and `Math.random`. */
+export declare function createRandomIdempotencyKey(): string;
+/** Builds the client. `apiBasePath` and `getAccessToken` are required. */
+export declare function createCompositionApi(options: CompositionApiOptions): CompositionApi;