Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

79.7 KB
Raw Blame
import { describe, expect, test } from "vitest";
import {
  getInputJsonSchemaMetadata,
  ROOT_INSTANCE_ID,
  toInputJsonSchemaObject,
  type Assets,
  type InputJsonSchema,
  type Instance,
} from "@webstudio-is/sdk";
import { runtimeOperationContracts } from "../contracts/builder-runtime";
import { getRuntimeGeneratedInputPaths } from "../contracts/input-schema";
import { builderRuntimeCutoverManifests } from "./cutover";
import {
  builderRuntimeOperations,
  executeBuilderRuntimeOperation,
  getBuilderRuntimeOperation,
  isDestructiveRuntimeCommand,
} from "./registry";
import { runtimeGeneratedIdInput } from "./generated-id-input";
import { createEmptyWebstudioFragment } from "./component-template";
import { getRuntimeOutputSchema, runtimeOutputSchemas } from "./output-schemas";
import { getPage, listFolders, listPages } from "./pages";
import {
  getStyleDeclarations,
  listCssVariables,
  listDesignTokens,
} from "./styles";
import {
  inspectInstance,
  listInstances,
  listTextInstances,
  updateTextInstance,
} from "./instances";
import { listDataVariables, listResources } from "./data";
import { listFonts } from "./fonts";
import { listAssets } from "./assets";
import { bindProps, deleteProps, updateProps } from "./props";
import type { BuilderState } from "../state/builder-state";
import { applyBuilderPatchTransactions } from "../state/patch";
import type { SemanticValidationIssue } from "./errors";
import {
  context,
  expectRuntimeValidationError,
  state,
} from "./runtime.test-fixtures";
import { createResourceCollectionIntegrationFixture } from "./runtime-ui.test-fixture";
import type { ContentBlockApplication } from "./content-block-application";
import type { BuilderRuntimeMutation } from "./mutation";

const hasDirectInputProperty = (
  schema: InputJsonSchema | undefined,
  property: string
): boolean => {
  const schemaObject = toInputJsonSchemaObject(schema);
  if (schemaObject === undefined) {
    return false;
  }
  if (Object.hasOwn(schemaObject.properties ?? {}, property)) {
    return true;
  }
  return (
    schemaObject.oneOf?.some((branch) =>
      hasDirectInputProperty(toInputJsonSchemaObject(branch), property)
    ) ??
    schemaObject.anyOf?.some((branch) =>
      hasDirectInputProperty(toInputJsonSchemaObject(branch), property)
    ) ??
    schemaObject.allOf?.some((branch) =>
      hasDirectInputProperty(toInputJsonSchemaObject(branch), property)
    ) ??
    false
  );
};

const mutationOperationIds = runtimeOperationContracts
  .filter((contract) => contract.kind === "mutation")
  .map((contract) => contract.id);

const paginatedReadOperationIds = [
  "pages.list",
  "redirects.list",
  "breakpoints.list",
  "pageTemplates.list",
  "folders.list",
  "instances.list",
  "instances.listTexts",
  "styles.getDeclarations",
  "designTokens.list",
  "cssVariables.list",
  "variables.list",
  "resources.list",
  "assetsResources.list",
  "assets.list",
  "fonts.list",
] as const;

const maxCompactListBytes = 16 * 1024;

test("property writes load assets and reject an incompatible Image source", () => {
  const operation = getBuilderRuntimeOperation("instances.updateProps");
  expect(operation.readNamespaces).toContain("assets");
  expect(operation.requiresAssets).toBe(true);
  const image: Instance = {
    type: "instance",
    id: "image",
    component: "Image",
    children: [],
  };
  const assets: Assets = new Map([
    [
      "text",
      {
        id: "text",
        projectId: "project",
        name: "data.txt",
        type: "file",
        format: "txt",
        meta: {},
        size: 1,
        createdAt: "",
      },
    ],
  ]);
  expect(() =>
    executeBuilderRuntimeOperation({
      id: "instances.updateProps",
      state: {
        instances: new Map([[image.id, image]]),
        props: new Map(),
        assets,
      },
      input: {
        updates: [
          { instanceId: image.id, name: "src", type: "asset", value: "text" },
        ],
      },
      context,
    })
  ).toThrow(expect.objectContaining({ code: "BAD_REQUEST" }));
});

test("fragment insertion is available to Content mode editors", () => {
  expect(getBuilderRuntimeOperation("instances.insertFragment").permit).toBe(
    "edit"
  );
});

test("rejects a fragment containing a Form with more than 10 actions", () => {
  let nextId = 0;
  expect(() =>
    executeBuilderRuntimeOperation({
      id: "instances.insertFragment",
      state,
      input: {
        parentInstanceId: "body",
        fragment: {
          ...createEmptyWebstudioFragment(),
          children: [{ type: "id", value: "new-form" }],
          instances: [
            {
              type: "instance",
              id: "new-form",
              component: "ResourceForm",
              children: [],
            },
          ],
          props: [
            {
              id: "form-action",
              instanceId: "new-form",
              name: "action",
              type: "json",
              value: Array.from({ length: 11 }, (_, index) => ({
                dataSourceId: `resource-${index}`,
              })),
            },
          ],
        },
      },
      context: { createId: () => `form-test-${nextId++}` },
    })
  ).toThrow("Select no more than 10 Resource actions");
});

test("assets.list accepts every stored asset type", () => {
  const operation = getBuilderRuntimeOperation("assets.list");

  expect(operation.inputSchema.parse({ type: "file" })).toEqual({
    type: "file",
  });
});

test.each(paginatedReadOperationIds)(
  "%s uses the shared paginated compact/verbose contract",
  (operationId) => {
    const operation = getBuilderRuntimeOperation(operationId);
    expect(hasDirectInputProperty(operation.inputJsonSchema, "cursor")).toBe(
      true
    );
    expect(hasDirectInputProperty(operation.inputJsonSchema, "limit")).toBe(
      true
    );
    expect(hasDirectInputProperty(operation.inputJsonSchema, "verbose")).toBe(
      true
    );
    for (const property of [
      "detail",
      "total",
      "returnedCount",
      "nextCursor",
      "filters",
    ]) {
      expect(
        hasDirectInputProperty(operation.outputJsonSchema, property),
        `${operationId} output is missing ${property}`
      ).toBe(true);
    }
  }
);

const getMutationResult = (operation: unknown): unknown => {
  expect(operation).toHaveProperty("result");
  return (operation as { result: unknown }).result;
};

test("contentBlocks.editSource preserves invalid MDX and returns diagnostics", async () => {
  const source = "# Kept\n\n<ws.element";
  const diagnostic = {
    code: "invalid-mdx" as const,
    severity: "error" as const,
    blockInstanceId: "block",
    assetId: "asset",
    contentRef: "article.mdx",
    renderScope: "page",
    message: "Unexpected end of file",
    sourceRange: {
      start: { line: 3, column: 12, offset: source.length },
      end: { line: 3, column: 12, offset: source.length },
    },
  };
  const result = await executeBuilderRuntimeOperation({
    id: "contentBlocks.editSource",
    state,
    input: { blockInstanceId: "block", renderScope: "page", source },
    context: {
      ...context,
      contentBlockApplication: {
        editSource: async () => ({
          state: {
            asset: { id: "asset" },
            status: "saved" as const,
          },
          source,
          diagnostics: [diagnostic],
        }),
      } as unknown as ContentBlockApplication,
    },
  });

  expect(getMutationResult(result)).toEqual({
    assetId: "asset",
    source,
    status: "saved",
    diagnostics: [diagnostic],
  });
});

test.each([
  {
    family: "page",
    operationId: "pages.create",
    input: { name: false, path: "/" },
    path: ["name"],
    constraint: "type:string",
  },
  {
    family: "instance",
    operationId: "instances.move",
    input: {
      moves: [
        { instanceId: "item", parentInstanceId: "parent", insertIndex: -1 },
      ],
    },
    path: ["moves", "0", "insertIndex"],
    constraint: "number:minimum:0",
  },
  {
    family: "prop",
    operationId: "instances.updateProps",
    input: { updates: "not-an-array" },
    path: ["updates"],
    constraint: "type:array",
  },
  {
    family: "style",
    operationId: "styles.updateDeclarations",
    input: { updates: [{ instanceId: "item", property: false, value: "red" }] },
    path: ["updates", "0", "property"],
    constraint: "type:string",
  },
  {
    family: "resource",
    operationId: "resources.create",
    input: {
      resource: { name: "Posts", method: "get", url: "/posts", headers: {} },
    },
    path: ["resource", "headers"],
    constraint: "type:array",
  },
  {
    family: "expression",
    operationId: "instances.updateProps",
    input: {
      updates: [
        {
          instanceId: "item",
          name: "title",
          type: "expression",
          value: "invalid {",
        },
      ],
    },
    path: ["updates", "0", "value"],
    constraint: "valid_webstudio_expression",
  },
  {
    family: "project settings",
    operationId: "projectSettings.update",
    input: { meta: { siteName: false } },
    path: ["meta", "siteName"],
    constraint: "type:string",
  },
])(
  "returns an actionable $family input issue",
  ({ operationId, input, path, constraint }) => {
    expectRuntimeValidationError(operationId, input, { path, constraint });
  }
);

test("keeps generated runtime contracts in sync with the registry", () => {
  expect(runtimeOperationContracts).toEqual(
    builderRuntimeOperations.map(
      ({
        id,
        command,
        client,
        permit,
        kind,
        inputJsonSchema,
        outputJsonSchema,
        readNamespaces,
        writeNamespaces,
        invalidatesNamespaces,
        retryOnConflict,
        requiresAssets,
        requiresConfirm,
      }) => ({
        id,
        command,
        client,
        permit,
        kind,
        inputSchema: inputJsonSchema,
        outputSchema: outputJsonSchema,
        readNamespaces,
        writeNamespaces,
        invalidatesNamespaces,
        retryOnConflict,
        requiresAssets,
        requiresConfirm,
      })
    )
  );
});

test.each(["pages.create", "pages.update", "pages.updateSettings"])(
  "%s loads the page expression scope",
  (operationId) => {
    expect(getBuilderRuntimeOperation(operationId).readNamespaces).toEqual([
      "pages",
      "instances",
      "dataSources",
    ]);
  }
);

test("requires an output schema for every runtime operation", () => {
  expect(
    builderRuntimeOperations
      .filter((operation) => operation.outputSchema === undefined)
      .map((operation) => operation.id)
  ).toEqual([]);
  expect(
    Object.keys(runtimeOutputSchemas)
      .filter((operationId) => operationId.startsWith("system.") === false)
      .sort()
  ).toEqual(builderRuntimeOperations.map((operation) => operation.id).sort());
  expect(() => getRuntimeOutputSchema("missing.operation")).toThrow(
    'Missing runtime output schema for operation "missing.operation".'
  );
});

test("validates structured runtime operation results", () => {
  expect(
    getRuntimeOutputSchema("resources.update").parse({ resourceId: "resource" })
  ).toEqual({ resourceId: "resource" });
  expect(
    getRuntimeOutputSchema("resources.update").parse({
      resourceId: "resource",
      dataSourceId: "data-source",
      warnings: [
        {
          severity: "warning",
          code: "expression_lint_warning",
          path: ["resource", "url"],
          message: '"missing" is not defined in the scope',
          range: { from: 0, to: 7 },
          remediation: "Use an in-scope variable.",
        },
      ],
    })
  ).toMatchObject({
    dataSourceId: "data-source",
    warnings: [{ code: "expression_lint_warning" }],
  });

  expect(
    getRuntimeOutputSchema("instances.deleteBySelector").safeParse({
      instanceSelector: ["instance", "parent"],
    }).success
  ).toBe(false);
  expect(
    getRuntimeOutputSchema("instances.replacePropText").parse({
      changedCount: 1,
      matchingPropCount: 1,
      truncated: false,
      matches: [
        {
          propId: "prop",
          instanceId: "instance",
          name: "title",
          before: "Before",
          after: "After",
        },
      ],
    }).matches
  ).toHaveLength(1);
});

describe("builder runtime pages", () => {
  test("lists pages and folders from shared state", () => {
    expect(listPages(state)).toMatchObject({
      pages: [
        { id: "home", path: "", isHome: true, parentFolderId: "root" },
        { id: "post", path: "/blog/post", parentFolderId: "blog" },
      ],
    });

    expect(listFolders(state)).toMatchObject({
      folders: [
        { id: "root", parentFolderId: undefined },
        { id: "blog", parentFolderId: "root" },
      ],
    });
  });

  test("gets page details by id and path", () => {
    expect(getPage(state, { pageId: "post" })).toMatchObject({
      id: "post",
      path: "/blog/post",
      meta: {
        description: "Post description",
        excludePageFromSearch: true,
        documentType: "html",
      },
    });

    expect(
      executeBuilderRuntimeOperation({
        id: "pages.getByPath",
        state,
        input: { path: "/blog/post" },
        context,
      })
    ).toMatchObject({ id: "post" });
  });

  test("validates page and folder mutations through public operations", () => {
    expect(() =>
      executeBuilderRuntimeOperation({
        id: "pages.create",
        state,
        input: {
          name: "Broken",
          path: "/prefix-:id",
        },
        context,
      })
    ).toThrow();

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "pages.update",
        state,
        input: {
          pageId: "post",
          values: { path: "/blog-*" },
        },
        context,
      })
    ).toThrow();

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "folders.create",
        state,
        input: {
          name: "Invalid Folder",
          slug: "Invalid Folder",
        },
        context,
      })
    ).toThrow();

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "folders.update",
        state,
        input: {
          folderId: "blog",
          values: { slug: "invalid/folder" },
        },
        context,
      })
    ).toThrow();
  });
});

describe("builder runtime read families", () => {
  test("keeps representative high-volume compact lists within budget", () => {
    const sourceInstance = state.instances.get("heading")!;
    const sourceAsset = state.assets.get("asset")!;
    const sourceToken = state.styleSources.get("token")!;
    const largeState: BuilderState = {
      ...state,
      instances: new Map(
        Array.from({ length: 100 }, (_, index) => {
          const id = `instance-${index}`;
          return [id, { ...sourceInstance, id, label: `Item ${index}` }];
        })
      ),
      assets: new Map(
        Array.from({ length: 100 }, (_, index) => {
          const id = `asset-${index}`;
          return [
            id,
            {
              ...sourceAsset,
              id,
              name: `${id}.png`,
              description: `Verbose description ${"detail ".repeat(100)}`,
            },
          ];
        })
      ),
      styleSources: new Map(
        Array.from({ length: 100 }, (_, index) => {
          const id = `token-${index}`;
          return [id, { ...sourceToken, id, name: `Token ${index}` }];
        })
      ),
      styles: new Map(),
      styleSourceSelections: new Map(),
    };

    const outputs = [
      listInstances(largeState),
      listAssets(largeState),
      listDesignTokens(largeState),
    ];

    for (const output of outputs) {
      expect(output.returnedCount).toBe(20);
      expect(Buffer.byteLength(JSON.stringify(output))).toBeLessThanOrEqual(
        maxCompactListBytes
      );
    }
  });

  test("keeps instance lists compact and paginates verbose expansion", () => {
    const instances: BuilderState["instances"] = new Map(state.instances);
    const largeState: BuilderState = {
      ...state,
      instances,
    };
    instances.set("body", {
      ...state.instances.get("body")!,
      children: [
        ...Array.from({ length: 100 }, (_, index) => ({
          type: "id" as const,
          value: `repeated-child-${index}-${"detail-".repeat(10)}`,
        })),
        { type: "id" as const, value: "heading" },
      ],
    });
    const compact = listInstances(largeState, { limit: 1 });
    const verbose = listInstances(largeState, { limit: 1, verbose: true });

    expect(compact).toMatchObject({
      detail: "compact",
      total: 2,
      returnedCount: 1,
      nextCursor: "1",
      instances: [{ id: "body" }],
    });
    expect(compact.instances[0]).not.toHaveProperty("record");
    expect(verbose).toMatchObject({
      detail: "verbose",
      total: compact.total,
      returnedCount: compact.returnedCount,
      nextCursor: compact.nextCursor,
      instances: [
        expect.objectContaining({
          ...compact.instances[0],
          record: expect.objectContaining({ id: "body" }),
        }),
      ],
    });
    expect(JSON.stringify(compact).length).toBeLessThan(
      JSON.stringify(verbose).length * 0.5
    );
  });

  test("reads instances and text nodes", () => {
    expect(
      executeBuilderRuntimeOperation({
        id: "instances.list",
        state,
        input: { pageId: "home" },
        context,
      })
    ).toMatchObject({
      instances: [
        { id: "body", depth: 0 },
        {
          id: "heading",
          depth: 1,
          label: "Hero",
          parentId: "body",
          indexWithinParent: 0,
        },
      ],
    });

    expect(inspectInstance(state, { instanceId: "heading" })).toMatchObject({
      id: "heading",
      props: expect.arrayContaining([expect.objectContaining({ id: "prop" })]),
    });

    const inspectedInstance = inspectInstance(state, {
      instanceId: "heading",
      include: ["props", "styles", "sources", "ancestors"],
    });
    expect(inspectedInstance).toMatchObject({
      id: "heading",
      parentId: "body",
      indexWithinParent: 0,
      ancestors: [{ id: "body", childIndex: 0 }],
      sources: ["token", "local"],
    });
    expect(inspectedInstance.styles).toEqual(
      expect.arrayContaining([
        expect.objectContaining({ instanceId: "heading", property: "color" }),
      ])
    );
    expect(inspectedInstance.props).toEqual(
      expect.arrayContaining([expect.objectContaining({ id: "prop" })])
    );

    expect(listTextInstances(state, { contains: "Hello" })).toMatchObject({
      texts: [
        {
          instanceId: "heading",
          childIndex: 0,
          valuePreview: "Hello",
          valueLength: 5,
          truncated: false,
        },
      ],
    });
  });

  test("builds text update mutations", () => {
    expect(
      updateTextInstance(state, {
        instanceId: "heading",
        childIndex: 0,
        text: "Updated",
      })
    ).toMatchObject({
      kind: "mutation",
      noop: false,
      payload: [
        {
          namespace: "instances",
          patches: [
            {
              op: "replace",
              path: ["heading", "children", 0],
              value: { type: "text", value: "Updated" },
            },
          ],
        },
      ],
      result: { instanceId: "heading", childIndex: 0, mode: "text" },
    });

    expect(
      updateTextInstance(state, {
        instanceId: "heading",
        childIndex: 0,
        text: "Hello",
      })
    ).toMatchObject({
      noop: true,
      payload: [],
      result: { instanceId: "heading", childIndex: 0, mode: "text" },
    });
  });

  test("replaces bounded literal text through the public runtime operation", () => {
    const replaceState = {
      ...state,
      instances: new Map<
        string,
        NonNullable<BuilderState["instances"]> extends Map<
          string,
          infer Instance
        >
          ? Instance
          : never
      >([
        ...state.instances,
        [
          "subtitle",
          {
            type: "instance" as const,
            id: "subtitle",
            component: "Text",
            tag: "p",
            children: [{ type: "text" as const, value: "Hello from Acme" }],
          },
        ],
      ]),
    } satisfies BuilderState;

    expect(
      executeBuilderRuntimeOperation({
        id: "instances.replaceText",
        state: replaceState,
        input: {
          find: "Hello",
          replace: "Welcome",
          match: "substring",
          limit: 1,
        },
        context,
      })
    ).toMatchObject({
      kind: "mutation",
      result: {
        changedCount: 1,
        matchingChildCount: 2,
        truncated: true,
        matches: [
          {
            instanceId: "heading",
            childIndex: 0,
            before: "Hello",
            after: "Welcome",
          },
        ],
      },
      payload: [
        {
          namespace: "instances",
          patches: [
            {
              op: "replace",
              path: ["heading", "children", 0],
              value: { type: "text", value: "Welcome" },
            },
          ],
        },
      ],
    });
  });

  test("builds prop mutations", () => {
    expect(
      updateProps(
        state,
        {
          updates: [
            {
              instanceId: "heading",
              name: "title",
              type: "string",
              value: "Updated",
            },
          ],
        },
        context
      )
    ).toMatchObject({
      kind: "mutation",
      noop: false,
      result: { propIds: ["prop"] },
      payload: [{ namespace: "props" }],
    });

    expect(
      bindProps(
        state,
        {
          bindings: [
            {
              instanceId: "heading",
              name: "title",
              binding: { type: "expression", value: "title" },
            },
          ],
        },
        context
      )
    ).toMatchObject({
      result: { propIds: ["prop"] },
      payload: [{ namespace: "props" }],
    });

    expect(
      deleteProps(state, {
        deletions: [{ instanceId: "heading", name: "src" }],
      })
    ).toMatchObject({
      result: { propIds: ["resourceProp"] },
      payload: [{ namespace: "props" }, { namespace: "resources" }],
    });
  });

  test("binds readable expression names to data sources at write time", () => {
    const propResult = executeBuilderRuntimeOperation({
      id: "instances.bindProps",
      state,
      input: {
        bindings: [
          {
            instanceId: "heading",
            name: "title",
            binding: { type: "expression", value: "Title" },
          },
        ],
      },
      context,
    });
    expect(propResult).toMatchObject({
      payload: [
        {
          namespace: "props",
          patches: [
            {
              value: {
                type: "expression",
                value: "$ws$dataSource$variable",
              },
            },
          ],
        },
      ],
    });

    const textResult = executeBuilderRuntimeOperation({
      id: "instances.updateText",
      state,
      input: {
        instanceId: "heading",
        childIndex: 0,
        text: 'Title ?? "Untitled"',
        mode: "expression",
      },
      context,
    });
    expect(textResult).toMatchObject({
      payload: [
        {
          namespace: "instances",
          patches: [
            {
              value: {
                type: "expression",
                value: '$ws$dataSource$variable ?? "Untitled"',
              },
            },
          ],
        },
      ],
    });

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "instances.updateText",
        state,
        input: {
          instanceId: "heading",
          childIndex: 0,
          text: "$ws$dataSource$stale.name",
          mode: "expression",
        },
        context,
      })
    ).toThrow(/data source "stale".*not available/);
  });

  test("returns non-blocking expression warnings with actionable locations", () => {
    const text = executeBuilderRuntimeOperation({
      id: "instances.updateText",
      state,
      input: {
        instanceId: "heading",
        childIndex: 0,
        text: "missingTitle",
        mode: "expression",
      },
      context,
    });
    expect(getMutationResult(text)).toMatchObject({
      warnings: [
        {
          code: "expression_lint_warning",
          path: ["text"],
          instanceId: "heading",
          range: { from: 0, to: 12 },
          remediation: expect.stringContaining("available"),
        },
      ],
    });

    const prop = executeBuilderRuntimeOperation({
      id: "instances.bindProps",
      state,
      input: {
        bindings: [
          {
            instanceId: "heading",
            name: "title",
            binding: { type: "expression", value: "missingTitle" },
          },
          {
            instanceId: "heading",
            name: "onClick",
            binding: {
              type: "action",
              value: [
                {
                  type: "execute",
                  args: ["event"],
                  code: "missingValue = event",
                },
              ],
            },
          },
        ],
      },
      context,
    });
    expect(getMutationResult(prop)).toMatchObject({
      warnings: [
        expect.objectContaining({
          path: ["bindings", "0", "binding", "value"],
          instanceId: "heading",
        }),
        expect.objectContaining({
          path: ["bindings", "1", "binding", "value", "0", "code"],
          instanceId: "heading",
        }),
      ],
    });

    const resource = executeBuilderRuntimeOperation({
      id: "resources.create",
      state,
      input: {
        resource: {
          name: "Create post",
          method: "post",
          url: "https://api.example.com/posts",
          headers: [],
          body: "missingPayload",
        },
      },
      context: {
        ...context,
        createId: (() => {
          const ids = ["warning-resource", "warning-data-source"];
          return () => ids.shift() ?? "id";
        })(),
      },
    });
    expect(getMutationResult(resource)).toMatchObject({
      warnings: [
        expect.objectContaining({
          path: ["resource", "body"],
          resourceId: "warning-resource",
        }),
      ],
    });

    const collection = executeBuilderRuntimeOperation({
      id: "instances.insertCollection",
      state,
      input: {
        parentInstanceId: "body",
        data: { type: "json", value: [{ name: "Starter" }] },
        itemFragment: {
          children: [{ type: "id", value: "item" }],
          instances: [
            {
              type: "instance",
              id: "item",
              component: "Text",
              children: [
                { type: "expression", value: "collectionItem.name" },
                { type: "expression", value: "missingCollectionItem.name" },
              ],
            },
          ],
          props: [],
          dataSources: [],
          resources: [],
          styleSources: [],
          styleSourceSelections: [],
          styles: [],
          breakpoints: [],
          assets: [],
        },
      },
      context: {
        ...context,
        createId: (() => {
          const ids = [
            "collection",
            "collection-data-prop",
            "collection-item",
            "collection-item-key",
          ];
          return () => ids.shift() ?? "generated-id";
        })(),
      },
    });
    expect(getMutationResult(collection)).toMatchObject({
      warnings: [
        expect.objectContaining({
          path: ["itemFragment", "instances", "0", "children", "1", "value"],
          message: expect.stringContaining("missingCollectionItem"),
        }),
      ],
    });

    try {
      executeBuilderRuntimeOperation({
        id: "instances.bindProps",
        state,
        input: {
          bindings: [
            {
              instanceId: "heading",
              name: "onClick",
              binding: {
                type: "action",
                value: [{ type: "execute", args: ["event"], code: "event +" }],
              },
            },
          ],
        },
        context,
      });
      expect.unreachable("Expected invalid action syntax to be rejected");
    } catch (error) {
      expect(error).toMatchObject({
        code: "INVALID_INPUT",
        issues: [
          expect.objectContaining({
            path: ["bindings", "0", "binding", "value"],
            detail: expect.stringMatching(/Unexpected token/),
          }),
        ],
      });
    }
  });

  test("binds Collection data and item names in their respective scopes", () => {
    const collectionState = {
      ...state,
      instances: new Map([
        [
          "body",
          {
            type: "instance" as const,
            id: "body",
            component: "Body",
            children: [{ type: "id" as const, value: "collection" }],
          },
        ],
        [
          "collection",
          {
            type: "instance" as const,
            id: "collection",
            component: "ws:collection",
            children: [{ type: "id" as const, value: "item" }],
          },
        ],
        [
          "item",
          {
            type: "instance" as const,
            id: "item",
            component: "Text",
            children: [{ type: "text" as const, value: "Item" }],
          },
        ],
      ]),
      props: new Map(),
      dataSources: new Map([
        [
          "plans",
          {
            id: "plans",
            type: "variable" as const,
            name: "Plans",
            scopeInstanceId: "body",
            value: { type: "json" as const, value: [{ name: "Starter" }] },
          },
        ],
        [
          "item-parameter",
          {
            id: "item-parameter",
            type: "parameter" as const,
            name: "collectionItem",
            scopeInstanceId: "collection",
          },
        ],
      ]),
    } satisfies BuilderState;

    expect(
      executeBuilderRuntimeOperation({
        id: "instances.bindProps",
        state: collectionState,
        input: {
          bindings: [
            {
              instanceId: "collection",
              name: "data",
              binding: { type: "expression", value: "Plans" },
            },
          ],
        },
        context,
      })
    ).toMatchObject({
      result: { propIds: ["id"] },
      payload: [
        {
          namespace: "props",
          patches: [
            {
              value: {
                value: "$ws$dataSource$plans",
              },
            },
          ],
        },
      ],
    });

    const validItemBinding = executeBuilderRuntimeOperation({
      id: "instances.updateText",
      state: collectionState,
      input: {
        instanceId: "item",
        childIndex: 0,
        text: "collectionItem.name",
        mode: "expression",
      },
      context,
    });
    expect(validItemBinding).toMatchObject({
      payload: [
        {
          namespace: "instances",
          patches: [
            {
              value: {
                value: "$ws$dataSource$item__DASH__parameter.name",
              },
            },
          ],
        },
      ],
    });

    const invalidItemBinding = executeBuilderRuntimeOperation({
      id: "instances.updateText",
      state: collectionState,
      input: {
        instanceId: "item",
        childIndex: 0,
        text: "missingCollectionItem.name",
        mode: "expression",
      },
      context,
    });
    expect(getMutationResult(invalidItemBinding)).toMatchObject({
      warnings: [
        expect.objectContaining({
          path: ["text"],
          instanceId: "item",
          message: expect.stringContaining("missingCollectionItem"),
        }),
      ],
    });
  });

  test("replaces bounded static prop text without changing dynamic bindings", () => {
    const replaceState = {
      ...state,
      props: new Map<
        string,
        NonNullable<BuilderState["props"]> extends Map<string, infer Prop>
          ? Prop
          : never
      >([
        ...state.props,
        [
          "expression-prop",
          {
            id: "expression-prop",
            instanceId: "heading",
            name: "title",
            type: "expression" as const,
            value: "Heading",
          },
        ],
      ]),
    } satisfies BuilderState;

    expect(
      executeBuilderRuntimeOperation({
        id: "instances.replacePropText",
        state: replaceState,
        input: {
          find: "Heading",
          replace: "Welcome",
          match: "exact",
          names: ["title"],
          limit: 1,
        },
        context,
      })
    ).toMatchObject({
      kind: "mutation",
      result: {
        changedCount: 1,
        matchingPropCount: 1,
        truncated: false,
        matches: [
          {
            propId: "prop",
            instanceId: "heading",
            name: "title",
            before: "Heading",
            after: "Welcome",
          },
        ],
      },
      payload: [
        {
          namespace: "props",
          patches: [
            {
              op: "replace",
              path: ["prop", "value"],
              value: "Welcome",
            },
          ],
        },
      ],
    });
  });

  test("deletes multiple props through the public runtime operation", () => {
    expect(
      executeBuilderRuntimeOperation({
        id: "instances.deleteProps",
        state,
        input: {
          deletions: [
            { instanceId: "heading", name: "title" },
            { instanceId: "heading", name: "aria-label" },
          ],
        },
        context,
      })
    ).toMatchObject({
      result: { propIds: ["prop", "labelProp"] },
      payload: [
        {
          namespace: "props",
          patches: [
            { op: "remove", path: ["prop"] },
            { op: "remove", path: ["labelProp"] },
          ],
        },
      ],
    });
  });

  test("reads styles, tokens, variables, and resources", () => {
    const declarations = getStyleDeclarations(state, {
      instanceIds: ["heading"],
    });
    expect(declarations.declarations).toEqual(
      expect.arrayContaining([
        expect.objectContaining({ instanceId: "heading", property: "color" }),
      ])
    );
    expect(listDesignTokens(state, { withUsage: true })).toMatchObject({
      tokens: [{ id: "token", declarationCount: 1, usageCount: 1 }],
    });
    expect(
      listDesignTokens(state, { withUsage: true, verbose: true })
    ).toMatchObject({
      tokens: [{ id: "token", styles: { color: expect.any(Object) } }],
    });
    expect(listCssVariables(state, { withUsage: true })).toMatchObject({
      vars: [
        {
          name: "--brand-color",
          scope: "heading",
          usageCount: 1,
          value: "red",
          valueLength: 3,
        },
      ],
    });
    expect(listDataVariables(state)).toMatchObject({
      variables: [
        {
          id: "variable",
          scopeInstanceId: "heading",
          valueType: expect.any(String),
        },
      ],
    });
    expect(listDataVariables(state, { verbose: true })).toMatchObject({
      variables: [{ value: expect.any(Object) }],
    });
    expect(listResources(state)).toMatchObject({
      resources: [{ id: "resource", dataSourceId: "resourceDataSource" }],
    });
  });

  test("compact list records are bounded subsets of verbose records", () => {
    const assertions = [
      [
        listCssVariables(state, { withUsage: true }),
        listCssVariables(state, { withUsage: true, verbose: true }),
      ],
      [listDataVariables(state), listDataVariables(state, { verbose: true })],
    ] as const;

    for (const [compact, verbose] of assertions) {
      const { detail: _compactDetail, ...compactResult } = compact;
      const { detail: _verboseDetail, ...verboseResult } = verbose;
      expect(verboseResult).toMatchObject(compactResult);
      expect(JSON.stringify(compact).length).toBeLessThanOrEqual(
        JSON.stringify(verbose).length
      );
      expect(verbose.total).toBe(compact.total);
      expect(verbose.nextCursor).toBe(compact.nextCursor);
    }

    const instances = new Map<string, Instance>(state.instances);
    const heading = instances.get("heading");
    if (heading === undefined || heading.type !== "instance") {
      throw new Error("Expected heading fixture");
    }
    instances.set("heading", {
      ...heading,
      children: [{ type: "text", value: "x".repeat(400) }],
    });
    const compactText = listTextInstances({ ...state, instances });
    const verboseText = listTextInstances(
      { ...state, instances },
      { verbose: true }
    );
    const { detail: _compactDetail, ...compactTextResult } = compactText;
    const { detail: _verboseDetail, ...verboseTextResult } = verboseText;
    expect(verboseTextResult).toMatchObject(compactTextResult);
    expect(compactText.texts[0]).toMatchObject({
      valueLength: 400,
      truncated: true,
    });
    expect(JSON.stringify(compactText).length).toBeLessThan(
      JSON.stringify(verboseText).length
    );
  });

  test("cursor traversal preserves page ordering without duplication", () => {
    const first = listPages(state, { limit: 1 });
    const second = listPages(state, {
      limit: 1,
      cursor: first.nextCursor ?? undefined,
    });

    expect([...first.pages, ...second.pages].map((page) => page.id)).toEqual([
      "home",
      "post",
    ]);
    expect(second.nextCursor).toBeNull();
  });

  test("lists uploaded font families separately from system font stacks", () => {
    const assets: Assets = new Map(state.assets);
    assets.set("font", {
      id: "font",
      projectId: "project",
      name: "acme-sans.woff2",
      type: "font",
      size: 1,
      format: "woff2",
      createdAt: "2026-01-01T00:00:00.000Z",
      description: null,
      meta: { family: "Acme Sans", style: "normal", weight: 400 },
    });
    const fontState = {
      ...state,
      assets,
    } satisfies BuilderState;

    expect(listFonts(fontState, { includeSystem: false })).toEqual({
      uploaded: [
        {
          family: "Acme Sans",
          source: "uploaded",
          assetCount: 1,
        },
      ],
      system: [],
      detail: "compact",
      total: 1,
      returnedCount: 1,
      nextCursor: null,
      filters: { includeSystem: false },
    });

    expect(
      listFonts(fontState, { includeSystem: false, verbose: true })
    ).toMatchObject({
      uploaded: [
        {
          family: "Acme Sans",
          assetCount: 1,
          assets: [
            {
              assetId: "font",
              format: "woff2",
              style: "normal",
              weight: 400,
              variable: false,
            },
          ],
        },
      ],
      detail: "verbose",
    });

    expect(
      executeBuilderRuntimeOperation({
        id: "fonts.list",
        state: fontState,
        input: {},
        context,
      })
    ).toMatchObject({
      uploaded: [{ family: "Acme Sans" }],
      system: expect.arrayContaining([
        expect.objectContaining({ family: "System UI", source: "system" }),
      ]),
    });
  });

  test("validates data variable mutations through public operations", () => {
    expect(
      executeBuilderRuntimeOperation({
        id: "variables.create",
        state,
        input: {
          scopeInstanceId: "heading",
          name: "Subtitle",
          value: { type: "string", value: "Hello" },
        },
        context,
      })
    ).toMatchObject({
      kind: "mutation",
      result: { dataSourceId: "id" },
      payload: [{ namespace: "dataSources" }],
    });

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "variables.create",
        state,
        input: {
          scopeInstanceId: "heading",
          name: "Title",
          value: { type: "string", value: "Hello" },
        },
        context,
      })
    ).toThrow("Name is already used by another variable on this instance");

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "variables.update",
        state,
        input: {
          dataSourceId: "variable",
          values: { name: "" },
        },
        context,
      })
    ).toThrow();
  });

  test("validates style mutation inputs through shared runtime schemas", () => {
    const updates = [
      {
        instanceId: "heading",
        property: "box-shadow",
        value: { type: "keyword", value: "none" },
      },
    ];
    expect(
      executeBuilderRuntimeOperation({
        id: "styles.updateDeclarations",
        state,
        input: { updates: JSON.stringify(updates) },
        context,
      })
    ).toMatchObject({
      result: { styleKeys: expect.arrayContaining(["local:base:boxShadow:"]) },
    });

    const deletions = [{ instanceId: "heading", property: "color" }];
    expect(
      executeBuilderRuntimeOperation({
        id: "styles.deleteDeclarations",
        state,
        input: { deletions: JSON.stringify(deletions) },
        context,
      })
    ).toMatchObject({
      result: { styleKeys: ["local:base:color:"] },
    });

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "styles.updateDeclarations",
        state,
        input: { updates: { instanceId: "heading" } },
        context,
      })
    ).toThrow();

    const tokenUpdates = [
      {
        property: "font-size",
        value: { type: "unit", value: 16, unit: "px" },
      },
    ];
    expect(
      executeBuilderRuntimeOperation({
        id: "designTokens.updateStyles",
        state,
        input: {
          designTokenId: "token",
          updates: JSON.stringify(tokenUpdates),
        },
        context,
      })
    ).toMatchObject({
      result: { designTokenId: "token", styleKeys: ["token:base:fontSize:"] },
    });

    const tokenDeletions = [{ property: "color" }];
    expect(
      executeBuilderRuntimeOperation({
        id: "designTokens.deleteStyles",
        state,
        input: {
          designTokenId: "token",
          deletions: JSON.stringify(tokenDeletions),
        },
        context,
      })
    ).toMatchObject({
      result: { designTokenId: "token", styleKeys: ["token:base:color:"] },
    });

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "designTokens.updateStyles",
        state,
        input: {
          designTokenId: "token",
          updates: { property: "color" },
        },
        context,
      })
    ).toThrow();
  });

  test("validates asset update mutations through the public runtime operation", () => {
    expect(
      executeBuilderRuntimeOperation({
        id: "assets.update",
        state,
        input: {
          assetId: "asset",
          values: {
            filename: "Updated",
            description: "Updated description",
          },
        },
        context,
      })
    ).toMatchObject({
      kind: "mutation",
      result: { assetId: "asset" },
      payload: [
        {
          namespace: "assets",
          patches: [
            { op: "add", path: ["asset", "filename"], value: "Updated" },
            {
              op: "replace",
              path: ["asset", "description"],
              value: "Updated description",
            },
          ],
        },
      ],
    });

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "assets.update",
        state,
        input: {
          assetId: "asset",
          values: { filename: "bad/name" },
        },
        context,
      })
    ).toThrow("Invalid filename");

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "assets.update",
        state,
        input: {
          assetId: "asset",
          values: { filename: "Hero" },
        },
        context,
      })
    ).toThrow("Filename already used");
  });

  test("validates resource URL mutations through the public runtime operation", () => {
    expectRuntimeValidationError(
      "resources.create",
      {
        scopeInstanceId: "heading",
        resource: {
          name: "Users",
          method: "get",
          url: `"not-a-url"`,
          headers: [],
        },
      },
      {
        path: ["resource", "url"],
        constraint: "absolute_or_root_relative_url",
      }
    );

    expectRuntimeValidationError(
      "resources.update",
      {
        resourceId: "resource",
        values: { url: `""` },
      },
      {
        path: ["values", "url"],
        constraint: "absolute_or_root_relative_url",
      }
    );

    const fixedUrlResult = executeBuilderRuntimeOperation({
      id: "resources.create",
      state,
      input: {
        scopeInstanceId: "heading",
        resource: {
          name: "Users",
          method: "get",
          url: "https://api.example.com/users",
          headers: [],
        },
      },
      context: {
        ...context,
        createId: (() => {
          const ids = ["fixed-resource-id", "fixed-data-source-id"];
          return () => ids.shift() ?? "id";
        })(),
      },
    });

    expect(fixedUrlResult).toMatchObject({
      payload: expect.arrayContaining([
        {
          namespace: "resources",
          patches: expect.arrayContaining([
            expect.objectContaining({
              value: expect.objectContaining({
                url: `"https://api.example.com/users"`,
              }),
            }),
          ]),
        },
      ]),
    });

    const literalRequestValuesResult = executeBuilderRuntimeOperation({
      id: "resources.create",
      state,
      input: {
        scopeInstanceId: "heading",
        resource: {
          name: "Literal request values",
          method: "post",
          url: "https://api.example.com/users",
          searchParams: [
            {
              name: "source",
              value: { type: "literal", value: "website" },
            },
          ],
          headers: [
            {
              name: "Content-Type",
              value: { type: "literal", value: "application/json" },
            },
          ],
          body: { type: "literal", value: "Plain text body" },
        },
      },
      context: {
        ...context,
        createId: (() => {
          const ids = ["literal-resource-id", "literal-data-source-id"];
          return () => ids.shift() ?? "id";
        })(),
      },
    });

    expect(literalRequestValuesResult).toMatchObject({
      payload: expect.arrayContaining([
        {
          namespace: "resources",
          patches: expect.arrayContaining([
            expect.objectContaining({
              value: expect.objectContaining({
                url: '"https://api.example.com/users"',
                searchParams: [{ name: "source", value: '"website"' }],
                headers: [
                  { name: "Content-Type", value: '"application/json"' },
                ],
                body: '"Plain text body"',
              }),
            }),
          ]),
        },
      ]),
    });

    const dynamicUrlResult = executeBuilderRuntimeOperation({
      id: "resources.upsert",
      state,
      input: {
        scopeInstanceId: "heading",
        resource: {
          name: "Users",
          method: "get",
          url: "apiUrl",
          headers: [],
        },
      },
      context: {
        ...context,
        createId: (() => {
          const ids = ["resource-id", "data-source-id"];
          return () => ids.shift() ?? "id";
        })(),
      },
    });

    expect(dynamicUrlResult).toMatchObject({
      kind: "mutation",
      result: { resourceId: "resource-id", dataSourceId: "data-source-id" },
    });
  });

  test("creates a default Assets query and supports explicit configuration", () => {
    const defaultQuery = executeBuilderRuntimeOperation({
      id: "assetsResources.create",
      state,
      input: {
        name: "All assets",
        scopeInstanceId: "heading",
      },
      context: {
        ...context,
        createId: (() => {
          const ids = ["all-assets-resource", "all-assets-data-source"];
          return () => ids.shift() ?? "id";
        })(),
      },
    }) as {
      payload: Array<{
        namespace: string;
        patches: Array<{ op: string; value?: unknown }>;
      }>;
    };
    const defaultResource = defaultQuery.payload
      .find(({ namespace }) => namespace === "resources")
      ?.patches.find(({ op }) => op === "add")?.value;
    expect(defaultResource).toMatchObject({
      id: "all-assets-resource",
      control: "system",
      method: "post",
      url: '"/$resources/assets"',
      headers: [
        {
          name: "Content-Type",
          value: '"application/json"',
        },
      ],
    });
    expect(defaultResource).toHaveProperty(
      "body",
      expect.stringContaining('"url"')
    );

    const created = executeBuilderRuntimeOperation({
      id: "assetsResources.create",
      state,
      input: {
        name: "Blog posts",
        scopeInstanceId: "heading",
        query: {
          result: "one",
          where: {
            all: [
              {
                field: ["properties", "slug"],
                operator: "eq",
                value: "system.params.slug",
              },
            ],
          },
          limit: "1",
          content: { mode: "markdown-body-ref", maxBytes: 65_536 },
        },
      },
      context: {
        ...context,
        createId: (() => {
          const ids = ["asset-resource", "asset-data-source"];
          return () => ids.shift() ?? "id";
        })(),
      },
    });
    expect(created).toMatchObject({
      result: {
        resourceId: "asset-resource",
        dataSourceId: "asset-data-source",
        warnings: [],
      },
    });
    const createdMutation = created as {
      payload: Array<{
        namespace: string;
        patches: Array<{ op: string; value?: unknown }>;
      }>;
    };
    const resourcePatch = createdMutation.payload
      .find(({ namespace }) => namespace === "resources")
      ?.patches.find(({ op }) => op === "add");
    const dataSourcePatch = createdMutation.payload
      .find(({ namespace }) => namespace === "dataSources")
      ?.patches.find(({ op }) => op === "add");
    expect(resourcePatch?.value).toMatchObject({
      id: "asset-resource",
      control: "system",
      method: "post",
      url: '"/$resources/assets"',
    });
    expect(resourcePatch?.value).toHaveProperty(
      "body",
      expect.stringContaining('"properties"')
    );

    const queryState = {
      ...state,
      resources: new Map([
        ...state.resources,
        ["asset-resource", resourcePatch?.value],
      ]),
      dataSources: new Map([
        ...state.dataSources,
        ["asset-data-source", dataSourcePatch?.value],
      ]),
    } as BuilderState;
    const inspected = executeBuilderRuntimeOperation({
      id: "assetsResources.get",
      state: queryState,
      input: { resourceId: "asset-resource" },
    });
    expect(inspected).toEqual({
      resource: expect.objectContaining({
        resourceId: "asset-resource",
        name: "Blog posts",
        scopeInstanceId: "heading",
        mode: "query",
        query: {
          result: "one",
          where: {
            all: [
              {
                field: ["properties", "slug"],
                operator: "eq",
                value: "system.params.slug",
              },
            ],
          },
          sort: [],
          limit: "20",
          offset: "0",
          output: {
            mode: "fields",
            includeMetadata: false,
            fields: [["url"], ["width"], ["height"]],
          },
          content: { mode: "markdown-body-ref", maxBytes: 65_536 },
        },
      }),
    });
    expect(
      executeBuilderRuntimeOperation({
        id: "assetsResources.list",
        state: queryState,
        input: {},
      })
    ).toMatchObject({ total: 1, returnedCount: 1 });

    const updated = executeBuilderRuntimeOperation({
      id: "assetsResources.update",
      state: queryState,
      input: {
        resourceId: "asset-resource",
        values: {
          query: {
            result: "many",
            limit: "2",
          },
        },
      },
      context,
    });
    expect((updated as { payload: unknown }).payload).toEqual(
      expect.arrayContaining([
        expect.objectContaining({ namespace: "resources" }),
      ])
    );
    const updatedPayload = JSON.stringify(
      (updated as { payload: unknown }).payload
    );
    expect(updatedPayload).toContain("properties");
    expect(updatedPayload).toContain("system.params.slug");
    expect(updatedPayload).toContain("markdown-body-ref");
    expect(updatedPayload).toContain('result: \\"many\\"');
    expect(updatedPayload).toContain("limit: 2");

    const reset = executeBuilderRuntimeOperation({
      id: "assetsResources.update",
      state: queryState,
      input: {
        resourceId: "asset-resource",
        values: { query: null },
      },
      context,
    });
    expect(JSON.stringify((reset as { payload: unknown }).payload)).toContain(
      '\\"/$resources/assets\\"'
    );
    const resetPayload = JSON.stringify(
      (reset as { payload: unknown }).payload
    );
    expect(resetPayload).toContain('\"method\":\"post\"');
    expect(resetPayload).toContain(
      'fields: [[\\"url\\"], [\\"width\\"], [\\"height\\"]]'
    );

    const storedQueryResource = queryState.resources?.get("asset-resource");
    if (storedQueryResource === undefined) {
      throw new Error("Expected queried Assets resource");
    }
    const invalidQueryState = {
      ...queryState,
      resources: new Map([
        ...(queryState.resources ?? []),
        [
          "invalid-asset-resource",
          {
            ...storedQueryResource,
            id: "invalid-asset-resource",
            body: "invalid query configuration",
          },
        ],
      ]),
    } as BuilderState;
    const repaired = executeBuilderRuntimeOperation({
      id: "assetsResources.update",
      state: invalidQueryState,
      input: {
        resourceId: "invalid-asset-resource",
        values: { query: null },
        scopeInstanceId: "heading",
      },
      context,
    });
    expect(
      JSON.stringify((repaired as { payload: unknown }).payload)
    ).toContain('\\"/$resources/assets\\"');
  });

  test("creates and updates an Assets resource scoped to Global Root", () => {
    const created = executeBuilderRuntimeOperation({
      id: "assetsResources.create",
      state,
      input: {
        name: "Global assets",
        scopeInstanceId: ROOT_INSTANCE_ID,
      },
      context: {
        ...context,
        createId: (() => {
          const ids = ["global-assets-resource", "global-assets-data-source"];
          return () => ids.shift() ?? "id";
        })(),
      },
    });

    expect(created).toMatchObject({
      result: {
        resourceId: "global-assets-resource",
        dataSourceId: "global-assets-data-source",
      },
    });
    const createdState = applyBuilderPatchTransactions(state, [
      {
        id: "create-global-assets-resource",
        payload: (created as BuilderRuntimeMutation).payload,
      },
    ]).state;
    expect(createdState.dataSources?.get("global-assets-data-source")).toEqual(
      expect.objectContaining({ scopeInstanceId: ROOT_INSTANCE_ID })
    );

    const updated = executeBuilderRuntimeOperation({
      id: "assetsResources.update",
      state: createdState,
      input: {
        resourceId: "global-assets-resource",
        values: { name: "Updated global assets" },
      },
      context,
    });

    expect(updated).toMatchObject({
      kind: "mutation",
      result: {
        resourceId: "global-assets-resource",
        dataSourceId: "global-assets-data-source",
      },
    });
  });

  test("replaces bounded fixed resource URLs without changing expressions", () => {
    const resource = state.resources.get("resource");
    if (resource === undefined) {
      throw new Error("Expected test resource");
    }
    const replaceState = {
      ...state,
      resources: new Map([
        [
          "resource",
          {
            ...resource,
            url: '"https://api.old.example.com/posts"',
          },
        ],
        [
          "dynamic-resource",
          {
            ...resource,
            id: "dynamic-resource",
            name: "Dynamic posts",
            url: "apiBase + '/posts'",
          },
        ],
      ]),
    } satisfies BuilderState;

    expect(
      executeBuilderRuntimeOperation({
        id: "resources.replaceText",
        state: replaceState,
        input: {
          find: "/posts",
          replace: "/articles",
          match: "substring",
          fields: ["url"],
          limit: 1,
        },
        context,
      })
    ).toMatchObject({
      kind: "mutation",
      result: {
        changedCount: 1,
        matchingFieldCount: 1,
        truncated: false,
        matches: [
          {
            resourceId: "resource",
            field: "url",
            before: "https://api.old.example.com/posts",
            after: "https://api.old.example.com/articles",
          },
        ],
      },
      payload: [
        {
          namespace: "resources",
          patches: [
            {
              op: "replace",
              path: ["resource", "url"],
              value: '"https://api.old.example.com/articles"',
            },
          ],
        },
      ],
    });
  });

  test("validates project settings and redirects through public operations", () => {
    expectRuntimeValidationError(
      "projectSettings.update",
      { meta: { contactEmail: "not-an-email" } },
      {
        code: "invalid_contact_email",
        path: ["meta", "contactEmail"],
        constraint: "comma_separated_email_addresses",
      }
    );

    expectRuntimeValidationError(
      "projectSettings.update",
      {
        meta: {
          auth: JSON.stringify({
            version: 1,
            routes: {
              private: {
                method: "basic",
                login: "admin",
                password: "secret",
              },
            },
          }),
        },
      },
      {
        code: "invalid_project_auth",
        path: ["meta", "auth"],
        constraint: "valid_webstudio_auth_json",
      }
    );

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "redirects.create",
        state,
        input: {
          old: "/old#fragment",
          new: "/other",
        },
        context,
      })
    ).toThrow("Redirect already exists");

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "redirects.setAll",
        state,
        input: {
          redirects: [
            { old: "/über", new: "/one" },
            { old: "/%C3%BCber", new: "/two" },
          ],
        },
        context,
      })
    ).toThrow('Duplicate redirect source "/%C3%BCber"');
  });

  test("validates breakpoint mutations through public operations", () => {
    expect(() =>
      executeBuilderRuntimeOperation({
        id: "breakpoints.create",
        state,
        input: {
          label: "Broken",
          minWidth: -1,
        },
        context,
      })
    ).toThrow();

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "breakpoints.update",
        state,
        input: {
          breakpointId: "base",
          values: { label: "New base" },
        },
        context,
      })
    ).toThrow("Base breakpoint cannot be updated");

    const breakpoints = new Map(state.breakpoints);
    for (let index = 0; index < 7; index += 1) {
      breakpoints.set(`extra-${index}`, {
        id: `extra-${index}`,
        label: `Extra ${index}`,
        minWidth: index + 1,
      });
    }

    expect(() =>
      executeBuilderRuntimeOperation({
        id: "breakpoints.create",
        state: { ...state, breakpoints },
        input: {
          label: "Overflow",
          minWidth: 1200,
        },
        context,
      })
    ).toThrow("Breakpoint limit reached");
  });
});

describe("builder runtime registry", () => {
  test("exposes complete metadata from executable runtime operations", () => {
    for (const operation of builderRuntimeOperations) {
      expect(operation.id).toMatch(/^[a-z]+[A-Za-z]*\.[a-z]+[A-Za-z]*$/);
      expect(operation.command).toMatch(/^[a-z][a-z-]+$/);
      expect(operation.client).toMatch(/^[a-z][A-Za-z]+$/);
      const metadata = getInputJsonSchemaMetadata(operation.inputJsonSchema);
      expect(metadata.inputFields).not.toContain("projectId");
      for (const field of Object.keys(metadata.inputFieldTypes)) {
        expect(metadata.inputFields).toContain(field);
      }

      if (operation.kind === "read") {
        expect(operation.writeNamespaces).toEqual([]);
        expect(operation.invalidatesNamespaces).toEqual([]);
        expect(operation.requiresConfirm).toBe(false);
      }

      if (operation.kind === "mutation") {
        expect(
          operation.writeNamespaces.length +
            operation.invalidatesNamespaces.length
        ).toBeGreaterThan(0);
      }
    }
  });

  test("publishes truthful inputs for asset and page-copy operations", () => {
    const addAssetOperation = getBuilderRuntimeOperation("assets.add");
    const addAssetSchema = toInputJsonSchemaObject(
      addAssetOperation.inputJsonSchema
    );
    const assetSchema = toInputJsonSchemaObject(
      addAssetSchema?.properties?.asset
    );
    expect(JSON.stringify(assetSchema)).not.toContain("projectId");

    const copyPageOperation = getBuilderRuntimeOperation("pages.copy");
    const copyPageSchema = toInputJsonSchemaObject(
      copyPageOperation.inputJsonSchema
    );
    expect(copyPageSchema?.required).toContain("sourceData");
    expectRuntimeValidationError(
      "pages.copy",
      { pageId: "home" },
      { path: ["sourceData"] }
    );
  });

  test("publishes Content Block replacement confirmation", () => {
    const operation = getBuilderRuntimeOperation("contentBlocks.connectSource");
    const schema = toInputJsonSchemaObject(operation.inputJsonSchema);
    const switchOperation = getBuilderRuntimeOperation(
      "contentBlocks.switchSource"
    );
    const switchSchema = toInputJsonSchemaObject(
      switchOperation.inputJsonSchema
    );

    expect(schema?.properties).toHaveProperty("confirmReplacement");
    expect(switchSchema?.properties).not.toHaveProperty("confirmReplacement");
    expect(schema?.properties?.renderScope).toHaveProperty("description");
    expect(schema?.properties?.variables).toHaveProperty("description");
  });

  test("keeps router adapter policy in runtime metadata", () => {
    for (const operation of builderRuntimeOperations) {
      expect(operation.requiresAssets).toBe(
        operation.readNamespaces.includes("assets") ||
          operation.writeNamespaces.includes("assets") ||
          operation.readNamespaces.includes("assetFolders") ||
          operation.writeNamespaces.includes("assetFolders")
      );
    }
    for (const operation of builderRuntimeOperations.filter((operation) =>
      isDestructiveRuntimeCommand(operation.command)
    )) {
      expect(operation.requiresConfirm, operation.command).toBe(true);
    }
    expect(getBuilderRuntimeOperation("folders.delete").requiresConfirm).toBe(
      true
    );
    expect(getBuilderRuntimeOperation("redirects.setAll").requiresConfirm).toBe(
      true
    );
    expect(
      getBuilderRuntimeOperation("styleSources.clearStyles").requiresConfirm
    ).toBe(true);
    expect(getBuilderRuntimeOperation("pages.create").requiresConfirm).toBe(
      false
    );
  });

  test("rejects client-supplied generated ids and hides generated id fields", () => {
    expect(runtimeGeneratedIdInput.safeParse(undefined).success).toBe(true);
    expect(runtimeGeneratedIdInput.safeParse("client-created-id").success).toBe(
      false
    );

    let generatedIdFieldCount = 0;

    for (const operation of builderRuntimeOperations) {
      const generatedIdPaths = getRuntimeGeneratedInputPaths(
        operation.inputSchema
      );
      if (generatedIdPaths.length === 0) {
        continue;
      }

      for (const path of generatedIdPaths) {
        generatedIdFieldCount += 1;
        if (path.length === 1) {
          expect(
            getInputJsonSchemaMetadata(operation.inputJsonSchema).inputFields
          ).not.toContain(path[0]);
        }
        let inputJsonSchema = operation.inputJsonSchema;
        for (const segment of path.slice(0, -1)) {
          const prefixItems = Array.isArray(inputJsonSchema.prefixItems)
            ? inputJsonSchema.prefixItems
            : undefined;
          inputJsonSchema =
            toInputJsonSchemaObject(
              segment === "*"
                ? (prefixItems?.[0] ?? inputJsonSchema.items)
                : inputJsonSchema.properties?.[segment]
            ) ?? {};
        }
        const hiddenField = path.at(-1);
        if (hiddenField !== undefined && hiddenField !== "*") {
          expect(hasDirectInputProperty(inputJsonSchema, hiddenField)).toBe(
            false
          );
        }
      }
    }

    expect(generatedIdFieldCount).toBeGreaterThan(0);
  });

  test("implements every cutover operation", () => {
    for (const manifest of builderRuntimeCutoverManifests) {
      for (const operationId of manifest.operationIds) {
        expect(getBuilderRuntimeOperation(operationId).id).toBe(operationId);
      }
    }
  });

  test("uses runtime context for ids in migrated mutations", () => {
    const duplicateWithDeterministicIds = () => {
      let nextId = 0;
      return executeBuilderRuntimeOperation({
        id: "pages.duplicate",
        state,
        input: {
          projectId: "project-1",
          pageId: "home",
          parentFolderId: "root",
        },
        context: {
          ...context,
          createId: () => `runtime-id-${++nextId}`,
        },
      });
    };

    expect(duplicateWithDeterministicIds()).toEqual(
      duplicateWithDeterministicIds()
    );
  });

  test("uses the default runtime context when none is provided", () => {
    const result = executeBuilderRuntimeOperation({
      id: "pages.create",
      state,
      input: {
        projectId: "project-1",
        name: "Generated Page",
        path: "/generated",
      },
    });

    expect(result).toMatchObject({
      kind: "mutation",
      payload: expect.arrayContaining([
        expect.objectContaining({ namespace: "pages" }),
      ]),
    });
  });

  test("validates every mutation input at the runtime boundary", () => {
    const invalidInputByOperation = new Map<string, unknown>([
      ["contentBlocks.connectSource", {}],
      ["contentBlocks.switchSource", {}],
      ["contentBlocks.disconnectSource", {}],
      ["contentBlocks.editSource", {}],
      ["contentBlocks.updateFrontmatter", {}],
      ["contentBlocks.migrateTemplateReferences", {}],
      ["pages.create", {}],
      ["pages.update", {}],
      ["pages.updateSettings", {}],
      ["pages.updateMarketplace", {}],
      ["pages.savePathInHistory", {}],
      ["pages.setHome", {}],
      ["projectSettings.update", { meta: "invalid" }],
      ["responseHeaders.set", {}],
      ["responseHeaders.delete", {}],
      ["projectSettings.updateMarketplaceProduct", {}],
      ["redirects.create", {}],
      ["redirects.update", {}],
      ["redirects.delete", {}],
      ["redirects.setAll", { redirects: {} }],
      ["breakpoints.create", {}],
      ["breakpoints.update", {}],
      ["breakpoints.delete", {}],
      ["pages.delete", {}],
      ["pages.duplicate", {}],
      ["pages.copy", {}],
      ["pageTemplates.create", {}],
      ["pageTemplates.update", {}],
      ["pageTemplates.delete", {}],
      ["pageTemplates.duplicate", {}],
      ["pageTemplates.reorder", {}],
      ["pageTemplates.createPage", {}],
      ["folders.create", {}],
      ["folders.update", {}],
      ["folders.delete", {}],
      ["folders.duplicate", {}],
      ["pageTransfer.insert", {}],
      ["pageTree.move", {}],
      ["pageTree.reparentOrphans", "invalid"],
      ["runtimeUi.integrate", {}],
      ["instances.insertComponent", { parentInstanceId: "body" }],
      ["instances.insertMdxText", { parentInstanceId: "body" }],
      ["instances.insertCollection", { parentInstanceId: "body" }],
      ["instances.insertFragment", { parentInstanceId: "body" }],
      ["slots.attach", {}],
      ["slots.extract", {}],
      ["instances.move", { moves: {} }],
      ["instances.reparent", {}],
      ["instances.fillGrid", {}],
      ["instances.wrap", {}],
      ["instances.convert", {}],
      ["instances.unwrap", {}],
      ["instances.clone", {}],
      ["instances.duplicateAfterItself", {}],
      ["instances.delete", { instanceIds: "heading" }],
      ["instances.deleteBySelector", {}],
      ["instances.updateProps", { updates: {} }],
      ["instances.replacePropText", {}],
      ["instances.deleteProps", { deletions: {} }],
      ["instances.bindProps", { bindings: {} }],
      ["instances.updateText", {}],
      ["instances.replaceText", {}],
      ["instances.setTextContent", { operation: "unknown" }],
      ["instances.updateTextTree", {}],
      ["instances.setTag", {}],
      ["instances.setLabel", {}],
      ["instances.setName", {}],
      ["styles.updateDeclarations", { updates: {} }],
      ["styles.deleteDeclarations", { deletions: {} }],
      ["styles.updateSelectedDeclarations", { updates: {} }],
      ["styles.deleteSelectedDeclarations", { deletions: {} }],
      ["styles.replaceValues", {}],
      ["designTokens.create", { tokens: {} }],
      ["designTokens.import", {}],
      ["designTokens.createAttached", { tokens: {}, instanceIds: [] }],
      ["designTokens.updateStyles", { designTokenId: "token", updates: {} }],
      ["designTokens.deleteStyles", { designTokenId: "token", deletions: {} }],
      ["designTokens.attach", { designTokenId: "token", instanceIds: {} }],
      ["designTokens.detach", { designTokenId: "token", instanceIds: {} }],
      ["designTokens.extract", { instanceIds: {}, name: "Token" }],
      ["styleSources.rename", {}],
      ["styleSources.delete", {}],
      ["styleSources.setLock", {}],
      ["styleSources.reorder", {}],
      ["styleSources.clearStyles", {}],
      ["styleSources.duplicate", {}],
      ["styleSources.convertLocalToToken", {}],
      ["cssVariables.define", { vars: [] }],
      ["cssVariables.delete", { names: "--color" }],
      ["cssVariables.rewriteRefs", { map: [] }],
      ["cssVariables.rename", {}],
      ["variables.create", {}],
      ["variables.update", {}],
      ["variables.delete", {}],
      ["variables.deleteUnused", []],
      ["assetsResources.create", {}],
      ["assetsResources.update", {}],
      ["resources.create", {}],
      ["resources.update", {}],
      ["resources.replaceText", {}],
      ["resources.upsert", {}],
      ["resources.upsertProp", {}],
      ["resources.delete", {}],
      ["assetFolders.create", {}],
      ["assetFolders.update", {}],
      ["assetFolders.delete", {}],
      ["assetFolders.duplicate", {}],
      ["assets.update", {}],
      ["assets.setImageDescriptions", {}],
      ["assets.add", {}],
      ["assets.duplicate", {}],
      ["assets.replace", {}],
      ["assets.delete", { assetIdsOrPrefixes: "asset" }],
    ]);

    expect(Array.from(invalidInputByOperation.keys())).toEqual(
      mutationOperationIds
    );

    for (const [operationId, input] of invalidInputByOperation) {
      expectRuntimeValidationError(operationId, input);
    }
  });

  test("returns actionable issues for semantic input relationships", () => {
    const cases: Array<[string, unknown, Partial<SemanticValidationIssue>]> = [
      [
        "projectSettings.update",
        {},
        {
          code: "empty_project_settings_update",
          path: [],
          constraint: "at_least_one_of:meta,compiler",
        },
      ],
      [
        "assets.update",
        { assetId: "asset", values: {} },
        {
          code: "empty_asset_update",
          path: ["values"],
          constraint: "at_least_one_property",
        },
      ],
      [
        "assets.setImageDescriptions",
        {
          updates: [
            { assetId: "asset", decorative: true },
            { assetId: "asset", decorative: true },
          ],
        },
        {
          code: "duplicate_asset_update",
          path: ["updates", "1", "assetId"],
          constraint: "unique_by:assetId",
        },
      ],
      [
        "resources.create",
        {
          exposeAsDataSource: true,
          resource: {
            name: "Posts",
            method: "get",
            url: "https://api.example.com/posts",
            headers: [],
          },
        },
        {
          code: "missing_resource_scope",
          path: ["scopeInstanceId"],
          constraint: "required_when:exposeAsDataSource=true",
        },
      ],
      [
        "instances.move",
        {
          moves: [
            {
              instanceId: "heading",
              parentInstanceId: "body",
              insertIndex: 0,
              position: "end",
            },
          ],
        },
        {
          code: "conflicting_move_position",
          path: ["moves", "0", "position"],
          constraint: "mutually_exclusive_with:insertIndex",
        },
      ],
    ];

    for (const [operationId, input, issue] of cases) {
      expectRuntimeValidationError(operationId, input, issue);
    }
  });

  test("validates internal runtime operation inputs without exposing them publicly", () => {
    expect(
      builderRuntimeOperations.map((operation) => operation.id)
    ).not.toContain("system.migrateLoadedData");
    expectRuntimeValidationError(
      "system.migrateLoadedData",
      { unexpected: true },
      { constraint: "recognized_keys_only" }
    );
  });

  test("does not mutate caller state across representative public mutation surfaces", async () => {
    const inputs = new Map<string, unknown>([
      ["pages.create", { projectId: "project-1", name: "Docs", path: "/docs" }],
      [
        "pages.duplicate",
        { projectId: "project-1", pageId: "home", parentFolderId: "root" },
      ],
      ["pages.update", { pageId: "home", values: { name: "Renamed Home" } }],
      ["pages.delete", { pageId: "post" }],
      [
        "folders.create",
        { name: "Docs", slug: "docs", parentFolderId: "root" },
      ],
      ["folders.delete", { folderId: "blog" }],
      [
        "pageTemplates.create",
        {
          name: "Article Template",
          title: '"Article Template"',
          meta: { description: '"Reusable article"' },
        },
      ],
      ["projectSettings.update", { meta: { siteName: "Updated project" } }],
      ["redirects.create", { old: "/legacy", new: "/new" }],
      ["breakpoints.create", { label: "Tablet", maxWidth: 768 }],
      [
        "instances.updateText",
        { instanceId: "heading", childIndex: 0, text: "Updated" },
      ],
      ["instances.delete", { instanceIds: ["heading"] }],
      [
        "instances.move",
        {
          moves: [
            { instanceId: "heading", parentInstanceId: "body", insertIndex: 0 },
          ],
        },
      ],
      [
        "instances.clone",
        { sourceInstanceId: "heading", targetParentInstanceId: "body" },
      ],
      [
        "instances.insertComponent",
        { parentInstanceId: "body", component: "ws:element", tag: "div" },
      ],
      [
        "runtimeUi.integrate",
        {
          ...createResourceCollectionIntegrationFixture().input,
          retainedBehavior: [],
        },
      ],
      [
        "instances.fillGrid",
        { parentInstanceId: "body", totalCells: 3, breakpointId: "base" },
      ],
      ["pageTree.reparentOrphans", {}],
      [
        "instances.duplicateAfterItself",
        { sourceInstanceId: "heading", parentInstanceId: "body" },
      ],
      ["instances.setLabel", { instanceId: "heading", label: "Updated hero" }],
      ["instances.setTag", { instanceId: "heading", tag: "h2" }],
      [
        "instances.updateProps",
        {
          updates: [
            {
              instanceId: "heading",
              name: "title",
              type: "string",
              value: "Updated title",
            },
          ],
        },
      ],
      [
        "instances.deleteProps",
        { deletions: [{ instanceId: "heading", name: "title" }] },
      ],
      [
        "styles.updateDeclarations",
        {
          updates: [
            {
              instanceId: "heading",
              property: "color",
              value: { type: "keyword", value: "green" },
            },
          ],
        },
      ],
      [
        "styles.deleteDeclarations",
        { deletions: [{ instanceId: "heading", property: "color" }] },
      ],
      [
        "designTokens.create",
        {
          tokens: [
            {
              name: "Accent",
              styles: { color: { type: "keyword", value: "green" } },
            },
          ],
        },
      ],
      [
        "variables.create",
        {
          scopeInstanceId: "heading",
          name: "Subtitle",
          value: { type: "string", value: "Hello" },
        },
      ],
      [
        "styleSources.rename",
        { styleSourceId: "token", name: "Updated Brand" },
      ],
      ["styleSources.setLock", { styleSourceId: "token", locked: true }],
      ["styleSources.clearStyles", { styleSourceId: "local" }],
      [
        "styleSources.duplicate",
        { instanceId: "heading", styleSourceId: "token" },
      ],
      [
        "designTokens.attach",
        { designTokenId: "token", instanceIds: ["heading"] },
      ],
      [
        "designTokens.detach",
        { designTokenId: "token", instanceIds: ["heading"] },
      ],
      [
        "cssVariables.define",
        { vars: { "--accent-color": { type: "keyword", value: "green" } } },
      ],
      [
        "cssVariables.rename",
        { oldName: "--brand-color", newName: "--main-color" },
      ],
      ["cssVariables.delete", { names: ["--brand-color"], force: true }],
      [
        "variables.update",
        {
          dataSourceId: "variable",
          values: { value: { type: "string", value: "Updated" } },
        },
      ],
      ["variables.delete", { dataSourceId: "variable" }],
      [
        "resources.update",
        { resourceId: "resource", values: { name: "Updated Posts" } },
      ],
      [
        "resources.create",
        {
          scopeInstanceId: "heading",
          resource: {
            name: "Users",
            method: "get",
            url: "https://api.example.com/users",
            headers: [],
            searchParams: [],
          },
        },
      ],
      [
        "assetsResources.create",
        { name: "All assets", scopeInstanceId: "heading" },
      ],
      ["resources.delete", { resourceId: "resource", force: true }],
      [
        "assetFolders.update",
        { folderId: "asset-folder", values: { name: "Updated Media" } },
      ],
      [
        "assets.update",
        {
          assetId: "asset",
          values: { filename: "Updated", description: "Updated description" },
        },
      ],
      [
        "assets.setImageDescriptions",
        {
          updates: [{ assetId: "asset", description: "Updated description" }],
        },
      ],
      ["assets.delete", { assetIdsOrPrefixes: ["asset"] }],
      ["assets.replace", { fromAssetId: "asset", toAssetId: "next" }],
      [
        "contentBlocks.migrateTemplateReferences",
        {
          assetIds: ["asset"],
          migration: { type: "rename", from: "Old", to: "New" },
        },
      ],
    ]);

    const immutabilityContext = {
      ...context,
      contentBlockApplication: {
        migrateTemplateReferences: async () => ({
          status: "complete" as const,
          migration: { type: "rename" as const, from: "Old", to: "New" },
          files: [],
          updateCount: 0,
          omissionCount: 0,
          changedFileCount: 0,
        }),
      } as unknown as ContentBlockApplication,
    };

    const mutationIds = new Set(mutationOperationIds);
    for (const manifest of builderRuntimeCutoverManifests) {
      const familyMutationIds = manifest.operationIds.filter((id) =>
        mutationIds.has(id)
      );
      if (familyMutationIds.length > 0) {
        expect(
          familyMutationIds.some((id) => inputs.has(id)),
          `${manifest.family} has no caller-state immutability fixture`
        ).toBe(true);
      }
    }

    for (const [id, input] of inputs) {
      const before = structuredClone(state);
      let nextId = 0;
      await executeBuilderRuntimeOperation({
        id,
        state,
        input,
        context: {
          ...immutabilityContext,
          createId: () => `runtime-id-${++nextId}`,
        },
      });
      expect(state).toEqual(before);
    }
  });
});