@forgeax/app-shell 0.54.1 → 0.56.0

package/dist/react.d.ts

@@ -232,6 +232,35 @@ interface OutsideDismissLifecycleOptions {
  */
 declare function installOutsideDismissLifecycle(options: OutsideDismissLifecycleOptions): () => void;
 
+interface BoundedFrameRetryLifecycleOptions {
+    readonly attempt: () => boolean;
+    readonly onSuccess?: () => void;
+    readonly maxFrames?: number;
+    readonly requestFrame?: (callback: FrameRequestCallback) => number;
+    readonly cancelFrame?: (handle: number) => void;
+}
+/**
+ * Attempt immediately, then retry on a bounded number of animation frames.
+ * Products own the work and success predicate; App Shell owns scheduling,
+ * cancellation, stale-callback fencing and best-effort exception isolation.
+ */
+declare function installBoundedFrameRetryLifecycle(options: BoundedFrameRetryLifecycleOptions): () => void;
+
+interface CoalescedFrameTaskLifecycleOptions {
+    readonly task: () => void;
+    readonly requestFrame?: (callback: FrameRequestCallback) => number;
+    readonly cancelFrame?: (handle: number) => void;
+}
+interface CoalescedFrameTaskLifecycle {
+    schedule(): void;
+    dispose(): void;
+}
+/**
+ * Coalesce repeated requests into one next-frame task. Products own the task;
+ * App Shell owns pending-state release, cancellation and stale-callback fencing.
+ */
+declare function createCoalescedFrameTaskLifecycle(options: CoalescedFrameTaskLifecycleOptions): CoalescedFrameTaskLifecycle;
+
 type PanelContentPadding = 'none' | 'sm' | 'md';
 type PanelContentScroll = 'none' | 'auto';
 type PanelContentTone = 'default' | 'surface' | 'tool';
@@ -373,4 +402,4 @@ interface ShellSlotProps extends HTMLAttributes<HTMLElement> {
 /** Structural shell marker that preserves the caller's semantic element. */
 declare function ShellSlot({ as, name, ...props }: ShellSlotProps): ReactElement;
 
-export { type AnchoredResizeDirection, AnchoredResizeHandle, type AnchoredResizeHandleProps, type AnchoredResizeSession, DetachedPanelBoundary, type DetachedPanelBoundaryProps, DetachedSurfaceFrame, type DetachedSurfaceFrameProps, DetachedSurfaceStatus, type DetachedSurfaceStatusProps, type DetachedSurfaceStatusTone, type DockLayoutControlBinding, type DockLayoutControlBindingOptions, DockLayoutMenu, type DockLayoutMenuPanel, type DockLayoutMenuProps, DockTabAction, type DockTabActionProps, DockTabFrame, type DockTabFrameProps, DockTabIcon, type DockTabIconProps, DockTabStatusSummary, type DockTabStatusSummaryItem, type DockTabStatusSummaryProps, type DockTabStatusTone, DockTabTitle, type DockTabTitleProps, FloatingMenu, type FloatingMenuAnchor, type FloatingMenuPoint, type FloatingMenuProps, type LiveTabPlacement, type LiveTabPlacementSource, type LiveTabTitleSource, OWNED_INTERACTION_SURFACE_SELECTOR, type OutsideDismissEventTarget, type OutsideDismissLifecycleOptions, type OutsideDismissReason, type PanelContentPadding, type PanelContentPolicy, type PanelContentScroll, type PanelContentTone, PanelEmptyState, type PanelEmptyStateProps, PanelSurface, type PanelSurfaceProps, type PersistentSizeStorage, type PersistentSizeStore, type PersistentSizeStoreOptions, type PersistentSizeUpdate, type PointerDragFinishReason, type PointerDragSessionOptions, type PointerReorderFinishReason, type PointerReorderSession, type PointerReorderSessionOptions, ResizeHandle, type ResizeHandleProps, ShellSlot, type ShellSlotElement, type ShellSlotProps, SlotDebugOverlay, SurfacePlaceholder, type SurfacePlaceholderProps, SurfaceRegion, type SurfaceRegionProps, type TabCloseInteractions, type TabCloseInteractionsOptions, type TabPinnedStateSource, type ThresholdPointerDragFinishReason, type ThresholdPointerDragSession, type ThresholdPointerDragSessionOptions, applyAnchoredResizeDelta, beginAnchoredResize, createPersistentSizeStore, hashSlotHue, installOutsideDismissLifecycle, installPointerDragSession, installPointerReorderSession, installThresholdPointerDragSession, isDismissExemptInteractionTarget, isSlotDebugEnabled, useDockLayoutControlBinding, useLiveTabPlacement, useLiveTabTitle, useLocalSize, usePersistentSizeStore, useTabCloseInteractions, useTabPinnedState };
+export { type AnchoredResizeDirection, AnchoredResizeHandle, type AnchoredResizeHandleProps, type AnchoredResizeSession, type BoundedFrameRetryLifecycleOptions, type CoalescedFrameTaskLifecycle, type CoalescedFrameTaskLifecycleOptions, DetachedPanelBoundary, type DetachedPanelBoundaryProps, DetachedSurfaceFrame, type DetachedSurfaceFrameProps, DetachedSurfaceStatus, type DetachedSurfaceStatusProps, type DetachedSurfaceStatusTone, type DockLayoutControlBinding, type DockLayoutControlBindingOptions, DockLayoutMenu, type DockLayoutMenuPanel, type DockLayoutMenuProps, DockTabAction, type DockTabActionProps, DockTabFrame, type DockTabFrameProps, DockTabIcon, type DockTabIconProps, DockTabStatusSummary, type DockTabStatusSummaryItem, type DockTabStatusSummaryProps, type DockTabStatusTone, DockTabTitle, type DockTabTitleProps, FloatingMenu, type FloatingMenuAnchor, type FloatingMenuPoint, type FloatingMenuProps, type LiveTabPlacement, type LiveTabPlacementSource, type LiveTabTitleSource, OWNED_INTERACTION_SURFACE_SELECTOR, type OutsideDismissEventTarget, type OutsideDismissLifecycleOptions, type OutsideDismissReason, type PanelContentPadding, type PanelContentPolicy, type PanelContentScroll, type PanelContentTone, PanelEmptyState, type PanelEmptyStateProps, PanelSurface, type PanelSurfaceProps, type PersistentSizeStorage, type PersistentSizeStore, type PersistentSizeStoreOptions, type PersistentSizeUpdate, type PointerDragFinishReason, type PointerDragSessionOptions, type PointerReorderFinishReason, type PointerReorderSession, type PointerReorderSessionOptions, ResizeHandle, type ResizeHandleProps, ShellSlot, type ShellSlotElement, type ShellSlotProps, SlotDebugOverlay, SurfacePlaceholder, type SurfacePlaceholderProps, SurfaceRegion, type SurfaceRegionProps, type TabCloseInteractions, type TabCloseInteractionsOptions, type TabPinnedStateSource, type ThresholdPointerDragFinishReason, type ThresholdPointerDragSession, type ThresholdPointerDragSessionOptions, applyAnchoredResizeDelta, beginAnchoredResize, createCoalescedFrameTaskLifecycle, createPersistentSizeStore, hashSlotHue, installBoundedFrameRetryLifecycle, installOutsideDismissLifecycle, installPointerDragSession, installPointerReorderSession, installThresholdPointerDragSession, isDismissExemptInteractionTarget, isSlotDebugEnabled, useDockLayoutControlBinding, useLiveTabPlacement, useLiveTabTitle, useLocalSize, usePersistentSizeStore, useTabCloseInteractions, useTabPinnedState };

package/dist/react.js

@@ -1725,6 +1725,137 @@ function installOutsideDismissLifecycle(options) {
   };
 }
 
+// src/frame-retry.ts
+function installBoundedFrameRetryLifecycle(options) {
+  const requestFrame = options.requestFrame ?? (typeof requestAnimationFrame === "undefined" ? void 0 : requestAnimationFrame.bind(globalThis));
+  const cancelFrame = options.cancelFrame ?? (typeof cancelAnimationFrame === "undefined" ? void 0 : cancelAnimationFrame.bind(globalThis));
+  const requestedMaxFrames = options.maxFrames ?? 240;
+  const maxFrames = Number.isFinite(requestedMaxFrames) ? Math.max(0, Math.floor(requestedMaxFrames)) : 0;
+  let disposed = false;
+  let completed = false;
+  let attemptedFrames = 0;
+  let frameHandle = null;
+  let frameGeneration = 0;
+  const attempt = () => {
+    if (disposed || completed) return true;
+    let succeeded = false;
+    try {
+      succeeded = options.attempt() === true;
+    } catch {
+    }
+    if (disposed || !succeeded) return disposed;
+    completed = true;
+    frameGeneration++;
+    try {
+      options.onSuccess?.();
+    } catch {
+    }
+    return true;
+  };
+  const schedule = () => {
+    if (disposed || completed || !requestFrame || attemptedFrames >= maxFrames) return;
+    attemptedFrames++;
+    const generation = ++frameGeneration;
+    let callbackRan = false;
+    let handle;
+    try {
+      handle = requestFrame(() => {
+        callbackRan = true;
+        if (disposed || completed || generation !== frameGeneration) return;
+        frameGeneration++;
+        frameHandle = null;
+        if (!attempt()) schedule();
+      });
+    } catch {
+      if (generation === frameGeneration) frameGeneration++;
+      return;
+    }
+    if (callbackRan || disposed || completed || generation !== frameGeneration) {
+      try {
+        cancelFrame?.(handle);
+      } catch {
+      }
+      return;
+    }
+    frameHandle = handle;
+  };
+  if (!attempt()) schedule();
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    frameGeneration++;
+    if (frameHandle !== null) {
+      try {
+        cancelFrame?.(frameHandle);
+      } catch {
+      }
+      frameHandle = null;
+    }
+  };
+}
+
+// src/coalesced-frame-task.ts
+function createCoalescedFrameTaskLifecycle(options) {
+  const requestFrame = options.requestFrame ?? (typeof requestAnimationFrame === "undefined" ? void 0 : requestAnimationFrame.bind(globalThis));
+  const cancelFrame = options.cancelFrame ?? (typeof cancelAnimationFrame === "undefined" ? void 0 : cancelAnimationFrame.bind(globalThis));
+  let disposed = false;
+  let pending = false;
+  let frameHandle = null;
+  let frameGeneration = 0;
+  const schedule = () => {
+    if (disposed || pending || !requestFrame) return;
+    pending = true;
+    const generation = ++frameGeneration;
+    let callbackRan = false;
+    let handle;
+    try {
+      handle = requestFrame(() => {
+        callbackRan = true;
+        if (disposed || !pending || generation !== frameGeneration) return;
+        pending = false;
+        frameHandle = null;
+        frameGeneration++;
+        try {
+          options.task();
+        } catch {
+        }
+      });
+    } catch {
+      if (generation === frameGeneration) {
+        pending = false;
+        frameHandle = null;
+        frameGeneration++;
+      }
+      return;
+    }
+    if (callbackRan) return;
+    if (disposed || !pending || generation !== frameGeneration) {
+      try {
+        cancelFrame?.(handle);
+      } catch {
+      }
+      return;
+    }
+    frameHandle = handle;
+  };
+  return {
+    schedule,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      pending = false;
+      frameGeneration++;
+      if (frameHandle !== null) {
+        try {
+          cancelFrame?.(frameHandle);
+        } catch {
+        }
+        frameHandle = null;
+      }
+    }
+  };
+}
+
 // src/panel.tsx
 import { jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
 function PanelEmptyState({
@@ -2096,8 +2227,10 @@ export {
   SurfaceRegion,
   applyAnchoredResizeDelta,
   beginAnchoredResize,
+  createCoalescedFrameTaskLifecycle,
   createPersistentSizeStore,
   hashSlotHue,
+  installBoundedFrameRetryLifecycle,
   installOutsideDismissLifecycle,
   installPointerDragSession,
   installPointerReorderSession,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/app-shell",
-  "version": "0.54.1",
+  "version": "0.56.0",
   "description": "Generic Dock, Panel, Window, and Slot composition primitives",
   "license": "Apache-2.0",
   "type": "module",