@comet/mail-react 9.0.0-beta.3 → 9.0.0-beta.4

package/README.md

@@ -1,26 +1,53 @@
 # @comet/mail-react
 
-Utilities for building HTML emails with React and MJML.
+Single-package solution for building HTML emails with React and MJML. Consumers install only `@comet/mail-react` (plus `react`) — never `@faire/mjml-react` directly.
 
-## Spec-driven development with OpenSpec
+The package:
 
-This package uses [OpenSpec](https://github.com/Fission-AI/OpenSpec) for spec-driven development. Specs and change history live in `openspec/` and are committed to the repo.
+- re-exports all `@faire/mjml-react` MJML components (with prop types renamed to drop the `I` prefix);
+- extends some of them with extra props and features;
+- adds new components and utilities — block factories (`BlocksBlock`, `ListBlock`, `OneOfBlock`, `OptionalBlock`) for rendering Comet CMS block data, and a `css()` tagged template literal for IDE syntax highlighting.
 
-## Getting started
+Some components also ship in an `Html` variant for use inside MJML ending tags. These variants are additive — separate components alongside the `Mjml` versions, with their own API.
 
-- Run `./install.sh` from the project root to install dependencies and configure OpenSpec agent skills
-- Open the `packages/mail-react/` directory directly in the IDE, as OpenSpec does not currently support monorepos
+## Internal development
 
-## Suggested development workflow
+We extend `@faire/mjml-react` rather than fork it. A few rules keep that working:
 
-- Use `/opsx:explore` to think through ideas before proposing
-- Use `/opsx:propose` to propose a change, then commit the proposal
-- Use `/opsx:apply` to apply the change, then commit the result
-- Use `/opsx:archive` to archive the change and merge delta specs into the main specs, then commit
+- **Additive only.** A custom component must work everywhere the base did. Only add props — never remove or rename them, and don't require new providers or context. For theme access, prefer `useOptionalTheme()` over `useTheme()`.
+- **Wrap, don't reimplement.** Custom components delegate to `@faire/mjml-react`. Less to maintain, and we stay close to upstream behaviour.
+- **One export per name.** When we ship a custom version, it replaces the re-export. Consumers should never need to import from `@faire/mjml-react` directly.
 
-Minor fixes may skip this workflow if they do not create a gap between `openspec/specs/` and the code (e.g. changing a TSDoc comment).
+### Styling
 
-## Suggested review workflow
+- **Inline first.** Components must render correctly without any `<style>` block — clients like Outlook ignore them.
+- **Media queries** via `registerStyles` are progressive enhancement for mobile, where modern CSS (flex, grid) is fine. Use `theme.breakpoints.*.belowMediaQuery` (max-width queries) to target viewports below a breakpoint.
+- **BEM, camelCase blocks.** Block `mjmlSection`, element `mjmlSection__item`, modifier `mjmlSection--indented`. Every component applies its block class and merges any consumer-provided `className` with `clsx`: `clsx("mjmlSection", className)`.
 
-- A pull request should propose, apply, and archive a change in one go
-- Reviewers can then focus on the code changes and resulting spec, skimming the archived implementation details
+### File layout
+
+- **Location.** Custom components live in `src/components/<concern>/` (e.g. `src/components/section/MjmlSection.tsx`).
+- **File order.** Imports → types/props → component → styles. `registerStyles` calls go below the component.
+- **Module format.** ESM only (`type: module`). Use `.js` extensions in imports.
+- **TSDoc.** Short TSDoc — one line where possible — on exported components and props.
+
+### Storybook
+
+Every custom component has a story in `src/components/<concern>/__stories__/<Component>.stories.tsx`. Wrap non-section stories in `<MjmlSection indent>` to show a realistic indented layout.
+
+### Changesets
+
+A changeset describes what changes for the consumer. If the public API and end-user behavior are unchanged, no changeset is needed.
+
+When a custom component replaces a re-export, describe the change against the previous re-export — the added props, features, or behavior. Consumers don't need to know the internal component is new; they only see what's different in the API they use.
+
+## Living document
+
+If a change reverses a decision or shifts a convention recorded here, update this README in the same PR.
+
+## Consumer-facing companions
+
+- Docs: [docs/docs/3-features-modules/13-building-html-emails/](../../docs/docs/3-features-modules/13-building-html-emails/)
+- Agent skill: [skills/comet-mail-react/SKILL.md](../../skills/comet-mail-react/SKILL.md)
+
+When a change here affects usage patterns, component APIs, or styling conventions, update these alongside the library change.

package/lib/blocks/pixelImage/HtmlPixelImageBlock.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentProps, ReactNode } from "react";
+import type { PixelImageBlockBaseProps } from "./common.js";
+export type HtmlPixelImageBlockProps = Omit<ComponentProps<"img">, "src" | "width" | "height"> & PixelImageBlockBaseProps;
+/**
+ * Renders a pixel-image from the DAM as a raw `<img>` tag.
+ *
+ * Use within raw HTML context — HTML-only emails or
+ * [MJML ending tags](https://documentation.mjml.io/#ending-tags) like `MjmlRaw`.
+ * For MJML context, use `MjmlPixelImageBlock`.
+ */
+export declare function HtmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imgProps }: HtmlPixelImageBlockProps): ReactNode;

package/lib/blocks/pixelImage/HtmlPixelImageBlock.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from "clsx";
+import { registerStyles } from "../../styles/registerStyles.js";
+import { css } from "../../utils/css.js";
+import { usePixelImageBlockData } from "./usePixelImageBlockData.js";
+/**
+ * Renders a pixel-image from the DAM as a raw `<img>` tag.
+ *
+ * Use within raw HTML context — HTML-only emails or
+ * [MJML ending tags](https://documentation.mjml.io/#ending-tags) like `MjmlRaw`.
+ * For MJML context, use `MjmlPixelImageBlock`.
+ */
+export function HtmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imgProps }) {
+    const imageData = usePixelImageBlockData({ data, defaultRenderWidth: width, largestPossibleRenderWidth, aspectRatio });
+    if (!imageData) {
+        return null;
+    }
+    return (_jsx("img", { src: imageData.imageUrl, width: imageData.defaultRenderWidth, height: imageData.desktopImageHeight, alt: imageData.alt, title: imageData.title, className: clsx("htmlPixelImageBlock", className), ...imgProps }));
+}
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .htmlPixelImageBlock {
+                width: 100%;
+                height: auto;
+            }
+        }
+    `);

package/lib/blocks/pixelImage/MjmlPixelImageBlock.d.ts

@@ -0,0 +1,9 @@
+import { type IMjmlImageProps } from "@faire/mjml-react";
+import type { ReactNode } from "react";
+import type { PixelImageBlockBaseProps } from "./common.js";
+export type MjmlPixelImageBlockProps = Omit<IMjmlImageProps, "src" | "width" | "height"> & PixelImageBlockBaseProps;
+/**
+ * Renders a pixel-image from the DAM as `MjmlImage`. Must be placed within an
+ * `MjmlColumn`. For raw HTML context, use `HtmlPixelImageBlock`.
+ */
+export declare function MjmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imageProps }: MjmlPixelImageBlockProps): ReactNode;

package/lib/blocks/pixelImage/MjmlPixelImageBlock.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MjmlImage } from "@faire/mjml-react";
+import clsx from "clsx";
+import { registerStyles } from "../../styles/registerStyles.js";
+import { css } from "../../utils/css.js";
+import { usePixelImageBlockData } from "./usePixelImageBlockData.js";
+/**
+ * Renders a pixel-image from the DAM as `MjmlImage`. Must be placed within an
+ * `MjmlColumn`. For raw HTML context, use `HtmlPixelImageBlock`.
+ */
+export function MjmlPixelImageBlock({ data, width, largestPossibleRenderWidth, aspectRatio, className, ...imageProps }) {
+    const imageData = usePixelImageBlockData({ data, defaultRenderWidth: width, largestPossibleRenderWidth, aspectRatio });
+    if (!imageData) {
+        return null;
+    }
+    return (_jsx(MjmlImage, { src: imageData.imageUrl, width: imageData.defaultRenderWidth, height: imageData.desktopImageHeight, alt: imageData.alt, title: imageData.title, className: clsx("mjmlPixelImageBlock", className), ...imageProps }));
+}
+registerStyles((theme) => css `
+        ${theme.breakpoints.default.belowMediaQuery} {
+            .mjmlPixelImageBlock img {
+                height: auto !important;
+            }
+        }
+    `);

package/lib/blocks/pixelImage/__stories__/HtmlPixelImageBlock.stories.d.ts

@@ -0,0 +1,7 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { HtmlPixelImageBlock } from "../HtmlPixelImageBlock.js";
+type Story = StoryObj<typeof HtmlPixelImageBlock>;
+declare const config: Meta<typeof HtmlPixelImageBlock>;
+export default config;
+export declare const Default: Story;
+export declare const AspectRatioOverride: Story;

package/lib/blocks/pixelImage/__stories__/HtmlPixelImageBlock.stories.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn, MjmlRaw } from "@faire/mjml-react";
+import { MjmlMailRoot } from "../../../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../../../components/section/MjmlSection.js";
+import { HtmlPixelImageBlock } from "../HtmlPixelImageBlock.js";
+import { exampleBlockData } from "./exampleBlockData.js";
+const config = {
+    title: "Components/Blocks/HtmlPixelImageBlock",
+    component: HtmlPixelImageBlock,
+    tags: ["autodocs"],
+    parameters: {
+        mailRoot: false,
+        docs: {
+            description: {
+                component: "Renders a pixel-image from the DAM as a raw `<img>` tag, for use in HTML-only emails or inside MJML ending tags such as `MjmlRaw`.\n\n_Note: this story may fail to load the actual image when the API fixtures don't include the referenced DAM file._",
+            },
+        },
+    },
+    argTypes: {
+        data: { control: false },
+        aspectRatio: {
+            control: "select",
+            options: ["inherit", "16x9", "4x3", "3x2", "3x1", "2x1", "1x1", "1x2", "1x3", "2x3", "3x4", "9x16"],
+        },
+    },
+    args: {
+        data: exampleBlockData,
+        width: 600,
+    },
+};
+export default config;
+export const Default = {
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlRaw, { children: _jsx(HtmlPixelImageBlock, { ...args }) }) }) }) })),
+};
+export const AspectRatioOverride = {
+    parameters: {
+        docs: {
+            description: {
+                story: "Renders the same DAM image at its native aspect ratio and overridden to `16x9`, demonstrating how the `aspectRatio` prop reframes the rendered image without changing the source DAM record.",
+            },
+        },
+    },
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsxs(MjmlRaw, { children: [_jsx(HtmlPixelImageBlock, { ...args }), _jsx(HtmlPixelImageBlock, { ...args, aspectRatio: "16x9" })] }) }) }) })),
+};

package/lib/blocks/pixelImage/__stories__/MjmlPixelImageBlock.stories.d.ts

@@ -0,0 +1,7 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { MjmlPixelImageBlock } from "../MjmlPixelImageBlock.js";
+type Story = StoryObj<typeof MjmlPixelImageBlock>;
+declare const config: Meta<typeof MjmlPixelImageBlock>;
+export default config;
+export declare const Default: Story;
+export declare const AspectRatioOverride: Story;

package/lib/blocks/pixelImage/__stories__/MjmlPixelImageBlock.stories.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MjmlColumn } from "@faire/mjml-react";
+import { MjmlMailRoot } from "../../../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../../../components/section/MjmlSection.js";
+import { MjmlPixelImageBlock } from "../MjmlPixelImageBlock.js";
+import { exampleBlockData } from "./exampleBlockData.js";
+const config = {
+    title: "Components/Blocks/MjmlPixelImageBlock",
+    component: MjmlPixelImageBlock,
+    tags: ["autodocs"],
+    parameters: {
+        mailRoot: false,
+        docs: {
+            description: {
+                component: "Renders a pixel-image from the DAM as `MjmlImage`. Must be placed within an `MjmlColumn`.\n\n_Note: this story may fail to load the actual image when the API fixtures don't include the referenced DAM file._",
+            },
+        },
+    },
+    argTypes: {
+        data: { control: false },
+        aspectRatio: {
+            control: "select",
+            options: ["inherit", "16x9", "4x3", "3x2", "3x1", "2x1", "1x1", "1x2", "1x3", "2x3", "3x4", "9x16"],
+        },
+    },
+    args: {
+        data: exampleBlockData,
+        width: 600,
+    },
+};
+export default config;
+export const Default = {
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsx(MjmlColumn, { children: _jsx(MjmlPixelImageBlock, { ...args }) }) }) })),
+};
+export const AspectRatioOverride = {
+    parameters: {
+        docs: {
+            description: {
+                story: "Renders the same DAM image at its native aspect ratio and overridden to `16x9`, demonstrating how the `aspectRatio` prop reframes the rendered image without changing the source DAM record.",
+            },
+        },
+    },
+    render: (args) => (_jsx(MjmlMailRoot, { config: {
+            pixelImageBlock: {
+                validSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 2560, 3200, 3840],
+                baseUrl: "",
+            },
+        }, children: _jsx(MjmlSection, { indent: true, children: _jsxs(MjmlColumn, { children: [_jsx(MjmlPixelImageBlock, { ...args }), _jsx(MjmlPixelImageBlock, { ...args, aspectRatio: "16x9" })] }) }) })),
+};

package/lib/blocks/pixelImage/__stories__/exampleBlockData.d.ts

@@ -0,0 +1,2 @@
+import type { PixelImageBlockData } from "../../../blocks.generated.js";
+export declare const exampleBlockData: PixelImageBlockData;

package/lib/blocks/pixelImage/__stories__/exampleBlockData.js

@@ -0,0 +1,19 @@
+export const exampleBlockData = {
+    damFile: {
+        id: "example-image",
+        name: "example-image.jpg",
+        size: 1000000,
+        mimetype: "image/jpeg",
+        contentHash: "example-hash",
+        archived: false,
+        scope: { domain: "at" },
+        fileUrl: "https://picsum.photos/seed/comet-pixel-image/1000/1000",
+        image: {
+            width: 1000,
+            height: 1000,
+            cropArea: { focalPoint: "SMART" },
+            dominantColor: "#000000",
+        },
+    },
+    urlTemplate: "https://picsum.photos/seed/comet-pixel-image/$resizeWidth/$resizeHeight",
+};

package/lib/blocks/pixelImage/__tests__/usePixelImageBlockConfig.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/blocks/pixelImage/__tests__/usePixelImageBlockConfig.test.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ConfigProvider } from "../../../config/ConfigProvider.js";
+import { usePixelImageBlockConfig } from "../usePixelImageBlockConfig.js";
+function ConfigProbe() {
+    usePixelImageBlockConfig();
+    return null;
+}
+describe("usePixelImageBlockConfig", () => {
+    it("throws when config.pixelImageBlock is unset", () => {
+        expect(() => renderToStaticMarkup(_jsx(ConfigProbe, {}))).toThrowError(/`pixelImageBlock` must be set/);
+    });
+    it("error message points at MjmlMailRoot and ConfigProvider", () => {
+        expect(() => renderToStaticMarkup(_jsx(ConfigProbe, {}))).toThrowError(/MjmlMailRoot/);
+        expect(() => renderToStaticMarkup(_jsx(ConfigProbe, {}))).toThrowError(/ConfigProvider/);
+    });
+    it("does not throw when config.pixelImageBlock is provided", () => {
+        expect(() => renderToStaticMarkup(_jsx(ConfigProvider, { config: { pixelImageBlock: { validSizes: [640, 1280], baseUrl: "http://localhost:3000" } }, children: _jsx(ConfigProbe, {}) }))).not.toThrow();
+    });
+});

package/lib/blocks/pixelImage/__tests__/usePixelImageBlockData.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/blocks/pixelImage/__tests__/usePixelImageBlockData.test.js

@@ -0,0 +1,205 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ConfigProvider } from "../../../config/ConfigProvider.js";
+import { createTheme } from "../../../theme/createTheme.js";
+import { ThemeProvider } from "../../../theme/ThemeProvider.js";
+import { usePixelImageBlockData } from "../usePixelImageBlockData.js";
+function captureUsePixelImageData({ data, defaultRenderWidth, largestPossibleRenderWidth, aspectRatio, config }) {
+    const captured = { value: undefined };
+    function Probe() {
+        captured.value = usePixelImageBlockData({ data, defaultRenderWidth, largestPossibleRenderWidth, aspectRatio });
+        return null;
+    }
+    renderToStaticMarkup(_jsx(ThemeProvider, { theme: createTheme(), children: _jsx(ConfigProvider, { config: config, children: _jsx(Probe, {}) }) }));
+    if (captured.value === undefined) {
+        throw new Error("Probe did not run");
+    }
+    return captured.value;
+}
+function expectNonNull(value) {
+    if (value === null) {
+        throw new Error("Expected non-null result from usePixelImageBlockData");
+    }
+    return value;
+}
+const validSizes = [320, 640, 1280, 2048];
+const baseUrl = "http://localhost:3000";
+const config = { pixelImageBlock: { validSizes, baseUrl } };
+const smartUrlTemplate = "/dam/images/abc/resize:$resizeWidth:$resizeHeight/photo.jpg";
+const smartImageData = {
+    damFile: {
+        id: "id-1",
+        name: "photo.jpg",
+        size: 1000,
+        mimetype: "image/jpeg",
+        contentHash: "hash",
+        archived: false,
+        fileUrl: "/dam/files/id-1.jpg",
+        image: {
+            width: 4000,
+            height: 2000,
+            cropArea: { focalPoint: "SMART" },
+        },
+    },
+    urlTemplate: smartUrlTemplate,
+};
+describe("usePixelImageBlockData — width selection", () => {
+    it("picks the smallest validSizes entry >= defaultRenderWidth × 2", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, config }));
+        expect(result.imageUrl).toContain(":640:");
+    });
+    it("picks an exact validSizes match when present", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 320, config }));
+        expect(result.imageUrl).toContain(":640:");
+    });
+    it("falls back to the largest validSizes entry when none qualifies", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 2000, config }));
+        expect(result.imageUrl).toContain(":2048:");
+    });
+    it("uses largestPossibleRenderWidth × 2 when defaultRenderWidth equals largestPossibleRenderWidth", () => {
+        const result = expectNonNull(captureUsePixelImageData({
+            data: smartImageData,
+            defaultRenderWidth: 600,
+            largestPossibleRenderWidth: 600,
+            config,
+        }));
+        expect(result.imageUrl).toContain(":1200:");
+    });
+    it("defaults largestPossibleRenderWidth to theme.sizes.bodyWidth (600) and triggers DPR-2 fixed path at width 600", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 600, config }));
+        expect(result.imageUrl).toContain(":1200:");
+    });
+});
+describe("usePixelImageBlockData — URL prefixing", () => {
+    it("prefixes a relative URL with config.pixelImageBlock.baseUrl", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, config }));
+        expect(result.imageUrl.startsWith(`${baseUrl}/dam/images/abc/`)).toBe(true);
+    });
+    it("does not prefix an absolute URL", () => {
+        const absoluteData = {
+            ...smartImageData,
+            urlTemplate: "https://cdn.example.com/$resizeWidth/$resizeHeight/photo.jpg",
+        };
+        const result = expectNonNull(captureUsePixelImageData({ data: absoluteData, defaultRenderWidth: 200, config }));
+        expect(result.imageUrl.startsWith("https://cdn.example.com/")).toBe(true);
+        expect(result.imageUrl.includes(baseUrl)).toBe(false);
+    });
+});
+describe("usePixelImageBlockData — aspect ratio", () => {
+    it("uses the natural image aspect ratio for SMART crop areas", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, config }));
+        expect(result.desktopImageHeight).toBe(100);
+        expect(result.imageUrl).toContain(":640:320/");
+    });
+    it("derives aspect ratio from crop dimensions for non-SMART crop areas", () => {
+        const nonSmartData = {
+            damFile: {
+                id: "id-2",
+                name: "photo2.jpg",
+                size: 1000,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-2.jpg",
+                image: {
+                    width: 4000,
+                    height: 2000,
+                    cropArea: { focalPoint: "CENTER", width: 50, height: 100, x: 25, y: 0 },
+                },
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        const result = expectNonNull(captureUsePixelImageData({ data: nonSmartData, defaultRenderWidth: 200, config }));
+        expect(result.desktopImageHeight).toBe(200);
+        expect(result.imageUrl).toContain(":640:640/");
+    });
+    it("throws when crop dimensions are missing on a non-SMART crop area", () => {
+        const malformedData = {
+            damFile: {
+                id: "id-3",
+                name: "photo3.jpg",
+                size: 1000,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-3.jpg",
+                image: {
+                    width: 4000,
+                    height: 2000,
+                    cropArea: { focalPoint: "CENTER" },
+                },
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        expect(() => captureUsePixelImageData({ data: malformedData, defaultRenderWidth: 200, config })).toThrow(/Missing crop dimensions/);
+    });
+});
+describe("usePixelImageBlockData — aspectRatio override", () => {
+    it("uses a numeric aspectRatio in place of the cropArea-derived ratio", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: 16 / 9, config }));
+        expect(result.imageUrl).toContain(":640:360/");
+        expect(result.desktopImageHeight).toBe(113);
+    });
+    it.each([
+        ["WxH", "16x9"],
+        ["W:H", "16:9"],
+        ["W/H", "16/9"],
+    ])("parses string aspectRatio in %s form", (_label, value) => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: value, config }));
+        expect(result.imageUrl).toContain(":640:360/");
+        expect(result.desktopImageHeight).toBe(113);
+    });
+    it("treats a single-token string as `width / 1`", () => {
+        const result = expectNonNull(captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: "2", config }));
+        expect(result.imageUrl).toContain(":640:320/");
+        expect(result.desktopImageHeight).toBe(100);
+    });
+    it("overrides a non-SMART cropArea ratio", () => {
+        const nonSmartData = {
+            damFile: {
+                id: "id-override",
+                name: "photo.jpg",
+                size: 1000,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-override.jpg",
+                image: {
+                    width: 4000,
+                    height: 2000,
+                    cropArea: { focalPoint: "CENTER", width: 50, height: 100, x: 25, y: 0 },
+                },
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        const result = expectNonNull(captureUsePixelImageData({ data: nonSmartData, defaultRenderWidth: 200, aspectRatio: "16x9", config }));
+        expect(result.imageUrl).toContain(":640:360/");
+        expect(result.desktopImageHeight).toBe(113);
+    });
+    it("throws when the aspectRatio string is malformed", () => {
+        expect(() => captureUsePixelImageData({ data: smartImageData, defaultRenderWidth: 200, aspectRatio: "not-a-ratio", config })).toThrow(/An error occurred while parsing the aspect ratio: not-a-ratio/);
+    });
+});
+describe("usePixelImageBlockData — incomplete data", () => {
+    it("returns null when damFile is absent", () => {
+        const result = captureUsePixelImageData({ data: { urlTemplate: smartUrlTemplate }, defaultRenderWidth: 200, config });
+        expect(result).toBeNull();
+    });
+    it("returns null when damFile.image is absent", () => {
+        const noImageData = {
+            damFile: {
+                id: "id-4",
+                name: "no-image.jpg",
+                size: 0,
+                mimetype: "image/jpeg",
+                contentHash: "hash",
+                archived: false,
+                fileUrl: "/dam/files/id-4.jpg",
+            },
+            urlTemplate: smartUrlTemplate,
+        };
+        const result = captureUsePixelImageData({ data: noImageData, defaultRenderWidth: 200, config });
+        expect(result).toBeNull();
+    });
+});

package/lib/blocks/pixelImage/common.d.ts

@@ -0,0 +1,18 @@
+import type { PixelImageBlockData } from "../../blocks.generated.js";
+export type PixelImageBlockBaseProps = {
+    /** The block data to render. */
+    data: PixelImageBlockData;
+    /** Width at which the image is rendered, in the default/desktop breakpoint. */
+    width: number;
+    /**
+     * Largest possible width the image can be rendered at across breakpoints.
+     * Defaults to `theme.sizes.bodyWidth`. Use this when the image can stretch
+     * wider on a narrower breakpoint than its desktop render width.
+     */
+    largestPossibleRenderWidth?: number;
+    /**
+     * Aspect ratio for the rendered image.
+     * @example "16x9"
+     */
+    aspectRatio?: number | string;
+};

package/lib/blocks/pixelImage/common.js

@@ -0,0 +1 @@
+export {};

package/lib/blocks/pixelImage/usePixelImageBlockConfig.d.ts

@@ -0,0 +1,5 @@
+import { type PixelImageBlockConfig } from "../../config/ConfigProvider.js";
+/**
+ * Reads `config.pixelImageBlock` from the configuration context and returns it narrowed to non-null.
+ */
+export declare function usePixelImageBlockConfig(): PixelImageBlockConfig;

package/lib/blocks/pixelImage/usePixelImageBlockConfig.js

@@ -0,0 +1,11 @@
+import { useConfig } from "../../config/ConfigProvider.js";
+/**
+ * Reads `config.pixelImageBlock` from the configuration context and returns it narrowed to non-null.
+ */
+export function usePixelImageBlockConfig() {
+    const { pixelImageBlock } = useConfig();
+    if (!pixelImageBlock) {
+        throw new Error("`pixelImageBlock` must be set in `config` on `MjmlMailRoot` or `ConfigProvider` to use the pixel-image configuration.");
+    }
+    return pixelImageBlock;
+}

package/lib/blocks/pixelImage/usePixelImageBlockData.d.ts

@@ -0,0 +1,16 @@
+import type { PixelImageBlockData as PixelImageBlockSourceData } from "../../blocks.generated.js";
+interface UsePixelImageBlockDataProps {
+    data: PixelImageBlockSourceData;
+    defaultRenderWidth: number;
+    largestPossibleRenderWidth?: number;
+    aspectRatio?: number | string;
+}
+interface PixelImageBlockData {
+    imageUrl: string;
+    defaultRenderWidth: number;
+    desktopImageHeight: number;
+    alt: string | undefined;
+    title: string | undefined;
+}
+export declare function usePixelImageBlockData({ data: { damFile, cropArea, urlTemplate }, defaultRenderWidth, largestPossibleRenderWidth: passedLargestPossibleRenderWidth, aspectRatio: passedAspectRatio, }: UsePixelImageBlockDataProps): PixelImageBlockData | null;
+export {};

package/lib/blocks/pixelImage/usePixelImageBlockData.js

@@ -0,0 +1,80 @@
+import { useTheme } from "../../theme/ThemeProvider.js";
+import { usePixelImageBlockConfig } from "./usePixelImageBlockConfig.js";
+export function usePixelImageBlockData({ data: { damFile, cropArea, urlTemplate }, defaultRenderWidth, largestPossibleRenderWidth: passedLargestPossibleRenderWidth, aspectRatio: passedAspectRatio, }) {
+    const theme = useTheme();
+    const { validSizes, baseUrl } = usePixelImageBlockConfig();
+    const largestPossibleRenderWidth = passedLargestPossibleRenderWidth ?? theme.sizes.bodyWidth;
+    if (!damFile?.image) {
+        return null;
+    }
+    const usedCropArea = cropArea ?? damFile.image.cropArea;
+    const aspectRatio = passedAspectRatio !== undefined ? parseAspectRatio(passedAspectRatio) : calculateAspectRatio(damFile.image, usedCropArea);
+    const optimalWidth = getOptimalAllowedImageWidth(validSizes, defaultRenderWidth, largestPossibleRenderWidth);
+    const resolvedImageUrl = generateImageUrl(urlTemplate, optimalWidth, aspectRatio);
+    return {
+        imageUrl: isAbsoluteUrl(resolvedImageUrl) ? resolvedImageUrl : `${baseUrl}${resolvedImageUrl}`,
+        defaultRenderWidth,
+        desktopImageHeight: Math.round(defaultRenderWidth / aspectRatio),
+        alt: damFile.altText,
+        title: damFile.title,
+    };
+}
+function isAbsoluteUrl(url) {
+    return !url.startsWith("/");
+}
+function getOptimalAllowedImageWidth(validSizes, defaultRenderWidth, largestPossibleRenderWidth) {
+    const sortedValidSizes = validSizes.sort((a, b) => a - b);
+    let width = null;
+    const largestPossibleWidth = sortedValidSizes[sortedValidSizes.length - 1];
+    sortedValidSizes.forEach((validWidth) => {
+        if (defaultRenderWidth === largestPossibleRenderWidth) {
+            width = largestPossibleRenderWidth * 2;
+        }
+        else if (!width && validWidth >= defaultRenderWidth * 2) {
+            width = validWidth;
+        }
+    });
+    if (!width) {
+        return largestPossibleWidth;
+    }
+    return width;
+}
+// Copied from `calculateInheritAspectRatio` in `@comet/site-react` (`src/image/image.utils.ts`).
+// Keep in sync with the site-react version when changes are made.
+function calculateAspectRatio(image, cropArea) {
+    if (cropArea.focalPoint === "SMART") {
+        return image.width / image.height;
+    }
+    if (cropArea.width === undefined || cropArea.height === undefined) {
+        throw new Error("Missing crop dimensions");
+    }
+    return (cropArea.width * image.width) / (cropArea.height * image.height);
+}
+// Copied from `generateImageUrl` in `@comet/site-react` (`src/image/image.utils.ts`).
+// Keep in sync with the site-react version when changes are made.
+function generateImageUrl(urlTemplate, width, aspectRatio) {
+    return urlTemplate.replace("$resizeWidth", String(width)).replace("$resizeHeight", String(Math.ceil(width / aspectRatio)));
+}
+// Copied from `parseAspectRatio` in `@comet/site-react` (`src/image/image.utils.ts`).
+// Keep in sync with the site-react version when changes are made.
+function parseAspectRatio(value) {
+    let width;
+    let height;
+    if (typeof value === "string") {
+        [width, height] = value.split(/[x/:]/).map((part) => {
+            const parsed = parseFloat(part);
+            return isNaN(parsed) ? undefined : parsed;
+        });
+        if (width && !height) {
+            height = 1;
+        }
+    }
+    else {
+        width = value;
+        height = 1;
+    }
+    if (!width || !height) {
+        throw new Error(`An error occurred while parsing the aspect ratio: ${value}`);
+    }
+    return width / height;
+}

package/lib/components/mailRoot/MjmlMailRoot.d.ts

@@ -1,4 +1,5 @@
 import type { PropsWithChildren, ReactNode } from "react";
+import { type Config } from "../../config/ConfigProvider.js";
 import type { Theme } from "../../theme/themeTypes.js";
 type MjmlMailRootProps = PropsWithChildren<{
     /**
@@ -6,17 +7,25 @@ type MjmlMailRootProps = PropsWithChildren<{
      * (equivalent to `createTheme()`) is used.
      */
     theme?: Theme;
+    /** Extra content appended inside the built-in `<MjmlAttributes>`, after the default `<MjmlAll>`. */
+    attributes?: ReactNode;
+    /** Extra content appended inside `<MjmlHead>`, after the registered styles block. */
+    head?: ReactNode;
+    /**
+     * Configuration to make available to descendants via `useConfig`.
+     */
+    config?: Config;
 }>;
 /**
  * The root element for email templates. Renders the standard MJML email skeleton
  * (`<Mjml>`, `<MjmlHead>`, `<MjmlBody>`) with `<MjmlAll padding={0} />` as the
  * default attribute so all components start with zero padding.
  *
- * Accepts an optional `theme` prop that controls the body width and responsive
- * breakpoints. The theme is made available to all descendant components via
- * `useTheme()`.
+ * Accepts an optional `theme` prop that controls the body width and responsive breakpoints. The theme is made available to all descendant components via `useTheme()`.
+ *
+ * Accepts an optional `config` prop containing configuration. When provided, the value is made available to descendants via `useConfig()`.
  *
  * Direct children should be section-level components (e.g. `MjmlSection`).
  */
-export declare function MjmlMailRoot({ theme: themeProp, children }: MjmlMailRootProps): ReactNode;
+export declare function MjmlMailRoot({ theme: themeProp, attributes, head, config, children }: MjmlMailRootProps): ReactNode;
 export {};

package/lib/components/mailRoot/MjmlMailRoot.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Mjml, MjmlAll, MjmlAttributes, MjmlBody, MjmlBreakpoint, MjmlHead } from "@faire/mjml-react";
+import { ConfigProvider } from "../../config/ConfigProvider.js";
 import { Styles } from "../../styles/Styles.js";
 import { createTheme } from "../../theme/createTheme.js";
 import { ThemeProvider } from "../../theme/ThemeProvider.js";
@@ -8,13 +9,17 @@ import { ThemeProvider } from "../../theme/ThemeProvider.js";
  * (`<Mjml>`, `<MjmlHead>`, `<MjmlBody>`) with `<MjmlAll padding={0} />` as the
  * default attribute so all components start with zero padding.
  *
- * Accepts an optional `theme` prop that controls the body width and responsive
- * breakpoints. The theme is made available to all descendant components via
- * `useTheme()`.
+ * Accepts an optional `theme` prop that controls the body width and responsive breakpoints. The theme is made available to all descendant components via `useTheme()`.
+ *
+ * Accepts an optional `config` prop containing configuration. When provided, the value is made available to descendants via `useConfig()`.
  *
  * Direct children should be section-level components (e.g. `MjmlSection`).
  */
-export function MjmlMailRoot({ theme: themeProp, children }) {
+export function MjmlMailRoot({ theme: themeProp, attributes, head, config, children }) {
     const theme = themeProp ?? createTheme();
-    return (_jsx(ThemeProvider, { theme: theme, children: _jsxs(Mjml, { children: [_jsxs(MjmlHead, { children: [_jsx(MjmlAttributes, { children: _jsx(MjmlAll, { padding: "0", fontFamily: theme.text.fontFamily }) }), _jsx(MjmlBreakpoint, { width: `${theme.breakpoints.mobile.value}px` }), _jsx(Styles, {})] }), _jsx(MjmlBody, { width: theme.sizes.bodyWidth, backgroundColor: theme.colors.background.body, children: children })] }) }));
+    const content = (_jsx(ThemeProvider, { theme: theme, children: _jsxs(Mjml, { children: [_jsxs(MjmlHead, { children: [_jsxs(MjmlAttributes, { children: [_jsx(MjmlAll, { padding: "0", fontFamily: theme.text.fontFamily }), attributes] }), _jsx(MjmlBreakpoint, { width: `${theme.breakpoints.mobile.value}px` }), _jsx(Styles, {}), head] }), _jsx(MjmlBody, { width: theme.sizes.bodyWidth, backgroundColor: theme.colors.background.body, children: children })] }) }));
+    if (config) {
+        return _jsx(ConfigProvider, { config: config, children: content });
+    }
+    return content;
 }

package/lib/config/ConfigProvider.d.ts

@@ -0,0 +1,43 @@
+import { type PropsWithChildren, type ReactNode } from "react";
+export interface PixelImageBlockConfig {
+    /**
+     * Image widths supported by the API, used to pick a render width.
+     * Generally derived from `cometConfig.images.imageSizes` and `cometConfig.images.deviceSizes`.
+     */
+    validSizes: number[];
+    /**
+     * Origin to prefix relative image URLs with, e.g. `http://localhost:3000`.
+     */
+    baseUrl: string;
+}
+/**
+ * Configuration context for mails.
+ *
+ * Add custom keys via TypeScript interface declaration merging:
+ *
+ * ```ts
+ * declare module "@comet/mail-react" {
+ *     interface Config {
+ *         myKey?: { foo: string };
+ *     }
+ * }
+ * ```
+ */
+export interface Config {
+    /**
+     * Configuration consumed by `HtmlPixelImageBlock` and `MjmlPixelImageBlock`.
+     * Required when those components are rendered.
+     */
+    pixelImageBlock?: PixelImageBlockConfig;
+}
+/**
+ * Places a `Config` value into a React context, making it available to all
+ * descendants via `useConfig`.
+ */
+export declare function ConfigProvider({ config, children }: PropsWithChildren<{
+    config: Config;
+}>): ReactNode;
+/**
+ * Returns the nearest `Config` from context, defined by `ConfigProvider` or by the `config` prop on `MjmlMailRoot`.
+ */
+export declare function useConfig(): Config;

package/lib/config/ConfigProvider.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const ConfigContext = createContext({});
+/**
+ * Places a `Config` value into a React context, making it available to all
+ * descendants via `useConfig`.
+ */
+export function ConfigProvider({ config, children }) {
+    return _jsx(ConfigContext.Provider, { value: config, children: children });
+}
+/**
+ * Returns the nearest `Config` from context, defined by `ConfigProvider` or by the `config` prop on `MjmlMailRoot`.
+ */
+export function useConfig() {
+    return useContext(ConfigContext);
+}

package/lib/config/ConfigProvider.test.d.ts

@@ -0,0 +1,8 @@
+declare module "./ConfigProvider.js" {
+    interface Config {
+        testKey?: {
+            value: string;
+        };
+    }
+}
+export {};

package/lib/config/ConfigProvider.test.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MjmlColumn, MjmlText } from "@faire/mjml-react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { MjmlMailRoot } from "../components/mailRoot/MjmlMailRoot.js";
+import { MjmlSection } from "../components/section/MjmlSection.js";
+import { renderMailHtml } from "../server/renderMailHtml.js";
+import { ConfigProvider, useConfig } from "./ConfigProvider.js";
+function Probe() {
+    const config = useConfig();
+    return _jsx("span", { "data-config-value": config.testKey?.value ?? "no-config" });
+}
+describe("useConfig", () => {
+    it("returns an empty Config when no ConfigProvider is mounted", () => {
+        const html = renderToStaticMarkup(_jsx(Probe, {}));
+        expect(html).toContain('data-config-value="no-config"');
+    });
+});
+describe("MjmlMailRoot config integration", () => {
+    it("makes the config value available to descendants via useConfig", () => {
+        const { html, mjmlWarnings } = renderMailHtml(_jsx(MjmlMailRoot, { config: { testKey: { value: "from-root" } }, children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: _jsx(Probe, {}) }) }) }) }));
+        expect(mjmlWarnings).toEqual([]);
+        expect(html).toContain('data-config-value="from-root"');
+    });
+    it("does not shadow an outer ConfigProvider when no config prop is passed", () => {
+        const { html, mjmlWarnings } = renderMailHtml(_jsx(ConfigProvider, { config: { testKey: { value: "from-outer" } }, children: _jsx(MjmlMailRoot, { children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: _jsx(Probe, {}) }) }) }) }) }));
+        expect(mjmlWarnings).toEqual([]);
+        expect(html).toContain('data-config-value="from-outer"');
+    });
+});

package/lib/index.d.ts

@@ -4,6 +4,10 @@ export { OneOfBlock } from "./blocks/factories/OneOfBlock.js";
 export { OptionalBlock } from "./blocks/factories/OptionalBlock.js";
 export type { SupportedBlocks } from "./blocks/factories/types.js";
 export type { PropsWithData } from "./blocks/helpers/PropsWithData.js";
+export type { HtmlPixelImageBlockProps } from "./blocks/pixelImage/HtmlPixelImageBlock.js";
+export { HtmlPixelImageBlock } from "./blocks/pixelImage/HtmlPixelImageBlock.js";
+export type { MjmlPixelImageBlockProps } from "./blocks/pixelImage/MjmlPixelImageBlock.js";
+export { MjmlPixelImageBlock } from "./blocks/pixelImage/MjmlPixelImageBlock.js";
 export type { HtmlInlineLinkProps } from "./components/inlineLink/HtmlInlineLink.js";
 export { HtmlInlineLink } from "./components/inlineLink/HtmlInlineLink.js";
 export { MjmlMailRoot } from "./components/mailRoot/MjmlMailRoot.js";
@@ -15,6 +19,7 @@ export type { MjmlTextProps } from "./components/text/MjmlText.js";
 export { MjmlText } from "./components/text/MjmlText.js";
 export type { MjmlWrapperProps } from "./components/wrapper/MjmlWrapper.js";
 export { MjmlWrapper } from "./components/wrapper/MjmlWrapper.js";
+export { type Config, ConfigProvider, type PixelImageBlockConfig, useConfig } from "./config/ConfigProvider.js";
 export { registerStyles } from "./styles/registerStyles.js";
 export { createBreakpoint } from "./theme/createBreakpoint.js";
 export { createTheme } from "./theme/createTheme.js";

package/lib/index.js

@@ -2,12 +2,15 @@ export { BlocksBlock } from "./blocks/factories/BlocksBlock.js";
 export { ListBlock } from "./blocks/factories/ListBlock.js";
 export { OneOfBlock } from "./blocks/factories/OneOfBlock.js";
 export { OptionalBlock } from "./blocks/factories/OptionalBlock.js";
+export { HtmlPixelImageBlock } from "./blocks/pixelImage/HtmlPixelImageBlock.js";
+export { MjmlPixelImageBlock } from "./blocks/pixelImage/MjmlPixelImageBlock.js";
 export { HtmlInlineLink } from "./components/inlineLink/HtmlInlineLink.js";
 export { MjmlMailRoot } from "./components/mailRoot/MjmlMailRoot.js";
 export { MjmlSection } from "./components/section/MjmlSection.js";
 export { HtmlText } from "./components/text/HtmlText.js";
 export { MjmlText } from "./components/text/MjmlText.js";
 export { MjmlWrapper } from "./components/wrapper/MjmlWrapper.js";
+export { ConfigProvider, useConfig } from "./config/ConfigProvider.js";
 export { registerStyles } from "./styles/registerStyles.js";
 export { createBreakpoint } from "./theme/createBreakpoint.js";
 export { createTheme } from "./theme/createTheme.js";

package/lib/server/renderMailHtml.test.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { MjmlColumn, MjmlText } from "@faire/mjml-react";
+import { MjmlClass, MjmlColumn, MjmlText, MjmlTitle } from "@faire/mjml-react";
 import { describe, expect, it } from "vitest";
 import { MjmlMailRoot } from "../components/mailRoot/MjmlMailRoot.js";
 import { MjmlSection } from "../components/section/MjmlSection.js";
@@ -36,6 +36,15 @@ describe("server/renderMailHtml", () => {
         expect(html).toContain(".themed");
         expect(html).toContain("width: 600px");
     });
+    it("renders the head slot content inside <mj-head>", () => {
+        const titleText = "Welcome to Comet";
+        const { html } = renderMailHtml(_jsx(MjmlMailRoot, { head: _jsx(MjmlTitle, { children: titleText }), children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "Hello" }) }) }) }));
+        expect(html).toContain(`<title>${titleText}</title>`);
+    });
+    it("renders the attributes slot content inside <mj-attributes>", () => {
+        const { html } = renderMailHtml(_jsx(MjmlMailRoot, { attributes: _jsx(MjmlClass, { name: "cta", color: "#FF0000" }), children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { mjmlClass: "cta", children: "Hello" }) }) }) }));
+        expect(html).toContain("color:#FF0000");
+    });
     it("produces no MJML warnings for a valid component tree", () => {
         const { mjmlWarnings } = renderMailHtml(_jsx(MjmlMailRoot, { children: _jsx(MjmlSection, { children: _jsx(MjmlColumn, { children: _jsx(MjmlText, { children: "No warnings expected" }) }) }) }));
         expect(mjmlWarnings).toEqual([]);

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@comet/mail-react",
-  "version": "9.0.0-beta.3",
+  "version": "9.0.0-beta.4",
   "description": "Utilities for building HTML emails with React",
   "license": "BSD-2-Clause",
   "type": "module",
+  "repository": {
+    "directory": "packages/mail-react",
+    "type": "git",
+    "url": "https://github.com/vivid-planet/comet"
+  },
   "exports": {
     ".": "./lib/index.js",
     "./client": "./lib/client/index.js",
     "./server": "./lib/server/index.js",
     "./storybook": "./lib/storybook/index.js"
   },
+  "sideEffects": false,
   "files": [
     "lib/*"
   ],
@@ -20,25 +26,24 @@
     "mjml-browser": "^4.18.0"
   },
   "devDependencies": {
-    "@fission-ai/openspec": "^1.2.0",
     "@storybook/addon-docs": "^10.3.5",
     "@storybook/react-vite": "^10.3.5",
     "@types/mjml": "^4.7.4",
     "@types/mjml-browser": "^4.15.0",
-    "@types/react": "^19.2.10",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "chokidar-cli": "^3.0.0",
-    "eslint": "^9.39.2",
+    "eslint": "^9.39.4",
     "npm-run-all2": "^8.0.4",
     "prettier": "^3.6.2",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "rimraf": "^6.1.2",
     "storybook": "^10.3.5",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16",
-    "@comet/cli": "9.0.0-beta.3",
-    "@comet/eslint-config": "9.0.0-beta.3"
+    "@comet/cli": "9.0.0-beta.4",
+    "@comet/eslint-config": "9.0.0-beta.4"
   },
   "peerDependencies": {
     "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
@@ -71,7 +76,6 @@
     "lint:fix:prettier": "pnpm run lint:prettier --write",
     "lint:prettier": "pnpm exec prettier --check '*.{ts,js,json,md,yml,yaml}'",
     "lint:tsc": "tsc",
-    "openspec:install-skills": "openspec init --tools github-copilot,cursor,claude",
     "storybook": "storybook dev -p 6066 --no-open",
     "test": "vitest --run",
     "test:watch": "vitest --watch"