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

package/changelog.md

@@ -8,6 +8,86 @@
 
 # Changelog
 
+## [0.4.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.
+
+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.
+
 ## [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.

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)
+}