@pylonsync/react 0.3.316 → 0.3.318

package/dist/image-response.d.ts

@@ -0,0 +1,62 @@
+import type { ReactNode } from "react";
+/** A font for `ImageResponse`. Satori requires static TTF/OTF (not woff2,
+ *  not variable fonts) — a variable font crashes the parser. */
+export interface ImageResponseFont {
+    name: string;
+    data: ArrayBuffer | Buffer | Uint8Array;
+    weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+    style?: "normal" | "italic";
+}
+export interface ImageResponseOptions {
+    /** Output width in px. Default 1200 (the standard OG card width). */
+    width?: number;
+    /** Output height in px. Default 630 (1.91:1). */
+    height?: number;
+    /** Override/extra fonts. When omitted the framework's bundled Inter
+     *  (weights 400 + 600) is used. */
+    fonts?: ImageResponseFont[];
+    /** Response content type. Only "image/png" is produced today. */
+    contentType?: string;
+    /** Extra headers merged onto the image response (e.g. a custom
+     *  `Cache-Control`). The framework sets a sensible default otherwise. */
+    headers?: Record<string, string>;
+    /** Satori emoji/asset loader passthrough (`graphemeImages` /
+     *  `loadAdditionalAsset`) for rendering emoji or remote images. */
+    loadAdditionalAsset?: (code: string, text: string) => Promise<string> | string;
+}
+/**
+ * A response that renders a React element to an image (PNG), for the
+ * `opengraph-image.tsx` / `twitter-image.tsx` file convention — the Pylon
+ * equivalent of Next.js's `next/og` `ImageResponse`.
+ *
+ * Return one from an `opengraph-image` module's default export:
+ *
+ * ```tsx
+ * import { ImageResponse } from "@pylonsync/react";
+ * export const size = { width: 1200, height: 630 };
+ * export default function OG() {
+ *   return new ImageResponse(
+ *     <div style={{ width: "100%", height: "100%", display: "flex" }}>
+ *       Hello
+ *     </div>,
+ *     { ...size },
+ *   );
+ * }
+ * ```
+ *
+ * This is a thin holder: it captures the element + options and the SSR
+ * runtime does the Satori→resvg render server-side (so this package pulls
+ * in no image-rendering deps). Satori is flexbox-only — an element with
+ * more than one child must set `display: flex` (same rule as next/og).
+ */
+export declare class ImageResponse {
+    /** Brand for structural detection in the runtime (survives bundling and
+     *  cross-realm boundaries where `instanceof` would not). */
+    readonly __pylonImageResponse: true;
+    readonly element: ReactNode;
+    readonly options: ImageResponseOptions;
+    constructor(element: ReactNode, options?: ImageResponseOptions);
+}
+/** Structural check the runtime uses instead of `instanceof` (the user's
+ *  module and the runtime may load different copies of this class). */
+export declare function isImageResponse(v: unknown): v is ImageResponse;

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { Image } from "./Image";
 export type { ImageProps } from "./Image";
 export { Form } from "./Form";
 export type { FormProps } from "./Form";
+export { ImageResponse, isImageResponse } from "./image-response";
+export type { ImageResponseOptions, ImageResponseFont, } from "./image-response";
 export type { PageProps, PageAuth, ServerData, SsrResponse, SsrCookieOptions, Metadata, GenerateMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, RouteSegmentConfig, ErrorBoundaryProps, NotFoundProps, FormFields, FormDb, FormRequest, RouteHandler, RawRouteHandler, RawResponse, } from "./ssr";
 export { useRouter, useSearchParams, usePathname, useParams, useRouteSeed, useRouteData, redirect, notFound, NotFoundError, } from "./useRouter";
 export type { PylonRouter } from "./useRouter";

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.316",
+  "version": "0.3.318",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -13,8 +13,8 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.316",
-    "@pylonsync/sync": "0.3.316"
+    "@pylonsync/sdk": "0.3.318",
+    "@pylonsync/sync": "0.3.318"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/image-response.ts

@@ -0,0 +1,76 @@
+import type { ReactNode } from "react";
+
+/** A font for `ImageResponse`. Satori requires static TTF/OTF (not woff2,
+ *  not variable fonts) — a variable font crashes the parser. */
+export interface ImageResponseFont {
+  name: string;
+  data: ArrayBuffer | Buffer | Uint8Array;
+  weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+  style?: "normal" | "italic";
+}
+
+export interface ImageResponseOptions {
+  /** Output width in px. Default 1200 (the standard OG card width). */
+  width?: number;
+  /** Output height in px. Default 630 (1.91:1). */
+  height?: number;
+  /** Override/extra fonts. When omitted the framework's bundled Inter
+   *  (weights 400 + 600) is used. */
+  fonts?: ImageResponseFont[];
+  /** Response content type. Only "image/png" is produced today. */
+  contentType?: string;
+  /** Extra headers merged onto the image response (e.g. a custom
+   *  `Cache-Control`). The framework sets a sensible default otherwise. */
+  headers?: Record<string, string>;
+  /** Satori emoji/asset loader passthrough (`graphemeImages` /
+   *  `loadAdditionalAsset`) for rendering emoji or remote images. */
+  loadAdditionalAsset?: (code: string, text: string) => Promise<string> | string;
+}
+
+/**
+ * A response that renders a React element to an image (PNG), for the
+ * `opengraph-image.tsx` / `twitter-image.tsx` file convention — the Pylon
+ * equivalent of Next.js's `next/og` `ImageResponse`.
+ *
+ * Return one from an `opengraph-image` module's default export:
+ *
+ * ```tsx
+ * import { ImageResponse } from "@pylonsync/react";
+ * export const size = { width: 1200, height: 630 };
+ * export default function OG() {
+ *   return new ImageResponse(
+ *     <div style={{ width: "100%", height: "100%", display: "flex" }}>
+ *       Hello
+ *     </div>,
+ *     { ...size },
+ *   );
+ * }
+ * ```
+ *
+ * This is a thin holder: it captures the element + options and the SSR
+ * runtime does the Satori→resvg render server-side (so this package pulls
+ * in no image-rendering deps). Satori is flexbox-only — an element with
+ * more than one child must set `display: flex` (same rule as next/og).
+ */
+export class ImageResponse {
+  /** Brand for structural detection in the runtime (survives bundling and
+   *  cross-realm boundaries where `instanceof` would not). */
+  readonly __pylonImageResponse = true as const;
+  readonly element: ReactNode;
+  readonly options: ImageResponseOptions;
+
+  constructor(element: ReactNode, options: ImageResponseOptions = {}) {
+    this.element = element;
+    this.options = options;
+  }
+}
+
+/** Structural check the runtime uses instead of `instanceof` (the user's
+ *  module and the runtime may load different copies of this class). */
+export function isImageResponse(v: unknown): v is ImageResponse {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as { __pylonImageResponse?: unknown }).__pylonImageResponse === true
+  );
+}

package/src/index.ts

@@ -10,6 +10,15 @@ export type { ImageProps } from "./Image";
 export { Form } from "./Form";
 export type { FormProps } from "./Form";
 
+// Dynamic image generation for the `opengraph-image.tsx` / `twitter-image.tsx`
+// file convention (Next.js `next/og` parity). `ImageResponse` is a thin
+// holder — the SSR runtime does the Satori→resvg render server-side.
+export { ImageResponse, isImageResponse } from "./image-response";
+export type {
+  ImageResponseOptions,
+  ImageResponseFont,
+} from "./image-response";
+
 // SSR page-author types — the contract every `app/**/page.tsx` is handed
 // in props, plus `metadata` / `generateMetadata`. Type-only.
 export type {