@ossy/app 1.39.7 → 1.40.1

package/README.md

@@ -113,22 +113,25 @@ Build output: `build/.ossy/tasks.generated.json` — a registry of `[{ type, mod
 
 ## Components (`*.component.jsx`)
 
-Create `*.component.jsx` files in `src/` (or in any package dependency) to register slot-injectable components. The build discovers them automatically and bundles them separately — they are loaded on every page and slotted in by the layout when `metadata.id` matches the active page id.
+Register injectable UI via `*.component.jsx` in `src/` or feature packages. Components are bundled separately and resolved into slots at runtime.
 
-```jsx
-// src/workspace-users.component.jsx
-export const metadata = {
-  id: 'workspace/users', // rendered when pageId === 'workspace/users'
-}
+**Shell chrome** — the app assigns placement in `*.layout.jsx`:
 
-export default function WorkspaceUsersContent() {
-  return <div>Users content</div>
+```jsx
+export const slots = {
+  'shell:header': 'app-header',
+  'shell:sidebar': 'app-sidebar',
 }
 ```
 
-In your layout, use `<Slot name={app?.pageId} fallback={children} />` from `@ossy/design-system` to render the matching component (or fall back to the page's own output).
+**Resource / input UI** — feature packages use `metadata.id` as the slot key:
+
+```jsx
+export const metadata = { id: 'resource:booking/service/form' }
+export default function ServiceForm() { … }
+```
 
-See [`docs/component-primitive.md`](./docs/component-primitive.md) for the full contract, flow diagram, and examples.
+See [`docs/component-primitive.md`](./docs/component-primitive.md) and [design-system/docs/SLOTS.md](../design-system/docs/SLOTS.md).
 
 ## Port configuration
 

package/cli/build.task.js

@@ -22,10 +22,12 @@ import getPlatformFiles, {
   ACTION_FILE_PATTERN,
   E2E_FILE_PATTERN,
   LAYOUT_FILE_PATTERN,
+  TRANSLATIONS_FILE_PATTERN,
 } from './get-platform-files.task.js'
 import { manifestPlugin } from './manifest-plugin.js'
+import { mergeAndEmitTranslations } from './merge-translations.task.js'
 
-export { PAGE_FILE_PATTERN, API_FILE_PATTERN, TASK_FILE_PATTERN, RESOURCE_FILE_PATTERN, COMPONENT_FILE_PATTERN, AGGREGATE_FILE_PATTERN, INTEGRATION_FILE_PATTERN, STARTUP_FILE_PATTERN, EMAIL_FILE_PATTERN, ACTION_FILE_PATTERN, E2E_FILE_PATTERN, LAYOUT_FILE_PATTERN }
+export { PAGE_FILE_PATTERN, API_FILE_PATTERN, TASK_FILE_PATTERN, RESOURCE_FILE_PATTERN, COMPONENT_FILE_PATTERN, AGGREGATE_FILE_PATTERN, INTEGRATION_FILE_PATTERN, STARTUP_FILE_PATTERN, EMAIL_FILE_PATTERN, ACTION_FILE_PATTERN, E2E_FILE_PATTERN, LAYOUT_FILE_PATTERN, TRANSLATIONS_FILE_PATTERN }
 
 // Generated entry stubs live under `build/.ossy/entries/`. Putting them
 // inside `build/` means they're cleaned automatically with every build,
@@ -185,25 +187,23 @@ function generateStartupStub ({ stubAbs, sourceAbs }) {
   ].join('\n')
 }
 
-// Emails are React components. The stub re-exports `id`, `subject`, and the
-// default component export so the manifest plugin can validate them.
+// Emails are React components. The stub re-exports `id` and the default component.
+// Optional `subject` may be resolved from translations at send time instead.
 function generateEmailStub ({ stubAbs, sourceAbs }) {
   const importPath = relImport(stubAbs, sourceAbs)
   return [
     '// Generated by @ossy/app — do not edit',
-    `export { id, subject, default } from '${importPath}'`,
+    `export { id, default } from '${importPath}'`,
     '',
   ].join('\n')
 }
 
-// Actions are named command handlers. The stub re-exports `id`, `access`, and
-// `run` so the manifest plugin can validate them and the platform server can
-// invoke them at runtime.
+// Actions are intent (metadata only). Implementation lives in a matching `*.task.js`.
 function generateActionStub ({ stubAbs, sourceAbs }) {
   const importPath = relImport(stubAbs, sourceAbs)
   return [
     '// Generated by @ossy/app — do not edit',
-    `export { id, access, run } from '${importPath}'`,
+    `export { metadata } from '${importPath}'`,
     '',
   ].join('\n')
 }
@@ -380,6 +380,7 @@ export async function build (cliArgs = []) {
         configValue,
         appPackageName,
         manifestPath: path.join(buildPath, 'manifest.json'),
+        projectRoot: cwd,
       }),
     ],
   })
@@ -398,4 +399,12 @@ export async function build (cliArgs = []) {
     fs.cpSync(publicSrc, publicOutDir, { recursive: true, force: true })
   }
 
+  mergeAndEmitTranslations({
+    srcDir,
+    projectRoot: cwd,
+    publicOutDir,
+    manifestPath: path.join(buildPath, 'manifest.json'),
+    configValue,
+    warn: (message) => console.warn(message),
+  })
 }

package/cli/discover-translation-files.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import {
+  discoverFilesByPattern,
+  TRANSLATIONS_FILE_PATTERN,
+} from './get-platform-files.task.js'
+import {
+  isValidLocaleCode,
+  parseLocaleFromTranslationFilename,
+} from '@ossy/locale'
+
+/**
+ * @param {string} projectRoot
+ * @returns {string[]}
+ */
+function collectNodeModulesDirs (projectRoot) {
+  const dirs = []
+  let current = projectRoot
+  while (true) {
+    const nm = path.join(current, 'node_modules')
+    if (fs.existsSync(nm) && fs.statSync(nm).isDirectory()) dirs.push(nm)
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return dirs
+}
+
+/**
+ * @typedef {import('@ossy/locale').TranslationSourceFile} TranslationSourceFile
+ */
+
+/**
+ * Discover `*.translations.json` from installed packages and app `src/`.
+ *
+ * @param {{ srcDir: string, projectRoot: string }} options
+ * @returns {TranslationSourceFile[]}
+ */
+export function discoverTranslationFiles ({ srcDir, projectRoot }) {
+  /** @type {TranslationSourceFile[]} */
+  const files = []
+  const seenPaths = new Set()
+
+  const nmDirs = collectNodeModulesDirs(projectRoot)
+  /** @type {Array<{ packageName: string, sourcePath: string }>} */
+  const packageFiles = []
+
+  const tryPackageDir = (pkgDir) => {
+    const real = fs.realpathSync(pkgDir)
+    const pkgJsonPath = path.join(real, 'package.json')
+    if (!fs.existsSync(pkgJsonPath)) return
+
+    let pkg
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'))
+    } catch {
+      return
+    }
+    if (!pkg.ossy?.src) return
+
+    const packageSrcDir = path.resolve(real, pkg.ossy.src)
+    const matches = discoverFilesByPattern(packageSrcDir, TRANSLATIONS_FILE_PATTERN)
+    for (const sourcePath of matches) {
+      const stat = fs.statSync(sourcePath)
+      if (!stat.isFile() || stat.size === 0) continue
+      packageFiles.push({ packageName: pkg.name, sourcePath })
+    }
+  }
+
+  for (const nmDir of nmDirs) {
+    for (const entry of fs.readdirSync(nmDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+      if (entry.name.startsWith('@')) {
+        const scopeDir = path.join(nmDir, entry.name)
+        if (!fs.existsSync(scopeDir)) continue
+        for (const scoped of fs.readdirSync(scopeDir, { withFileTypes: true })) {
+          if (scoped.isDirectory() || scoped.isSymbolicLink()) {
+            tryPackageDir(path.join(scopeDir, scoped.name))
+          }
+        }
+      } else {
+        tryPackageDir(path.join(nmDir, entry.name))
+      }
+    }
+  }
+
+  packageFiles.sort((a, b) => {
+    const byPackage = a.packageName.localeCompare(b.packageName)
+    if (byPackage !== 0) return byPackage
+    return a.sourcePath.localeCompare(b.sourcePath)
+  })
+
+  for (const { packageName, sourcePath } of packageFiles) {
+    if (seenPaths.has(sourcePath)) continue
+    seenPaths.add(sourcePath)
+    const locale = parseLocaleFromTranslationFilename(path.basename(sourcePath))
+    if (!locale) continue
+    files.push({
+      locale,
+      sourcePath,
+      tier: 'package',
+      packageName,
+      sortKey: `${packageName}:${sourcePath}`,
+    })
+  }
+
+  const appFiles = discoverFilesByPattern(srcDir, TRANSLATIONS_FILE_PATTERN).sort()
+  for (const sourcePath of appFiles) {
+    if (seenPaths.has(sourcePath)) continue
+    seenPaths.add(sourcePath)
+    const stat = fs.statSync(sourcePath)
+    if (!stat.isFile() || stat.size === 0) continue
+    const locale = parseLocaleFromTranslationFilename(path.basename(sourcePath))
+    if (!locale) continue
+    files.push({
+      locale,
+      sourcePath,
+      tier: 'app',
+      sortKey: sourcePath,
+    })
+  }
+
+  return files
+}
+
+/**
+ * @param {TranslationSourceFile[]} files
+ */
+export function validateTranslationLocales (files) {
+  for (const file of files) {
+    if (!isValidLocaleCode(file.locale)) {
+      throw new Error(
+        `[@ossy/app][build] Invalid locale "${file.locale}" in ${file.sourcePath}. ` +
+        'Expected ISO 639-1 code (e.g. en, sv).',
+      )
+    }
+  }
+}

package/cli/get-platform-files.task.js

@@ -13,6 +13,7 @@ export const EMAIL_FILE_PATTERN = /\.email\.(jsx?|tsx?)$/
 export const ACTION_FILE_PATTERN = /\.action\.(mjs|cjs|js)$/
 export const E2E_FILE_PATTERN = /\.e2e\.(mjs|cjs|js)$/
 export const LAYOUT_FILE_PATTERN = /\.layout\.(jsx?|tsx?)$/
+export const TRANSLATIONS_FILE_PATTERN = /\.translations\.json$/
 
 /**
  * @typedef {'page' | 'api' | 'task' | 'resource' | 'component' | 'aggregate' | 'integration' | 'startup' | 'email' | 'action' | 'e2e' | 'layout'} EntryKind

package/cli/manifest-plugin.js

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.js'
+import { discoverPackageDefinitions } from '../src/manifest/discover-package-definitions.js'
 
 /**
  * @typedef {import('./get-platform-files.task.js').PlatformEntry} PlatformEntry
@@ -29,6 +30,8 @@ import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.
  *   the `package` field on manifest entries that live in the app `src/` tree.
  * @property {string} manifestPath
  *   Absolute path to write the manifest to (typically `build/manifest.json`).
+ * @property {string} projectRoot
+ *   Absolute path to the consuming app root — used to discover package definitions.
  *
  * @typedef {'page' | 'api' | 'task'} ManifestEntryType
  *
@@ -91,6 +94,7 @@ import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.
  * @property {E2eManifestEntry[]} e2es              Discovered `*.e2e.js` entries from installed packages.
  * @property {LayoutManifestEntry[]} layouts        Discovered `*.layout.{jsx,tsx}` entries (includes app `slots` map).
  * @property {object} config                        Inlined `src/config.js` default export.
+ * @property {Record<string, object>} [definitions] Package Definition metadata keyed by slug.
  */
 
 /**
@@ -131,7 +135,7 @@ function entryPackage (entryInfo, appPackageName) {
   return entryInfo.packageName || appPackageName
 }
 
-export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configValue, appPackageName = '@ossy/app', manifestPath }) {
+export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configValue, appPackageName = '@ossy/app', manifestPath, projectRoot }) {
   return {
     name: 'ossy-manifest',
     async writeBundle (_, bundle) {
@@ -264,25 +268,19 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
           continue
         }
 
-        // Actions are named, discoverable command handlers. The bundle exports
-        // `id` (a unique slug), `run` (the handler function), and optionally
-        // `access` ('public' | 'authenticated' | 'workspace', default 'authenticated').
+        // Actions are intent: `metadata` only (`{ id, access }`). Matching task
+        // with the same id holds `run` (see ADR 0003).
         if (entryInfo.kind === 'action') {
-          const actionId = mod && mod.id
+          const actionId = mod?.metadata?.id
           if (typeof actionId !== 'string' || actionId.trim() === '') {
             this.error(
-              `[@ossy/app][build] action entry ${entryInfo.sourcePath} must export a non-empty string "id"`,
-            )
-          }
-          if (typeof mod.run !== 'function') {
-            this.error(
-              `[@ossy/app][build] action entry ${entryInfo.sourcePath} must export a "run" function`,
+              `[@ossy/app][build] action entry ${entryInfo.sourcePath} must export a non-empty string "metadata.id"`,
             )
           }
           if (seenActionIds.has(actionId)) {
             this.error(`[@ossy/app][build] Duplicate action id "${actionId}"`)
           }
-          const access = mod.access ?? 'authenticated'
+          const access = mod.metadata?.access ?? 'authenticated'
           seenActionIds.add(actionId)
           actions.push({ id: actionId, entry: url, access, package: entryPackage(entryInfo, appPackageName) })
           continue
@@ -483,7 +481,24 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
       }
 
       /** @type {Manifest} */
-      const manifest = { entries, components, resourceTemplates, aggregates, integrations, startups, emails, actions, e2es, layouts, config: configValue || {} }
+      const definitions = projectRoot
+        ? await discoverPackageDefinitions(projectRoot)
+        : {}
+
+      const manifest = {
+        entries,
+        components,
+        resourceTemplates,
+        aggregates,
+        integrations,
+        startups,
+        emails,
+        actions,
+        e2es,
+        layouts,
+        definitions,
+        config: configValue || {},
+      }
       fs.mkdirSync(path.dirname(manifestPath), { recursive: true })
       fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8')
     },

package/cli/merge-translations.task.js

@@ -0,0 +1,170 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { mergeTranslationFiles, pageIdToDocumentTitleKey } from '@ossy/locale'
+import {
+  discoverTranslationFiles,
+  validateTranslationLocales,
+} from './discover-translation-files.js'
+
+/**
+ * @param {Array<{ type: string, id: string, path?: string | Record<string, string> }>} entries
+ * @param {string[]} supportedLanguages
+ * @param {string | undefined} defaultLanguage
+ * @param {(message: string) => void} error
+ * @param {(message: string) => void} warn
+ */
+export function validateLanguageConfig ({ entries, supportedLanguages, defaultLanguage, error, warn }) {
+  if (!Array.isArray(supportedLanguages) || supportedLanguages.length === 0) return
+
+  if (defaultLanguage && !supportedLanguages.includes(defaultLanguage)) {
+    error(
+      `[@ossy/app][build] config.defaultLanguage "${defaultLanguage}" is not in supportedLanguages`,
+    )
+  }
+
+  for (const entry of entries.filter((e) => e.type === 'page')) {
+    if (typeof entry.path !== 'object' || !entry.path) continue
+
+    for (const lang of Object.keys(entry.path)) {
+      if (!supportedLanguages.includes(lang)) {
+        error(
+          `[@ossy/app][build] Page "${entry.id}" metadata.path key "${lang}" is not in supportedLanguages`,
+        )
+      }
+    }
+
+    for (const lang of supportedLanguages) {
+      if (!(lang in entry.path)) {
+        warn(
+          `[@ossy/app][build] Page "${entry.id}" metadata.path is missing key for supported language "${lang}"`,
+        )
+      }
+    }
+  }
+}
+
+/**
+ * @param {Array<{ type: string, id: string, title?: string }>} entries
+ * @param {Record<string, Record<string, string>>} catalogs
+ * @param {string | undefined} defaultLanguage
+ * @param {(message: string) => void} warn
+ */
+export function validatePageDocumentTitles ({ entries, catalogs, defaultLanguage, warn }) {
+  if (!defaultLanguage) return
+  const catalog = catalogs[defaultLanguage] || {}
+
+  for (const entry of entries.filter((e) => e.type === 'page')) {
+    if (entry.title) continue
+    const key = pageIdToDocumentTitleKey(entry.id)
+    if (!catalog[key]) {
+      warn(
+        `[@ossy/app][build] Page "${entry.id}" document title key "${key}" missing in default language "${defaultLanguage}" catalog`,
+      )
+    }
+  }
+}
+
+/**
+ * @param {{ actions?: Array<{ id: string }> }} manifest
+ * @param {Record<string, Record<string, string>>} catalogs
+ * @param {string | undefined} defaultLanguage
+ * @param {(message: string) => void} warn
+ */
+export function validateActionTranslationKeys ({ manifest, catalogs, defaultLanguage, warn }) {
+  if (!defaultLanguage) return
+  const catalog = catalogs[defaultLanguage] || {}
+  const actions = Array.isArray(manifest?.actions) ? manifest.actions : []
+
+  for (const action of actions) {
+    const actionId = action.id
+    if (!actionId) continue
+    if (!catalog[`${actionId}.label`]) {
+      warn(
+        `[@ossy/app][build] Action "${actionId}" missing "${actionId}.label" in default language catalog`,
+      )
+    }
+    if (!catalog[`${actionId}.description`]) {
+      warn(
+        `[@ossy/app][build] Action "${actionId}" missing "${actionId}.description" in default language catalog`,
+      )
+    }
+  }
+}
+
+/**
+ * Discover, merge, validate, and emit per-locale translation catalogs.
+ *
+ * @param {{
+ *   srcDir: string
+ *   projectRoot: string
+ *   publicOutDir: string
+ *   manifestPath: string
+ *   configValue: object
+ *   log?: (message: string) => void
+ *   warn?: (message: string) => void
+ * }} options
+ */
+export function mergeAndEmitTranslations ({
+  srcDir,
+  projectRoot,
+  publicOutDir,
+  manifestPath,
+  configValue,
+  log = () => {},
+  warn = (message) => log(message),
+}) {
+  const supportedLanguages = Array.isArray(configValue?.supportedLanguages)
+    ? configValue.supportedLanguages
+    : []
+  const defaultLanguage = typeof configValue?.defaultLanguage === 'string'
+    ? configValue.defaultLanguage
+    : undefined
+
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+  const entries = Array.isArray(manifest.entries) ? manifest.entries : []
+
+  /** @type {string[]} */
+  const errors = []
+  validateLanguageConfig({
+    entries,
+    supportedLanguages,
+    defaultLanguage,
+    error: (message) => errors.push(message),
+    warn,
+  })
+
+  const discovered = discoverTranslationFiles({ srcDir, projectRoot })
+  validateTranslationLocales(discovered)
+
+  const catalogs = mergeTranslationFiles(discovered, supportedLanguages, {
+    readFileSync: (filePath, encoding) => fs.readFileSync(filePath, encoding),
+  })
+
+  for (const lang of supportedLanguages) {
+    const keys = Object.keys(catalogs[lang] || {})
+    if (keys.length === 0) {
+      warn(
+        `[@ossy/app][build] No translation keys merged for supported language "${lang}"`,
+      )
+    }
+  }
+
+  validatePageDocumentTitles({ entries, catalogs, defaultLanguage, warn })
+  validateActionTranslationKeys({ manifest, catalogs, defaultLanguage, warn })
+
+  /** @type {Record<string, string>} */
+  const files = {}
+  for (const lang of supportedLanguages) {
+    const outPath = path.join(publicOutDir, `${lang}.translations.json`)
+    fs.writeFileSync(outPath, JSON.stringify(catalogs[lang] || {}, null, 2) + '\n', 'utf8')
+    files[lang] = `/${lang}.translations.json`
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join('\n'))
+  }
+
+  manifest.translations = { files }
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8')
+}

package/cli/start.task.js

@@ -1,6 +1,7 @@
 import path from 'node:path'
 import arg from 'arg'
 import { startServer } from '@ossy/platform/server'
+import 'dotenv/config' 
 
 export async function start (cliArgs = []) {
   const options = arg({
@@ -13,7 +14,7 @@ export async function start (cliArgs = []) {
   const cwd = options['--cwd'] ? path.resolve(options['--cwd']) : process.cwd()
   const buildDir = options['--build-dir'] || 'build'
   const port = options['--port']
-
+  
   const { lifetime } = await startServer({ cwd, buildDir, port })
   await lifetime
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/app",
-  "version": "1.39.7",
+  "version": "1.40.1",
   "description": "",
   "source": "./src/index.js",
   "main": "./src/index.js",
@@ -12,7 +12,9 @@
     "./runtime/resolve-shell-slots": "./runtime/resolve-shell-slots.js",
     "./runtime/api-runtime": "./runtime/api-runtime.js",
     "./runtime/task-runtime": "./runtime/task-runtime.js",
-    "./manifest/build-manifest-summary": "./src/manifest/build-manifest-summary.js"
+    "./manifest/build-manifest-summary": "./src/manifest/build-manifest-summary.js",
+    "./manifest/discover-package-definitions": "./src/manifest/discover-package-definitions.js",
+    "./manifest/serialize-package-definition": "./src/manifest/serialize-package-definition.js"
   },
   "bin": {
     "app": "./cli/index.js"
@@ -40,14 +42,15 @@
     "@babel/eslint-parser": "^7.15.8",
     "@babel/preset-react": "^7.26.3",
     "@babel/register": "^7.25.9",
-    "@ossy/design-system": "^1.39.7",
+    "@ossy/design-system": "^1.40.1",
+    "@ossy/locale": "^1.40.1",
     "@ossy/pages": "^1.23.0",
-    "@ossy/platform": "^1.38.7",
-    "@ossy/router": "^1.39.7",
-    "@ossy/router-react": "^1.39.7",
-    "@ossy/sdk": "^1.39.7",
-    "@ossy/sdk-react": "^1.39.7",
-    "@ossy/themes": "^1.39.7",
+    "@ossy/platform": "^1.39.1",
+    "@ossy/router": "^1.40.1",
+    "@ossy/router-react": "^1.40.1",
+    "@ossy/sdk": "^1.40.1",
+    "@ossy/sdk-react": "^1.40.1",
+    "@ossy/themes": "^1.40.1",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-babel": "^7.0.0",
     "@rollup/plugin-commonjs": "^29.0.0",
@@ -81,5 +84,5 @@
     "README.md",
     "tsconfig.json"
   ],
-  "gitHead": "f65df0cd6da864c314c4f424112e05e8e2dec0ff"
+  "gitHead": "c0ba5d90749690634e4dc2705178ff8d89dd3070"
 }

package/runtime/page-runtime.js

@@ -1,4 +1,5 @@
 import { createElement } from 'react'
+import { pageIdToDocumentTitleKey, resolveMessage } from '@ossy/locale'
 import { App } from '../src/shell/App.jsx'
 import { resolvePageSlots } from './resolve-shell-slots.js'
 
@@ -41,16 +42,44 @@ export async function loadLayout (layoutEntry) {
   try {
     const mod = await import(layoutEntry)
     return mod?.default ?? null
-  } catch {
+  } catch (err) {
+    if (typeof console !== 'undefined' && typeof console.error === 'function') {
+      console.error('[@ossy/app][page-runtime] Failed to load layout bundle:', layoutEntry, err)
+    }
     return null
   }
 }
 
+function resolveDocumentTitle (metadata, props) {
+  if (metadata.id && props.messages) {
+    const key = pageIdToDocumentTitleKey(metadata.id)
+    const hasTranslation =
+      props.messages[key] != null || props.fallbackMessages?.[key] != null
+    if (hasTranslation) {
+      return resolveMessage(props.messages, key, {
+        fallbackCatalog: props.fallbackMessages,
+        onMissingKey: (missingKey) => {
+          if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+            console.warn(
+              `[@ossy/app][page-runtime] Missing document title key "${missingKey}" for page "${metadata.id}"`,
+            )
+          }
+        },
+      })
+    }
+    if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+      console.warn(
+        `[@ossy/app][page-runtime] Missing document title key "${key}" for page "${metadata.id}"; falling back to metadata.title`,
+      )
+    }
+  }
+  return metadata.title || props.documentTitle || ''
+}
+
 function buildTree ({ Component, Layout, metadata, props }) {
-  const lang = props.htmlLang || props.defaultLanguage || 'en'
-  const contentEl = Layout
-    ? createElement(Layout, props)
-    : createElement(Component, props)
+  const lang = props.language || props.defaultLanguage || 'en'
+  const pageEl = createElement(Component, props)
+  const contentEl = Layout ? createElement(Layout, props, pageEl) : pageEl
   return createElement(
     'html',
     { lang },
@@ -58,9 +87,9 @@ function buildTree ({ Component, Layout, metadata, props }) {
       'head',
       null,
       createElement('meta', { charSet: 'utf-8' }),
-      createElement('title', null, metadata.title || props.documentTitle || ''),
+      createElement('title', null, resolveDocumentTitle(metadata, props)),
     ),
-    createElement(App, props, contentEl),
+    createElement('body', null, createElement(App, props, contentEl)),
   )
 }
 
@@ -152,6 +181,10 @@ export function createPageEntry (pageModule, options = {}) {
         pageComponent: Component,
       })
       hydrateRoot(document, buildTree({ Component, Layout, metadata, props: { ...pageProps, components } }))
+    }).catch((err) => {
+      if (typeof console !== 'undefined' && typeof console.error === 'function') {
+        console.error('[@ossy/app][page-runtime] Hydration failed:', err)
+      }
     })
   }
 

package/src/manifest/build-manifest-summary.js

@@ -106,5 +106,10 @@ export function buildManifestSummary (manifest) {
     }
   }
 
-  return { packages }
+  const definitions =
+    manifest.definitions && typeof manifest.definitions === 'object' && !Array.isArray(manifest.definitions)
+      ? manifest.definitions
+      : {}
+
+  return { packages, definitions }
 }

package/src/manifest/discover-package-definitions.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { packageNameToSlug } from './build-manifest-summary.js'
+import { serializePackageDefinition } from './serialize-package-definition.js'
+
+/**
+ * @param {string} projectRoot
+ * @returns {string[]}
+ */
+function collectNodeModulesDirs (projectRoot) {
+  const dirs = []
+  let current = projectRoot
+  while (true) {
+    const nm = path.join(current, 'node_modules')
+    if (fs.existsSync(nm) && fs.statSync(nm).isDirectory()) dirs.push(nm)
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return dirs
+}
+
+/**
+ * Load `Definition.js` from disk only — never import the package main entry,
+ * which may pull CLI side effects (e.g. `@ossy/cli` runs on import).
+ *
+ * @param {string} pkgDir
+ * @param {object} pkg
+ * @returns {Promise<object | null>}
+ */
+async function loadPackageDefinition (pkgDir, pkg) {
+  if (!pkg.ossy?.src) return null
+
+  const defPath = path.join(pkgDir, pkg.ossy.src, 'Definition.js')
+  if (!fs.existsSync(defPath)) return null
+
+  try {
+    const mod = await import(pathToFileURL(defPath).href + `?t=${Date.now()}`)
+    if (mod?.Definition && typeof mod.Definition === 'object') {
+      return mod.Definition
+    }
+  } catch {
+    // skip packages without a readable Definition
+  }
+
+  return null
+}
+
+/**
+ * Discover `Definition.js` from installed `@ossy/*` packages.
+ *
+ * @param {string} projectRoot Absolute path to the consuming app root.
+ * @returns {Promise<Record<string, object>>} Map keyed by package slug.
+ */
+export async function discoverPackageDefinitions (projectRoot) {
+  const nmDirs = collectNodeModulesDirs(projectRoot)
+  /** @type {Record<string, object>} */
+  const definitions = {}
+  const seen = new Set()
+
+  const tryPackageDir = async (pkgDir) => {
+    const real = fs.realpathSync(pkgDir)
+    if (seen.has(real)) return
+    seen.add(real)
+
+    const pkgJsonPath = path.join(pkgDir, 'package.json')
+    if (!fs.existsSync(pkgJsonPath)) return
+
+    let pkg
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'))
+    } catch {
+      return
+    }
+
+    const name = typeof pkg.name === 'string' ? pkg.name.trim() : ''
+    if (!name.startsWith('@ossy/')) return
+
+    const slug = packageNameToSlug(name)
+    if (!slug || definitions[slug]) return
+
+    const raw = await loadPackageDefinition(real, pkg)
+    const serialized = serializePackageDefinition(raw)
+    if (serialized) definitions[slug] = serialized
+  }
+
+  for (const nmDir of nmDirs) {
+    const scopeDir = path.join(nmDir, '@ossy')
+    if (!fs.existsSync(scopeDir) || !fs.statSync(scopeDir).isDirectory()) continue
+
+    for (const entry of fs.readdirSync(scopeDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+      await tryPackageDir(path.join(scopeDir, entry.name))
+    }
+  }
+
+  return definitions
+}

package/src/manifest/serialize-package-definition.js

@@ -0,0 +1,30 @@
+/**
+ * Pick JSON-serializable Definition fields for manifest / SSR bootstrap.
+ * Definition holds module presentation metadata only — capabilities live in manifestSummary.
+ *
+ * @param {object | null | undefined} definition
+ * @returns {object | null}
+ */
+export function serializePackageDefinition (definition) {
+  if (!definition || typeof definition !== 'object' || Array.isArray(definition)) return null
+
+  /** @type {Record<string, unknown>} */
+  const out = {}
+
+  if (typeof definition.id === 'string' && definition.id.trim()) out.id = definition.id.trim()
+  if (typeof definition.title === 'string' && definition.title.trim()) out.title = definition.title.trim()
+  if (typeof definition.description === 'string' && definition.description.trim()) {
+    out.description = definition.description.trim()
+  }
+  if (typeof definition.icon === 'string' && definition.icon.trim()) out.icon = definition.icon.trim()
+  if (typeof definition.navOrder === 'number' && Number.isFinite(definition.navOrder)) {
+    out.navOrder = definition.navOrder
+  }
+  if (definition.entitlementRequired === false) out.entitlementRequired = false
+  if (typeof definition.status === 'string' && definition.status.trim()) out.status = definition.status.trim()
+  if (Array.isArray(definition.statuses) && definition.statuses.length) {
+    out.statuses = definition.statuses.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim())
+  }
+
+  return Object.keys(out).length ? out : null
+}

package/src/shell/App.jsx

@@ -1,13 +1,13 @@
 import React from 'react'
 import { SDK } from '@ossy/sdk'
 import { WorkspaceProvider } from '@ossy/sdk-react'
-import { Theme, ComponentSlotsProvider } from '@ossy/design-system'
+import { Theme, ComponentSlotsProvider, LocaleProvider } from '@ossy/design-system'
 import { ThemeEditor } from './ThemeEditor.jsx'
 import { defaultAppSettings } from './AppSettings.jsx'
 import { Router } from '@ossy/router-react'
 import { AppContext } from './AppContext.js'
 
-export const App = ({ children, ..._appSettings }) => {
+export const App = ({ children, language, messages, fallbackMessages, ..._appSettings }) => {
   const appSettings = { ...defaultAppSettings(), ..._appSettings }
 
   // `components` holds resolved ComponentType values — not JSON-serializable,
@@ -20,17 +20,25 @@ export const App = ({ children, ..._appSettings }) => {
   })
 
   return (
-    <AppContext.Provider value={contextSettings}>
-      <ComponentSlotsProvider slots={components || {}}>
-        <Theme theme={appSettings.theme} themes={appSettings.themes}>
-          <WorkspaceProvider sdk={sdk}>
-            <Router {...appSettings} pages={appSettings.pages || []}>
-              {children}
-              {appSettings.devMode && <ThemeEditor />}
-            </Router>
-          </WorkspaceProvider>
-        </Theme>
-      </ComponentSlotsProvider>
-    </AppContext.Provider>
+    <LocaleProvider
+      language={language}
+      messages={messages}
+      fallbackMessages={fallbackMessages}
+      defaultLanguage={appSettings.defaultLanguage}
+      supportedLanguages={appSettings.supportedLanguages}
+    >
+      <AppContext.Provider value={contextSettings}>
+        <ComponentSlotsProvider slots={components || {}}>
+          <Theme theme={appSettings.theme} themes={appSettings.themes}>
+            <WorkspaceProvider sdk={sdk}>
+              <Router {...appSettings} pages={appSettings.pages || []}>
+                {children}
+                {appSettings.devMode && <ThemeEditor />}
+              </Router>
+            </WorkspaceProvider>
+          </Theme>
+        </ComponentSlotsProvider>
+      </AppContext.Provider>
+    </LocaleProvider>
   )
 }

package/src/shell/ThemeEditor.jsx

@@ -1,5 +1,6 @@
 import React, { useState, useMemo, useCallback, useEffect } from 'react'
-import { useResource } from '@ossy/sdk-react'
+import { updateResourceContent } from '@ossy/resources'
+import { useSdk } from '@ossy/sdk-react'
 import { Overlay, Button, useTheme, View, Text } from '@ossy/design-system'
 import { DevPagesPanel } from './DevPagesPanel.jsx'
 
@@ -40,7 +41,7 @@ const ThemeSwitcher = () => {
 }
 
 export const ThemeEditor = () => {
-  const { updateResourceContent } = useResource('PCX53TaGviq4_8KvK-VOp')
+  const sdk = useSdk()
   const [isEditorOpen, setIsEditorOpen] = useState(false)
   const [viewCount, setViewCount] = useState(0)
   // const [theme, temporarilyUpdateTheme] = useTheme()
@@ -72,7 +73,7 @@ export const ThemeEditor = () => {
 
   const onSaveTheme = event => {
     event.preventDefault()
-    updateResourceContent(theme)
+    updateResourceContent(sdk, 'PCX53TaGviq4_8KvK-VOp', theme)
   }
 
   useEffect(() => {