catalyst-core 0.3.0-beta.5 → 0.3.0-canary.2

package/changelog.md

@@ -1,4 +1,108 @@
-# 1.0.0-beta.1
+# Changelog
+
+## [1.0.0] - unreleased
+
+This release freezes the public API. The root entry of `catalyst-core` now exports exactly eight names and nothing else: `RouterDataProvider`, `useCurrentRouteData`, `useRouterData`, `MetaTag`, `split`, `hydrationReady`, `Head`, and `Body`. Anything previously reachable through the root entry but not in that list is no longer public. Applications that import a removed name will fail at build time rather than silently resolving to `undefined`.
+
+### React Router is no longer re-exported
+
+`catalyst-core` used to re-export the whole of React Router from its root entry, so `Link`, `Outlet`, `RouterProvider`, `useParams`, `useNavigate` and every other router name could be imported from `catalyst-core`. That re-export is gone.
+
+React Router is now a peer dependency (`^7.18.2`). Install it in the application:
+
+```bash
+npm install react-router@^7.18.2
+```
+
+Then import router names from `react-router` directly. An import line that mixed both sources splits into two:
+
+```js
+// before
+import { useCurrentRouteData, useParams, Link } from "catalyst-core"
+
+// after
+import { useCurrentRouteData } from "catalyst-core"
+import { useParams, Link } from "react-router"
+```
+
+One exception: `client/index.js` imports `RouterProvider` from `react-router/dom`, not from `react-router`. The `react-router/dom` build passes React DOM's `flushSync` into the router, which view transitions and `flushSync` navigations depend on. The `react-router` export renders the same tree but silently skips that.
+
+Because the version is now declared by the application, npm will report a peer dependency conflict if the installed React Router major does not satisfy `^7.18.2`. The server also verifies the resolved version at startup and exits with a clear error if React Router is missing or outside the supported range.
+
+### Removed export paths
+
+- `catalyst-core/caching` — removed. The caching feature was withdrawn and has no replacement.
+- `catalyst-core/document` — removed. Import `Head` and `Body` from the `catalyst-core` root entry instead.
+
+### No default export from the root entry
+
+`split` was previously exported both as a named export and as the default. The default export is gone; use the named one.
+
+```js
+// before
+import split from "catalyst-core"
+
+// after
+import { split } from "catalyst-core"
+```
+
+### Names that are no longer public
+
+These were reachable from the root entry and are now internal: `RouterContext`, `serverDataFetcher`, `mergeHeadElements`, `deleteHeadTagsByDataAttribute`, `getMetaData`, and `useNavigateWithTransition`. In addition, `sanitizeFilePickerOptions` is no longer exported from `catalyst-core/hooks`. None of these have a supported replacement. If an application depends on one of them, open an issue describing the use case before upgrading.
+
+### Native hooks: canonical keys
+
+The native hooks now agree on one set of key names. Every change in this section is additive: no key that a hook returned before has been removed or repointed, so existing components keep working.
+
+Several hooks were missing keys that the rest of the surface already had. `useNotificationPermission` gained `loading`, `data`, `error`, `isNative`, and `isWeb`, and it now reports permission failures as a standard error object instead of only logging them. `useCameraPermission` gained `loading`, `data`, `error`, `execute`, `isNative`, and `isWeb` on the same pattern. `useDeviceInfo` gained `data` alongside its existing `deviceInfo`. `useNativeTransition` gained `loading` alongside `transitioning`. The SSR stub returned by `useAI` reported `isWeb: false`, which was wrong on both counts; it now reports `isWeb: true`.
+
+Where a hook had two names for one value, the shorter one is canonical and the older one is a deprecated alias that will be removed at 2.0: `loading` over `isLoading` and `transitioning`, `data` over `deviceInfo` and `permission`, and `execute` over `request`.
+
+Hooks fall into three categories, and the category decides whether a hook has `execute`. A hook that wraps a single native operation exposes it as `execute` plus a domain-specific alias — `takePhoto`, `pickFile`, `openFile`, `signIn`, `trigger`, `request`. A hook that wraps several distinct operations has no single action to name, so its named functions are the API and it has no `execute` at all: `useVideoStream`, `useDataProtection`, and `useNativeTransition` work this way. A read-only hook reports ambient device state and has no action functions at all: `useNetworkStatus`, `useDeviceInfo`, and `useSafeArea` return state plus the runtime-context keys. `useNotification` is the one exception. It carries `execute` and `schedule` as aliases of `scheduleLocal` for backward compatibility. Both are frozen, both are discouraged, and neither should be read as the pattern for multi-action hooks. `execute` never takes an operation name as a string argument; it takes the arguments of the operation itself.
+
+Hook errors are `CatalystError` values from the framework-wide error registry introduced in this release, carrying a `RUNTIME-NATIVE-*` code, a message, a category, a suggested action, a documentation link, and the originating platform error as `cause`. `useVideoStream` in particular used to report seventeen failures as bare `{ message }` objects with no code at all; those now carry real codes, and a camera denial reports the same code whether it comes from the permission hook or the stream. The error object's fields changed with it: `action` is now `suggestedAction`, `nativeError` is now `cause`, `recoverable` and `timestamp` are gone, and `code` values are registry codes such as `RUNTIME-NATIVE-001` instead of names such as `PERMISSION_DENIED`, so compare against `ERROR_CODES` from `catalyst-core/errors` rather than string literals.
+
+One consequence for error logging: `CatalystError` extends `Error`, so `message` now lives on the prototype rather than as an own property. Reading `error.message` is unaffected, but `JSON.stringify(error)` no longer includes it. Log `error.message` explicitly, or use the `code` and `docUrl` fields.
+
+Two hooks are exempt from the error contract. `useNativeTransition` and `useSafeArea` return no `error` key, because transition failures self-heal into a plain navigation and safe-area insets always resolve to numeric defaults. Two others carry the right key with the wrong type: `error` on `useDeviceInfo` and `useNetworkStatus` is still a plain string rather than an error object, and stays a string until 2.0. The shape of `useAI` is owned by the `catalyst-ai` package and sits outside this contract entirely.
+
+`requestHapticFeedback` and `requestCameraPermission` remain available both as `catalyst-core/hooks` exports and as `WebBridge` methods, and the two versions still differ in their defaults and return types. The hooks exports are the ones to prefer in application code: they are SSR-safe and treat a denied permission as a rejection. The two surfaces are unified at 2.0.
+
+### Node 22.12 is now the minimum
+
+The error registry is loaded from the native bridge, which is built as CommonJS, so the package relies on `require()` of an ES module. That is unflagged only from Node 22.12 onward, and `engines` now declares `>=22.12`. Node 20 installs will warn, and importing `catalyst-core/hooks` or `catalyst-core/WebBridge` there fails with `ERR_REQUIRE_ESM`.
+
+### App contract violations are reported at startup
+
+The app contract validators in `server/utils/validator.js` used to log a bare message and return `undefined` when an app was missing a required export, which pushed the real failure into an unrelated `TypeError` deep inside a render. They now report through the shared error reporter instead, naming the specific file and export and what the app must provide, with detail governed by the output mode. Reporting is not fatal: startup continues, so an app that is only partly misconfigured still boots and the startup output explains what will fail.
+
+The route and store checks moved out of the per-request path. `validateGetRoutes` and `validateConfigureStore` now run once when the renderer module loads — at server startup in production, and on the first SSR request in development, where the handler is loaded lazily — rather than once per request inside the handler's `try`/`catch`. The shape of `addMiddlewares` from `server/server.js` is checked during server setup.
+
+Module aliases and `config/config.json` keys are not checked at load time; a missing alias or key still surfaces where it is used. An application that satisfies the contract sees no change. The full contract — the files Catalyst imports by fixed path and the required module aliases — is documented under File Conventions.
+The webpack-era keys `WEBPACK_DEV_SERVER_HOSTNAME`, `WEBPACK_DEV_SERVER_PORT` and `ANALYZE_BUNDLE` are no longer required or read; remove them from `config/config.json`.
+
+## [0.3.0-beta.5] - 2026-08-18
+
+- Upgrade react-router-dom v6 to v7.18.2 (CVE fixes) (#399).
+- Docs: clarify setMetaData must return array of JSX elements (#327).
+
+## [0.3.0-beta.4] - 2026-08-10
+
+- Detect CommonJS by parsing, not by matching source text (#397).
+- Sub-path base + HMR config for reverse-proxy dev setups (#379).
+
+## [0.3.0-beta.3] - 2026-08-04
+
+- Resolve semgrep and dependency findings from security scan (#375).
+
+## [0.3.0-beta.2] - 2026-08-03
+
+- @catalyst/cloud-ai — multi-provider AI integration with useAI hook (#288).
+- Eliminate SSR streaming race between onShellReady and onAllReady (#323).
+- Update iOS release docs and MCP guidance (#324).
+- Patch @tailwindcss/postcss base so Vite scans the whole app (#326).
+
+## [0.3.0-beta.1] - 2026-07-15
 
 - Replaced the Webpack build and SSR pipeline with Vite and ESM.
 - Added React 19 Suspense-aware routing, split components, and manifest-based asset loading.
@@ -6,13 +110,51 @@
 - Preserved native application builds, internal plugins, Sentry exports, and safe-area SSR hydration.
 - Removed the legacy `devBuild` and `devServe` commands.
 
-# Changelog
+## [0.2.0-beta.3] - 2026-07-14
+
+- Catalyst Profiler Runtime (#274).
+
+## [0.2.0-beta.2] - 2026-07-09
+
+- Route Caching (#287).
+- Android build fixes (#303).
+
+## [0.2.0-beta.1] - 2026-07-08
+
+- Catalyst react + rendering update (#293).
+- Add GitHub feedback integration to Catalyst MCP v2 (#272).
+- Sync MCP v2: extract seeding, delegate docs sync, add FTS + initial sync (#295).
+
+## [0.1.0-beta.7] - 2026-06-29
+
+- Syncing dweb branch with main (#283).
+
+## [0.1.0-beta.6] - 2026-06-11
+
+- Add examples folder with local testing app for catalyst-core (#246).
+
+## [0.1.0-beta.5] - 2026-06-09
+
+- Semgrep Plugin Fixes (#266).
+
+## [0.1.0-beta.4] - 2026-06-03
+
+- Merge video hook, web fallback, and plugin system into monorepo (#258).
+
+## [0.1.0-beta.3] - 2026-06-02
+
+- Security Fixes (semgrep) (#259).
+- Catalyst Docs Mismatches Fix (#244).
 
 ## [0.1.0-beta.2] - 2026-05-06
 
 - Moved Catalyst into a monorepo structure with `catalyst-core`, `create-catalyst-app`, the Catalyst docs app, and the Catalyst core test app managed from one repository.
 - Replaced the internal-package pre-release flow with a local release sandbox that scaffolds a real app using current-branch CCA and a locally packed current-branch `catalyst-core`.
 
+## [0.1.0-canary.9] - 2026-05-06
+
+- Changelog-only update; same code as 0.1.0-beta.2.
+
 ## [0.1.0-canary.8] - 2026-04-15
 
 - Introduced Catalyst’s internal plugin architecture, adding the `PluginBridge` web API, native plugin runtimes for Android and iOS, and manifest-driven build composition for modular native capabilities.
@@ -40,7 +182,7 @@
 - Improved universal app runtime behavior with safe-area inset support, edge-to-edge rendering, and notification permission override fixes.
 - Expanded platform support with offline fallback handling, notification/access-control refinements, localhost HTTP allowances for local development, and file-picker/HTTPS server improvements.
 
-## [0.1.0-canary.4] - 2026-02-12
+## [0.1.0-canary.4] - 2026-02-16
 
 - Added Google Sign-In support for both Android and iOS in Catalyst, enabling a unified native authentication experience for apps built on the framework.
 - Improved release/build reliability with related bridge and CI updates, making integration smoother and more consistent across platforms.
@@ -68,26 +210,26 @@
 - Notification refactor: streamlined config toggle for local vs push, centralized permission/asset handling, and simpler routing into the web app
 - Access control: combined access control config for ios
 
-## [0.0.3-canary.18] - 2025-11-19
+## [0.0.3-canary.18] - 2025-11-25
 
 - Configuration Files
 - Android Native WebView - MainActivity.kt
 - Android Native WebView - CustomWebview.kt
 
-## [0.0.3-canary.17] - 2025-11-19
+## [0.0.3-canary.17] - 2025-11-21
 
-- ✨ Added complete notification system (local & push)
-- 🔔 New useNotification() React hook
-- 📱 Firebase Cloud Messaging conditional build support
-- 🤖 Android notification handling in MainActivity
-- 🔧 5 new notification commands + 5 callbacks in NativeBridge
-- 📦 Auto-processing of notification icons & sounds
-- ⚙️ Conditional dependencies based on notification config
-- 🧹 Updated .gitignore & .npmignore
-- 📋 Enhanced build process with automatic permission injection
-- 🔗 Deep link integration with notifications
+- Added complete notification system (local & push)
+- New useNotification() React hook
+- Firebase Cloud Messaging conditional build support
+- Android notification handling in MainActivity
+- 5 new notification commands + 5 callbacks in NativeBridge
+- Auto-processing of notification icons & sounds
+- Conditional dependencies based on notification config
+- Updated .gitignore & .npmignore
+- Enhanced build process with automatic permission injection
+- Deep link integration with notifications
 
-## [0.0.3-canary.16] - 2025-11-19
+## [0.0.3-canary.16] - 2025-11-20
 
 - FeaturesGallery Support for File Picker: Enhanced file picker to open native gallery for selecting images and videos
 - HTTPS Framework Server: Enabled HTTPS support for the framework server with self-signed SSL certificate
@@ -97,17 +239,17 @@
 
 - Adding Android release support and appInfo key
 
-## [0.0.3-canary.14] - 2025-09-29
+## [0.0.3-canary.14] - 2025-10-29
 
 - Android custom splashscreen
 
-## [0.0.3-canary.13] - 2025-09-28
+## [0.0.3-canary.13] - 2025-10-28
 
 - Multi file support in useFilePicker hook
 - Android multiple app icon support
 - Android whitelisting toggle support
 
-## [0.0.3-canary.12] - 2025-09-26
+## [0.0.3-canary.12] - 2025-10-13
 
 - Universal App Context: Added comprehensive context support for building universal mobile applications
 - OpenTelemetry SDK Integration: Built-in support for observability and performance monitoring with Otel SDK
@@ -118,70 +260,42 @@
 - Enhanced Android native support: Add support for native keyboard and webview resizing in Android
 - Device info API web support: Web support in device info API
 
-## [0.0.3-canary.10] - 2025-09-11
+## [0.0.3-canary.10] - 2025-09-17
 
-- **Sentry import bug fix**
-- **Open telemetry SDK**
+- Sentry import bug fix.
+- Open telemetry SDK.
 
 ## [0.0.3-canary.9] - 2025-09-11
 
-- **App name configuration**
-- **Device Info API**
-- **Access control configuration**
-
-## [0.0.3-canary.8] - 2025-01-06
+- App name configuration.
+- Device Info API.
+- Access control configuration.
 
-- **App icon configuration**
-- **Splash screen integration**
-- **Url Whitelisting**
+## [0.0.3-canary.8] - 2025-08-08
 
-## [0.0.3-canary.7] - 2025-01-06
+- App icon configuration.
+- Splash screen integration.
+- Url Whitelisting.
 
-### 🚀 Features
-
-- **Native API Integration**: Enhanced native module integration for better performance
-- **Automated IP Resolution**: Intelligent network detection eliminates manual IP configuration
-- **Universal Build System**: Streamlined one-command builds for both Android and iOS platforms
-- **Enhanced CLI Interface**: Improved command-line tools for better developer experience
-
-### 🐛 Bug Fixes
+## [0.0.3-canary.7] - 2025-08-06
 
+- Native API Integration: Enhanced native module integration for better performance
+- Automated IP Resolution: Intelligent network detection eliminates manual IP configuration
+- Universal Build System: Streamlined one-command builds for both Android and iOS platforms
+- Enhanced CLI Interface: Improved command-line tools for better developer experience
 - Fixed IP address detection issues on development environments
 - Resolved build configuration conflicts between platforms
 - Improved error handling and recovery mechanisms
-
-### 🔧 Improvements
-
-- **Performance**: Optimized native module loading and execution
-- **Developer Experience**: Enhanced CLI with better error messages and debugging info
-- **Configuration**: Dynamic config updates without requiring restarts
-- **Build Process**: Faster and more reliable build pipeline
-
-### 🧪 Testing & Validation
-
-- ✅ **Android Build**: Verified APK generation, installation, and runtime behavior
-- ✅ **iOS Build**: Tested build process and device compatibility
-- ✅ **IP Detection**: Validated automatic network resolution across platforms
-- ✅ **Native Modules**: Confirmed API integration and performance benchmarks
-- ✅ **CLI Operations**: Tested enhanced command-line workflows and error handling
-
-### 🔄 Breaking Changes
-
-**None** - All changes maintain backward compatibility while enhancing existing functionality
-
-### 📝 Technical Details
-
+- Performance: Optimized native module loading and execution
+- Developer Experience: Enhanced CLI with better error messages and debugging info
+- Configuration: Dynamic config updates without requiring restarts
+- Build Process: Faster and more reliable build pipeline
+- Android Build: Verified APK generation, installation, and runtime behavior
+- iOS Build: Tested build process and device compatibility
+- IP Detection: Validated automatic network resolution across platforms
+- Native Modules: Confirmed API integration and performance benchmarks
+- CLI Operations: Tested enhanced command-line workflows and error handling
 - Improved native API bridge for better cross-platform communication
 - Enhanced error reporting with detailed stack traces and suggestions
 - Optimized build configuration for faster development cycles
 - Added comprehensive logging for debugging and monitoring
-
-### 🔗 Migration Notes
-
-- No migration steps required
-- Existing projects will automatically benefit from improvements
-- Optional: Update CLI usage to leverage new enhanced features
-
-## Version
-
-- Target version: 0.0.3-canary.7

package/dist/errors/generateDocs.js

@@ -0,0 +1,100 @@
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync, existsSync } from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+import { ERROR_DEFINITIONS } from "./registry.js"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// packages/catalyst-core/src/errors -> repo root /errors
+const DEFAULT_ERRORS_DIR = path.resolve(__dirname, "../../../../errors")
+
+function renderMarkdown(code, def) {
+    return `# ${code}
+
+**Category:** ${def.category}
+
+## Message
+
+${def.defaultMessage}
+
+## Details
+
+${def.defaultDetails}
+
+## Suggested action
+
+${def.suggestedAction}
+`
+}
+
+function clearGeneratedCategoryDirs(errorsDir) {
+    if (!existsSync(errorsDir)) return
+    const categories = new Set(Object.values(ERROR_DEFINITIONS).map((d) => d.category))
+    for (const category of categories) {
+        const dir = path.join(errorsDir, category)
+        if (existsSync(dir)) {
+            for (const file of readdirSync(dir)) {
+                if (file.endsWith(".md")) rmSync(path.join(dir, file))
+            }
+        }
+    }
+}
+
+// Other packages (e.g. create-catalyst-app) own their own categories and
+// merge their entries into this same index.json. Only clear/overwrite keys
+// for categories this registry itself defines, so a regen here never wipes
+// entries owned by another package's generator.
+function readExistingIndex(indexPath) {
+    if (!existsSync(indexPath)) return {}
+    try {
+        return JSON.parse(readFileSync(indexPath, "utf8"))
+    } catch {
+        return {}
+    }
+}
+
+/**
+ * Regenerate errors/**\/*.md + errors/index.json from ERROR_DEFINITIONS.
+ *
+ * `errorsDir` defaults to the real repo-root errors/ dir (the CLI/prepublish
+ * use case) but can be overridden — e.g. by the docs-drift contract test
+ * (see test/errors/docsDrift.test.js), which regenerates into a temp dir and
+ * diffs against the committed output rather than mutating it.
+ */
+export function generateDocs(errorsDir = DEFAULT_ERRORS_DIR) {
+    const indexPath = path.join(errorsDir, "index.json")
+
+    clearGeneratedCategoryDirs(errorsDir)
+
+    const ownedCategories = new Set(Object.values(ERROR_DEFINITIONS).map((d) => d.category))
+    const index = readExistingIndex(indexPath)
+    for (const code of Object.keys(index)) {
+        if (ownedCategories.has(index[code].category)) delete index[code]
+    }
+
+    for (const [code, def] of Object.entries(ERROR_DEFINITIONS)) {
+        const dir = path.join(errorsDir, def.category)
+        mkdirSync(dir, { recursive: true })
+        const filePath = path.join(dir, `${code}.md`)
+        writeFileSync(filePath, renderMarkdown(code, def))
+
+        index[code] = {
+            category: def.category,
+            message: def.defaultMessage,
+            details: def.defaultDetails,
+            suggestedAction: def.suggestedAction,
+            docUrl: `https://github.com/tata1mg/catalyst-core/blob/main/errors/${def.category}/${code}.md`,
+        }
+    }
+
+    mkdirSync(errorsDir, { recursive: true })
+    writeFileSync(indexPath, JSON.stringify(index, null, 4))
+
+    return { count: Object.keys(ERROR_DEFINITIONS).length, errorsDir }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const { count, errorsDir } = generateDocs()
+    console.log(`Generated ${count} error doc(s) + index.json in ${errorsDir}`)
+}

package/dist/errors/index.js

@@ -0,0 +1,243 @@
+import pc from "ansis"
+/**
+ * The "catalyst-core/errors" subpath export exists so catalyst's own
+ * packages (catalyst-ai, create-catalyst-app, etc.) can share this
+ * registry/CatalystError shape instead of each defining their own. It is
+ * not a recommendation for app code to throw CatalystError instead of
+ * Error — apps should keep using plain Error unless they're specifically
+ * interoperating with catalyst's own error codes.
+ */
+import { ERROR_CODES, getDefinition, getDocUrl } from "./registry.js"
+
+export { ERROR_CODES, getDocUrl }
+
+export class CatalystError extends Error {
+    constructor(code, { message, details, suggestedAction, category, docUrl, cause } = {}) {
+        super(message)
+        this.name = "CatalystError"
+        this.code = code
+        this.category = category
+        this.details = details
+        this.suggestedAction = suggestedAction
+        this.docUrl = docUrl
+        if (cause !== undefined) this.cause = cause
+    }
+}
+
+/**
+ * Create a CatalystError for a code we own, using registry.js defaults
+ * unless overridden.
+ */
+export function createError(code, overrides = {}) {
+    const def = getDefinition(code)
+    return new CatalystError(code, {
+        category: def.category,
+        message: overrides.message || def.defaultMessage,
+        details: overrides.details || def.defaultDetails,
+        suggestedAction: overrides.suggestedAction || def.suggestedAction,
+        docUrl: getDocUrl(code),
+        cause: overrides.cause,
+    })
+}
+
+const STAGE_WRAPPER_CODE = {
+    BUNDLE: ERROR_CODES.BUNDLE_UPSTREAM_ERROR,
+    IOS: ERROR_CODES.IOS_UPSTREAM_ERROR,
+    ANDROID: ERROR_CODES.ANDROID_UPSTREAM_ERROR,
+}
+
+const STAGE_UPSTREAM_NAME = {
+    BUNDLE: "Vite/Rollup",
+    IOS: "Xcode/CocoaPods",
+    ANDROID: "Gradle",
+}
+
+/**
+ * Wrap a foreign error (Vite/Rollup/native toolchain) that already carries
+ * its own code/message. We do not replace or reinterpret it — we attach a
+ * generic per-stage wrapper code and preserve the original as `cause`, so
+ * the upstream code/message is always what gets shown to the user.
+ */
+export function wrapForeignError(stage, err) {
+    const code = STAGE_WRAPPER_CODE[stage]
+    if (!code) {
+        throw new Error(`wrapForeignError: unknown stage "${stage}"`)
+    }
+    const upstreamName = STAGE_UPSTREAM_NAME[stage]
+    // Only show err.code when it's a real upstream identifier (e.g. Rollup's
+    // "PLUGIN_LOAD_ERROR"), not a bare numeric process exit status — a spawned
+    // child's exit code is not an "upstream error code" and would be misleading.
+    const hasNamedCode = err && typeof err.code === "string"
+    const upstreamCode = hasNamedCode ? ` ${upstreamName} ${err.code}` : ` ${upstreamName}`
+    const wrapped = createError(code, {
+        message: `Build failed (upstream:${upstreamCode})`,
+        cause: err,
+    })
+    return wrapped
+}
+
+const SSR_STAGE_CODE = {
+    RENDER: ERROR_CODES.RUNTIME_WEB_RENDER_FAILED,
+    FETCHER: ERROR_CODES.RUNTIME_WEB_FETCHER_FAILED,
+    SERVER_SIDE_FUNCTION: ERROR_CODES.RUNTIME_WEB_SERVER_SIDE_FUNCTION_FAILED,
+    REQUEST_HANDLING: ERROR_CODES.RUNTIME_WEB_REQUEST_HANDLING_FAILED,
+}
+
+/**
+ * Wrap an error caught during SSR (handler.jsx). Unlike wrapForeignError's
+ * build-stage wrapping, the caught error here could originate from the
+ * user's app code, a third-party dependency, or catalyst-core's own
+ * pipeline — there is no way to tell from the caught error object which.
+ * So, like the BUNDLE/IOS/ANDROID wrappers, we never reinterpret it: we
+ * attach a stage-specific code that identifies *where* in the SSR pipeline
+ * the failure happened, and preserve the original error as `cause`.
+ */
+export function wrapSSRError(stage, err) {
+    const code = SSR_STAGE_CODE[stage]
+    if (!code) {
+        throw new Error(`wrapSSRError: unknown stage "${stage}"`)
+    }
+    return createError(code, { cause: err })
+}
+
+/**
+ * Wrap a failed AI provider HTTP response (OpenAI/Gemini). Unlike
+ * wrapForeignError (build toolchains, which carry a named err.code), provider
+ * failures are an HTTP status + response body — we preserve both verbatim
+ * as `cause` rather than reinterpreting them.
+ */
+export function wrapProviderError(provider, status, bodyText) {
+    const cause = new Error(`${provider} API error (${status}): ${bodyText}`)
+    cause.provider = provider
+    cause.status = status
+    return createError(ERROR_CODES.AI_UPSTREAM_ERROR, {
+        message: `AI provider request failed (upstream: ${provider} ${status})`,
+        cause,
+    })
+}
+
+function formatDefault(err) {
+    const lines = [`[${err.code}] ${err.message}`]
+    if (err.cause) {
+        const causeMessage = err.cause.message || String(err.cause)
+        lines.push(`→ ${causeMessage}`)
+    } else if (err.details) {
+        lines.push(err.details)
+    }
+    if (err.suggestedAction) {
+        lines.push(`Suggested action: ${err.suggestedAction}`)
+    }
+    if (err.docUrl) {
+        lines.push(`Docs: ${err.docUrl}`)
+    }
+    return lines.join("\n")
+}
+
+const BOX_WIDTH = 70
+
+function box(bodyLines) {
+    const top = pc.red(`┌${"─".repeat(BOX_WIDTH)}`)
+    const bottom = pc.red(`└${"─".repeat(BOX_WIDTH)}`)
+    const body = bodyLines.map((line) => (line === "" ? pc.red("│") : `${pc.red("│")} ${line}`))
+    return [top, ...body, bottom].join("\n")
+}
+
+function formatCauseChain(cause) {
+    const lines = []
+    let current = cause
+    let depth = 0
+    while (current) {
+        const prefix = depth === 0 ? "Caused by:" : `  ${"  ".repeat(depth - 1)}Caused by:`
+        lines.push(`${prefix} ${current.message || String(current)}`)
+        current = current.cause
+        depth += 1
+    }
+    return lines
+}
+
+/**
+ * Verbose output: boxed per RFC #155 §3.2 — code, timestamp, problem,
+ * suggested action, docs link. Owns its own coloring (the box border and
+ * text are colored as a unit here) rather than leaving callers to wrap the
+ * whole multi-line block in a color function themselves.
+ */
+function formatVerbose(err) {
+    const lines = [
+        pc.bold(`❌ ${err.message}`),
+        `Code: ${err.code}`,
+        `Category: ${err.category || "UNKNOWN"}`,
+        `Time: ${new Date().toISOString()}`,
+        "",
+    ]
+    if (err.cause) {
+        lines.push(`Problem: ${err.cause.message || String(err.cause)}`)
+        lines.push("")
+    } else if (err.details) {
+        lines.push(`Problem: ${err.details}`)
+        lines.push("")
+    }
+    if (err.suggestedAction) {
+        lines.push("Solution:", `  ${err.suggestedAction}`, "")
+    }
+    if (err.docUrl) {
+        lines.push(`Docs: ${err.docUrl}`)
+    }
+    return box(lines)
+}
+
+/**
+ * Debug output: verbose + full cause chain + stack trace + environment
+ * info. Environment gathering happens here (Node-side), not as module-level
+ * state, so errors/index.js stays free of os/process imports and safe to
+ * bundle into the browser (see formatError's mode parameter below).
+ */
+function formatDebug(err, env) {
+    const lines = [
+        pc.bold(`❌ ${err.message}`),
+        `Code: ${err.code}`,
+        `Category: ${err.category || "UNKNOWN"}`,
+        `Time: ${new Date().toISOString()}`,
+        "",
+    ]
+    if (err.cause) {
+        lines.push(...formatCauseChain(err.cause), "")
+    } else if (err.details) {
+        lines.push(`Problem: ${err.details}`, "")
+    }
+    if (err.suggestedAction) {
+        lines.push("Solution:", `  ${err.suggestedAction}`, "")
+    }
+    if (err.docUrl) {
+        lines.push(`Docs: ${err.docUrl}`, "")
+    }
+    if (env) {
+        lines.push("Environment:")
+        for (const [key, value] of Object.entries(env)) {
+            lines.push(`  ${key}: ${value}`)
+        }
+        lines.push("")
+    }
+    lines.push("Stack trace:")
+    const stack = err.cause?.stack || err.stack || "(no stack available)"
+    lines.push(...stack.split("\n").map((l) => `  ${l}`))
+    return box(lines)
+}
+
+/**
+ * Format a CatalystError for terminal output. Foreign-wrapped errors always
+ * show the original upstream message/code, never a paraphrase of it.
+ *
+ * `mode` is a parameter, not module-level state — WebBridge.js (browser) has
+ * no process.argv/TTY and keeps calling formatError(err) unchanged, getting
+ * "default". Node call sites resolve their own mode (see
+ * scripts/scriptUtils.js#resolveOutputMode) and pass it through explicitly.
+ *
+ * `env` (debug mode only) is gathered by the caller, not here — keeps this
+ * module free of os/process imports so it stays safe to bundle into the
+ * browser regardless of which mode a Node caller happens to request.
+ */
+export function formatError(err, mode = "default", env) {
+    if (mode === "debug") return formatDebug(err, env)
+    if (mode === "verbose") return formatVerbose(err)
+    return formatDefault(err)
+}