@vectojs/markdown 0.18.0 → 0.18.2

package/dist/Markdown.d.ts

@@ -94,14 +94,40 @@ export declare class Markdown extends UIComponent {
     saveFile: (filename: string, content: string, mimeType: string) => void;
     private activeBlockMetrics;
     /**
-     * Called after a streamed append has re-laid-out the document.
-     *
-     * Not required for a `VirtualList` to track a streaming row's height: the list
-     * re-reads `height` on every mounted row each frame, so it sees this entity grow
-     * without being told. Prefer that over wiring this up — it fires from the append
-     * path only, **not** from `setContent()`, so it is not a complete size signal.
+     * Called after this entity's own `width`/`height` changed because the document
+     * was re-laid-out. **This is the hook to wire up when a host has to move or
+     * resize anything positioned below the document.**
+     *
+     * Fires from three paths, all of which republish `width`/`height` from
+     * `content`:
+     *
+     * - a streamed append (`updateTokens`),
+     * - a width change ({@link setMaxWidth}),
+     * - a paragraph image whose decoded bitmap corrected the guessed aspect ratio
+     *   (`reflowAfterImageResize`) — the guess is a flat 16:10, so this one fires
+     *   on essentially every document containing an image, and a host that misses
+     *   it leaves every block below the image overlapping it.
+     *
+     * It does **not** fire from `setContent()`, which replaces the whole document
+     * and is a call the host already made, so this is a re-layout signal rather
+     * than a complete size signal.
+     *
+     * A `VirtualList` needs none of this to track a streaming row: it re-reads
+     * `height` on every mounted row each frame, so it sees this entity grow without
+     * being told. Prefer that where it applies. Reach for this callback when the
+     * host owns absolute positions of its own — a page that stacks navigation, a
+     * footer and a scroll height under the document has to recompute them here.
+     *
+     * There is no `onHeightChanged`. That name has been assigned by real callers
+     * through an `as unknown as` cast, which compiles, silences the type error and
+     * then never fires; if a layout callback appears dead, check the name first.
      */
     onLayoutUpdated?: () => void;
+    /**
+     * Latch for the miswired-hook warning, so a streaming document warns once
+     * rather than on every chunk.
+     */
+    private hasWarnedLayoutHookName;
     /**
      * The document's BODY text — everything after any front matter block.
      *
@@ -574,6 +600,53 @@ export declare class Markdown extends UIComponent {
      */
     private affordanceButtonOptions;
     private paragraphImage;
+    /**
+     * Re-position every block after an image whose decode corrected its box.
+     *
+     * The 16:10 guess above is rarely the real aspect ratio, so without this every
+     * sibling below the image keeps the position computed from the guess, and an
+     * image taller than the guess renders *under* the paragraph that follows it.
+     *
+     * A bare `this.content.layout()` is not enough, and that is the part worth
+     * knowing: `Stack.layout()` is **not recursive**. It positions its children
+     * from the size each child reports at the moment it runs and never asks a
+     * child to recompute its own box first. Every image sits behind at least one
+     * intermediate container that caches a height — an image-bearing paragraph is
+     * a `Stack`, a list item's or blockquote's image is wrapped in a
+     * `MarkdownContainer` — so laying out `content` alone re-reads the very boxes
+     * the decode just invalidated. Measured on `94d6da3`: a 600x900 portrait in
+     * `![alt](…)\n\nAfter.` corrects `Image.height` 480 to 900 while its parent
+     * `Stack` stays 480 and the following paragraph stays at `y=496`.
+     *
+     * So resync bottom-up, from the image's own parent up to `content`, and each
+     * level sees a freshly-sized child before it positions anything.
+     */
+    private reflowAfterImageResize;
+    /**
+     * Publish a completed re-layout to the host.
+     *
+     * Every path that republishes `width`/`height` from `content` ends here rather
+     * than calling {@link onLayoutUpdated} directly, so the misuse check below is
+     * reached however the re-layout was triggered.
+     *
+     * The check exists because the failure it catches is silent and was found in
+     * production, not in review. A host wired its reflow to `onHeightChanged` — a
+     * name this class has never had — through an `as unknown as` cast. The cast
+     * satisfied the compiler, the callback never fired, and every post containing
+     * an image stayed laid out against the guessed 16:10 aspect ratio with a stale
+     * document scroll height. Nothing in the type system, the tests or the console
+     * said anything. A property that is *only ever assigned* has no read site to
+     * fail, so the one place that can notice is the moment we would have called it.
+     */
+    private notifyLayoutUpdated;
+    /**
+     * Re-derive one `MarkdownContainer`'s cached box from its children.
+     *
+     * Mirrors how {@link reflowToken}'s `blockquote` / `container` arms and every
+     * construction site derive it, so an image resize and a width change converge
+     * on the same geometry rather than each having its own arithmetic.
+     */
+    private resyncWrapperBox;
     /** One table cell entity, shared by the render arm and the streamed-table path. */
     private tableCellRichText;
     /**

package/dist/index.js

@@ -2787,6 +2787,12 @@ import_marked.marked.use({
     }
   ]
 });
+var MISWIRED_LAYOUT_HOOK_NAMES = [
+  "onHeightChanged",
+  "onHeightChange",
+  "onLayoutUpdate",
+  "onResize"
+];
 var markdownWorker = null;
 var workerIdCounter = 0;
 var workerInstanceCounter = 0;
@@ -2854,14 +2860,40 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
   saveFile;
   activeBlockMetrics = null;
   /**
-   * Called after a streamed append has re-laid-out the document.
+   * Called after this entity's own `width`/`height` changed because the document
+   * was re-laid-out. **This is the hook to wire up when a host has to move or
+   * resize anything positioned below the document.**
+   *
+   * Fires from three paths, all of which republish `width`/`height` from
+   * `content`:
+   *
+   * - a streamed append (`updateTokens`),
+   * - a width change ({@link setMaxWidth}),
+   * - a paragraph image whose decoded bitmap corrected the guessed aspect ratio
+   *   (`reflowAfterImageResize`) — the guess is a flat 16:10, so this one fires
+   *   on essentially every document containing an image, and a host that misses
+   *   it leaves every block below the image overlapping it.
    *
-   * Not required for a `VirtualList` to track a streaming row's height: the list
-   * re-reads `height` on every mounted row each frame, so it sees this entity grow
-   * without being told. Prefer that over wiring this up — it fires from the append
-   * path only, **not** from `setContent()`, so it is not a complete size signal.
+   * It does **not** fire from `setContent()`, which replaces the whole document
+   * and is a call the host already made, so this is a re-layout signal rather
+   * than a complete size signal.
+   *
+   * A `VirtualList` needs none of this to track a streaming row: it re-reads
+   * `height` on every mounted row each frame, so it sees this entity grow without
+   * being told. Prefer that where it applies. Reach for this callback when the
+   * host owns absolute positions of its own — a page that stacks navigation, a
+   * footer and a scroll height under the document has to recompute them here.
+   *
+   * There is no `onHeightChanged`. That name has been assigned by real callers
+   * through an `as unknown as` cast, which compiles, silences the type error and
+   * then never fires; if a layout callback appears dead, check the name first.
    */
   onLayoutUpdated;
+  /**
+   * Latch for the miswired-hook warning, so a streaming document warns once
+   * rather than on every chunk.
+   */
+  hasWarnedLayoutHookName = false;
   /**
    * The document's BODY text — everything after any front matter block.
    *
@@ -3312,7 +3344,7 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
     this.content.layout();
     this.width = this.content.width;
     this.height = this.content.height;
-    this.onLayoutUpdated?.();
+    this.notifyLayoutUpdated();
     this.scene?.markDirty();
     return this;
   }
@@ -4130,16 +4162,116 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
       radius: this.theme.imageRadius,
       onLoad: () => {
         const bmp = img.bitmap;
+        const previousWidth = img.width;
+        const previousHeight = img.height;
         if (bmp && bmp.naturalWidth && bmp.naturalHeight) {
           const aspect = bmp.naturalHeight / bmp.naturalWidth;
           img.width = Math.min(bmp.naturalWidth, availableWidth);
           img.height = Math.round(img.width * aspect);
         }
+        if (img.width !== previousWidth || img.height !== previousHeight) {
+          this.reflowAfterImageResize(img);
+        }
         this.scene?.markDirty();
       }
     });
     return img;
   }
+  /**
+   * Re-position every block after an image whose decode corrected its box.
+   *
+   * The 16:10 guess above is rarely the real aspect ratio, so without this every
+   * sibling below the image keeps the position computed from the guess, and an
+   * image taller than the guess renders *under* the paragraph that follows it.
+   *
+   * A bare `this.content.layout()` is not enough, and that is the part worth
+   * knowing: `Stack.layout()` is **not recursive**. It positions its children
+   * from the size each child reports at the moment it runs and never asks a
+   * child to recompute its own box first. Every image sits behind at least one
+   * intermediate container that caches a height — an image-bearing paragraph is
+   * a `Stack`, a list item's or blockquote's image is wrapped in a
+   * `MarkdownContainer` — so laying out `content` alone re-reads the very boxes
+   * the decode just invalidated. Measured on `94d6da3`: a 600x900 portrait in
+   * `![alt](…)\n\nAfter.` corrects `Image.height` 480 to 900 while its parent
+   * `Stack` stays 480 and the following paragraph stays at `y=496`.
+   *
+   * So resync bottom-up, from the image's own parent up to `content`, and each
+   * level sees a freshly-sized child before it positions anything.
+   */
+  reflowAfterImageResize(img) {
+    let reachesContent = false;
+    for (let node = img.parent; node; node = node.parent) {
+      if (node === this.content) {
+        reachesContent = true;
+        break;
+      }
+    }
+    if (!reachesContent) return;
+    for (let node = img.parent; node; node = node.parent) {
+      if (node instanceof import_ui4.Stack) node.layout();
+      else if (node instanceof MarkdownContainer) this.resyncWrapperBox(node);
+      if (node === this.content) break;
+    }
+    this.width = this.content.width;
+    this.height = this.content.height;
+    this.notifyLayoutUpdated();
+  }
+  /**
+   * Publish a completed re-layout to the host.
+   *
+   * Every path that republishes `width`/`height` from `content` ends here rather
+   * than calling {@link onLayoutUpdated} directly, so the misuse check below is
+   * reached however the re-layout was triggered.
+   *
+   * The check exists because the failure it catches is silent and was found in
+   * production, not in review. A host wired its reflow to `onHeightChanged` — a
+   * name this class has never had — through an `as unknown as` cast. The cast
+   * satisfied the compiler, the callback never fired, and every post containing
+   * an image stayed laid out against the guessed 16:10 aspect ratio with a stale
+   * document scroll height. Nothing in the type system, the tests or the console
+   * said anything. A property that is *only ever assigned* has no read site to
+   * fail, so the one place that can notice is the moment we would have called it.
+   */
+  notifyLayoutUpdated() {
+    if (this.onLayoutUpdated) {
+      this.onLayoutUpdated();
+      return;
+    }
+    if (!this.hasWarnedLayoutHookName) {
+      const wrongName = MISWIRED_LAYOUT_HOOK_NAMES.find(
+        (name) => typeof this[name] === "function"
+      );
+      if (wrongName) {
+        this.hasWarnedLayoutHookName = true;
+        console.warn(
+          `[VectoJS] Markdown.${wrongName} is not a VectoJS callback and will never fire. The document just re-laid-out and nothing was notified. Assign \`onLayoutUpdated\` instead \u2014 anything positioned below the document needs it, and a paragraph image corrects its guessed aspect ratio on decode, so a missed signal leaves following blocks overlapping the image.`
+        );
+      }
+    }
+  }
+  /**
+   * Re-derive one `MarkdownContainer`'s cached box from its children.
+   *
+   * Mirrors how {@link reflowToken}'s `blockquote` / `container` arms and every
+   * construction site derive it, so an image resize and a width change converge
+   * on the same geometry rather than each having its own arithmetic.
+   */
+  resyncWrapperBox(wrapper) {
+    const innerStack = wrapper.children.find((c) => c instanceof import_ui4.Stack);
+    const border = wrapper.children.find((c) => c instanceof QuoteBorder);
+    const background = wrapper.children.find((c) => c instanceof ContainerBackground);
+    if (border || background) {
+      const contentHeight = innerStack?.height || 20;
+      if (border instanceof QuoteBorder) border.height = contentHeight;
+      if (background instanceof ContainerBackground) background.height = contentHeight;
+      wrapper.height = Math.max(background?.height ?? 0, border?.height ?? 0, contentHeight);
+      return;
+    }
+    const child = wrapper.children[0];
+    if (!child) return;
+    wrapper.width = child.x + child.width;
+    wrapper.height = child.height;
+  }
   /** One table cell entity, shared by the render arm and the streamed-table path. */
   tableCellRichText(cell, header, t) {
     return new import_ui4.RichText(this.tableCellSpans(cell, t), {
@@ -4251,6 +4383,8 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
       const wrapper = new MarkdownContainer();
       el.x = indent;
       wrapper.add(el);
+      wrapper.width = el.width + indent;
+      wrapper.height = el.height;
       stack.add(wrapper);
     }
     for (let i = leadChildren.length; i < children.length; i++) {
@@ -4924,9 +5058,7 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
     this.width = this.content.width;
     this.height = this.content.height;
     this.scene?.markDirty();
-    if (this.onLayoutUpdated) {
-      this.onLayoutUpdated();
-    }
+    this.notifyLayoutUpdated();
   }
   /**
    * Render one nested block with a temporary width/margin context while

package/dist/index.mjs

@@ -2735,6 +2735,12 @@ marked.use({
     }
   ]
 });
+var MISWIRED_LAYOUT_HOOK_NAMES = [
+  "onHeightChanged",
+  "onHeightChange",
+  "onLayoutUpdate",
+  "onResize"
+];
 var markdownWorker = null;
 var workerIdCounter = 0;
 var workerInstanceCounter = 0;
@@ -2802,14 +2808,40 @@ var Markdown = class _Markdown extends UIComponent3 {
   saveFile;
   activeBlockMetrics = null;
   /**
-   * Called after a streamed append has re-laid-out the document.
+   * Called after this entity's own `width`/`height` changed because the document
+   * was re-laid-out. **This is the hook to wire up when a host has to move or
+   * resize anything positioned below the document.**
+   *
+   * Fires from three paths, all of which republish `width`/`height` from
+   * `content`:
+   *
+   * - a streamed append (`updateTokens`),
+   * - a width change ({@link setMaxWidth}),
+   * - a paragraph image whose decoded bitmap corrected the guessed aspect ratio
+   *   (`reflowAfterImageResize`) — the guess is a flat 16:10, so this one fires
+   *   on essentially every document containing an image, and a host that misses
+   *   it leaves every block below the image overlapping it.
    *
-   * Not required for a `VirtualList` to track a streaming row's height: the list
-   * re-reads `height` on every mounted row each frame, so it sees this entity grow
-   * without being told. Prefer that over wiring this up — it fires from the append
-   * path only, **not** from `setContent()`, so it is not a complete size signal.
+   * It does **not** fire from `setContent()`, which replaces the whole document
+   * and is a call the host already made, so this is a re-layout signal rather
+   * than a complete size signal.
+   *
+   * A `VirtualList` needs none of this to track a streaming row: it re-reads
+   * `height` on every mounted row each frame, so it sees this entity grow without
+   * being told. Prefer that where it applies. Reach for this callback when the
+   * host owns absolute positions of its own — a page that stacks navigation, a
+   * footer and a scroll height under the document has to recompute them here.
+   *
+   * There is no `onHeightChanged`. That name has been assigned by real callers
+   * through an `as unknown as` cast, which compiles, silences the type error and
+   * then never fires; if a layout callback appears dead, check the name first.
    */
   onLayoutUpdated;
+  /**
+   * Latch for the miswired-hook warning, so a streaming document warns once
+   * rather than on every chunk.
+   */
+  hasWarnedLayoutHookName = false;
   /**
    * The document's BODY text — everything after any front matter block.
    *
@@ -3260,7 +3292,7 @@ var Markdown = class _Markdown extends UIComponent3 {
     this.content.layout();
     this.width = this.content.width;
     this.height = this.content.height;
-    this.onLayoutUpdated?.();
+    this.notifyLayoutUpdated();
     this.scene?.markDirty();
     return this;
   }
@@ -4078,16 +4110,116 @@ var Markdown = class _Markdown extends UIComponent3 {
       radius: this.theme.imageRadius,
       onLoad: () => {
         const bmp = img.bitmap;
+        const previousWidth = img.width;
+        const previousHeight = img.height;
         if (bmp && bmp.naturalWidth && bmp.naturalHeight) {
           const aspect = bmp.naturalHeight / bmp.naturalWidth;
           img.width = Math.min(bmp.naturalWidth, availableWidth);
           img.height = Math.round(img.width * aspect);
         }
+        if (img.width !== previousWidth || img.height !== previousHeight) {
+          this.reflowAfterImageResize(img);
+        }
         this.scene?.markDirty();
       }
     });
     return img;
   }
+  /**
+   * Re-position every block after an image whose decode corrected its box.
+   *
+   * The 16:10 guess above is rarely the real aspect ratio, so without this every
+   * sibling below the image keeps the position computed from the guess, and an
+   * image taller than the guess renders *under* the paragraph that follows it.
+   *
+   * A bare `this.content.layout()` is not enough, and that is the part worth
+   * knowing: `Stack.layout()` is **not recursive**. It positions its children
+   * from the size each child reports at the moment it runs and never asks a
+   * child to recompute its own box first. Every image sits behind at least one
+   * intermediate container that caches a height — an image-bearing paragraph is
+   * a `Stack`, a list item's or blockquote's image is wrapped in a
+   * `MarkdownContainer` — so laying out `content` alone re-reads the very boxes
+   * the decode just invalidated. Measured on `94d6da3`: a 600x900 portrait in
+   * `![alt](…)\n\nAfter.` corrects `Image.height` 480 to 900 while its parent
+   * `Stack` stays 480 and the following paragraph stays at `y=496`.
+   *
+   * So resync bottom-up, from the image's own parent up to `content`, and each
+   * level sees a freshly-sized child before it positions anything.
+   */
+  reflowAfterImageResize(img) {
+    let reachesContent = false;
+    for (let node = img.parent; node; node = node.parent) {
+      if (node === this.content) {
+        reachesContent = true;
+        break;
+      }
+    }
+    if (!reachesContent) return;
+    for (let node = img.parent; node; node = node.parent) {
+      if (node instanceof Stack) node.layout();
+      else if (node instanceof MarkdownContainer) this.resyncWrapperBox(node);
+      if (node === this.content) break;
+    }
+    this.width = this.content.width;
+    this.height = this.content.height;
+    this.notifyLayoutUpdated();
+  }
+  /**
+   * Publish a completed re-layout to the host.
+   *
+   * Every path that republishes `width`/`height` from `content` ends here rather
+   * than calling {@link onLayoutUpdated} directly, so the misuse check below is
+   * reached however the re-layout was triggered.
+   *
+   * The check exists because the failure it catches is silent and was found in
+   * production, not in review. A host wired its reflow to `onHeightChanged` — a
+   * name this class has never had — through an `as unknown as` cast. The cast
+   * satisfied the compiler, the callback never fired, and every post containing
+   * an image stayed laid out against the guessed 16:10 aspect ratio with a stale
+   * document scroll height. Nothing in the type system, the tests or the console
+   * said anything. A property that is *only ever assigned* has no read site to
+   * fail, so the one place that can notice is the moment we would have called it.
+   */
+  notifyLayoutUpdated() {
+    if (this.onLayoutUpdated) {
+      this.onLayoutUpdated();
+      return;
+    }
+    if (!this.hasWarnedLayoutHookName) {
+      const wrongName = MISWIRED_LAYOUT_HOOK_NAMES.find(
+        (name) => typeof this[name] === "function"
+      );
+      if (wrongName) {
+        this.hasWarnedLayoutHookName = true;
+        console.warn(
+          `[VectoJS] Markdown.${wrongName} is not a VectoJS callback and will never fire. The document just re-laid-out and nothing was notified. Assign \`onLayoutUpdated\` instead \u2014 anything positioned below the document needs it, and a paragraph image corrects its guessed aspect ratio on decode, so a missed signal leaves following blocks overlapping the image.`
+        );
+      }
+    }
+  }
+  /**
+   * Re-derive one `MarkdownContainer`'s cached box from its children.
+   *
+   * Mirrors how {@link reflowToken}'s `blockquote` / `container` arms and every
+   * construction site derive it, so an image resize and a width change converge
+   * on the same geometry rather than each having its own arithmetic.
+   */
+  resyncWrapperBox(wrapper) {
+    const innerStack = wrapper.children.find((c) => c instanceof Stack);
+    const border = wrapper.children.find((c) => c instanceof QuoteBorder);
+    const background = wrapper.children.find((c) => c instanceof ContainerBackground);
+    if (border || background) {
+      const contentHeight = innerStack?.height || 20;
+      if (border instanceof QuoteBorder) border.height = contentHeight;
+      if (background instanceof ContainerBackground) background.height = contentHeight;
+      wrapper.height = Math.max(background?.height ?? 0, border?.height ?? 0, contentHeight);
+      return;
+    }
+    const child = wrapper.children[0];
+    if (!child) return;
+    wrapper.width = child.x + child.width;
+    wrapper.height = child.height;
+  }
   /** One table cell entity, shared by the render arm and the streamed-table path. */
   tableCellRichText(cell, header, t) {
     return new RichText2(this.tableCellSpans(cell, t), {
@@ -4199,6 +4331,8 @@ var Markdown = class _Markdown extends UIComponent3 {
       const wrapper = new MarkdownContainer();
       el.x = indent;
       wrapper.add(el);
+      wrapper.width = el.width + indent;
+      wrapper.height = el.height;
       stack.add(wrapper);
     }
     for (let i = leadChildren.length; i < children.length; i++) {
@@ -4872,9 +5006,7 @@ var Markdown = class _Markdown extends UIComponent3 {
     this.width = this.content.width;
     this.height = this.content.height;
     this.scene?.markDirty();
-    if (this.onLayoutUpdated) {
-      this.onLayoutUpdated();
-    }
+    this.notifyLayoutUpdated();
   }
   /**
    * Render one nested block with a temporary width/margin context while

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/markdown",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "publishConfig": {
     "access": "public"
   },