@uniweb/build 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,210 @@
+# @uniweb/build
+
+Foundation build tooling for the Uniweb Component Web Platform.
+
+## Overview
+
+This package provides build utilities for creating Uniweb Foundations—React component libraries that define the vocabulary and rendering logic for content-driven websites.
+
+## Installation
+
+```bash
+npm install @uniweb/build --save-dev
+```
+
+## Features
+
+- **Component Discovery** - Automatically discovers components from `src/components/*/meta.js`
+- **Entry Generation** - Generates the foundation entry point with all exports
+- **Schema Building** - Creates `schema.json` with full component metadata for editors
+- **Image Processing** - Converts preview images to WebP format with dimension extraction
+- **Vite Plugin** - Integrates seamlessly with Vite builds
+
+## Usage
+
+### Vite Plugin
+
+Add the foundation plugin to your `vite.config.js`:
+
+```js
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { foundationPlugin } from '@uniweb/build'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    foundationPlugin()
+  ],
+  build: {
+    lib: {
+      entry: 'src/_entry.generated.js',
+      formats: ['es'],
+      fileName: 'foundation'
+    },
+    rollupOptions: {
+      external: ['react', 'react-dom', 'react/jsx-runtime']
+    }
+  }
+})
+```
+
+### Programmatic API
+
+```js
+import {
+  discoverComponents,
+  buildSchema,
+  generateEntryPoint,
+  processAllPreviews
+} from '@uniweb/build'
+
+// Discover components in a foundation
+const components = await discoverComponents('./src')
+// => { Hero: { title: 'Hero Banner', ... }, Features: { ... } }
+
+// Build complete schema
+const schema = await buildSchema('./src')
+// => { _self: { name: 'My Foundation' }, Hero: {...}, Features: {...} }
+
+// Generate entry point
+await generateEntryPoint('./src', './src/_entry.generated.js')
+
+// Process preview images
+const { schema: withImages, totalImages } = await processAllPreviews(
+  './src',
+  './dist',
+  schema,
+  true // production mode - converts to webp
+)
+```
+
+## Foundation Structure
+
+Foundations use a folder-based component structure:
+
+```
+src/
+├── meta.js                    # Foundation-level metadata
+├── index.css                  # Global styles (Tailwind)
+├── components/
+│   └── Hero/
+│       ├── index.jsx          # Component implementation
+│       ├── meta.js            # Component metadata
+│       └── previews/          # Preset preview images
+│           └── default.png
+```
+
+### Component Meta File
+
+```js
+// src/components/Hero/meta.js
+export default {
+  title: 'Hero Banner',
+  description: 'A prominent header section',
+  category: 'Headers',
+
+  elements: {
+    title: { label: 'Headline', required: true },
+    subtitle: { label: 'Subtitle' },
+  },
+
+  properties: {
+    alignment: {
+      type: 'select',
+      label: 'Text Alignment',
+      options: [
+        { value: 'center', label: 'Center' },
+        { value: 'left', label: 'Left' },
+      ],
+      default: 'center',
+    },
+  },
+
+  presets: {
+    default: { label: 'Default', properties: {} },
+    dark: { label: 'Dark Theme', properties: { theme: 'dark' } },
+  },
+}
+```
+
+### Foundation Meta File
+
+```js
+// src/meta.js
+export default {
+  name: 'My Foundation',
+  description: 'Components for marketing websites',
+
+  // Runtime props available to all components
+  props: {
+    themeToggleEnabled: true,
+  },
+
+  // Foundation-wide style configuration
+  styleFields: [
+    {
+      id: 'primary-color',
+      type: 'color',
+      label: 'Primary Color',
+      default: '#3b82f6',
+    },
+  ],
+}
+```
+
+## Build Output
+
+After building, your foundation will contain:
+
+```
+dist/
+├── foundation.js      # Bundled components (~6KB typical)
+├── foundation.js.map  # Source map
+├── schema.json        # Full metadata for editors
+└── assets/
+    └── Hero/
+        └── default.webp  # Processed preview images
+```
+
+## API Reference
+
+### Schema Functions
+
+| Function | Description |
+|----------|-------------|
+| `discoverComponents(srcDir)` | Discover all exposed components |
+| `loadComponentMeta(componentDir)` | Load meta file for a component |
+| `loadFoundationMeta(srcDir)` | Load foundation-level meta |
+| `buildSchema(srcDir)` | Build complete schema object |
+| `buildRuntimeConfig(srcDir)` | Build minimal runtime config |
+
+### Entry Generation
+
+| Function | Description |
+|----------|-------------|
+| `generateEntryPoint(srcDir, outputPath)` | Generate foundation entry file |
+
+### Image Processing
+
+| Function | Description |
+|----------|-------------|
+| `processComponentPreviews(componentDir, name, outputDir, isProduction)` | Process one component's previews |
+| `processAllPreviews(srcDir, outputDir, schema, isProduction)` | Process all preview images |
+
+### Vite Plugins
+
+| Plugin | Description |
+|--------|-------------|
+| `foundationPlugin(options)` | Combined dev + build plugin |
+| `foundationBuildPlugin(options)` | Build-only plugin |
+| `foundationDevPlugin(options)` | Dev-only plugin with HMR |
+
+## Related Packages
+
+- [`uniweb`](https://github.com/uniweb/cli) - CLI for creating Uniweb projects
+- [`@uniweb/runtime`](https://github.com/uniweb/runtime) - Runtime loader for sites
+
+## License
+
+Apache 2.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@uniweb/build",
+  "version": "0.1.0",
+  "description": "Foundation build tooling for the Uniweb Component Web Platform",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./schema": "./src/schema.js",
+    "./images": "./src/images.js",
+    "./generate-entry": "./src/generate-entry.js",
+    "./vite-plugin": "./src/vite-foundation-plugin.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "uniweb",
+    "foundation",
+    "build",
+    "vite",
+    "components"
+  ],
+  "author": "Proximify",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uniweb/build.git"
+  },
+  "homepage": "https://github.com/uniweb/build#readme",
+  "bugs": {
+    "url": "https://github.com/uniweb/build/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "sharp": "^0.33.2"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  }
+}

package/src/generate-entry.js

@@ -0,0 +1,200 @@
+/**
+ * Foundation Entry Point Generator
+ *
+ * Auto-generates the foundation entry point based on discovered components.
+ * The generated file exports components and runtime configuration.
+ */
+
+import { writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import {
+  discoverComponents,
+  loadFoundationMeta,
+  extractRuntimeConfig,
+} from './schema.js'
+
+/**
+ * Generate the entry point source code
+ */
+function generateEntrySource(componentNames, runtimeConfig, options = {}) {
+  const { includeCss = true, cssPath = './index.css', componentExtensions = {} } = options
+
+  const imports = []
+  const exports = []
+
+  // CSS import
+  if (includeCss) {
+    imports.push(`import '${cssPath}'`)
+  }
+
+  // Component imports (use detected extension or default to .js)
+  for (const name of componentNames) {
+    const ext = componentExtensions[name] || 'js'
+    imports.push(`import ${name} from './components/${name}/index.${ext}'`)
+  }
+
+  // Build components object
+  const componentsObj = `const components = {\n  ${componentNames.join(',\n  ')},\n}`
+
+  // Runtime config (serialized)
+  const configStr = JSON.stringify(runtimeConfig, null, 2)
+    .split('\n')
+    .map((line, i) => (i === 0 ? line : '  ' + line))
+    .join('\n')
+
+  const runtimeConfigBlock = `
+// Runtime configuration (extracted from meta files)
+// Only includes properties needed at render time
+const runtimeConfig = ${configStr}`
+
+  // Export functions
+  const exportFunctions = `
+/**
+ * Get a component by name
+ */
+export function getComponent(name) {
+  return components[name]
+}
+
+/**
+ * List all available component names
+ */
+export function listComponents() {
+  return Object.keys(components)
+}
+
+/**
+ * Get runtime config for a specific component
+ * Returns input schema and other render-time properties
+ */
+export function getComponentConfig(name) {
+  return runtimeConfig.components[name] || {}
+}
+
+/**
+ * Get foundation-level runtime config
+ */
+export function getFoundationConfig() {
+  return runtimeConfig.foundation
+}
+
+/**
+ * Get all component schemas (for compatibility)
+ * Note: Full schemas are in schema.json, this only returns runtime-relevant config
+ */
+export function getAllSchemas() {
+  const schemas = {}
+  for (const name of Object.keys(components)) {
+    if (components[name].schema) {
+      schemas[name] = components[name].schema
+    }
+  }
+  return schemas
+}
+
+/**
+ * Get schema for a specific component (for compatibility)
+ */
+export function getSchema(name) {
+  return components[name]?.schema
+}`
+
+  // Named exports for direct imports
+  const namedExports = componentNames.length > 0
+    ? `\n// Named exports for direct imports\nexport { ${componentNames.join(', ')} }`
+    : ''
+
+  return `// Auto-generated foundation entry point
+// DO NOT EDIT - This file is regenerated during build
+
+${imports.join('\n')}
+
+${componentsObj}
+${runtimeConfigBlock}
+${exportFunctions}
+${namedExports}
+`
+}
+
+/**
+ * Detect the index file extension for a component
+ */
+function detectComponentExtension(srcDir, componentName) {
+  const basePath = join(srcDir, 'components', componentName)
+  for (const ext of ['jsx', 'tsx', 'js', 'ts']) {
+    if (existsSync(join(basePath, `index.${ext}`))) {
+      return ext
+    }
+  }
+  return 'js' // default
+}
+
+/**
+ * Generate the foundation entry point file
+ */
+export async function generateEntryPoint(srcDir, outputPath = null) {
+  // Discover components
+  const components = await discoverComponents(srcDir)
+  const componentNames = Object.keys(components).sort()
+
+  if (componentNames.length === 0) {
+    console.warn('Warning: No exposed components found')
+  }
+
+  // Detect extensions for each component
+  const componentExtensions = {}
+  for (const name of componentNames) {
+    componentExtensions[name] = detectComponentExtension(srcDir, name)
+  }
+
+  // Load foundation meta and build runtime config
+  const foundationMeta = await loadFoundationMeta(srcDir)
+
+  const runtimeConfig = {
+    foundation: extractRuntimeConfig(foundationMeta),
+    components: {},
+  }
+
+  for (const [name, meta] of Object.entries(components)) {
+    const config = extractRuntimeConfig(meta)
+    if (Object.keys(config).length > 0) {
+      runtimeConfig.components[name] = config
+    }
+  }
+
+  // Check if CSS exists
+  const cssExists = existsSync(join(srcDir, 'index.css'))
+
+  // Generate source
+  const source = generateEntrySource(componentNames, runtimeConfig, {
+    includeCss: cssExists,
+    componentExtensions,
+  })
+
+  // Write to file
+  const output = outputPath || join(srcDir, '_entry.generated.js')
+  await mkdir(dirname(output), { recursive: true })
+  await writeFile(output, source, 'utf-8')
+
+  console.log(`Generated entry point: ${output}`)
+  console.log(`  - ${componentNames.length} components: ${componentNames.join(', ')}`)
+
+  return {
+    outputPath: output,
+    componentNames,
+    runtimeConfig,
+  }
+}
+
+/**
+ * Check if entry point needs regeneration
+ * (Compare discovered components with existing generated file)
+ */
+export async function shouldRegenerateEntry(srcDir, entryPath) {
+  if (!existsSync(entryPath)) return true
+
+  // Could add more sophisticated checking here
+  // For now, always regenerate during build
+  return true
+}

package/src/images.js

@@ -0,0 +1,212 @@
+/**
+ * Image Processing Utilities
+ *
+ * Handles preview image discovery, conversion to webp, and metadata extraction.
+ */
+
+import { readdir, mkdir, copyFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, extname, basename } from 'node:path'
+import sharp from 'sharp'
+
+// Supported image extensions
+const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webp', '.gif']
+
+/**
+ * Check if a file is an image based on extension
+ */
+function isImageFile(filename) {
+  const ext = extname(filename).toLowerCase()
+  return IMAGE_EXTENSIONS.includes(ext)
+}
+
+/**
+ * Get image metadata (dimensions)
+ */
+async function getImageMetadata(imagePath) {
+  try {
+    const metadata = await sharp(imagePath).metadata()
+    return {
+      width: metadata.width,
+      height: metadata.height,
+      format: metadata.format,
+    }
+  } catch (error) {
+    console.warn(`Warning: Could not read metadata for ${imagePath}:`, error.message)
+    return null
+  }
+}
+
+/**
+ * Convert an image to webp format
+ */
+async function convertToWebp(inputPath, outputPath, options = {}) {
+  const { quality = 80 } = options
+
+  try {
+    await sharp(inputPath)
+      .webp({ quality })
+      .toFile(outputPath)
+    return true
+  } catch (error) {
+    console.warn(`Warning: Could not convert ${inputPath} to webp:`, error.message)
+    return false
+  }
+}
+
+/**
+ * Process preview images for a single component
+ *
+ * @param {string} componentDir - Path to component directory (e.g., src/components/Hero)
+ * @param {string} componentName - Component name
+ * @param {string} outputDir - Output directory for processed images
+ * @param {boolean} isProduction - Whether to convert to webp
+ * @returns {Object} Map of preset name to image info
+ */
+export async function processComponentPreviews(componentDir, componentName, outputDir, isProduction = true) {
+  const previewsDir = join(componentDir, 'previews')
+  const previews = {}
+
+  if (!existsSync(previewsDir)) {
+    return previews
+  }
+
+  // Create output directory
+  const componentOutputDir = join(outputDir, 'assets', componentName)
+  await mkdir(componentOutputDir, { recursive: true })
+
+  // Get all image files
+  const files = await readdir(previewsDir)
+  const imageFiles = files.filter(isImageFile)
+
+  for (const file of imageFiles) {
+    const inputPath = join(previewsDir, file)
+    const presetName = basename(file, extname(file))
+    const originalExt = extname(file).toLowerCase()
+
+    // Get original metadata
+    const metadata = await getImageMetadata(inputPath)
+    if (!metadata) continue
+
+    let outputFilename
+    let outputPath
+    let finalFormat
+
+    if (isProduction && originalExt !== '.webp') {
+      // Convert to webp in production
+      outputFilename = `${presetName}.webp`
+      outputPath = join(componentOutputDir, outputFilename)
+      finalFormat = 'webp'
+
+      const success = await convertToWebp(inputPath, outputPath)
+      if (!success) {
+        // Fall back to copying original
+        outputFilename = file
+        outputPath = join(componentOutputDir, file)
+        finalFormat = originalExt.slice(1)
+        await copyFile(inputPath, outputPath)
+      }
+    } else {
+      // Copy as-is in development or if already webp
+      outputFilename = file
+      outputPath = join(componentOutputDir, file)
+      finalFormat = originalExt.slice(1)
+      await copyFile(inputPath, outputPath)
+    }
+
+    previews[presetName] = {
+      path: `assets/${componentName}/${outputFilename}`,
+      width: metadata.width,
+      height: metadata.height,
+      type: finalFormat,
+    }
+  }
+
+  return previews
+}
+
+/**
+ * Process all preview images for a foundation
+ *
+ * @param {string} srcDir - Source directory (e.g., src/)
+ * @param {string} outputDir - Output directory (e.g., dist/)
+ * @param {Object} schema - Schema object to update with image info
+ * @param {boolean} isProduction - Whether to convert to webp
+ * @returns {Object} Updated schema with image references
+ */
+export async function processAllPreviews(srcDir, outputDir, schema, isProduction = true) {
+  const componentsDir = join(srcDir, 'components')
+
+  if (!existsSync(componentsDir)) {
+    return schema
+  }
+
+  const entries = await readdir(componentsDir, { withFileTypes: true })
+  let totalImages = 0
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+
+    const componentName = entry.name
+    const componentDir = join(componentsDir, componentName)
+
+    // Skip if component not in schema
+    if (!schema[componentName]) continue
+
+    // Process preview images
+    const previews = await processComponentPreviews(
+      componentDir,
+      componentName,
+      outputDir,
+      isProduction
+    )
+
+    const previewCount = Object.keys(previews).length
+    if (previewCount > 0) {
+      totalImages += previewCount
+
+      // Attach preview info to presets in schema
+      if (schema[componentName].presets) {
+        for (const [presetName, previewInfo] of Object.entries(previews)) {
+          if (schema[componentName].presets[presetName]) {
+            schema[componentName].presets[presetName].image = previewInfo
+          } else {
+            // Preview exists but no matching preset - still include it
+            // This allows standalone preview images
+            if (!schema[componentName].images) {
+              schema[componentName].images = {}
+            }
+            schema[componentName].images[presetName] = previewInfo
+          }
+        }
+      } else {
+        // No presets defined, add as standalone images
+        schema[componentName].images = previews
+      }
+    }
+  }
+
+  return { schema, totalImages }
+}
+
+/**
+ * Copy a single image with optional conversion
+ */
+export async function processImage(inputPath, outputPath, options = {}) {
+  const { convertToWebp: shouldConvert = false, quality = 80 } = options
+
+  const ext = extname(inputPath).toLowerCase()
+
+  if (shouldConvert && ext !== '.webp') {
+    const webpPath = outputPath.replace(/\.[^.]+$/, '.webp')
+    const success = await convertToWebp(inputPath, webpPath, { quality })
+    if (success) {
+      return { path: webpPath, converted: true }
+    }
+  }
+
+  // Copy as-is
+  await mkdir(join(outputPath, '..'), { recursive: true })
+  await copyFile(inputPath, outputPath)
+  return { path: outputPath, converted: false }
+}

package/src/index.js

@@ -0,0 +1,39 @@
+/**
+ * @uniweb/build - Foundation Build Tooling
+ *
+ * Build utilities for Uniweb Foundations.
+ */
+
+// Schema discovery and loading
+export {
+  loadComponentMeta,
+  loadFoundationMeta,
+  discoverComponents,
+  extractRuntimeConfig,
+  buildSchema,
+  buildRuntimeConfig,
+  getExposedComponents,
+} from './schema.js'
+
+// Entry point generation
+export {
+  generateEntryPoint,
+  shouldRegenerateEntry,
+} from './generate-entry.js'
+
+// Image processing
+export {
+  processComponentPreviews,
+  processAllPreviews,
+  processImage,
+} from './images.js'
+
+// Vite plugins
+export {
+  foundationPlugin,
+  foundationBuildPlugin,
+  foundationDevPlugin,
+} from './vite-foundation-plugin.js'
+
+// Default export is the combined Vite plugin
+export { default } from './vite-foundation-plugin.js'

package/src/schema.js

@@ -0,0 +1,304 @@
+/**
+ * Schema Discovery and Loading Utilities
+ *
+ * Discovers component meta files, loads them, and extracts
+ * runtime-relevant configuration.
+ */
+
+import { readdir, readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, basename } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// Meta file names in order of preference
+const META_FILE_NAMES = ['meta.js', 'config.js', 'config.yml', 'meta.yml']
+
+// Keys that should be extracted for runtime (embedded in foundation.js)
+const RUNTIME_KEYS = ['input', 'props']
+
+/**
+ * Simple YAML parser for backwards compatibility
+ * Supports basic key-value, nested objects, and arrays
+ */
+function parseYaml(content) {
+  const lines = content.split('\n')
+  return parseYamlLines(lines, 0).value
+}
+
+function getIndent(line) {
+  const match = line.match(/^(\s*)/)
+  return match ? match[1].length : 0
+}
+
+function parseYamlValue(value) {
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+      (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1)
+  }
+  if (trimmed === 'true') return true
+  if (trimmed === 'false') return false
+  if (!isNaN(Number(trimmed)) && trimmed !== '') return Number(trimmed)
+  return trimmed
+}
+
+function parseYamlLines(lines, startIndex, baseIndent = 0) {
+  const result = {}
+  let i = startIndex
+
+  while (i < lines.length) {
+    const line = lines[i]
+    const trimmed = line.trim()
+
+    if (!trimmed || trimmed.startsWith('#')) {
+      i++
+      continue
+    }
+
+    const indent = getIndent(line)
+    if (indent < baseIndent && i > startIndex) break
+    if (trimmed.startsWith('- ')) {
+      i++
+      continue
+    }
+
+    const colonIndex = trimmed.indexOf(':')
+    if (colonIndex === -1) {
+      i++
+      continue
+    }
+
+    const key = trimmed.slice(0, colonIndex).trim()
+    const valueAfterColon = trimmed.slice(colonIndex + 1).trim()
+
+    const nextLine = lines[i + 1]
+    const nextTrimmed = nextLine?.trim()
+    const nextIndent = nextLine ? getIndent(nextLine) : 0
+
+    if (nextTrimmed?.startsWith('- ') && nextIndent > indent) {
+      const arrayResult = parseYamlArray(lines, i + 1, nextIndent)
+      result[key] = arrayResult.value
+      i = arrayResult.endIndex
+    } else if (!valueAfterColon && nextIndent > indent) {
+      const nestedResult = parseYamlLines(lines, i + 1, nextIndent)
+      result[key] = nestedResult.value
+      i = nestedResult.endIndex
+    } else {
+      result[key] = parseYamlValue(valueAfterColon)
+      i++
+    }
+  }
+
+  return { value: result, endIndex: i }
+}
+
+function parseYamlArray(lines, startIndex, baseIndent) {
+  const result = []
+  let i = startIndex
+
+  while (i < lines.length) {
+    const line = lines[i]
+    const trimmed = line.trim()
+
+    if (!trimmed || trimmed.startsWith('#')) {
+      i++
+      continue
+    }
+
+    const indent = getIndent(line)
+    if (indent < baseIndent) break
+
+    if (trimmed.startsWith('- ')) {
+      const afterDash = trimmed.slice(2)
+      const colonIndex = afterDash.indexOf(':')
+
+      if (colonIndex !== -1) {
+        const key = afterDash.slice(0, colonIndex).trim()
+        const value = afterDash.slice(colonIndex + 1).trim()
+        const obj = { [key]: parseYamlValue(value) }
+        const itemIndent = indent + 2
+        i++
+
+        while (i < lines.length) {
+          const propLine = lines[i]
+          const propTrimmed = propLine?.trim()
+
+          if (!propTrimmed || propTrimmed.startsWith('#')) {
+            i++
+            continue
+          }
+
+          const propIndent = getIndent(propLine)
+          if (propIndent < itemIndent || propTrimmed.startsWith('- ')) break
+
+          const propColonIndex = propTrimmed.indexOf(':')
+          if (propColonIndex !== -1) {
+            const propKey = propTrimmed.slice(0, propColonIndex).trim()
+            const propValue = propTrimmed.slice(propColonIndex + 1).trim()
+            obj[propKey] = parseYamlValue(propValue)
+          }
+          i++
+        }
+
+        result.push(obj)
+      } else {
+        result.push(parseYamlValue(afterDash))
+        i++
+      }
+    } else {
+      break
+    }
+  }
+
+  return { value: result, endIndex: i }
+}
+
+/**
+ * Load a meta file (JS or YAML)
+ */
+async function loadMetaFile(filePath) {
+  if (filePath.endsWith('.js')) {
+    // Dynamic import for JS files
+    const fileUrl = pathToFileURL(filePath).href
+    const module = await import(fileUrl)
+    return module.default
+  } else {
+    // Parse YAML
+    const content = await readFile(filePath, 'utf-8')
+    return parseYaml(content)
+  }
+}
+
+/**
+ * Find and load meta file for a component directory
+ * Returns null if no meta file found
+ */
+export async function loadComponentMeta(componentDir) {
+  for (const fileName of META_FILE_NAMES) {
+    const filePath = join(componentDir, fileName)
+    if (existsSync(filePath)) {
+      try {
+        const meta = await loadMetaFile(filePath)
+        return { meta, fileName, filePath }
+      } catch (error) {
+        console.warn(`Warning: Failed to load ${filePath}:`, error.message)
+        return null
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Load foundation-level meta file
+ */
+export async function loadFoundationMeta(srcDir) {
+  for (const fileName of META_FILE_NAMES) {
+    const filePath = join(srcDir, fileName)
+    if (existsSync(filePath)) {
+      try {
+        return await loadMetaFile(filePath)
+      } catch (error) {
+        console.warn(`Warning: Failed to load foundation meta ${filePath}:`, error.message)
+        return {}
+      }
+    }
+  }
+  return {}
+}
+
+/**
+ * Discover all exposed components in a foundation
+ * Returns map of componentName -> meta
+ */
+export async function discoverComponents(srcDir) {
+  const componentsDir = join(srcDir, 'components')
+
+  if (!existsSync(componentsDir)) {
+    return {}
+  }
+
+  const entries = await readdir(componentsDir, { withFileTypes: true })
+  const components = {}
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+
+    const componentDir = join(componentsDir, entry.name)
+    const result = await loadComponentMeta(componentDir)
+
+    if (result && result.meta) {
+      // Check if explicitly not exposed
+      if (result.meta.exposed === false) {
+        continue
+      }
+
+      components[entry.name] = {
+        name: entry.name,
+        ...result.meta,
+      }
+    }
+  }
+
+  return components
+}
+
+/**
+ * Extract runtime-relevant config from meta
+ * Only includes keys that are needed at render time
+ */
+export function extractRuntimeConfig(meta) {
+  if (!meta) return {}
+
+  const config = {}
+  for (const key of RUNTIME_KEYS) {
+    if (meta[key] !== undefined) {
+      config[key] = meta[key]
+    }
+  }
+  return config
+}
+
+/**
+ * Build complete schema for a foundation
+ * Returns { _self: foundationMeta, ComponentName: componentMeta, ... }
+ */
+export async function buildSchema(srcDir) {
+  const foundationMeta = await loadFoundationMeta(srcDir)
+  const components = await discoverComponents(srcDir)
+
+  return {
+    _self: foundationMeta,
+    ...components,
+  }
+}
+
+/**
+ * Build runtime config (minimal, for embedding in foundation.js)
+ */
+export async function buildRuntimeConfig(srcDir) {
+  const foundationMeta = await loadFoundationMeta(srcDir)
+  const components = await discoverComponents(srcDir)
+
+  const componentConfigs = {}
+  for (const [name, meta] of Object.entries(components)) {
+    const config = extractRuntimeConfig(meta)
+    if (Object.keys(config).length > 0) {
+      componentConfigs[name] = config
+    }
+  }
+
+  return {
+    foundation: extractRuntimeConfig(foundationMeta),
+    components: componentConfigs,
+  }
+}
+
+/**
+ * Get list of exposed component names
+ */
+export async function getExposedComponents(srcDir) {
+  const components = await discoverComponents(srcDir)
+  return Object.keys(components)
+}

package/src/vite-foundation-plugin.js

@@ -0,0 +1,155 @@
+/**
+ * Vite Plugin for Foundation Builds
+ *
+ * Handles:
+ * - Auto-generating entry point from discovered components
+ * - Building schema.json from meta files
+ * - Processing preview images for presets
+ */
+
+import { writeFile, readFile, readdir, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, resolve, relative } from 'node:path'
+import { buildSchema, discoverComponents } from './schema.js'
+import { generateEntryPoint } from './generate-entry.js'
+import { processAllPreviews } from './images.js'
+
+/**
+ * Build schema.json with preview image references
+ */
+async function buildSchemaWithPreviews(srcDir, outDir, isProduction) {
+  const schema = await buildSchema(srcDir)
+
+  // Process preview images
+  const { schema: schemaWithImages, totalImages } = await processAllPreviews(
+    srcDir,
+    outDir,
+    schema,
+    isProduction
+  )
+
+  if (totalImages > 0) {
+    console.log(`Processed ${totalImages} preview images`)
+  }
+
+  return schemaWithImages
+}
+
+/**
+ * Vite plugin for foundation builds
+ */
+export function foundationBuildPlugin(options = {}) {
+  const {
+    srcDir = 'src',
+    generateEntry = true,
+    entryFileName = '_entry.generated.js',
+  } = options
+
+  let resolvedSrcDir
+  let resolvedOutDir
+  let isProduction
+
+  return {
+    name: 'uniweb-foundation-build',
+
+    async configResolved(config) {
+      resolvedSrcDir = resolve(config.root, srcDir)
+      resolvedOutDir = config.build.outDir
+      isProduction = config.mode === 'production'
+    },
+
+    async buildStart() {
+      if (!generateEntry) return
+
+      // Generate entry point before build starts
+      const entryPath = join(resolvedSrcDir, entryFileName)
+      await generateEntryPoint(resolvedSrcDir, entryPath)
+    },
+
+    async writeBundle() {
+      // After bundle is written, generate schema.json
+      const outDir = resolve(resolvedOutDir)
+
+      const schema = await buildSchemaWithPreviews(
+        resolvedSrcDir,
+        outDir,
+        isProduction
+      )
+
+      const schemaPath = join(outDir, 'schema.json')
+      await writeFile(schemaPath, JSON.stringify(schema, null, 2), 'utf-8')
+
+      console.log(`Generated schema.json with ${Object.keys(schema).length - 1} components`)
+    },
+  }
+}
+
+/**
+ * Vite plugin for development mode
+ * Watches meta files and regenerates entry on change
+ */
+export function foundationDevPlugin(options = {}) {
+  const {
+    srcDir = 'src',
+    entryFileName = '_entry.generated.js',
+  } = options
+
+  let resolvedSrcDir
+
+  return {
+    name: 'uniweb-foundation-dev',
+
+    configResolved(config) {
+      resolvedSrcDir = resolve(config.root, srcDir)
+    },
+
+    async buildStart() {
+      // Generate entry point at dev server start
+      const entryPath = join(resolvedSrcDir, entryFileName)
+      await generateEntryPoint(resolvedSrcDir, entryPath)
+    },
+
+    async handleHotUpdate({ file, server }) {
+      // Regenerate entry when meta files change
+      if (file.includes('/components/') && file.match(/meta\.(js|yml)$|config\.(js|yml)$/)) {
+        console.log('Meta file changed, regenerating entry...')
+        const entryPath = join(resolvedSrcDir, entryFileName)
+        await generateEntryPoint(resolvedSrcDir, entryPath)
+
+        // Trigger full reload since entry changed
+        server.ws.send({ type: 'full-reload' })
+      }
+    },
+  }
+}
+
+/**
+ * Combined plugin that works for both dev and build
+ */
+export function foundationPlugin(options = {}) {
+  const buildPlugin = foundationBuildPlugin(options)
+  const devPlugin = foundationDevPlugin(options)
+
+  return {
+    name: 'uniweb-foundation',
+
+    configResolved(config) {
+      buildPlugin.configResolved?.(config)
+      devPlugin.configResolved?.(config)
+    },
+
+    async buildStart() {
+      await devPlugin.buildStart?.()
+    },
+
+    async writeBundle(...args) {
+      await buildPlugin.writeBundle?.(...args)
+    },
+
+    handleHotUpdate(...args) {
+      return devPlugin.handleHotUpdate?.(...args)
+    },
+  }
+}
+
+export default foundationPlugin