Engine, DOM, and layout readiness

Raw Gameface initialization has several boundaries. Publish the native surface size only after the engine is ready, the document is built, and layout has settled.

function waitForDomBuilt() {
  return new Promise((resolve) => {
    if (window.isDomBuilt) {
      resolve();
      return;
    }
    engine.on('self.onDomBuilt', resolve);
  });
}

function nextAnimationFrame() {
  return new Promise((resolve) => requestAnimationFrame(resolve));
}

engine.whenReady
  .then(() => waitForDomBuilt())
  .then(() => nextAnimationFrame())
  .then(() => nextAnimationFrame())
  .then(() => {
    const panel = document.querySelector('.feature-panel');
    const rect = panel.getBoundingClientRect();
    viewEnv.resizeViewPx(Math.ceil(rect.width), Math.ceil(rect.height));
    window.model.onReady();
  });
Boundary What it proves What it does not prove
Python view created The layout ID and view class were accepted. The window has a live parent or area.
Wulf window loaded The content entered the Wulf window lifecycle. The Gameface engine and DOM are ready.
engine.whenReady Gameface APIs can be used. The authored panel has completed layout.
DOM-built readiness The document structure exists. Fonts, React updates, and final layout frames are settled.
resizeViewPx The native surface receives an explicit size. Python has already repositioned or clamped the resized window.

Zero-size surfaces and fallbacks

A raw panel can visibly render while the Gameface view and Wulf window still report 0 × 0. If the current client gives up waiting for layout, it may assign a fallback native surface size. Treat the fallback as version-sensitive and fix the readiness sequence instead of designing around that number.

  • Call resizeViewPx after engine readiness, DOM construction, and at least two layout frames.
  • Recenter or reclamp the Wulf window only after JavaScript confirms the final size.
  • Keep Python hit-test dimensions, CSS dimensions, and Gameface resize dimensions identical.
  • When a panel appears clipped or stops short of an edge, inspect the native surface size before changing CSS margins.

Read by topic

Choose a focused chapter. Complete examples and reference details are preserved on their topic pages.