@pipelex/sdk 0.63.0 → 0.65.0

package/README.md

@@ -178,6 +178,31 @@ const copy = await client.copyMethod(
 );
 if (copy.outcome === "copied") console.log(copy.method.copied_from); // the original it names
 
+// Store a layout a producer designed for one pipe of a published version, over that version's
+// tree; a write of the same tree, pipe, catalog and prompt hash replaces it. A validate by
+// method_id naming `layouts` then carries the layouts beside the descriptor, newest first, and
+// leaves `layouts` out when there are none: render the plain form then.
+const v1 = await client.getMethodVersion(created.method_id, 1);
+const layoutKey = crypto.randomUUID(); // one key per layout, sent again unchanged on each retry
+await client.storeMethodLayout(created.method_id, 1, {
+  tree_digest: v1.tree_digest!,
+  pipe_ref: "greeting.greet",
+  catalog: "composer",
+  prompt_hash: "a1b2c3d4e5f6",
+  jsonl: '{"op":"add","path":"/root","value":"page"}',
+  provenance: { producer: "pipelex-method", model: "claude-4.8-opus", style: "editorial" },
+}, { idempotencyKey: layoutKey });
+const laidOut = await client.validate({ method_id: `${created.method_id}@1` }, false, {
+  views: ["input_form", "layouts"],
+});
+if (laidOut.is_valid) console.log(laidOut.layouts?.map((layout) => layout.catalog) ?? "plain form");
+
+// A host opening the page reads the same layouts with no dry run, and a builder can switch a
+// page's design off, per catalog, without losing it; the list is written whole.
+const { items: laidOutPages } = await client.listMethodLayouts(created.method_id, 1);
+console.log(laidOutPages.length);
+await client.setMethodLayoutsOff(created.method_id, ["composer"]);
+
 // The template catalog: the public methods every organization reads, in the platform's order, with
 // the categories that have a template and each card's thumbnails behind short-lived links. A
 // category's `labels` name it by language tag and may lack a language, in which case a client
@@ -302,6 +327,7 @@ These pages ship inside the published package, so a reader who has only installe
 | [`docs/files.md`](./docs/files.md) | An organization's files: `listFiles` and `iterateFiles`, the row, the whole record and its provenance, the query and its repeated filters, paging through filtered pages, one file and its uses, the records of an address, the rename rule, links that name the file, a zip of files and its caps, a run's files, the copy into a method's draft, and an upload recorded as a method's test file with the refusals that come with it |
 | [`docs/method-examples.md`](./docs/method-examples.md) | A method's saved examples: the create, the paged list and its iterator, the edit that raises the input revision, the latest-run write and its `recorded` or `stale` verdict, the build assistant's save and its `kept` or `created` verdict, how an integer past `Number.MAX_SAFE_INTEGER` in the inputs stays exact, and what is refused before sending |
 | [`docs/method-copy.md`](./docs/method-copy.md) | Copying a method into another organization or duplicating it: what a copy holds and the stored files it copies, the `copied` or `refused` verdict, every refusal, the copy's idempotency key, and `copied_from` |
+| [`docs/method-layouts.md`](./docs/method-layouts.md) | A method's stored layouts: `storeMethodLayout`, which stores a layout designed for one pipe of a published version, its closed body and its refusals, the layout, its provenance and its written sample, `listMethodLayouts`, which reads a version's layouts with no dry run, `setMethodLayoutsOff`, which switches a page's design off, and the `layouts` a validate by `method_id` carries when `views` names `layouts`, absent when there are none |
 | [`docs/public-methods.md`](./docs/public-methods.md) | Public methods and the template catalog: `listMethodTemplates` and its iterator, the ordering, the categories with their labels by language and `listMethodCategories`, the thumbnails' links, another organization's public method read in its narrower shape, the copy of a public method, `visibility` and `categories` on a method, and the refusals a public method's publish adds |
 | [`docs/organization-branding.md`](./docs/organization-branding.md) | An organization's logos, colours, app style and typeface, and its white-label entitlement: `getBranding`, which every member and API key reads, `updateOrganizationBranding`, a write by the `admin` or the `member` role that sets, clears or keeps each key, and how a refused logo, colour, style or typeface names its field so a settings screen shows the sentence under it |
 | [`docs/exact-integers.md`](./docs/exact-integers.md) | Which reads keep an integer past `Number.MAX_SAFE_INTEGER` exact, as a `bigint` (a run's inputs and outputs, an example's inputs), how a request body writes it back with its digits, and `parseExactJson` and `stringifyExactJson` for code showing such data as JSON text |

package/dist/cli/script.d.ts

@@ -15,7 +15,7 @@ import type { CommandIO } from "./io.js";
  * update notice and npm 12's run notices off the script's stderr, which carries the command's
  * own lines, while npm's warnings and errors still print.
  */
-export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.63.0";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.65.0";
 export declare const SCRIPT_WRITER = "@pipelex/sdk";
 export declare const SCRIPT_NEEDS = "Node 22.12 or later";
 /** Run `pipelex-sdk script` and return its exit code. */

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, StartOptions, VersionInfo } from "mthds/protocol";
-import type { CodegenRequest, CodegenResponse, CrateRouteOptions, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidateSource, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
+import type { CodegenRequest, CodegenResponse, CrateRouteOptions, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidateSource, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector, ValidateView } from "./models.js";
+import type { MethodLayout, MethodLayoutInput, MethodLayoutList } from "./method-layouts.js";
 import { type GetRunResultOptions, type RunProgress, type RunRead, type RunResults, type RunResultState, type StartAndWaitForResultOptions, type WaitForResultOptions } from "./runs.js";
 import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, DraftFileFromFileInput, DraftFileFromFileResult, FileArchive, FileArchiveRequest, FileDetail, FileLinkTarget, FileLinksResult, FilePage, FileRecord, FileRecordList, FileRenameInput, FileSummary, GetFileQuery, GetFilesByUriOptions, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodTemplatesQuery, ListMethodVersionsQuery, ListRunFilesQuery, MethodCategoryList, MethodCopyInput, MethodCopyResult, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleAssistantSaveInput, MethodExampleAssistantSaveResult, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodTemplate, MethodTemplatePage, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PublicMethodDetail, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunFilesPage, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
 import type { MethodTreeForms, MethodTreeLimits } from "./method-trees.js";
@@ -173,6 +174,55 @@ export interface MethodCopyRequestOptions {
      */
     idempotencyKey?: string | null;
 }
+/** Options for `listMethodLayouts`. */
+export interface MethodLayoutListOptions {
+    /**
+     * Caller-driven cancellation, such as an `AbortSignal.timeout(…)` for a page that can do without
+     * the layouts; the abort reason propagates untouched.
+     */
+    signal?: AbortSignal;
+}
+/** Options for `setMethodLayoutsOff`. */
+export interface MethodLayoutsOffOptions {
+    /**
+     * The write's idempotency key, sent as the `Idempotency-Key` header of
+     * `PUT /v1/methods/{id}/layouts-off`, and not sent at all when absent or `null`. Generate one per
+     * switch the caller means to make (a `crypto.randomUUID()` is a good key), and keep it, with the
+     * arguments unchanged, across that write's retries.
+     *
+     * The write is the whole list, so a write sent again without a key writes that list again, and
+     * undoes a switch that landed in between. Under the same key the hosted API answers the retry
+     * with the first write's stored answer and runs nothing. The rest of the rule, a key's form and
+     * its `409`s included, is `MethodLayoutWriteOptions.idempotencyKey`'s.
+     */
+    idempotencyKey?: string | null;
+}
+/** Options for `storeMethodLayout`. */
+export interface MethodLayoutWriteOptions {
+    /**
+     * The write's idempotency key, sent as the `Idempotency-Key` header of
+     * `POST /v1/methods/{id}/versions/{n}/layouts`, and not sent at all when absent or `null`.
+     * Generate one per layout the caller means to store (a `crypto.randomUUID()` is a good key), and
+     * keep it, with the arguments unchanged, across that write's retries.
+     *
+     * A write sent again without a key runs again: it stamps the layout with a new `stored_at`, which
+     * moves it ahead of every layout stored since in the newest-first order, and applies the bound
+     * again, so a layout another producer stored meanwhile, a newer prompt of the same pipe and
+     * catalog included, can be the one removed. Under the same key the hosted API answers the retry
+     * with the first write's stored answer and runs nothing, so a write whose answer was lost, as on
+     * a client timeout, can be sent again unchanged. The write's `200` and its `4xx` refusals are
+     * stored alike; a `5xx` and a refusal for its timing (a `408`, `425` or `429`) are not, so the
+     * same key sends the write afresh. The same key with a different body is refused (`409`
+     * `request.idempotency_conflict`, whose `retry` is `no`), as is a key whose earlier request is
+     * still being handled (`409` `request.idempotency_key_in_use`, whose `retry` is `yes`); these
+     * two are the key's own answers and are never stored, so a retry after the second runs as the
+     * key's first request would.
+     *
+     * A key is held to the rule a start's is (`PipelexStartRequestOptions.idempotencyKey`): 1 to
+     * 255 visible ASCII characters, anything else a `RequestArgumentError` before any request.
+     */
+    idempotencyKey?: string | null;
+}
 /**
  * `start()` / `startAndWaitForResult()` options — the same, for the durable path, plus the start
  * request's own `idempotencyKey`.
@@ -191,8 +241,13 @@ export interface ValidateOptions {
      * `"markdown"`, so both arms carry `rendered_markdown`.
      */
     render?: string[];
-    /** Structured-view opt-in tokens, e.g. `["input_form", "output_form"]`; sent only when given. */
-    views?: string[];
+    /**
+     * Structured-view opt-in tokens, e.g. `["input_form", "output_form"]`, or
+     * `["input_form", "layouts"]` for a stored method's descriptor and the layouts over it; sent
+     * verbatim, and only when given. A token this SDK does not know (`ValidateView`) is sent as its
+     * raw string.
+     */
+    views?: (ValidateView | (string & {}))[];
     /**
      * Per-call request ceiling; defaults to the 20-min execute ceiling. A positive number
      * no larger than 2147483647, the longest delay a timer honours, else a `RangeError`.
@@ -284,8 +339,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `url` is a fully resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose errors then say whether it may have (see `RunCreation`).
      * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
-     * `Idempotency-Key` header; only `start`, `copyMethod`, `rotateWebhookSecret` and
-     * `replayRunWebhookDelivery` pass one.
+     * `Idempotency-Key` header; only `start`, `copyMethod`, `storeMethodLayout`,
+     * `setMethodLayoutsOff`, `rotateWebhookSecret` and `replayRunWebhookDelivery` pass one.
      */
     private requestRaw;
     /**
@@ -315,7 +370,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     private requestProductObject;
     /**
      * A methods-catalog route answering one stored method (`createMethod`, `writeDraft`,
-     * `renameMethod`), read as `readObjectAnswer` reads it.
+     * `renameMethod`, `setMethodLayoutsOff`), read as `readObjectAnswer` reads it.
      */
     private requestMethodData;
     /**
@@ -565,7 +620,10 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `options.views` is the sibling opt-in for *structured* views where `render`
      * carries *rendered text*. The two lists are independent, each resolving its own
      * tokens against its own supported set, and each supported token adds a same-named
-     * top-level field to the valid arm — `input_form` and `output_form`. Unlike
+     * top-level field to the valid arm — `input_form` and `output_form`, and on a hosted
+     * validate by `method_id`, `layouts`, the layouts stored for the resolved tree
+     * (`PipelexValidationReport.layouts`, absent when there are none), each entry read as
+     * `storeMethodLayout`'s answer is and one that does not read as a layout left out. Unlike
      * `render`, this client sends `views` ONLY when the caller asks: the point of an
      * opt-in view is that the default response stays byte-identical, and the
      * highest-frequency consumers (hook pipelines, CI gates, agent loops) never pay for
@@ -1372,6 +1430,103 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * one, which names no tree to serve.
      */
     getMethodVersion(methodId: string, version: number): Promise<MethodVersion>;
+    /**
+     * Store a layout designed for one pipe of a published version of a method —
+     * `POST /v1/methods/{id}/versions/{n}/layouts` — and answer it as stored, with the `stored_at` the
+     * platform stamped.
+     *
+     * A layout is a data file a producer designed over the version's input-form descriptor, in the
+     * vocabulary of a catalog of components. The platform stores it beside the method, keyed by the
+     * content it was designed for, and hands it back through `listMethodLayouts` and on every validate
+     * of the method by `method_id` that names `layouts` among its `views` and resolves the same tree
+     * (`PipelexValidationReport.layouts`). It never produces, parses or judges one.
+     *
+     * `layout.tree_digest` must be the digest of the tree `version` holds, its
+     * `MethodVersionSummary.tree_digest`: a producer designs over the descriptor of the version it was
+     * handed. **A write of the same identity replaces the layout**, the identity being `tree_digest`,
+     * `pipe_ref`, `catalog` and `prompt_hash`, and is answered the same `200` whether it stored a new
+     * layout or replaced one. `options.idempotencyKey` is sent as the `Idempotency-Key` header, so a
+     * write whose answer was lost is sent again under the same key and answered as the first was; sent
+     * again without one, it runs again, with a new `stored_at` and the bound applied again
+     * (`MethodLayoutWriteOptions`). A content keeps at most 16
+     * layouts, every pipe, catalog and prompt hash together; past the bound a write removes first what
+     * newer prompts of the same pipe and catalog superseded (see `docs/method-layouts.md`).
+     * `layout.sample_json` keeps a written sample with the layout, never a run's output.
+     *
+     * The write changes the method, so it takes an `admin` or a `member` of the method's
+     * organization. Takes a bare catalog id, as `getMethod` does, and the version number. Sends the
+     * members of `MethodLayoutInput` and nothing else, the route's body being closed at both levels,
+     * and leaves out `sample_json` and each optional provenance member that is `null` or omitted, for
+     * the platform's default. Throws `RequestArgumentError` before any request for a `version` that is not a positive
+     * integer and for a `layout` or a `provenance` that is not an object; every other member is sent
+     * as given. Throws `ApiResponseError` when the platform refuses the write, which stores nothing:
+     * `422` `request.invalid` for a member breaking its shape or bound, naming it in `params.field`
+     * and `location.field` (`provenance.<member>` for one of the provenance's), and, naming
+     * `tree_digest`, for a digest that is not the tree the version holds; `403` `auth.forbidden`
+     * naming the `member` requirement for a `runner` or a caller with no recognised role; `404`
+     * `pipelex.catalog.not_found` for an unknown method or another organization's, its
+     * `params.resource` `method`, and for a version the method never published, its
+     * `params.resource` `version`; `409` `pipelex.catalog.being_deleted` while the method's erasure is
+     * pending, under way or stopped; and `500` `runtime.unexpected` for a version stored before
+     * methods were trees, which names no tree. Under an idempotency key, `409`
+     * `request.idempotency_conflict` for the key sent with a different body and `409`
+     * `request.idempotency_key_in_use` while its earlier request is still being handled; a key that is
+     * not 1 to 255 visible ASCII characters is a `RequestArgumentError` before any request. An answer
+     * that does not read as a layout (`methodLayoutFault`) is an answer the SDK cannot read, thrown as
+     * an `ApiResponseError` too.
+     */
+    storeMethodLayout(methodId: string, version: number, layout: MethodLayoutInput, options?: MethodLayoutWriteOptions): Promise<MethodLayout>;
+    /**
+     * The layouts stored for the content of a published version of a method —
+     * `GET /v1/methods/{id}/versions/{n}/layouts` — newest first, at most 16, `items` empty when none
+     * is stored. It touches only the platform's database and calls no runner, so it costs a host far
+     * less than the `layouts` view of `validate`, which dry-runs every pipe of the method.
+     *
+     * It answers what is stored whatever `layouts_off` says: the switch is the host's to honour.
+     * Another organization's public method reads too, with the layouts its builders stored, and a
+     * `runner` reads what it is shown. Takes a bare catalog id, as `getMethod` does, and the version
+     * number. `options.signal` cancels the read. Throws `RequestArgumentError` for a `version` that is
+     * not a positive integer, before any request.
+     *
+     * Throws `ApiResponseError`: `404` `pipelex.catalog.not_found` for an unknown method or another
+     * organization's internal one, its `params.resource` `method`, and for a version the method never
+     * published, its `params.resource` `version`; `409` `pipelex.catalog.being_deleted` while the
+     * erasure of the caller's own method is pending, under way or stopped; `500` `runtime.unexpected`
+     * for a version stored before methods were trees, which names no tree. An answer whose `items` is
+     * not an array is an answer the SDK cannot read, thrown as an `ApiResponseError` too; an entry
+     * that does not read as a layout is left out (`readMethodLayouts`), so one layout it cannot read
+     * never costs the caller the others.
+     */
+    listMethodLayouts(methodId: string, version: number, options?: MethodLayoutListOptions): Promise<MethodLayoutList>;
+    /**
+     * Set which catalogs of a method have their layouts switched off —
+     * `PUT /v1/methods/{id}/layouts-off` — and return the method, its `layouts_off` the list as held.
+     *
+     * `catalogs` is the whole list and replaces the one held, each catalog id once, at most 8, empty
+     * when every design is on: to change one, read `layouts_off` and write the new list. The switch
+     * acts at once, with no publish, and holds across every publish. A layout switched off is kept,
+     * and `listMethodLayouts` still answers it; a host draws the plain page instead. Like a rename, it
+     * never moves the draft token, so the `updated_at` a caller holds stays valid.
+     *
+     * The last write to land is the one held. `options.idempotencyKey` is sent as the
+     * `Idempotency-Key` header, so a write whose answer was lost is sent again under the same key and
+     * answered as the first was (`MethodLayoutsOffOptions`).
+     *
+     * The write changes the method, so it takes an `admin` or a `member` of the method's
+     * organization. Takes a bare catalog id, as `getMethod` does. Throws `RequestArgumentError` before
+     * any request for `catalogs` that is not an array; its entries are sent as given. Throws
+     * `ApiResponseError`: `404` `pipelex.catalog.not_found` for an unknown method or another
+     * organization's, a public one included; `403` `auth.forbidden` naming the `member` requirement
+     * for a `runner` or a caller with no recognised role; `409` `pipelex.catalog.being_deleted` while
+     * the method's erasure is pending, under way or stopped; `413` `request.too_large` for a list that
+     * would leave the method too large to publish, which a list that does not grow never is; and
+     * `422` `request.invalid` for more than 8 catalogs, a catalog named twice or one that is not a
+     * slug. Under an idempotency key, `409` `request.idempotency_conflict` for the key sent with a
+     * different list and `409` `request.idempotency_key_in_use` while its earlier request is still
+     * being handled; a key that is not 1 to 255 visible ASCII characters is a `RequestArgumentError`
+     * before any request.
+     */
+    setMethodLayoutsOff(methodId: string, catalogs: readonly string[], options?: MethodLayoutsOffOptions): Promise<MethodData>;
     /**
      * Copy a method into an organization the caller may change methods in —
      * `POST /v1/methods/{id}/copy`: the method's own organization for a duplicate, another team, or

package/dist/client.js

@@ -2,6 +2,7 @@
 // source combinations are legal is an invariant of `RunRequest` itself, so this
 // client and the MTHDS runners cannot disagree about what they reject.
 import { assertOneMethodSource, buildProblem, isProblem, parseJsonBody, readProblemBody, } from "mthds/protocol";
+import { LAYOUT_INPUT_MEMBERS, PROVENANCE_INPUT_MEMBERS, methodLayoutFault, readMethodLayout, readMethodLayouts, } from "./method-layouts.js";
 import { assertArtifactSelection, assertWaitOptions, pollUntilResult, readRunDegradation, RUN_STATUSES, runProgressFault, runStatusFilter, selectionIncludesMainStuff, throwIfAborted, withCheckedProgressHealth, } from "./runs.js";
 import { ABORT_TIMEOUT, ApiResponseError, argumentInvalidProblem, ApiUnreachableError, MissingMainStuffError, PagingNotTerminatingError, PipelineExecuteTimeoutError, ProblemError, RequestArgumentError, RunLifecycleUnavailableError, RunStillRunningError, } from "./errors.js";
 import { isPlainObject } from "./records.js";
@@ -326,6 +327,27 @@ const COPY_DRAFT_TOKEN_ARGUMENT = {
     what: "an expected_draft_updated_at, the draft token the caller last read, the method's " +
         "`updated_at`, a string, or none",
 };
+/** What each argument of a layout write is, as a refusal of it names it. */
+const LAYOUT_VERSION_ARGUMENT = {
+    name: "version",
+    what: "a version number, the published version the layout was designed for, a positive integer",
+};
+const LAYOUT_LIST_VERSION_ARGUMENT = {
+    name: "version",
+    what: "a version number, the published version whose layouts to read, a positive integer",
+};
+const LAYOUTS_OFF_CATALOGS_ARGUMENT = {
+    name: "catalogs",
+    what: "the ids of the catalogs to switch off as an array, the whole list, empty for none",
+};
+const LAYOUT_ARGUMENT = {
+    name: "layout",
+    what: "the layout to store as an object, a MethodLayoutInput",
+};
+const LAYOUT_PROVENANCE_ARGUMENT = {
+    name: "provenance",
+    what: "the layout's provenance as an object naming at least its producer and its model",
+};
 /**
  * The refusal of an argument a call cannot take, worded as every such refusal is:
  * `<call>() takes <what>; got <got>.`, with what made it unusable as `cause` when there is one.
@@ -374,12 +396,16 @@ function requireNameAndInputs(name, inputs, call, needs) {
 }
 /**
  * A caller's value as the refusal of a number argument names it: a number by its value, anything
- * else by its type, as `requireNonEmptyId` names a value, and `null` as itself. Never by `String`,
- * which throws for an object with no prototype and would replace the refusal with a `TypeError`.
+ * else by its type, as `requireNonEmptyId` names a value, `null` as itself and an array as one, so
+ * a refusal of a value that is not an object never answers an array with "got object". Never by
+ * `String`, which throws for an object with no prototype and would replace the refusal with a
+ * `TypeError`.
  */
 function describeNumberArgument(value) {
     if (typeof value === "number")
         return String(value);
+    if (Array.isArray(value))
+        return "an array";
     return value === null ? "null" : typeof value;
 }
 /**
@@ -582,8 +608,8 @@ export class PipelexApiClient {
      * `url` is a fully resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose errors then say whether it may have (see `RunCreation`).
      * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
-     * `Idempotency-Key` header; only `start`, `copyMethod`, `rotateWebhookSecret` and
-     * `replayRunWebhookDelivery` pass one.
+     * `Idempotency-Key` header; only `start`, `copyMethod`, `storeMethodLayout`,
+     * `setMethodLayoutsOff`, `rotateWebhookSecret` and `replayRunWebhookDelivery` pass one.
      */
     async requestRaw(method, url, options = {}) {
         const hasBody = options.body !== undefined;
@@ -700,7 +726,7 @@ export class PipelexApiClient {
     }
     /**
      * A methods-catalog route answering one stored method (`createMethod`, `writeDraft`,
-     * `renameMethod`), read as `readObjectAnswer` reads it.
+     * `renameMethod`, `setMethodLayoutsOff`), read as `readObjectAnswer` reads it.
      */
     async requestMethodData(method, endpoint, body, options = {}) {
         const res = await this.requestProductAnswer(method, endpoint, body, options);
@@ -1181,7 +1207,10 @@ export class PipelexApiClient {
      * `options.views` is the sibling opt-in for *structured* views where `render`
      * carries *rendered text*. The two lists are independent, each resolving its own
      * tokens against its own supported set, and each supported token adds a same-named
-     * top-level field to the valid arm — `input_form` and `output_form`. Unlike
+     * top-level field to the valid arm — `input_form` and `output_form`, and on a hosted
+     * validate by `method_id`, `layouts`, the layouts stored for the resolved tree
+     * (`PipelexValidationReport.layouts`, absent when there are none), each entry read as
+     * `storeMethodLayout`'s answer is and one that does not read as a layout left out. Unlike
      * `render`, this client sends `views` ONLY when the caller asks: the point of an
      * opt-in view is that the default response stays byte-identical, and the
      * highest-frequency consumers (hook pipelines, CI gates, agent loops) never pay for
@@ -1239,7 +1268,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("POST", "validate", res);
         }
-        return withVerdictItems(this.readObjectAnswer("POST", "validate", res));
+        return withReadLayouts(withVerdictItems(this.readObjectAnswer("POST", "validate", res)));
     }
     // ── Tools extensions (Pipelex API — `/v1/lint`, `/v1/format`) ─────────
     //
@@ -2635,6 +2664,140 @@ export class PipelexApiClient {
         const res = await this.requestProductAnswer("GET", endpoint, undefined);
         return this.readSavedTree("GET", endpoint, withLinks(res), "a published version");
     }
+    /**
+     * Store a layout designed for one pipe of a published version of a method —
+     * `POST /v1/methods/{id}/versions/{n}/layouts` — and answer it as stored, with the `stored_at` the
+     * platform stamped.
+     *
+     * A layout is a data file a producer designed over the version's input-form descriptor, in the
+     * vocabulary of a catalog of components. The platform stores it beside the method, keyed by the
+     * content it was designed for, and hands it back through `listMethodLayouts` and on every validate
+     * of the method by `method_id` that names `layouts` among its `views` and resolves the same tree
+     * (`PipelexValidationReport.layouts`). It never produces, parses or judges one.
+     *
+     * `layout.tree_digest` must be the digest of the tree `version` holds, its
+     * `MethodVersionSummary.tree_digest`: a producer designs over the descriptor of the version it was
+     * handed. **A write of the same identity replaces the layout**, the identity being `tree_digest`,
+     * `pipe_ref`, `catalog` and `prompt_hash`, and is answered the same `200` whether it stored a new
+     * layout or replaced one. `options.idempotencyKey` is sent as the `Idempotency-Key` header, so a
+     * write whose answer was lost is sent again under the same key and answered as the first was; sent
+     * again without one, it runs again, with a new `stored_at` and the bound applied again
+     * (`MethodLayoutWriteOptions`). A content keeps at most 16
+     * layouts, every pipe, catalog and prompt hash together; past the bound a write removes first what
+     * newer prompts of the same pipe and catalog superseded (see `docs/method-layouts.md`).
+     * `layout.sample_json` keeps a written sample with the layout, never a run's output.
+     *
+     * The write changes the method, so it takes an `admin` or a `member` of the method's
+     * organization. Takes a bare catalog id, as `getMethod` does, and the version number. Sends the
+     * members of `MethodLayoutInput` and nothing else, the route's body being closed at both levels,
+     * and leaves out `sample_json` and each optional provenance member that is `null` or omitted, for
+     * the platform's default. Throws `RequestArgumentError` before any request for a `version` that is not a positive
+     * integer and for a `layout` or a `provenance` that is not an object; every other member is sent
+     * as given. Throws `ApiResponseError` when the platform refuses the write, which stores nothing:
+     * `422` `request.invalid` for a member breaking its shape or bound, naming it in `params.field`
+     * and `location.field` (`provenance.<member>` for one of the provenance's), and, naming
+     * `tree_digest`, for a digest that is not the tree the version holds; `403` `auth.forbidden`
+     * naming the `member` requirement for a `runner` or a caller with no recognised role; `404`
+     * `pipelex.catalog.not_found` for an unknown method or another organization's, its
+     * `params.resource` `method`, and for a version the method never published, its
+     * `params.resource` `version`; `409` `pipelex.catalog.being_deleted` while the method's erasure is
+     * pending, under way or stopped; and `500` `runtime.unexpected` for a version stored before
+     * methods were trees, which names no tree. Under an idempotency key, `409`
+     * `request.idempotency_conflict` for the key sent with a different body and `409`
+     * `request.idempotency_key_in_use` while its earlier request is still being handled; a key that is
+     * not 1 to 255 visible ASCII characters is a `RequestArgumentError` before any request. An answer
+     * that does not read as a layout (`methodLayoutFault`) is an answer the SDK cannot read, thrown as
+     * an `ApiResponseError` too.
+     */
+    async storeMethodLayout(methodId, version, layout, options = {}) {
+        const call = "storeMethodLayout";
+        if (!Number.isSafeInteger(version) || version < 1) {
+            throw argumentRefusal(call, LAYOUT_VERSION_ARGUMENT, describeNumberArgument(version), "not_a_positive_integer");
+        }
+        const endpoint = `${methodPath(methodId, call)}/versions/${version}/layouts`;
+        const body = methodLayoutBody(layout, call);
+        const idempotencyKey = idempotencyKeyOf(options, "store the layout");
+        const res = await this.requestProductAnswer("POST", endpoint, body, { idempotencyKey });
+        const answer = this.readObjectAnswer("POST", endpoint, res);
+        const stored = readMethodLayout(answer);
+        if (stored === null) {
+            throw this.unreadableAnswer("POST", `/${API_PREFIX}/${endpoint}`, res, `a layout ${methodLayoutFault(answer) ?? "that is not one"}`);
+        }
+        return stored;
+    }
+    /**
+     * The layouts stored for the content of a published version of a method —
+     * `GET /v1/methods/{id}/versions/{n}/layouts` — newest first, at most 16, `items` empty when none
+     * is stored. It touches only the platform's database and calls no runner, so it costs a host far
+     * less than the `layouts` view of `validate`, which dry-runs every pipe of the method.
+     *
+     * It answers what is stored whatever `layouts_off` says: the switch is the host's to honour.
+     * Another organization's public method reads too, with the layouts its builders stored, and a
+     * `runner` reads what it is shown. Takes a bare catalog id, as `getMethod` does, and the version
+     * number. `options.signal` cancels the read. Throws `RequestArgumentError` for a `version` that is
+     * not a positive integer, before any request.
+     *
+     * Throws `ApiResponseError`: `404` `pipelex.catalog.not_found` for an unknown method or another
+     * organization's internal one, its `params.resource` `method`, and for a version the method never
+     * published, its `params.resource` `version`; `409` `pipelex.catalog.being_deleted` while the
+     * erasure of the caller's own method is pending, under way or stopped; `500` `runtime.unexpected`
+     * for a version stored before methods were trees, which names no tree. An answer whose `items` is
+     * not an array is an answer the SDK cannot read, thrown as an `ApiResponseError` too; an entry
+     * that does not read as a layout is left out (`readMethodLayouts`), so one layout it cannot read
+     * never costs the caller the others.
+     */
+    async listMethodLayouts(methodId, version, options = {}) {
+        const call = "listMethodLayouts";
+        if (!Number.isSafeInteger(version) || version < 1) {
+            throw argumentRefusal(call, LAYOUT_LIST_VERSION_ARGUMENT, describeNumberArgument(version), "not_a_positive_integer");
+        }
+        const endpoint = `${methodPath(methodId, call)}/versions/${version}/layouts`;
+        const res = await this.requestProductAnswer("GET", endpoint, undefined, {
+            signal: options.signal,
+        });
+        const answer = this.readObjectAnswer("GET", endpoint, res);
+        if (!Array.isArray(answer.items)) {
+            throw this.unreadableAnswer("GET", `/${API_PREFIX}/${endpoint}`, res, "a list of layouts whose `items` is not an array");
+        }
+        return { ...answer, items: readMethodLayouts(answer.items) };
+    }
+    /**
+     * Set which catalogs of a method have their layouts switched off —
+     * `PUT /v1/methods/{id}/layouts-off` — and return the method, its `layouts_off` the list as held.
+     *
+     * `catalogs` is the whole list and replaces the one held, each catalog id once, at most 8, empty
+     * when every design is on: to change one, read `layouts_off` and write the new list. The switch
+     * acts at once, with no publish, and holds across every publish. A layout switched off is kept,
+     * and `listMethodLayouts` still answers it; a host draws the plain page instead. Like a rename, it
+     * never moves the draft token, so the `updated_at` a caller holds stays valid.
+     *
+     * The last write to land is the one held. `options.idempotencyKey` is sent as the
+     * `Idempotency-Key` header, so a write whose answer was lost is sent again under the same key and
+     * answered as the first was (`MethodLayoutsOffOptions`).
+     *
+     * The write changes the method, so it takes an `admin` or a `member` of the method's
+     * organization. Takes a bare catalog id, as `getMethod` does. Throws `RequestArgumentError` before
+     * any request for `catalogs` that is not an array; its entries are sent as given. Throws
+     * `ApiResponseError`: `404` `pipelex.catalog.not_found` for an unknown method or another
+     * organization's, a public one included; `403` `auth.forbidden` naming the `member` requirement
+     * for a `runner` or a caller with no recognised role; `409` `pipelex.catalog.being_deleted` while
+     * the method's erasure is pending, under way or stopped; `413` `request.too_large` for a list that
+     * would leave the method too large to publish, which a list that does not grow never is; and
+     * `422` `request.invalid` for more than 8 catalogs, a catalog named twice or one that is not a
+     * slug. Under an idempotency key, `409` `request.idempotency_conflict` for the key sent with a
+     * different list and `409` `request.idempotency_key_in_use` while its earlier request is still
+     * being handled; a key that is not 1 to 255 visible ASCII characters is a `RequestArgumentError`
+     * before any request.
+     */
+    async setMethodLayoutsOff(methodId, catalogs, options = {}) {
+        const call = "setMethodLayoutsOff";
+        const endpoint = `${methodPath(methodId, call)}/layouts-off`;
+        if (!Array.isArray(catalogs)) {
+            throw argumentRefusal(call, LAYOUTS_OFF_CATALOGS_ARGUMENT, describeNumberArgument(catalogs), "not_a_list");
+        }
+        const idempotencyKey = idempotencyKeyOf(options, "set the layouts off");
+        return this.requestMethodData("PUT", endpoint, { catalogs }, { idempotencyKey });
+    }
     /**
      * Copy a method into an organization the caller may change methods in —
      * `POST /v1/methods/{id}/copy`: the method's own organization for a duplicate, another team, or
@@ -4402,13 +4565,14 @@ const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
  */
 const VISIBLE_ASCII = /^[\x21-\x7E]+$/;
 /**
- * The idempotency key a start, a method copy, a secret rotation or a delivery replay sends, or
+ * The idempotency key a start, a method copy, a layout write, a write of the layouts switched off,
+ * a secret rotation or a delivery replay sends, or
  * `undefined` when the options carry none (absent or `null`). A key that is not a string of 1 to
  * 255 visible ASCII characters is refused with a `RequestArgumentError` rather than dropped, an
  * empty one included, since a request sent without the key its caller gave would lose the
  * protection the caller asked for without a word. `request` says what the request does, as the
- * refusal's last sentence names it ("start the run", "copy the method", "rotate the secret",
- * "replay the delivery"). The message never quotes the key, which a caller may derive from
+ * refusal's last sentence names it ("start the run", "copy the method", "store the layout",
+ * "set the layouts off", "rotate the secret", "replay the delivery"). The message never quotes the key, which a caller may derive from
  * something private. The Python SDK holds a key to the same rule, in the same words.
  */
 function idempotencyKeyOf(options, request = "start the run") {
@@ -4771,6 +4935,54 @@ function withVerdictItems(answer) {
         read.warnings = readProblemItems(answer.warnings);
     return read;
 }
+/**
+ * A valid verdict with its `layouts` read entry by entry (`readMethodLayouts`), only when the
+ * answer carries the key: each entry that reads as a layout is kept, in the answer's order, and a
+ * list left with none is removed, so `layouts` is either absent or holds at least one layout, as
+ * the platform sends it. Any other answer is returned as it came.
+ */
+function withReadLayouts(answer) {
+    if (!isPlainObject(answer) || answer.is_valid !== true || !Object.hasOwn(answer, "layouts")) {
+        return answer;
+    }
+    const read = { ...answer };
+    const layouts = readMethodLayouts(answer.layouts);
+    if (layouts.length === 0)
+        delete read.layouts;
+    else
+        read.layouts = layouts;
+    return read;
+}
+/** `source`'s members that `members` lists, each `optional` one left out when `null` or omitted. */
+function sentMembers(members, source) {
+    const sent = {};
+    for (const [member, presence] of Object.entries(members)) {
+        const value = source[member];
+        if (presence === "required" || value != null)
+            sent[member] = value;
+    }
+    return sent;
+}
+/**
+ * The body `storeMethodLayout` sends for `layout`: the members of `MethodLayoutInput` and nothing
+ * else, since the route's body is closed at both levels, `sample_json` and each provenance member
+ * that is `null` or omitted left out for the platform's default. The members are `LAYOUT_INPUT_MEMBERS` and
+ * `PROVENANCE_INPUT_MEMBERS`, which the build holds to the interfaces. A layout or a provenance that is not an object is
+ * refused with `RequestArgumentError` before anything is sent; every other member is sent as given,
+ * for the platform to hold to its shapes, its `422` naming the member it refuses.
+ */
+function methodLayoutBody(layout, call) {
+    if (!isPlainObject(layout)) {
+        throw argumentRefusal(call, LAYOUT_ARGUMENT, describeNumberArgument(layout), "not_an_object");
+    }
+    const provenance = layout.provenance;
+    if (!isPlainObject(provenance)) {
+        throw argumentRefusal(call, LAYOUT_PROVENANCE_ARGUMENT, describeNumberArgument(provenance), "not_an_object");
+    }
+    const body = sentMembers(LAYOUT_INPUT_MEMBERS, layout);
+    body.provenance = sentMembers(PROVENANCE_INPUT_MEMBERS, provenance);
+    return body;
+}
 /**
  * A run record with its `error` kept only when it is a problem document, and read as `null`
  * otherwise. Only when the record carries the `error` key, so a server that does not serve it