@parche/core 0.3.0-alpha.0 → 0.4.0

package/src/integration/vite-plugin-parche.ts

@@ -74,6 +74,8 @@ const THEMES_CONFIG_ID = 'parche:config/themes';
 const THEMES_CONFIG_VIRTUAL = '\0parche:config/themes';
 const STYLES_CONFIG_ID = 'parche:config/styles';
 const STYLES_CONFIG_VIRTUAL = '\0parche:config/styles';
+const LAYOUT_CONFIG_ID = 'parche:config/layout';
+const LAYOUT_CONFIG_VIRTUAL = '\0parche:config/layout';
 
 // Core's base.css is the Tailwind root (it has `@import "tailwindcss"`). We
 // append each parche's absolute @source globs into it at transform time —
@@ -113,28 +115,41 @@ function extractTemplateKey(virtualId: string): string {
 }
 
 /**
- * Generate a JS module that exports the widget map.
+ * Generate the widget catalog as LAZY loaders. Each widget is a `() => import()`
+ * so Vite code-splits it into its own chunk, loaded only when a rendered section
+ * references it — the SSR server never holds the whole catalog resident. Renderers
+ * call `loadWidgets(keys)` in their (async) frontmatter to resolve just the
+ * components a page uses before rendering synchronously.
  */
 function generateWidgetMapModule(registry: ResolvedRegistry): string {
-  const entries: { varName: string; key: string; importPath: string }[] = [];
-  let index = 0;
+  const entries: { key: string; importPath: string }[] = [];
 
   for (const virtualId of Object.keys(registry.modules)) {
     if (virtualId.startsWith('parche:widgets/') || virtualId.startsWith('parche:primitives/')) {
-      const key = extractWidgetKey(virtualId);
-      entries.push({ varName: `W${index}`, key, importPath: virtualId });
-      index++;
+      entries.push({ key: extractWidgetKey(virtualId), importPath: virtualId });
     }
   }
 
-  const imports = entries.map((e) => `import ${e.varName} from '${e.importPath}';`).join('\n');
-  const mapEntries = entries.map((e) => `  '${e.key}': ${e.varName},`).join('\n');
+  const loaderEntries = entries
+    .map((e) => `  ${JSON.stringify(e.key)}: () => import(${JSON.stringify(e.importPath)}),`)
+    .join('\n');
 
-  return `${imports}
-
-export const widgetMap = {
-${mapEntries}
+  return `export const widgetLoaders = {
+${loaderEntries}
 };
+
+/** Resolve the given widget keys (deduped) to their components. Keys with no
+ *  loader (e.g. the synthetic 'layout/Main') are skipped. */
+export async function loadWidgets(keys) {
+  const out = {};
+  await Promise.all(
+    [...new Set(keys)].map(async (key) => {
+      const loader = widgetLoaders[key];
+      if (loader) out[key] = (await loader()).default;
+    }),
+  );
+  return out;
+}
 `;
 }
 
@@ -183,6 +198,17 @@ export const showPanel = ${JSON.stringify(registry.showPanel)};
 `;
 }
 
+/**
+ * Generate a JS module that exports layout hints the render path needs — the
+ * set of widget keys that render full-bleed (no default SectionWrapper). Kept as
+ * a plain static array so DynamicRenderer imports zero widget schemas/components
+ * for this decision. Which widgets are full-bleed is declared by the parches, not
+ * hardcoded in core.
+ */
+function generateLayoutConfigModule(registry: ResolvedRegistry): string {
+  return `export const fullBleedWidgets = ${JSON.stringify(registry.fullBleedWidgets)};\n`;
+}
+
 /**
  * Generate the styles entry: side-effect CSS imports for every file the
  * imported parches contribute (plus any user entry). Empty when none — the
@@ -235,8 +261,7 @@ function humanLabel(name: string): string {
  */
 function generateWidgetSchemasModule(registry: ResolvedRegistry): string {
   const imports: string[] = [`import { z } from ${JSON.stringify(resolveFromCore('zod'))};`];
-  const schemaEntries: string[] = [];
-  const metaEntries: string[] = [];
+  const statements: string[] = [];
   let index = 0;
 
   for (const [virtualId, filePath] of Object.entries(registry.modules)) {
@@ -253,46 +278,69 @@ function generateWidgetSchemasModule(registry: ResolvedRegistry): string {
     const variants = loadWidgetDefaults(filePath);
     const variantsJson = JSON.stringify(variants ?? [{ props: {} }]);
     const defaultPropsJson = JSON.stringify(variants?.[0]?.props ?? {});
+    const keyJson = JSON.stringify(key);
 
     if (hasProps) {
-      const varName = `p${index}`;
-      imports.push(`import { schema as ${varName}_s, meta as ${varName}_m } from ${JSON.stringify(propsPath)};`);
-
-      schemaEntries.push(`  ${JSON.stringify(key)}: z.toJSONSchema(${varName}_s)`);
-
-      metaEntries.push(`  ${JSON.stringify(key)}: {
-    label: ${varName}_m?.widget?.label ?? ${JSON.stringify(humanLabel(key))},
-    category: ${varName}_m?.widget?.category ?? ${JSON.stringify(extractWidgetCategory(virtualId))},
-    description: ${varName}_m?.widget?.description ?? '',
-    icon: ${varName}_m?.widget?.icon ?? '',
-    defaultProps: ${defaultPropsJson},
-    defaultVariants: ${variantsJson},
-    ui: ${varName}_m?.ui ?? {},
-  }`);
+      // Namespace import: a `.props.ts` missing `schema` or `meta` no longer
+      // fails the whole module (it would with a named import). Each widget's
+      // schema serialization is isolated in a try/catch so one bad/incompatible
+      // schema (e.g. Zod v3, or a construct toJSONSchema can't serialize) is
+      // skipped with a warning instead of killing the entire builder palette.
+      const m = `p${index}`;
+      imports.push(`import * as ${m} from ${JSON.stringify(propsPath)};`);
+      statements.push(
+        `if (${m}.schema) { try { widgetSchemas[${keyJson}] = z.toJSONSchema(${m}.schema); } ` +
+        `catch (e) { console.warn(${JSON.stringify(`[parche] Skipped JSON Schema for widget "${key}": `)} + ((e && e.message) || e)); } }`,
+      );
+      statements.push(`widgetMeta[${keyJson}] = {
+  label: ${m}.meta?.widget?.label ?? ${JSON.stringify(humanLabel(key))},
+  category: ${m}.meta?.widget?.category ?? ${JSON.stringify(extractWidgetCategory(virtualId))},
+  description: ${m}.meta?.widget?.description ?? '',
+  icon: ${m}.meta?.widget?.icon ?? '',
+  defaultProps: ${defaultPropsJson},
+  defaultVariants: ${variantsJson},
+  ui: ${m}.meta?.ui ?? {},
+};`);
       index++;
     } else {
       // No .props.ts — basic meta only, no schema
-      metaEntries.push(`  ${JSON.stringify(key)}: {
-    label: ${JSON.stringify(humanLabel(key))},
-    category: ${JSON.stringify(extractWidgetCategory(virtualId))},
-    description: '',
-    icon: '',
-    defaultProps: ${defaultPropsJson},
-    defaultVariants: ${variantsJson},
-    ui: {},
-  }`);
+      statements.push(`widgetMeta[${keyJson}] = {
+  label: ${JSON.stringify(humanLabel(key))},
+  category: ${JSON.stringify(extractWidgetCategory(virtualId))},
+  description: '',
+  icon: '',
+  defaultProps: ${defaultPropsJson},
+  defaultVariants: ${variantsJson},
+  ui: {},
+};`);
     }
   }
 
+  // Structural requirements (V2): warn when a requiring parche expects a prop
+  // the provider's schema doesn't expose. Runs where the schemas exist (this
+  // module), so it fires for builder/dev; presence + versions are gated earlier
+  // in createRegistry for every build.
+  const requirementChecks = registry.widgetPropRequirements.map((r) => {
+    const nameJson = JSON.stringify(r.name);
+    const fromJson = JSON.stringify(r.from);
+    const propsJson = JSON.stringify(r.props);
+    return `{
+  const __s = widgetSchemas[${nameJson}];
+  if (__s && __s.properties) {
+    const __missing = ${propsJson}.filter((p) => !(p in __s.properties));
+    if (__missing.length) console.warn(${JSON.stringify(`[parche] ${r.from} requires widget "${r.name}" to expose prop(s): `)} + __missing.join(', ') + ${JSON.stringify(` — provider "${r.name}" schema does not.`)});
+  }
+}`;
+  });
+
   return `${imports.join('\n')}
 
-export const widgetSchemas = {
-${schemaEntries.join(',\n')}
-};
+export const widgetSchemas = {};
+export const widgetMeta = {};
 
-export const widgetMeta = {
-${metaEntries.join(',\n')}
-};
+${statements.join('\n')}
+
+${requirementChecks.join('\n')}
 `;
 }
 
@@ -343,6 +391,22 @@ export async function getResolverPaths(locales, defaultLocale, opts) {
 `;
 }
 
+/**
+ * Is this the core base.css (the Tailwind root we inject @source into)?
+ * Compares by realpath so a symlinked path (pnpm's isolated layout) still
+ * matches — otherwise a mismatch would silently drop every parche's classes.
+ * A consuming app's own base.css has a different realpath and won't match.
+ */
+function isCoreBaseCss(file: string): boolean {
+  if (file === BASE_CSS_PATH) return true;
+  if (!file.endsWith('base.css')) return false;
+  try {
+    return fs.realpathSync(file) === fs.realpathSync(BASE_CSS_PATH);
+  } catch {
+    return false;
+  }
+}
+
 export function vitePluginParche(registry: ResolvedRegistry): Plugin {
   return {
     name: 'vite-plugin-parche',
@@ -354,6 +418,7 @@ export function vitePluginParche(registry: ResolvedRegistry): Plugin {
       if (id === I18N_CONFIG_ID) return I18N_CONFIG_VIRTUAL;
       if (id === THEMES_CONFIG_ID) return THEMES_CONFIG_VIRTUAL;
       if (id === STYLES_CONFIG_ID) return STYLES_CONFIG_VIRTUAL;
+      if (id === LAYOUT_CONFIG_ID) return LAYOUT_CONFIG_VIRTUAL;
 
       if (id === WIDGET_SCHEMAS_ID) return WIDGET_SCHEMAS_VIRTUAL;
       if (id === RESOLVERS_ID) return RESOLVERS_VIRTUAL;
@@ -369,17 +434,25 @@ export function vitePluginParche(registry: ResolvedRegistry): Plugin {
       // `transform`) so @tailwindcss/vite compiles the augmented CSS regardless
       // of plugin ordering. Absolute paths are the only ones that reach sibling
       // packages once installed from npm.
-      if (registry.contentGlobs.length > 0 && id.split('?')[0] === BASE_CSS_PATH) {
+      if (registry.contentGlobs.length > 0 && isCoreBaseCss(id.split('?')[0])) {
         const css = fs.readFileSync(BASE_CSS_PATH, 'utf-8');
         this.addWatchFile(BASE_CSS_PATH);
         return `${css}\n${generateSourceDirectives(registry)}\n`;
       }
 
+      // Inline site config (parche({ site })) — serve the validated object directly
+      // instead of re-exporting a user file. Must come before the generic
+      // module resolution, which has no file path for parche:config here.
+      if (id === '\0parche:config' && registry.inlineSiteConfig) {
+        return `export default ${JSON.stringify(registry.inlineSiteConfig)};\n`;
+      }
+
       if (id === WIDGET_MAP_VIRTUAL) return generateWidgetMapModule(registry);
       if (id === TEMPLATE_MAP_VIRTUAL) return generateTemplateMapModule(registry);
       if (id === I18N_CONFIG_VIRTUAL) return generateI18nConfigModule(registry);
       if (id === THEMES_CONFIG_VIRTUAL) return generateThemesConfigModule(registry);
       if (id === STYLES_CONFIG_VIRTUAL) return generateStylesModule(registry);
+      if (id === LAYOUT_CONFIG_VIRTUAL) return generateLayoutConfigModule(registry);
       if (id === RESOLVERS_VIRTUAL) return generateResolversModule(registry);
       if (id === WIDGET_SCHEMAS_VIRTUAL) {
         // Watch .props.ts and .defaults.json files for HMR

package/src/routes/[...slug].astro

@@ -3,9 +3,9 @@ import 'parche:config/styles';
 import BaseLayout from 'parche:layouts/BaseLayout';
 import ThemePanel from 'parche:components/ThemePanel';
 import LayoutRenderer from 'parche:LayoutRenderer';
+import DynamicRenderer from 'parche:DynamicRenderer';
 import config from 'parche:config';
 import { templateMap } from 'parche:registry/templates';
-import { widgetMap } from 'parche:registry/widgets';
 import { defaultLocale } from 'parche:config/i18n';
 import { showPanel } from 'parche:config/themes';
 import { resolveContent, getResolverPaths } from 'parche:registry/resolvers';
@@ -101,11 +101,15 @@ let AppTemplate: any = null;
 let AppContent: any = null;
 let appMetadata: any = null;
 let appExtras: any = {};
-const RelatedPosts = widgetMap['blog/RelatedPosts'];
-const SeriesNav = widgetMap['blog/SeriesNav'];
 
 if (mode === 'resolver' && resolvedApp) {
   AppTemplate = templateMap[resolvedApp.template];
+  if (import.meta.env.DEV && resolvedApp.template && !AppTemplate) {
+    console.warn(
+      `[parche] Unknown template "${resolvedApp.template}" requested by a resolver — ` +
+      `not registered by any parche. Falling back to a bare <article>.`,
+    );
+  }
   appMetadata = resolvedApp.metadata;
   appExtras = resolvedApp.extras;
 
@@ -137,6 +141,12 @@ if (mode === 'page' && pageData) {
   pageMetadata = resolved;
 
   PageTemplateComponent = pageTemplate !== 'dynamic' ? templateMap[pageTemplate] : null;
+  if (import.meta.env.DEV && pageTemplate !== 'dynamic' && !PageTemplateComponent) {
+    console.warn(
+      `[parche] Unknown template "${pageTemplate}" set on page "${pageKey}" — ` +
+      `not registered by any parche. The page will render without it.`,
+    );
+  }
 
   const pageEntry = await getEntry('pages', entryId);
   if (pageEntry) {
@@ -186,18 +196,8 @@ const layoutSections = await resolveLayout(layoutName, locale, defaultLocale);
         </article>
       )}
 
-      {appExtras.seriesNav && SeriesNav && (
-        <div class="max-w-4xl mx-auto px-4 mb-8">
-          <SeriesNav
-            seriesName={appExtras.seriesNav.seriesName}
-            posts={appExtras.seriesNav.posts}
-            currentOrder={appExtras.seriesNav.currentOrder}
-          />
-        </div>
-      )}
-
-      {appExtras.relatedPosts && RelatedPosts && (
-        <RelatedPosts posts={appExtras.relatedPosts} />
+      {appExtras.sections?.length > 0 && (
+        <DynamicRenderer sections={appExtras.sections} />
       )}
     </LayoutRenderer>
   ) : (

package/src/styles/semantic.css

@@ -29,7 +29,7 @@
   --ds-color-background:  oklch(1 0 0);
   --ds-color-foreground:  oklch(0.07 0.01 260);
   --ds-color-surface:     oklch(1 0 0);
-  --ds-color-primary:     var(--color-neutral-900) /* oklch(0.500 0.220 260) */;
+  --ds-color-primary:     oklch(0.500 0.220 260);   /* brand blue — same as dark, so primary is consistent across modes */
   --ds-color-on-primary:  oklch(1 0 0);
   --ds-color-muted:       oklch(0.55 0.02 264.42);
   --ds-color-border:      oklch(0.90 0.006 260);

package/src/types/config.ts

@@ -60,7 +60,8 @@ export const siteConfigSchema = z.object({
     defaultRobots: defaultRobotsSchema,
     defaultOgType: z.enum(['website', 'article', 'product', 'profile']).default('website'),
     defaultTwitterCard: z.enum(['summary', 'summary_large_image', 'player', 'app']).default('summary_large_image'),
-    allowAICrawlers: z.boolean().default(true),
+    // Note: AI-crawler policy for robots.txt is the `parche({ seo: { allowAICrawlers } })`
+    // integration option, not a SiteConfig field — kept there so it's a single home.
     preconnect: z.array(z.string()).default([]),
   }).default({}),
 
@@ -77,23 +78,17 @@ export const siteConfigSchema = z.object({
     contactPoint: contactPointSchema.optional(),
   }).default({}),
 
-  header: z.object({
-    logo: z.string().optional(),
-    links: z.array(linkSchema).default([]),
-    actions: z.array(actionSchema).default([]),
-  }).default({}),
-
-  footer: z.object({
-    columns: z.array(footerColumnSchema).default([]),
-    copyright: z.string().default(''),
-    socialLinks: z.array(linkSchema).default([]),
-  }).default({}),
-
-  theme: z.object({
-    name: z.string().default(''),
-    darkMode: z.boolean().default(true),
-  }).default({}),
-});
+  // Note: header/footer nav and theme are NOT configured here.
+  // - Chrome (header/footer) is authored in the `layouts` content collection
+  //   (see content/schemas.ts navigationSchema) and passed to the layout widgets.
+  // - Theming is driven by imported theme parches + the `[data-theme]` switcher,
+  //   not by a config flag.
+  // These fields used to live here but were consumed by nothing (a silent trap),
+  // so they were removed. Setting them is now a type error, on purpose.
+}).strict();
+// `.strict()` so a stray/typo'd top-level key (e.g. the old `theme`, `header`,
+// `footer`) fails at build with a clear message instead of being silently
+// dropped by Zod — matching `userConfigSchema` in the integration.
 
 export type SiteConfig = z.infer<typeof siteConfigSchema>;
 

package/src/utils/i18n.ts

@@ -12,7 +12,19 @@ export interface SlugMapEntry {
   entryId: string;
 }
 
+// The `pages` collection is immutable at runtime, so in production (SSG build and
+// SSR serving) we memoize the slug map + a slug→entry lookup index. This collapses
+// the two `buildSlugMap` calls per page request into one and turns the linear
+// resolve scan into an O(1) lookup (also fixes the static build's O(N²) — every
+// generated page was rebuilding the whole map). Disabled in dev so edited content
+// is always fresh.
+const CACHE = import.meta.env.PROD;
+let _slugMapCache: SlugMapEntry[] | null = null;
+let _slugIndexCache: { defaultLocale: string; index: Map<string, SlugMapEntry> } | null = null;
+
 export async function buildSlugMap(): Promise<SlugMapEntry[]> {
+  if (CACHE && _slugMapCache) return _slugMapCache;
+
   const allPages = await getCollection('pages');
   const map: SlugMapEntry[] = [];
 
@@ -24,31 +36,44 @@ export async function buildSlugMap(): Promise<SlugMapEntry[]> {
     map.push({ locale, pageKey, slug, data: entry.data, entryId: entry.id });
   }
 
+  if (CACHE) _slugMapCache = map;
   return map;
 }
 
+/** The URL slug an entry is served at (empty string = the root / home). */
+function expectedSlugFor(entry: SlugMapEntry, defaultLocale: string): string {
+  if (entry.pageKey === 'home') return entry.locale === defaultLocale ? '' : entry.locale;
+  if (entry.locale === defaultLocale) return entry.slug;
+  return `${entry.locale}/${entry.slug}`;
+}
+
+function buildSlugIndex(slugMap: SlugMapEntry[], defaultLocale: string): Map<string, SlugMapEntry> {
+  const index = new Map<string, SlugMapEntry>();
+  for (const entry of slugMap) {
+    const key = expectedSlugFor(entry, defaultLocale);
+    if (!index.has(key)) index.set(key, entry); // first wins, matching the old scan
+  }
+  return index;
+}
+
 export async function resolvePageFromSlug(
   urlSlug: string | undefined,
   defaultLocale: string,
 ): Promise<{ pageData: any; locale: string; pageKey: string; entryId: string } | undefined> {
   const slugMap = await buildSlugMap();
 
-  for (const entry of slugMap) {
-    let expectedSlug: string | undefined;
-    if (entry.pageKey === 'home') {
-      expectedSlug = entry.locale === defaultLocale ? undefined : entry.locale;
-    } else if (entry.locale === defaultLocale) {
-      expectedSlug = entry.slug;
-    } else {
-      expectedSlug = `${entry.locale}/${entry.slug}`;
-    }
-
-    if ((expectedSlug ?? '') === (urlSlug ?? '')) {
-      return { pageData: entry.data, locale: entry.locale, pageKey: entry.pageKey, entryId: entry.entryId };
-    }
+  let index: Map<string, SlugMapEntry>;
+  if (CACHE && _slugIndexCache?.defaultLocale === defaultLocale) {
+    index = _slugIndexCache.index;
+  } else {
+    index = buildSlugIndex(slugMap, defaultLocale);
+    if (CACHE) _slugIndexCache = { defaultLocale, index };
   }
 
-  return undefined;
+  const entry = index.get(urlSlug ?? '');
+  return entry
+    ? { pageData: entry.data, locale: entry.locale, pageKey: entry.pageKey, entryId: entry.entryId }
+    : undefined;
 }
 
 export function getAlternateUrls(

package/src/utils/layout.ts

@@ -4,6 +4,30 @@ import type { SectionEntry } from '../content/schemas.js';
 /** Hardcoded base layout: just a Main area (no header/footer) */
 const BASE_LAYOUT_SECTIONS: SectionEntry[] = [{ widget: 'layout/Main' }];
 
+type LayoutEntry = { id: string; data: { sections: SectionEntry[] } };
+
+// Content collections are immutable at runtime, so build the id→entry index
+// once and reuse it across requests. Cache only in prod — in dev, content edits
+// must re-read (mirrors the i18n slug-index caching).
+const CACHE = import.meta.env.PROD;
+let _layoutIndex: Map<string, LayoutEntry> | null = null;
+
+async function getLayoutIndex(): Promise<Map<string, LayoutEntry> | null> {
+  if (CACHE && _layoutIndex) return _layoutIndex;
+  let allLayouts;
+  try {
+    allLayouts = await getCollection('layouts');
+  } catch {
+    return null;
+  }
+  if (!allLayouts || allLayouts.length === 0) return null;
+  const index = new Map<string, LayoutEntry>(
+    (allLayouts as LayoutEntry[]).map((entry) => [entry.id, entry]),
+  );
+  if (CACHE) _layoutIndex = index;
+  return index;
+}
+
 /**
  * Resolve a layout by name and locale from the layouts content collection.
  *
@@ -19,28 +43,14 @@ export async function resolveLayout(
   locale: string,
   defaultLocale: string,
 ): Promise<SectionEntry[]> {
-  let allLayouts;
-  try {
-    allLayouts = await getCollection('layouts');
-  } catch {
-    return BASE_LAYOUT_SECTIONS;
-  }
-
-  if (!allLayouts || allLayouts.length === 0) {
-    return BASE_LAYOUT_SECTIONS;
-  }
-
-  const find = (id: string) => allLayouts.find((entry) => entry.id === id);
+  const index = await getLayoutIndex();
+  if (!index) return BASE_LAYOUT_SECTIONS;
 
   const entry =
-    find(`${locale}/${name}`) ??
-    find(`${defaultLocale}/${name}`) ??
-    find(`${locale}/default`) ??
-    find(`${defaultLocale}/default`);
-
-  if (!entry) {
-    return BASE_LAYOUT_SECTIONS;
-  }
+    index.get(`${locale}/${name}`) ??
+    index.get(`${defaultLocale}/${name}`) ??
+    index.get(`${locale}/default`) ??
+    index.get(`${defaultLocale}/default`);
 
-  return entry.data.sections;
+  return entry ? entry.data.sections : BASE_LAYOUT_SECTIONS;
 }