@decocms/start 1.5.0 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -48,6 +48,7 @@
     "./sdk/createInvoke": "./src/sdk/createInvoke.ts",
     "./sdk/router": "./src/sdk/router.ts",
     "./matchers/posthog": "./src/matchers/posthog.ts",
+    "./apps": "./src/apps/index.ts",
     "./apps/autoconfig": "./src/apps/autoconfig.ts",
     "./sdk/setupApps": "./src/sdk/setupApps.ts",
     "./matchers/builtins": "./src/matchers/builtins.ts",

package/src/admin/render.ts

@@ -15,6 +15,16 @@ import { getPreviewWrapper } from "./setup";
 
 export { setRenderShell, setPreviewWrapper } from "./setup";
 
+/** Escape user-controlled strings before interpolating into HTML. */
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
 // Cache the dynamic import — avoids re-importing per section render
 let _renderToString: ((element: any) => string) | null = null;
 async function getRenderToString() {
@@ -36,7 +46,7 @@ function wrapInHtmlShell(sectionHtml: string): string {
 async function renderResolvedSection(section: ResolvedSection): Promise<string> {
   const sectionLoader = getSection(section.component);
   if (!sectionLoader) {
-    return `<div style="padding:8px;color:orange;font-size:12px;border:1px dashed orange;margin:4px 0;">Unsupported: ${section.component}</div>`;
+    return `<div style="padding:8px;color:orange;font-size:12px;border:1px dashed orange;margin:4px 0;">Unsupported: ${escapeHtml(section.component)}</div>`;
   }
 
   try {
@@ -47,7 +57,7 @@ async function renderResolvedSection(section: ResolvedSection): Promise<string>
     const wrapped = Wrapper ? createElement(Wrapper, null, element) : element;
     return renderToString(wrapped);
   } catch (error) {
-    return `<div style="padding:8px;color:red;font-size:12px;">Error rendering ${section.component}: ${(error as Error).message}</div>`;
+    return `<div style="padding:8px;color:red;font-size:12px;">Error rendering ${escapeHtml(section.component)}: ${escapeHtml((error as Error).message)}</div>`;
   }
 }
 
@@ -62,7 +72,7 @@ async function renderOneSection(section: Record<string, unknown>): Promise<strin
 
   const sectionLoader = getSection(resolveType);
   if (!sectionLoader) {
-    return `<div style="padding:8px;color:orange;font-size:12px;border:1px dashed orange;margin:4px 0;">Unsupported: ${resolveType}</div>`;
+    return `<div style="padding:8px;color:orange;font-size:12px;border:1px dashed orange;margin:4px 0;">Unsupported: ${escapeHtml(resolveType)}</div>`;
   }
 
   try {
@@ -74,7 +84,7 @@ async function renderOneSection(section: Record<string, unknown>): Promise<strin
     const wrapped = Wrapper ? createElement(Wrapper, null, element) : element;
     return renderToString(wrapped);
   } catch (error) {
-    return `<div style="padding:8px;color:red;font-size:12px;">Error rendering ${resolveType}: ${(error as Error).message}</div>`;
+    return `<div style="padding:8px;color:red;font-size:12px;">Error rendering ${escapeHtml(resolveType)}: ${escapeHtml((error as Error).message)}</div>`;
   }
 }
 
@@ -234,7 +244,7 @@ export async function handleRender(request: Request): Promise<Response> {
     const sectionLoader = getSection(component);
     if (!sectionLoader) {
       const unknownHtml = wrapInHtmlShell(
-        `<div style="padding:20px;color:red;">Unknown section: ${component}</div>`,
+        `<div style="padding:20px;color:red;">Unknown section: ${escapeHtml(component)}</div>`,
       );
       return new Response(unknownHtml, {
         status: 200,
@@ -257,7 +267,7 @@ export async function handleRender(request: Request): Promise<Response> {
       });
     } catch (error) {
       const errorHtml = wrapInHtmlShell(
-        `<div style="padding:20px;color:red;">Render error: ${(error as Error).message}</div>`,
+        `<div style="padding:20px;color:red;">Render error: ${escapeHtml((error as Error).message)}</div>`,
       );
       return new Response(errorHtml, {
         status: 200,

package/src/apps/autoconfig.ts

@@ -1,89 +1,135 @@
 /**
- * Auto-configures known apps from CMS blocks using AppModContract.
+ * Registry-driven auto-configuration of known apps from CMS blocks.
  *
- * Scans the decofile for known app block keys (e.g. "deco-vtex", "deco-resend")
- * and calls each app's `configure()` function from its mod.ts.
- * Then delegates to `setupApps()` for invoke handler registration, middleware, etc.
+ * A site passes an `AppRegistry` (declarative list of known app blockKeys +
+ * lazy module imports). For every registry entry whose `blockKey` exists in
+ * the decofile, this calls `mod.configure(block, resolveSecret)` and then
+ * hands the resulting AppDefinitions off to `setupApps()`.
+ *
+ * The canonical registry lives in `@decocms/apps/registry` so the framework
+ * itself has zero knowledge of which apps exist.
  *
  * Usage in setup.ts:
  *   import { autoconfigApps } from "@decocms/start/apps/autoconfig";
- *   setBlocks(generatedBlocks);
- *   await autoconfigApps(generatedBlocks);
+ *   import { APP_REGISTRY } from "@decocms/apps/registry";
+ *   await autoconfigApps(generatedBlocks, APP_REGISTRY);
  */
 
 import { onChange } from "../cms/loader";
 import { resolveSecret } from "../sdk/crypto";
 import {
-	setupApps,
-	type AppDefinition,
-	type AppDefinitionWithHandlers,
+  setupApps,
+  type AppDefinition,
+  type AppDefinitionWithHandlers,
 } from "../sdk/setupApps";
 
-// ---------------------------------------------------------------------------
-// Known app block keys → dynamic import of their mod.ts
-// ---------------------------------------------------------------------------
+/**
+ * Shape of the secret resolver passed to each app's `configure()`. Matches
+ * `resolveSecret` in `src/sdk/crypto.ts`. Apps typically narrow the return
+ * type inside their own `configure()` by throwing on null.
+ */
+export type ResolveSecret = (
+  value: unknown,
+  envVarName?: string,
+) => Promise<string | null>;
+
+/**
+ * One entry in the app registry — describes a single installable app.
+ * Sites pass an array of these to `autoconfigApps()` (typically imported
+ * from `@decocms/apps/registry`).
+ */
+export interface AppRegistryEntry {
+  /** Block key in the decofile, e.g. "deco-shopify". */
+  blockKey: string;
+
+  /**
+   * Lazy import of the app's mod module. Must return an object exposing
+   * `configure(block, resolveSecret)` and optionally `handlers`.
+   *
+   * Use a string-literal dynamic import so bundlers (Vite/Rollup) can
+   * statically trace the chunk. E.g.
+   *   () => import("@decocms/apps/shopify/mod")
+   */
+  module: () => Promise<{
+    configure: (
+      block: unknown,
+      resolveSecret: ResolveSecret,
+    ) => Promise<AppDefinition | null>;
+    handlers?: Record<string, (props: any, req: Request) => Promise<any>>;
+  }>;
 
-const APP_MODS: Record<string, () => Promise<any>> = {
-	"deco-vtex": () => import("@decocms/apps/vtex/mod" as string),
-	"deco-shopify": () => import("@decocms/apps/shopify/mod" as string),
-	"deco-resend": () => import("@decocms/apps/resend/mod" as string),
-};
+  /** Human-readable name shown in admin install UI. */
+  displayName?: string;
+  /** Icon URL (absolute or site-relative) shown in admin install UI. */
+  icon?: string;
+  /** Grouping label, e.g. "commerce", "email", "analytics". */
+  category?: string;
+  /** Short summary (one sentence) shown in admin install UI. */
+  description?: string;
+}
 
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
+export type AppRegistry = readonly AppRegistryEntry[];
 
 async function configureAllApps(
-	blocks: Record<string, unknown>,
+  blocks: Record<string, unknown>,
+  registry: AppRegistry,
 ): Promise<AppDefinitionWithHandlers[]> {
-	const apps: AppDefinitionWithHandlers[] = [];
+  const apps: AppDefinitionWithHandlers[] = [];
 
-	for (const [blockKey, importMod] of Object.entries(APP_MODS)) {
-		const block = blocks[blockKey];
-		if (!block) continue;
+  for (const entry of registry) {
+    const block = blocks[entry.blockKey];
+    if (!block) continue;
 
-		try {
-			const mod = await importMod();
-			if (typeof mod.configure !== "function") continue;
+    try {
+      const mod = await entry.module();
+      if (typeof mod?.configure !== "function") continue;
 
-			const appDef: AppDefinition | null = await mod.configure(
-				block,
-				resolveSecret,
-			);
-			if (!appDef) continue;
+      const appDef: AppDefinition | null = await mod.configure(
+        block,
+        resolveSecret,
+      );
+      if (!appDef) continue;
 
-			// Attach explicit handlers from mod.ts (e.g. resend's pre-wrapped handlers)
-			const withHandlers: AppDefinitionWithHandlers = {
-				...appDef,
-				handlers: mod.handlers,
-			};
-			apps.push(withHandlers);
-		} catch {
-			// App not installed or configure failed — skip silently
-		}
-	}
+      const withHandlers: AppDefinitionWithHandlers = {
+        ...appDef,
+        handlers: mod.handlers,
+      };
+      apps.push(withHandlers);
+    } catch {
+      // App module missing, configure threw, or block was malformed — skip.
+    }
+  }
 
-	return apps;
+  return apps;
 }
 
 /**
- * Auto-configure apps from CMS blocks.
- * Call in setup.ts after setBlocks(). Also re-runs on admin hot-reload.
+ * Auto-configure apps from CMS blocks against a declarative registry.
+ *
+ * Call once in setup.ts after setBlocks(). Re-runs on admin hot-reload.
+ *
+ * @param blocks   Decofile blocks (from blocks.gen or loadBlocks()).
+ * @param registry List of installable apps — typically
+ *                 `import { APP_REGISTRY } from "@decocms/apps/registry"`.
  */
-export async function autoconfigApps(blocks: Record<string, unknown>) {
-	if (typeof document !== "undefined") return; // server-only
+export async function autoconfigApps(
+  blocks: Record<string, unknown>,
+  registry: AppRegistry,
+): Promise<void> {
+  if (typeof document !== "undefined") return; // server-only
+  if (!registry || registry.length === 0) return;
 
-	const apps = await configureAllApps(blocks);
-	if (apps.length > 0) {
-		await setupApps(apps);
-	}
+  const apps = await configureAllApps(blocks, registry);
+  if (apps.length > 0) {
+    await setupApps(apps);
+  }
 
-	// Re-configure on admin hot-reload
-	onChange(async (newBlocks) => {
-		if (typeof document !== "undefined") return;
-		const updatedApps = await configureAllApps(newBlocks);
-		if (updatedApps.length > 0) {
-			await setupApps(updatedApps);
-		}
-	});
+  // Re-configure on admin hot-reload
+  onChange(async (newBlocks) => {
+    if (typeof document !== "undefined") return;
+    const updatedApps = await configureAllApps(newBlocks, registry);
+    if (updatedApps.length > 0) {
+      await setupApps(updatedApps);
+    }
+  });
 }

package/src/apps/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Public entry point for app-install primitives.
+ *
+ * Sites import from `@decocms/start/apps`:
+ *   - `autoconfigApps(blocks, registry)` — main bootstrap call
+ *   - `AppRegistry`, `AppRegistryEntry` — registry types
+ *   - `setupApps`, `AppDefinition` — lower-level primitives when composing custom registries
+ */
+
+export {
+  autoconfigApps,
+  type AppRegistry,
+  type AppRegistryEntry,
+} from "./autoconfig";
+
+export {
+  setupApps,
+  registerAppMiddleware,
+  getAppMiddleware,
+  type AppDefinition,
+  type AppDefinitionWithHandlers,
+  type AppManifest,
+  type AppMiddleware,
+} from "../sdk/setupApps";

package/src/cms/applySectionConventions.ts

@@ -11,10 +11,12 @@ import {
   registerSectionsSync,
 } from "./registry";
 import {
+  type CacheableSectionInput,
   registerCacheableSections,
   registerLayoutSections,
 } from "./sectionLoaders";
 import {
+  type AsyncRenderingConfig,
   registerEagerSections,
   registerSeoSections,
   setAsyncRenderingConfig,
@@ -48,13 +50,13 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
   const eagerSections: string[] = [];
   const layoutSections: string[] = [];
   const seoSections: string[] = [];
-  const cacheableSections: Record<string, string> = {};
+  const cacheableSections: Record<string, CacheableSectionInput> = {};
 
   for (const [key, entry] of Object.entries(meta)) {
     if (entry.eager) eagerSections.push(key);
     if (entry.layout) layoutSections.push(key);
     if (entry.seo) seoSections.push(key);
-    if (entry.cache) cacheableSections[key] = entry.cache;
+    if (entry.cache) cacheableSections[key] = entry.cache as CacheableSectionInput;
 
     if (entry.clientOnly && sectionGlob) {
       const globKey = sectionGlobKey(key, sectionGlob);
@@ -81,7 +83,8 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
     // Permanent registry — survives subsequent setAsyncRenderingConfig() calls
     registerEagerSections(eagerSections);
     // Also add to alwaysEager for backward compat with code that reads the config
-    const existing = getAsyncRenderingConfig() ?? {};
+    const existing: Partial<AsyncRenderingConfig> =
+      getAsyncRenderingConfig() ?? {};
     setAsyncRenderingConfig({
       ...existing,
       alwaysEager: [...(existing.alwaysEager ?? []), ...eagerSections],

package/src/cms/index.ts

@@ -49,6 +49,8 @@ export {
   registerBotPattern,
   registerCommerceLoader,
   registerCommerceLoaders,
+  unregisterCommerceLoader,
+  clearCommerceLoaders,
   registerMatcher,
   registerEagerSections,
   registerSeoSections,

package/src/cms/resolve.ts

@@ -298,6 +298,16 @@ export function registerCommerceLoaders(loaders: Record<string, CommerceLoader>)
   Object.assign(commerceLoaders, loaders);
 }
 
+/** Delete a single commerce loader by key. No-op if key is absent. */
+export function unregisterCommerceLoader(key: string): void {
+  delete commerceLoaders[key];
+}
+
+/** Clear all commerce loaders. Use with care — wipes site-registered entries too. */
+export function clearCommerceLoaders(): void {
+  for (const key of Object.keys(commerceLoaders)) delete commerceLoaders[key];
+}
+
 // ---------------------------------------------------------------------------
 // Custom matchers
 // ---------------------------------------------------------------------------

package/src/cms/sectionLoaders.ts

@@ -34,7 +34,7 @@ interface CacheableSectionConfig {
   maxAge: number;
 }
 
-type CacheableSectionInput = CacheableSectionConfig | import("../sdk/cacheHeaders").CacheProfileName;
+export type CacheableSectionInput = CacheableSectionConfig | import("../sdk/cacheHeaders").CacheProfileName;
 
 function resolveSectionCacheConfig(input: CacheableSectionInput): CacheableSectionConfig {
   if (typeof input === "string") {

package/src/hooks/PreviewProviders.tsx

@@ -9,7 +9,10 @@ import type { ReactNode } from "react";
 const rootRoute = createRootRoute();
 
 const previewRouter = createRouter({
-  routeTree: rootRoute,
+  // TanStack Router's RootRoute/Route generic inference rejects bare rootRoute
+  // at the type level (works at runtime). `as any` avoids leaking the mismatch
+  // into consumer sites that typecheck framework source via npm link.
+  routeTree: rootRoute as any,
   history: createMemoryHistory({ initialEntries: ["/"] }),
 });
 

package/src/sdk/setupApps.ts

@@ -21,6 +21,10 @@
 
 import { clearInvokeHandlers, registerInvokeHandlers } from "../admin/invoke";
 import { registerSections } from "../cms/registry";
+import {
+  registerCommerceLoaders,
+  unregisterCommerceLoader,
+} from "../cms/resolve";
 import { RequestContext } from "./requestContext";
 
 // ---------------------------------------------------------------------------
@@ -68,6 +72,17 @@ const appMiddlewares: Array<{
   middleware: AppMiddleware;
 }> = [];
 
+/**
+ * Keys this module wrote into the commerce-loaders map. Tracked so hot-reload
+ * can wipe app-owned entries without touching site-local registrations.
+ */
+const appCommerceLoaderKeys = new Set<string>();
+
+function clearAppCommerceLoaders() {
+  for (const key of appCommerceLoaderKeys) unregisterCommerceLoader(key);
+  appCommerceLoaderKeys.clear();
+}
+
 function registerAppState(name: string, state: unknown) {
   appStates.push({ name, state });
 }
@@ -143,6 +158,26 @@ function flattenDependencies(apps: AppDefinition[]): AppDefinition[] {
   return result;
 }
 
+/**
+ * Register handlers into the commerce-loaders map used by the CMS resolve path
+ * (src/cms/resolve.ts). Tracks the keys so clearAppCommerceLoaders() can revert
+ * them on hot-reload without clobbering site-registered loaders.
+ *
+ * CommerceLoader receives `(props)` only. The admin invoke path passes
+ * `(props, req)`; here `req` is undefined. Handlers that need `req` should
+ * rely on RequestContext instead of a positional argument.
+ */
+function registerAppCommerceHandlers(
+  handlers: Record<string, (props: any, req: Request) => Promise<any>>,
+) {
+  const entries: Record<string, (props: any) => Promise<any>> = {};
+  for (const [key, handler] of Object.entries(handlers)) {
+    entries[key] = (props: any) => handler(props, undefined as unknown as Request);
+    appCommerceLoaderKeys.add(key);
+  }
+  registerCommerceLoaders(entries);
+}
+
 // ---------------------------------------------------------------------------
 // Main pipeline
 // ---------------------------------------------------------------------------
@@ -161,34 +196,51 @@ export async function setupApps(
   // Clear previous registrations (safe for hot-reload via onChange)
   clearRegistrations();
   clearInvokeHandlers();
+  clearAppCommerceLoaders();
 
   for (const app of flattenDependencies(apps as AppDefinition[])) {
     const appWithHandlers = app as AppDefinitionWithHandlers;
 
     // 1. Register explicit handlers (pre-unwrapped by the app, e.g. resend)
+    //    These also go into the commerce-loaders map so the CMS resolve path
+    //    (src/cms/resolve.ts) can dispatch to them by __resolveType.
     if (appWithHandlers.handlers) {
       registerInvokeHandlers(appWithHandlers.handlers);
+      registerAppCommerceHandlers(appWithHandlers.handlers);
     }
 
-    // 2. Flatten manifest modules → individual invoke handlers
-    // manifest.actions["vtex/actions/checkout"] = { getOrCreateCart, addItemsToCart, ... }
-    // → register "vtex/actions/checkout/getOrCreateCart" as handler
+    // 2. Flatten manifest modules → individual invoke handlers.
+    //
+    //   Convention (mirrors legacy deco-cx/apps):
+    //     - `default` export is registered at the moduleKey itself.
+    //         shopify/loaders/ProductList.ts (default) → key "shopify/loaders/ProductList"
+    //     - Named function exports are registered at `${moduleKey}/${fnName}`.
+    //         vtex/actions/checkout.ts ({ getOrCreateCart, addItemsToCart })
+    //         → keys "vtex/actions/checkout/getOrCreateCart", ".../addItemsToCart"
+    //     - Each key also gets a `.ts` sibling for callers that include the
+    //       extension (admin invoke path, some __resolveType producers).
     for (const category of ["loaders", "actions"] as const) {
       const modules = app.manifest[category];
       if (!modules) continue;
 
       for (const [moduleKey, moduleExports] of Object.entries(modules)) {
-        for (const [fnName, fn] of Object.entries(
-          moduleExports as Record<string, unknown>,
-        )) {
+        const exports = moduleExports as Record<string, unknown>;
+
+        for (const [fnName, fn] of Object.entries(exports)) {
           if (typeof fn !== "function") continue;
-          const key = `${moduleKey}/${fnName}`;
+          const key = fnName === "default"
+            ? moduleKey
+            : `${moduleKey}/${fnName}`;
           const handler = (props: any, req: Request) =>
             (fn as Function)(props, req);
           registerInvokeHandlers({
             [key]: handler,
             [`${key}.ts`]: handler,
           });
+          registerAppCommerceHandlers({
+            [key]: handler,
+            [`${key}.ts`]: handler,
+          });
         }
       }
     }