npm - @pylonsync/functions - Versions diffs - 0.3.235 → 0.3.236 - Mend

@pylonsync/functions 0.3.235 → 0.3.236

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.235",
+  "version": "0.3.236",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts CHANGED Viewed

@@ -25,7 +25,7 @@ export { slugifyName, availableSlug } from "./slugify";
 // SSR page response controller — pages/layouts receive `response` in
 // props (response.setStatus / redirect / notFound / setHeader / setCookie).
 // Type-only; the runtime instance is injected per-render by the SSR adapter.
-export type { SsrResponse, SsrCookieOptions } from "./ssr-runtime";
+export type { SsrResponse, SsrCookieOptions, SsrMetadata } from "./ssr-runtime";
 export type {
   QueryCtx,
   MutationCtx,

package/src/ssr-runtime.ts CHANGED Viewed

@@ -240,6 +240,130 @@ function finalizeHeaders(
  * has flushed) are uncatchable here — React's `onError` would have
  * to feed into a separate signal, deferred to Phase 1.5.
  */
+/**
+ * Page SEO metadata. A page exports `export const metadata = {...}`
+ * (static) or `export async function generateMetadata(props)` (dynamic,
+ * e.g. param-derived titles). Kept flat — no deep nesting beyond og/twitter.
+ *
+ * React 19 hoists the resulting <title>/<meta>/<link> into <head>. A page
+ * `title` overrides a layout's static `<title>` (both render; the browser
+ * uses the last, which is the page's). React does NOT dedupe arbitrary
+ * `<meta>`, so set `description`/OG in EITHER the layout OR page metadata,
+ * not both, to avoid duplicate tags.
+ */
+export interface SsrMetadata {
+  title?: string;
+  description?: string;
+  keywords?: string | string[];
+  canonical?: string;
+  robots?: string;
+  openGraph?: {
+    title?: string;
+    description?: string;
+    image?: string;
+    url?: string;
+    type?: string;
+  };
+  twitter?: {
+    card?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+  };
+}
+/**
+ * Build a React fragment of <title>/<meta>/<link> from a page's metadata.
+ * React 19 auto-hoists these into <head> wherever they render, and the
+ * host's </head> splice preserves them. React escapes all text/attrs, so
+ * there's no manual XSS handling. Returns null when there's nothing to emit.
+ */
+function renderMetadata(React: any, m: SsrMetadata | undefined): any {
+  if (!m) return null;
+  const el = React.createElement;
+  const kids: any[] = [];
+  if (m.title != null) kids.push(el("title", { key: "t" }, m.title));
+  if (m.description != null) {
+    kids.push(el("meta", { key: "d", name: "description", content: m.description }));
+  }
+  const kw = Array.isArray(m.keywords) ? m.keywords.join(", ") : m.keywords;
+  if (kw) kids.push(el("meta", { key: "kw", name: "keywords", content: kw }));
+  if (m.robots) kids.push(el("meta", { key: "r", name: "robots", content: m.robots }));
+  if (m.canonical) {
+    kids.push(el("link", { key: "c", rel: "canonical", href: m.canonical }));
+  }
+  const og = m.openGraph;
+  if (og) {
+    if (og.title != null) kids.push(el("meta", { key: "ogt", property: "og:title", content: og.title }));
+    if (og.description != null) kids.push(el("meta", { key: "ogd", property: "og:description", content: og.description }));
+    if (og.image) kids.push(el("meta", { key: "ogi", property: "og:image", content: og.image }));
+    if (og.url) kids.push(el("meta", { key: "ogu", property: "og:url", content: og.url }));
+    if (og.type) kids.push(el("meta", { key: "ogy", property: "og:type", content: og.type }));
+  }
+  const tw = m.twitter;
+  if (tw) {
+    if (tw.card) kids.push(el("meta", { key: "twc", name: "twitter:card", content: tw.card }));
+    if (tw.title != null) kids.push(el("meta", { key: "twt", name: "twitter:title", content: tw.title }));
+    if (tw.description != null) kids.push(el("meta", { key: "twd", name: "twitter:description", content: tw.description }));
+    if (tw.image) kids.push(el("meta", { key: "twi", name: "twitter:image", content: tw.image }));
+  }
+  return kids.length > 0 ? el(React.Fragment, null, ...kids) : null;
+}
+const MODULE_EXTS = [".tsx", ".ts", ".jsx", ".js"];
+/** Import a project-relative module, trying each common extension. */
+async function importModule(cwd: string, relPath: string): Promise<any> {
+  const base = `${cwd}/${relPath}`;
+  let lastErr: unknown = null;
+  for (const ext of MODULE_EXTS) {
+    try {
+      return await import(`${base}${ext}`);
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  throw lastErr ?? new Error(`could not import module "${relPath}"`);
+}
+/**
+ * Wrap a leaf element in its layout chain (leaf → root). Resolves ALL
+ * layouts first so a missing one fails before any chunk is emitted. Reused
+ * by the page render and by the not-found / error boundary render.
+ */
+async function buildLayoutTree(
+  cwd: string,
+  leaf: any,
+  layouts: string[] | undefined,
+  props: any,
+  React: any,
+): Promise<any> {
+  if (!layouts || layouts.length === 0) return leaf;
+  const layoutComps: any[] = [];
+  for (const layoutPath of layouts) {
+    let lMod: any;
+    try {
+      lMod = await importModule(cwd, layoutPath);
+    } catch {
+      throw new Error(
+        `could not import layout "${layoutPath}" — checked .tsx / .ts / .jsx / .js`,
+      );
+    }
+    const LayoutComp = lMod.default ?? lMod.Layout ?? lMod.layout;
+    if (typeof LayoutComp !== "function") {
+      throw new Error(
+        `layout "${layoutPath}" has no default export (or named export "Layout")`,
+      );
+    }
+    layoutComps.push(LayoutComp);
+  }
+  let tree = leaf;
+  for (let i = layoutComps.length - 1; i >= 0; i--) {
+    tree = React.createElement(layoutComps[i], props, tree);
+  }
+  return tree;
+}
 export async function handleRenderRoute(
   msg: RenderRouteMessage,
   send: Send,
@@ -291,23 +415,14 @@ export async function handleRenderRoute(
       );
     }
-    // Resolve the page module. The component string is project-
-    // relative without extension; try .tsx → .ts → .jsx → .js so
-    // any of the common page-file shapes work. cwd was captured
-    // above for the react resolver.
-    const baseName = `${cwd}/${msg.component}`;
-    let mod: any = null;
-    let lastErr: unknown = null;
-    for (const ext of [".tsx", ".ts", ".jsx", ".js"]) {
-      try {
-        mod = await import(`${baseName}${ext}`);
-        break;
-      } catch (e) {
-        lastErr = e;
-      }
-    }
-    if (!mod) {
-      throw lastErr ?? new Error(`could not import component "${msg.component}"`);
+    // Resolve the page module (project-relative, extension-agnostic).
+    let mod: any;
+    try {
+      mod = await importModule(cwd, msg.component);
+    } catch (e) {
+      throw e instanceof Error
+        ? e
+        : new Error(`could not import component "${msg.component}"`);
     }
     const Component = mod.default ?? mod.Page ?? mod.page;
     if (typeof Component !== "function") {
@@ -328,50 +443,32 @@ export async function handleRenderRoute(
       response,
     };
+    // SEO metadata: static `export const metadata` or dynamic
+    // `export async function generateMetadata(props)`. Awaited before the
+    // first byte, so keep it to cheap derivations (params → title); heavy
+    // data belongs in the page body behind <Suspense>.
+    let metadata: SsrMetadata | undefined = mod.metadata;
+    if (typeof mod.generateMetadata === "function") {
+      metadata = await mod.generateMetadata(props);
+    }
+    const metaFragment = renderMetadata(React, metadata);
     // Resolve the layout chain. Each layout module exports a default
     // function that accepts the same props + `children`. Walk leaf →
     // root: start with the page component as `tree`, then for each
     // layout (innermost first) wrap it as the new tree. Result is
     // the outermost layout containing all nested layouts down to
-    // the page.
-    let tree: any = React.createElement(Component, props);
-    const layouts = msg.layouts ?? [];
-    if (layouts.length > 0) {
-      // Resolve all layouts first so we fail fast on a missing one
-      // BEFORE we start emitting headers / chunks.
-      const layoutMods: any[] = [];
-      for (const layoutPath of layouts) {
-        const lBase = `${cwd}/${layoutPath}`;
-        let lMod: any = null;
-        for (const ext of [".tsx", ".ts", ".jsx", ".js"]) {
-          try {
-            lMod = await import(`${lBase}${ext}`);
-            break;
-          } catch {
-            // try next extension
-          }
-        }
-        if (!lMod) {
-          throw new Error(
-            `could not import layout "${layoutPath}" — checked .tsx / .ts / .jsx / .js`,
-          );
-        }
-        const LayoutComp =
-          lMod.default ?? lMod.Layout ?? lMod.layout;
-        if (typeof LayoutComp !== "function") {
-          throw new Error(
-            `layout "${layoutPath}" has no default export (or named export "Layout")`,
-          );
-        }
-        layoutMods.push(LayoutComp);
-      }
-      // Walk LEAF → ROOT (reverse iteration on the layouts array).
-      // The innermost layout wraps the page first; each outer layout
-      // wraps the result.
-      for (let i = layoutMods.length - 1; i >= 0; i--) {
-        tree = React.createElement(layoutMods[i], props, tree);
-      }
-    }
+    // the page. The metadata fragment is the FIRST child so React hoists
+    // its <title>/<meta> into the <head> a layout renders.
+    let tree: any = metaFragment
+      ? React.createElement(
+          React.Fragment,
+          null,
+          metaFragment,
+          React.createElement(Component, props),
+        )
+      : React.createElement(Component, props);
+    tree = await buildLayoutTree(cwd, tree, msg.layouts, props, React);
     const element = tree;
     const stream: ReadableStream<Uint8Array> = await renderToReadableStream(
       element,