@capacms/sdk 1.0.0-next.2 → 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.

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/package.json

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