@parhelia/core 0.3.12831 → 0.3.12833

package/dist/editor/page-viewer/canvasFrameNavigation.js

@@ -0,0 +1,36 @@
+/**
+ * Navigates the canvas iframe to `url` without adding a browser history entry.
+ *
+ * Browsers record every iframe navigation after the first as an entry in the
+ * page's joint session history. The canvas reloads its frame on version
+ * switches, hard refreshes and pre-bridge fallbacks, so driving those loads
+ * through the `src` attribute made the browser Back button step back through
+ * canvas reloads (re-rendering a stale `edit_rev`) before it ever left the
+ * page - and the editor's popstate handler never saw a URL change. Traversing
+ * such an entry only navigates the iframe: the top-level URL stays put.
+ *
+ * `location.replace()` swaps the frame's current entry in place instead, and
+ * is callable on cross-origin frames. The first load still goes through `src`:
+ * navigating away from the initial about:blank document replaces its entry,
+ * and consumers that fall back to reading the attribute keep a meaningful
+ * value.
+ */
+export function navigateCanvasFrame(iframe, url) {
+    if (!iframe.getAttribute("src")) {
+        iframe.src = url;
+        return;
+    }
+    try {
+        const frameWindow = iframe.contentWindow;
+        if (frameWindow) {
+            frameWindow.location.replace(url);
+            return;
+        }
+    }
+    catch {
+        // A detached or otherwise inaccessible frame window: fall through to the
+        // attribute so the canvas still loads, even at the cost of a history entry.
+    }
+    iframe.src = url;
+}
+//# sourceMappingURL=canvasFrameNavigation.js.map

package/dist/editor/page-viewer/canvasFrameNavigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasFrameNavigation.js","sourceRoot":"","sources":["../../../src/editor/page-viewer/canvasFrameNavigation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAyB,EACzB,GAAW;IAEX,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC;QACjB,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC;QACzC,IAAI,WAAW,EAAE,CAAC;YAChB,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO;QACT,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,4EAA4E;IAC9E,CAAC;IAED,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC;AACnB,CAAC"}

package/dist/editor/page-viewer/canvasLoadSettling.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Decides what a pre-bridge re-run of the canvas render effect should do while
+ * a full iframe load is still settling.
+ *
+ * Opening a page sets the iframe src ("initial load"). The effect usually
+ * re-runs shortly afterwards with an otherwise identical URL - the edit
+ * revision becomes defined once the page model lands, or a dependency changes
+ * identity - while the bridge has not connected yet. Routing that re-run
+ * through the pre-bridge recovery path issued a second full load that differed
+ * only by the edit_rev nonce: a wasted host render and a visible canvas flash.
+ *
+ * A load is "settling" from the moment its src is set until the bridge is
+ * ready, with two bounds: a grace period after the document's load event for
+ * the bridge handshake, and an overall cap for loads that never fire it. Inside
+ * that window the re-run waits; once it closes the outcome is decided by the
+ * bridge: ready and signature unchanged means the load already covered the
+ * re-run, ready and signature changed means an incremental bridge refresh, and
+ * no bridge means the documented recovery reload for a genuinely failed load.
+ */
+export type InFlightCanvasLoad = {
+    /** Render URL without the per-request edit_rev nonce. */
+    signatureUrl: string;
+    /** The exact src requested, so a stale load event cannot settle a newer load. */
+    requestedSrc: string;
+    startedAt: number;
+    /** Set when the iframe fired `load` for `requestedSrc`. */
+    loadedAt?: number;
+};
+/** How long after the iframe load event the bridge handshake may still land. */
+export declare const CANVAS_LOAD_BRIDGE_GRACE_MS = 2000;
+/** Upper bound for a load that never fires its load event. */
+export declare const CANVAS_LOAD_SETTLE_MAX_MS = 15000;
+export declare function isCanvasLoadSettling(load: InFlightCanvasLoad | null | undefined, signatureUrl: string, now: number): boolean;
+export type DeferredCanvasRefreshDecision = "wait" | "skip" | "bridge-refresh" | "reload";
+export declare function resolveDeferredCanvasRefresh(input: {
+    bridgeSupportsRefresh: boolean;
+    renderSignature: string;
+    lastAppliedSignature: string | undefined;
+    load: InFlightCanvasLoad | null | undefined;
+    signatureUrl: string;
+    now: number;
+}): DeferredCanvasRefreshDecision;

package/dist/editor/page-viewer/canvasLoadSettling.js

@@ -0,0 +1,46 @@
+/**
+ * Decides what a pre-bridge re-run of the canvas render effect should do while
+ * a full iframe load is still settling.
+ *
+ * Opening a page sets the iframe src ("initial load"). The effect usually
+ * re-runs shortly afterwards with an otherwise identical URL - the edit
+ * revision becomes defined once the page model lands, or a dependency changes
+ * identity - while the bridge has not connected yet. Routing that re-run
+ * through the pre-bridge recovery path issued a second full load that differed
+ * only by the edit_rev nonce: a wasted host render and a visible canvas flash.
+ *
+ * A load is "settling" from the moment its src is set until the bridge is
+ * ready, with two bounds: a grace period after the document's load event for
+ * the bridge handshake, and an overall cap for loads that never fire it. Inside
+ * that window the re-run waits; once it closes the outcome is decided by the
+ * bridge: ready and signature unchanged means the load already covered the
+ * re-run, ready and signature changed means an incremental bridge refresh, and
+ * no bridge means the documented recovery reload for a genuinely failed load.
+ */
+/** How long after the iframe load event the bridge handshake may still land. */
+export const CANVAS_LOAD_BRIDGE_GRACE_MS = 2000;
+/** Upper bound for a load that never fires its load event. */
+export const CANVAS_LOAD_SETTLE_MAX_MS = 15000;
+export function isCanvasLoadSettling(load, signatureUrl, now) {
+    if (!load || load.signatureUrl !== signatureUrl)
+        return false;
+    if (now - load.startedAt >= CANVAS_LOAD_SETTLE_MAX_MS)
+        return false;
+    if (load.loadedAt !== undefined &&
+        now - load.loadedAt >= CANVAS_LOAD_BRIDGE_GRACE_MS) {
+        return false;
+    }
+    return true;
+}
+export function resolveDeferredCanvasRefresh(input) {
+    if (input.bridgeSupportsRefresh) {
+        return input.lastAppliedSignature === input.renderSignature
+            ? "skip"
+            : "bridge-refresh";
+    }
+    if (isCanvasLoadSettling(input.load, input.signatureUrl, input.now)) {
+        return "wait";
+    }
+    return "reload";
+}
+//# sourceMappingURL=canvasLoadSettling.js.map

package/dist/editor/page-viewer/canvasLoadSettling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasLoadSettling.js","sourceRoot":"","sources":["../../../src/editor/page-viewer/canvasLoadSettling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,gFAAgF;AAChF,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAChD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAE/C,MAAM,UAAU,oBAAoB,CAClC,IAA2C,EAC3C,YAAoB,EACpB,GAAW;IAEX,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,YAAY,KAAK,YAAY;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,yBAAyB;QAAE,OAAO,KAAK,CAAC;IACpE,IACE,IAAI,CAAC,QAAQ,KAAK,SAAS;QAC3B,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,2BAA2B,EAClD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAQD,MAAM,UAAU,4BAA4B,CAAC,KAO5C;IACC,IAAI,KAAK,CAAC,qBAAqB,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC,oBAAoB,KAAK,KAAK,CAAC,eAAe;YACzD,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,gBAAgB,CAAC;IACvB,CAAC;IACD,IAAI,oBAAoB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACpE,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/editor/page-viewer/canvasScrollHandoff.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Carries the canvas scroll position from a page frame that unmounts to the
+ * frame that mounts for the same page right after it.
+ *
+ * Switching layouts - entering or leaving fullscreen - renders the page in a
+ * different part of the React tree, so the old iframe is destroyed and the new
+ * one loads the page from scratch at the top. The unmounting frame stashes its
+ * scroll here and the new frame uses it as the initial restore target, through
+ * the same path that keeps the scroll across canvas reloads.
+ *
+ * The new canvas usually has a different width (fullscreen vs. sidebars), so
+ * the page reflows and the same pixel offset shows different content. When the
+ * selected component was in view it is stashed as an anchor, and the new frame
+ * puts it back at the same distance from the canvas top.
+ *
+ * Entries are one-shot and short-lived: they bridge an unmount and a remount
+ * that happen together, and must never land a later, unrelated page open at an
+ * old offset.
+ */
+import type { BridgeScroll } from "../bridge/protocol";
+import type { ItemDescriptor } from "../pageModel";
+export declare const CANVAS_SCROLL_HANDOFF_TTL_MS = 5000;
+export type CanvasScrollAnchor = {
+    componentId: string;
+    /** Distance of the component's top from the canvas top, in geometry units. */
+    viewportTop: number;
+};
+export type CanvasScrollHandoff = {
+    scroll: BridgeScroll;
+    anchor?: CanvasScrollAnchor;
+};
+export declare function getCanvasScrollHandoffKey(page: Pick<ItemDescriptor, "id" | "language" | "version">): string;
+export declare function stashCanvasScrollHandoff(key: string, handoff: CanvasScrollHandoff | undefined, now?: number): void;
+export declare function takeCanvasScrollHandoff(key: string, now?: number): CanvasScrollHandoff | undefined;

package/dist/editor/page-viewer/canvasScrollHandoff.js

@@ -0,0 +1,55 @@
+/**
+ * Carries the canvas scroll position from a page frame that unmounts to the
+ * frame that mounts for the same page right after it.
+ *
+ * Switching layouts - entering or leaving fullscreen - renders the page in a
+ * different part of the React tree, so the old iframe is destroyed and the new
+ * one loads the page from scratch at the top. The unmounting frame stashes its
+ * scroll here and the new frame uses it as the initial restore target, through
+ * the same path that keeps the scroll across canvas reloads.
+ *
+ * The new canvas usually has a different width (fullscreen vs. sidebars), so
+ * the page reflows and the same pixel offset shows different content. When the
+ * selected component was in view it is stashed as an anchor, and the new frame
+ * puts it back at the same distance from the canvas top.
+ *
+ * Entries are one-shot and short-lived: they bridge an unmount and a remount
+ * that happen together, and must never land a later, unrelated page open at an
+ * old offset.
+ */
+export const CANVAS_SCROLL_HANDOFF_TTL_MS = 5000;
+const handoffs = new Map();
+export function getCanvasScrollHandoffKey(page) {
+    return [page.id, page.language, page.version].join("|");
+}
+export function stashCanvasScrollHandoff(key, handoff, now = Date.now()) {
+    for (const [storedKey, stored] of handoffs) {
+        if (now - stored.storedAt > CANVAS_SCROLL_HANDOFF_TTL_MS) {
+            handoffs.delete(storedKey);
+        }
+    }
+    // A frame at the top with nothing selected in view has nothing to hand
+    // over, and must not leave an older offset behind for the next frame.
+    const { scroll, anchor } = handoff ?? {};
+    if (!scroll || (scroll.x <= 0 && scroll.y <= 0 && !anchor)) {
+        handoffs.delete(key);
+        return;
+    }
+    handoffs.set(key, {
+        handoff: {
+            scroll: { x: scroll.x, y: scroll.y },
+            ...(anchor ? { anchor: { ...anchor } } : {}),
+        },
+        storedAt: now,
+    });
+}
+export function takeCanvasScrollHandoff(key, now = Date.now()) {
+    const stored = handoffs.get(key);
+    if (!stored)
+        return undefined;
+    handoffs.delete(key);
+    return now - stored.storedAt <= CANVAS_SCROLL_HANDOFF_TTL_MS
+        ? stored.handoff
+        : undefined;
+}
+//# sourceMappingURL=canvasScrollHandoff.js.map

package/dist/editor/page-viewer/canvasScrollHandoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasScrollHandoff.js","sourceRoot":"","sources":["../../../src/editor/page-viewer/canvasScrollHandoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC;AAajD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAGrB,CAAC;AAEJ,MAAM,UAAU,yBAAyB,CACvC,IAAyD;IAEzD,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,GAAW,EACX,OAAwC,EACxC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAEhB,KAAK,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC3C,IAAI,GAAG,GAAG,MAAM,CAAC,QAAQ,GAAG,4BAA4B,EAAE,CAAC;YACzD,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,uEAAuE;IACvE,sEAAsE;IACtE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IACzC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3D,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE;QAChB,OAAO,EAAE;YACP,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE;YACpC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7C;QACD,QAAQ,EAAE,GAAG;KACd,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,GAAW,EACX,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAEhB,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,OAAO,GAAG,GAAG,MAAM,CAAC,QAAQ,IAAI,4BAA4B;QAC1D,CAAC,CAAC,MAAM,CAAC,OAAO;QAChB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}

package/dist/editor/page-viewer/compareFrameWidth.d.ts

@@ -0,0 +1,8 @@
+export type CompareFrameView = "primary" | "compare";
+export type CompareFrameWidths = Partial<Record<CompareFrameView, number>>;
+/**
+ * The width both compare-view iframes render at, or undefined while either
+ * pane has not reported a usable width yet (the panes then keep filling their
+ * own space, as outside compare mode).
+ */
+export declare function resolveSharedCompareFrameWidth(widths: CompareFrameWidths): number | undefined;

package/dist/editor/page-viewer/compareFrameWidth.js

@@ -0,0 +1,25 @@
+// Shared page-iframe width for the compare view.
+//
+// In compare mode the two panes sit in a user-resizable splitter and each pane
+// decides on its own whether the minimap column is visible. Left to itself,
+// each page iframe fills whatever is left in its pane, so the two versions are
+// rendered at different viewport widths and text reflows differently — a
+// changed paragraph then looks different even where the words are identical.
+// Both panes therefore report the width their iframe could take, and both
+// render the iframe at the narrower of the two so the layouts line up.
+/**
+ * The width both compare-view iframes render at, or undefined while either
+ * pane has not reported a usable width yet (the panes then keep filling their
+ * own space, as outside compare mode).
+ */
+export function resolveSharedCompareFrameWidth(widths) {
+    const primary = widths.primary;
+    const compare = widths.compare;
+    if (!isUsableWidth(primary) || !isUsableWidth(compare))
+        return undefined;
+    return Math.floor(Math.min(primary, compare));
+}
+function isUsableWidth(width) {
+    return typeof width === "number" && Number.isFinite(width) && width > 0;
+}
+//# sourceMappingURL=compareFrameWidth.js.map

package/dist/editor/page-viewer/compareFrameWidth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compareFrameWidth.js","sourceRoot":"","sources":["../../../src/editor/page-viewer/compareFrameWidth.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAC/E,yEAAyE;AACzE,6EAA6E;AAC7E,0EAA0E;AAC1E,uEAAuE;AAMvE;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAA0B;IAE1B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IACzE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,aAAa,CAAC,KAAyB;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AAC1E,CAAC"}

package/dist/editor/page-viewer/feedbackMarginLayout.d.ts

@@ -0,0 +1,119 @@
+import type { FeedbackAnchor } from "../page-editor-chrome/overlay/feedbackAnchorMeasurements";
+import type { FeedbackThread } from "../reviews/feedbackThreads";
+export type MarginMode = "anchored" | "stacked";
+export type AnchoredMarginThread = {
+    id: string;
+    anchorY: number;
+    created: number;
+};
+export type MarginThreadOrder = {
+    /** Threads with a position on the page, top to bottom. */
+    anchored: AnchoredMarginThread[];
+    /** Threads whose anchor is not rendered on this page. */
+    unplaced: string[];
+};
+export type RememberedAnchor = {
+    anchor: FeedbackAnchor;
+    /** When the measurement went away; unset while the thread is measured. */
+    lostAt?: number;
+};
+/** How long a thread keeps its last anchor after its measurement went away. */
+export declare const REMEMBERED_ANCHOR_MS = 8000;
+/**
+ * The anchor of every thread: its current measurement, or for a short while
+ * the last one it had. A canvas reload or re-render drops the measurements
+ * for a moment and the cards must not jump into the "content not shown" footer
+ * and back; but a thread whose text is really gone (component deleted or
+ * hidden) has to end up there, so the memory expires. `remembered` is updated
+ * in place; `nextExpiry` is when the result has to be recomputed.
+ */
+export declare function resolveMarginAnchors(threads: readonly FeedbackThread[], measure: (thread: FeedbackThread) => FeedbackAnchor | undefined, remembered: Map<string, RememberedAnchor>, now: number): {
+    anchors: Record<string, FeedbackAnchor | undefined>;
+    nextExpiry: number | undefined;
+};
+/**
+ * Splits threads into the ones that can sit beside their text and the ones
+ * that cannot, and orders the former by anchor. A freshly drafted comment
+ * without a measurable anchor is still shown, at `draftFallbackY` (the top of
+ * the visible column), so the composer is never hidden in the footer.
+ */
+export declare function orderMarginThreads(threads: readonly FeedbackThread[], anchors: Readonly<Record<string, FeedbackAnchor | undefined>>, draftFallbackY: number): MarginThreadOrder;
+/**
+ * Anchored is the normal presentation. The column falls back to a scrolling
+ * stack when the cards cannot fit, and only returns once they fit with some
+ * slack, so a card growing by a few pixels does not flip the column back and
+ * forth.
+ */
+export declare function decideMarginMode(current: MarginMode, fits: boolean, fitsWithSlack: boolean): MarginMode;
+/** Height cap for one card body so a single long thread never exceeds the page. */
+export declare function getCardBodyMaxHeight(columnHeight: number): number;
+/**
+ * The narrowest canvas the full margin may leave beside itself. Matches the
+ * canvas pane's own minimum splitter width, so the margin never squeezes the
+ * canvas below what the pane guarantees on its own.
+ */
+export declare const FEEDBACK_MARGIN_MIN_CANVAS_WIDTH = 320;
+/**
+ * `full`: cards beside their text. `rail`: a narrow strip of markers beside
+ * their text; the selected thread's card floats over the canvas edge.
+ */
+export type FeedbackMarginPresentation = "full" | "rail";
+export type FeedbackMarginSize = {
+    presentation: FeedbackMarginPresentation;
+    width: number;
+    /**
+     * The rail is there because the user collapsed a column the pane has room
+     * for: its edge drags the column open again and expanding it docks the
+     * column instead of floating it over the canvas.
+     */
+    collapsed?: boolean;
+};
+/**
+ * The widest the margin column may be while the canvas keeps
+ * `minCanvasWidth`; undefined before the pane has been measured. Also the
+ * limit for resizing the column by hand.
+ */
+export declare function getFeedbackMarginRoom({ paneWidth, reservedWidth, minCanvasWidth, }: {
+    paneWidth: number | undefined;
+    reservedWidth: number;
+    minCanvasWidth?: number;
+}): number | undefined;
+/**
+ * How wide the margin column is beside the canvas. `paneWidth` is the content
+ * width of the canvas pane; before the first measurement it is undefined and
+ * the column takes its full width, so it does not flash narrow on mount.
+ * `reservedWidth` is what other columns in the pane (the minimap) already take.
+ *
+ * The column gives up width before the canvas does: it shrinks from `maxWidth`
+ * to `minWidth` while the canvas keeps `minCanvasWidth`, and below that
+ * collapses into the marker rail. The rail is always shown, even when the
+ * canvas then gets less than its minimum: comments never silently disappear
+ * while they are switched on. The pane width does not depend on the column,
+ * so the result cannot flap. A column the user `collapsed` is the rail even
+ * where the pane has room for it.
+ */
+export declare function resolveFeedbackMarginSize({ paneWidth, reservedWidth, maxWidth, minWidth, railWidth, collapsed, minCanvasWidth, }: {
+    paneWidth: number | undefined;
+    reservedWidth: number;
+    maxWidth: number;
+    minWidth: number;
+    railWidth: number;
+    collapsed?: boolean;
+    minCanvasWidth?: number;
+}): FeedbackMarginSize;
+export type FeedbackMarginGate = {
+    showComments: boolean;
+    compareView: boolean;
+    isMobile: boolean;
+    fullscreen: boolean;
+    slotActive: boolean;
+    hasLayout: boolean;
+};
+/**
+ * The margin belongs to the primary, active canvas pane of the desktop editor.
+ * Compare panes, fullscreen presentation, items without a layout and mobile
+ * (which lists comments in a panel below the canvas instead, see
+ * MobileCommentsPanel) never show it. A narrow pane does not hide it; it
+ * narrows or collapses into a rail (resolveFeedbackMarginSize).
+ */
+export declare function shouldShowFeedbackMargin({ showComments, compareView, isMobile, fullscreen, slotActive, hasLayout, }: FeedbackMarginGate): boolean;

package/dist/editor/page-viewer/feedbackMarginLayout.js

@@ -0,0 +1,155 @@
+import { compareBalloonAnchors } from "../reviews/balloonLayout";
+/** How long a thread keeps its last anchor after its measurement went away. */
+export const REMEMBERED_ANCHOR_MS = 8000;
+/**
+ * The anchor of every thread: its current measurement, or for a short while
+ * the last one it had. A canvas reload or re-render drops the measurements
+ * for a moment and the cards must not jump into the "content not shown" footer
+ * and back; but a thread whose text is really gone (component deleted or
+ * hidden) has to end up there, so the memory expires. `remembered` is updated
+ * in place; `nextExpiry` is when the result has to be recomputed.
+ */
+export function resolveMarginAnchors(threads, measure, remembered, now) {
+    const anchors = {};
+    const measuredIds = new Set();
+    for (const thread of threads) {
+        const measured = measure(thread);
+        if (!measured)
+            continue;
+        measuredIds.add(thread.id);
+        remembered.set(thread.id, { anchor: measured });
+        anchors[thread.id] = measured;
+    }
+    // Everything else (unmeasured threads, threads of other pages) runs on the
+    // clock that started when its measurement was first found missing.
+    const listedIds = new Set(threads.map((thread) => thread.id));
+    let nextExpiry;
+    remembered.forEach((entry, id) => {
+        if (measuredIds.has(id))
+            return;
+        entry.lostAt ??= now;
+        const expiry = entry.lostAt + REMEMBERED_ANCHOR_MS;
+        if (now >= expiry) {
+            remembered.delete(id);
+            return;
+        }
+        if (!listedIds.has(id))
+            return;
+        anchors[id] = entry.anchor;
+        nextExpiry =
+            nextExpiry === undefined ? expiry : Math.min(nextExpiry, expiry);
+    });
+    return { anchors, nextExpiry };
+}
+/**
+ * Splits threads into the ones that can sit beside their text and the ones
+ * that cannot, and orders the former by anchor. A freshly drafted comment
+ * without a measurable anchor is still shown, at `draftFallbackY` (the top of
+ * the visible column), so the composer is never hidden in the footer.
+ */
+export function orderMarginThreads(threads, anchors, draftFallbackY) {
+    const anchored = [];
+    const unplaced = [];
+    for (const thread of threads) {
+        const anchor = anchors[thread.id];
+        if (anchor) {
+            anchored.push({
+                id: thread.id,
+                anchorY: anchor.y,
+                created: thread.created,
+            });
+            continue;
+        }
+        if (thread.kind === "comment" && thread.root.isNew) {
+            anchored.push({
+                id: thread.id,
+                anchorY: draftFallbackY,
+                created: thread.created,
+            });
+            continue;
+        }
+        unplaced.push(thread.id);
+    }
+    anchored.sort(compareBalloonAnchors);
+    return { anchored, unplaced };
+}
+/**
+ * Anchored is the normal presentation. The column falls back to a scrolling
+ * stack when the cards cannot fit, and only returns once they fit with some
+ * slack, so a card growing by a few pixels does not flip the column back and
+ * forth.
+ */
+export function decideMarginMode(current, fits, fitsWithSlack) {
+    if (current === "anchored")
+        return fits ? "anchored" : "stacked";
+    return fitsWithSlack ? "anchored" : "stacked";
+}
+/** Height cap for one card body so a single long thread never exceeds the page. */
+export function getCardBodyMaxHeight(columnHeight) {
+    if (!Number.isFinite(columnHeight) || columnHeight <= 0)
+        return 480;
+    return Math.round(Math.min(480, Math.max(240, columnHeight * 0.45)));
+}
+/**
+ * The narrowest canvas the full margin may leave beside itself. Matches the
+ * canvas pane's own minimum splitter width, so the margin never squeezes the
+ * canvas below what the pane guarantees on its own.
+ */
+export const FEEDBACK_MARGIN_MIN_CANVAS_WIDTH = 320;
+/**
+ * The widest the margin column may be while the canvas keeps
+ * `minCanvasWidth`; undefined before the pane has been measured. Also the
+ * limit for resizing the column by hand.
+ */
+export function getFeedbackMarginRoom({ paneWidth, reservedWidth, minCanvasWidth = FEEDBACK_MARGIN_MIN_CANVAS_WIDTH, }) {
+    if (paneWidth === undefined || !Number.isFinite(paneWidth))
+        return undefined;
+    return Math.floor(paneWidth - reservedWidth - minCanvasWidth);
+}
+/**
+ * How wide the margin column is beside the canvas. `paneWidth` is the content
+ * width of the canvas pane; before the first measurement it is undefined and
+ * the column takes its full width, so it does not flash narrow on mount.
+ * `reservedWidth` is what other columns in the pane (the minimap) already take.
+ *
+ * The column gives up width before the canvas does: it shrinks from `maxWidth`
+ * to `minWidth` while the canvas keeps `minCanvasWidth`, and below that
+ * collapses into the marker rail. The rail is always shown, even when the
+ * canvas then gets less than its minimum: comments never silently disappear
+ * while they are switched on. The pane width does not depend on the column,
+ * so the result cannot flap. A column the user `collapsed` is the rail even
+ * where the pane has room for it.
+ */
+export function resolveFeedbackMarginSize({ paneWidth, reservedWidth, maxWidth, minWidth, railWidth, collapsed = false, minCanvasWidth = FEEDBACK_MARGIN_MIN_CANVAS_WIDTH, }) {
+    const available = getFeedbackMarginRoom({
+        paneWidth,
+        reservedWidth,
+        minCanvasWidth,
+    });
+    if (available === undefined || available >= minWidth) {
+        if (collapsed) {
+            return { presentation: "rail", width: railWidth, collapsed: true };
+        }
+        return {
+            presentation: "full",
+            width: available === undefined ? maxWidth : Math.min(maxWidth, available),
+        };
+    }
+    return { presentation: "rail", width: railWidth };
+}
+/**
+ * The margin belongs to the primary, active canvas pane of the desktop editor.
+ * Compare panes, fullscreen presentation, items without a layout and mobile
+ * (which lists comments in a panel below the canvas instead, see
+ * MobileCommentsPanel) never show it. A narrow pane does not hide it; it
+ * narrows or collapses into a rail (resolveFeedbackMarginSize).
+ */
+export function shouldShowFeedbackMargin({ showComments, compareView, isMobile, fullscreen, slotActive, hasLayout, }) {
+    return (showComments &&
+        !compareView &&
+        !isMobile &&
+        !fullscreen &&
+        slotActive &&
+        hasLayout);
+}
+//# sourceMappingURL=feedbackMarginLayout.js.map

package/dist/editor/page-viewer/feedbackMarginLayout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedbackMarginLayout.js","sourceRoot":"","sources":["../../../src/editor/page-viewer/feedbackMarginLayout.ts"],"names":[],"mappings":"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"}

package/dist/editor/page-viewer/feedbackMarginSources.d.ts

@@ -0,0 +1,36 @@
+import { type FeedbackAnchor } from "../page-editor-chrome/overlay/feedbackAnchorMeasurements";
+import type { FeedbackThread } from "../reviews/feedbackThreads";
+import type { FeedbackMarginSource } from "./FeedbackMarginController";
+import { type PageViewContext } from "./pageViewContext";
+/**
+ * The anchor of every listed thread, with a short memory: a thread that
+ * loses its canvas measurement while it is still listed (a suggestion that
+ * was just applied or rejected no longer marks the canvas, a page re-render
+ * briefly drops a target) keeps its last known anchor, so its card stays
+ * beside its text instead of jumping into the "content not shown" footer.
+ * Only for a moment, though: text that is really gone (component deleted or
+ * hidden) sends its card to the footer once the memory expires.
+ */
+export declare function useRememberedMarginAnchors(threads: readonly FeedbackThread[], measure: (thread: FeedbackThread) => FeedbackAnchor | undefined): Record<string, FeedbackAnchor | undefined>;
+/**
+ * The canvas as the margin's surface. Anchors come from the canvas overlay's
+ * own measurements (published by the highlight components), so a card can
+ * only ever sit where its highlight is; the margin does not measure on its
+ * own. Must run inside the margin's `IframeOverlayProvider`.
+ */
+export declare function useCanvasMarginSource(pageViewContext: PageViewContext): FeedbackMarginSource;
+/**
+ * Anchors every thread to its field in the item form (`[data-field-id]`
+ * elements under `form`), in coordinates relative to the form's top. A thread
+ * without a field is about the item itself and anchors to the top of the
+ * form. Threads whose field is not rendered (a field of another item, a
+ * collapsed or hidden section) get no anchor and end up in the margin's
+ * footer.
+ */
+export declare function measureFormAnchors(form: HTMLElement, threads: readonly FeedbackThread[]): Record<string, FeedbackAnchor>;
+/**
+ * The item form as the margin's surface. The column scrolls natively with the
+ * form (both live in `scroller`), so anchors are plain offsets from the top
+ * of `form`, re-measured whenever the form changes size or structure.
+ */
+export declare function useFormMarginSource(scroller: HTMLElement | null, form: HTMLElement | null, threads: readonly FeedbackThread[]): FeedbackMarginSource;