@cloudhal/mcp-server 0.0.0-stage → 0.1.0

package/dist/src/render/types.d.ts

@@ -0,0 +1,89 @@
+/** The `render_page` contract: widths, check ids, options and results, the DevTools socket shapes. */
+/** The widths `render_page` renders at, and the viewport height used at each. */
+export declare const RENDER_WIDTHS: readonly [1440, 768, 390];
+export type RenderWidth = (typeof RENDER_WIDTHS)[number];
+export declare const VIEWPORT_HEIGHT: Record<RenderWidth, number>;
+/** A text socket to a browser's DevTools endpoint (browser-level, not a single page). */
+export interface CdpSocket {
+    send(message: string): void;
+    /** Called with each complete message. */
+    onMessage(listener: (message: string) => void): void;
+    onClose(listener: () => void): void;
+    close(): void;
+}
+/** A browser for one `render_page` call; `close` releases it. */
+export interface RenderSession {
+    open(url: string, viewport: {
+        width: number;
+        height: number;
+        scheme?: RenderScheme;
+        reducedMotion?: boolean;
+    }): Promise<RenderTab>;
+    close(): Promise<void>;
+}
+export interface RenderTab {
+    /** Evaluates an expression in the page, awaiting promises; the value comes back as JSON. */
+    evaluate<T>(expression: string): Promise<T>;
+    /** A JPEG of the viewport as it is now. */
+    screenshot(quality: number): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+/** Where `render_page` gets its browsers from. */
+export interface PageRenderer {
+    session(): Promise<RenderSession>;
+}
+/** One automatic check (RFC-0021 §4). `examples` name the section and component where known. */
+export interface RenderCheck {
+    id: RenderCheckId;
+    ok: boolean;
+    count: number;
+    examples: string[];
+    /** The widths it failed at. */
+    widths: number[];
+}
+export declare const RENDER_CHECK_IDS: readonly ["overflow-x", "img-alt", "img-broken", "heading-order", "contrast", "empty-section", "tap-target", "long-line", "input-label", "chart-empty", "reduced-motion", "motion-cls", "motion-budget", "flash", "skip-link", "landmarks", "header-contrast", "focus-obscured", "overlay-open", "carousel-label", "carousel-lcp", "carousel-focus", "carousel-autoplay", "image-fit"];
+export type RenderCheckId = (typeof RENDER_CHECK_IDS)[number];
+export interface RenderShot {
+    width: number;
+    /** The page's full height at this width. */
+    height: number;
+    /** The screenshots stop before the end of the page. */
+    truncated: boolean;
+    /** JPEGs, top to bottom, one viewport each. */
+    images: Uint8Array[];
+}
+export interface RenderResult {
+    shots: RenderShot[];
+    checks: RenderCheck[];
+}
+/** The `prefers-color-scheme` a page is rendered in (RFC-0023: sites with a dark or auto mode). */
+export declare const RENDER_SCHEMES: readonly ["light", "dark"];
+export type RenderScheme = (typeof RENDER_SCHEMES)[number];
+/**
+ * How the page may move while it renders (RFC-0024 §8): `static` (the default) and `reduce`
+ * render with `prefers-reduced-motion: reduce`, so screenshots show final states and the
+ * `reduced-motion` check runs; `full` lets every preset play, for `motion-cls`.
+ */
+export declare const RENDER_MOTIONS: readonly ["static", "reduce", "full"];
+export type RenderMotion = (typeof RENDER_MOTIONS)[number];
+export interface RenderOptions {
+    widths: readonly RenderWidth[];
+    /** Default light. */
+    scheme?: RenderScheme;
+    /** Default `static`. */
+    motion?: RenderMotion;
+    /**
+     * RFC-0024 §8: screenshots at this many evenly spaced scroll positions (at most 6), each after
+     * the page settles, in place of one per viewport, to show a scroll story or scroll effects.
+     */
+    frames?: number;
+    /** Screenshots down the page (up to `maxImages` viewports per width); otherwise the first one. */
+    fullPage: boolean;
+    maxImages?: number;
+    /** JPEG quality, 1–100. */
+    quality?: number;
+    timeoutMs?: number;
+}
+export declare class RenderError extends Error {
+    readonly name = "RenderError";
+}

package/dist/src/render/types.js

@@ -0,0 +1,140 @@
+/** The `render_page` contract: widths, check ids, options and results, the DevTools socket shapes. */
+
+/** The widths `render_page` renders at, and the viewport height used at each. */
+export const RENDER_WIDTHS = [1440, 768, 390]         ;
+                                                         
+export const VIEWPORT_HEIGHT                              = { 1440: 900, 768: 1024, 390: 844 };
+
+/** A text socket to a browser's DevTools endpoint (browser-level, not a single page). */
+                            
+                              
+                                           
+                                                       
+                                      
+                
+ 
+
+/** A browser for one `render_page` call; `close` releases it. */
+                                
+       
+                
+                                                                                                
+                        
+                         
+ 
+
+                            
+                                                                                              
+                                              
+                                             
+                                                   
+                         
+ 
+
+/** Where `render_page` gets its browsers from. */
+                               
+                                    
+ 
+
+/** One automatic check (RFC-0021 §4). `examples` name the section and component where known. */
+                              
+                    
+              
+                
+                     
+                                 
+                   
+ 
+
+export const RENDER_CHECK_IDS = [
+  "overflow-x",
+  "img-alt",
+  "img-broken",
+  "heading-order",
+  "contrast",
+  "empty-section",
+  "tap-target",
+  "long-line",
+  // RFC-0022 §2: a form control a reader cannot identify.
+  "input-label",
+  // RFC-0022 §3: a chart with no rows to draw.
+  "chart-empty",
+  // RFC-0024 §8: content hidden or moving for a reader who asked for reduced motion.
+  "reduced-motion",
+  // RFC-0024 §8: layout shift while the page loads and scrolls (reveals included).
+  "motion-cls",
+  // RFC-0024 §2: more scroll effects or scroll stories than a page should carry.
+  "motion-budget",
+  // RFC-0024 §8, WCAG 2.3.1: something that flashes more than three times a second.
+  "flash",
+  // RFC-0025 §4: the first thing Tab reaches skips to the main content.
+  "skip-link",
+  // RFC-0025 §4: one banner header, one main, one footer, and every menu named.
+  "landmarks",
+  // RFC-0025 §2: a transparent header's text against the band under it.
+  "header-contrast",
+  // RFC-0025 §4, WCAG 2.4.11: a sticky or fixed header covering what has focus.
+  "focus-obscured",
+  // RFC-0025 §3: each overlay opens from its trigger, takes focus, closes and gives focus back.
+  "overlay-open",
+  // RFC-0027: carousels and their slides are named (and not just "carousel").
+  "carousel-label",
+  // RFC-0027: a hero carousel's first slide loads first; the others wait.
+  "carousel-lcp",
+  // RFC-0027: Tab never lands in a hero slide out of view; the controls are working.
+  "carousel-focus",
+  // RFC-0027 27d: a playing carousel has its rotation control first; at most one plays per page.
+  "carousel-autoplay",
+  // RFC-0028: an image cropped hard by cover with no focal point to keep its subject in view.
+  "image-fit",
+]         ;
+                                                              
+
+                             
+                
+                                              
+                 
+                                                         
+                     
+                                                 
+                       
+ 
+
+                               
+                      
+                        
+ 
+
+/** The `prefers-color-scheme` a page is rendered in (RFC-0023: sites with a dark or auto mode). */
+export const RENDER_SCHEMES = ["light", "dark"]         ;
+                                                           
+/**
+ * How the page may move while it renders (RFC-0024 §8): `static` (the default) and `reduce`
+ * render with `prefers-reduced-motion: reduce`, so screenshots show final states and the
+ * `reduced-motion` check runs; `full` lets every preset play, for `motion-cls`.
+ */
+export const RENDER_MOTIONS = ["static", "reduce", "full"]         ;
+                                                           
+
+                                
+                                 
+                       
+                        
+                          
+                        
+     
+                                                                                                 
+                                                                                              
+     
+                  
+                                                                                                    
+                    
+                     
+                             
+                   
+                     
+ 
+
+export class RenderError extends Error {
+                    name = "RenderError";
+}

package/dist/src/render-tools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `render_page` (RFC-0021 §4): an agent looks at what it built. The page's draft opens through its
+ * preview link in a real browser at desktop, tablet and phone widths; the result is screenshots
+ * (one viewport each, so they stay readable) and automatic checks that name the section and
+ * component behind each problem. Read-only: nothing is stored, and the preview link expires.
+ */
+import { type ToolContext, type ToolDefinition } from "./common.js";
+type PreviewDoc = (args: Record<string, unknown>, ctx: ToolContext) => Promise<{
+    title: string;
+    path: string;
+    url: string | null;
+}>;
+export declare function renderTools(previewDoc: PreviewDoc): ToolDefinition[];
+export {};

package/dist/src/render-tools.js

@@ -0,0 +1,314 @@
+/**
+ * `render_page` (RFC-0021 §4): an agent looks at what it built. The page's draft opens through its
+ * preview link in a real browser at desktop, tablet and phone widths; the result is screenshots
+ * (one viewport each, so they stay readable) and automatic checks that name the section and
+ * component behind each problem. Read-only: nothing is stored, and the preview link expires.
+ */
+
+import {
+  id,
+  obj,
+                   
+                   
+                      
+  ToolError,
+} from "./common.js";
+import {
+  bytesToBase64,
+  RENDER_CHECK_IDS,
+  RENDER_MOTIONS,
+  RENDER_SCHEMES,
+  RENDER_WIDTHS,
+                   
+  RenderError,
+  RenderLimiter,
+                    
+                    
+                   
+  renderPage,
+} from "./render.js";
+
+                   
+                                
+                   
+                                                                  
+
+/** Shared by every server in this process (or Worker isolate) unless a deployment brings its own. */
+const SHARED_LIMITER = new RenderLimiter();
+
+                            
+              
+               
+                       
+                       
+                                                                                  
+                        
+                                                                                             
+                                                    
+ 
+
+const WHAT                                                    = {
+  "overflow-x": "scrolls sideways",
+  "img-alt": "images without alt text",
+  "img-broken": "images that did not load",
+  "heading-order": "heading levels",
+  contrast: "text contrast",
+  "empty-section": "empty sections",
+  "tap-target": "small tap targets",
+  "long-line": "long lines",
+  "input-label": "unlabelled inputs",
+  "chart-empty": "empty charts",
+  "reduced-motion": "motion under reduced motion",
+  "motion-cls": "layout shift",
+  "motion-budget": "too much motion",
+  flash: "flashing",
+  "skip-link": "skip link",
+  landmarks: "page landmarks",
+  "header-contrast": "transparent header contrast",
+  "focus-obscured": "focus under the sticky header",
+  "overlay-open": "overlays",
+  "carousel-label": "carousel names",
+  "carousel-lcp": "carousel image loading",
+  "carousel-focus": "carousel focus",
+  "carousel-autoplay": "carousel autoplay",
+  "image-fit": "image crops",
+};
+
+function summary(r                  )         {
+  const failed = r.checks.filter((c) => !c.ok);
+  return [
+    `Rendered ${r.path} (the draft) at ${r.widths.map((w) => `${w.width}`).join(", ")} px, ${r.scheme} scheme, motion ${r.motion}.`,
+    ...r.widths.map(
+      (w) =>
+        `${w.width} px: ${w.images} screenshot(s) of a ${w.height} px page${w.truncated ? " (truncated: the screenshots stop there; preview_page has the whole page as HTML)" : ""}.`,
+    ),
+    failed.length
+      ? `Checks: ${failed.length} of ${r.checks.length} found problems.`
+      : `Checks: all ${r.checks.length} passed.`,
+    ...failed.map(
+      (c) =>
+        `✗ ${c.id} (${WHAT[c.id]}): ${c.count} at ${c.widths.join(", ")} px\n${c.examples.map((e) => `  - ${e}`).join("\n")}`,
+    ),
+    ...(failed.length
+      ? [
+          "Fix what you can in the draft (examples name the section and component), render again, and tell the person about anything you leave.",
+        ]
+      : []),
+  ].join("\n");
+}
+
+/** The other scheme's contrast problems folded into the contrast check, each example marked. */
+function mergeContrast(
+  checks               ,
+  extra                        ,
+  scheme              ,
+)                {
+  const add = extra.find((c) => c.id === "contrast");
+  if (!add || add.ok) return checks;
+  return checks.map((c) =>
+    c.id === "contrast"
+      ? {
+          ...c,
+          ok: false,
+          count: c.count + add.count,
+          widths: [...new Set([...c.widths, ...add.widths])],
+          examples: [
+            ...c.examples,
+            ...add.examples.map((e) =>
+              e.startsWith("@") ? `${scheme} ${e}` : `${scheme} @${add.widths[0]}: ${e}`,
+            ),
+          ].slice(0, 8),
+        }
+      : c,
+  );
+}
+
+export function renderTools(previewDoc            )                   {
+  return [
+    {
+      name: "render_page",
+      title: "Render a page in a browser",
+      description:
+        "Look at a page's draft as people will see it: renders it in a real browser at desktop (1440), tablet (768) and phone (390) widths and returns screenshots plus automatic checks (sideways scrolling, alt text, broken images, heading order, text contrast, empty sections, tap targets, line length, motion under reduced motion, layout shift) that name the section and component behind each problem. Use it after building or changing a page and before asking a person to publish; fix what it finds and render again. Read-only. Rate-limited (about 10 a minute); when no browser is available, use preview_page.",
+      inputSchema: obj(
+        {
+          siteId: id,
+          pageId: id,
+          entryId: id,
+          widths: {
+            type: "array",
+            items: { type: "integer", enum: [...RENDER_WIDTHS] },
+            minItems: 1,
+            maxItems: 3,
+            uniqueItems: true,
+            description: "Default [1440, 390]",
+          },
+          fullPage: {
+            type: "boolean",
+            description: "Screenshots down the page, up to 4 per width (default true)",
+          },
+          frames: {
+            type: "integer",
+            minimum: 1,
+            maximum: 6,
+            description:
+              "Screenshots at this many evenly spaced scroll positions instead of one per viewport, with motion full unless set, to see a scroll story (Scrolly) or scroll effects (RFC-0024)",
+          },
+          motion: {
+            type: "string",
+            enum: [...RENDER_MOTIONS],
+            description:
+              "static (default): the reader asks for reduced motion, so screenshots show final states and the reduced-motion check runs; full: every motion preset plays, for the motion-cls check (RFC-0024).",
+          },
+          scheme: {
+            type: "string",
+            enum: [...RENDER_SCHEMES],
+            description:
+              "The reader's color scheme: light by default, dark for a site whose mode is dark. When the mode is dark or auto, text contrast is also checked in the other scheme (its examples are marked).",
+          },
+        },
+        ["siteId"],
+      ),
+      outputSchema: obj(
+        {
+          url: { type: "string" },
+          path: { type: "string" },
+          scheme: { type: "string", enum: [...RENDER_SCHEMES] },
+          motion: { type: "string", enum: [...RENDER_MOTIONS] },
+          widths: {
+            type: "array",
+            items: obj(
+              {
+                width: { type: "integer" },
+                height: { type: "integer" },
+                truncated: { type: "boolean" },
+                images: { type: "integer" },
+              },
+              ["width", "height", "truncated", "images"],
+            ),
+          },
+          checks: {
+            type: "array",
+            items: obj(
+              {
+                id: { type: "string", enum: [...RENDER_CHECK_IDS] },
+                ok: { type: "boolean" },
+                count: { type: "integer" },
+                examples: { type: "array", items: { type: "string" } },
+                widths: { type: "array", items: { type: "integer" } },
+              },
+              ["id", "ok", "count", "examples", "widths"],
+            ),
+          },
+        },
+        ["url", "path", "widths", "checks"],
+      ),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      scopes: ["preview:create"],
+      renderContent: (raw) => {
+        const { images = [], ...structured } = raw                    ;
+        const content                = [{ type: "text", text: summary(structured) }];
+        for (const shot of images) {
+          shot.jpegs.forEach((jpeg, i) => {
+            content.push({
+              type: "text",
+              text: `${shot.width} px, screenshot ${i + 1} of ${shot.jpegs.length}:`,
+            });
+            content.push({ type: "image", data: bytesToBase64(jpeg), mimeType: "image/jpeg" });
+          });
+        }
+        return { content, structured: structured                                       };
+      },
+      handler: async (a, ctx) => {
+        if (!a.pageId && !a.entryId) throw new ToolError("invalid", "pass pageId or entryId");
+        const doc = await previewDoc(a, ctx);
+        if (!ctx.render)
+          throw new ToolError(
+            "render_unavailable",
+            `this server has no browser for render_page; use preview_page${doc.url ? ` or open ${doc.url}` : ""}`,
+            { url: doc.url },
+          );
+        if (!doc.url)
+          throw new ToolError(
+            "render_unavailable",
+            "this page has no preview link to open (the site has no domain and no `cloudhal dev` is running); use preview_page",
+          );
+        const limiter = ctx.render.limiter ?? SHARED_LIMITER;
+        const refused = limiter.take(
+          ctx.principal.actor.id,
+          a.siteId          ,
+          ctx.now?.() ?? new Date(),
+        );
+        if (refused) throw new ToolError("render_limited", refused);
+        const widths = (
+          Array.isArray(a.widths) && a.widths.length ? a.widths : [1440, 390]
+        )                 ;
+        // RFC-0023: a dark site renders dark by default; a dark or automatic one also has its
+        // contrast checked in the other scheme, so a page cannot pass light and fail dark.
+        const mode = (await ctx.store.getSite(a.siteId          ))?.theme.config?.mode;
+        const scheme               =
+          a.scheme === "dark" || a.scheme === "light"
+            ? a.scheme
+            : mode === "dark"
+              ? "dark"
+              : "light";
+        const other               = scheme === "light" ? "dark" : "light";
+        const frames = Number.isInteger(a.frames)
+          ? Math.min(6, Math.max(1, a.frames          ))
+          : 0;
+        const motion               =
+          a.motion === "full" || a.motion === "reduce" || a.motion === "static"
+            ? a.motion
+            : frames
+              ? "full"
+              : "static";
+        const checkOther = mode === "auto" || (mode === "dark" && scheme === "light");
+        try {
+          const r = await renderPage(ctx.render.renderer, doc.url, {
+            widths,
+            fullPage: a.fullPage !== false,
+            scheme,
+            motion,
+            ...(frames ? { frames } : {}),
+            timeoutMs: ctx.render.timeoutMs ?? 20_000,
+          });
+          if (checkOther) {
+            const extra = await renderPage(ctx.render.renderer, doc.url, {
+              widths: [widths[0]               ],
+              fullPage: false,
+              scheme: other,
+              timeoutMs: ctx.render.timeoutMs ?? 20_000,
+            });
+            r.checks = mergeContrast(r.checks, extra.checks, other);
+          }
+          const result                   = {
+            url: doc.url,
+            path: doc.path,
+            scheme,
+            motion,
+            widths: r.shots.map((s) => ({
+              width: s.width,
+              height: s.height,
+              truncated: s.truncated,
+              images: s.images.length,
+            })),
+            checks: r.checks,
+            images: r.shots.map((s) => ({ width: s.width, jpegs: s.images })),
+          };
+          return result;
+        } catch (e) {
+          if (e instanceof RenderError)
+            throw new ToolError("render_failed", `${e.message}; use preview_page instead`, {
+              url: doc.url,
+            });
+          throw e;
+        }
+      },
+    },
+  ];
+}

package/dist/src/render.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Sight for agents (RFC-0021 §4): renders a page in a real browser at a few widths and returns
+ * screenshots plus automatic checks (overflow, alt text, broken images, heading order, contrast,
+ * empty sections, tap targets, line length). The browser is a DevTools socket: local Chrome under
+ * Node (`@cloudhal/cli`), Cloudflare Browser Rendering on Workers (`@cloudhal/cloudflare`). One
+ * small DevTools client serves both, so there is no browser library to bundle.
+ *
+ * Worker-safe: no Node imports.
+ */
+export { base64ToBytes, bytesToBase64, Cdp, cdpSession } from "./render/cdp.js";
+export { RENDER_CHECK_SCRIPT } from "./render/checks/index.js";
+export { RenderLimiter } from "./render/limiter.js";
+export { renderPage } from "./render/page.js";
+export { type CdpSocket, type PageRenderer, RENDER_CHECK_IDS, RENDER_MOTIONS, RENDER_SCHEMES, RENDER_WIDTHS, type RenderCheck, type RenderCheckId, RenderError, type RenderMotion, type RenderOptions, type RenderResult, type RenderScheme, type RenderSession, type RenderShot, type RenderTab, type RenderWidth, } from "./render/types.js";

package/dist/src/render.js

@@ -0,0 +1,33 @@
+/**
+ * Sight for agents (RFC-0021 §4): renders a page in a real browser at a few widths and returns
+ * screenshots plus automatic checks (overflow, alt text, broken images, heading order, contrast,
+ * empty sections, tap targets, line length). The browser is a DevTools socket: local Chrome under
+ * Node (`@cloudhal/cli`), Cloudflare Browser Rendering on Workers (`@cloudhal/cloudflare`). One
+ * small DevTools client serves both, so there is no browser library to bundle.
+ *
+ * Worker-safe: no Node imports.
+ */
+
+export { base64ToBytes, bytesToBase64, Cdp, cdpSession } from "./render/cdp.js";
+export { RENDER_CHECK_SCRIPT } from "./render/checks/index.js";
+export { RenderLimiter } from "./render/limiter.js";
+export { renderPage } from "./render/page.js";
+export {
+                 
+                    
+  RENDER_CHECK_IDS,
+  RENDER_MOTIONS,
+  RENDER_SCHEMES,
+  RENDER_WIDTHS,
+                   
+                     
+  RenderError,
+                    
+                     
+                    
+                    
+                     
+                  
+                 
+                   
+} from "./render/types.js";

package/dist/src/schedule-tools.d.ts

@@ -0,0 +1,2 @@
+import { type ToolDefinition } from "./common.js";
+export declare function scheduleTools(): ToolDefinition[];