@pylonsync/react 0.3.223 → 0.3.224

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.223",
+  "version": "0.3.224",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,8 +12,8 @@
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.223",
-    "@pylonsync/sync": "0.3.223"
+    "@pylonsync/sdk": "0.3.224",
+    "@pylonsync/sync": "0.3.224"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/Image.tsx

@@ -0,0 +1,174 @@
+// Pylon's Next.js-style <Image>. Generates optimized + responsive
+// images via Pylon's built-in Rust image processor.
+//
+// SSR output: a plain <img> with src + srcset + sizes pointing at
+// `/_pylon/image?src=<your-src>&w=<width>&q=<quality>`. The Rust
+// handler decodes, resizes with SIMD (fast_image_resize), and
+// re-encodes with mozjpeg / libwebp on the fly, then caches the
+// result by content hash so the second request is a static-file
+// serve.
+//
+// What it does for you:
+//   - Multiple widths in `srcset` so the browser picks the smallest
+//     candidate for the viewport DPR.
+//   - `sizes="100vw"` default — override for tighter layouts.
+//   - `loading="lazy"` + `decoding="async"` by default (override
+//     with `priority` for above-the-fold).
+//   - `width` + `height` attrs locked to the explicit props so the
+//     browser reserves space before paint (no CLS).
+//
+// What it doesn't do (Phase 2):
+//   - No automatic blur placeholder. Pass `placeholder="<color>"` or
+//     `placeholder={dataUri}` if you want one.
+//   - No remote allowlist enforcement client-side — the server
+//     refuses unknown hosts per `PYLON_IMAGE_REMOTE_ALLOWLIST`.
+//   - No AVIF (server only emits WebP / JPEG / PNG today).
+
+import React from "react";
+
+export interface ImageProps
+  extends Omit<
+    React.ImgHTMLAttributes<HTMLImageElement>,
+    "src" | "width" | "height" | "loading" | "srcSet"
+  > {
+  /** Source URL — site-relative (`/foo.jpg`) or http(s) (allowlisted via env). */
+  src: string;
+  /** Intrinsic width in CSS px (used for aspect ratio + the 1x candidate). */
+  width: number;
+  /** Intrinsic height in CSS px. */
+  height: number;
+  /** Required alt text. Pass `""` for purely decorative images. */
+  alt: string;
+  /**
+   * JPEG/WebP quality 1..=100. Default 75 — matches Next.js.
+   * PNG ignores it (lossless).
+   */
+  quality?: number;
+  /**
+   * Override the candidate widths used in `srcset`. By default we
+   * emit 1x and 2x of `width`, capped at 3840px.
+   */
+  widths?: number[];
+  /**
+   * `<img sizes>` attribute. Default `100vw` — change to match the
+   * container width so the browser picks the smallest srcset
+   * candidate that fits. Example: `(max-width: 768px) 100vw, 50vw`.
+   */
+  sizes?: string;
+  /** Skip lazy-loading + bump fetch priority. Use for above-the-fold hero images. */
+  priority?: boolean;
+  /**
+   * Skip the Pylon optimizer and render `src` directly. Useful for
+   * SVGs (the optimizer rejects them as a security precaution),
+   * animated GIFs, or formats Pylon doesn't process. The browser
+   * still gets `width`/`height` for layout stability, but there's
+   * no `srcset` and no caching beyond whatever the source URL
+   * declares.
+   */
+  unoptimized?: boolean;
+}
+
+const DEFAULT_QUALITY = 75;
+const MAX_WIDTH = 3840;
+
+/**
+ * Default srcset widths — must match (be a subset of) the server's
+ * `PYLON_IMAGE_DEVICE_SIZES + PYLON_IMAGE_IMAGE_SIZES`. The server
+ * rejects requests for widths outside its allowlist (cache-fill
+ * DoS protection), so the React component has to stay in lock-step.
+ *
+ * If you customize the server's allowed widths, pass `widths={...}`
+ * on each `<Image>` (or wrap with your own component) to make sure
+ * the React-side candidates land in your custom set.
+ */
+const DEFAULT_WIDTHS = [
+  16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840,
+];
+
+/**
+ * Build the optimized URL for a given width / quality. The server
+ * picks the output format from the request's Accept header
+ * (WebP > JPEG); explicit `format=` could be added later.
+ */
+function optimizedUrl(src: string, width: number, quality: number): string {
+  const w = Math.min(Math.max(Math.round(width), 32), MAX_WIDTH);
+  const q = Math.min(Math.max(quality, 1), 100);
+  return `/_pylon/image?src=${encodeURIComponent(src)}&w=${w}&q=${q}`;
+}
+
+export function Image({
+  src,
+  width,
+  height,
+  alt,
+  quality = DEFAULT_QUALITY,
+  widths,
+  sizes = "100vw",
+  priority = false,
+  unoptimized = false,
+  className,
+  style,
+  ...rest
+}: ImageProps) {
+  // Bypass route — render the source directly. No srcset, no
+  // optimizer round-trip. Width/height still set for layout.
+  if (unoptimized) {
+    return (
+      <img
+        src={src}
+        width={width}
+        height={height}
+        alt={alt}
+        loading={priority ? "eager" : "lazy"}
+        {...({ fetchPriority: priority ? "high" : "auto" } as Record<string, string>)}
+        decoding="async"
+        className={className}
+        style={style}
+        {...rest}
+      />
+    );
+  }
+
+  // Candidate widths: explicit list, else default ladder filtered
+  // to "smallest that satisfies 1x" through "smallest that
+  // satisfies 2x", picked from DEFAULT_WIDTHS. Picking from the
+  // ladder (rather than [width, width*2]) keeps URLs in the
+  // server's allowed-widths set so we never get back a 400.
+  const candidates = (() => {
+    if (widths && widths.length > 0) {
+      return Array.from(new Set(widths.map((w) => Math.round(w)))).sort(
+        (a, b) => a - b,
+      );
+    }
+    const oneX = DEFAULT_WIDTHS.find((w) => w >= width) ?? MAX_WIDTH;
+    const targetTwoX = Math.min(width * 2, MAX_WIDTH);
+    const twoX = DEFAULT_WIDTHS.find((w) => w >= targetTwoX) ?? MAX_WIDTH;
+    return Array.from(new Set([oneX, twoX])).sort((a, b) => a - b);
+  })();
+
+  const baseSrc = optimizedUrl(src, candidates[candidates.length - 1], quality);
+  const srcSet = candidates
+    .map((w) => `${optimizedUrl(src, w, quality)} ${w}w`)
+    .join(", ");
+
+  return (
+    <img
+      src={baseSrc}
+      srcSet={srcSet}
+      sizes={sizes}
+      width={width}
+      height={height}
+      alt={alt}
+      loading={priority ? "eager" : "lazy"}
+      // React 19 uses the camelCase `fetchPriority`; older React
+      // emits `fetchpriority`. Both serialize to the same HTML
+      // attribute. We cast to bypass the typings since the prop
+      // is still marked experimental on @types/react.
+      {...({ fetchPriority: priority ? "high" : "auto" } as Record<string, string>)}
+      decoding="async"
+      className={className}
+      style={style}
+      {...rest}
+    />
+  );
+}

package/src/Link.tsx

@@ -0,0 +1,119 @@
+// Pylon's Next.js-style <Link>. SSR-safe (renders <a> with no JS),
+// client-side enhanced for instant navigation + prefetch.
+//
+// Behavior on the client (post-hydration):
+//   - Renders <a href data-pylon-link>. The runtime's global click
+//     handler intercepts the click and calls `__pylon.navigate(href)`,
+//     which fetches the new SSR HTML, dynamic-imports the matching
+//     route entry, and re-renders the React root in place. Layouts
+//     that match across the two routes survive reconciliation, so
+//     their state persists.
+//   - Prefetches on viewport entry (IntersectionObserver) by default.
+//     The runtime injects `<link rel=prefetch>` for the HTML and
+//     `<link rel=modulepreload>` for the shared chunks the user
+//     will need.
+//   - Hover/touch escalation: if the link isn't in the viewport
+//     long enough, hovering still triggers prefetch.
+//   - Modifier keys (cmd/ctrl/shift/alt) or middle-click fall
+//     through to the browser's default behavior (open in new tab,
+//     etc.) — matches Next.js semantics.
+//
+// SSR: with no JS or before hydration, this is just an <a href>, so
+// the link works regardless. Progressive enhancement.
+//
+// Disable client-side nav for a specific link with `prefetch={false}`
+// (HTML still prefetches) or by setting `target="_blank"`.
+
+import React, { useEffect, useRef } from "react";
+
+declare global {
+  interface Window {
+    __pylon?: {
+      prefetch: (href: string) => Promise<void>;
+      navigate: (href: string, opts?: { push?: boolean }) => Promise<void>;
+    };
+  }
+}
+
+export interface LinkProps
+  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  /** Destination path. Same-origin paths get client-side nav; off-origin paths render as plain <a>. */
+  href: string;
+  /**
+   * Prefetch the destination on viewport entry. Default true.
+   * Set `false` to skip prefetch (useful for links the user
+   * is unlikely to follow — pagination tail, etc.).
+   */
+  prefetch?: boolean;
+  children?: React.ReactNode;
+}
+
+export function Link({
+  href,
+  prefetch = true,
+  children,
+  ...rest
+}: LinkProps) {
+  const ref = useRef<HTMLAnchorElement>(null);
+
+  useEffect(() => {
+    if (!prefetch || !ref.current) return;
+    if (typeof window === "undefined") return;
+    // Don't prefetch off-origin / hash-only / non-HTTP links.
+    if (
+      href.startsWith("http://") ||
+      href.startsWith("https://") ||
+      href.startsWith("//") ||
+      href.startsWith("#") ||
+      href.startsWith("mailto:") ||
+      href.startsWith("tel:")
+    ) {
+      return;
+    }
+
+    const el = ref.current;
+    let prefetched = false;
+    const doPrefetch = () => {
+      if (prefetched) return;
+      prefetched = true;
+      window.__pylon?.prefetch(href);
+    };
+
+    let io: IntersectionObserver | null = null;
+    if (typeof IntersectionObserver !== "undefined") {
+      io = new IntersectionObserver(
+        (entries) => {
+          for (const e of entries) {
+            if (e.isIntersecting) {
+              doPrefetch();
+              io?.disconnect();
+            }
+          }
+        },
+        { rootMargin: "256px" },
+      );
+      io.observe(el);
+    }
+
+    const onHover = () => doPrefetch();
+    el.addEventListener("mouseenter", onHover, { once: true });
+    el.addEventListener("touchstart", onHover, { once: true, passive: true });
+
+    return () => {
+      io?.disconnect();
+      el.removeEventListener("mouseenter", onHover);
+      el.removeEventListener("touchstart", onHover);
+    };
+  }, [href, prefetch]);
+
+  return (
+    <a
+      ref={ref}
+      href={href}
+      data-pylon-link=""
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}

package/src/index.ts

@@ -1,6 +1,13 @@
 export { defineRoute } from "@pylonsync/sdk";
 export type { RouteMode, AppManifest } from "@pylonsync/sdk";
 
+// SSR primitives — Next.js-style <Link> and <Image>. Both render
+// progressively (work without JS) and enhance on the client.
+export { Link } from "./Link";
+export type { LinkProps } from "./Link";
+export { Image } from "./Image";
+export type { ImageProps } from "./Image";
+
 import {
   defaultStorage,
   pylonFetch,