@uniweb/runtime 0.1.2 → 0.2.2

package/README.md

@@ -1,10 +1,12 @@
 # @uniweb/runtime
 
-Runtime loader and Vite plugins for Uniweb sites.
+Minimal runtime for loading Uniweb foundations and orchestrating rendering.
 
 ## Overview
 
-This package provides the runtime environment for Uniweb sites—content-driven websites that load Foundation components dynamically. It bridges site content with Foundation components and provides Vite plugins for development.
+This package provides the browser-side runtime for Uniweb sites. It loads foundations dynamically and renders content using React Router.
+
+For Vite build plugins, see [`@uniweb/build`](https://github.com/uniweb/build).
 
 ## Installation
 
@@ -12,13 +14,6 @@ This package provides the runtime environment for Uniweb sites—content-driven
 npm install @uniweb/runtime
 ```
 
-## Features
-
-- **Foundation Loading** - Load Foundations via dynamic import or import maps
-- **Content Rendering** - Render pages from structured content (JSON/YAML)
-- **Vite Plugins** - Collect site content and serve foundations in development
-- **React Integration** - Built on React with React Router for navigation
-
 ## Usage
 
 ### Runtime Loading
@@ -26,7 +21,7 @@ npm install @uniweb/runtime
 Initialize the runtime with a Foundation URL:
 
 ```jsx
-import { initRuntime } from '@uniweb/runtime'
+import initRuntime from '@uniweb/runtime'
 
 // Load foundation from URL
 initRuntime('/foundation/foundation.js', {
@@ -40,194 +35,76 @@ initRuntime({
 })
 ```
 
-### Vite Plugins for Sites
-
-Use the Vite plugins to collect content and optionally serve a foundation:
-
-```js
-// vite.config.js
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import { siteContentPlugin, foundationPlugin } from '@uniweb/runtime/vite'
-
-export default defineConfig({
-  plugins: [
-    react(),
-
-    // Collect content from pages/ directory
-    siteContentPlugin({
-      sitePath: './',
-      inject: true,  // Inject into HTML
-    }),
-
-    // Optional: Serve foundation in dev mode
-    foundationPlugin({
-      name: 'my-foundation',
-      path: '../my-foundation',
-      serve: '/foundation',
-    }),
-  ]
-})
-```
-
-### Site Content Structure
-
-Sites use a pages/ directory structure:
-
-```
-site/
-├── site.yml           # Site configuration
-├── theme.yml          # Theme configuration
-└── pages/
-    ├── @header/       # Special: header section
-    │   └── 1.md
-    ├── @footer/       # Special: footer section
-    │   └── 1.md
-    ├── home/          # Home page (route: /)
-    │   ├── page.yml   # Page metadata
-    │   ├── 1.md       # First section
-    │   └── 2.md       # Second section
-    └── about/         # About page (route: /about)
-        ├── page.yml
-        └── 1.md
-```
-
-### Section Markdown Format
-
-Each `.md` file is a section with YAML frontmatter for configuration and markdown body for content:
-
-```markdown
----
-component: Hero
-preset: default
-theme: dark
----
+### Static Bundling
 
-# Welcome to Our Site
+Foundation imported directly and bundled with the site:
 
-Building the future together.
+```jsx
+import * as Foundation from '@my-org/my-foundation'
+import initRuntime from '@uniweb/runtime'
 
-[Get Started](#features)
+initRuntime(Foundation)
 ```
 
-The frontmatter specifies the component and configuration parameters. The markdown body contains the actual content, which is semantically parsed into structured data (headings → titles, paragraphs → descriptions, links → CTAs).
-
-## API Reference
-
-### Runtime Functions
-
-| Function | Description |
-|----------|-------------|
-| `initRuntime(source, options)` | Initialize runtime with foundation |
-| `initRTE(source, options)` | Alias for initRuntime |
-
-### Exported Components
-
-| Component | Description |
-|-----------|-------------|
-| `Link` | Router-aware link component |
-| `SafeHtml` | Safe HTML rendering |
-| `ChildBlocks` | Render child sections |
-| `ErrorBoundary` | Error boundary wrapper |
-
-### Vite Plugins
+## API
 
-| Plugin | Description |
-|--------|-------------|
-| `siteContentPlugin(options)` | Collect and inject site content |
-| `foundationPlugin(options)` | Build and serve foundation in dev |
-| `collectSiteContent(sitePath)` | Programmatic content collection |
+### initRuntime(source, options)
 
-### Plugin Options
+Initialize the runtime with a foundation.
 
-**siteContentPlugin:**
-```js
-{
-  sitePath: './',           // Path to site directory
-  pagesDir: 'pages',        // Pages subdirectory
-  inject: true,             // Inject into HTML
-  filename: 'site-content.json',  // Output filename
-  watch: true               // Watch for changes (dev)
-}
-```
+**source** - One of:
+- URL string to foundation module
+- Object with `{ url, cssUrl }`
+- Foundation module object (for static bundling)
 
-**foundationPlugin:**
+**options:**
 ```js
 {
-  name: 'foundation',       // Foundation name (for logs)
-  path: '../foundation',    // Path to foundation package
-  serve: '/foundation',     // URL path to serve from
-  watch: true,              // Watch for changes
-  buildOnStart: true        // Build when dev server starts
+  development: false,    // Enable dev mode (StrictMode, verbose errors)
+  configData: null,      // Site content (or reads from DOM)
+  basename: undefined    // React Router basename
 }
 ```
 
-## Core Classes
-
-### Uniweb
-
-The main runtime instance (available as `globalThis.uniweb`):
-
-```js
-uniweb.getComponent(name)     // Get component from foundation
-uniweb.listComponents()       // List available components
-uniweb.activeWebsite          // Current website instance
-```
-
-### Website
+For core classes (`Uniweb`, `Website`, `Block`, etc.), import from [`@uniweb/core`](https://github.com/uniweb/core).
 
-Manages pages, theme, and localization:
+## Architecture
 
-```js
-website.getPage(route)        // Get page by route
-website.setActivePage(route)  // Navigate to page
-website.localize(value)       // Localize a value
-website.getLanguage()         // Get current language
 ```
-
-### Block
-
-Represents a section on a page:
-
-```js
-block.initComponent()         // Initialize foundation component
-block.getBlockContent()       // Get structured content
-block.getBlockProperties()    // Get configuration properties
-block.getBlockLinks()         // Get links from content
+@uniweb/runtime (browser)
+    │
+    ├── Loads foundation dynamically
+    ├── Creates Uniweb instance via @uniweb/core
+    └── Orchestrates React/Router rendering
 ```
 
-## Two Loading Modes
+Foundations should:
+- Import components from `@uniweb/kit` (bundled)
+- Mark `@uniweb/core` as external (provided by runtime)
 
-### Runtime Loading (Import Maps)
+## Build Plugins
 
-Foundation loaded at runtime via dynamic import. React provided by host via import map.
+Vite plugins have moved to `@uniweb/build`:
 
-```html
-<script type="importmap">
-{
-  "imports": {
-    "react": "https://esm.sh/react@18",
-    "react-dom": "https://esm.sh/react-dom@18"
-  }
-}
-</script>
-```
-
-### Static Bundling
-
-Foundation imported directly and bundled with the site.
-
-```jsx
-import * as Foundation from '@my-org/my-foundation'
-import { initRuntime } from '@uniweb/runtime'
+```js
+// vite.config.js
+import { siteContentPlugin } from '@uniweb/build/site'
+import { foundationDevPlugin } from '@uniweb/build/dev'
 
-initRuntime(Foundation)
+export default defineConfig({
+  plugins: [
+    siteContentPlugin({ sitePath: './', inject: true }),
+    foundationDevPlugin({ path: '../foundation', serve: '/foundation' }),
+  ]
+})
 ```
 
 ## Related Packages
 
-- [`uniweb`](https://github.com/uniweb/cli) - CLI for creating Uniweb projects
-- [`@uniweb/build`](https://github.com/uniweb/build) - Foundation build tooling
+- [`@uniweb/core`](https://github.com/uniweb/core) - Core classes (Uniweb, Website, Block)
+- [`@uniweb/kit`](https://github.com/uniweb/kit) - Component library for foundations
+- [`@uniweb/build`](https://github.com/uniweb/build) - Vite build plugins
+- [`uniweb`](https://github.com/uniweb/cli) - CLI for creating projects
 
 ## License
 

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.1.2",
-  "description": "Runtime loader and Vite plugins for Uniweb sites",
+  "version": "0.2.2",
+  "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
-    ".": "./src/index.jsx",
-    "./vite": "./src/vite/index.js"
+    ".": "./src/index.jsx"
   },
   "files": [
     "src"
@@ -13,9 +12,8 @@
   "keywords": [
     "uniweb",
     "runtime",
-    "vite",
     "react",
-    "components"
+    "foundation"
   ],
   "author": "Proximify",
   "license": "Apache-2.0",
@@ -31,21 +29,11 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "js-yaml": "^4.1.0",
-    "@uniweb/semantic-parser": "1.0.1"
+    "@uniweb/core": "0.1.5"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
-    "react-router-dom": "^6.0.0 || ^7.0.0",
-    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0"
-  },
-  "peerDependenciesMeta": {
-    "vite": {
-      "optional": true
-    }
-  },
-  "optionalDependencies": {
-    "@uniweb/content-reader": "1.0.1"
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "react-router-dom": "^6.0.0 || ^7.0.0"
   }
 }

package/src/components/Blocks.jsx

@@ -0,0 +1,26 @@
+/**
+ * Blocks
+ *
+ * Renders an array of blocks for a layout area (header, body, footer, panels).
+ * Used by the Layout component to pre-render each area.
+ */
+
+import React from 'react'
+import BlockRenderer from './BlockRenderer.jsx'
+
+/**
+ * Render a list of blocks
+ *
+ * @param {Object} props
+ * @param {Block[]} props.blocks - Array of Block instances to render
+ * @param {Object} [props.extra] - Extra props to pass to each block
+ */
+export default function Blocks({ blocks, extra = {} }) {
+  if (!blocks || blocks.length === 0) return null
+
+  return blocks.map((block, index) => (
+    <React.Fragment key={block.id || index}>
+      <BlockRenderer block={block} extra={extra} />
+    </React.Fragment>
+  ))
+}

package/src/components/Layout.jsx

@@ -0,0 +1,100 @@
+/**
+ * Layout
+ *
+ * Orchestrates page rendering by assembling layout areas (header, body, footer, panels).
+ * Supports foundation-provided custom Layout components via website.getRemoteLayout().
+ *
+ * Layout Areas:
+ * - header: Top navigation, branding (from @header page)
+ * - body: Main page content (from page sections)
+ * - footer: Bottom navigation, copyright (from @footer page)
+ * - left: Left sidebar/panel (from @left page)
+ * - right: Right sidebar/panel (from @right page)
+ *
+ * Custom Layouts:
+ * Foundations can export a Layout component that receives pre-rendered areas as props:
+ *
+ * ```jsx
+ * export const site = {
+ *   Layout: ({ page, website, header, body, footer, left, right }) => (
+ *     <div className="my-layout">
+ *       <header>{header}</header>
+ *       <aside>{left}</aside>
+ *       <main>{body}</main>
+ *       <aside>{right}</aside>
+ *       <footer>{footer}</footer>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+
+import React from 'react'
+import Blocks from './Blocks.jsx'
+
+/**
+ * Default layout - renders header, body, footer in sequence
+ * (no panels in default layout)
+ */
+function DefaultLayout({ header, body, footer }) {
+  return (
+    <>
+      {header}
+      {body}
+      {footer}
+    </>
+  )
+}
+
+/**
+ * Layout component
+ *
+ * @param {Object} props
+ * @param {Page} props.page - Current page instance
+ * @param {Website} props.website - Website instance
+ */
+export default function Layout({ page, website }) {
+  // Check if foundation provides a custom Layout
+  const RemoteLayout = website.getRemoteLayout()
+
+  // Get block groups from page (respects layout preferences)
+  const headerBlocks = page.getHeaderBlocks()
+  const bodyBlocks = page.getBodyBlocks()
+  const footerBlocks = page.getFooterBlocks()
+  const leftBlocks = page.getLeftBlocks()
+  const rightBlocks = page.getRightBlocks()
+
+  // Pre-render each area as React elements
+  const headerElement = headerBlocks ? <Blocks blocks={headerBlocks} /> : null
+  const bodyElement = bodyBlocks ? <Blocks blocks={bodyBlocks} /> : null
+  const footerElement = footerBlocks ? <Blocks blocks={footerBlocks} /> : null
+  const leftElement = leftBlocks ? <Blocks blocks={leftBlocks} /> : null
+  const rightElement = rightBlocks ? <Blocks blocks={rightBlocks} /> : null
+
+  // Use foundation's custom Layout if provided
+  if (RemoteLayout) {
+    return (
+      <RemoteLayout
+        page={page}
+        website={website}
+        header={headerElement}
+        body={bodyElement}
+        footer={footerElement}
+        left={leftElement}
+        right={rightElement}
+        // Aliases for backwards compatibility
+        leftPanel={leftElement}
+        rightPanel={rightElement}
+      />
+    )
+  }
+
+  // Default layout
+  return (
+    <DefaultLayout
+      header={headerElement}
+      body={bodyElement}
+      footer={footerElement}
+    />
+  )
+}

package/src/components/PageRenderer.jsx

@@ -1,11 +1,15 @@
 /**
  * PageRenderer
  *
- * Renders a page by iterating through its blocks.
+ * Renders a page using the Layout component for proper orchestration
+ * of header, body, footer, and panel areas.
+ * Manages head meta tags for SEO and social sharing.
  */
 
-import React, { useEffect } from 'react'
+import React from 'react'
 import BlockRenderer from './BlockRenderer.jsx'
+import Layout from './Layout.jsx'
+import { useHeadMeta } from '../hooks/useHeadMeta.js'
 
 /**
  * ChildBlocks - renders child blocks of a block
@@ -23,17 +27,27 @@ export function ChildBlocks({ block, childBlocks, pure = false, extra = {} }) {
 
 /**
  * PageRenderer component
+ *
+ * Renders the current page using the Layout system which supports:
+ * - Header, body, footer areas
+ * - Left and right panels
+ * - Foundation-provided custom layouts
+ * - Per-page layout preferences
  */
 export default function PageRenderer() {
-  const page = globalThis.uniweb?.activeWebsite?.activePage
-  const pageTitle = page?.title || 'Website'
+  const uniweb = globalThis.uniweb
+  const website = uniweb?.activeWebsite
+  const page = website?.activePage
+  const siteName = website?.name || ''
+
+  // Get head metadata from page (uses Page.getHeadMeta() if available)
+  const headMeta = page?.getHeadMeta?.() || {
+    title: page?.title || 'Website',
+    description: page?.description || ''
+  }
 
-  useEffect(() => {
-    document.title = pageTitle
-    return () => {
-      document.title = 'Website'
-    }
-  }, [pageTitle])
+  // Manage head meta tags
+  useHeadMeta(headMeta, { siteName })
 
   if (!page) {
     return (
@@ -43,15 +57,6 @@ export default function PageRenderer() {
     )
   }
 
-  const blocks = page.getPageBlocks()
-
-  return (
-    <>
-      {blocks.map((block, index) => (
-        <React.Fragment key={block.id || index}>
-          <BlockRenderer block={block} />
-        </React.Fragment>
-      ))}
-    </>
-  )
+  // Use Layout component for proper orchestration
+  return <Layout page={page} website={website} />
 }

package/src/components/WebsiteRenderer.jsx

@@ -2,10 +2,12 @@
  * WebsiteRenderer
  *
  * Top-level renderer that sets up theme styles and renders pages.
+ * Manages scroll memory for navigation and optional analytics.
  */
 
 import React from 'react'
 import PageRenderer from './PageRenderer.jsx'
+import { useRememberScroll } from '../hooks/useRememberScroll.js'
 
 /**
  * Build CSS custom properties from theme data
@@ -57,6 +59,9 @@ function Fonts({ fontsData }) {
 export default function WebsiteRenderer() {
   const website = globalThis.uniweb?.activeWebsite
 
+  // Enable scroll memory for navigation
+  useRememberScroll({ enabled: true })
+
   if (!website) {
     return (
       <div className="website-loading" style={{ padding: '2rem', textAlign: 'center', color: '#64748b' }}>