@parche/core 0.3.0-alpha.0 → 0.4.0

package/src/integration/registry.ts

@@ -1,6 +1,8 @@
+import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import type { ParcheUserConfig, ResolvedRegistry, ParcheManifest } from './types.js';
+import type { SiteConfig } from '../types/config.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const coreDir = path.resolve(__dirname, '..');
@@ -20,6 +22,45 @@ function dedupeThemes(
 /** The always-present base look (no data-theme). Themes are added by parches. */
 const DEFAULT_THEME = { label: 'Default', value: '' };
 
+/** Parse "1.2.3" (ignoring build/prerelease suffix) into a numeric tuple. */
+function parseVersion(v: string): [number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim().replace(/^v/, ''));
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+function cmpVersion(a: [number, number, number], b: [number, number, number]): number {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+/**
+ * Minimal semver range check for peer requirements: `*`/``/`latest` = any;
+ * caret `^x.y.z` (npm semantics, incl. 0.x pinning); tilde `~x.y.z`;
+ * `>=x.y.z`; anything else is treated as an exact match. Exported for testing.
+ */
+export function satisfiesVersion(actual: string, range: string): boolean {
+  const r = range.trim();
+  if (!r || r === '*' || r === 'latest') return true;
+  const a = parseVersion(actual);
+  if (!a) return false;
+  if (r.startsWith('>=')) {
+    const b = parseVersion(r.slice(2));
+    return !!b && cmpVersion(a, b) >= 0;
+  }
+  if (r.startsWith('^')) {
+    const b = parseVersion(r.slice(1));
+    if (!b || cmpVersion(a, b) < 0) return false;
+    if (b[0] > 0) return a[0] === b[0];
+    if (b[1] > 0) return a[0] === 0 && a[1] === b[1];
+    return a[0] === 0 && a[1] === 0 && a[2] === b[2];
+  }
+  if (r.startsWith('~')) {
+    const b = parseVersion(r.slice(1));
+    return !!b && a[0] === b[0] && a[1] === b[1] && cmpVersion(a, b) >= 0;
+  }
+  const b = parseVersion(r);
+  return !!b && cmpVersion(a, b) === 0;
+}
+
 /** Built-in core component registry */
 const CORE_MODULES: Record<string, string> = {
   // Theme / i18n engine controls (consumed by the ui parche's Header)
@@ -44,12 +85,13 @@ const CORE_MODULES: Record<string, string> = {
   // now provided by the ui parche — core no longer ships chrome or primitives.
 };
 
-/** Modules that use named exports instead of default export */
-const NAMED_EXPORT_MODULES = new Set([
+/** Core modules that use named exports instead of default export. Frozen default —
+ *  each createRegistry call gets its own Set seeded from this (never mutate this). */
+const BASE_NAMED_EXPORTS: readonly string[] = [
   'parche:utils/metadata',
   'parche:utils/i18n',
   'parche:utils/layout',
-]);
+];
 
 /**
  * Convert an override key ('widgets:hero:Hero') to a virtual module ID ('parche:widgets/hero/Hero')
@@ -65,46 +107,75 @@ export function createRegistry(
   userConfig: ParcheUserConfig,
   rootDir: string,
   astroI18n?: { locales?: Array<string | { path: string; codes: string[] }>; defaultLocale?: string },
+  inlineSiteConfig?: SiteConfig,
 ): ResolvedRegistry {
   const modules: Record<string, string> = { ...CORE_MODULES };
 
-  // Add config module
-  const configPath = userConfig.config || './src/config.ts';
-  modules['parche:config'] = path.resolve(rootDir, configPath);
+  // Site config: `parche({ site })` passes it inline (served as parche:config by
+  // the vite plugin); otherwise parche:config points at the user's config file.
+  if (!inlineSiteConfig) {
+    const configPath = userConfig.config || './parche.config.ts';
+    modules['parche:config'] = path.resolve(rootDir, configPath);
+  }
+
+  // Modules that use named exports — instance-local, seeded from the frozen base
+  // so registrations don't bleed between createRegistry calls in one process.
+  const namedExportModules = new Set<string>(BASE_NAMED_EXPORTS);
+
+  // Surface silent last-wins collisions and bad parche paths with attribution,
+  // instead of an opaque "Unknown virtual module" / ESM error much later.
+  const collisions: string[] = [];
+  const badPaths: string[] = [];
+  const setModule = (parcheName: string, kind: string, virtualId: string, absPath: string) => {
+    if (!path.isAbsolute(absPath)) {
+      badPaths.push(`"${parcheName}" ${kind} "${virtualId}" → not an absolute path: ${absPath}`);
+    } else if (!fs.existsSync(absPath)) {
+      badPaths.push(`"${parcheName}" ${kind} "${virtualId}" → file not found: ${absPath}`);
+    }
+    const prev = modules[virtualId];
+    if (prev && prev !== absPath) {
+      collisions.push(`${virtualId} — "${parcheName}" overwrites ${prev}`);
+    }
+    modules[virtualId] = absPath;
+  };
 
   // Register parches (order = precedence: later wins). Each parche contributes
   // primitives / widgets / templates / routes / config to the system.
   const parches = userConfig.parches ?? [];
   const providedPrimitives = new Set<string>();
   const providedWidgets = new Set<string>();
+  const providedTemplates = new Set<string>();
   const apps: ParcheManifest[] = [];
   const contributedStyles: string[] = [];
   const contributedThemes: Array<{ label: string; value: string }> = [];
   const contentGlobs: string[] = [];
+  const fullBleedWidgets: string[] = [];
 
   for (const parche of parches) {
     if (parche.styles) contributedStyles.push(...parche.styles);
     if (parche.themes) contributedThemes.push(...parche.themes);
     if (parche.content) contentGlobs.push(...parche.content);
+    if (parche.fullBleed) fullBleedWidgets.push(...parche.fullBleed);
     if (parche.primitives) {
       for (const [name, absPath] of Object.entries(parche.primitives)) {
-        modules[`parche:primitives/${name}`] = absPath;
+        setModule(parche.name, 'primitive', `parche:primitives/${name}`, absPath);
         providedPrimitives.add(name);
       }
     }
     if (parche.widgets) {
       for (const [name, absPath] of Object.entries(parche.widgets)) {
-        modules[`parche:widgets/${name}`] = absPath;
+        setModule(parche.name, 'widget', `parche:widgets/${name}`, absPath);
         providedWidgets.add(name);
       }
     }
     if (parche.templates) {
       for (const [name, absPath] of Object.entries(parche.templates)) {
-        modules[`parche:templates/${name}`] = absPath;
+        setModule(parche.name, 'template', `parche:templates/${name}`, absPath);
+        providedTemplates.add(name);
       }
     }
     if (parche.namedExportModules) {
-      for (const id of parche.namedExportModules) NAMED_EXPORT_MODULES.add(id);
+      for (const id of parche.namedExportModules) namedExportModules.add(id);
     }
     // A parche that injects routes / resolves slugs / exposes config is an "app".
     if (parche.routes || parche.resolver || parche.config) {
@@ -112,10 +183,21 @@ export function createRegistry(
     }
   }
 
+  if (badPaths.length) {
+    console.warn('[parche] Parche path problems (these modules will fail to load):\n  - ' + badPaths.join('\n  - '));
+  }
+  if (collisions.length) {
+    console.warn(
+      '[parche] Duplicate registrations — the last parche wins. If this is intentional, use `overrides` to make it explicit:\n  - ' +
+        collisions.join('\n  - '),
+    );
+  }
+
   // Add user-defined templates
   if (userConfig.routes?.templates) {
     for (const [name, userPath] of Object.entries(userConfig.routes.templates)) {
       modules[`parche:templates/${name}`] = path.resolve(rootDir, userPath);
+      providedTemplates.add(name);
     }
   }
 
@@ -126,14 +208,45 @@ export function createRegistry(
     }
   }
 
-  // Validate parche requirements (V1: capability presence).
+  // Validate parche requirements (V2: presence of every capability, plus
+  // peer-parche version ranges). Structural widget-prop checks run where the
+  // schemas are available (widgetSchemas generation), not here.
+  const providedThemes = new Set<string>(['', ...contributedThemes.map((t) => t.value)]);
+  const parcheVersions = new Map<string, string | undefined>(parches.map((p) => [p.name, p.version]));
+
   const missing: string[] = [];
+  const widgetPropRequirements: Array<{ from: string; name: string; props: string[] }> = [];
   for (const parche of parches) {
-    for (const name of parche.requires?.primitives ?? []) {
+    const req = parche.requires;
+    if (!req) continue;
+    for (const name of req.primitives ?? []) {
       if (!providedPrimitives.has(name)) missing.push(`"${parche.name}" requires primitive "${name}" (parche:primitives/${name})`);
     }
-    for (const name of parche.requires?.widgets ?? []) {
-      if (!providedWidgets.has(name)) missing.push(`"${parche.name}" requires widget "${name}" (parche:widgets/${name})`);
+    for (const w of req.widgets ?? []) {
+      const name = typeof w === 'string' ? w : w.name;
+      if (!providedWidgets.has(name)) {
+        missing.push(`"${parche.name}" requires widget "${name}" (parche:widgets/${name})`);
+      } else if (typeof w === 'object' && w.props?.length) {
+        widgetPropRequirements.push({ from: parche.name, name, props: w.props });
+      }
+    }
+    for (const name of req.templates ?? []) {
+      if (!providedTemplates.has(name)) missing.push(`"${parche.name}" requires template "${name}" (parche:templates/${name})`);
+    }
+    for (const value of req.themes ?? []) {
+      if (!providedThemes.has(value)) missing.push(`"${parche.name}" requires theme "${value}"`);
+    }
+    for (const dep of req.parches ?? []) {
+      if (!parcheVersions.has(dep.name)) {
+        missing.push(`"${parche.name}" requires parche "${dep.name}"${dep.version ? ` (${dep.version})` : ''} — not imported`);
+      } else if (dep.version) {
+        const actual = parcheVersions.get(dep.name);
+        if (!actual) {
+          missing.push(`"${parche.name}" requires "${dep.name}@${dep.version}" but "${dep.name}" declares no version`);
+        } else if (!satisfiesVersion(actual, dep.version)) {
+          missing.push(`"${parche.name}" requires "${dep.name}@${dep.version}" but found ${actual}`);
+        }
+      }
     }
   }
   if (missing.length) {
@@ -181,7 +294,10 @@ export function createRegistry(
 
   return {
     modules,
-    namedExportModules: NAMED_EXPORT_MODULES,
+    namedExportModules,
+    fullBleedWidgets,
+    widgetPropRequirements,
+    inlineSiteConfig,
     i18n,
     themes,
     showPanel,

package/src/integration/types.ts

@@ -41,12 +41,34 @@ export interface WidgetMeta {
   };
 }
 
-/** Capabilities a parche needs from the system (validated at setup). */
+/** A required widget: a bare name checks presence; the object form also asserts
+ *  the provider exposes the named props (structural, checked where schemas exist). */
+export type WidgetRequirement = string | { name: string; props?: string[] };
+
+/** A required peer parche, optionally constrained to a version range
+ *  (exact `1.2.3`, caret `^1.2.0`, tilde `~1.2.0`, or `>=1.2.0`; `*`/omitted = any). */
+export interface ParcheRequirement {
+  name: string;
+  version?: string;
+}
+
+/**
+ * Capabilities a parche needs from the system, validated at setup (V2). Presence
+ * of every named capability is checked and fails the build with attribution;
+ * peer-parche versions are range-checked; widget prop requirements are checked
+ * structurally where the schemas are available.
+ */
 export interface ParcheRequires {
   /** Primitive names that must exist (parche:primitives/{name}) */
   primitives?: string[];
-  /** Widget names that must exist (parche:widgets/{name}) */
-  widgets?: string[];
+  /** Widgets that must exist — bare name, or { name, props } for a structural check */
+  widgets?: WidgetRequirement[];
+  /** Template names that must exist (parche:templates/{name}) */
+  templates?: string[];
+  /** Theme values that must be present in the switcher */
+  themes?: string[];
+  /** Peer parches that must be imported, optionally within a version range */
+  parches?: ParcheRequirement[];
 }
 
 /**
@@ -57,10 +79,20 @@ export interface ParcheRequires {
 export interface ParcheManifest {
   /** Unique identifier (e.g. 'primitives', 'ui', 'blog') */
   name: string;
+  /** Semver of this parche, used to satisfy peers' `requires.parches` ranges. */
+  version?: string;
   /** Primitives to register: name → absolute path (parche:primitives/{name}) */
   primitives?: Record<string, string>;
   /** Widgets to register: virtual ID suffix → absolute path (parche:widgets/{name}) */
   widgets?: Record<string, string>;
+  /**
+   * Widget keys (as registered in `widgets`) that render full-bleed and manage
+   * their own padding — DynamicRenderer skips the default SectionWrapper for them
+   * unless a section sets `wrapper` explicitly. Declared here (statically) rather
+   * than in each widget's `.props.ts` so the render path never imports schemas.
+   * Core no longer hardcodes any widget names.
+   */
+  fullBleed?: string[];
   /** Templates to register: virtual ID suffix → absolute path */
   templates?: Record<string, string>;
   /**
@@ -154,10 +186,18 @@ export interface ParcheSeoConfig {
 }
 
 export interface ParcheUserConfig {
+  /**
+   * Inherit from one or more shared presets (a company base, a monorepo root).
+   * Presets are deep-merged left-to-right, then this config is merged on top —
+   * this config wins on every leaf. `parches` are the exception: they are
+   * concatenated (preset parches first, so a local parche can override them,
+   * since later-in-the-array wins). Build presets with `parchePreset(...)`.
+   */
+  extends?: ParchePreset | ParchePreset[];
   /** Override any component using namespaced keys: 'widgets:hero:Hero', 'primitives:Button', etc.
    *  Values are paths to .astro component files. */
   overrides?: Record<string, string>;
-  /** Path to user config file (default: './src/config.ts') */
+  /** Path to user config file (default: './parche.config.ts', at project root) */
   config?: string;
   /** Parches (plugins): primitive-packs, widget-packs and apps. Order = precedence. */
   parches?: ParcheManifest[];
@@ -171,11 +211,27 @@ export interface ParcheUserConfig {
   seo?: ParcheSeoConfig;
 }
 
+/**
+ * A reusable, partial Parche config that others `extends`. Every field is
+ * optional; whatever it sets becomes the base an extending config overrides.
+ * (`extends` itself doesn't nest — resolve a chain by extending the preset that
+ * already extends its own base.)
+ */
+export type ParchePreset = Omit<ParcheUserConfig, 'extends'>;
+
 export interface ResolvedRegistry {
   /** Map of virtual module ID → absolute file path */
   modules: Record<string, string>;
   /** Set of virtual IDs that use named exports (export *) instead of default */
   namedExportModules: Set<string>;
+  /** Widget keys that render full-bleed (skip the default SectionWrapper) */
+  fullBleedWidgets: string[];
+  /** Structural widget requirements: prop names a requiring parche expects the
+   *  provider to expose. Checked against the generated schemas (builder-time). */
+  widgetPropRequirements: Array<{ from: string; name: string; props: string[] }>;
+  /** Inline site config (parche({ site })); when set, the plugin serves it as
+   *  parche:config instead of re-exporting a user config file. */
+  inlineSiteConfig?: import('../types/config.js').SiteConfig;
   /** Resolved i18n config */
   i18n: ParcheI18nConfig;
   /** Resolved themes config */

package/src/integration/virtual.d.ts

@@ -11,7 +11,15 @@ declare module 'parche:config/styles' {}
 
 // Generated maps
 declare module 'parche:registry/widgets' {
-  export const widgetMap: Record<string, import('astro').AstroComponentFactory>;
+  /** Lazy widget catalog: key → dynamic import of the component. */
+  export const widgetLoaders: Record<
+    string,
+    () => Promise<{ default: import('astro').AstroComponentFactory }>
+  >;
+  /** Resolve the given widget keys (deduped) to their components. */
+  export function loadWidgets(
+    keys: string[],
+  ): Promise<Record<string, import('astro').AstroComponentFactory>>;
 }
 
 declare module 'parche:registry/templates' {
@@ -31,8 +39,11 @@ declare module 'parche:registry/resolvers' {
     templateProps: Record<string, any>;
     metadata: Record<string, any>;
     extras: {
-      seriesNav?: { seriesName: string; posts: any[]; currentOrder: number };
-      relatedPosts?: any[];
+      sections: Array<{
+        widget: string;
+        props?: Record<string, any>;
+        wrapper?: false | { classes?: Record<string, unknown>; [key: string]: unknown };
+      }>;
     };
   } | null>;
   export function getResolverPaths(
@@ -52,23 +63,19 @@ declare module 'parche:config/themes' {
   export const showPanel: boolean;
 }
 
+declare module 'parche:config/layout' {
+  /** Widget keys that render full-bleed (skip the default SectionWrapper). */
+  export const fullBleedWidgets: string[];
+}
+
 // Layouts
 declare module 'parche:layouts/BaseLayout' {
   const Component: typeof import('../layouts/BaseLayout.astro').default;
   export default Component;
 }
 
-// Components
-declare module 'parche:components/Header' {
-  const Component: typeof import('../components/common/Header.astro').default;
-  export default Component;
-}
-
-declare module 'parche:components/Footer' {
-  const Component: typeof import('../components/common/Footer.astro').default;
-  export default Component;
-}
-
+// Components (core-owned; Header/Footer now live in the ui parche as
+// parche:widgets/layout/*)
 declare module 'parche:components/ThemeToggle' {
   const Component: typeof import('../components/common/ThemeToggle.astro').default;
   export default Component;
@@ -103,199 +110,23 @@ declare module 'parche:utils/i18n' {
   export * from '../utils/i18n.js';
 }
 
-// Templates
-declare module 'parche:templates/contact' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:templates/content' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Atoms
-declare module 'parche:primitives/Button' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:primitives/Container' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:primitives/Section' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:primitives/Icon' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:primitives/Badge' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:primitives/Eyebrow' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:primitives/Avatar' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:primitives/Divider' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:primitives/Tag' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:primitives/Link' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:primitives/Image' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Hero
-declare module 'parche:widgets/hero/Hero' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:widgets/hero/HeroFullscreen' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Features
-declare module 'parche:widgets/features/Features' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:widgets/features/FeaturesList' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:widgets/features/FeaturesBento' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Stats
-declare module 'parche:widgets/stats/Stats' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Steps
-declare module 'parche:widgets/steps/Steps' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:widgets/steps/StepsHorizontal' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Content
-declare module 'parche:widgets/content/Content' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Pricing
-declare module 'parche:widgets/pricing/Pricing' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:widgets/pricing/PricingTable' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Testimonials
-declare module 'parche:widgets/testimonials/Testimonials' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:widgets/testimonials/TestimonialsCarousel' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:widgets/testimonials/TestimonialsMasonry' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Brands / Logos
-declare module 'parche:widgets/brands/Brands' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-declare module 'parche:widgets/brands/LogoWallMarquee' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — FAQ
-declare module 'parche:widgets/faq/FAQs' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Call to Action
-declare module 'parche:widgets/call-to-action/CallToAction' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Team
-declare module 'parche:widgets/team/Team' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Contact
-declare module 'parche:widgets/contact/Contact' {
-  const Component: import('astro').AstroComponentFactory;
-  export default Component;
-}
-
-// Widgets — Subscribe
-declare module 'parche:widgets/subscribe/Subscribe' {
+// Templates — provided by parches; names aren't known to core, so declare
+// the namespace generically.
+declare module 'parche:templates/*' {
   const Component: import('astro').AstroComponentFactory;
   export default Component;
 }
 
-// Widgets — Gallery
-declare module 'parche:widgets/gallery/Gallery' {
+// Primitives — provided by parches; names aren't known to core, so declare
+// the namespace generically.
+declare module 'parche:primitives/*' {
   const Component: import('astro').AstroComponentFactory;
   export default Component;
 }
 
-// Widgets — Announce
-declare module 'parche:widgets/announce/Announce' {
+// Widgets — provided by parches; names aren't known to core, so declare
+// the namespace generically. Matches nested keys like widgets/hero/Hero.
+declare module 'parche:widgets/*' {
   const Component: import('astro').AstroComponentFactory;
   export default Component;
 }