@nuxtseo/protocol 0.1.5 → 0.2.0

package/dist/v1/performance.js

@@ -1,5 +1,5 @@
 import { z as schema } from 'zod';
-import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1BooleanFlag, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
 export const performanceSiteParamsSchema = schema.strictObject({
     siteId: schema.string().min(1),
 });
@@ -190,9 +190,651 @@ export const sitePerformanceOverviewOperation = defineOperation({
             }],
     },
 });
+// ---------------------------------------------------------------------------
+// Field vitals (CrUX real-user p75) — the dataset the `crux_vitals` MCP tool
+// answers. Distinct from `page.performance` above, which is the stored
+// Lighthouse LAB overview (ADR-0129: a name names its dataset).
+// ---------------------------------------------------------------------------
+export const fieldVitalsQuerySchema = schema.strictObject({
+    url: schema.string().url().optional(),
+    formFactor: schema.enum(['PHONE', 'DESKTOP', 'ALL_FORM_FACTORS']).default('PHONE'),
+    view: schema.enum(['summary', 'trend']).default('summary'),
+});
+const fieldVitalRatingSchema = schema.enum(['good', 'needs-improvement', 'poor']);
+export const fieldVitalSummarySchema = defineResponseObject({
+    p75: schema.number().nullable(),
+    status: fieldVitalRatingSchema.nullable(),
+    deltaOverPeriod: schema.number().nullable(),
+}, {
+    p75: schema.number().nullable(),
+    status: fieldVitalRatingSchema.nullable(),
+    deltaOverPeriod: schema.number().nullable(),
+});
+export const fieldVitalPointSchema = defineResponseObject({ date: schema.string().min(1), p75: schema.number().nullable() }, { date: schema.string().min(1), p75: schema.number().nullable() });
+/**
+ * `available: false` is the "CrUX has no record for this target" answer, not an
+ * error: an origin under the CrUX traffic floor is a normal state and a caller
+ * should read `message` rather than retry.
+ */
+export const fieldVitalsDataSchema = defineResponseObject({
+    target: schema.string().min(1),
+    mode: schema.enum(['origin', 'url']),
+    formFactor: schema.enum(['PHONE', 'DESKTOP', 'ALL_FORM_FACTORS']),
+    view: schema.enum(['summary', 'trend']),
+    available: schema.boolean(),
+    message: schema.string().nullable(),
+    summary: schema.strictObject({
+        lcp: fieldVitalSummarySchema.producer,
+        inp: fieldVitalSummarySchema.producer,
+        cls: fieldVitalSummarySchema.producer,
+        overall: schema.enum(['pass', 'ni', 'fail']).nullable(),
+        asOf: schema.string().min(1).nullable(),
+    }).nullable(),
+    trend: schema.strictObject({
+        lcp: schema.array(fieldVitalPointSchema.producer),
+        inp: schema.array(fieldVitalPointSchema.producer),
+        cls: schema.array(fieldVitalPointSchema.producer),
+    }).nullable(),
+}, {
+    target: schema.string().min(1),
+    mode: schema.enum(['origin', 'url']),
+    formFactor: schema.enum(['PHONE', 'DESKTOP', 'ALL_FORM_FACTORS']),
+    view: schema.enum(['summary', 'trend']),
+    available: schema.boolean(),
+    message: schema.string().nullable(),
+    summary: schema.looseObject({
+        lcp: fieldVitalSummarySchema.client,
+        inp: fieldVitalSummarySchema.client,
+        cls: fieldVitalSummarySchema.client,
+        overall: schema.enum(['pass', 'ni', 'fail']).nullable(),
+        asOf: schema.string().min(1).nullable(),
+    }).nullable(),
+    trend: schema.looseObject({
+        lcp: schema.array(fieldVitalPointSchema.client),
+        inp: schema.array(fieldVitalPointSchema.client),
+        cls: schema.array(fieldVitalPointSchema.client),
+    }).nullable(),
+});
+export const fieldVitalsResponseSchema = defineSuccessEnvelope(fieldVitalsDataSchema);
+export const fieldVitalsOperation = defineOperation({
+    id: 'page.vitals',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/vitals',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['page:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: performanceSiteParamsSchema, query: fieldVitalsQuerySchema, headers: null, body: null },
+    responses: { 200: fieldVitalsResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: {
+        reads: [{ type: 'site.page', idFrom: 'params.siteId' }],
+        changes: [],
+    },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Get field Core Web Vitals',
+        description: 'Returns Core Web Vitals from CrUX real-user field data for the Site origin, or for one Page when url is given. The summary view returns the latest p75 and its change over the window. The trend view returns the 25-week p75 series. For lab scan scores use the Site performance overview. For the DOM element behind a failing vital use the field vitals findings.',
+        tags: ['Pages'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { formFactor: 'PHONE', view: 'summary' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            target: 'https://example.com',
+                            mode: 'origin',
+                            formFactor: 'PHONE',
+                            view: 'summary',
+                            available: true,
+                            message: null,
+                            summary: {
+                                lcp: { p75: 2400, status: 'needs-improvement', deltaOverPeriod: -150 },
+                                inp: { p75: 180, status: 'good', deltaOverPeriod: 10 },
+                                cls: { p75: 0.08, status: 'good', deltaOverPeriod: null },
+                                overall: 'ni',
+                                asOf: '2026-08-24',
+                            },
+                            trend: null,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const fieldVitalFindingsQuerySchema = schema.strictObject({
+    metrics: schema.union([
+        schema.array(schema.enum(['lcp', 'inp', 'cls'])),
+        schema.enum(['lcp', 'inp', 'cls']).transform(one => [one]),
+    ]).optional(),
+    onlyFailing: publicV1BooleanFlag(true),
+    limit: schema.coerce.number().int().min(1).max(50).default(20),
+    offset: schema.coerce.number().int().min(0).default(0),
+});
+export const fieldVitalFindingSchema = defineResponseObject({
+    metric: schema.enum(['lcp', 'inp', 'cls']),
+    severity: fieldVitalRatingSchema,
+    p75: schema.number().nullable(),
+    route: schema.string(),
+    selector: schema.string(),
+    estimatedViews: schema.number(),
+    fixPrompt: schema.string().min(1),
+}, {
+    metric: schema.enum(['lcp', 'inp', 'cls']),
+    severity: fieldVitalRatingSchema,
+    p75: schema.number().nullable(),
+    route: schema.string(),
+    selector: schema.string(),
+    estimatedViews: schema.number(),
+    fixPrompt: schema.string().min(1),
+});
+export const fieldVitalFindingsDataSchema = defineResponseObject({
+    source: schema.string().nullable(),
+    message: schema.string().nullable(),
+    findings: schema.array(fieldVitalFindingSchema.producer),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    offset: schema.number().int().nonnegative(),
+}, {
+    source: schema.string().nullable(),
+    message: schema.string().nullable(),
+    findings: schema.array(fieldVitalFindingSchema.client),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    offset: schema.number().int().nonnegative(),
+});
+export const fieldVitalFindingsResponseSchema = defineSuccessEnvelope(fieldVitalFindingsDataSchema);
+export const fieldVitalFindingsOperation = defineOperation({
+    id: 'page.vitals.findings',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/vitals/findings',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['page:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: performanceSiteParamsSchema, query: fieldVitalFindingsQuerySchema, headers: null, body: null },
+    responses: { 200: fieldVitalFindingsResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: {
+        reads: [{ type: 'site.page', idFrom: 'params.siteId' }],
+        changes: [],
+    },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'List field Core Web Vitals findings',
+        description: 'Returns each failing real-user vital attributed to the DOM element behind it, with the p75, the CSS selector, and a ready-to-apply fix prompt. It requires a connected Web Analytics provider. If no provider is connected, findings is empty and message says so.',
+        tags: ['Pages'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { onlyFailing: '1', limit: 20, offset: 0 } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            source: 'cloudflare',
+                            message: null,
+                            findings: [{
+                                    metric: 'lcp',
+                                    severity: 'poor',
+                                    p75: 4300,
+                                    route: '/blog',
+                                    selector: 'main > img.hero',
+                                    estimatedViews: 1840,
+                                    fixPrompt: 'The LCP element on /blog is main > img.hero at 4300ms.',
+                                }],
+                            total: 1,
+                            limit: 20,
+                            offset: 0,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+// ---------------------------------------------------------------------------
+// Lighthouse drill-downs. `page.performance` above answers the Site median.
+// These three answer the questions behind it: which Pages are monitored, which
+// Scans ran, and what one Scan actually found. Same reads as the
+// `lighthouse_audits` tool's scans / pages / scan_detail actions.
+// ---------------------------------------------------------------------------
+export const performanceScansQuerySchema = schema.strictObject({
+    limit: schema.coerce.number().int().min(1).max(100).default(25),
+});
+export const performanceScanParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+    scanId: schema.string().min(1),
+});
+const scanScoresShape = {
+    perf: nullableMetricSchema,
+    a11y: nullableMetricSchema,
+    bestPractices: nullableMetricSchema,
+    seo: nullableMetricSchema,
+};
+export const performanceScanSummarySchema = defineResponseObject({
+    id: schema.string().min(1),
+    url: schema.string().min(1),
+    strategy: schema.string().min(1),
+    status: schema.string().min(1),
+    trigger: schema.string().nullable(),
+    scores: schema.strictObject(scanScoresShape),
+    lcp: nullableMetricSchema,
+    tbt: nullableMetricSchema,
+    cls: nullableMetricSchema,
+    completedAt: schema.string().datetime().nullable(),
+    error: schema.string().nullable(),
+}, {
+    id: schema.string().min(1),
+    url: schema.string().min(1),
+    strategy: schema.string().min(1),
+    status: schema.string().min(1),
+    trigger: schema.string().nullable(),
+    scores: schema.looseObject(scanScoresShape),
+    lcp: nullableMetricSchema,
+    tbt: nullableMetricSchema,
+    cls: nullableMetricSchema,
+    completedAt: schema.string().datetime().nullable(),
+    error: schema.string().nullable(),
+});
+export const performanceScansDataSchema = defineResponseObject({
+    scans: schema.array(performanceScanSummarySchema.producer),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+}, {
+    scans: schema.array(performanceScanSummarySchema.client),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+});
+export const performanceScansResponseSchema = defineSuccessEnvelope(performanceScansDataSchema);
+export const performanceScansOperation = defineOperation({
+    id: 'page.performance.scans',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/performance/scans',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['page:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: performanceSiteParamsSchema, query: performanceScansQuerySchema, headers: null, body: null },
+    responses: { 200: performanceScansResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.page', idFrom: 'params.siteId' }], changes: [] },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'List Lighthouse Scans',
+        description: 'Returns retained Lighthouse Scans for the Site, newest first, with the scores and lab vitals each one recorded. A failed Scan carries its error. Use one Scan id with the Scan read for the failing checks behind a score.',
+        tags: ['Pages'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { limit: 25 } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            scans: [{
+                                    id: 'scan_01JXYZ',
+                                    url: 'https://example.com/',
+                                    strategy: 'mobile',
+                                    status: 'complete',
+                                    trigger: 'scheduled',
+                                    scores: { perf: 82, a11y: 96, bestPractices: 92, seo: 98 },
+                                    lcp: 2200,
+                                    tbt: 180,
+                                    cls: 0.08,
+                                    completedAt: '2026-08-10T01:00:00.000Z',
+                                    error: null,
+                                }],
+                            total: 1,
+                            limit: 25,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const monitoredPageSchema = defineResponseObject({
+    id: schema.string().min(1),
+    path: schema.string(),
+    source: schema.string().nullable(),
+    enabled: schema.boolean(),
+    lastScanAt: schema.string().datetime().nullable(),
+}, {
+    id: schema.string().min(1),
+    path: schema.string(),
+    source: schema.string().nullable(),
+    enabled: schema.boolean(),
+    lastScanAt: schema.string().datetime().nullable(),
+});
+export const monitoredPagesDataSchema = defineResponseObject({
+    pages: schema.array(monitoredPageSchema.producer),
+    total: schema.number().int().nonnegative(),
+}, {
+    pages: schema.array(monitoredPageSchema.client),
+    total: schema.number().int().nonnegative(),
+});
+export const monitoredPagesResponseSchema = defineSuccessEnvelope(monitoredPagesDataSchema);
+export const monitoredPagesOperation = defineOperation({
+    id: 'page.performance.pages',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/performance/pages',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['page:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: performanceSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: monitoredPagesResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.page', idFrom: 'params.siteId' }], changes: [] },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'List monitored Pages',
+        description: 'Returns the Pages this Site scans on a schedule, in display order, with the last time each one was scanned. Start a Scan for a new Page with the Page scan operation.',
+        tags: ['Pages'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            pages: [{ id: 'lhp_01JXYZ', path: '/', source: 'homepage', enabled: true, lastScanAt: '2026-08-10T01:00:00.000Z' }],
+                            total: 1,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+const scanElementSampleShape = {
+    selector: schema.string().nullable(),
+    snippet: schema.string().nullable(),
+    message: schema.string().nullable(),
+    explanation: schema.string().nullable(),
+    sourceUrl: schema.string().nullable(),
+};
+export const scanElementSampleSchema = defineResponseObject(scanElementSampleShape, scanElementSampleShape);
+export const scanFailingCheckSchema = defineResponseObject({
+    auditId: schema.string().min(1),
+    title: schema.string(),
+    severity: schema.string(),
+    description: schema.string().nullable(),
+    wcag: schema.array(schema.string()),
+    wcagLevel: schema.string().nullable(),
+    instanceCount: schema.number().int().nonnegative(),
+    elements: schema.array(scanElementSampleSchema.producer),
+    /** Elements that actually failed, when more than the sample above. */
+    elementsTotal: schema.number().int().nonnegative().nullable(),
+}, {
+    auditId: schema.string().min(1),
+    title: schema.string(),
+    severity: schema.string(),
+    description: schema.string().nullable(),
+    wcag: schema.array(schema.string()),
+    wcagLevel: schema.string().nullable(),
+    instanceCount: schema.number().int().nonnegative(),
+    elements: schema.array(scanElementSampleSchema.client),
+    elementsTotal: schema.number().int().nonnegative().nullable(),
+});
+export const scanPerformanceIssueSchema = defineResponseObject({
+    type: schema.string(),
+    subtype: schema.string().nullable(),
+    url: schema.string().nullable(),
+    wastedMs: nullableMetricSchema,
+    wastedBytes: nullableMetricSchema,
+}, {
+    type: schema.string(),
+    subtype: schema.string().nullable(),
+    url: schema.string().nullable(),
+    wastedMs: nullableMetricSchema,
+    wastedBytes: nullableMetricSchema,
+});
+export const scanCachePolicySchema = defineResponseObject({
+    url: schema.string().nullable(),
+    repeatVisitBytes: nullableMetricSchema,
+    cacheLifetimeMs: nullableMetricSchema,
+    totalBytes: nullableMetricSchema,
+    resourceType: schema.string().nullable(),
+    mimeType: schema.string().nullable(),
+    versioning: schema.enum(['fingerprinted', 'unknown']),
+}, {
+    url: schema.string().nullable(),
+    repeatVisitBytes: nullableMetricSchema,
+    cacheLifetimeMs: nullableMetricSchema,
+    totalBytes: nullableMetricSchema,
+    resourceType: schema.string().nullable(),
+    mimeType: schema.string().nullable(),
+    versioning: schema.enum(['fingerprinted', 'unknown']),
+});
+export const scanThirdPartySchema = defineResponseObject({
+    entity: schema.string().nullable(),
+    blockingTime: nullableMetricSchema,
+    mainThreadTime: nullableMetricSchema,
+    transferSize: nullableMetricSchema,
+}, {
+    entity: schema.string().nullable(),
+    blockingTime: nullableMetricSchema,
+    mainThreadTime: nullableMetricSchema,
+    transferSize: nullableMetricSchema,
+});
+const scanCoverageShape = {
+    perCheckElementCap: schema.number().int().positive(),
+    perScanCheckCap: schema.number().int().positive(),
+    accessibilityChecksTotal: schema.number().int().nonnegative(),
+    bestPracticesChecksTotal: schema.number().int().nonnegative(),
+    possiblyTruncated: schema.boolean(),
+};
+export const performanceScanDetailDataSchema = defineResponseObject({
+    id: schema.string().min(1),
+    url: schema.string().min(1),
+    strategy: schema.string().min(1),
+    status: schema.string().min(1),
+    scores: schema.strictObject(scanScoresShape),
+    lcp: nullableMetricSchema,
+    tbt: nullableMetricSchema,
+    cls: nullableMetricSchema,
+    fcp: nullableMetricSchema,
+    speedIndex: nullableMetricSchema,
+    ttfb: nullableMetricSchema,
+    completedAt: schema.string().datetime().nullable(),
+    performanceIssues: schema.array(scanPerformanceIssueSchema.producer),
+    cachePolicy: schema.array(scanCachePolicySchema.producer),
+    thirdParties: schema.array(scanThirdPartySchema.producer),
+    lcpElement: schema.strictObject({
+        selector: schema.string().nullable(),
+        elementType: schema.string().nullable(),
+        nodeLabel: schema.string().nullable(),
+    }).nullable(),
+    accessibility: schema.array(scanFailingCheckSchema.producer),
+    bestPractices: schema.array(scanFailingCheckSchema.producer),
+    coverage: schema.strictObject(scanCoverageShape),
+}, {
+    id: schema.string().min(1),
+    url: schema.string().min(1),
+    strategy: schema.string().min(1),
+    status: schema.string().min(1),
+    scores: schema.looseObject(scanScoresShape),
+    lcp: nullableMetricSchema,
+    tbt: nullableMetricSchema,
+    cls: nullableMetricSchema,
+    fcp: nullableMetricSchema,
+    speedIndex: nullableMetricSchema,
+    ttfb: nullableMetricSchema,
+    completedAt: schema.string().datetime().nullable(),
+    performanceIssues: schema.array(scanPerformanceIssueSchema.client),
+    cachePolicy: schema.array(scanCachePolicySchema.client),
+    thirdParties: schema.array(scanThirdPartySchema.client),
+    lcpElement: schema.looseObject({
+        selector: schema.string().nullable(),
+        elementType: schema.string().nullable(),
+        nodeLabel: schema.string().nullable(),
+    }).nullable(),
+    accessibility: schema.array(scanFailingCheckSchema.client),
+    bestPractices: schema.array(scanFailingCheckSchema.client),
+    coverage: schema.looseObject(scanCoverageShape),
+});
+export const performanceScanDetailResponseSchema = defineSuccessEnvelope(performanceScanDetailDataSchema);
+export const performanceScanDetailOperation = defineOperation({
+    id: 'page.performance.scan',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/performance/scans/{scanId}',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['page:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: performanceScanParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: performanceScanDetailResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.page', idFrom: 'params.siteId' }], changes: [] },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Get one Lighthouse Scan',
+        description: 'Returns one Scan with the evidence behind its scores: the wasteful assets, the repeat-visit cache policy, the third-party scripts, the LCP element, and every failing accessibility and best-practices check with the CSS selectors and DOM snippets that failed. Read coverage before quoting a total: elements and checks are both capped per Scan.',
+        tags: ['Pages'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ', scanId: 'scan_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            id: 'scan_01JXYZ',
+                            url: 'https://example.com/',
+                            strategy: 'mobile',
+                            status: 'complete',
+                            scores: { perf: 82, a11y: 96, bestPractices: 92, seo: 98 },
+                            lcp: 2200,
+                            tbt: 180,
+                            cls: 0.08,
+                            fcp: 1100,
+                            speedIndex: 2400,
+                            ttfb: 210,
+                            completedAt: '2026-08-10T01:00:00.000Z',
+                            performanceIssues: [],
+                            cachePolicy: [],
+                            thirdParties: [],
+                            lcpElement: { selector: 'main > img.hero', elementType: 'image', nodeLabel: 'Hero' },
+                            accessibility: [],
+                            bestPractices: [],
+                            coverage: {
+                                perCheckElementCap: 5,
+                                perScanCheckCap: 12,
+                                accessibilityChecksTotal: 0,
+                                bestPracticesChecksTotal: 0,
+                                possiblyTruncated: false,
+                            },
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
 export const performanceV1Registry = defineRegistry({
     feature: 'page',
     operations: {
         overview: sitePerformanceOverviewOperation,
+        vitals: fieldVitalsOperation,
+        vitalFindings: fieldVitalFindingsOperation,
+        scans: performanceScansOperation,
+        monitoredPages: monitoredPagesOperation,
+        scanDetail: performanceScanDetailOperation,
     },
 });