@decocms/start 2.4.0 → 2.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/admin/decofile.ts

@@ -1,6 +1,6 @@
-import { getRevision, loadBlocks, setBlocks } from "../cms/loader.ts";
-import { clearLoaderCache } from "../sdk/cachedLoader.ts";
-import { invalidateMetaCache } from "./meta.ts";
+import { getRevision, loadBlocks, setBlocks } from "../cms/loader";
+import { clearLoaderCache } from "../sdk/cachedLoader";
+import { invalidateMetaCache } from "./meta";
 
 export function handleDecofileRead(): Response {
   const blocks = loadBlocks();

package/src/admin/meta.ts

@@ -1,5 +1,5 @@
-import { djb2Hex } from "../sdk/djb2.ts";
-import { composeMeta, type MetaResponse } from "./schema.ts";
+import { djb2Hex } from "../sdk/djb2";
+import { composeMeta, type MetaResponse } from "./schema";
 
 // Use globalThis to share meta state across module instances.
 // The daemon middleware imports this module via native import() (outside Vite SSR),

package/src/cms/loader.ts

@@ -1,5 +1,5 @@
 import * as asyncHooks from "node:async_hooks";
-import { djb2Hex } from "../sdk/djb2.ts";
+import { djb2Hex } from "../sdk/djb2";
 
 export type Resolvable = {
   __resolveType?: string;

package/src/cms/sectionLoaders.test.ts

@@ -1,11 +1,11 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ResolvedSection } from "./resolve";
 import {
   registerCacheableSections,
   registerLayoutSections,
   registerSectionLoader,
   runSingleSectionLoader,
 } from "./sectionLoaders";
-import type { ResolvedSection } from "./resolve";
 
 const G = globalThis as any;
 
@@ -15,10 +15,7 @@ beforeEach(() => {
   G.__deco.cacheableSections.clear();
 });
 
-const makeSection = (
-  component: string,
-  props: Record<string, unknown> = {},
-): ResolvedSection => ({
+const makeSection = (component: string, props: Record<string, unknown> = {}): ResolvedSection => ({
   component,
   props,
   key: component,
@@ -75,10 +72,7 @@ describe("runSingleSectionLoader — page context injection", () => {
 
   it("returns section unchanged when no loader is registered", async () => {
     const section = makeSection("site/sections/NoLoader.tsx", { foo: 1 });
-    const result = await runSingleSectionLoader(
-      section,
-      new Request("https://store.com/"),
-    );
+    const result = await runSingleSectionLoader(section, new Request("https://store.com/"));
     expect(result).toBe(section);
   });
 });
@@ -135,10 +129,145 @@ describe("runSingleSectionLoader — error handling", () => {
     registerSectionLoader("site/sections/Boom.tsx", loader);
 
     const section = makeSection("site/sections/Boom.tsx", { x: 1 });
-    const result = await runSingleSectionLoader(
-      section,
-      new Request("https://store.com/"),
-    );
+    const result = await runSingleSectionLoader(section, new Request("https://store.com/"));
     expect(result).toEqual(section);
   });
 });
+
+describe("runSingleSectionLoader — nested section recursion", () => {
+  it("runs the loader of a nested section in props", async () => {
+    const childLoader = vi.fn(async (props: Record<string, unknown>) => ({
+      ...props,
+      enriched: true,
+    }));
+    registerSectionLoader("site/sections/CategoryBanner.tsx", childLoader);
+
+    // Parent has no own loader, only a nested section in props
+    const parent = makeSection("site/sections/BackgroundWrapper.tsx", {
+      child: {
+        Component: "site/sections/CategoryBanner.tsx",
+        props: { matcher: "/foo" },
+      },
+    });
+
+    const result = await runSingleSectionLoader(parent, new Request("https://store.com/foo"));
+
+    expect(childLoader).toHaveBeenCalledTimes(1);
+    expect(result.props).toEqual({
+      child: {
+        Component: "site/sections/CategoryBanner.tsx",
+        props: {
+          matcher: "/foo",
+          enriched: true,
+          // page context is injected for nested sections too
+          __pageUrl: "https://store.com/foo",
+          __pagePath: "/foo",
+        },
+      },
+    });
+  });
+
+  it("runs nested loaders in arrays (e.g. sections: Section[])", async () => {
+    const banner = vi.fn(async (props: any) => ({ ...props, ranBanner: true }));
+    const shelf = vi.fn(async (props: any) => ({ ...props, ranShelf: true }));
+    registerSectionLoader("site/sections/Banner.tsx", banner);
+    registerSectionLoader("site/sections/Shelf.tsx", shelf);
+
+    const parent = makeSection("site/sections/Wrapper.tsx", {
+      sections: [
+        { Component: "site/sections/Banner.tsx", props: { id: 1 } },
+        { Component: "site/sections/Shelf.tsx", props: { id: 2 } },
+      ],
+    });
+
+    const result = await runSingleSectionLoader(parent, new Request("https://store.com/"));
+
+    expect(banner).toHaveBeenCalledTimes(1);
+    expect(shelf).toHaveBeenCalledTimes(1);
+    const sections = (result.props as any).sections;
+    expect(sections[0].props).toMatchObject({ id: 1, ranBanner: true });
+    expect(sections[1].props).toMatchObject({ id: 2, ranShelf: true });
+  });
+
+  it("returns same props reference when no nested sections (zero-alloc leaf path)", async () => {
+    const loader = vi.fn(async (props: Record<string, unknown>) => props);
+    registerSectionLoader("site/sections/Leaf.tsx", loader);
+
+    const props = { foo: "bar" };
+    const section = makeSection("site/sections/Leaf.tsx", props);
+
+    const result = await runSingleSectionLoader(section, new Request("https://store.com/"));
+
+    // Loader returned the SAME props ref → enrichNestedSections must also
+    // return the same ref → no { ...result, props } wrapping happens
+    expect(result.props).toMatchObject({
+      foo: "bar",
+      __pageUrl: "https://store.com/",
+      __pagePath: "/",
+    });
+  });
+
+  it("recurses into deeply nested sections (wrapper inside wrapper)", async () => {
+    const inner = vi.fn(async (props: any) => ({ ...props, deep: true }));
+    registerSectionLoader("site/sections/Inner.tsx", inner);
+
+    const parent = makeSection("site/sections/Outer.tsx", {
+      child: {
+        Component: "site/sections/MidWrapper.tsx",
+        props: {
+          grandchild: {
+            Component: "site/sections/Inner.tsx",
+            props: { tag: "deep" },
+          },
+        },
+      },
+    });
+
+    const result = await runSingleSectionLoader(parent, new Request("https://store.com/"));
+
+    expect(inner).toHaveBeenCalledTimes(1);
+    const grandchild = (result.props as any).child.props.grandchild;
+    expect(grandchild.props).toMatchObject({ tag: "deep", deep: true });
+  });
+
+  it("ignores nested objects that do not look like sections", async () => {
+    const loader = vi.fn(async (props: Record<string, unknown>) => props);
+    registerSectionLoader("site/sections/Leaf.tsx", loader);
+
+    const section = makeSection("site/sections/Leaf.tsx", {
+      // Plain config object, not a section. Has `Component: string` but
+      // missing the `props` field — must NOT be treated as a nested section.
+      config: { Component: "ButtonStyle", color: "red" },
+    });
+
+    const result = await runSingleSectionLoader(section, new Request("https://store.com/"));
+
+    expect(loader).toHaveBeenCalledTimes(1);
+    expect((result.props as any).config).toEqual({
+      Component: "ButtonStyle",
+      color: "red",
+    });
+  });
+
+  it("runs nested loaders even when parent has no own loader", async () => {
+    const childLoader = vi.fn(async (props: any) => ({ ...props, ran: true }));
+    registerSectionLoader("site/sections/Child.tsx", childLoader);
+
+    // Parent has no entry in registry — but it has a nested section in props
+    // (typical of a pure layout container that just renders children).
+    const parent = makeSection("site/sections/UnregisteredLayout.tsx", {
+      child: {
+        Component: "site/sections/Child.tsx",
+        props: { foo: "bar" },
+      },
+    });
+
+    const result = await runSingleSectionLoader(parent, new Request("https://store.com/"));
+
+    expect(childLoader).toHaveBeenCalledTimes(1);
+    expect((result.props as any).child.props).toMatchObject({
+      foo: "bar",
+      ran: true,
+    });
+  });
+});

package/src/cms/sectionLoaders.ts

@@ -34,7 +34,9 @@ interface CacheableSectionConfig {
   maxAge: number;
 }
 
-export type CacheableSectionInput = CacheableSectionConfig | import("../sdk/cacheHeaders").CacheProfileName;
+export type CacheableSectionInput =
+  | CacheableSectionConfig
+  | import("../sdk/cacheHeaders").CacheProfileName;
 
 function resolveSectionCacheConfig(input: CacheableSectionInput): CacheableSectionConfig {
   if (typeof input === "string") {
@@ -255,10 +257,7 @@ export async function runSectionLoaders(
   if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
     for (const s of sections) {
       const key = s.component.toLowerCase();
-      if (
-        (key.includes("header") || key.includes("footer")) &&
-        !layoutSections.has(s.component)
-      ) {
+      if ((key.includes("header") || key.includes("footer")) && !layoutSections.has(s.component)) {
         console.warn(
           `[SectionLoaders] "${s.component}" looks like a layout section but is not in registerLayoutSections(). ` +
             `Add it to registerLayoutSections() in setup.ts for consistent caching across navigations.`,
@@ -318,47 +317,180 @@ function withPageContext(loader: SectionLoaderFn): SectionLoaderFn {
  * 1. Layout sections (Header/Footer) — 5min TTL + in-flight dedup
  * 2. Cacheable sections (ProductShelf, FAQ) — SWR with configurable maxAge
  * 3. Regular sections — no cache, always fresh
+ *
+ * After the section's own loader runs, recursively runs loaders for any
+ * nested sections found in its resolved props (e.g. wrapper sections with
+ * a `sections: Section[]` prop). This eliminates the need for sites to
+ * manually walk + invoke `runSingleSectionLoader` on children.
  */
 export async function runSingleSectionLoader(
   section: ResolvedSection,
   request: Request,
 ): Promise<ResolvedSection> {
   const loader = loaderRegistry.get(section.component);
-  if (!loader) return section;
-
-  // Wrap the loader so __pageUrl/__pagePath are injected at the call site.
-  // Cache keys (component name for layout, component+propsHash for cacheable)
-  // are computed from the *original* section.props — keeping cache entries
-  // URL-agnostic and shared across pages.
-  const wrapped = withPageContext(loader);
-
-  if (layoutSections.has(section.component)) {
-    try {
-      return await resolveLayoutSection(section, wrapped, request);
-    } catch (error) {
-      console.error(`[SectionLoader] Error in layout "${section.component}":`, error);
-      return section;
+
+  let result: ResolvedSection;
+
+  if (!loader) {
+    // No own-loader, but the section may still contain nested sections in
+    // its props (CMS-resolved children) that need their loaders run.
+    result = section;
+  } else {
+    // Wrap the loader so __pageUrl/__pagePath are injected at the call site.
+    // Cache keys (component name for layout, component+propsHash for cacheable)
+    // are computed from the *original* section.props — keeping cache entries
+    // URL-agnostic and shared across pages.
+    const wrapped = withPageContext(loader);
+
+    if (layoutSections.has(section.component)) {
+      try {
+        result = await resolveLayoutSection(section, wrapped, request);
+      } catch (error) {
+        console.error(`[SectionLoader] Error in layout "${section.component}":`, error);
+        result = section;
+      }
+    } else {
+      const cacheConfig = cacheableSections.get(section.component);
+      if (cacheConfig) {
+        try {
+          result = await runCacheableSectionLoader(section, wrapped, request, cacheConfig);
+        } catch (error) {
+          console.error(`[SectionLoader] Error in cacheable "${section.component}":`, error);
+          result = section;
+        }
+      } else {
+        try {
+          const enrichedProps = await wrapped(section.props as Record<string, unknown>, request);
+          result = { ...section, props: enrichedProps };
+        } catch (error) {
+          console.error(`[SectionLoader] Error in "${section.component}":`, error);
+          result = section;
+        }
+      }
     }
   }
 
-  const cacheConfig = cacheableSections.get(section.component);
-  if (cacheConfig) {
-    try {
-      return await runCacheableSectionLoader(section, wrapped, request, cacheConfig);
-    } catch (error) {
-      console.error(`[SectionLoader] Error in cacheable "${section.component}":`, error);
-      return section;
+  // Recurse into nested sections AFTER the parent's loader/cache lookup so
+  // child sections keep their own cache TTL independent from the parent's.
+  // For layout/cacheable parents, this means a 5-min layout cache hit still
+  // re-evaluates child sections (whose own caches are usually shorter, e.g.
+  // ProductShelf 60s). For leaf sections, `enrichNestedSections` returns
+  // the same reference (no allocation, no extra work).
+  const props = result.props as Record<string, unknown> | undefined;
+  if (props && typeof props === "object") {
+    const enrichedProps = await enrichNestedSections(props, request);
+    if (enrichedProps !== props) {
+      return { ...result, props: enrichedProps };
     }
   }
+  return result;
+}
 
-  try {
-    const enrichedProps = await wrapped(
-      section.props as Record<string, unknown>,
-      request,
-    );
-    return { ...section, props: enrichedProps };
-  } catch (error) {
-    console.error(`[SectionLoader] Error in "${section.component}":`, error);
-    return section;
+// ---------------------------------------------------------------------------
+// Nested section loader support
+// ---------------------------------------------------------------------------
+
+/**
+ * Type guard: matches the shape produced by `normalizeNestedSections` in
+ * resolve.ts — `{ Component: string, props: object }`. This is how the CMS
+ * resolver represents nested sections (children of wrapper sections).
+ *
+ * Note: the `Component` key uses capital C to match the runtime renderer's
+ * convention (mirrors deco-cx/deco's Fresh API). Not to be confused with
+ * the lowercase `component` on `ResolvedSection`.
+ */
+function isNestedSection(
+  value: unknown,
+): value is { Component: string; props: Record<string, unknown> } {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.Component === "string" &&
+    obj.props != null &&
+    typeof obj.props === "object" &&
+    !Array.isArray(obj.props)
+  );
+}
+
+/**
+ * Walk a props object and run section loaders for any nested sections.
+ * Handles direct child sections AND arrays of sections (e.g.
+ * `sections: Section[]`, `slides: Slide[]`).
+ *
+ * Returns the same reference if nothing changed — so leaf sections (the
+ * vast majority) incur zero allocation overhead.
+ *
+ * Concurrency: all nested loader calls run in parallel via Promise.all.
+ */
+async function enrichNestedSections(
+  props: Record<string, unknown>,
+  request: Request,
+): Promise<Record<string, unknown>> {
+  type Pending = {
+    key: string;
+    index?: number;
+    promise: Promise<ResolvedSection>;
+  };
+  const pending: Pending[] = [];
+
+  for (const [key, value] of Object.entries(props)) {
+    if (isNestedSection(value)) {
+      pending.push({
+        key,
+        promise: runSingleSectionLoader(
+          {
+            component: value.Component,
+            props: value.props,
+            key: value.Component,
+          } as ResolvedSection,
+          request,
+        ),
+      });
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        if (isNestedSection(item)) {
+          pending.push({
+            key,
+            index: i,
+            promise: runSingleSectionLoader(
+              {
+                component: item.Component,
+                props: item.props,
+                key: item.Component,
+              } as ResolvedSection,
+              request,
+            ),
+          });
+        }
+      }
+    }
   }
+
+  if (pending.length === 0) return props;
+
+  const results = await Promise.all(pending.map((p) => p.promise));
+  const updated: Record<string, unknown> = { ...props };
+
+  for (let i = 0; i < pending.length; i++) {
+    const { key, index } = pending[i];
+    const enriched = results[i];
+    const nestedValue = { Component: enriched.component, props: enriched.props };
+
+    if (index != null) {
+      // Array item — clone the array on first mutation for this key
+      const current = updated[key];
+      if (current === props[key]) {
+        updated[key] = [...(current as unknown[])];
+      }
+      (updated[key] as unknown[])[index] = nestedValue;
+    } else {
+      updated[key] = nestedValue;
+    }
+  }
+
+  return updated;
 }

package/src/daemon/fs.ts

@@ -11,7 +11,7 @@ import { join, resolve, sep } from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import fjp from "fast-json-patch";
 import type { Operation } from "fast-json-patch";
-import { inferMetadata, broadcastFSEvent, type Metadata } from "./watch.ts";
+import { inferMetadata, broadcastFSEvent, type Metadata } from "./watch";
 
 const cwd = process.cwd();
 const toPosix = (p: string) => p.replaceAll(sep, "/");

package/src/daemon/index.ts

@@ -1,8 +1,8 @@
-export { startTunnel } from "./tunnel.ts";
-export type { TunnelOptions, TunnelConnection } from "./tunnel.ts";
-export { createAuthMiddleware, verifyAdminJwt, tokenIsValid } from "./auth.ts";
-export type { JwtPayload } from "./auth.ts";
-export { createDaemonMiddleware } from "./middleware.ts";
-export type { DaemonOptions } from "./middleware.ts";
-export { createVolumesHandler } from "./volumes.ts";
-export { createWatchHandler, watchFS, broadcastFSEvent } from "./watch.ts";
+export { startTunnel } from "./tunnel";
+export type { TunnelOptions, TunnelConnection } from "./tunnel";
+export { createAuthMiddleware, verifyAdminJwt, tokenIsValid } from "./auth";
+export type { JwtPayload } from "./auth";
+export { createDaemonMiddleware } from "./middleware";
+export type { DaemonOptions } from "./middleware";
+export { createVolumesHandler } from "./volumes";
+export { createWatchHandler, watchFS, broadcastFSEvent } from "./watch";

package/src/daemon/middleware.ts

@@ -10,10 +10,10 @@
  * Ported from: deco-cx/deco daemon/daemon.ts
  */
 import type { IncomingMessage, ServerResponse, Server as HttpServer } from "node:http";
-import { createAuthMiddleware } from "./auth.ts";
-import { createFSHandler } from "./fs.ts";
-import { createVolumesHandler } from "./volumes.ts";
-import { createWatchHandler, watchFS } from "./watch.ts";
+import { createAuthMiddleware } from "./auth";
+import { createFSHandler } from "./fs";
+import { createVolumesHandler } from "./volumes";
+import { createWatchHandler, watchFS } from "./watch";
 
 const DAEMON_API_SPECIFIER = "x-daemon-api";
 const HYPERVISOR_API_SPECIFIER = "x-hypervisor-api";

package/src/sdk/cachedLoader.ts

@@ -11,7 +11,7 @@
  * (e.g. "product") which derives timing from the unified profile system.
  */
 
-import { loaderCacheOptions, type CacheProfileName } from "./cacheHeaders.ts";
+import { loaderCacheOptions, type CacheProfileName } from "./cacheHeaders";
 
 export type CachePolicy = "no-store" | "no-cache" | "stale-while-revalidate";