@wix/web5-core 1.63.26 → 1.63.28

package/dist/cjs/context/ComponentDependenciesContext.js

@@ -3,6 +3,7 @@
 exports.__esModule = true;
 exports.ComponentDependenciesProvider = void 0;
 exports.useComponentDependencies = useComponentDependencies;
+exports.useOptionalComponentDependencies = useOptionalComponentDependencies;
 var _react = _interopRequireWildcard(require("react"));
 var _jsxFileName = "/home/builduser/work/c2b6ca0b3fa984ee/packages/web5-core/dist/cjs/context/ComponentDependenciesContext.tsx";
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
@@ -14,6 +15,19 @@ function useComponentDependencies() {
   }
   return ctx;
 }
+
+/**
+ * The same context, without the throw.
+ *
+ * For providers the HOST mounts around every section rather than a component
+ * opting in: those sit above trees that may legitimately have no dependencies
+ * configured — a layout test, a storybook story — and hard-crashing them would
+ * make an unrelated feature's provider a global requirement. A consumer that
+ * genuinely needs deps should still use `useComponentDependencies`.
+ */
+function useOptionalComponentDependencies() {
+  return (0, _react.useContext)(ComponentDependenciesContext);
+}
 const ComponentDependenciesProvider = ({
   deps,
   children
@@ -23,7 +37,7 @@ const ComponentDependenciesProvider = ({
     __self: void 0,
     __source: {
       fileName: _jsxFileName,
-      lineNumber: 31,
+      lineNumber: 44,
       columnNumber: 5
     }
   }, children);

package/dist/cjs/context/ComponentDependenciesContext.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","_interopRequireWildcard","require","_jsxFileName","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","ComponentDependenciesContext","createContext","useComponentDependencies","ctx","useContext","Error","ComponentDependenciesProvider","deps","children","createElement","Provider","value","__self","__source","fileName","lineNumber","columnNumber","exports"],"sources":["../../../src/context/ComponentDependenciesContext.tsx"],"sourcesContent":["import React, {\n  createContext,\n  useContext,\n  type FC,\n  type PropsWithChildren,\n} from 'react';\nimport type { ComponentDependencies } from '../types/dependencies';\n\nconst ComponentDependenciesContext =\n  createContext<ComponentDependencies | null>(null);\n\nexport function useComponentDependencies(): ComponentDependencies {\n  const ctx = useContext(ComponentDependenciesContext);\n  if (!ctx) {\n    throw new Error(\n      'useComponentDependencies must be used within a ComponentDependenciesProvider. ' +\n        'Wrap your app with <ComponentDependenciesProvider deps={...}>.',\n    );\n  }\n  return ctx;\n}\n\nexport interface ComponentDependenciesProviderProps extends PropsWithChildren {\n  deps: ComponentDependencies;\n}\n\nexport const ComponentDependenciesProvider: FC<\n  ComponentDependenciesProviderProps\n> = ({ deps, children }) => {\n  return (\n    <ComponentDependenciesContext.Provider value={deps}>\n      {children}\n    </ComponentDependenciesContext.Provider>\n  );\n};\n"],"mappings":";;;;;AAAA,IAAAA,MAAA,GAAAC,uBAAA,CAAAC,OAAA;AAKe,IAAAC,YAAA;AAAA,SAAAF,wBAAAG,CAAA,EAAAC,CAAA,6BAAAC,OAAA,MAAAC,CAAA,OAAAD,OAAA,IAAAE,CAAA,OAAAF,OAAA,YAAAL,uBAAA,YAAAA,CAAAG,CAAA,EAAAC,CAAA,SAAAA,CAAA,IAAAD,CAAA,IAAAA,CAAA,CAAAK,UAAA,SAAAL,CAAA,MAAAM,CAAA,EAAAC,CAAA,EAAAC,CAAA,KAAAC,SAAA,QAAAC,OAAA,EAAAV,CAAA,iBAAAA,CAAA,uBAAAA,CAAA,yBAAAA,CAAA,SAAAQ,CAAA,MAAAF,CAAA,GAAAL,CAAA,GAAAG,CAAA,GAAAD,CAAA,QAAAG,CAAA,CAAAK,GAAA,CAAAX,CAAA,UAAAM,CAAA,CAAAM,GAAA,CAAAZ,CAAA,GAAAM,CAAA,CAAAO,GAAA,CAAAb,CAAA,EAAAQ,CAAA,gBAAAP,CAAA,IAAAD,CAAA,gBAAAC,CAAA,OAAAa,cAAA,CAAAC,IAAA,CAAAf,CAAA,EAAAC,CAAA,OAAAM,CAAA,IAAAD,CAAA,GAAAU,MAAA,CAAAC,cAAA,KAAAD,MAAA,CAAAE,wBAAA,CAAAlB,CAAA,EAAAC,CAAA,OAAAM,CAAA,CAAAK,GAAA,IAAAL,CAAA,CAAAM,GAAA,IAAAP,CAAA,CAAAE,CAAA,EAAAP,CAAA,EAAAM,CAAA,IAAAC,CAAA,CAAAP,CAAA,IAAAD,CAAA,CAAAC,CAAA,WAAAO,CAAA,KAAAR,CAAA,EAAAC,CAAA;AAGf,MAAMkB,4BAA4B,gBAChC,IAAAC,oBAAa,EAA+B,IAAI,CAAC;AAE5C,SAASC,wBAAwBA,CAAA,EAA0B;EAChE,MAAMC,GAAG,GAAG,IAAAC,iBAAU,EAACJ,4BAA4B,CAAC;EACpD,IAAI,CAACG,GAAG,EAAE;IACR,MAAM,IAAIE,KAAK,CACb,gFAAgF,GAC9E,gEACJ,CAAC;EACH;EACA,OAAOF,GAAG;AACZ;AAMO,MAAMG,6BAEZ,GAAGA,CAAC;EAAEC,IAAI;EAAEC;AAAS,CAAC,KAAK;EAC1B,oBACE/B,MAAA,CAAAc,OAAA,CAAAkB,aAAA,CAACT,4BAA4B,CAACU,QAAQ;IAACC,KAAK,EAAEJ,IAAK;IAAAK,MAAA;IAAAC,QAAA;MAAAC,QAAA,EAAAlC,YAAA;MAAAmC,UAAA;MAAAC,YAAA;IAAA;EAAA,GAChDR,QACoC,CAAC;AAE5C,CAAC;AAACS,OAAA,CAAAX,6BAAA,GAAAA,6BAAA","ignoreList":[]}
+{"version":3,"names":["_react","_interopRequireWildcard","require","_jsxFileName","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","ComponentDependenciesContext","createContext","useComponentDependencies","ctx","useContext","Error","useOptionalComponentDependencies","ComponentDependenciesProvider","deps","children","createElement","Provider","value","__self","__source","fileName","lineNumber","columnNumber","exports"],"sources":["../../../src/context/ComponentDependenciesContext.tsx"],"sourcesContent":["import React, {\n  createContext,\n  useContext,\n  type FC,\n  type PropsWithChildren,\n} from 'react';\nimport type { ComponentDependencies } from '../types/dependencies';\n\nconst ComponentDependenciesContext =\n  createContext<ComponentDependencies | null>(null);\n\nexport function useComponentDependencies(): ComponentDependencies {\n  const ctx = useContext(ComponentDependenciesContext);\n  if (!ctx) {\n    throw new Error(\n      'useComponentDependencies must be used within a ComponentDependenciesProvider. ' +\n        'Wrap your app with <ComponentDependenciesProvider deps={...}>.',\n    );\n  }\n  return ctx;\n}\n\n/**\n * The same context, without the throw.\n *\n * For providers the HOST mounts around every section rather than a component\n * opting in: those sit above trees that may legitimately have no dependencies\n * configured — a layout test, a storybook story — and hard-crashing them would\n * make an unrelated feature's provider a global requirement. A consumer that\n * genuinely needs deps should still use `useComponentDependencies`.\n */\nexport function useOptionalComponentDependencies(): ComponentDependencies | null {\n  return useContext(ComponentDependenciesContext);\n}\n\nexport interface ComponentDependenciesProviderProps extends PropsWithChildren {\n  deps: ComponentDependencies;\n}\n\nexport const ComponentDependenciesProvider: FC<\n  ComponentDependenciesProviderProps\n> = ({ deps, children }) => {\n  return (\n    <ComponentDependenciesContext.Provider value={deps}>\n      {children}\n    </ComponentDependenciesContext.Provider>\n  );\n};\n"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,uBAAA,CAAAC,OAAA;AAKe,IAAAC,YAAA;AAAA,SAAAF,wBAAAG,CAAA,EAAAC,CAAA,6BAAAC,OAAA,MAAAC,CAAA,OAAAD,OAAA,IAAAE,CAAA,OAAAF,OAAA,YAAAL,uBAAA,YAAAA,CAAAG,CAAA,EAAAC,CAAA,SAAAA,CAAA,IAAAD,CAAA,IAAAA,CAAA,CAAAK,UAAA,SAAAL,CAAA,MAAAM,CAAA,EAAAC,CAAA,EAAAC,CAAA,KAAAC,SAAA,QAAAC,OAAA,EAAAV,CAAA,iBAAAA,CAAA,uBAAAA,CAAA,yBAAAA,CAAA,SAAAQ,CAAA,MAAAF,CAAA,GAAAL,CAAA,GAAAG,CAAA,GAAAD,CAAA,QAAAG,CAAA,CAAAK,GAAA,CAAAX,CAAA,UAAAM,CAAA,CAAAM,GAAA,CAAAZ,CAAA,GAAAM,CAAA,CAAAO,GAAA,CAAAb,CAAA,EAAAQ,CAAA,gBAAAP,CAAA,IAAAD,CAAA,gBAAAC,CAAA,OAAAa,cAAA,CAAAC,IAAA,CAAAf,CAAA,EAAAC,CAAA,OAAAM,CAAA,IAAAD,CAAA,GAAAU,MAAA,CAAAC,cAAA,KAAAD,MAAA,CAAAE,wBAAA,CAAAlB,CAAA,EAAAC,CAAA,OAAAM,CAAA,CAAAK,GAAA,IAAAL,CAAA,CAAAM,GAAA,IAAAP,CAAA,CAAAE,CAAA,EAAAP,CAAA,EAAAM,CAAA,IAAAC,CAAA,CAAAP,CAAA,IAAAD,CAAA,CAAAC,CAAA,WAAAO,CAAA,KAAAR,CAAA,EAAAC,CAAA;AAGf,MAAMkB,4BAA4B,gBAChC,IAAAC,oBAAa,EAA+B,IAAI,CAAC;AAE5C,SAASC,wBAAwBA,CAAA,EAA0B;EAChE,MAAMC,GAAG,GAAG,IAAAC,iBAAU,EAACJ,4BAA4B,CAAC;EACpD,IAAI,CAACG,GAAG,EAAE;IACR,MAAM,IAAIE,KAAK,CACb,gFAAgF,GAC9E,gEACJ,CAAC;EACH;EACA,OAAOF,GAAG;AACZ;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,gCAAgCA,CAAA,EAAiC;EAC/E,OAAO,IAAAF,iBAAU,EAACJ,4BAA4B,CAAC;AACjD;AAMO,MAAMO,6BAEZ,GAAGA,CAAC;EAAEC,IAAI;EAAEC;AAAS,CAAC,KAAK;EAC1B,oBACEhC,MAAA,CAAAc,OAAA,CAAAmB,aAAA,CAACV,4BAA4B,CAACW,QAAQ;IAACC,KAAK,EAAEJ,IAAK;IAAAK,MAAA;IAAAC,QAAA;MAAAC,QAAA,EAAAnC,YAAA;MAAAoC,UAAA;MAAAC,YAAA;IAAA;EAAA,GAChDR,QACoC,CAAC;AAE5C,CAAC;AAACS,OAAA,CAAAX,6BAAA,GAAAA,6BAAA","ignoreList":[]}

package/dist/cjs/context/ImageSlotContext.js

@@ -0,0 +1,221 @@
+"use strict";
+
+exports.__esModule = true;
+exports.useImageSlotCollector = exports.ImageSlotProvider = void 0;
+var _react = _interopRequireWildcard(require("react"));
+var _ComponentDependenciesContext = require("./ComponentDependenciesContext");
+var _diagnosticTypes = require("../component/diagnosticTypes");
+var _jsxFileName = "/home/builduser/work/c2b6ca0b3fa984ee/packages/web5-core/dist/cjs/context/ImageSlotContext.tsx";
+/**
+ * The section-scoped image slot collector.
+ *
+ * A section declares the holes in its layout; it never makes a request. This
+ * gathers every declaration made inside one section's subtree, fires ONE
+ * `ResolveImageSet` through the injected port, and hands each declaration its
+ * answer back by `slotId`. Sections stay ignorant of each other — no section
+ * imports another, no ordering rules, no exclusion lists threaded through
+ * props — and the network still sees the joint solve that distinctness depends
+ * on.
+ *
+ * WHY THE BOUNDARY IS THE SECTION
+ * -------------------------------
+ * The resolver solves a maximum-weight one-to-one assignment across everything
+ * in one request, so distinctness and palette cohesion are properties of that
+ * solve and stop at its edge. Drawing the boundary at the page would buy
+ * cross-section distinctness at the cost of making every section's pictures
+ * wait on the slowest declaration on the page; drawing it at the section keeps
+ * each section independent and accepts that two sections may land on the same
+ * photograph. The most visible case — four identical photos in one grid — is
+ * still prevented for free, because those slots share a request.
+ *
+ * WHY THERE IS NO READINESS POLICY
+ * --------------------------------
+ * There is nothing to wait for. A section component is never constructed from
+ * partial markdown: a declared-but-unstreamed section is a `PageSection` with
+ * `isSkeleton: true` and `component: null`, and the real element is built only
+ * once its body has finished streaming. So a section's props are final the
+ * moment it exists, and the flush is simply "after this section's first render
+ * commit" — one effect, not a scheduler.
+ *
+ * The same fact bounds the win honestly: because only a *mounted* section
+ * declares, no section can ask for a picture before its own body has streamed,
+ * including a background whose subject needed nothing from that body.
+ */
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+const ImageSlotContext = /*#__PURE__*/(0, _react.createContext)(null);
+
+/**
+ * Module-level so `read` returns a STABLE reference for a slot nobody has
+ * published yet. `useImageSlot` reads this store through
+ * `useSyncExternalStore`, which compares snapshots with `Object.is` on every
+ * render — a fresh `{ status: 'pending' }` per call reads as "the store
+ * changed", and React re-renders until it throws "Maximum update depth
+ * exceeded". Every slot is pending from mount until its batch answers, so a
+ * literal here takes down every section that declares one.
+ */
+const PENDING = {
+  status: 'pending'
+};
+/**
+ * Mounted once per section by the host's section wrapper, so every section in
+ * every client package gets a collector without opting in.
+ */
+const ImageSlotProvider = ({
+  sectionId,
+  children
+}) => {
+  // Optional on purpose: this is mounted by the host around EVERY section, so
+  // it sits above trees that may have no dependencies configured at all (a
+  // layout test, a story). Throwing there would make the image feature's
+  // provider a global requirement for rendering any section.
+  const deps = (0, _ComponentDependenciesContext.useOptionalComponentDependencies)();
+  const resolve = deps == null ? void 0 : deps.resolveImageSet;
+
+  /**
+   * Slot state lives in a ref, NOT in React state, and the context value never
+   * changes. Holding it in state put it inside the provider's value, so every
+   * resolution produced a new value and re-rendered every consumer in the
+   * section — free at one slot, twelve re-renders per resolution in a
+   * twelve-card grid, which is exactly the shape this boundary exists to serve.
+   * Consumers now subscribe to their own id and nothing else.
+   */
+  const statesRef = (0, _react.useRef)({});
+  const listenersRef = (0, _react.useRef)(new Map());
+
+  // Declarations arriving during this commit. A ref, not state: collecting a
+  // declaration must not itself cause a render, or every hook that declares
+  // would re-render every sibling before the batch is even sent.
+  const pendingRef = (0, _react.useRef)(new Map());
+  // Ids already sent. A re-render re-declares the same content-derived id, and
+  // that must be a no-op rather than a second request.
+  const sentRef = (0, _react.useRef)(new Set());
+  const flushScheduled = (0, _react.useRef)(false);
+  const aliveRef = (0, _react.useRef)(true);
+  (0, _react.useEffect)(() => {
+    aliveRef.current = true;
+    return () => {
+      aliveRef.current = false;
+    };
+  }, []);
+  const publish = (0, _react.useCallback)(next => {
+    const changed = [];
+    for (const [id, state] of Object.entries(next)) {
+      if (statesRef.current[id] !== state) {
+        statesRef.current[id] = state;
+        changed.push(id);
+      }
+    }
+    for (const id of changed) {
+      var _listenersRef$current;
+      (_listenersRef$current = listenersRef.current.get(id)) == null || _listenersRef$current.forEach(fn => fn());
+    }
+  }, []);
+  const markUnavailable = (0, _react.useCallback)(batch => {
+    if (!aliveRef.current) {
+      return;
+    }
+    publish(Object.fromEntries(batch.map(s => [s.id, {
+      status: 'unavailable'
+    }])));
+  }, [publish]);
+  const flush = (0, _react.useCallback)(async () => {
+    flushScheduled.current = false;
+    const batch = [...pendingRef.current.values()].filter(s => !sentRef.current.has(s.id));
+    pendingRef.current.clear();
+    if (batch.length === 0) {
+      return;
+    }
+    batch.forEach(s => sentRef.current.add(s.id));
+
+    // No port means the host has not injected a resolver. Fail the batch closed
+    // rather than silently leaving slots pending forever.
+    if (!resolve) {
+      markUnavailable(batch);
+      return;
+    }
+    try {
+      const res = await resolve(batch);
+      if (!aliveRef.current) {
+        return;
+      }
+      const bySlotId = new Map(res.slots.map(s => [s.slotId, s]));
+      const next = {};
+      for (const req of batch) {
+        const got = bySlotId.get(req.id);
+        // A slot the resolver could not fill comes back with a null url. That
+        // is `unavailable` to a layout, not a resolved picture.
+        next[req.id] = got && got.imageUrl ? {
+          status: 'resolved',
+          slot: got
+        } : {
+          status: 'unavailable'
+        };
+      }
+      publish(next);
+    } catch (err) {
+      // Failure is contained to this section: one bad request costs this
+      // section its pictures and nothing else on the page.
+      deps == null || deps.reportDiagnostic == null || deps.reportDiagnostic(_diagnosticTypes.DIAGNOSTIC_TYPES.IMAGE_RESOLUTION_FAILED, sectionId, `ResolveImageSet failed for ${batch.length} slot(s): ${err instanceof Error ? err.message : String(err)}`);
+      markUnavailable(batch);
+    }
+  }, [resolve, deps, sectionId, publish, markUnavailable]);
+  const declare = (0, _react.useCallback)(slot => {
+    if (sentRef.current.has(slot.id)) {
+      return;
+    }
+    pendingRef.current.set(slot.id, slot);
+    // Flush on a microtask, so every declaration made during this commit —
+    // the background, the cards, an inline image — lands in the same batch.
+    if (!flushScheduled.current) {
+      flushScheduled.current = true;
+      queueMicrotask(() => {
+        void flush();
+      });
+    }
+  }, [flush]);
+  const read = (0, _react.useCallback)(slotId => statesRef.current[slotId] ?? PENDING, []);
+  const subscribe = (0, _react.useCallback)((slotId, onChange) => {
+    let set = listenersRef.current.get(slotId);
+    if (!set) {
+      set = new Set();
+      listenersRef.current.set(slotId, set);
+    }
+    set.add(onChange);
+    return () => {
+      var _set;
+      (_set = set) == null || _set.delete(onChange);
+      if (set && set.size === 0) {
+        listenersRef.current.delete(slotId);
+      }
+    };
+  }, []);
+
+  // Stable for the provider's lifetime: every member is a `useCallback` with no
+  // reactive deps, so mounting this around a section costs its consumers
+  // nothing after first render.
+  const api = (0, _react.useMemo)(() => ({
+    declare,
+    read,
+    subscribe
+  }), [declare, read, subscribe]);
+  return /*#__PURE__*/_react.default.createElement(ImageSlotContext.Provider, {
+    value: api,
+    __self: void 0,
+    __source: {
+      fileName: _jsxFileName,
+      lineNumber: 246,
+      columnNumber: 5
+    }
+  }, children);
+};
+
+/**
+ * Null when no provider is mounted above — a host that has not adopted the
+ * section wrapper's collector. `useImageSlot` handles that by resolving each
+ * slot on its own, so a section still gets its picture and only loses batching
+ * with its siblings.
+ */
+exports.ImageSlotProvider = ImageSlotProvider;
+const useImageSlotCollector = () => (0, _react.useContext)(ImageSlotContext);
+exports.useImageSlotCollector = useImageSlotCollector;
+//# sourceMappingURL=ImageSlotContext.js.map

package/dist/cjs/context/ImageSlotContext.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","_interopRequireWildcard","require","_ComponentDependenciesContext","_diagnosticTypes","_jsxFileName","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","ImageSlotContext","createContext","PENDING","status","ImageSlotProvider","sectionId","children","deps","useOptionalComponentDependencies","resolve","resolveImageSet","statesRef","useRef","listenersRef","Map","pendingRef","sentRef","Set","flushScheduled","aliveRef","useEffect","current","publish","useCallback","next","changed","id","state","entries","push","_listenersRef$current","forEach","fn","markUnavailable","batch","fromEntries","map","s","flush","values","filter","clear","length","add","res","bySlotId","slots","slotId","req","got","imageUrl","slot","err","reportDiagnostic","DIAGNOSTIC_TYPES","IMAGE_RESOLUTION_FAILED","Error","message","String","declare","queueMicrotask","read","subscribe","onChange","_set","delete","size","api","useMemo","createElement","Provider","value","__self","__source","fileName","lineNumber","columnNumber","exports","useImageSlotCollector","useContext"],"sources":["../../../src/context/ImageSlotContext.tsx"],"sourcesContent":["/**\n * The section-scoped image slot collector.\n *\n * A section declares the holes in its layout; it never makes a request. This\n * gathers every declaration made inside one section's subtree, fires ONE\n * `ResolveImageSet` through the injected port, and hands each declaration its\n * answer back by `slotId`. Sections stay ignorant of each other — no section\n * imports another, no ordering rules, no exclusion lists threaded through\n * props — and the network still sees the joint solve that distinctness depends\n * on.\n *\n * WHY THE BOUNDARY IS THE SECTION\n * -------------------------------\n * The resolver solves a maximum-weight one-to-one assignment across everything\n * in one request, so distinctness and palette cohesion are properties of that\n * solve and stop at its edge. Drawing the boundary at the page would buy\n * cross-section distinctness at the cost of making every section's pictures\n * wait on the slowest declaration on the page; drawing it at the section keeps\n * each section independent and accepts that two sections may land on the same\n * photograph. The most visible case — four identical photos in one grid — is\n * still prevented for free, because those slots share a request.\n *\n * WHY THERE IS NO READINESS POLICY\n * --------------------------------\n * There is nothing to wait for. A section component is never constructed from\n * partial markdown: a declared-but-unstreamed section is a `PageSection` with\n * `isSkeleton: true` and `component: null`, and the real element is built only\n * once its body has finished streaming. So a section's props are final the\n * moment it exists, and the flush is simply \"after this section's first render\n * commit\" — one effect, not a scheduler.\n *\n * The same fact bounds the win honestly: because only a *mounted* section\n * declares, no section can ask for a picture before its own body has streamed,\n * including a background whose subject needed nothing from that body.\n */\nimport React, {\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n} from 'react';\nimport { useOptionalComponentDependencies } from './ComponentDependenciesContext';\nimport { DIAGNOSTIC_TYPES } from '../component/diagnosticTypes';\nimport type {\n  ImageSlotRequest,\n  SlotState,\n} from '../image/imageSlotTypes';\n\nexport interface ImageSlotCollector {\n  /** Register a slot for this batch. Idempotent per content-derived id. */\n  declare: (slot: ImageSlotRequest) => void;\n  /** Current state for one slot. Not reactive alone — pair with `subscribe`. */\n  read: (slotId: string) => SlotState;\n  /** Notify only when THIS slot changes. Returns an unsubscribe. */\n  subscribe: (slotId: string, onChange: () => void) => () => void;\n}\n\nconst ImageSlotContext = createContext<ImageSlotCollector | null>(null);\n\n/**\n * Module-level so `read` returns a STABLE reference for a slot nobody has\n * published yet. `useImageSlot` reads this store through\n * `useSyncExternalStore`, which compares snapshots with `Object.is` on every\n * render — a fresh `{ status: 'pending' }` per call reads as \"the store\n * changed\", and React re-renders until it throws \"Maximum update depth\n * exceeded\". Every slot is pending from mount until its batch answers, so a\n * literal here takes down every section that declares one.\n */\nconst PENDING: SlotState = { status: 'pending' };\n\nexport interface ImageSlotProviderProps {\n  /** Identifies the section in diagnostics. */\n  sectionId: string;\n  children: React.ReactNode;\n}\n\n/**\n * Mounted once per section by the host's section wrapper, so every section in\n * every client package gets a collector without opting in.\n */\nexport const ImageSlotProvider: React.FC<ImageSlotProviderProps> = ({\n  sectionId,\n  children,\n}) => {\n  // Optional on purpose: this is mounted by the host around EVERY section, so\n  // it sits above trees that may have no dependencies configured at all (a\n  // layout test, a story). Throwing there would make the image feature's\n  // provider a global requirement for rendering any section.\n  const deps = useOptionalComponentDependencies();\n  const resolve = deps?.resolveImageSet;\n\n  /**\n   * Slot state lives in a ref, NOT in React state, and the context value never\n   * changes. Holding it in state put it inside the provider's value, so every\n   * resolution produced a new value and re-rendered every consumer in the\n   * section — free at one slot, twelve re-renders per resolution in a\n   * twelve-card grid, which is exactly the shape this boundary exists to serve.\n   * Consumers now subscribe to their own id and nothing else.\n   */\n  const statesRef = useRef<Record<string, SlotState>>({});\n  const listenersRef = useRef<Map<string, Set<() => void>>>(new Map());\n\n  // Declarations arriving during this commit. A ref, not state: collecting a\n  // declaration must not itself cause a render, or every hook that declares\n  // would re-render every sibling before the batch is even sent.\n  const pendingRef = useRef<Map<string, ImageSlotRequest>>(new Map());\n  // Ids already sent. A re-render re-declares the same content-derived id, and\n  // that must be a no-op rather than a second request.\n  const sentRef = useRef<Set<string>>(new Set());\n  const flushScheduled = useRef(false);\n  const aliveRef = useRef(true);\n\n  useEffect(() => {\n    aliveRef.current = true;\n    return () => {\n      aliveRef.current = false;\n    };\n  }, []);\n\n  const publish = useCallback((next: Record<string, SlotState>) => {\n    const changed: string[] = [];\n    for (const [id, state] of Object.entries(next)) {\n      if (statesRef.current[id] !== state) {\n        statesRef.current[id] = state;\n        changed.push(id);\n      }\n    }\n    for (const id of changed) {\n      listenersRef.current.get(id)?.forEach((fn) => fn());\n    }\n  }, []);\n\n  const markUnavailable = useCallback(\n    (batch: ImageSlotRequest[]) => {\n      if (!aliveRef.current) {\n        return;\n      }\n      publish(\n        Object.fromEntries(\n          batch.map((s) => [s.id, { status: 'unavailable' } as SlotState]),\n        ),\n      );\n    },\n    [publish],\n  );\n\n  const flush = useCallback(async () => {\n    flushScheduled.current = false;\n\n    const batch = [...pendingRef.current.values()].filter(\n      (s) => !sentRef.current.has(s.id),\n    );\n    pendingRef.current.clear();\n    if (batch.length === 0) {\n      return;\n    }\n    batch.forEach((s) => sentRef.current.add(s.id));\n\n    // No port means the host has not injected a resolver. Fail the batch closed\n    // rather than silently leaving slots pending forever.\n    if (!resolve) {\n      markUnavailable(batch);\n      return;\n    }\n\n    try {\n      const res = await resolve(batch);\n      if (!aliveRef.current) {\n        return;\n      }\n      const bySlotId = new Map(res.slots.map((s) => [s.slotId, s]));\n      const next: Record<string, SlotState> = {};\n      for (const req of batch) {\n        const got = bySlotId.get(req.id);\n        // A slot the resolver could not fill comes back with a null url. That\n        // is `unavailable` to a layout, not a resolved picture.\n        next[req.id] =\n          got && got.imageUrl\n            ? { status: 'resolved', slot: got }\n            : { status: 'unavailable' };\n      }\n      publish(next);\n    } catch (err) {\n      // Failure is contained to this section: one bad request costs this\n      // section its pictures and nothing else on the page.\n      deps?.reportDiagnostic?.(\n        DIAGNOSTIC_TYPES.IMAGE_RESOLUTION_FAILED,\n        sectionId,\n        `ResolveImageSet failed for ${batch.length} slot(s): ${\n          err instanceof Error ? err.message : String(err)\n        }`,\n      );\n      markUnavailable(batch);\n    }\n  }, [resolve, deps, sectionId, publish, markUnavailable]);\n\n  const declare = useCallback(\n    (slot: ImageSlotRequest) => {\n      if (sentRef.current.has(slot.id)) {\n        return;\n      }\n      pendingRef.current.set(slot.id, slot);\n      // Flush on a microtask, so every declaration made during this commit —\n      // the background, the cards, an inline image — lands in the same batch.\n      if (!flushScheduled.current) {\n        flushScheduled.current = true;\n        queueMicrotask(() => {\n          void flush();\n        });\n      }\n    },\n    [flush],\n  );\n\n  const read = useCallback(\n    (slotId: string): SlotState => statesRef.current[slotId] ?? PENDING,\n    [],\n  );\n\n  const subscribe = useCallback((slotId: string, onChange: () => void) => {\n    let set = listenersRef.current.get(slotId);\n    if (!set) {\n      set = new Set();\n      listenersRef.current.set(slotId, set);\n    }\n    set.add(onChange);\n    return () => {\n      set?.delete(onChange);\n      if (set && set.size === 0) {\n        listenersRef.current.delete(slotId);\n      }\n    };\n  }, []);\n\n  // Stable for the provider's lifetime: every member is a `useCallback` with no\n  // reactive deps, so mounting this around a section costs its consumers\n  // nothing after first render.\n  const api = useMemo<ImageSlotCollector>(\n    () => ({ declare, read, subscribe }),\n    [declare, read, subscribe],\n  );\n\n  return (\n    <ImageSlotContext.Provider value={api}>{children}</ImageSlotContext.Provider>\n  );\n};\n\n/**\n * Null when no provider is mounted above — a host that has not adopted the\n * section wrapper's collector. `useImageSlot` handles that by resolving each\n * slot on its own, so a section still gets its picture and only loses batching\n * with its siblings.\n */\nexport const useImageSlotCollector = (): ImageSlotCollector | null =>\n  useContext(ImageSlotContext);\n"],"mappings":"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","ignoreList":[]}

package/dist/cjs/hooks/useImageSlot.js

@@ -0,0 +1,182 @@
+"use strict";
+
+exports.__esModule = true;
+exports.useImageSlot = useImageSlot;
+var _react = require("react");
+var _ComponentDependenciesContext = require("../context/ComponentDependenciesContext");
+var _ImageSlotContext = require("../context/ImageSlotContext");
+var _composeSemantic = require("../image/composeSemantic");
+/**
+ * `useImageSlot` — the whole section-facing surface for images.
+ *
+ * A section describes the hole in its layout and what the picture should be
+ * about. It does not name a request, a batch, or a set boundary; that omission
+ * is deliberate and load-bearing, because it is what lets the boundary widen
+ * from the section to the page later without touching a single component.
+ *
+ * Replaces the per-image `useResolvedImageSources` path, whose endpoint was
+ * removed and, once restored, answers with an empty list.
+ */
+
+/** The `web5://image/` prefix an author's token carries. */
+const TOKEN_PREFIX = 'web5://image/';
+const decodeToken = raw => {
+  const body = raw.startsWith(TOKEN_PREFIX) ? raw.slice(TOKEN_PREFIX.length) : raw;
+  try {
+    return decodeURIComponent(body).trim();
+  } catch {
+    return body.trim();
+  }
+};
+
+/**
+ * Content-derived, never an index and never a React key. A re-render
+ * re-declares the same id so it does not re-request, and reordering items
+ * cannot remap pictures onto different cards — which an index-based id would
+ * do, visibly. Kept short and readable rather than cryptographic: it only has
+ * to be stable, and unique within one request.
+ */
+const slotIdFor = (role, subjectKey, ratio, width) => {
+  let h = 0;
+  const material = `${role}|${subjectKey}|${ratio.toFixed(4)}|${width}`;
+  for (let i = 0; i < material.length; i++) {
+    h = Math.imul(31, h) + material.charCodeAt(i) | 0;
+  }
+  return `${role}-${(h >>> 0).toString(36)}`;
+};
+
+/** Module-level so `getSnapshot` returns a STABLE reference. Returning a fresh
+ *  `{ status: 'unavailable' }` on every call makes `useSyncExternalStore`
+ *  believe the store changed on every check, and it re-renders forever. */
+const SETTLED_UNAVAILABLE = {
+  status: 'unavailable'
+};
+function useImageSlot(options) {
+  var _state$slot$visualMet;
+  const {
+    role = 'background',
+    ratio,
+    width = 800,
+    subject,
+    fallbackUrl,
+    enabled = true
+  } = options;
+
+  // Optional for the same reason the provider's is: a section rendered without
+  // dependencies configured should lose its picture, not throw.
+  const deps = (0, _ComponentDependenciesContext.useOptionalComponentDependencies)();
+  const collector = (0, _ImageSlotContext.useImageSlotCollector)();
+  const resolve = deps == null ? void 0 : deps.resolveImageSet;
+
+  /** The declaration, derived purely from props. */
+  const request = (0, _react.useMemo)(() => {
+    if (!enabled) {
+      return null;
+    }
+    if (subject.from === 'entity') {
+      var _subject$entityId;
+      const entityId = (_subject$entityId = subject.entityId) == null ? void 0 : _subject$entityId.trim();
+      if (!entityId) {
+        return null;
+      }
+      return {
+        id: slotIdFor(role, `e:${entityId}`, ratio, width),
+        kind: 'IMAGE_SLOT_KIND_ENTITY',
+        ratio,
+        renderWidthPx: width,
+        entityId
+      };
+    }
+    const semantic = subject.from === 'token' ? decodeToken(subject.token ?? '') : (0, _composeSemantic.composeSemantic)({
+      title: subject.title,
+      lead: subject.lead
+    });
+
+    // Too thin to retrieve on is not a query worth sending. `composeSemantic`
+    // returns empty rather than guessing, and a token can be empty too
+    // (`![alt](web5://image/)`).
+    if (!semantic) {
+      return null;
+    }
+    return {
+      id: slotIdFor(role, `s:${semantic}`, ratio, width),
+      kind: 'IMAGE_SLOT_KIND_EDITORIAL',
+      ratio,
+      renderWidthPx: width,
+      semantic
+    };
+  }, [enabled, role, ratio, width, subject]);
+
+  // Used only when no collector is mounted above — a host that has not adopted
+  // the section wrapper's provider. Same answer, no batching with siblings.
+  const [soloState, setSoloState] = (0, _react.useState)({
+    status: 'pending'
+  });
+  const soloSentRef = (0, _react.useRef)(null);
+  (0, _react.useEffect)(() => {
+    if (!request) {
+      return;
+    }
+    if (collector) {
+      collector.declare(request);
+      return;
+    }
+    if (soloSentRef.current === request.id) {
+      return;
+    }
+    soloSentRef.current = request.id;
+    if (!resolve) {
+      setSoloState({
+        status: 'unavailable'
+      });
+      return;
+    }
+    let alive = true;
+    resolve([request]).then(res => {
+      if (!alive) {
+        return;
+      }
+      const got = res.slots.find(s => s.slotId === request.id);
+      setSoloState(got && got.imageUrl ? {
+        status: 'resolved',
+        slot: got
+      } : {
+        status: 'unavailable'
+      });
+    }).catch(() => {
+      if (alive) {
+        setSoloState({
+          status: 'unavailable'
+        });
+      }
+    });
+    return () => {
+      alive = false;
+    };
+  }, [collector, resolve, request]);
+
+  // Subscribe to THIS slot only. `useSyncExternalStore` is the right shape
+  // here: the collector holds slot state outside React so resolving one slot
+  // does not re-render its siblings, and this is the supported way to read such
+  // a store without tearing. Memoised on the slot id so a re-render does not
+  // churn listeners.
+  const slotId = request == null ? void 0 : request.id;
+  const subscribe = (0, _react.useMemo)(() => onChange => collector && slotId ? collector.subscribe(slotId, onChange) : () => {}, [collector, slotId]);
+  const getSnapshot = (0, _react.useMemo)(() => () => collector && slotId ? collector.read(slotId) : SETTLED_UNAVAILABLE, [collector, slotId]);
+  const collectorState = (0, _react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const state = !request ?
+  // Not asking (disabled, or nothing worth retrieving on) is settled, not
+  // pending — a layout must not wait for an answer that will never come.
+  SETTLED_UNAVAILABLE : collector ? collectorState : soloState;
+  const resolvedUrl = state.status === 'resolved' ? state.slot.imageUrl : null;
+  return {
+    state,
+    // Pending deliberately renders nothing rather than the fallback: swapping
+    // fallback -> resolved a moment later is a visible flicker, and the layouts
+    // that use this already have a ground colour for the pending case.
+    url: state.status === 'pending' ? null : resolvedUrl ?? fallbackUrl ?? null,
+    backgroundColor: state.status === 'resolved' ? ((_state$slot$visualMet = state.slot.visualMetadata) == null ? void 0 : _state$slot$visualMet.backgroundColor) || undefined : undefined,
+    isPending: state.status === 'pending'
+  };
+}
+//# sourceMappingURL=useImageSlot.js.map

package/dist/cjs/hooks/useImageSlot.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_ComponentDependenciesContext","_ImageSlotContext","_composeSemantic","TOKEN_PREFIX","decodeToken","raw","body","startsWith","slice","length","decodeURIComponent","trim","slotIdFor","role","subjectKey","ratio","width","h","material","toFixed","i","Math","imul","charCodeAt","toString","SETTLED_UNAVAILABLE","status","useImageSlot","options","_state$slot$visualMet","subject","fallbackUrl","enabled","deps","useOptionalComponentDependencies","collector","useImageSlotCollector","resolve","resolveImageSet","request","useMemo","from","_subject$entityId","entityId","id","kind","renderWidthPx","semantic","token","composeSemantic","title","lead","soloState","setSoloState","useState","soloSentRef","useRef","useEffect","declare","current","alive","then","res","got","slots","find","s","slotId","imageUrl","slot","catch","subscribe","onChange","getSnapshot","read","collectorState","useSyncExternalStore","state","resolvedUrl","url","backgroundColor","visualMetadata","undefined","isPending"],"sources":["../../../src/hooks/useImageSlot.ts"],"sourcesContent":["/**\n * `useImageSlot` — the whole section-facing surface for images.\n *\n * A section describes the hole in its layout and what the picture should be\n * about. It does not name a request, a batch, or a set boundary; that omission\n * is deliberate and load-bearing, because it is what lets the boundary widen\n * from the section to the page later without touching a single component.\n *\n * Replaces the per-image `useResolvedImageSources` path, whose endpoint was\n * removed and, once restored, answers with an empty list.\n */\nimport { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';\nimport { useOptionalComponentDependencies } from '../context/ComponentDependenciesContext';\nimport { useImageSlotCollector } from '../context/ImageSlotContext';\nimport { composeSemantic } from '../image/composeSemantic';\nimport type {\n  ImageSlotRequest,\n  ImageSubject,\n  SlotState,\n} from '../image/imageSlotTypes';\n\nexport interface UseImageSlotOptions {\n  /** What the picture is for. Only affects how a layout reads the result. */\n  role?: 'background' | 'inline' | 'card';\n  /** width / height of the hole — a constant of the layout, never measured. */\n  ratio: number;\n  /**\n   * Delivered pixel width. Pass a value off the breakpoint ladder, never a\n   * measurement: a bucket keeps the slot id stable across a resize, keeps two\n   * sections at 798px and 802px one cacheable shape, and gives the CDN a small\n   * set of urls it can cache across visitors.\n   */\n  width?: 400 | 800 | 1200 | 1600;\n  subject: ImageSubject;\n  /** Rendered instead when the resolver cannot fill the slot — typically an\n   *  entity's own payload image. */\n  fallbackUrl?: string;\n  /**\n   * Declare nothing when false. For the case where the layout already HAS its\n   * picture — a direct url in props, a story fixture — and resolving would be a\n   * request whose answer is thrown away. Default true.\n   */\n  enabled?: boolean;\n}\n\nexport interface ResolvedImage {\n  state: SlotState;\n  /** What to actually render — the resolved url, else the caller's fallback,\n   *  else nothing. Saves every layout writing the same three-way check. */\n  url: string | null;\n  /** Paint the letterbox with this while an image is showing. */\n  backgroundColor?: string;\n  isPending: boolean;\n}\n\n/** The `web5://image/` prefix an author's token carries. */\nconst TOKEN_PREFIX = 'web5://image/';\n\nconst decodeToken = (raw: string): string => {\n  const body = raw.startsWith(TOKEN_PREFIX)\n    ? raw.slice(TOKEN_PREFIX.length)\n    : raw;\n  try {\n    return decodeURIComponent(body).trim();\n  } catch {\n    return body.trim();\n  }\n};\n\n/**\n * Content-derived, never an index and never a React key. A re-render\n * re-declares the same id so it does not re-request, and reordering items\n * cannot remap pictures onto different cards — which an index-based id would\n * do, visibly. Kept short and readable rather than cryptographic: it only has\n * to be stable, and unique within one request.\n */\nconst slotIdFor = (\n  role: string,\n  subjectKey: string,\n  ratio: number,\n  width: number,\n): string => {\n  let h = 0;\n  const material = `${role}|${subjectKey}|${ratio.toFixed(4)}|${width}`;\n  for (let i = 0; i < material.length; i++) {\n    h = (Math.imul(31, h) + material.charCodeAt(i)) | 0;\n  }\n  return `${role}-${(h >>> 0).toString(36)}`;\n};\n\n/** Module-level so `getSnapshot` returns a STABLE reference. Returning a fresh\n *  `{ status: 'unavailable' }` on every call makes `useSyncExternalStore`\n *  believe the store changed on every check, and it re-renders forever. */\nconst SETTLED_UNAVAILABLE: SlotState = { status: 'unavailable' };\n\nexport function useImageSlot(options: UseImageSlotOptions): ResolvedImage {\n  const {\n    role = 'background',\n    ratio,\n    width = 800,\n    subject,\n    fallbackUrl,\n    enabled = true,\n  } = options;\n\n  // Optional for the same reason the provider's is: a section rendered without\n  // dependencies configured should lose its picture, not throw.\n  const deps = useOptionalComponentDependencies();\n  const collector = useImageSlotCollector();\n  const resolve = deps?.resolveImageSet;\n\n  /** The declaration, derived purely from props. */\n  const request = useMemo<ImageSlotRequest | null>(() => {\n    if (!enabled) {\n      return null;\n    }\n\n    if (subject.from === 'entity') {\n      const entityId = subject.entityId?.trim();\n      if (!entityId) {\n        return null;\n      }\n      return {\n        id: slotIdFor(role, `e:${entityId}`, ratio, width),\n        kind: 'IMAGE_SLOT_KIND_ENTITY',\n        ratio,\n        renderWidthPx: width,\n        entityId,\n      };\n    }\n\n    const semantic =\n      subject.from === 'token'\n        ? decodeToken(subject.token ?? '')\n        : composeSemantic({ title: subject.title, lead: subject.lead });\n\n    // Too thin to retrieve on is not a query worth sending. `composeSemantic`\n    // returns empty rather than guessing, and a token can be empty too\n    // (`![alt](web5://image/)`).\n    if (!semantic) {\n      return null;\n    }\n\n    return {\n      id: slotIdFor(role, `s:${semantic}`, ratio, width),\n      kind: 'IMAGE_SLOT_KIND_EDITORIAL',\n      ratio,\n      renderWidthPx: width,\n      semantic,\n    };\n  }, [enabled, role, ratio, width, subject]);\n\n  // Used only when no collector is mounted above — a host that has not adopted\n  // the section wrapper's provider. Same answer, no batching with siblings.\n  const [soloState, setSoloState] = useState<SlotState>({ status: 'pending' });\n  const soloSentRef = useRef<string | null>(null);\n\n  useEffect(() => {\n    if (!request) {\n      return;\n    }\n    if (collector) {\n      collector.declare(request);\n      return;\n    }\n    if (soloSentRef.current === request.id) {\n      return;\n    }\n    soloSentRef.current = request.id;\n\n    if (!resolve) {\n      setSoloState({ status: 'unavailable' });\n      return;\n    }\n\n    let alive = true;\n    resolve([request])\n      .then((res) => {\n        if (!alive) {\n          return;\n        }\n        const got = res.slots.find((s) => s.slotId === request.id);\n        setSoloState(\n          got && got.imageUrl\n            ? { status: 'resolved', slot: got }\n            : { status: 'unavailable' },\n        );\n      })\n      .catch(() => {\n        if (alive) {\n          setSoloState({ status: 'unavailable' });\n        }\n      });\n\n    return () => {\n      alive = false;\n    };\n  }, [collector, resolve, request]);\n\n  // Subscribe to THIS slot only. `useSyncExternalStore` is the right shape\n  // here: the collector holds slot state outside React so resolving one slot\n  // does not re-render its siblings, and this is the supported way to read such\n  // a store without tearing. Memoised on the slot id so a re-render does not\n  // churn listeners.\n  const slotId = request?.id;\n  const subscribe = useMemo(\n    () => (onChange: () => void) =>\n      collector && slotId ? collector.subscribe(slotId, onChange) : () => {},\n    [collector, slotId],\n  );\n  const getSnapshot = useMemo(\n    () => () =>\n      collector && slotId ? collector.read(slotId) : SETTLED_UNAVAILABLE,\n    [collector, slotId],\n  );\n  const collectorState = useSyncExternalStore(\n    subscribe,\n    getSnapshot,\n    getSnapshot,\n  );\n\n  const state: SlotState = !request\n    ? // Not asking (disabled, or nothing worth retrieving on) is settled, not\n      // pending — a layout must not wait for an answer that will never come.\n      SETTLED_UNAVAILABLE\n    : collector\n      ? collectorState\n      : soloState;\n\n  const resolvedUrl = state.status === 'resolved' ? state.slot.imageUrl : null;\n\n  return {\n    state,\n    // Pending deliberately renders nothing rather than the fallback: swapping\n    // fallback -> resolved a moment later is a visible flicker, and the layouts\n    // that use this already have a ground colour for the pending case.\n    url:\n      state.status === 'pending' ? null : (resolvedUrl ?? fallbackUrl ?? null),\n    backgroundColor:\n      state.status === 'resolved'\n        ? state.slot.visualMetadata?.backgroundColor || undefined\n        : undefined,\n    isPending: state.status === 'pending',\n  };\n}\n"],"mappings":"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","ignoreList":[]}

package/dist/cjs/image/composeSemantic.js

@@ -0,0 +1,94 @@
+"use strict";
+
+exports.__esModule = true;
+exports.composeSemantic = composeSemantic;
+/**
+ * Turn a section's own words into a retrieval phrase.
+ *
+ * The section hands over its RAW props — a title, a lead paragraph — not a
+ * query string. Composing is this module's job, in one place, because the two
+ * call sites that do it today invent their own phrase, do not agree with each
+ * other, and neither is tested:
+ *
+ *   w5-client-circana/src/components/sections/GenericEntitySection.tsx:144
+ *     `web5://image/${title}`                     — raw, so `**Nike** collections`
+ *                                                   is searched WITH its asterisks
+ *   w5-client-circana/src/components/sections/ResearchSection.tsx:68
+ *     `web5://image/${encodeURIComponent(title)}` — same idea, escaped
+ *
+ * Centralising it is most of what the text-derived case is worth.
+ *
+ * Lifted from the seed client package (ADR 0225): it started there because the
+ * CDN build externalises core, so a core change could not be seen through
+ * `?clientBundleUrl=` until it had been published. 0223 always assigned it
+ * here, and this is that move.
+ */
+
+/** Longer than this and the tail stops helping retrieval and starts diluting it. */
+const MAX_LENGTH = 120;
+
+/** Below this there is no query worth sending — better to render no picture
+ *  than to retrieve on a word like "More". */
+const MIN_LENGTH = 3;
+const stripMarkdown = raw => raw
+// images before links: ![alt](src) would otherwise leave a stray `!`
+.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+// emphasis / strong / strike / inline code — keep the words, drop the marks
+.replace(/(\*\*\*|\*\*|\*|___|__|_|~~|`)/g, '')
+// leading heading hashes and blockquote marks
+.replace(/^\s*#{1,6}\s*/gm, '').replace(/^\s*>\s?/gm, '')
+// html tags an author or the parser may have left behind
+.replace(/<[^>]+>/g, ' ');
+const tidy = raw => stripMarkdown(raw).replace(/\s+/g, ' ').trim()
+// trailing punctuation is noise in a retrieval phrase
+.replace(/[\s.,;:!?—–-]+$/g, '').trim();
+
+/**
+ * Clamp without cutting a word in half. Slicing at a fixed length leaves
+ * fragments like "the kinds of product" — observed in the first real run — and
+ * a dangling partial word is noise in a retrieval phrase, not a shorter
+ * version of it. Falls back to a hard slice only when the budget cannot fit
+ * even one word.
+ */
+const clampToWord = (raw, max) => {
+  if (raw.length <= max) {
+    return raw;
+  }
+  // +1 so a boundary landing exactly on the budget still counts as a break.
+  const cut = raw.slice(0, max + 1);
+  const lastBreak = cut.lastIndexOf(' ');
+  const out = lastBreak > 0 ? cut.slice(0, lastBreak) : raw.slice(0, max);
+  return out.replace(/[\s.,;:!?—–-]+$/g, '').trim();
+};
+
+/** The first clause carries the subject; what follows is usually qualification. */
+const firstClause = raw => {
+  const m = raw.match(/^[^.!?;]+/);
+  return (m ? m[0] : raw).trim();
+};
+/**
+ * Returns the phrase, or `''` when what survives is too thin to retrieve on —
+ * the caller then declares no slot at all rather than sending a bad query.
+ */
+function composeSemantic({
+  title,
+  lead,
+  sectionSemantic
+}) {
+  // A mission, when there is one, is the whole answer.
+  const mission = tidy(sectionSemantic ?? '');
+  if (mission.length >= MIN_LENGTH) {
+    return clampToWord(mission, MAX_LENGTH);
+  }
+  const head = tidy(title ?? '');
+  const body = firstClause(tidy(lead ?? ''));
+  const joined = [head, body].filter(Boolean).join('. ');
+  if (joined.length < MIN_LENGTH) return '';
+  if (joined.length <= MAX_LENGTH) return joined;
+
+  // Over budget: keep the title whole if it fits, since it is the stronger
+  // signal, and spend whatever is left on the lead.
+  if (head.length >= MAX_LENGTH) return clampToWord(head, MAX_LENGTH);
+  return clampToWord(joined, MAX_LENGTH);
+}
+//# sourceMappingURL=composeSemantic.js.map

package/dist/cjs/image/composeSemantic.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["MAX_LENGTH","MIN_LENGTH","stripMarkdown","raw","replace","tidy","trim","clampToWord","max","length","cut","slice","lastBreak","lastIndexOf","out","firstClause","m","match","composeSemantic","title","lead","sectionSemantic","mission","head","body","joined","filter","Boolean","join"],"sources":["../../../src/image/composeSemantic.ts"],"sourcesContent":["/**\n * Turn a section's own words into a retrieval phrase.\n *\n * The section hands over its RAW props — a title, a lead paragraph — not a\n * query string. Composing is this module's job, in one place, because the two\n * call sites that do it today invent their own phrase, do not agree with each\n * other, and neither is tested:\n *\n *   w5-client-circana/src/components/sections/GenericEntitySection.tsx:144\n *     `web5://image/${title}`                     — raw, so `**Nike** collections`\n *                                                   is searched WITH its asterisks\n *   w5-client-circana/src/components/sections/ResearchSection.tsx:68\n *     `web5://image/${encodeURIComponent(title)}` — same idea, escaped\n *\n * Centralising it is most of what the text-derived case is worth.\n *\n * Lifted from the seed client package (ADR 0225): it started there because the\n * CDN build externalises core, so a core change could not be seen through\n * `?clientBundleUrl=` until it had been published. 0223 always assigned it\n * here, and this is that move.\n */\n\n/** Longer than this and the tail stops helping retrieval and starts diluting it. */\nconst MAX_LENGTH = 120;\n\n/** Below this there is no query worth sending — better to render no picture\n *  than to retrieve on a word like \"More\". */\nconst MIN_LENGTH = 3;\n\nconst stripMarkdown = (raw: string): string =>\n  raw\n    // images before links: ![alt](src) would otherwise leave a stray `!`\n    .replace(/!\\[([^\\]]*)\\]\\([^)]*\\)/g, '$1')\n    .replace(/\\[([^\\]]*)\\]\\([^)]*\\)/g, '$1')\n    // emphasis / strong / strike / inline code — keep the words, drop the marks\n    .replace(/(\\*\\*\\*|\\*\\*|\\*|___|__|_|~~|`)/g, '')\n    // leading heading hashes and blockquote marks\n    .replace(/^\\s*#{1,6}\\s*/gm, '')\n    .replace(/^\\s*>\\s?/gm, '')\n    // html tags an author or the parser may have left behind\n    .replace(/<[^>]+>/g, ' ');\n\nconst tidy = (raw: string): string =>\n  stripMarkdown(raw)\n    .replace(/\\s+/g, ' ')\n    .trim()\n    // trailing punctuation is noise in a retrieval phrase\n    .replace(/[\\s.,;:!?—–-]+$/g, '')\n    .trim();\n\n/**\n * Clamp without cutting a word in half. Slicing at a fixed length leaves\n * fragments like \"the kinds of product\" — observed in the first real run — and\n * a dangling partial word is noise in a retrieval phrase, not a shorter\n * version of it. Falls back to a hard slice only when the budget cannot fit\n * even one word.\n */\nconst clampToWord = (raw: string, max: number): string => {\n  if (raw.length <= max) {\n    return raw;\n  }\n  // +1 so a boundary landing exactly on the budget still counts as a break.\n  const cut = raw.slice(0, max + 1);\n  const lastBreak = cut.lastIndexOf(' ');\n  const out = lastBreak > 0 ? cut.slice(0, lastBreak) : raw.slice(0, max);\n  return out.replace(/[\\s.,;:!?—–-]+$/g, '').trim();\n};\n\n/** The first clause carries the subject; what follows is usually qualification. */\nconst firstClause = (raw: string): string => {\n  const m = raw.match(/^[^.!?;]+/);\n  return (m ? m[0] : raw).trim();\n};\n\nexport interface ComposeSemanticInput {\n  /** The section's headline. */\n  title?: string;\n  /** Its lead paragraph or body copy. */\n  lead?: string;\n  /** The descriptor's own `semantic` / mission, when the host supplies one.\n   *  Outranks the prose: it is what the orchestrator meant the section to be\n   *  about, which is a better subject than what it happened to say. */\n  sectionSemantic?: string;\n}\n\n/**\n * Returns the phrase, or `''` when what survives is too thin to retrieve on —\n * the caller then declares no slot at all rather than sending a bad query.\n */\nexport function composeSemantic({\n  title,\n  lead,\n  sectionSemantic,\n}: ComposeSemanticInput): string {\n  // A mission, when there is one, is the whole answer.\n  const mission = tidy(sectionSemantic ?? '');\n  if (mission.length >= MIN_LENGTH) {\n    return clampToWord(mission, MAX_LENGTH);\n  }\n\n  const head = tidy(title ?? '');\n  const body = firstClause(tidy(lead ?? ''));\n\n  const joined = [head, body].filter(Boolean).join('. ');\n  if (joined.length < MIN_LENGTH) return '';\n\n  if (joined.length <= MAX_LENGTH) return joined;\n\n  // Over budget: keep the title whole if it fits, since it is the stronger\n  // signal, and spend whatever is left on the lead.\n  if (head.length >= MAX_LENGTH) return clampToWord(head, MAX_LENGTH);\n  return clampToWord(joined, MAX_LENGTH);\n}\n"],"mappings":"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","ignoreList":[]}