@parche/core 0.3.0-alpha.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parche/core",
-  "version": "0.3.0-alpha.0",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": "./src/integration/index.ts",

package/src/components/DynamicRenderer.astro

@@ -1,5 +1,6 @@
 ---
-import { widgetMap } from 'parche:registry/widgets';
+import { loadWidgets } from 'parche:registry/widgets';
+import { fullBleedWidgets } from 'parche:config/layout';
 import SectionWrapper from './SectionWrapper.astro';
 
 interface WrapperConfig {
@@ -25,43 +26,116 @@ interface Props {
 
 const { sections, Wrapper } = Astro.props;
 
-// ---- Image resolution: ~/assets/images/foo.png → optimized import ----
-const imageModules = import.meta.glob<{ default: ImageMetadata }>(
+// ---- Image resolution: @/assets/images/foo.png → optimized import ----
+// Lazy glob: a loader exists for every image, but a module (and its build-time
+// optimization) is only produced for the ones actually referenced. We collect
+// just the paths these sections use, resolve them once, then substitute
+// synchronously during render.
+const imageLoaders = import.meta.glob<{ default: ImageMetadata }>(
   '/src/assets/images/**/*.{png,jpg,jpeg,gif,svg,webp,avif}',
-  { eager: true }
+);
+
+/** Plain objects/arrays are the only things we recurse into — Dates, class
+ *  instances, etc. are left untouched (and never hold image paths). */
+function isPlainObject(v: any): boolean {
+  if (v === null || typeof v !== 'object') return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+/** Gather every '@/assets/…' string used anywhere in the section props. */
+function collectAssetPaths(value: any, acc: Set<string>): void {
+  if (typeof value === 'string') {
+    if (value.startsWith('@/assets/')) acc.add(value);
+  } else if (Array.isArray(value)) {
+    for (const v of value) collectAssetPaths(v, acc);
+  } else if (isPlainObject(value)) {
+    for (const v of Object.values(value)) collectAssetPaths(v, acc);
+  }
+}
+
+// Load only the widget components these sections reference (lazy catalog).
+const widgets = await loadWidgets(sections.map((s) => s.widget));
+
+const assetPaths = new Set<string>();
+for (const section of sections) collectAssetPaths(section.props ?? {}, assetPaths);
+
+const resolvedImages = new Map<string, string>();
+await Promise.all(
+  [...assetPaths].map(async (src) => {
+    const loader = imageLoaders[src.replace('@/', '/src/')];
+    if (loader) {
+      const mod = await loader();
+      resolvedImages.set(src, mod.default.src);
+    }
+  }),
 );
 
 function resolveImage(src: string): string {
-  if (!src || !src.startsWith('@/assets/')) return src;
-  const fsPath = src.replace('@/', '/src/');
-  const meta = imageModules[fsPath]?.default;
-  return meta?.src ?? src;
+  return resolvedImages.get(src) ?? src;
 }
 
-/** Walk props and resolve any ~/assets/ image paths */
-function resolveProps(props: Record<string, any>): Record<string, any> {
-  const resolved = { ...props };
-  for (const [key, value] of Object.entries(resolved)) {
-    if (typeof value === 'string' && value.startsWith('@/assets/')) {
-      resolved[key] = resolveImage(value);
-    } else if (value && typeof value === 'object' && !Array.isArray(value) && 'src' in value && typeof value.src === 'string' && value.src.startsWith('@/assets/')) {
-      resolved[key] = { ...value, src: resolveImage(value.src) };
+/** Substitute resolved image paths at any depth, reusing every subtree that
+ *  didn't change so props with no images are passed through, not deep-cloned. */
+function resolveDeep(value: any): any {
+  if (typeof value === 'string') return resolveImage(value);
+  if (Array.isArray(value)) {
+    let changed = false;
+    const out = value.map((v) => {
+      const r = resolveDeep(v);
+      if (r !== v) changed = true;
+      return r;
+    });
+    return changed ? out : value;
+  }
+  if (isPlainObject(value)) {
+    let changed = false;
+    const out: Record<string, any> = {};
+    for (const [k, v] of Object.entries(value)) {
+      const r = resolveDeep(v);
+      if (r !== v) changed = true;
+      out[k] = r;
     }
+    return changed ? out : value;
   }
-  return resolved;
+  return value;
+}
+
+function resolveProps(props: Record<string, any>): Record<string, any> {
+  return resolveDeep(props);
 }
 
-// Widgets that render full-bleed and manage their own padding — no wrapper by default
-const noWrapperWidgets = new Set(['Hero', 'Hero2', 'HeroText', 'Announcement', 'Note']);
+// Widgets that render full-bleed and manage their own padding — no wrapper by
+// default. The list is contributed by the parches (manifest `fullBleed`), not
+// hardcoded here; core knows no widget names. Match the key as registered, or
+// its short form (a parche may register `hero/Hero` while declaring `Hero`).
+const noWrapperWidgets = new Set(fullBleedWidgets);
 function widgetSkipsWrapper(name: string): boolean {
-  const key = name.includes('/') ? name.split('/').pop()! : name;
-  return noWrapperWidgets.has(key);
+  if (noWrapperWidgets.has(name)) return true;
+  const short = name.includes('/') ? name.split('/').pop()! : name;
+  return noWrapperWidgets.has(short);
 }
 ---
 
 {sections.map((section, index) => {
-  const Widget = widgetMap[section.widget];
-  if (!Widget) return null;
+  const Widget = widgets[section.widget];
+  if (!Widget) {
+    if (import.meta.env.DEV) {
+      console.warn(
+        `[parche] Unknown widget "${section.widget}" — not registered by any parche. ` +
+        `Check the widget name or that a parche provides it.`,
+      );
+      return (
+        <div
+          data-parche-missing-widget={section.widget}
+          style="margin:.5rem;padding:.75rem 1rem;border:2px dashed #dc2626;border-radius:.5rem;background:#fef2f2;color:#991b1b;font:14px/1.5 ui-monospace,SFMono-Regular,monospace"
+        >
+          ⚠ Parche: unknown widget <strong>{section.widget}</strong> — not registered by any parche.
+        </div>
+      );
+    }
+    return null;
+  }
 
   const props = resolveProps(section.props ?? {});
 

package/src/components/LayoutRenderer.astro

@@ -1,5 +1,5 @@
 ---
-import { widgetMap } from 'parche:registry/widgets';
+import { loadWidgets } from 'parche:registry/widgets';
 import DynamicRenderer from 'parche:DynamicRenderer';
 
 interface WrapperConfig {
@@ -37,6 +37,10 @@ const {
   SectionWrapper: PreviewWrapper,
   mainId,
 } = Astro.props;
+
+// Load only the layout widgets this layout references ('layout/Main' is a
+// synthetic marker with no loader — skipped). Lazy catalog.
+const widgets = await loadWidgets(layoutSections.map((s) => s.widget));
 ---
 
 {layoutSections.map((section) => {
@@ -58,8 +62,24 @@ const {
     );
   }
 
-  const Widget = widgetMap[section.widget];
-  if (!Widget) return null;
+  const Widget = widgets[section.widget];
+  if (!Widget) {
+    if (import.meta.env.DEV) {
+      console.warn(
+        `[parche] Unknown layout widget "${section.widget}" — not registered by any parche. ` +
+        `Check the layout definition or the parche providing this widget.`,
+      );
+      return (
+        <div
+          data-parche-missing-widget={section.widget}
+          style="margin:.5rem;padding:.75rem 1rem;border:2px dashed #dc2626;border-radius:.5rem;background:#fef2f2;color:#991b1b;font:14px/1.5 ui-monospace,SFMono-Regular,monospace"
+        >
+          ⚠ Parche: unknown layout widget <strong>{section.widget}</strong> — not registered by any parche.
+        </div>
+      );
+    }
+    return null;
+  }
 
   return <Widget {...(section.props ?? {})} />;
 })}

package/src/components/SectionWrapper.astro

@@ -1,8 +1,11 @@
 ---
 /**
  * Default section wrapper used by DynamicRenderer.
- * Provides: configurable HTML tag, background layer, isDark per-widget,
- * responsive container with padding, and class overrides via twMerge.
+ * Provides: configurable HTML tag, a raw-HTML background layer, isDark per-widget,
+ * a responsive container, and class overrides via twMerge.
+ *
+ * Section rhythm/backgrounds are authored as raw HTML via `bg` in page content —
+ * a gradient div, an inline SVG (dots/grid), a glow, whatever the section needs.
  */
 import type { HTMLTag } from 'astro/types';
 import { twMerge } from 'tailwind-merge';
@@ -10,6 +13,7 @@ import { twMerge } from 'tailwind-merge';
 interface Props {
   id?: string;
   isDark?: boolean;
+  /** Raw HTML background layer (a div, gradient, inline SVG, pattern…). */
   bg?: string;
   classes?: Record<string, unknown>;
   as?: string;
@@ -23,21 +27,18 @@ const containerClass = (classes.container as string) ?? '';
 
 <Tag class="relative not-prose scroll-mt-[72px]" {...id ? { id } : {}}>
   {bg && (
-    <div class="absolute inset-0 pointer-events-none -z-[1]" aria-hidden="true">
+    <div class="absolute inset-0 pointer-events-none -z-[1] overflow-hidden" aria-hidden="true">
       <Fragment set:html={bg} />
     </div>
   )}
   {isDark && !bg && (
     <div class="absolute inset-0 pointer-events-none -z-[1]" aria-hidden="true">
-      <div class="absolute inset-0 bg-neutral-900 dark:bg-transparent" />
+      <div class="absolute inset-0 bg-neutral-900 dark:bg-transparent"></div>
     </div>
   )}
   <div
     class:list={[
-      twMerge(
-        'relative mx-auto max-w-7xl px-4 md:px-6 py-12 md:py-16 lg:py-20',
-        containerClass,
-      ),
+      twMerge('relative mx-auto max-w-7xl px-4 md:px-6 py-12 md:py-16 lg:py-20', containerClass),
       { dark: isDark },
     ]}
   >

package/src/integration/index.ts

@@ -2,19 +2,176 @@ import type { AstroIntegration } from 'astro';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import fs from 'node:fs';
+import { z } from 'zod';
 import { vitePluginParche } from './vite-plugin-parche.js';
 import { createRegistry } from './registry.js';
-import type { ParcheUserConfig, UIRegistry, ParcheApp, ParcheManifest, ParcheRequires } from './types.js';
+import { siteConfigSchema, type SiteConfig } from '../types/config.js';
+import type { ParcheUserConfig, ParchePreset, ParcheSeoConfig, UIRegistry, ParcheApp, ParcheManifest, ParcheRequires } from './types.js';
 
-export default function parche(userConfig: ParcheUserConfig = {}): AstroIntegration {
+// ---------------------------------------------------------------------------
+// Preset composition (`extends`)
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Deep-merge two config fragments. Objects merge recursively; primitives and
+ * arrays are replaced by the override (last wins) — except `parches`, which the
+ * caller concatenates. `undefined` on the override never clobbers the base.
+ */
+function deepMerge<T>(base: T, over: T): T {
+  if (over === undefined) return base;
+  if (isPlainObject(base) && isPlainObject(over)) {
+    const out: Record<string, unknown> = { ...base };
+    for (const key of Object.keys(over)) {
+      out[key] = deepMerge((base as Record<string, unknown>)[key], (over as Record<string, unknown>)[key]);
+    }
+    return out as T;
+  }
+  return over;
+}
+
+/** Merge an override config onto a base, concatenating `parches` (base first). */
+function mergeConfig(base: ParchePreset, over: ParchePreset): ParchePreset {
+  const merged = deepMerge(base, over);
+  const baseParches = base.parches ?? [];
+  const overParches = over.parches ?? [];
+  if (baseParches.length || overParches.length) {
+    merged.parches = [...baseParches, ...overParches];
+  }
+  return merged;
+}
+
+/**
+ * Identity helper that types and freezes a reusable config fragment for
+ * `extends`. Authoring a preset through it gets you inference and a clear
+ * boundary; it does no work beyond returning the object.
+ */
+export function parchePreset(preset: ParchePreset): ParchePreset {
+  return preset;
+}
+
+/** Fold a config's `extends` chain into a single flat config (presets first). */
+export function resolveExtends(userConfig: ParcheUserConfig): ParcheUserConfig {
+  if (!userConfig.extends) return userConfig;
+  const presets = Array.isArray(userConfig.extends) ? userConfig.extends : [userConfig.extends];
+  let base: ParchePreset = {};
+  for (const preset of presets) base = mergeConfig(base, preset);
+  const { extends: _drop, ...rest } = userConfig;
+  return mergeConfig(base, rest) as ParcheUserConfig;
+}
+
+// Shape validation for the `parche({ ... })` options. `.strict()` turns a typo'd
+// option name (e.g. `parchez`) or a malformed value into a friendly error at
+// config time, instead of a deep, cryptic Vite failure later. The `parches`
+// array holds manifests (validated structurally by the registry), so it's `any`.
+const userConfigSchema = z
+  .object({
+    overrides: z.record(z.string(), z.string()).optional(),
+    config: z.string().optional(),
+    parches: z.array(z.any()).optional(),
+    routes: z
+      .object({
+        pages: z.boolean().optional(),
+        templates: z.record(z.string(), z.string()).optional(),
+        layouts: z.record(z.string(), z.string()).optional(),
+        catchAllRoute: z.string().optional(),
+        notFoundRoute: z.string().optional(),
+        middleware: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+    themes: z
+      .object({
+        available: z.array(z.object({ label: z.string(), value: z.string() })).optional(),
+        showPanel: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+    styles: z.object({ entry: z.string().optional() }).strict().optional(),
+    seo: z.object({ allowAICrawlers: z.boolean().optional() }).strict().optional(),
+  })
+  .strict();
+
+function validateUserConfig(userConfig: ParcheUserConfig): void {
+  const result = userConfigSchema.safeParse(userConfig);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('\n');
+    throw new Error(`[parche] Invalid parche() options:\n${issues}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config resolution
+// ---------------------------------------------------------------------------
+
+/** Runtime context passed to the function form of `parche()`. */
+export interface ParcheConfigContext {
+  /** Astro command driving this run. */
+  command: 'dev' | 'build' | 'preview' | 'sync';
+  /** Convenience alias: 'development' for dev, 'production' otherwise. */
+  mode: 'development' | 'production';
+  /** Environment variables, for env-based / white-label branching. */
+  env: Record<string, string | undefined>;
+  /** Tenant id from PARCHE_TENANT (multi-tenant / white-label), if set. */
+  tenant: string | undefined;
+}
+
+type SiteConfigInput = Parameters<typeof siteConfigSchema.parse>[0];
+
+/**
+ * The Parche config object: integration options (parches, routes, themes,
+ * styles, overrides, extends) plus, optionally, the site identity inline. Omit
+ * the site fields and point `config` at a separate file instead — both styles
+ * are equally supported. `seo` carries the site SEO fields and the build-time
+ * `allowAICrawlers`.
+ */
+export type ParcheConfig = Omit<ParcheUserConfig, 'seo'> &
+  Partial<Omit<SiteConfigInput, 'seo'>> & {
+    seo?: (SiteConfigInput extends { seo?: infer S } ? S : never) & ParcheSeoConfig;
+  };
+
+/** `parche()` accepts a config object or a function of the runtime context. */
+export type ParcheConfigInput = ParcheConfig | ((ctx: ParcheConfigContext) => ParcheConfig);
+
+interface PreparedConfig {
+  /** Integration options only (site data stripped), extends already folded. */
+  userConfig: ParcheUserConfig;
+  /** Inline site config, when the site identity was given inline. */
+  inlineSiteConfig?: SiteConfig;
+  /** robots.txt AI-crawler policy. */
+  allowAICrawlers: boolean;
+}
+
+/**
+ * Shared integration body. `prepare` turns the runtime context into the resolved
+ * options; everything downstream (registry, route injection, robots.txt) is
+ * identical regardless of how the config was authored.
+ */
+function createIntegration(prepare: (ctx: ParcheConfigContext) => PreparedConfig): AstroIntegration {
   let resolvedSiteUrl = '';
+  let allowAICrawlers = true;
   return {
     name: 'parche',
     hooks: {
-      'astro:config:setup': ({ updateConfig, config, injectRoute, addMiddleware }) => {
+      'astro:config:setup': ({ command, updateConfig, config, injectRoute, addMiddleware }) => {
+        const ctx: ParcheConfigContext = {
+          command,
+          mode: command === 'dev' ? 'development' : 'production',
+          env: process.env,
+          tenant: process.env.PARCHE_TENANT,
+        };
+        const prepared = prepare(ctx);
+        const resolved = prepared.userConfig;
+        allowAICrawlers = prepared.allowAICrawlers;
+        validateUserConfig(resolved);
         resolvedSiteUrl = config.site ?? '';
         const rootDir = fileURLToPath(config.root);
-        const resolvedRegistry = createRegistry(userConfig, rootDir, config.i18n);
+        const resolvedRegistry = createRegistry(resolved, rootDir, config.i18n, prepared.inlineSiteConfig);
 
         // Resolve @core/* alias for backward compatibility with widget internal imports
         const coreDir = path.resolve(
@@ -25,24 +182,24 @@ export default function parche(userConfig: ParcheUserConfig = {}): AstroIntegrat
         const routesDir = path.resolve(coreDir, 'routes');
 
         // Inject routes only when explicitly enabled via routes.pages: true
-        if (userConfig.routes?.pages) {
+        if (resolved.routes?.pages) {
           // Catch-all page route
           injectRoute({
             pattern: '[...slug]',
-            entrypoint: userConfig.routes?.catchAllRoute
+            entrypoint: resolved.routes?.catchAllRoute
               ?? path.resolve(routesDir, '[...slug].astro'),
           });
 
           // 404 page
           injectRoute({
             pattern: '404',
-            entrypoint: userConfig.routes?.notFoundRoute
+            entrypoint: resolved.routes?.notFoundRoute
               ?? path.resolve(routesDir, '404.astro'),
           });
 
           // Middleware for i18n locale resolution
           addMiddleware({
-            entrypoint: userConfig.routes?.middleware
+            entrypoint: resolved.routes?.middleware
               ?? path.resolve(routesDir, 'middleware.ts'),
             order: 'pre',
           });
@@ -78,13 +235,71 @@ export default function parche(userConfig: ParcheUserConfig = {}): AstroIntegrat
       },
 
       'astro:build:done': ({ dir }) => {
-        const allowAICrawlers = userConfig.seo?.allowAICrawlers ?? true;
         processRobotsTxt(dir, resolvedSiteUrl, allowAICrawlers);
       },
     },
   };
 }
 
+/**
+ * The Parche Astro integration. One entry, two equally supported styles for the
+ * site identity:
+ *
+ *   • Inline — pass `site` (and optionally metadata/seo/organization) right here.
+ *     It's validated and served as `parche:config`; no separate file needed.
+ *   • Separate file — omit `site` and point `config` at a file (default
+ *     `./parche.config.ts` at the project root). The parches stay in
+ *     astro.config; everything else lives in that file (authored with
+ *     `defineConfig` from `@parche/core/config`).
+ *
+ * The argument may also be a function of the runtime context
+ * (`(ctx) => config`) for env-based / conditional / multi-tenant setups, and any
+ * config may `extends` a `parchePreset(...)`.
+ *
+ * @example
+ * // astro.config.mjs
+ * import parche from '@parche/core';
+ * export default defineConfig({
+ *   integrations: [parche({ parches: [createUI()], config: './parche.config.ts', routes: { pages: true } })],
+ * });
+ */
+export default function parche(input: ParcheConfigInput = {}): AstroIntegration {
+  return createIntegration((ctx) => prepareParcheConfig(input, ctx));
+}
+
+/**
+ * Resolve a config input (object or function) into the pieces the integration
+ * needs: the integration options, an optional inline site config, and the
+ * robots policy. Pure — exported for testing. Folds `extends`, splits the site
+ * identity out of the options, and picks inline vs separate-file mode.
+ */
+export function prepareParcheConfig(
+  input: ParcheConfigInput,
+  ctx: ParcheConfigContext,
+): PreparedConfig {
+  const cfg = typeof input === 'function' ? input(ctx) : input;
+  // Fold `extends` first (a preset may seed site data or parches), then split
+  // the site identity out of the integration options.
+  const merged = resolveExtends(cfg as unknown as ParcheUserConfig) as unknown as ParcheConfig;
+  const { site, metadata, seo, organization, config: configPath, ...rest } =
+    merged as ParcheConfig & { config?: string };
+  const userOpts = rest as ParcheUserConfig;
+  const { allowAICrawlers = true, ...siteSeo } = (seo ?? {}) as Record<string, unknown>;
+
+  if (site) {
+    // Inline mode: validate + serve the site identity as parche:config.
+    const inlineSiteConfig = siteConfigSchema.parse({ site, metadata, seo: siteSeo, organization });
+    return { userConfig: userOpts, inlineSiteConfig, allowAICrawlers: allowAICrawlers as boolean };
+  }
+
+  // Separate-file mode: site identity comes from `config` (or the default
+  // ./parche.config.ts). Only the robots policy is read from seo here.
+  return {
+    userConfig: { ...userOpts, config: configPath },
+    allowAICrawlers: allowAICrawlers as boolean,
+  };
+}
+
 const ROBOTS_MARKER = '# === PARCHE:AUTO-GENERATED';
 
 function processRobotsTxt(outDir: URL, siteUrl: string, allowAICrawlers: boolean) {
@@ -153,4 +368,4 @@ function buildAutoGeneratedRobots(siteUrl: string, allowAICrawlers: boolean): st
   return lines.join('\n');
 }
 
-export type { ParcheUserConfig, UIRegistry, ParcheApp, ParcheManifest, ParcheRequires };
+export type { ParcheUserConfig, ParchePreset, UIRegistry, ParcheApp, ParcheManifest, ParcheRequires };