Header/footer images: correct data model + DOCX export, but never render on live canvas (skeDrawings stays empty)

[abhishekrajput-web]

Version

@univerjs/engine-render 0.15.5 (all @univerjs/* packages pinned to ^0.15.3, all resolving to the same 0.15.x line).

Summary

An image inserted into a document's header or footer segment — via either (a) building the IDocumentData snapshot directly before createUniverDoc, or (b) Univer's own doc.command.insert-doc-image command targeted at the header/footer's segmentId — produces a fully correct document model (confirmed: DocumentDataModel.drawings, the header/footer body's customBlocks, and documentStyle.defaultHeaderId/defaultFooterId are all correct, and a from-scratch DOCX export built by reading that model directly renders the image correctly on every page). But the image never renders on the live canvas. Direct inspection of DocumentSkeleton.getSkeletonData().skeHeaders/skeFooters shows the header/footer page's skeDrawings Map is always empty, even though the equivalent flow for a BODY image (inserted via the toolbar's own Insert Image button) populates skeDrawings correctly and renders immediately.

Repro

1. Create a document with univerAPI.createUniverDoc(snapshot).
2. In snapshot, set documentStyle.defaultHeaderId = "hdr1".
3. Set snapshot.headers = { hdr1: { headerId: "hdr1", body: { dataStream: "\r\b\r\n", customBlocks: [{ startIndex: 1, blockType: 0, blockId: "img1" }], paragraphs: [{ startIndex: 3 }] } } } (the \b at index 1 is the custom-block placeholder character).
4. Set snapshot.drawings = { img1: { unitId, subUnitId: unitId, drawingId: "img1", drawingType: 0, transform: { width: 80, height: 40, left: 0, top: 0, angle: 0 }, docTransform: { size: { width: 80, height: 40 }, positionH: { relativeFrom: 2, posOffset: 0 }, positionV: { relativeFrom: 2, posOffset: 0 }, angle: 0 }, layoutType: 0, imageSourceType: "BASE64", source: "data:image/png;base64,..." } }.
5. Set snapshot.drawingsOrder = ["img1"] (required — DocDrawingController.loadDrawingDataForUnit reads documentDataModel.getDrawingsOrder(), which wraps snapshot.drawingsOrder only; it never reads headerFooterDrawingsOrder, confirmed by grepping the shipped bundle — that field is declared on IReferenceSource but does not appear anywhere in any @univerjs/* runtime bundle).
6. Load the document. Observe the header text renders, but the image does not.
7. Inspect injector.get(IRenderManagerService).getRenderById(unitId).with(DocSkeletonManagerService).getSkeleton().getSkeletonData(). For every page, skeHeaders.get("hdr1").get(pageWidth).skeDrawings.size === 0.

Reproduces identically whether the drawing is baked into the snapshot before creation, or inserted afterward through commandService.executeCommand("doc.command.insert-doc-image", { drawings: [...] }) with the active selection's segmentId set to "hdr1" (confirmed via DocSelectionManagerService.replaceDocRanges(...), executed successfully with ok: true, producing a correctly-shaped RichTextEditingMutation).

What we've ruled out

• Not a data problem. A from-scratch DOCX exporter that reads snapshot.headers[headerId].body.customBlocks and snapshot.drawings directly (bypassing Univer's canvas entirely) produces a correct Word document with the image in the header/footer of every page, from the exact same snapshot that fails to render on canvas.
• Not a stale-skeleton-cache problem. Confirmed via diagnostic that skeHeaders.get(headerId) has a freshly-built entry for the current page width at the time of the failed read (i.e., the header layout pass genuinely ran on this exact data), not a cached pre-image skeleton.
• Not a "positioning controller doesn't re-run" problem. DocDrawingTransformerController's _refreshDrawing (which walks each page's skeHeaders/skeFooters and calls drawingManagerService.refreshTransform per skeDrawings entry) only subscribes to currentSkeleton$ once at construction, so we suspected a later insert's positioning was simply never re-triggered. We replicated its exact logic manually (using only public APIs — Liquid, DocSkeletonManagerService.getSkeleton().getSkeletonData(), IDrawingManagerService.getDrawingData()), called it after every drawing registration (IDrawingManagerService's add$ firing), and it still finds skeDrawings.size === 0 every time. There is nothing to position because nothing was ever added to skeDrawings in the first place.
• Not a headerFooterDrawingsOrder problem. This field exists on IReferenceSource's type declaration but does not appear anywhere in any shipped @univerjs/* 0.15.5 runtime bundle (grep -rl headerFooterDrawingsOrder node_modules/@univerjs/*/lib/es/*.js returns nothing) — nothing reads it. We set it anyway (alongside drawingsOrder) with no effect.
• Body-segment images work correctly, both inserted programmatically via the same doc.command.insert-doc-image command and via the toolbar — confirmed live, rendering immediately with correct skeDrawings population.

What we found tracing the shipped (minified) engine-render bundle

No source maps are published, so this is necessarily minified-symbol tracing, but the control flow is unambiguous:

• The header/footer page-layout function (headerId/footerId-keyed skeleton builder) correctly receives the header/footer's own view-model tree entry from headerTreeMap/footerTreeMap.
• It calls into the paragraph-layout walker, passing viewModelNode.getChildren()[0] as the tree-walk root — a section/tree child node, not the header/footer's own DocumentViewModel-wrapping instance.
• That child node is threaded, unchanged, through two more function calls, arriving at the function that resolves a paragraph's custom-block indices to drawings:

  const I = g[A], M = t.getCustomBlock(I);
  if (M == null) continue;
  const { blockId: P } = M, N = u[P];
  N.layoutType === Z1.INLINE ? C.set(P, s5(N)) : w.set(P, s5(N));

  g is the paragraph node's own blocks array (built by scanning this.content for the custom-block placeholder character and pushing this.startIndex + offset — confirmed these are absolute document-relative indices). t.getCustomBlock(I) should resolve against _customBlockCache, which is built purely from getBody().customBlocks on whichever DocumentViewModel-like instance t actually is (confirmed via source: _buildCustomBlockCache iterates this.getBody()?.customBlocks ?? [] and keys by startIndex).
• We independently confirmed via a live diagnostic that the header's OWN view-model instance (queried directly, not through this call chain) correctly resolves getCustomBlockWithoutSetCurrentIndex (a different, absolute-index method on the same class) against a correctly-populated customBlocks array at the right startIndex. So the DATA that _customBlockCache should be built from is present and correct on the correct object.
• We were not able to fully confirm, purely from the minified bundle, whether t in t.getCustomBlock(I) is genuinely a different object than the one we queried directly (in which case its own _customBlockCache may simply never have been built/attached), or whether it correctly delegates back to the header/footer's real view model (in which case the failure is elsewhere in this same function, e.g. in how g's indices are computed for a header/footer paragraph specifically, or in how u — the drawings object passed via the layout config — is scoped). Either way, M == null (silently, no thrown error, consistent with the continue producing zero populated entries and zero crashes) is the exact and only point at which the header/footer path diverges from the working body path for the identical shape of underlying data.

Ask

Could someone with the actual (non-minified) TypeScript source confirm, in the header/footer paragraph-layout code path (as opposed to the body path), what object t actually is at the point of t.getCustomBlock(I), and whether it's expected to have a populated _customBlockCache for a header/footer segment? If this is a known gap, is there a supported workaround (a specific field to set, a command to call, a controller to trigger) that gets header/footer drawings into skeDrawings today, short of monkey-patching the skeleton after layout?

Happy to provide a minimal repro repository if useful.