@capacms/sdk 1.0.0-next.1 → 1.0.0-next.3

package/README.md

@@ -199,6 +199,19 @@ so that moving a folder cannot silently split one page's telemetry in two. Set
 `page` on the config instead when a client serves exactly one page; a value on
 the call wins over one on the config.
 
+A layout is not a page. `app/layout.tsx` (and any nested `layout.*` or
+`template.*`) renders around every page below it, and Next does not tell it
+which one, so its reads cannot be charged to the page being rendered. `routeOf`
+returns `"(layout)"` for these files, exported as `LAYOUT_PAGE`, and a read that
+names it sends no `Capa-Page` header at all, even when the client was created
+with a `page`. So a Site singleton or a nav read in your root layout is simply
+not attributed, instead of making `/` look as if it read everything:
+
+```ts
+// In app/layout.tsx: same call as in a page, and no page is recorded.
+const site = await capa.entries.list("site", { page: routeOf(import.meta.url) });
+```
+
 A malformed value throws a `TypeError`. Capa itself ignores a header it cannot
 store, because a mangled page identity must never take a blog down, so the SDK
 is the place a typo surfaces.
@@ -419,6 +432,14 @@ every navigation, `select { entryId, field }` on a click, and `hover`.
 `acceptMessage(event, allowedOrigins, parent)` is the site's filter, exported
 for your own tests.
 
+Since 1.0.0-next.2 the site also sends `visible { entryId, field }` while the
+page scrolls (at most every 150ms, and only when it changes): the tagged element
+at the centre of the viewport, chosen by `pickCentred`. At the very top of a
+page, where a heading can never reach the centre, it is the topmost visible
+element instead, and at the very bottom the bottommost. The editor's "Follow the
+page" scrolls the form to that field. It is additive and still `v: 1`: an older
+overlay never sends it and the editor simply does not follow.
+
 ## Not yet
 
 `--select-from-depth`, `capa convert-url`, `capa persist`, GraphQL, and `/api/`

package/dist/next/client.d.ts

@@ -287,6 +287,20 @@ export declare class CapaError extends Error {
 }
 export declare function isCapaError(error: unknown): error is CapaError;
 export declare function resolveNextConfig(config: CapaNextConfig): ResolvedNextConfig;
+/**
+ * The page a layout (or template) reads for: none.
+ *
+ * A root layout renders around every page on the site, so charging its reads
+ * to `/`, the route its file sits at, made the home page look as if it read
+ * every Site singleton and nav on the site. `routeOf` returns this for a
+ * `layout.*` or `template.*` file, and a read that names it sends NO
+ * `Capa-Page` at all, even when the client was built with a `page`.
+ *
+ * Not sent as a value, because the API would drop it anyway: it is not a
+ * `PAGE_ID`, and the API ignores what it cannot store. Staying absent keeps a
+ * layout read byte-identical to one from a client that never named a page.
+ */
+export declare const LAYOUT_PAGE = "(layout)";
 type SelectInput = string | ReadonlyArray<unknown>;
 /** Serialize the SDK object form into the canonical `/api/entries` grammar. */
 export declare function serializeSelect(select: SelectInput): string;

package/dist/next/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CapaError = void 0;
+exports.LAYOUT_PAGE = exports.CapaError = void 0;
 exports.isCapaError = isCapaError;
 exports.resolveNextConfig = resolveNextConfig;
 exports.serializeSelect = serializeSelect;
@@ -85,6 +85,20 @@ function resolveNextConfig(config) {
  * quietly stops arriving rather than as an error.
  */
 const PAGE_ID = /^\/[A-Za-z0-9._\-[\]/]{0,199}$/;
+/**
+ * The page a layout (or template) reads for: none.
+ *
+ * A root layout renders around every page on the site, so charging its reads
+ * to `/`, the route its file sits at, made the home page look as if it read
+ * every Site singleton and nav on the site. `routeOf` returns this for a
+ * `layout.*` or `template.*` file, and a read that names it sends NO
+ * `Capa-Page` at all, even when the client was built with a `page`.
+ *
+ * Not sent as a value, because the API would drop it anyway: it is not a
+ * `PAGE_ID`, and the API ignores what it cannot store. Staying absent keeps a
+ * layout read byte-identical to one from a client that never named a page.
+ */
+exports.LAYOUT_PAGE = "(layout)";
 /**
  * The page for one call: the call's own value, else the client's, else none.
  *
@@ -97,6 +111,10 @@ function resolvePage(configPage, callPage) {
     const value = callPage !== undefined ? callPage : configPage;
     if (value === undefined || value === null)
         return undefined;
+    // A layout's read, named on purpose: no header, and the config's page does
+    // not stand in for it either.
+    if (value === exports.LAYOUT_PAGE)
+        return undefined;
     if (typeof value !== "string" || !PAGE_ID.test(value)) {
         throw new TypeError(`@capacms/sdk/next: page must be a path such as "/blog/[slug]" or "/blog/hello". Got ${JSON.stringify(value)}.`);
     }

package/dist/next/index.d.ts

@@ -1,4 +1,4 @@
-export { CapaError, createClient, isCapaError, resolveNextConfig, serializeSelect, } from "./client";
+export { CapaError, createClient, isCapaError, LAYOUT_PAGE, resolveNextConfig, serializeSelect, } from "./client";
 export { capaAttrs } from "./attrs";
 export type { CapaAttrs } from "./attrs";
 export type { CallOptions, CapaNextClient, CapaNextConfig, EntriesResource, Entry, Filter, FilterOperator, FilterScalar, FilterValue, GetOptions, ListOptions, Page, PageDetail, PageInfo, PageSummary, PagesListOptions, PagesResource, PreviewClaim, ResponseMeta, Single, } from "./client";

package/dist/next/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.capaAttrs = exports.serializeSelect = exports.resolveNextConfig = exports.isCapaError = exports.createClient = exports.CapaError = void 0;
+exports.capaAttrs = exports.serializeSelect = exports.resolveNextConfig = exports.LAYOUT_PAGE = exports.isCapaError = exports.createClient = exports.CapaError = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "CapaError", { enumerable: true, get: function () { return client_1.CapaError; } });
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
 Object.defineProperty(exports, "isCapaError", { enumerable: true, get: function () { return client_1.isCapaError; } });
+Object.defineProperty(exports, "LAYOUT_PAGE", { enumerable: true, get: function () { return client_1.LAYOUT_PAGE; } });
 Object.defineProperty(exports, "resolveNextConfig", { enumerable: true, get: function () { return client_1.resolveNextConfig; } });
 Object.defineProperty(exports, "serializeSelect", { enumerable: true, get: function () { return client_1.serializeSelect; } });
 var attrs_1 = require("./attrs");

package/dist/nextjs/index.d.ts

@@ -1,4 +1,4 @@
-import { type CapaNextClient, type CapaNextConfig, type PagesResource, type PreviewClaim } from "../next";
+import { LAYOUT_PAGE, type CapaNextClient, type CapaNextConfig, type PagesResource, type PreviewClaim } from "../next";
 export interface CacheOptions {
     tags?: string[];
     revalidate?: number | false;
@@ -50,4 +50,5 @@ export declare function preview(token: string, client: CapaNextClient): Promise<
  * this and never hold the whole client.
  */
 export declare function pagesFor(client: CapaNextClient): PagesResource;
+export { LAYOUT_PAGE };
 export type { PreviewClaim };

package/dist/nextjs/index.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LAYOUT_PAGE = void 0;
 exports.withCache = withCache;
 exports.tagsFor = tagsFor;
 exports.revalidateFromWebhook = revalidateFromWebhook;
@@ -8,6 +9,7 @@ exports.routeOf = routeOf;
 exports.preview = preview;
 exports.pagesFor = pagesFor;
 const next_1 = require("../next");
+Object.defineProperty(exports, "LAYOUT_PAGE", { enumerable: true, get: function () { return next_1.LAYOUT_PAGE; } });
 /** Add Next.js fetch-cache options without importing `next/*`. */
 function withCache(fetchImpl, options) {
     return (async (input, init = {}) => {
@@ -64,6 +66,16 @@ async function draftClient(input) {
  *   src/app/(marketing)/pricing/page.tsx     -> /pricing
  *   pages/blog/[slug].tsx                    -> /blog/[slug]
  *   app/page.tsx                             -> /
+ *   app/layout.tsx, app/blog/template.tsx    -> (layout)
+ *
+ * A LAYOUT IS NOT A PAGE. `layout.*` and `template.*` render around every page
+ * below them, and a layout is not told which one: Next hands it no pathname.
+ * So its reads cannot be charged to the page being rendered, and charging them
+ * to the route its own file sits at is wrong: a root layout's Site singleton
+ * and nav would all be recorded as reads of `/`. `routeOf` returns
+ * `LAYOUT_PAGE` (`"(layout)"`) for these files instead, and a read that names
+ * it sends no `Capa-Page` at all. Pass `routeOf(import.meta.url)` from a layout
+ * exactly as from a page and it does the right thing.
  *
  * WHAT IS DROPPED, and why each one:
  *
@@ -74,8 +86,7 @@ async function draftClient(input) {
  *   parallel slots `@modal`               the same
  *   the `(.)` intercept marker            an intercepting route at the SAME
  *                                         level renders the segment beside it
- *   `page.*`, `layout.*`, `route.*`,      leaf files, not segments
- *   `default.*`, `template.*`
+ *   `page.*`, `route.*`, `default.*`      leaf files, not segments
  *   `index` in the pages router           the folder IS the route
  *   the extension                         never in a URL
  *
@@ -87,7 +98,9 @@ async function draftClient(input) {
  * case the message says to pass the page string yourself.
  */
 const ROUTER_ROOTS = new Set(["app", "pages"]);
-const LEAF_FILES = new Set(["page", "layout", "route", "default", "template"]);
+const LEAF_FILES = new Set(["page", "route", "default"]);
+/** Files that render around many routes, so they name none. */
+const LAYOUT_FILES = new Set(["layout", "template"]);
 /** `(..)photo`, `(..)(..)photo`, `(...)photo`: the URL is not here. */
 const OUTER_INTERCEPT = /^(\(\.\.\.\)|(\(\.\.\))+)/;
 function routeOf(file) {
@@ -131,6 +144,9 @@ function routeOf(file) {
             const dot = part.lastIndexOf(".");
             if (dot > 0)
                 part = part.slice(0, dot);
+            // Only in the app router: `pages/layout.tsx` is a page at `/layout`.
+            if (parts[rootIndex] === "app" && LAYOUT_FILES.has(part))
+                return next_1.LAYOUT_PAGE;
             if (LEAF_FILES.has(part))
                 continue;
             // The pages router: `pages/blog/index.tsx` is `/blog`.

package/dist/overlay/index.d.ts

@@ -1,5 +1,5 @@
-export { acceptMessage, hoverMessage, normaliseOrigins, readyMessage, selectMessage, ADMIN_SOURCE, PROTOCOL_VERSION, SITE_SOURCE, } from "./protocol";
-export type { AdminMessage, MessageLike, SiteMessage } from "./protocol";
+export { acceptMessage, hoverMessage, normaliseOrigins, pickCentred, readyMessage, scrollEdge, selectMessage, visibleMessage, ADMIN_SOURCE, PROTOCOL_VERSION, SITE_SOURCE, } from "./protocol";
+export type { AdminMessage, MessageLike, SiteMessage, TaggedBox } from "./protocol";
 export interface OverlayOptions {
     /**
      * The Capa admin origins allowed to drive this page, for example

package/dist/overlay/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SITE_SOURCE = exports.PROTOCOL_VERSION = exports.ADMIN_SOURCE = exports.selectMessage = exports.readyMessage = exports.normaliseOrigins = exports.hoverMessage = exports.acceptMessage = void 0;
+exports.SITE_SOURCE = exports.PROTOCOL_VERSION = exports.ADMIN_SOURCE = exports.visibleMessage = exports.selectMessage = exports.scrollEdge = exports.readyMessage = exports.pickCentred = exports.normaliseOrigins = exports.hoverMessage = exports.acceptMessage = void 0;
 exports.startOverlay = startOverlay;
 /**
  * `@capacms/sdk/overlay`: the site half of Capa's live preview.
@@ -21,8 +21,11 @@ var protocol_2 = require("./protocol");
 Object.defineProperty(exports, "acceptMessage", { enumerable: true, get: function () { return protocol_2.acceptMessage; } });
 Object.defineProperty(exports, "hoverMessage", { enumerable: true, get: function () { return protocol_2.hoverMessage; } });
 Object.defineProperty(exports, "normaliseOrigins", { enumerable: true, get: function () { return protocol_2.normaliseOrigins; } });
+Object.defineProperty(exports, "pickCentred", { enumerable: true, get: function () { return protocol_2.pickCentred; } });
 Object.defineProperty(exports, "readyMessage", { enumerable: true, get: function () { return protocol_2.readyMessage; } });
+Object.defineProperty(exports, "scrollEdge", { enumerable: true, get: function () { return protocol_2.scrollEdge; } });
 Object.defineProperty(exports, "selectMessage", { enumerable: true, get: function () { return protocol_2.selectMessage; } });
+Object.defineProperty(exports, "visibleMessage", { enumerable: true, get: function () { return protocol_2.visibleMessage; } });
 Object.defineProperty(exports, "ADMIN_SOURCE", { enumerable: true, get: function () { return protocol_2.ADMIN_SOURCE; } });
 Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_2.PROTOCOL_VERSION; } });
 Object.defineProperty(exports, "SITE_SOURCE", { enumerable: true, get: function () { return protocol_2.SITE_SOURCE; } });
@@ -32,6 +35,8 @@ const TAGGED = "[data-capa-entry][data-capa-field]";
 const SCROLL_KEY = "capa-overlay:scrollY";
 /** How long a refresh keeps putting the scroll position back while the page re-renders. */
 const RESTORE_WINDOW_MS = 1500;
+/** `visible` is sent at most this often while the page scrolls. */
+const VISIBLE_THROTTLE_MS = 150;
 const noop = () => { };
 let running = null;
 /**
@@ -67,6 +72,8 @@ function createOverlay(initial) {
     let readyFrame = 0;
     let hoverFrame = 0;
     let lastPointer = null;
+    let visibleTimer = 0;
+    let lastVisible = "";
     const post = (message) => {
         if (!adminOrigin)
             return;
@@ -195,6 +202,41 @@ function createOverlay(initial) {
             return;
         readyFrame = window.requestAnimationFrame(() => sendReady(false));
     };
+    // ------------------------------------------------------------- visible ---
+    /**
+     * Which tagged element sits at the centre of the viewport, reported when it
+     * changes. The editor's "Follow the page" scrolls the form to match. Sent
+     * only to an admin that has said hello, and only on a change, so a still
+     * page sends nothing.
+     */
+    const reportVisible = () => {
+        visibleTimer = 0;
+        if (!adminOrigin)
+            return;
+        const boxes = tagged().map((el) => {
+            const rect = el.getBoundingClientRect();
+            return {
+                entryId: el.getAttribute("data-capa-entry") ?? "",
+                field: el.getAttribute("data-capa-field") ?? "",
+                top: rect.top,
+                bottom: rect.bottom,
+            };
+        });
+        const edge = (0, protocol_1.scrollEdge)(window.scrollY, window.innerHeight, document.documentElement.scrollHeight);
+        const pick = (0, protocol_1.pickCentred)(boxes, window.innerHeight, edge);
+        if (!pick)
+            return;
+        const key = `${pick.entryId}\n${pick.field}`;
+        if (key === lastVisible)
+            return;
+        lastVisible = key;
+        post((0, protocol_1.visibleMessage)(pick.entryId, pick.field));
+    };
+    const onScroll = () => {
+        render();
+        if (!visibleTimer)
+            visibleTimer = window.setTimeout(reportVisible, VISIBLE_THROTTLE_MS);
+    };
     // -------------------------------------------------------------- scroll ---
     const restoreScroll = () => {
         if (!pendingScroll)
@@ -247,6 +289,7 @@ function createOverlay(initial) {
         switch (message.type) {
             case "hello":
                 adminOrigin = event.origin;
+                lastVisible = "";
                 sendReady(true);
                 render();
                 return;
@@ -321,7 +364,7 @@ function createOverlay(initial) {
         restoreScroll();
     });
     window.addEventListener("message", onMessage);
-    window.addEventListener("scroll", render, { capture: true, passive: true });
+    window.addEventListener("scroll", onScroll, { capture: true, passive: true });
     window.addEventListener("resize", render, { passive: true });
     window.addEventListener("popstate", scheduleReady);
     document.addEventListener("click", onClick, true);
@@ -330,7 +373,7 @@ function createOverlay(initial) {
     observer.observe(document.body, { childList: true, subtree: true, characterData: true });
     const dispose = () => {
         window.removeEventListener("message", onMessage);
-        window.removeEventListener("scroll", render, { capture: true });
+        window.removeEventListener("scroll", onScroll, { capture: true });
         window.removeEventListener("resize", render);
         window.removeEventListener("popstate", scheduleReady);
         document.removeEventListener("click", onClick, true);
@@ -340,6 +383,8 @@ function createOverlay(initial) {
         for (const id of [frame, readyFrame, hoverFrame])
             if (id)
                 window.cancelAnimationFrame(id);
+        if (visibleTimer)
+            window.clearTimeout(visibleTimer);
         layer?.remove();
         layer = null;
         if (running?.dispose === dispose)

package/dist/overlay/protocol.d.ts

@@ -15,6 +15,13 @@
  *     ready     { path, entries }                    after hello, and after every navigation
  *     select    { entryId, field }                   a tagged element was clicked
  *     hover     { entryId, field } | { entryId: "", field: null }
+ *     visible   { entryId, field }                   the tagged element at the centre of the
+ *                                                    viewport changed (throttled, on scroll)
+ *
+ * `visible` arrived in 1.0.0-next.2 and is OPTIONAL: it is still `v: 1`,
+ * because an admin that does not know it drops an unknown type, and an older
+ * overlay simply never sends it. Additive messages keep the version; only a
+ * change to an existing shape would move it.
  *
  * The admin keeps its own copy of these shapes (`apps/admin`, no dependency on
  * this package). If you change one side, change the other.
@@ -60,6 +67,12 @@ export type SiteMessage = {
     type: "hover";
     entryId: string;
     field: string | null;
+} | {
+    source: typeof SITE_SOURCE;
+    v: 1;
+    type: "visible";
+    entryId: string;
+    field: string;
 };
 /** The parts of a `MessageEvent` the filter reads, so a test can hand in a literal. */
 export interface MessageLike {
@@ -89,3 +102,33 @@ export declare function acceptMessage(event: MessageLike, allowedOrigins: readon
 export declare function readyMessage(path: string, entries: string[]): SiteMessage;
 export declare function selectMessage(entryId: string, field: string): SiteMessage;
 export declare function hoverMessage(entryId: string, field: string | null): SiteMessage;
+export declare function visibleMessage(entryId: string, field: string): SiteMessage;
+/** The part of a tagged element `pickCentred` reads, so a test can hand in literals. */
+export interface TaggedBox {
+    entryId: string;
+    field: string;
+    /** `getBoundingClientRect()`, viewport coordinates. */
+    top: number;
+    bottom: number;
+}
+/**
+ * The tagged element a reader is looking at: the one that contains the
+ * viewport's horizontal centre line, and when several do (a field inside a
+ * card that is also tagged) the SMALLEST, because the innermost element is
+ * the specific one. When none crosses the line, the nearest one that is at
+ * least partly on screen. Null when nothing tagged is on screen at all.
+ *
+ * `edge` is where the page is scrolled to. A heading near the top of a page
+ * can never reach the centre line, because the page cannot scroll above its
+ * top; at the top the topmost visible element is the one being read, and at
+ * the bottom the bottommost. The same rule a table of contents' scroll spy
+ * uses.
+ *
+ * Pure, so the admin's "follow the page" can be tested without a DOM.
+ */
+export declare function pickCentred(boxes: readonly TaggedBox[], viewportHeight: number, edge?: "top" | "bottom" | null): TaggedBox | null;
+/**
+ * Which edge a scroll position is at, for `pickCentred`. A page that does not
+ * scroll at all is at neither: nothing moves, and the centre rule stands.
+ */
+export declare function scrollEdge(scrollY: number, viewportHeight: number, scrollHeight: number): "top" | "bottom" | null;

package/dist/overlay/protocol.js

@@ -16,6 +16,13 @@
  *     ready     { path, entries }                    after hello, and after every navigation
  *     select    { entryId, field }                   a tagged element was clicked
  *     hover     { entryId, field } | { entryId: "", field: null }
+ *     visible   { entryId, field }                   the tagged element at the centre of the
+ *                                                    viewport changed (throttled, on scroll)
+ *
+ * `visible` arrived in 1.0.0-next.2 and is OPTIONAL: it is still `v: 1`,
+ * because an admin that does not know it drops an unknown type, and an older
+ * overlay simply never sends it. Additive messages keep the version; only a
+ * change to an existing shape would move it.
  *
  * The admin keeps its own copy of these shapes (`apps/admin`, no dependency on
  * this package). If you change one side, change the other.
@@ -27,6 +34,9 @@ exports.acceptMessage = acceptMessage;
 exports.readyMessage = readyMessage;
 exports.selectMessage = selectMessage;
 exports.hoverMessage = hoverMessage;
+exports.visibleMessage = visibleMessage;
+exports.pickCentred = pickCentred;
+exports.scrollEdge = scrollEdge;
 exports.PROTOCOL_VERSION = 1;
 exports.ADMIN_SOURCE = "capa-admin";
 exports.SITE_SOURCE = "capa";
@@ -104,3 +114,71 @@ function hoverMessage(entryId, field) {
         ? { source: exports.SITE_SOURCE, v: 1, type: "hover", entryId: "", field: null }
         : { source: exports.SITE_SOURCE, v: 1, type: "hover", entryId, field };
 }
+function visibleMessage(entryId, field) {
+    return { source: exports.SITE_SOURCE, v: 1, type: "visible", entryId, field };
+}
+/** Above any element height, so a box that misses the centre line never outranks one that crosses it. */
+const MISS_FLOOR = 1e9;
+/**
+ * The tagged element a reader is looking at: the one that contains the
+ * viewport's horizontal centre line, and when several do (a field inside a
+ * card that is also tagged) the SMALLEST, because the innermost element is
+ * the specific one. When none crosses the line, the nearest one that is at
+ * least partly on screen. Null when nothing tagged is on screen at all.
+ *
+ * `edge` is where the page is scrolled to. A heading near the top of a page
+ * can never reach the centre line, because the page cannot scroll above its
+ * top; at the top the topmost visible element is the one being read, and at
+ * the bottom the bottommost. The same rule a table of contents' scroll spy
+ * uses.
+ *
+ * Pure, so the admin's "follow the page" can be tested without a DOM.
+ */
+function pickCentred(boxes, viewportHeight, edge = null) {
+    const centre = viewportHeight / 2;
+    let best = null;
+    let bestScore = Infinity;
+    for (const b of boxes) {
+        if (!b.entryId || !b.field)
+            continue;
+        if (b.bottom <= 0 || b.top >= viewportHeight || b.bottom <= b.top)
+            continue;
+        const height = b.bottom - b.top;
+        let score;
+        if (edge === "top") {
+            // Topmost first; of two that start together, the smaller (inner) one.
+            score = b.top * MISS_FLOOR + height;
+        }
+        else if (edge === "bottom") {
+            score = (viewportHeight - b.bottom) * MISS_FLOOR + height;
+        }
+        else {
+            // Crossing the line scores by height (smaller wins) and always beats a
+            // box that misses it, which scores by its distance from the line on top
+            // of a floor no height can reach.
+            score =
+                b.top <= centre && b.bottom >= centre
+                    ? height
+                    : MISS_FLOOR + Math.min(Math.abs(b.top - centre), Math.abs(b.bottom - centre));
+        }
+        if (score < bestScore) {
+            best = b;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/**
+ * Which edge a scroll position is at, for `pickCentred`. A page that does not
+ * scroll at all is at neither: nothing moves, and the centre rule stands.
+ */
+function scrollEdge(scrollY, viewportHeight, scrollHeight) {
+    const max = scrollHeight - viewportHeight;
+    if (max <= 1)
+        return null;
+    if (scrollY <= 1)
+        return "top";
+    if (scrollY >= max - 1)
+        return "bottom";
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capacms/sdk",
-  "version": "1.0.0-next.1",
+  "version": "1.0.0-next.3",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",