@kerfjs/ui 5.0.0-beta.94 → 5.0.0-beta.95

package/README.md

@@ -382,8 +382,10 @@ relationships from that extension; `kerf-catalog-demo --write` emits a typed
 module and `--check` catches drift. See the [catalog guide](./docs/catalog.md)
 for repository base and source path configuration. To offer the catalog's
 **Capture region** link to UX Review on a local server, add the Node-only
-`uxReviewPlugin` from `@kerfjs/ui/vite-ux-review` to the Vite config and pass
-`wireCatalog`'s `onUxReviewProject` result to `Catalog`'s `uxReview` (the
+`uxReviewPlugin` from `@kerfjs/ui/vite-ux-review` to the Vite config (or, for a
+catalog your own backend serves, mount its `uxReviewProjectResponse` /
+`uxReviewMiddleware` on the development server) and pass `wireCatalog`'s
+`onUxReviewProject` result to `Catalog`'s `uxReview` (the
 [catalog guide](./docs/catalog.md#ux-review-capture) has the wiring).
 
 Composition-aware consumers use

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.94` and `kerfjs@5.0.0-beta.94`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.95` and `kerfjs@5.0.0-beta.95`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 

package/ai/skill.md

@@ -143,7 +143,9 @@ components, derive demo rows with `@kerfjs/ui/catalog-projection` or
 `kerf-catalog-demo --write`, then guard drift with `--check`; see
 `../docs/catalog.md`. For a local catalog's UX Review **Capture region** link,
 add `uxReviewPlugin()` from the Node-only `@kerfjs/ui/vite-ux-review` to the
-Vite config, report the project with `wireCatalog`'s `onUxReviewProject`, and
+Vite config (a catalog served by the app's own backend mounts that subpath's
+`uxReviewProjectResponse` or `uxReviewMiddleware` on its development server
+only), report the project with `wireCatalog`'s `onUxReviewProject`, and
 render `Catalog` with `uxReview={{ projectDirectory }}`; never hand-roll the
 endpoint or the `uxreview://` link. For per-entry variant/state controls, pass
 them as `Catalog`'s `settings` (with `settingsCollapsed` and the same signal as

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.94` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.95` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/docs/catalog.md

@@ -542,6 +542,47 @@ wireCatalog(app, {
 The browser helpers behind it, `uxReviewCaptureUrl` and `loadUxReviewProject`,
 are exported from `@kerfjs/ui/catalog` for a capture link placed elsewhere.
 
+### Catalogs served without Vite
+
+A catalog served by the app's own backend (an esbuild bundle behind Hono,
+Express, or a plain Node server) mounts the same endpoint from the same
+Node-only subpath, on its development server only. The catalog requests
+`__ux-review/project.json` relative to its page, so a page at `/ux-demo` asks
+for `/__ux-review/project.json`; both helpers answer at any base path.
+
+```ts
+import {
+  resolveUxReviewProject,
+  uxReviewMiddleware,
+  uxReviewProjectResponse,
+} from "@kerfjs/ui/vite-ux-review";
+
+// Resolve once at startup: the repository holding the working directory, or
+// resolveUxReviewProject({ root, projectDirectory }) like the Vite plugin.
+const projectDirectory = resolveUxReviewProject();
+
+// Fetch API servers (Hono, Bun, Deno): null means "not this endpoint".
+if (isDev)
+  app.use("*", async (c, next) =>
+    uxReviewProjectResponse(c.req.raw, projectDirectory) ?? next(),
+  );
+
+// Node / connect servers (Express, node:http):
+if (isDev) expressApp.use(uxReviewMiddleware(projectDirectory));
+```
+
+- **`resolveUxReviewProject({ root?, projectDirectory? })`** returns the real
+  path the Vite plugin would serve: `projectDirectory` resolved against `root`,
+  or the repository holding `root` (default `process.cwd()`).
+- **`uxReviewProjectResponse(request, projectDirectory)`** answers a Fetch API
+  `Request`: the JSON for a GET, `405` for another method, or `null` for any
+  other path.
+- **`uxReviewMiddleware(projectDirectory)`** is the same endpoint as a
+  `(request, response, next)` handler; `uxReviewPlugin` mounts it on Vite.
+
+Never register the endpoint in production: it reveals a local path, and a
+deployed catalog has no local project to capture into.
+
 ## Custom action names
 
 The shell emits `data-action="catalog-select"` (sidebar items),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.94",
+  "version": "5.0.0-beta.95",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",

package/vite-ux-review.d.mts

@@ -38,6 +38,45 @@ export interface UxReviewPlugin {
 /** The nearest directory at or above `start` that holds `.git`, else `start`. */
 export declare function findProjectDirectory(start: string): string;
 
+export interface ResolveUxReviewProjectOptions {
+  /** The directory to start from. Default: `process.cwd()`. */
+  root?: string;
+  /**
+   * An explicit project directory, resolved against `root`. Default: the
+   * nearest ancestor of `root` holding `.git`, or `root` itself.
+   */
+  projectDirectory?: string;
+}
+
+/** The real path of the UX Review project directory for a server. */
+export declare function resolveUxReviewProject(
+  options?: ResolveUxReviewProjectOptions,
+): string;
+
+/**
+ * Answer a Fetch API request for `…/__ux-review/project.json` at any base
+ * path: the project JSON for a GET, 405 for another method, or `null` for any
+ * other path so the server handles it as usual. Mount it on a development
+ * server only.
+ */
+export declare function uxReviewProjectResponse(
+  request: Request,
+  projectDirectory: string,
+): Response | null;
+
+/** A Node / connect `(request, response, next)` handler for a server's middleware stack. */
+export type UxReviewMiddleware = Parameters<
+  UxReviewMiddlewareServer['middlewares']['use']
+>[0];
+
+/**
+ * A Node / connect-style handler for `…/__ux-review/project.json` at any base
+ * path; other requests go to `next`. Mount it on a development server only.
+ */
+export declare function uxReviewMiddleware(
+  projectDirectory: string,
+): UxReviewMiddleware;
+
 /** Serve the UX Review project directory to catalog pages on dev and preview servers. */
 export declare function uxReviewPlugin(
   options?: UxReviewPluginOptions,

package/vite-ux-review.mjs

@@ -1,15 +1,21 @@
 /**
- * `@kerfjs/ui/vite-ux-review` — a Node-only Vite plugin that tells a local
- * catalog page which project it belongs to, so the catalog can offer a UX
- * Review "Capture region" link (see `wireCatalog`'s `onUxReviewProject` and
- * the Catalog's `uxReview` prop in `@kerfjs/ui/catalog`).
+ * `@kerfjs/ui/vite-ux-review` — Node-only helpers that tell a local catalog
+ * page which project it belongs to, so the catalog can offer a UX Review
+ * "Capture region" link (see `wireCatalog`'s `onUxReviewProject` and the
+ * Catalog's `uxReview` prop in `@kerfjs/ui/catalog`).
  *
- * It answers `GET …/__ux-review/project.json` with `{ projectDirectory }` on
- * the dev and preview servers. It imports nothing from Vite and never reaches
- * a browser bundle; a static build has no endpoint, so the link stays hidden.
+ * The endpoint answers `GET …/__ux-review/project.json` with
+ * `{ projectDirectory }`. `uxReviewPlugin()` mounts it on Vite's dev and
+ * preview servers; an app that serves its catalog from its own backend mounts
+ * `uxReviewProjectResponse()` (Fetch API servers) or `uxReviewMiddleware()`
+ * (Node / connect servers) instead, on its development server only. Nothing
+ * here imports Vite or reaches a browser bundle; a static build has no
+ * endpoint, so the link stays hidden.
  */
 import { existsSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import process from 'node:process';
+import { URL } from 'node:url';
 
 /** Where the endpoint lives, relative to the catalog page. */
 export const UX_REVIEW_PROJECT_PATH = '__ux-review/project.json';
@@ -24,15 +30,53 @@ export function findProjectDirectory(start) {
 }
 
 /**
- * Serve the UX Review project directory to catalog pages. By default it is
- * the repository holding Vite's `root` (the nearest ancestor with `.git`, or
- * `root` itself); `projectDirectory` overrides it, resolved against `root`.
+ * The real path of the UX Review project directory: `projectDirectory`
+ * resolved against `root` when given, otherwise the repository holding `root`
+ * (the nearest ancestor with `.git`, or `root` itself). `root` defaults to the
+ * current working directory.
  */
-export function uxReviewPlugin(options = {}) {
-  let projectDirectory = '';
-  const serve = (request, response, next) => {
+export function resolveUxReviewProject({
+  root = process.cwd(),
+  projectDirectory,
+} = {}) {
+  return realpathSync(
+    projectDirectory
+      ? resolve(root, projectDirectory)
+      : findProjectDirectory(root),
+  );
+}
+
+const isEndpoint = (path) => path.endsWith(`/${UX_REVIEW_PROJECT_PATH}`);
+const JSON_HEADERS = {
+  'Content-Type': 'application/json; charset=utf-8',
+  'Cache-Control': 'no-store',
+};
+
+/**
+ * Answer a Fetch API request for the endpoint, at any base path: the project
+ * JSON for a GET, 405 for another method, or `null` when the request is for
+ * some other path so the server handles it as usual.
+ */
+export function uxReviewProjectResponse(request, projectDirectory) {
+  if (!isEndpoint(new URL(request.url).pathname)) return null;
+  if (request.method !== 'GET')
+    return new globalThis.Response(null, {
+      status: 405,
+      headers: { Allow: 'GET' },
+    });
+  return new globalThis.Response(JSON.stringify({ projectDirectory }), {
+    headers: JSON_HEADERS,
+  });
+}
+
+/**
+ * A Node / connect-style `(request, response, next)` handler for the
+ * endpoint, at any base path; other requests go to `next`.
+ */
+export function uxReviewMiddleware(projectDirectory) {
+  return (request, response, next) => {
     const path = (request.url ?? '').split(/[?#]/)[0];
-    if (!path.endsWith(`/${UX_REVIEW_PROJECT_PATH}`)) {
+    if (!isEndpoint(path)) {
       next();
       return;
     }
@@ -42,17 +86,28 @@ export function uxReviewPlugin(options = {}) {
       response.end();
       return;
     }
-    response.setHeader('Content-Type', 'application/json; charset=utf-8');
-    response.setHeader('Cache-Control', 'no-store');
+    for (const [name, value] of Object.entries(JSON_HEADERS))
+      response.setHeader(name, value);
     response.end(JSON.stringify({ projectDirectory }));
   };
+}
+
+/**
+ * Serve the UX Review project directory to catalog pages on Vite's dev and
+ * preview servers. By default it is the repository holding Vite's `root`;
+ * `projectDirectory` overrides it, resolved against `root`.
+ */
+export function uxReviewPlugin(options = {}) {
+  let handler = uxReviewMiddleware('');
+  const serve = (request, response, next) => handler(request, response, next);
   return {
     name: 'kerf-ux-review',
     configResolved(config) {
-      projectDirectory = realpathSync(
-        options.projectDirectory
-          ? resolve(config.root, options.projectDirectory)
-          : findProjectDirectory(config.root),
+      handler = uxReviewMiddleware(
+        resolveUxReviewProject({
+          root: config.root,
+          projectDirectory: options.projectDirectory,
+        }),
       );
     },
     configureServer(server) {