@astryxdesign/core 0.5.2-canary.2da7a39 → 0.5.2-canary.2e51213

package/dist/Resizable/useResizable.js

@@ -4,17 +4,29 @@
 
 /**
  * @file useResizable.ts
- * @input Resize configuration (defaultSize, minSizePx, maxSizePx, snaps) and
- *   collapse configuration (collapsible, defaultIsCollapsed, isCollapsed)
+ * @input Resize configuration (defaultSize, minSize, maxSize, legacy pixel
+ *   aliases, snaps) and collapse configuration (collapsible,
+ *   defaultIsCollapsed, isCollapsed)
  * @output Hook return: size, isCollapsed, collapse/expand/resize methods, props for handle
  * @position Public hook; consumed by layout components via `resizable` prop
  */
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { observeResize } from "../utils/sharedResizeObserver.js";
+import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
+import { devWarn } from "../utils/devWarning.js";
 
 // =============================================================================
 // Types
 // =============================================================================
 
+/**
+ * The minimum, in one of two spellings. Exactly one may be supplied: the union
+ * makes passing both a type error, so a migration cannot leave a stale
+ * deprecated value shadowing the new one (AST-010 API4).
+ */
+
+/** The maximum, in one of two spellings. See {@link ResizableMinConfig}. */
+
 /**
  * Shared config shape for any component that integrates built-in resize
  * (e.g. SideNav `resizable` prop). Provides a simplified API surface
@@ -111,21 +123,217 @@ function persistState(key, state) {
     /* ignore */
   }
 }
-function resolveDefaultSize(defaultSize) {
-  if (defaultSize == null) {
-    return 250;
-  }
-  if (typeof defaultSize === 'number') {
-    return defaultSize;
-  }
-  if (defaultSize.endsWith('%')) {
-    const pct = parseFloat(defaultSize);
-    if (!isNaN(pct)) {
-      const approx = typeof window !== 'undefined' ? window.innerWidth : 1200;
-      return Math.round(pct / 100 * approx);
+
+/** The released compatibility basis when there is no window to measure. */
+const SERVER_BASIS = 1200;
+const DEFAULT_SIZE_FALLBACK = 250;
+const RESIZABLE_SIZE_GUIDANCE = 'Use a non-negative number of pixels, an exact "Npx" string, an exact ' + '"N%" string from 0% to 100%, pixel(value), or ' + 'percent(value, {min: pixel(value)}) / percent(value, {max: pixel(value)}).';
+const LEGACY_PIXEL_GUIDANCE = 'Use a non-negative number of pixels.';
+const LEGACY_MAX_PIXEL_GUIDANCE = 'Use a non-negative number of pixels or explicit Infinity.';
+
+/** Parsed, validated input. */
+
+const PX_PATTERN = /^(\d+(?:\.\d+)?)px$/;
+const PERCENT_PATTERN = /^(\d+(?:\.\d+)?)%$/;
+function parseSizeString(value) {
+  // Preserve the released atomic fast path exactly.
+  const px = PX_PATTERN.exec(value);
+  if (px) {
+    const parsed = Number(px[1]);
+    return Number.isFinite(parsed) ? {
+      kind: 'px',
+      value: parsed
+    } : null;
+  }
+  const percentValue = PERCENT_PATTERN.exec(value);
+  if (percentValue) {
+    const parsed = Number(percentValue[1]);
+    return Number.isFinite(parsed) && parsed <= 100 ? {
+      kind: 'percent',
+      value: parsed
+    } : null;
+  }
+  return null;
+}
+function parsePixelSize(value) {
+  if (typeof value !== 'object' || value == null || Array.isArray(value)) {
+    return null;
+  }
+  const candidate = value;
+  return candidate.type === 'pixel' && typeof candidate.value === 'number' && Number.isFinite(candidate.value) && candidate.value >= 0 ? candidate.value : null;
+}
+function parsePercentSize(value) {
+  if (Array.isArray(value)) {
+    return null;
+  }
+  const candidate = value;
+  if (candidate.type !== 'percent' || typeof candidate.value !== 'number' || !Number.isFinite(candidate.value) || candidate.value < 0 || candidate.value > 100) {
+    return null;
+  }
+  const hasMin = candidate.min !== undefined;
+  const hasMax = candidate.max !== undefined;
+  // Exactly one bound is required. The helper's public type enforces this for
+  // typed callers; this branch preserves it for JavaScript and `any`.
+  if (hasMin === hasMax) {
+    return null;
+  }
+  if (hasMin) {
+    const min = parsePixelSize(candidate.min);
+    return min == null ? null : {
+      kind: 'percent',
+      value: candidate.value,
+      min
+    };
+  }
+  const max = parsePixelSize(candidate.max);
+  return max == null ? null : {
+    kind: 'percent',
+    value: candidate.value,
+    max
+  };
+}
+function parseSize(value) {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value >= 0 ? {
+      kind: 'px',
+      value
+    } : null;
+  }
+  if (typeof value === 'string') {
+    return parseSizeString(value);
+  }
+  if (typeof value === 'object' && value != null) {
+    const pixelValue = parsePixelSize(value);
+    return pixelValue == null ? parsePercentSize(value) : {
+      kind: 'px',
+      value: pixelValue
+    };
+  }
+  return null;
+}
+function parseLegacyPixel(value, allowInfinity) {
+  if (allowInfinity && value === Infinity) {
+    return {
+      kind: 'px',
+      value
+    };
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value >= 0 ? {
+      kind: 'px',
+      value
+    } : null;
+  }
+  // Preserve the released runtime compatibility for untyped callers. The
+  // public aliases remain number-only, but exact atomic strings worked before
+  // they were deprecated and continue to resolve through the same fast path.
+  return typeof value === 'string' ? parseSizeString(value) : null;
+}
+
+/** Whether this parsed value must be recomputed when its basis changes. */
+function dependsOnBasis(parsed) {
+  return parsed?.kind === 'percent';
+}
+
+/** Resolve a parsed size against its basis, then apply its one pixel bound. */
+function toPixels(parsed, basis) {
+  if (parsed.kind === 'px') {
+    return parsed.value;
+  }
+  if (basis == null) {
+    return null;
+  }
+  const percentagePx = Math.round(parsed.value / 100 * basis);
+  if (parsed.min !== undefined) {
+    return Math.max(percentagePx, parsed.min);
+  }
+  if (parsed.max !== undefined) {
+    return Math.min(percentagePx, parsed.max);
+  }
+  return percentagePx;
+}
+function describeUnknown(value) {
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+function describePixelCandidate(value) {
+  if (typeof value !== 'object' || value == null || Array.isArray(value)) {
+    return describeUnknown(value);
+  }
+  const candidate = value;
+  return candidate.type === 'pixel' ? `{"type":"pixel","value":${describeUnknown(candidate.value)}}` : describeUnknown(value);
+}
+function describeSize(value) {
+  if (typeof value === 'object' && value != null && !Array.isArray(value)) {
+    const candidate = value;
+    if (candidate.type === 'pixel') {
+      return describePixelCandidate(value);
+    }
+    if (candidate.type === 'percent') {
+      const fields = ['"type":"percent"', `"value":${describeUnknown(candidate.value)}`];
+      if (candidate.min !== undefined) {
+        fields.push(`"min":${describePixelCandidate(candidate.min)}`);
+      }
+      if (candidate.max !== undefined) {
+        fields.push(`"max":${describePixelCandidate(candidate.max)}`);
+      }
+      return `{${fields.join(',')}}`;
     }
   }
-  return 250;
+  return describeUnknown(value);
+}
+
+/**
+ * Resolves one configured value, applying its role's fallback when the input is
+ * not accepted. The warning remains development-only through `devWarn`; every
+ * build takes the same deterministic fallback.
+ */
+function resolveBound(raw, parsed, basis, fallback, label, accepted, didWarnRef) {
+  if (raw === undefined) {
+    return fallback;
+  }
+  // Preserve the released explicit unbounded maximum on both the unified and
+  // deprecated spellings. Other roles still reject non-finite numbers.
+  if (raw === Infinity && fallback === Infinity) {
+    return Infinity;
+  }
+  if (parsed == null) {
+    if (!didWarnRef.current) {
+      didWarnRef.current = true;
+      devWarn('useResizable', `${label}: ${describeSize(raw)} is not a size. ${accepted} ` + `Falling back to ${fallback}.`);
+    }
+    return fallback;
+  }
+  return toPixels(parsed, basis) ?? fallback;
+}
+
+/**
+ * The container's content-box size on the active axis.
+ *
+ * Content box, not border box: a bordered or padded container would otherwise
+ * report a basis a few pixels larger than the space a percentage is actually a
+ * share of, and that error lands in `aria-valuemax`. The observer entry
+ * carries `contentBoxSize` natively, which is already writing-mode aware;
+ * measuring the element is the fallback for the synthetic entry
+ * `observeResize` fires on registration.
+ */
+function measureContentBox(element, direction, entry) {
+  const box = entry?.contentBoxSize?.[0];
+  if (box) {
+    return direction === 'vertical' ? box.blockSize : box.inlineSize;
+  }
+  const style = typeof window === 'undefined' ? null : window.getComputedStyle(element);
+  if (style == null) {
+    return null;
+  }
+  const size = direction === 'vertical' ? element.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom) : element.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight);
+  return Number.isFinite(size) ? size : null;
 }
 
 // =============================================================================
@@ -135,8 +343,12 @@ function resolveDefaultSize(defaultSize) {
 function useSingleResizable(config) {
   const {
     defaultSize,
-    minSizePx = DEFAULT_MIN,
-    maxSizePx = Infinity,
+    minSize,
+    maxSize,
+    minSizePx,
+    maxSizePx,
+    containerRef,
+    direction = 'horizontal',
     collapsible = false,
     collapsedSize = DEFAULT_COLLAPSED_SIZE,
     snaps: configuredSnaps,
@@ -148,14 +360,226 @@ function useSingleResizable(config) {
   } = config;
   const emptySnapsRef = useRef([]);
   const snaps = configuredSnaps ?? emptySnapsRef.current;
-  const resolvedDefault = resolveDefaultSize(defaultSize);
+
+  // The unified prop wins over its deprecated alias. The types make supplying
+  // both an error, so reaching here means untyped JavaScript, an `any`, or a
+  // spread — exactly the case where a stale alias hidden in an object would
+  // otherwise silently beat the explicit migration target.
+  const hasUnifiedMin = minSize !== undefined;
+  const hasUnifiedMax = maxSize !== undefined;
+  const minConflict = hasUnifiedMin && minSizePx !== undefined;
+  const maxConflict = hasUnifiedMax && maxSizePx !== undefined;
+  const rawMin = hasUnifiedMin ? minSize : minSizePx;
+  const rawMax = hasUnifiedMax ? maxSize : maxSizePx;
+  const parsedDefault = parseSize(defaultSize);
+  const parsedMin = hasUnifiedMin ? parseSize(minSize) : parseLegacyPixel(minSizePx, false);
+  const parsedMax = hasUnifiedMax ? parseSize(maxSize) : parseLegacyPixel(maxSizePx, true);
+  const hasContainer = containerRef != null;
   const persisted = autoSaveId ? loadPersistedState(autoSaveId) : null;
-  const initial = persisted?.size ?? resolvedDefault;
+  const initialDefaultRef = useRef(null);
+  const [, setDefaultBasisCleanupTick] = useState(0);
+  const defaultDependsOnBasis = dependsOnBasis(parsedDefault);
+  const boundsDependOnBasis = dependsOnBasis(parsedMin) || dependsOnBasis(parsedMax);
+  // A default needs a live container only until its initial pixel choice is
+  // final. A persisted pixel choice wins without measuring the unused default.
+  // Bounds are different: percentages keep following the basis so they can
+  // re-clamp the selected pixel size.
+  const defaultNeedsInitialBasis = persisted?.size == null && defaultDependsOnBasis && initialDefaultRef.current?.isFinal !== true;
+  const observeContainerBasis = hasContainer && (boundsDependOnBasis || defaultNeedsInitialBasis);
+  const observeViewportBasis = !hasContainer && boundsDependOnBasis;
+
+  // The container basis, read through the shared observer. `useSyncExternalStore`
+  // rather than an effect: the store IS the measurement, so there is no render
+  // that paints before the basis is known and no `setState` in an effect.
+  //
+  // The subscription depends on the ELEMENT, not on the ref object. A ref is
+  // stable across an element swap, so `containerRef.current` can become a
+  // different node — a remount behind the same ref, a conditional branch, a
+  // portal moving — without any input to this hook changing. Keyed on the ref,
+  // the old detached node stayed observed (and a detached node measures 0,
+  // which is how a replacement zeroed the bounds) and the new one was never
+  // observed at all.
+  const containerElementRef = useRef(null);
+  // DOM ref changes are invisible to React. This state is only a version tick
+  // while basis observation is active; the element itself lives in a ref so it
+  // can be released without adding a cleanup render.
+  const [, setContainerElementVersion] = useState(0);
+  const containerBasisRef = useRef(null);
+  const containerElement = observeContainerBasis ? containerElementRef.current : null;
+
+  // Follow the ref only while some configuration needs its basis. A numeric-only
+  // region never reads the ref. Once observation stops, drop both the element
+  // and its measurement without a state update; a later percentage starts from
+  // the ref's then-current element and a fresh basis.
+  useIsomorphicLayoutEffect(() => {
+    if (!observeContainerBasis) {
+      containerElementRef.current = null;
+      containerBasisRef.current = null;
+      return;
+    }
+    const element = containerRef?.current ?? null;
+    if (element !== containerElementRef.current) {
+      containerBasisRef.current = null;
+      containerElementRef.current = element;
+      setContainerElementVersion(version => version + 1);
+    }
+  });
+  const subscribeToContainer = useCallback(onStoreChange => {
+    if (!observeContainerBasis || containerElement == null || containerElement !== containerRef?.current) {
+      return () => {};
+    }
+    // Unsubscribe by callback: several regions share one container, and any
+    // number of unrelated hooks may observe the same node.
+    return observeResize(containerElement, entry => {
+      containerBasisRef.current = measureContentBox(containerElement, direction, entry);
+      onStoreChange();
+    });
+  }, [containerElement, observeContainerBasis, direction, containerRef]);
+  const readContainerBasis = useCallback(() => {
+    if (!observeContainerBasis || containerElement == null) {
+      // An inactive subscription owns no current measurement. Clearing this is
+      // important when a percentage bound is added later: the first active
+      // render must measure the container as it is now, not clamp against the
+      // last basis seen by a default-only subscription.
+      containerBasisRef.current = null;
+      return null;
+    }
+    // Cached in a ref so the snapshot is referentially stable between resizes;
+    // returning a fresh measurement every call would loop the store.
+    if (containerBasisRef.current == null) {
+      containerBasisRef.current = measureContentBox(containerElement, direction);
+    }
+    return containerBasisRef.current;
+  }, [containerElement, observeContainerBasis, direction]);
+  const containerBasis = useSyncExternalStore(subscribeToContainer, readContainerBasis, () => null);
+
+  // The viewport basis is always readable synchronously. Percentage-dependent
+  // BOUNDS subscribe to later resizes (FR6); a default reads the initial
+  // snapshot only, because it becomes a pixel choice immediately.
+  const subscribeToViewport = useCallback(onStoreChange => {
+    if (hasContainer || !observeViewportBasis || typeof window === 'undefined') {
+      return () => {};
+    }
+    window.addEventListener('resize', onStoreChange);
+    return () => window.removeEventListener('resize', onStoreChange);
+  }, [hasContainer, observeViewportBasis]);
+  const viewportBasis = useSyncExternalStore(subscribeToViewport, () => typeof window === 'undefined' ? SERVER_BASIS : window.innerWidth, () => SERVER_BASIS);
+
+  // With a container, its content box is the basis; without one, the released
+  // viewport basis. Before a supplied container has been measured — the first
+  // render, the server, and any moment it is display:none or detached — the
+  // deterministic 1200px stands in, and the first real measurement replaces it.
+  //
+  // A zero measurement is not a measurement. A hidden or detached container
+  // reports 0, and resolving `'50%'` against it produced a real maximum of 0:
+  // the panel collapsed and, with `autoSaveId`, that 0 was written over a
+  // perfectly good saved width. Treating 0 as unmeasured keeps the temporary
+  // basis until the container is actually laid out (AST-010 Platform support).
+  const needsContainerBasis = observeContainerBasis;
+  const hasPositiveMeasurement = containerBasis != null && containerBasis > 0;
+  const liveBasis = hasContainer ? hasPositiveMeasurement ? containerBasis : SERVER_BASIS : viewportBasis;
+  const isBasisMeasured = needsContainerBasis ? hasPositiveMeasurement : true;
 
-  // `size` is always the *expanded* size: collapse hides it behind the
-  // isCollapsed gate below rather than zeroing it, so the width the user had
-  // survives a collapse, a persist round-trip, and an expand.
-  const [size, setSize] = useState(() => clampSize(initial, minSizePx, maxSizePx, snaps));
+  // One stable basis per gesture. A container that resizes mid-drag would
+  // otherwise move the bound under the pointer; the new basis applies once the
+  // gesture ends.
+  const gestureBasisRef = useRef(null);
+  // Only forces the render that releases the frozen basis when a gesture ends.
+  const [gestureTick, setGestureTick] = useState(0);
+  void gestureTick;
+  const basis = gestureBasisRef.current ?? liveBasis;
+  const didWarnMinRef = useRef(false);
+  const didWarnMaxRef = useRef(false);
+  const didWarnDefaultRef = useRef(false);
+  const didWarnInvertedRef = useRef(false);
+  const didWarnMinAliasRef = useRef(false);
+  const didWarnMaxAliasRef = useRef(false);
+
+  // Bounds re-resolve from the live basis on every render — that is the whole
+  // point of a percentage bound — and clamp the pixel selection below.
+  const resolvedMin = resolveBound(rawMin, parsedMin, basis, DEFAULT_MIN, hasUnifiedMin ? 'minSize' : 'minSizePx', hasUnifiedMin ? RESIZABLE_SIZE_GUIDANCE : LEGACY_PIXEL_GUIDANCE, didWarnMinRef);
+  const resolvedMax = resolveBound(rawMax, parsedMax, basis, Infinity, hasUnifiedMax ? 'maxSize' : 'maxSizePx', hasUnifiedMax ? RESIZABLE_SIZE_GUIDANCE : LEGACY_MAX_PIXEL_GUIDANCE, didWarnMaxRef);
+
+  // A basis-dependent default is resolved ONCE into a pixel size. Latched in a
+  // ref (React's sanctioned lazy-init shape) rather than recomputed, because a
+  // default that kept tracking its basis would be a second, responsive sizing
+  // mode — the thing this API deliberately does not have.
+  //
+  // Not final while a supplied container is still unmeasured: that render used
+  // the temporary 1200px stand-in, and the first real measurement replaces it.
+  // Once final, a default-only subscription is removed. The correction is not a
+  // user interaction, so it neither persists the placeholder nor fires
+  // `onSizeChange`.
+  if (initialDefaultRef.current == null || !initialDefaultRef.current.isFinal) {
+    initialDefaultRef.current = {
+      px: resolveBound(defaultSize, parsedDefault, basis, DEFAULT_SIZE_FALLBACK, 'defaultSize', RESIZABLE_SIZE_GUIDANCE, didWarnDefaultRef),
+      isFinal: isBasisMeasured
+    };
+  }
+  const initialDefaultPx = initialDefaultRef.current.px;
+
+  // The size the user has settled on, or null while a container-relative
+  // default is still waiting for its first positive measurement. Once that
+  // basis is real, the default becomes an ordinary pixel selection — including
+  // any clamp applied at initialization. Leaving it represented by `null`
+  // allowed the raw default to be re-read later: 321px first clamped to 200px
+  // in a 400px container, then revived to 321px when the container grew.
+  //
+  // Initialized outright whenever the basis is already real on the first
+  // render — every pixel-only configuration, and the no-container percentage
+  // path. Only a supplied container needs a measurement that does not exist
+  // until after commit, so only it starts null. Initializing lazily in all
+  // cases cost every legacy pixel-only mount a second render pass, because the
+  // adjustment below then had to run on the first render to fill the value in.
+  const [chosenSize, setChosenSize] = useState(() => {
+    if (persisted?.size != null) {
+      return persisted.size;
+    }
+    return isBasisMeasured ? clampSize(initialDefaultPx, resolvedMin, resolvedMax, snaps) : null;
+  });
+  if (hasContainer && !boundsDependOnBasis && isBasisMeasured && defaultNeedsInitialBasis && chosenSize != null) {
+    // A programmatic resize may have selected pixels while the container was
+    // still unmeasured, so chosenSize can already be non-null here. Force the
+    // render that re-evaluates and removes the now-finished default subscription.
+    setDefaultBasisCleanupTick(tick => tick + 1);
+  }
+  if (isBasisMeasured && chosenSize == null) {
+    // The supplied container has now been measured, so the selection latched
+    // against the temporary basis is replaced by one against the real one.
+    // Render-phase adjustment is deliberate: React re-runs this render before
+    // paint, so the corrected selection, paint, persistence, and ARIA all see
+    // the same pixel value. It fires no interaction callback.
+    setChosenSize(clampSize(initialDefaultPx, resolvedMin, resolvedMax, snaps));
+  }
+
+  // A re-resolved bound clamps the SELECTION, not just the paint. Deriving
+  // alone was not enough: the stored choice survived, so a container that
+  // shrank and grew again revived the pre-clamp size — measured 320px
+  // reviving to 560px. The clamp has to be committed to be permanent.
+  //
+  // Adjusting state during render (React's documented shape for "a prop
+  // changed, so state must follow") rather than in an effect: React re-runs
+  // this render before painting, so nothing shows at the stale size, and no
+  // interaction callback fires for what is only a layout correction (FR10).
+  //
+  // Held until the basis is final. Before a supplied container is measured the
+  // bounds come from the temporary 1200px stand-in, and committing against
+  // that would move a persisted size to fit a basis that was never real.
+  const [committedBounds, setCommittedBounds] = useState({
+    min: resolvedMin,
+    max: resolvedMax
+  });
+  if (isBasisMeasured && gestureBasisRef.current == null && (committedBounds.min !== resolvedMin || committedBounds.max !== resolvedMax)) {
+    setCommittedBounds({
+      min: resolvedMin,
+      max: resolvedMax
+    });
+    setChosenSize(current => current == null ? null : clampSize(current, resolvedMin, resolvedMax, snaps));
+  }
+
+  // Derived for paint, so the clamp above and the rendered size agree on the
+  // very render that observes a new basis.
+  const size = clampSize(chosenSize ?? initialDefaultPx, resolvedMin, resolvedMax, snaps);
   const [uncontrolledIsCollapsed, setUncontrolledIsCollapsed] = useState(() => persisted?.isCollapsed ?? defaultIsCollapsed ?? false);
   const isControlled = controlledIsCollapsed !== undefined;
   const isCollapsed = collapsible && (isControlled ? controlledIsCollapsed : uncontrolledIsCollapsed);
@@ -177,14 +601,37 @@ function useSingleResizable(config) {
       setUncontrolledIsCollapsed(value);
     }
   }, [isControlled]);
+
+  // Configuration warnings live in an effect, not in render: render runs twice
+  // under StrictMode and must stay free of side effects.
   useEffect(() => {
-    if (autoSaveId) {
+    if (minConflict && !didWarnMinAliasRef.current) {
+      didWarnMinAliasRef.current = true;
+      devWarn('useResizable', 'both `minSize` and `minSizePx` were supplied. `minSize` wins; the ' + 'deprecated `minSizePx` is ignored.');
+    }
+    if (maxConflict && !didWarnMaxAliasRef.current) {
+      didWarnMaxAliasRef.current = true;
+      devWarn('useResizable', 'both `maxSize` and `maxSizePx` were supplied. `maxSize` wins; the ' + 'deprecated `maxSizePx` is ignored.');
+    }
+  }, [minConflict, maxConflict]);
+  useEffect(() => {
+    if (resolvedMin > resolvedMax && !didWarnInvertedRef.current) {
+      didWarnInvertedRef.current = true;
+      devWarn('useResizable', `the resolved minimum (${resolvedMin}px) is above the resolved ` + `maximum (${resolvedMax}px). The maximum wins, as it always has.`);
+    }
+  }, [resolvedMin, resolvedMax]);
+  useEffect(() => {
+    // Nothing is written while the basis is still the temporary stand-in. The
+    // size on such a render is a placeholder, and persisting it overwrites the
+    // real saved size with a value derived from a basis that was never real
+    // (AST-010 Platform support, FR9).
+    if (autoSaveId && isBasisMeasured) {
       persistState(autoSaveId, {
         size,
         isCollapsed
       });
     }
-  }, [size, isCollapsed, autoSaveId]);
+  }, [size, isCollapsed, autoSaveId, isBasisMeasured]);
   const collapse = useCallback(() => {
     // The already-collapsed guard keeps a repeated call from re-notifying a
     // transition that already happened.
@@ -204,9 +651,16 @@ function useSingleResizable(config) {
     onSizeChange?.(size);
   }, [setCollapsed, size, onCollapseChange, onSizeChange]);
   const resize = useCallback(newSize => {
-    const clamped = clampSize(newSize, minSizePx, maxSizePx, snaps);
+    // An invalid programmatic size repairs nothing — it must not replace a
+    // legal selection with NaN, which would then reach paint, storage and
+    // `aria-valuenow`.
+    if (!Number.isFinite(newSize) || newSize < 0) {
+      devWarn('useResizable', `resize(${String(newSize)}) is not a pixel size. Keeping the ` + 'current size. Percentages configure the hook; they are not a ' + 'programmatic input.');
+      return;
+    }
+    const clamped = clampSize(newSize, resolvedMin, resolvedMax, snaps);
     const wasCollapsed = isCollapsedRef.current;
-    setSize(clamped);
+    setChosenSize(clamped);
     setCollapsed(false);
     // Resizing out of the collapsed state is an implicit expand — notify
     // like the drag path does when it crosses back over the threshold.
@@ -214,10 +668,13 @@ function useSingleResizable(config) {
       onCollapseChange?.(false);
     }
     onSizeChange?.(clamped);
-  }, [minSizePx, maxSizePx, snaps, setCollapsed, onCollapseChange, onSizeChange]);
+  }, [resolvedMin, resolvedMax, snaps, setCollapsed, onCollapseChange, onSizeChange]);
   const onResizeStart = useCallback(() => {
+    // Freeze the basis for the whole gesture so a container resizing mid-drag
+    // cannot move the bound out from under the pointer.
+    gestureBasisRef.current = liveBasis;
     dragStartSizeRef.current = isCollapsedRef.current ? 0 : size;
-  }, [size]);
+  }, [size, liveBasis]);
   const onResizeMove = useCallback(delta => {
     const raw = dragStartSizeRef.current + delta;
     if (collapsible && raw < collapsedSize) {
@@ -232,24 +689,43 @@ function useSingleResizable(config) {
       setCollapsed(false);
       onCollapseChange?.(false);
     }
-    const clamped = clampSize(raw, minSizePx, maxSizePx, snaps);
-    setSize(clamped);
+    const clamped = clampSize(raw, resolvedMin, resolvedMax, snaps);
+    setChosenSize(clamped);
     onSizeChange?.(clamped);
-  }, [collapsible, collapsedSize, setCollapsed, minSizePx, maxSizePx, snaps, onSizeChange, onCollapseChange]);
-  const onResizeEnd = useCallback(() => {
-    // Sizes already committed during move
+  }, [collapsible, collapsedSize, setCollapsed, resolvedMin, resolvedMax, snaps, onSizeChange, onCollapseChange]);
+
+  // Releasing the frozen basis needs a render to apply whatever the basis
+  // became during the gesture.
+  const releaseGestureBasis = useCallback(() => {
+    if (gestureBasisRef.current != null) {
+      gestureBasisRef.current = null;
+      setGestureTick(tick => tick + 1);
+    }
   }, []);
+  const onResizeEnd = useCallback(() => {
+    // Sizes are already committed during move; only the basis is held.
+    releaseGestureBasis();
+  }, [releaseGestureBasis]);
+
+  // A gesture that is cancelled rather than completed — pointercancel, a lost
+  // capture, a handle unmounted mid-drag — is still over. It does not signal a
+  // resize end (that is #5297's contract, and the sizes were committed during
+  // move anyway), but the basis it froze has to come back, or every later
+  // percentage bound stays pinned to the container size at grab time.
+  const onResizeCancel = releaseGestureBasis;
   const props = {
     _size: isCollapsed ? 0 : size,
     _isCollapsed: isCollapsed,
     _onResizeStart: onResizeStart,
     _onResizeMove: onResizeMove,
     _onResizeEnd: onResizeEnd,
-    _minSizePx: minSizePx,
-    _maxSizePx: maxSizePx,
+    _onResizeCancel: onResizeCancel,
+    _minSizePx: resolvedMin,
+    _maxSizePx: resolvedMax,
     _snaps: snaps,
     _collapsedSize: collapsedSize,
     _collapsible: collapsible,
+    _direction: direction,
     _isResizableProps: true
   };
   return {
@@ -275,7 +751,9 @@ function useSingleResizable(config) {
 function useMultiResizable(config) {
   const {
     regions,
-    autoSaveId
+    autoSaveId,
+    containerRef,
+    direction
   } = config;
 
   // Stable key order — callers must not change region keys between renders.
@@ -288,6 +766,11 @@ function useMultiResizable(config) {
   // eslint-disable-next-line @eslint-react/rules-of-hooks -- region count is stable (documented contract)
   useSingleResizable({
     ...regionConfig,
+    // One container and one axis for every region (AST-010 FR11). Regions
+    // stay independently pixel-selected; sharing a basis introduces no ratio
+    // between them and no 100% total.
+    containerRef,
+    direction,
     autoSaveId: autoSaveId ? `${autoSaveId}:${key}` : undefined
   }));
   const result = {};