@commentray/render 0.2.0 → 0.3.0

package/dist/code-browser-smooth-reveal-dedup.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Historical ceiling for smooth-scroll duration (hash / search helpers may still use `smooth`).
+ * Dual-pane block sync uses **instant** partner writes (`applyRevealChildInPane`); partner echo
+ * suppression stays above this constant so any remaining smooth paths do not masquerade as driver
+ * input mid-gesture.
+ */
+/**
+ * Ceiling used when sizing partner echo suppression in `code-browser-client` so a smooth
+ * programmatic scroll (if any) is not mistaken for user input mid-animation.
+ */
+export declare const SMOOTH_REVEAL_INFLIGHT_DEDUP_MS = 800;
+/** Sub-pixel tolerance — clamp / `getBoundingClientRect` math drifts by less than this between frames. */
+export declare const SMOOTH_REVEAL_TARGET_EPSILON_PX = 0.5;
+export type SmoothRevealInFlight = {
+    /** Clamped scrollTop the most recent `scrollTo` was aimed at. */
+    target: number;
+    /** `performance.now()` at the moment of issue. */
+    issuedAt: number;
+};
+/**
+ * True when `target` essentially equals the last-issued target and the in-flight glide is still
+ * within the typical animation duration. The caller should skip its `scrollTo` in that case.
+ */
+export declare function smoothRevealAlreadyInFlight(last: SmoothRevealInFlight | null, target: number, now: number): boolean;
+//# sourceMappingURL=code-browser-smooth-reveal-dedup.d.ts.map

package/dist/code-browser-smooth-reveal-dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-browser-smooth-reveal-dedup.d.ts","sourceRoot":"","sources":["../src/code-browser-smooth-reveal-dedup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,0GAA0G;AAC1G,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,MAAM,MAAM,oBAAoB,GAAG;IACjC,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,oBAAoB,GAAG,IAAI,EACjC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAIT"}

package/dist/code-browser-smooth-reveal-dedup.js

@@ -0,0 +1,25 @@
+/**
+ * Historical ceiling for smooth-scroll duration (hash / search helpers may still use `smooth`).
+ * Dual-pane block sync uses **instant** partner writes (`applyRevealChildInPane`); partner echo
+ * suppression stays above this constant so any remaining smooth paths do not masquerade as driver
+ * input mid-gesture.
+ */
+/**
+ * Ceiling used when sizing partner echo suppression in `code-browser-client` so a smooth
+ * programmatic scroll (if any) is not mistaken for user input mid-animation.
+ */
+export const SMOOTH_REVEAL_INFLIGHT_DEDUP_MS = 800;
+/** Sub-pixel tolerance — clamp / `getBoundingClientRect` math drifts by less than this between frames. */
+export const SMOOTH_REVEAL_TARGET_EPSILON_PX = 0.5;
+/**
+ * True when `target` essentially equals the last-issued target and the in-flight glide is still
+ * within the typical animation duration. The caller should skip its `scrollTo` in that case.
+ */
+export function smoothRevealAlreadyInFlight(last, target, now) {
+    if (last === null)
+        return false;
+    if (Math.abs(last.target - target) > SMOOTH_REVEAL_TARGET_EPSILON_PX)
+        return false;
+    return now - last.issuedAt < SMOOTH_REVEAL_INFLIGHT_DEDUP_MS;
+}
+//# sourceMappingURL=code-browser-smooth-reveal-dedup.js.map

package/dist/code-browser-smooth-reveal-dedup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-browser-smooth-reveal-dedup.js","sourceRoot":"","sources":["../src/code-browser-smooth-reveal-dedup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAEnD,0GAA0G;AAC1G,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAC;AASnD;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAiC,EACjC,MAAc,EACd,GAAW;IAEX,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,+BAA+B;QAAE,OAAO,KAAK,CAAC;IACnF,OAAO,GAAG,GAAG,IAAI,CAAC,QAAQ,GAAG,+BAA+B,CAAC;AAC/D,CAAC"}

package/dist/code-browser.d.ts

@@ -1,5 +1,7 @@
 import { type CommentrayIndex } from "@commentray/core";
+import { type StretchBufferSyncStrategy } from "./block-stretch-layout.js";
 import { type CommentrayOutputUrlOptions } from "./markdown-pipeline.js";
+import { type DualPaneScrollSyncStrategyId } from "./code-browser-scroll-sync-strategy.js";
 /** One angle tab for {@link CodeBrowserPageOptions.multiAngleBrowsing}. */
 export type CodeBrowserMultiAngleSpec = {
     id: string;
@@ -9,9 +11,8 @@ export type CodeBrowserMultiAngleSpec = {
     commentrayOnGithubUrl?: string;
     /**
      * When the static site emits per-pair browse pages, same-tab navigation for the Doc toolbar
-     * (preferred over {@link commentrayOnGithubUrl} on the hub). Typical values are hub-relative
-     * `./browse/<human-path>/index.html` or `./browse/<source>@<angle>.html`; opaque `./browse/<hash>.html`
-     * remains valid for the canonical HTML file on disk.
+     * (preferred over {@link commentrayOnGithubUrl} on the hub). Paths mirror the companion layout
+     * under `./browse/…/index.html` (see `staticBrowseIndexRelPathFromPair` in `@commentray/core`).
      */
     staticBrowseUrl?: string;
     /**
@@ -48,8 +49,9 @@ export type CodeBrowserPageOptions = {
      */
     githubRepoUrl?: string;
     /**
-     * Same-site URL for the static documentation hub (e.g. `./` on `index.html`, `../index.html`
-     * under `browse/`). When set, the first toolbar control is a **home** link here instead of
+     * Same-site URL for the static documentation hub (e.g. `./` on `index.html`, or a
+     * depth-correct relative path to the hub from nested `browse/…` pages — see static export).
+     * When set, the first toolbar control is a **home** link here instead of
      * {@link githubRepoUrl}. Uses the same path safety rules as {@link commentrayStaticBrowseUrl}.
      */
     siteHubUrl?: string;
@@ -104,6 +106,18 @@ export type CodeBrowserPageOptions = {
      * **block-aware** scroll sync and separator lines in the commentray pane.
      */
     codeBrowserLayout?: "auto" | "dual";
+    /**
+     * Stretch layout only. Omitted uses `DEFAULT_STRETCH_BUFFER_SYNC` from `@commentray/core`
+     * (`flow-synchronizer`: sync ids + measure wrappers + client `BufferingFlowSynchronizer`).
+     * `table`: legacy row height only, no shell flag / client padding pass.
+     */
+    stretchBufferSync?: StretchBufferSyncStrategy;
+    /**
+     * Dual-pane scroll correlation (`#shell data-scroll-sync-strategy`). Strategies are mutually
+     * exclusive in the client; omit or set to the default for normal builds. `filler-blocks` is
+     * reserved until height-matched buffer layout exists (currently behaves like the default).
+     */
+    dualPaneScrollSyncStrategy?: DualPaneScrollSyncStrategyId;
     /**
      * `full` (default): in-page search indexes every source line and every commentray line.
      * `commentray-and-paths`: search only **toolbar path labels** plus commentray Markdown (no code-body line corpus).
@@ -121,8 +135,8 @@ export type CodeBrowserPageOptions = {
      */
     commentrayOnGithubUrl?: string;
     /**
-     * When set (e.g. `./browse/…/index.html` or `./browse/<hash>.html` from the static Pages build),
-     * the Doc toolbar icon opens this URL on the **same origin** instead of GitHub.
+     * When set (e.g. `./browse/…/index.html`, `/browse/…/index.html`, or `./browse/<hash>.html` from
+     * the static Pages build), the Doc toolbar icon opens this URL on the **same origin** instead of GitHub.
      */
     commentrayStaticBrowseUrl?: string;
     /**
@@ -138,7 +152,8 @@ export type CodeBrowserPageOptions = {
     documentedPairsEmbeddedB64?: string;
     /**
      * When **two or more** angles are listed for the same static browse session, the shell renders
-     * an Angle selector, embeds each rendered Markdown body, and disables stretch layout.
+     * an Angle selector. If every angle can build a block-stretch table (`layout` `auto`), the shell
+     * uses **stretch** (one scroll + row-aligned table); otherwise **dual** panes with client swap.
      */
     multiAngleBrowsing?: CodeBrowserMultiAngleBrowsing;
     /**
@@ -154,4 +169,6 @@ export type CodeBrowserPageOptions = {
  * token-in-line quick search (all non-whitespace tokens must appear on the same line).
  */
 export declare function renderCodeBrowserHtml(opts: CodeBrowserPageOptions): Promise<string>;
+export type { DualPaneScrollSyncStrategyId } from "./code-browser-scroll-sync-strategy.js";
+export type { StretchBufferSyncStrategy } from "./block-stretch-layout.js";
 //# sourceMappingURL=code-browser.d.ts.map

package/dist/code-browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-browser.d.ts","sourceRoot":"","sources":["../src/code-browser.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,eAAe,EAIrB,MAAM,kBAAkB,CAAC;AAU1B,OAAO,EAAE,KAAK,0BAA0B,EAAwB,MAAM,wBAAwB,CAAC;AAQ/F,2EAA2E;AAC3E,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QACjB,KAAK,EAAE,eAAe,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,yBAAyB,EAAE,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,0BAA0B,CAAC;IAClD;;;OAGG;IACH,gBAAgB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC;IACf;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE;QACjB,KAAK,EAAE,eAAe,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAAC;IACpD,oHAAoH;IACpH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,6BAA6B,CAAC;IACnD;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAs7EF;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6EzF"}
+{"version":3,"file":"code-browser.d.ts","sourceRoot":"","sources":["../src/code-browser.ts"],"names":[],"mappings":"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"}