dsh-tiddlywiki 0.22.3 → 0.22.4

package/src/client/tw-frame.ts

@@ -6,8 +6,16 @@
  * TW proxy (`/dsh-tiddlywiki/tw/`) in an iframe and share the same lifecycle:
  * lazy-load on first show, `/status` polling with restart/error states, DSH
  * theme sync, reload-on-FAB-event, and tiddler-hash navigation. This module
- * owns that machinery plus the two small shared bits of state the surfaces
- * mirror (the tab chip label from `ui.tabLabel` and the tab icon).
+ * owns that machinery — `createTwFrameSurface()` is the ONE implementation —
+ * plus the two small shared bits of state the surfaces mirror (the tab chip
+ * label from `ui.tabLabel` and the tab icon).
+ *
+ * v0.22.4 convergence: `panel.ts` used to carry its own copies of
+ * showError/showStarting/showFrame/fallbackLoad/doRefresh. They drifted, and
+ * the drift is exactly what produced the v0.22.3 empty-`src` bug (one copy got
+ * the guard, the other did not). A surface now supplies only its SKIN (class
+ * names), its lazy build point and its visibility; every lifecycle decision
+ * lives here. Add new lifecycle behaviour in this file, never at a call site.
  *
  * Link routing: each mounted TW surface registers its live frame controller
  * here; panel.ts asks `openTiddlerInLiveTab` first, so a wiki link lands in a
@@ -78,77 +86,67 @@ export interface FrameLoadedState {
  * attribute was never assigned the property returns the EMBEDDING page's URL,
  * and assigning it back to `src` makes the DSH GUI load itself inside the
  * iframe (a second DSH instance: duplicate FAB, duplicated global listeners,
- * blank white page). Both callers below drive a full reload, so they must
- * refuse to touch a frame that has no loaded TW URL.
+ * blank white page). Every full-reload path must refuse to touch a frame that
+ * has no loaded TW URL.
  */
 export function loadableFrameUrl(dataset: FrameLoadedState): string | null {
   const loaded = dataset.loaded
   return loaded === undefined || loaded.length === 0 ? null : loaded
 }
 
-/** The plain-DOM TW frame controller owned by one surface body. */
-export interface TwFrameController {
-  /** Reflect the surface's visibility; loads lazily on the first show. */
-  setVisible(visible: boolean): void
-  /** Open a tiddler by title; false when this controller cannot serve it. */
-  openTiddler(title: string): boolean
-  dispose(): void
-}
-
-/**
- * Controller for an ALREADY-aborted signal: no DOM is ever built, so there is
- * nothing to show and nothing to reap (the abort listener would never fire).
- */
-function disposedController(): TwFrameController {
-  return {
-    setVisible(): void {},
-    openTiddler(): boolean { return false },
-    dispose(): void {},
-  }
-}
-
-/** Live visible-capable TW frames; a controller joins on creation, leaves on dispose. */
-const liveFrames = new Set<TwFrameController>()
+/* ────────────────────────── the shared frame kernel ─────────────────────── */
 
-/**
- * Ask every live side TW surface to open a tiddler; true when one served it.
- * A controller answers false while hidden or disposed, so the center overlay
- * only opens when no visible side TW tab can take the link.
- */
-export function openTiddlerInLiveTab(title: string): boolean {
-  for (const controller of liveFrames) {
-    if (controller.openTiddler(title)) return true
-  }
-  return false
+/** Per-surface skin: the class names (and inline style) a surface wears. */
+export interface TwFrameSkin {
+  /** Wrapper filling the surface body (owns the flex chain). */
+  view: string
+  /** `data-*` attributes for the view wrapper (panel tags it for its CSS). */
+  viewDataset?: Record<string, string>
+  /** Wrapper around the iframe. */
+  frameWrap: string
+  /** Inline style for the frame wrapper (the panel's has no stylesheet rule). */
+  frameWrapStyle?: string
+  /** The TW iframe. */
+  frame: string
+  /** Error / starting panel. */
+  error: string
 }
 
-/**
- * Refresh the shared surface label from `/status` (ui.tabLabel) so a surface
- * that mounts before the first status call already shows the right name.
- */
-export function warmTabLabel(): void {
-  void fetchStatus().then((payload) => {
-    if (payload?.ui !== undefined) setTabLabel(payload.ui.tabLabel ?? tabLabel)
-  })
+/** A TW iframe surface: DOM + lifecycle, shared by every embedding surface. */
+export interface TwFrameSurface {
+  /**
+   * Build the surface DOM (view wrapper + iframe + error area) and return the
+   * view element; the CALLER decides where to append it. Idempotent, and safe
+   * to call AFTER `setVisible(true)`: a surface asked to show before its DOM
+   * existed (the panel builds lazily, once the center column appears) re-arms
+   * its `/status` load right here instead of stranding an empty surface.
+   */
+  build(): HTMLDivElement
+  /**
+   * Reflect visibility. The first `true` starts the lazy load and is the only
+   * thing that reveals the frame; `false` hides it and stops the bounded
+   * retry polling, so a later `true` starts a fresh budget. Only a frame that
+   * already carries a TW URL is ever revealed.
+   */
+  setVisible(visible: boolean): void
+  /** Open a tiddler by title; false when this surface cannot serve it. */
+  openTiddler(title: string): boolean
+  /** Tear down listeners/timers/theme sync and remove the view from the DOM. */
+  dispose(): void
 }
 
 /**
- * Create a TW frame controller inside `host`. The frame loads lazily on the
- * first `setVisible(true)`, polls `/status` (starting/restart/error states),
- * follows the DSH theme, reloads on the FAB's reload event, and navigates to
- * `#<title>` hashes once the frame is ready. `signal` (the tab's abort) tears
- * the whole controller down. Joins the live-frame registry on creation and
- * leaves it on dispose.
+ * Create the frame machinery for one surface. Every `/status`-driven decision
+ * (starting / error / running, iframe URL, theme config, shared chip label)
+ * and every tiddler-hash navigation is implemented here ONCE.
  */
-export function createTwFrameController(host: HTMLElement, signal: AbortSignal): TwFrameController {
-  // Already aborted (the tab was closed before this body mounted): 'abort' will
-  // never fire again, so registering here would strand the iframe in
-  // liveFrames forever. Hand back a no-op controller and build nothing.
-  if (signal.aborted) return disposedController()
-
+export function createTwFrameSurface(skin: TwFrameSkin): TwFrameSurface {
   let visible = false
   let started = false
   let disposed = false
+  let view: HTMLDivElement | undefined
+  let frame: HTMLIFrameElement | undefined
+  let errorArea: HTMLDivElement | undefined
   let refreshTimer: number | undefined
   /** In-flight hash-readiness retry timers (cancelled by dispose, v0.19.1). */
   const hashWaitTimers = new Set<number>()
@@ -157,31 +155,16 @@ export function createTwFrameController(host: HTMLElement, signal: AbortSignal):
   let pendingHash: string | null = null
   let themeSyncDispose: (() => void) | undefined
 
-  const view = document.createElement('div')
-  view.className = 'dsh-tw-rightbar-view'
-
-  const frameArea = document.createElement('div')
-  frameArea.className = 'dsh-tw-rightbar-frame-wrap'
-  const frame = document.createElement('iframe')
-  frame.className = 'dsh-tw-rightbar-frame'
-  frame.title = 'TiddlyWiki'
-  frame.hidden = true
-  frameArea.append(frame)
-
-  const errorArea = document.createElement('div')
-  errorArea.className = 'dsh-tw-rightbar-error'
-  errorArea.hidden = true
-
-  view.append(frameArea, errorArea)
-  host.append(view)
-
-  frame.addEventListener('load', () => {
-    frameLoaded = true
-    applyPendingHash()
-  })
-  themeSyncDispose = attachThemeSync(frame)
+  /** Cancel the pending bounded retry (a new refresh supersedes it). */
+  const clearRetry = (): void => {
+    if (refreshTimer !== undefined) {
+      window.clearTimeout(refreshTimer)
+      refreshTimer = undefined
+    }
+  }
 
   const showError = (message: string): void => {
+    if (frame === undefined || errorArea === undefined) return
     frame.hidden = true
     errorArea.hidden = false
     errorArea.replaceChildren()
@@ -201,6 +184,7 @@ export function createTwFrameController(host: HTMLElement, signal: AbortSignal):
   }
 
   const showStarting = (): void => {
+    if (frame === undefined || errorArea === undefined) return
     frame.hidden = true
     errorArea.hidden = false
     errorArea.replaceChildren()
@@ -210,8 +194,11 @@ export function createTwFrameController(host: HTMLElement, signal: AbortSignal):
   }
 
   const showFrame = (url: string): void => {
+    if (frame === undefined || errorArea === undefined) return
     errorArea.hidden = true
-    // Only reveal the frame while the surface is on screen.
+    // Only reveal the frame while the surface is on screen: doRefresh() can
+    // still be in flight after the surface was hidden, and an unconditional
+    // `hidden = false` would pop a closed surface back into view.
     frame.hidden = !visible
     // Set the src only when the url changed, so an editor never loses unsaved
     // state on a status refresh.
@@ -222,9 +209,22 @@ export function createTwFrameController(host: HTMLElement, signal: AbortSignal):
     }
   }
 
-  /** Apply a pending tiddler-hash once the frame is ready (see panel.ts). */
+  /**
+   * Apply a pending tiddler-hash navigation once the iframe document is ready.
+   * Preferred: same-origin `contentWindow.location.hash` — a hashchange INSIDE
+   * the frame (no reload), TW's story handler opens the tiddler. Fallback: a
+   * full `iframe.src` reload with the hash (TW auto-saves drafts, acceptable).
+   *
+   * TW registers its hashchange listener in a STARTUP module that runs after
+   * the iframe's `load` event, so setting `location.hash` right on load is a
+   * no-op (hash lost → TW stays on its home page). We therefore wait for TW to
+   * become ready inside the frame (the `$tw` global appears once boot settles)
+   * before setting the hash; if it never does (service down / slow boot) we
+   * fall back to a full reload with the hash, which TW processes at startup.
+   * A newer open request supersedes an in-flight wait.
+   */
   const applyPendingHash = (): void => {
-    if (pendingHash === null || !frameLoaded) return
+    if (pendingHash === null || frame === undefined || !frameLoaded) return
     const hash = pendingHash
     const win = frame.contentWindow
     if (win === null) {
@@ -232,8 +232,8 @@ export function createTwFrameController(host: HTMLElement, signal: AbortSignal):
       return
     }
     const tryOnce = (attempt: number): void => {
-      if (disposed) return
-      if (pendingHash !== hash) return
+      if (disposed) return // unmounted: do not keep waiting or touch the frame
+      if (pendingHash !== hash) return // superseded by a newer request
       const frameTw = win as { $tw?: unknown }
       if (typeof frameTw.$tw !== 'object' || frameTw.$tw === null) {
         if (attempt < 40) {
@@ -260,10 +260,11 @@ export function createTwFrameController(host: HTMLElement, signal: AbortSignal):
   }
 
   const fallbackLoad = (hash: string): void => {
-    if (disposed) return
+    if (disposed || frame === undefined) return // never drive a detached frame
     if (pendingHash === hash) pendingHash = null
     // Guard against the never-loaded frame: `frame.src` is '' before showFrame
-    // ran, and `'' + '#title'` resolves against the DSH page URL (v0.22.3).
+    // ran, and `'' + '#title'` resolves against the DSH page URL, which loads
+    // the GUI into the iframe (v0.22.3).
     const base = loadableFrameUrl(frame.dataset)
     if (base === null) return
     const next = `${base.split('#')[0]}${hash}`
@@ -271,17 +272,16 @@ export function createTwFrameController(host: HTMLElement, signal: AbortSignal):
   }
 
   const doRefresh = async (): Promise<void> => {
-    if (refreshTimer !== undefined) {
-      window.clearTimeout(refreshTimer)
-      refreshTimer = undefined
-    }
+    clearRetry()
     const payload = await fetchStatus()
-    if (disposed) return
+    if (disposed) return // unmounted while fetching: stop, don't touch DOM
     if (payload === null) {
       showError('无法访问 /dsh-tiddlywiki/status')
       return
     }
     if (payload.ui !== undefined) {
+      // Shared surface label + theme config: both are module-level, so any
+      // surface that polls keeps them fresh for every other surface.
       setTabLabel(payload.ui.tabLabel ?? tabLabel)
       setThemeSyncConfig({
         enabled: payload.ui.followDshTheme !== false,
@@ -290,6 +290,9 @@ export function createTwFrameController(host: HTMLElement, signal: AbortSignal):
     }
     if (payload.status === 'running') {
       refreshAttempts = 0
+      // Same-origin proxy URL: build from the page's own origin so it works no
+      // matter which host/domain the user reached DSH on. Fall back to the
+      // legacy loopback `url` for older servers that do not send twProxy.
       if (typeof payload.twProxy === 'string') {
         showFrame(new URL(payload.twProxy, window.location.origin).href)
       } else if (typeof payload.url === 'string') {
@@ -314,38 +317,78 @@ export function createTwFrameController(host: HTMLElement, signal: AbortSignal):
   const onReloadRequest = (): void => {
     // Reload = re-assign the URL the frame is ALREADY showing (full reload, so
     // TW re-reads the wiki; `location.reload()` could be blocked mid-edit).
-    // `hidden` alone is not enough (v0.22.3): setVisible(true) reveals the frame
-    // before the first /status response sets its src, and `frame.src = frame.src`
-    // with `src === ''` loads the DSH page into the iframe.
+    // The ONLY valid condition is `dataset.loaded` (v0.22.3): `frame.src` is ''
+    // before showFrame ran, and `frame.src = frame.src` with `src === ''` loads
+    // the DSH page into the iframe.
+    // Deliberately NOT gated on `frame.hidden`: the FAB entry is an EXPLICIT
+    // reload request, so it must reach every frame that really points at TW —
+    // including a closed panel that would otherwise reopen onto stale assets
+    // (v0.22.4; the panel used to reload in that state). An extra reload costs
+    // less than showing stale content.
+    if (frame === undefined) return
     const loaded = loadableFrameUrl(frame.dataset)
-    if (loaded !== null && !frame.hidden) frame.src = loaded
+    if (loaded !== null) frame.src = loaded
   }
   document.addEventListener(PANEL_RELOAD_EVENT, onReloadRequest)
 
-  const onAbort = (): void => controller.dispose()
-  signal.addEventListener('abort', onAbort, { once: true })
+  const build = (): HTMLDivElement => {
+    if (view !== undefined) return view
+    const viewEl = document.createElement('div')
+    viewEl.className = skin.view
+    if (skin.viewDataset !== undefined) {
+      for (const [key, value] of Object.entries(skin.viewDataset)) viewEl.dataset[key] = value
+    }
+    const wrapEl = document.createElement('div')
+    wrapEl.className = skin.frameWrap
+    if (skin.frameWrapStyle !== undefined) wrapEl.style.cssText = skin.frameWrapStyle
+    const frameEl = document.createElement('iframe')
+    frameEl.className = skin.frame
+    frameEl.title = 'TiddlyWiki'
+    frameEl.hidden = true
+    wrapEl.append(frameEl)
+    const errorEl = document.createElement('div')
+    errorEl.className = skin.error
+    errorEl.hidden = true
+    viewEl.append(wrapEl, errorEl)
+    view = viewEl
+    frame = frameEl
+    errorArea = errorEl
+    // Track load so a pending tiddler-hash navigation can target a ready
+    // document (setting contentWindow.location.hash before load is a no-op).
+    frameEl.addEventListener('load', () => {
+      frameLoaded = true
+      applyPendingHash()
+    })
+    // Embedded TW follows the DSH light/dark theme (non-persisting palette
+    // swap inside the same-origin iframe; re-applied on load + theme change).
+    themeSyncDispose = attachThemeSync(frameEl)
+    // The surface may already have been asked to show before its DOM existed
+    // (the panel builds lazily): re-arm the load so it never stays empty.
+    if (visible) void doRefresh()
+    return viewEl
+  }
 
-  const controller: TwFrameController = {
+  return {
+    build,
     setVisible(next: boolean): void {
+      if (disposed) return
       visible = next
-      if (!started) {
-        // Nothing loaded yet: stay hidden until the first show kicks the load.
-        frame.hidden = true
-        if (next) {
-          started = true
-          void doRefresh()
-        }
-        return
+      if (next && !started) started = true
+      if (frame !== undefined) {
+        // Reveal only a frame that already carries a TW URL; showFrame /
+        // showStarting decide what to display until the first /status lands.
+        frame.hidden = !next || loadableFrameUrl(frame.dataset) === null
+      }
+      if (next) {
+        // 每次重新显示都重探一次状态：启动轮询是有界的（30×1.5s），首次打开时
+        // 服务没起来就会把错误界面永久固定（切走再切回也不恢复）。doRefresh 自己
+        // 会清旧 timer，不会重复轮询。
+        void doRefresh()
+      } else {
+        // Hidden surfaces stop polling and get a fresh budget on the next show.
+        clearRetry()
+        refreshAttempts = 0
       }
-      // Revealing before the first /status response is harmless as long as
-      // every src-writing path checks `dataset.loaded` (onReloadRequest /
-      // fallbackLoad), which also keeps the surface visible while a switch to
-      // another wiki re-resolves its URL.
-      frame.hidden = !next
-      // 每次重新显示都重探一次状态：启动轮询是有界的（30×1.5s），首次打开时
-      // 服务没起来就会把错误界面永久固定（切走再切回也不恢复）。doRefresh 自己
-      // 会清旧 timer，不会重复轮询。
-      if (next) void doRefresh()
     },
     openTiddler(title: string): boolean {
       if (disposed || !visible) return false
@@ -361,16 +404,105 @@ export function createTwFrameController(host: HTMLElement, signal: AbortSignal):
     dispose(): void {
       if (disposed) return
       disposed = true
-      liveFrames.delete(controller)
       document.removeEventListener(PANEL_RELOAD_EVENT, onReloadRequest)
-      signal.removeEventListener('abort', onAbort)
-      if (refreshTimer !== undefined) window.clearTimeout(refreshTimer)
+      clearRetry()
       for (const timer of hashWaitTimers) window.clearTimeout(timer)
       hashWaitTimers.clear()
       themeSyncDispose?.()
-      view.remove()
+      view?.remove()
+    },
+  }
+}
+
+/** The plain-DOM TW frame controller owned by one surface body. */
+export interface TwFrameController {
+  /** Reflect the surface's visibility; loads lazily on the first show. */
+  setVisible(visible: boolean): void
+  /** Open a tiddler by title; false when this controller cannot serve it. */
+  openTiddler(title: string): boolean
+  dispose(): void
+}
+
+/**
+ * Controller for an ALREADY-aborted signal: no DOM is ever built, so there is
+ * nothing to show and nothing to reap (the abort listener would never fire).
+ */
+function disposedController(): TwFrameController {
+  return {
+    setVisible(): void {},
+    openTiddler(): boolean { return false },
+    dispose(): void {},
+  }
+}
+
+/** Live visible-capable TW frames; a controller joins on creation, leaves on dispose. */
+const liveFrames = new Set<TwFrameController>()
+
+/**
+ * Ask every live side TW surface to open a tiddler; true when one served it.
+ * A controller answers false while hidden or disposed, so the center overlay
+ * only opens when no visible side TW tab can take the link.
+ */
+export function openTiddlerInLiveTab(title: string): boolean {
+  for (const controller of liveFrames) {
+    if (controller.openTiddler(title)) return true
+  }
+  return false
+}
+
+/**
+ * Refresh the shared surface label from `/status` (ui.tabLabel) so a surface
+ * that mounts before the first status call already shows the right name.
+ */
+export function warmTabLabel(): void {
+  void fetchStatus().then((payload) => {
+    if (payload?.ui !== undefined) setTabLabel(payload.ui.tabLabel ?? tabLabel)
+  })
+}
+
+/** The rightbar tab's skin for the shared kernel (CSS owns the flex chain). */
+const RIGHTBAR_SKIN: TwFrameSkin = {
+  view: 'dsh-tw-rightbar-view',
+  frameWrap: 'dsh-tw-rightbar-frame-wrap',
+  frame: 'dsh-tw-rightbar-frame',
+  error: 'dsh-tw-rightbar-error',
+}
+
+/**
+ * Create a TW frame controller inside `host`: the shared kernel (which loads
+ * lazily on the first `setVisible(true)`, polls `/status`, follows the DSH
+ * theme, reloads on the FAB's reload event and navigates `#<title>` hashes)
+ * plus the rightbar skin and the live-frame registry. `signal` (the tab's
+ * abort) tears the whole controller down.
+ */
+export function createTwFrameController(host: HTMLElement, signal: AbortSignal): TwFrameController {
+  // Already aborted (the tab was closed before this body mounted): 'abort' will
+  // never fire again, so registering here would strand the iframe in
+  // liveFrames forever. Hand back a no-op controller and build nothing.
+  if (signal.aborted) return disposedController()
+
+  const surface = createTwFrameSurface(RIGHTBAR_SKIN)
+  host.append(surface.build())
+
+  let disposed = false
+  const onAbort = (): void => controller.dispose()
+  signal.addEventListener('abort', onAbort, { once: true })
+
+  const controller: TwFrameController = {
+    setVisible(visible: boolean): void {
+      surface.setVisible(visible)
+    },
+    openTiddler(title: string): boolean {
+      return surface.openTiddler(title)
+    },
+    dispose(): void {
+      if (disposed) return
+      disposed = true
+      liveFrames.delete(controller)
+      signal.removeEventListener('abort', onAbort)
+      surface.dispose()
     },
   }
   liveFrames.add(controller)
   return controller
-}
+}