@takazudo/zudo-doc 0.2.0-next.5 → 0.2.0-next.6

package/dist/html-preview-wrapper/html-preview-wrapper.d.ts

@@ -44,14 +44,52 @@ interface HtmlPreviewWrapperProps {
     defaultOpen?: boolean;
 }
 /**
- * HTML preview wrapper component.
+ * Bare HTML preview body — the actual island **hydration target**.
  *
- * Merges `settings.htmlPreview` (global config) with per-usage props and
- * forwards everything to `<HtmlPreview>`. Wraps it in
- * `<Island when="visible">`, mirroring the legacy `client:visible`
- * hydration timing — the iframe is heavy and not on the critical path,
- * so we defer hydration until the preview enters the viewport.
+ * Merges global (`settings.htmlPreview`) config with per-usage props and
+ * forwards everything to `<HtmlPreview>`. Renders the preview tree
+ * **directly**: it does NOT wrap itself in `<Island>`. `HtmlPreviewWrapper`
+ * below applies the `<Island when="visible">` wrapper around it.
+ *
+ * ## Island invariant (read before touching the displayName / Island wiring)
+ *
+ * The hydration-target export's NAME must equal its `displayName` (which
+ * becomes the `data-zfb-island="…"` marker), AND that export must NOT itself
+ * render an `<Island>`. The zfb scanner resolves the client hydration
+ * component by marker-name → export-name lookup; if the resolved export
+ * re-wraps in `Island()`, the client re-emits a second `data-zfb-island`
+ * wrapper and Preact reuses the SSR'd children one level off — re-parenting
+ * the preview + code sections inside the flex title bar (the broken
+ * side-by-side layout). This is the same class of bug fixed for
+ * Toc / MobileToc / Sidebar in zudolab/zudo-doc#1355 and was the original
+ * defect here (zudolab/zudo-doc#1925, an Astro→zfb migration regression):
+ * the inner bare component carried the *outer* wrapper's name
+ * (`displayName = "HtmlPreviewWrapper"`) and was not exported, so the marker
+ * resolved to the exported self-wrapping `HtmlPreviewWrapper` and the client
+ * double-wrapped. Fix: the bare component carries its OWN name
+ * (`HtmlPreviewWrapperInner`) and is exported, so the marker resolves to
+ * THIS bare component and the bundle hydrates it in-place.
+ */
+declare function HtmlPreviewWrapperInner(props: HtmlPreviewWrapperProps): VNode;
+declare namespace HtmlPreviewWrapperInner {
+    var displayName: string;
+}
+/**
+ * HTML preview wrapper component — the public MDX-registered binding
+ * (`HtmlPreview: HtmlPreviewWrapper`).
+ *
+ * Wraps the bare `HtmlPreviewWrapperInner` in `<Island when="visible">`,
+ * mirroring the legacy `client:visible` hydration timing — the iframe is
+ * heavy and not on the critical path, so hydration is deferred until the
+ * preview enters the viewport. The SSG output emits
+ * `data-zfb-island="HtmlPreviewWrapperInner"` around the bare tree, and the
+ * client bundle hydrates `HtmlPreviewWrapperInner` against it in-place.
+ *
+ * The public export name and signature are unchanged from before the
+ * zudolab/zudo-doc#1925 fix, so existing consumers that register
+ * `HtmlPreview: HtmlPreviewWrapper` keep working (and now hydrate correctly)
+ * with no call-site change.
  */
 declare function HtmlPreviewWrapper(props: HtmlPreviewWrapperProps): VNode;
 
-export { type HtmlPreviewGlobalConfig, HtmlPreviewWrapper, type HtmlPreviewWrapperProps };
+export { type HtmlPreviewGlobalConfig, HtmlPreviewWrapper, HtmlPreviewWrapperInner, type HtmlPreviewWrapperProps };

package/dist/html-preview-wrapper/html-preview-wrapper.js

@@ -23,7 +23,7 @@ function HtmlPreviewWrapperInner(props) {
     }
   );
 }
-HtmlPreviewWrapperInner.displayName = "HtmlPreviewWrapper";
+HtmlPreviewWrapperInner.displayName = "HtmlPreviewWrapperInner";
 function HtmlPreviewWrapper(props) {
   const rendered = Island({
     when: "visible",
@@ -32,5 +32,6 @@ function HtmlPreviewWrapper(props) {
   return rendered;
 }
 export {
-  HtmlPreviewWrapper
+  HtmlPreviewWrapper,
+  HtmlPreviewWrapperInner
 };

package/dist/html-preview-wrapper/index.d.ts

@@ -1,4 +1,4 @@
-export { HtmlPreviewGlobalConfig, HtmlPreviewWrapper, HtmlPreviewWrapperProps } from './html-preview-wrapper.js';
+export { HtmlPreviewGlobalConfig, HtmlPreviewWrapper, HtmlPreviewWrapperInner, HtmlPreviewWrapperProps } from './html-preview-wrapper.js';
 export { HtmlPreview, HtmlPreviewProps } from './html-preview.js';
 export { CodeBlockData, PreviewBase, PreviewBaseProps } from './preview-base.js';
 export { HighlightedCode, HighlightedCodeProps } from './highlighted-code.js';

package/dist/html-preview-wrapper/index.js

@@ -1,5 +1,6 @@
 import {
-  HtmlPreviewWrapper
+  HtmlPreviewWrapper,
+  HtmlPreviewWrapperInner
 } from "./html-preview-wrapper.js";
 import { HtmlPreview } from "./html-preview.js";
 import { PreviewBase } from "./preview-base.js";
@@ -8,5 +9,6 @@ export {
   HighlightedCode,
   HtmlPreview,
   HtmlPreviewWrapper,
+  HtmlPreviewWrapperInner,
   PreviewBase
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "0.2.0-next.5",
+  "version": "0.2.0-next.6",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -161,7 +161,7 @@
     "@takazudo/zfb": "^0.1.0-next.31",
     "@takazudo/zfb-runtime": "^0.1.0-next.31",
     "@takazudo/zdtp": "^0.2.0-next.2",
-    "@takazudo/zudo-doc-history-server": "^0.2.0-next.5"
+    "@takazudo/zudo-doc-history-server": "^0.2.0-next.6"
   },
   "peerDependenciesMeta": {
     "@takazudo/zudo-doc-history-server": {