@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/references/utilities/date.md

@@ -1,90 +1,50 @@
-# Date Utility
-
-The Date utility provides a set of functions for date and time manipulation, built on top of the powerful `dayjs` library. It also configures `dayjs` with useful plugins and a default timezone.
+---
+title: Date Utility
+description: Pre-configured dayjs re-export plus sleep, weekday, timezone, and high-resolution timing helpers
+difficulty: beginner
+lastUpdated: 2026-07-16
+---
 
-## `dayjs`
+# Date Utility
 
-The `dayjs` object is re-exported, so you can use it directly for any date and time operations. It is pre-configured with the following plugins: `CustomParseFormat`, `UTC`, `Timezone`, `Weekday`, and `IsoWeek`.
+A pre-configured `dayjs` re-export, plus small standalone helpers for sleeping, weekday math, timezone conversion, and high-resolution timing.
 
-The default timezone is set to `Asia/Ho_Chi_Minh` and can be overridden via the `APP_ENV_APPLICATION_TIMEZONE` environment variable.
+## In one example
 
 ```typescript
-import { dayjs } from '@venizia/ignis-helpers';
-
-// Get the current date and time
-const now = dayjs();
-
-// Format a date
-const formatted = now.format('YYYY-MM-DD HH:mm:ss');
-```
+import { dayjs, sleep, getDateTz } from '@venizia/ignis-helpers';
 
-## `sleep`
+const now = dayjs().format('YYYY-MM-DD HH:mm:ss');
 
-The `sleep` function pauses execution for a specified number of milliseconds.
+await sleep(2000); // pause for 2 seconds
 
-```typescript
-import { sleep } from '@venizia/ignis-helpers';
-
-async function myAsyncFunction() {
-  console.log('Start');
-  await sleep(2000); // Wait for 2 seconds
-  console.log('End');
-}
+const tokyoTime = getDateTz({ date: '2023-10-27T10:00:00Z', timezone: 'Asia/Tokyo' });
 ```
 
-## Weekday Functions
-
--   **`isWeekday(date)`**: Checks if a given date is a weekday (Monday to Friday). Accepts a `string` or `dayjs.Dayjs` instance.
--   **`getPreviousWeekday(opts?)`**: Returns the previous weekday from a given date. If no date is provided, defaults to today.
--   **`getNextWeekday(opts?)`**: Returns the next weekday from a given date. If no date is provided, defaults to today.
+## Functions
 
-```typescript
-import { isWeekday, getPreviousWeekday, getNextWeekday } from '@venizia/ignis-helpers';
-
-const isTodayWeekday = isWeekday('2026-03-15');
+| Function | Signature | What it does |
+|----------|-----------|---------------|
+| `dayjs` | re-exported `dayjs` object | The `dayjs` factory, pre-loaded with plugins - use it exactly like raw `dayjs`. |
+| `sleep` | `sleep(ms: number): Promise<void>` | Resolves after `ms` milliseconds (`setTimeout` wrapped in a Promise). |
+| `isWeekday` | `isWeekday(date: string \| dayjs.Dayjs): boolean` | `true` when `date` falls Monday through Friday (ISO weekday 1-5). |
+| `getPreviousWeekday` | `getPreviousWeekday(opts?: { date?: string \| dayjs.Dayjs }): dayjs.Dayjs` | Walks backward a day at a time from `date` (default: today) until it lands on a weekday. |
+| `getNextWeekday` | `getNextWeekday(opts?: { date?: string \| dayjs.Dayjs }): dayjs.Dayjs` | Walks forward a day at a time from `date` (default: today) until it lands on a weekday. |
+| `getDateTz` | `getDateTz(opts: { date: string; timezone: string; useClientTz?: boolean; timeOffset?: number }): dayjs.Dayjs` | Parses `date` and converts it to `timezone`, optionally shifting by `timeOffset` hours. |
+| `hrTime` | `hrTime(): number` | High-resolution seconds from `process.hrtime()`, rounded to 9 decimal places - for benchmarking. |
 
-const lastBusinessDay = getPreviousWeekday();
-const nextBusinessDay = getNextWeekday({ date: '2026-03-13' });
-```
+## Notes
 
-## `getDateTz`
+- **Plugins loaded once at module import:** `CustomParseFormat`, `UTC`, `Timezone`, `Weekday`, `IsoWeek`.
+- **Default timezone is `Asia/Ho_Chi_Minh`**, set via `dayjs.tz.setDefault()` at module load. Override with the `APP_ENV_APPLICATION_TIMEZONE` environment variable - it is read once, so changing it at runtime needs a restart.
+- **`getPreviousWeekday` / `getNextWeekday` are day-by-day loops**, not calendar lookups. They call `isWeekday()` after each step, so the worst case (stepping over a weekend) is only 2-3 iterations.
+- **`getDateTz`'s `useClientTz`** defaults to `false` and controls whether `dayjs().tz()` keeps the original wall-clock time or converts it - see the [Day.js Timezone plugin docs](https://day.js.org/docs/en/timezone/timezone) for the exact semantics.
 
-The `getDateTz` function allows you to get a `dayjs` object in a specific timezone, with an optional hour offset.
+## See also
 
-### `getDateTz(opts)`
+- [Utilities Overview](/references/utilities/) - all utility functions
+- [Day.js documentation](https://day.js.org/docs/en/installation/installation) - underlying date library
 
--   `opts` (object):
-    -   `date` (string): The date string to parse.
-    -   `timezone` (string): The IANA timezone name.
-    -   `useClientTz` (boolean, optional): Whether to keep the client's timezone. Defaults to `false`.
-    -   `timeOffset` (number, optional): Number of hours to add to the result. Defaults to `0`.
+**Files:**
 
-```typescript
-import { getDateTz } from '@venizia/ignis-helpers';
-
-const tokyoTime = getDateTz({
-  date: '2023-10-27T10:00:00Z',
-  timezone: 'Asia/Tokyo',
-});
-
-// With hour offset
-const offsetTime = getDateTz({
-  date: '2023-10-27T10:00:00Z',
-  timezone: 'Asia/Tokyo',
-  timeOffset: 2, // Add 2 hours
-});
-```
-
-## `hrTime`
-
-The `hrTime` function returns a high-resolution time measurement in seconds using `process.hrtime()`, useful for performance benchmarking. The result is rounded to 9 decimal places.
-
-```typescript
-import { hrTime } from '@venizia/ignis-helpers';
-
-const start = hrTime();
-// ... some long-running operation
-const end = hrTime();
-
-console.log(`Operation took ${end - start} seconds.`);
-```
+- [`packages/helpers/src/utilities/date.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/date.utility.ts)

package/content/references/utilities/duration.md

@@ -0,0 +1,85 @@
+---
+title: Duration Utility
+description: A unit vocabulary, written-duration parsing, and conversion between units and milliseconds
+difficulty: beginner
+lastUpdated: 2026-08-15
+---
+
+# Duration Utility
+
+A duration is `{ unit, value }`. This turns that into milliseconds, reads it out of a written string like `30d`, and converts between units.
+
+## In one example
+
+```typescript
+import { DurationMultipliers, DurationUnits } from '@venizia/ignis-helpers/common';
+
+const gracePeriod = { unit: DurationUnits.DAY, value: 30 };
+
+DurationMultipliers.toMilliseconds(gracePeriod); // 2_592_000_000
+DurationMultipliers.parseToMilliseconds('30d'); // 2_592_000_000
+DurationMultipliers.convert({ value: 36, from: 'hour', to: 'day' }); // 1.5
+```
+
+Everything here is browser-pure, so it works unchanged in a Worker. Import from `@venizia/ignis-helpers/common`, or from the root barrel if you already depend on it.
+
+## Units
+
+| Constant | Value | Milliseconds |
+|---|---|---|
+| `DurationUnits.MILLISECOND` | `'millisecond'` | 1 |
+| `DurationUnits.SECOND` | `'second'` | 1 000 |
+| `DurationUnits.MINUTE` | `'minute'` | 60 000 |
+| `DurationUnits.HOUR` | `'hour'` | 3 600 000 |
+| `DurationUnits.DAY` | `'day'` | 86 400 000 |
+| `DurationUnits.WEEK` | `'week'` | 604 800 000 |
+| `DurationUnits.MONTH` | `'month'` | 2 592 000 000 |
+| `DurationUnits.YEAR` | `'year'` | 31 536 000 000 |
+
+`TDurationUnit` is the union of those eight values. `IDuration` is `{ unit: TDurationUnit; value: number }`.
+
+## Functions
+
+| Function | Signature | What it does |
+|---|---|---|
+| `DurationUnits.isValid` | `isValid(input: string): input is TDurationUnit` | `true` when `input` is one of the eight canonical names. |
+| `DurationAliases.resolve` | `resolve(input: string): TDurationUnit \| null` | Reads a written unit - `'d'`, `'days'`, `'DAY'` - into its canonical name. |
+| `DurationMultipliers.toMilliseconds` | `toMilliseconds(opts: IDuration \| null): number \| null` | Converts a duration to milliseconds, rounded. |
+| `DurationMultipliers.fromMilliseconds` | `fromMilliseconds(opts: { milliseconds: number; unit: TDurationUnit }): number \| null` | The inverse. Fractional, not rounded. |
+| `DurationMultipliers.convert` | `convert(opts: { value: number; from: TDurationUnit; to: TDurationUnit }): number \| null` | Converts between two units. Fractional. |
+| `DurationMultipliers.parse` | `parse(input: string): IDuration \| null` | Reads `'30d'`, `'1500 ms'`, `'2 hours'` into an `IDuration`. |
+| `DurationMultipliers.parseToMilliseconds` | `parseToMilliseconds(input: string): number \| null` | `parse` followed by `toMilliseconds`. |
+
+## A month is 30 days and a year is 365
+
+These size a **window** - a grace period, a cache TTL, a near-expiry horizon. They are not calendar arithmetic.
+
+Adding `MONTH` to 31 January lands on 2 March in a leap year and 3 March otherwise. If you need a real calendar date, use [the date utility](./date.md) and let `dayjs` handle months.
+
+## Every function answers `null`, never throws
+
+An unknown unit, a `NaN` value, an unreadable string - all return `null`. A caller that wants an error raises its own, with its own context:
+
+```typescript
+const ttlMs = DurationMultipliers.parseToMilliseconds(config.cacheTtl);
+
+if (ttlMs === null) {
+  throw getError({ message: `[cache] Unreadable TTL: '${config.cacheTtl}'` });
+}
+```
+
+Zero is a real duration, not an absent one - `{ unit: 'day', value: 0 }` converts to `0`. A negative value converts too, so a caller deciding what a negative window means keeps that decision.
+
+## Writing a duration
+
+`parse` accepts one number, an optional space, and one unit: `30d`, `1.5h`, `-2 Hours`, `1500 ms`. Anything it cannot read whole is `null` - there is no partial credit, so `'30d extra'` fails rather than silently meaning 30 days.
+
+Accepted spellings are the member names of `DurationAliases`, lower-cased: short (`d`), abbreviated (`wk`), singular (`day`) and plural (`days`).
+
+**`m` is minute and `mo` is month.** That is the choice every duration library makes, and the one ambiguity worth checking before you write a config value. There is no single-letter month.
+
+## Notes
+
+- **The fast path allocates nothing.** `resolve` tries your input as given before normalising it, so a canonical `'day'` costs about 2ns while a messy `'  Days '` pays the ~80ns that trimming and upper-casing costs. Pass canonical spellings in a loop.
+- **`toMilliseconds` rounds; `fromMilliseconds` and `convert` do not.** Rounding on the way out would silently lose a 36-hour window asked for in days.
+- **The alias table is derived from `DurationAliases`**, not hand-listed beside it, so a new spelling is one member and the two cannot drift.

package/content/references/utilities/index.md

@@ -8,12 +8,14 @@ Pure, standalone functions providing common, reusable logic for the IGNIS framew
 |---------|---------|---------|---------------|
 | **Crypto** | `ignis-helpers` | Cryptographic hashing | `hash()` |
 | **Date** | `ignis-helpers` | Date/time manipulation | `dayjs`, `sleep()`, `isWeekday()`, `getDateTz()`, `hrTime()` |
+| **Duration** | `ignis-helpers` | Duration units and conversion | `DurationUnits`, `DurationMultipliers.toMilliseconds()`, `.parseToMilliseconds()` |
 | **JSX** | `ignis` | HTML/JSX responses | `htmlContent()`, `htmlResponse()` |
-| **Module** | `ignis-helpers` | Module validation | `validateModule()` |
+| **Module** | `ignis-helpers` | Optional peer loading | `ModuleUtility` |
 | **Parse** | `ignis-helpers` | Data type conversion | `int()`, `float()`, `toBoolean()`, `toCamel()` |
 | **Performance** | `ignis-helpers` | Execution timing | `executeWithPerformanceMeasure()`, `getPerformanceCheckpoint()` |
 | **Promise** | `ignis-helpers` | Promise helpers | `executePromiseWithLimit()`, `isPromiseLike()`, `getDeepProperty()` |
 | **Request** | `ignis-helpers` | HTTP utilities | `parseMultipartBody()`, `sanitizeFilename()`, `createContentDispositionHeader()` |
+| **Retry** | `ignis-helpers` | Backoff-driven retries | `executeWithRetry()`, `executeWithRetryUntil()`, `computeBackoffDelayMs()` |
 | **Schema** | `ignis` | Zod schema helpers | `jsonContent()`, `jsonResponse()`, `requiredString()`, `idParamsSchema()` |
 | **Statuses** | `ignis` | Status code constants | `Statuses`, `CommonStatuses`, `UserStatuses`, `RoleStatuses` |
 
@@ -22,13 +24,14 @@ Pure, standalone functions providing common, reusable logic for the IGNIS framew
 ### Data Processing
 
 - [**Crypto**](./crypto.md) - Simple, stateless cryptographic functions for hashing (SHA256 HMAC, MD5)
-- [**Parse**](./parse.md) - Functions for parsing and converting data types safely (integers, floats, booleans, camelCase, locale-aware numbers, array-to-map)
+- [**Parse**](./parse.md) - Functions for parsing and converting data types safely (integers, floats, booleans, camelCase, array-to-map)
 - [**Schema**](./schema.md) - Helpers for creating Zod schemas for OpenAPI request/response validation
 - [**Statuses**](./statuses.md) - Standardized status code constants for entity lifecycle management
 
 ### Time & Performance
 
 - [**Date**](./date.md) - Date and time manipulation functions built on `dayjs` with timezone support
+- [**Duration**](./duration.md) - A unit vocabulary, written-duration parsing, and conversion between units and milliseconds
 - [**Performance**](./performance.md) - Utilities for measuring code execution time and performance profiling
 
 ### Async & HTTP
@@ -36,6 +39,7 @@ Pure, standalone functions providing common, reusable logic for the IGNIS framew
 - [**JSX**](./jsx.md) - HTML and JSX response utilities for server-side rendering and OpenAPI documentation
 - [**Promise**](./promise.md) - Helper functions for working with Promises including concurrency limiting and value transformation
 - [**Request**](./request.md) - HTTP request utilities for parsing multipart form data and creating secure Content-Disposition headers
+- [**Retry**](./retry.md) - Backoff-driven retry helpers - error-triggered (`executeWithRetry`) and predicate-driven (`executeWithRetryUntil`)
 
 ### Runtime
 

package/content/references/utilities/jsx-reference.md

@@ -0,0 +1,298 @@
+---
+title: JSX/HTML Utility - Full Reference
+description: Complete reference for the JSX/HTML response helpers, defineJSXRoute, and Hono JSX component patterns
+difficulty: beginner
+---
+
+# JSX/HTML Utility - Full Reference
+
+Exhaustive reference for `htmlContent()`, `htmlResponse()`, and `BaseRestController.defineJSXRoute()`. For a readable introduction and the common tasks, start with the [JSX/HTML overview](/references/utilities/jsx).
+
+**Files:**
+
+- [`packages/core-server/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/utilities/jsx.utility.ts) - `htmlContent`, `htmlResponse`
+- [`packages/core-server/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/base.ts) - `BaseRestController.defineJSXRoute`
+- [`packages/core-server/src/base/controllers/rest/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/abstract.ts) - `AbstractRestController.getJSXRouteConfigs`
+- [`packages/helpers/src/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/common/types.ts) - `FC`, `PropsWithChildren`, `Child` (re-exported from `hono/jsx`)
+
+## `htmlContent()`
+
+Creates a standard OpenAPI content object for `text/html` responses.
+
+`Source ->` [`packages/core-server/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/utilities/jsx.utility.ts)
+
+```typescript
+const htmlContent = (opts: { description: string; required?: boolean }) => ({
+  description: opts.description,
+  content: {
+    'text/html': {
+      schema: z.string().openapi({
+        description: 'HTML content',
+        example: '<!DOCTYPE html><html><head><title>Page</title></head><body>...</body></html>',
+      }),
+    },
+  },
+  required: opts.required ?? false,
+});
+```
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `description` | `string` | Yes | - | Description of the HTML content, shown in the generated OpenAPI document |
+| `required` | `boolean` | No | `false` | Whether the content is required |
+
+### Returns
+
+An OpenAPI content configuration object: `description`, `content['text/html'].schema` (a `z.string()`), and `required`.
+
+## `htmlResponse()`
+
+Creates a standard OpenAPI response object for HTML endpoints. It pairs a success (`200`) HTML response with a JSON error response for `4xx | 5xx` status codes using `ErrorSchema`.
+
+`Source ->` [`packages/core-server/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/utilities/jsx.utility.ts)
+
+```typescript
+const htmlResponse = (opts: { description: string; required?: boolean }) => ({
+  [HTTP.ResultCodes.RS_2.Ok]: htmlContent({ description: opts.description, required: opts.required }),
+  ['4xx | 5xx']: {
+    description: 'Error Response',
+    content: { 'application/json': { schema: ErrorSchema } },
+  },
+});
+```
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `description` | `string` | Yes | - | Description of the successful HTML response |
+| `required` | `boolean` | No | `false` | Whether the content is required |
+
+### Returns
+
+A responses object: `200` (via `htmlContent()`) plus `4xx | 5xx` (JSON `ErrorSchema`).
+
+```typescript
+import { htmlResponse } from '@venizia/ignis';
+
+this.defineRoute({
+  configs: {
+    path: '/dashboard',
+    method: 'get',
+    responses: htmlResponse({ description: 'Dashboard HTML page' }),
+  },
+  handler: c => c.html(<h1>Dashboard</h1>),
+});
+```
+
+## `BaseRestController.defineJSXRoute()`
+
+Defines and registers a JSX/HTML route in a single call - the JSX counterpart of `defineRoute()`.
+
+`Source ->` [`packages/core-server/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/base.ts)
+
+```typescript
+defineJSXRoute<RouteConfig extends IAuthRouteConfig, ResponseType = unknown>(opts: {
+  configs: RouteConfig;
+  handler: TRouteHandler<ResponseType, RouteEnv>;
+  hook?: Hook<any, RouteEnv, string, ValueOrPromise<any>>;
+}): IDefineRouteOptions<RouteConfig, RouteEnv, RouteSchema, BasePath>
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `configs` | `RouteConfig` (extends `IAuthRouteConfig`) | Yes | `path`, `method`, `responses`, plus the same `authenticate`/`authorize`/`request`/`middleware` fields `defineRoute` accepts |
+| `handler` | `TRouteHandler<ResponseType, RouteEnv>` | Yes | Receives the route context (`TRouteContext`); return `c.html(<Component />)` |
+| `hook` | `Hook<...>` | No | Same validation hook `defineRoute` accepts |
+
+### Behavior
+
+`defineJSXRoute` is `defineRoute` with one difference: it builds the route configuration through `getJSXRouteConfigs` instead of `getRouteConfigs`.
+
+`Source ->` [`packages/core-server/src/base/controllers/rest/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/abstract.ts)
+
+```typescript
+getJSXRouteConfigs<RouteConfig extends IAuthRouteConfig>(opts: { configs: RouteConfig }) {
+  const { restConfig, security, mws } = this.buildRouteMiddlewares(opts);
+  const { responses, tags = [] } = restConfig;
+
+  return createRoute<string, RouteConfig>(
+    Object.assign({}, restConfig, {
+      middleware: mws,
+      responses: Object.assign({}, htmlResponse({ description: 'HTML page' }), responses),
+      tags: [...tags, this.scope],
+      security,
+    }) as any,
+  );
+}
+```
+
+- **Default response merged in first.** `htmlResponse({ description: 'HTML page' })` is the base object. Your own `responses` is merged over it with `Object.assign`, so any status code you declare (typically `200`) overrides the default entry with the same key.
+- **Everything else matches `defineRoute`.** Auth middleware, tags (`this.scope` is always appended), and OpenAPI security are built the same way as JSON routes via `buildRouteMiddlewares`.
+- **Handler contract is unchanged.** The handler still returns whatever `c.html(...)` produces (a `Response`). `defineJSXRoute` only changes how the route's OpenAPI shape is computed, not how the handler runs.
+
+## JSX setup
+
+### `tsconfig.json`
+
+`.tsx` files compile against Hono's JSX runtime, not React's:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx"
+  }
+}
+```
+
+Verified in [`packages/core-server/tsconfig.json`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/tsconfig.json) and the JSX example app's [`examples/rpc-api-server/tsconfig.json`](https://github.com/VENIZIA-AI/ignis/blob/main/examples/rpc-api-server/tsconfig.json).
+
+### Component types
+
+`FC`, `PropsWithChildren`, and `Child` are re-exported from `@venizia/ignis-helpers` (sourced from `hono/jsx`) - import them from there rather than reaching into `hono/jsx` directly.
+
+`Source ->` [`packages/helpers/src/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/common/types.ts)
+
+```typescript
+export type { Child, FC, PropsWithChildren } from 'hono/jsx';
+```
+
+### No separate renderer
+
+IGNIS registers no `jsxRenderer` middleware and no template engine. A handler builds a JSX tree and calls Hono's own `c.html()` on it - that call is what triggers rendering to an HTML string.
+
+## Component patterns
+
+### Layout composition
+
+A layout component takes `children` (typed via `PropsWithChildren`) and wraps them in the surrounding document shell. Page components render into a layout the same way any JSX component nests another.
+
+```tsx
+import type { FC, PropsWithChildren } from '@venizia/ignis-helpers';
+
+interface MainLayoutProps {
+  title: string;
+  description?: string;
+}
+
+export const MainLayout: FC<PropsWithChildren<MainLayoutProps>> = ({ title, description, children }) => (
+  <html lang="en">
+    <head>
+      <meta charSet="UTF-8" />
+      <title>{title}</title>
+      {description && <meta name="description" content={description} />}
+    </head>
+    <body>
+      <main>{children}</main>
+    </body>
+  </html>
+);
+
+interface HomePageProps {
+  timestamp?: string;
+}
+
+export const HomePage: FC<HomePageProps> = ({ timestamp }) => (
+  <MainLayout title="Home" description="Welcome to IGNIS">
+    <h1>Welcome to IGNIS!</h1>
+    {timestamp && <p>Page rendered at: {timestamp}</p>}
+  </MainLayout>
+);
+```
+
+### Wiring pages into a controller
+
+```tsx
+import { BaseRestController, controller, htmlContent, type IControllerOptions, type ValueOrPromise } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
+import { HomePage } from '@/views/pages/home.page';
+
+@controller({ path: '/' })
+export class ViewController extends BaseRestController {
+  constructor(opts: IControllerOptions) {
+    super({ ...opts, scope: ViewController.name, path: '/' });
+  }
+
+  override binding(): ValueOrPromise<void> {
+    this.defineJSXRoute({
+      configs: {
+        path: '/',
+        method: 'get',
+        description: 'Home page rendered with JSX',
+        tags: ['Views'],
+        responses: {
+          [HTTP.ResultCodes.RS_2.Ok]: htmlContent({ description: 'Home page HTML' }),
+        },
+      },
+      handler: c => {
+        const timestamp = new Date().toISOString();
+        return c.html(<HomePage timestamp={timestamp} />);
+      },
+    });
+  }
+}
+```
+
+### Raw HTML with `dangerouslySetInnerHTML`
+
+Hono JSX's intrinsic elements accept a `dangerouslySetInnerHTML` prop - an object with an `__html` string - matching React's escape hatch. Use it only for HTML you already trust (a stored template, sanitized markdown output) - never for unsanitized user input.
+
+```tsx
+async previewTemplate(c: TRouteContext) {
+  const { templateId } = c.req.valid<{ templateId: string }>('param');
+  const template = await this.emailService.getTemplate(templateId);
+
+  return c.html(
+    <html>
+      <head>
+        <title>Email Preview: {template.subject}</title>
+      </head>
+      <body>
+        <div dangerouslySetInnerHTML={{ __html: template.html }} />
+      </body>
+    </html>,
+  );
+}
+```
+
+## Comparison with JSON utilities
+
+### `htmlContent` vs `jsonContent`
+
+| Aspect | `htmlContent()` | `jsonContent()` |
+|--------|------------------|-------------------|
+| Content type | `text/html` | `application/json` |
+| Schema | `z.string()` | Caller-supplied Zod schema |
+| Use case | HTML pages, JSX rendering | API responses, structured data |
+
+### `htmlResponse` vs `jsonResponse`
+
+| Aspect | `htmlResponse()` | `jsonResponse()` |
+|--------|---------------------|----------------------|
+| Success type | `text/html` (`200`) | `application/json` (`200`) |
+| Error type | `application/json` (`4xx \| 5xx`) | `application/json` (`4xx \| 5xx`) |
+| Use case | Server-rendered web pages | REST APIs |
+
+See [Schema Utility](./schema.md) for `jsonContent`/`jsonResponse`.
+
+## Route definition choices
+
+`defineJSXRoute` is the recommended way to register a JSX route because it fills in a default HTML `200` response automatically. Two equivalent alternatives exist when you need more control:
+
+| Approach | When to use |
+|----------|-------------|
+| `this.defineJSXRoute({ configs, handler })` | Default choice - HTML response shape is inferred, override `responses[200]` only if you need a custom description |
+| `this.defineRoute({ configs: { responses: htmlResponse({ description }) }, handler })` | You want the full `responses` object built explicitly via `htmlResponse()`, without relying on the JSX default merge |
+| `this.bindRoute({ configs }).to({ handler })` | Fluent two-step registration, same `configs` shape as either of the above |
+
+Authentication and authorization on a JSX route use the same `configs.authenticate` / `configs.authorize` fields as JSON routes - see [Controllers](../base/controllers.md).
+
+## See also
+
+- [JSX/HTML overview](/references/utilities/jsx) - introduction and common tasks
+- [Schema Utility](./schema.md) - `jsonContent`, `jsonResponse`, and the wider response-helper family
+- [Controllers](../base/controllers.md) - `defineRoute`, `bindRoute`, route configuration, authentication
+- **External:** [Hono JSX Documentation](https://hono.dev/docs/guides/jsx)