@jini-ai/cms 0.5.4 → 0.5.5

package/dist/navigation/agent-tools.js

@@ -71,6 +71,18 @@ const MENU_ID_SCHEMA = {
     type: "string",
     description: "The menu's id, as returned by menus_list_menus, menus_get_menu, or menus_create_menu.",
 };
+/** HTML mode (2026-10-08, `menu-html.ts`): the same two fields on create and update. */
+const MENU_MODE_SCHEMA = {
+    type: "string",
+    enum: ["items", "html"],
+    description: "What the site renders for this menu: 'items' (the item tree, the default) or 'html' (the menu's own 'html'). Switching keeps the other mode's data. Omit to leave unchanged.",
+};
+const MENU_HTML_SCHEMA = {
+    type: "string",
+    maxLength: 200000,
+    description: "The menu's own HTML for 'html' mode — any markup and classes, e.g. '<ul class=\"nav\"><li><a href=\"/\">Home</a></li></ul>'. " +
+        "Rendered inside the theme element that holds the menu's marker. Needs raw-HTML permission (admins/owners). Omit to leave unchanged.",
+};
 /**
  * A link target, published as a `oneOf` over the 4 v1 kinds `menu-service.ts`'s `validateTarget`
  * accepts (`entryRef`/`termRef`/`url`/`route`) — `dynamicQuery`/`content` are named-but-rejected
@@ -208,6 +220,8 @@ export const menusAgentToolCatalog = [
                 title: { type: "string", minLength: 1, description: "Human-readable menu name." },
                 slug: { type: "string", pattern: "^[a-z0-9-]+$", description: "Stable machine handle. Lowercase letters, digits, and hyphens only." },
                 items: { ...ITEMS_TREE_SCHEMA, description: "Optional initial item tree. Defaults to an empty menu if omitted." },
+                mode: MENU_MODE_SCHEMA,
+                html: MENU_HTML_SCHEMA,
             },
         },
     },
@@ -215,19 +229,22 @@ export const menusAgentToolCatalog = [
         name: "menus_update_menu_tree",
         description: "Replaces an existing menu's whole item tree (and optionally its title/slug) in one version-guarded write. " +
             "Always a whole-tree replace — there is no per-item patch operation, so the submitted tree must include every " +
-            "item the menu keeps, each with its fields copied unchanged from the read. To delete a menu, use trash_item with entityType 'menu' (it moves to the Trash and can be restored).",
+            "item the menu keeps, each with its fields copied unchanged from the read. For a hand-written HTML menu, send " +
+            "'html' (and 'mode': 'html') and omit 'items' to keep the stored tree. To delete a menu, use trash_item with entityType 'menu' (it moves to the Trash and can be restored).",
         sideEffects: "mutates-durable-state",
         authorization: { permission: "admin.menus.update" },
         inputSchema: {
             type: "object",
             additionalProperties: false,
-            required: ["menuId", "expectedVersion", "items"],
+            required: ["menuId", "expectedVersion"],
             properties: {
                 menuId: MENU_ID_SCHEMA,
                 expectedVersion: { type: "integer", description: "The menu's current 'version', as last returned by a read or write on it — the optimistic-concurrency guard. A stale value is rejected with a conflict naming the current version." },
                 title: { type: "string", description: "New title. Omit to leave unchanged." },
                 slug: { type: "string", pattern: "^[a-z0-9-]+$", description: "New slug. Omit to leave unchanged. Must not collide with another menu's slug." },
-                items: ITEMS_TREE_SCHEMA,
+                items: { ...ITEMS_TREE_SCHEMA, description: "The full replacement item tree. Omit to keep the stored tree (e.g. an HTML-only edit); send at least one of items, html or mode." },
+                mode: MENU_MODE_SCHEMA,
+                html: MENU_HTML_SCHEMA,
             },
         },
     },

package/dist/navigation/index.d.ts

@@ -4,7 +4,7 @@
  * A module's public contract is its `index.ts` — deep imports
  * from outside this directory should go through here.
  */
-export type { NavTargetKind, ReservedNavTargetKind, NavTarget, NavEntryTarget, NavTermTarget, NavUrlTarget, NavRouteTarget, NavItemAttrs, NavItemNode, NavMenuDoc, NavMenuEntry, MenuStatus, NavLocationKey, NavLocationBindingRow, NavLocationDescriptor, ResolvedNavItem, ResolvedNav, } from "./types.js";
+export type { NavTargetKind, ReservedNavTargetKind, NavTarget, NavEntryTarget, NavTermTarget, NavUrlTarget, NavRouteTarget, NavItemAttrs, NavItemNode, NavMenuDoc, NavMenuMode, NavMenuEntry, MenuStatus, NavLocationKey, NavLocationBindingRow, NavLocationDescriptor, ResolvedNavItem, ResolvedNav, } from "./types.js";
 export { NAV_MENU_CONTENT_TYPE, NAV_FIELD_NAMESPACE, NAV_DOC_TYPE } from "./types.js";
 export type { NavLocationBindingRepoPort, NavResolveContext, NavTargetResolver, NavMenuReadModel, NavLocationRegistry, } from "./ports.js";
 export type { NavigationPermission, CreateMenuInput, UpdateMenuInput, AssignLocationInput, UnassignLocationInput, DeleteMenuInput, NavigationEventName, NavMenuChangedPayload, NavLocationChangedPayload, NavigationHookName, NavigationAiTool, NavWhereUsedResult, } from "./contracts.js";
@@ -26,6 +26,8 @@ export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, menuVersionConflictEr
  * `check:boundaries` blocks either host-side call site from doing so.
  */
 export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, isAllowedHref, ALLOWED_HREF_SHAPES_DESCRIPTION, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuVersionConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, type TreeValidationLimits, type CreateMenuDeps, type CreateMenuServiceInput, type CreateMenuRequired, type CreateMenuOptional, type UpdateMenuTreeDeps, type UpdateMenuTreeServiceInput, type UpdateMenuTreeRequired, type UpdateMenuTreeOptional, type AssignLocationDeps, type AssignLocationServiceInput, type AssignLocationRequired, type AssignLocationOptional, type DeleteMenuDeps, type DeleteMenuServiceInput, type DeleteMenuRequired, type DeleteMenuOptional, } from "./menu-service.js";
+/** HTML mode (2026-10-08): validation/normalization for a menu's author-written markup. */
+export { MAX_MENU_HTML_LENGTH, isMenuHtmlAuthoring, menuHtmlInputProblem, mergeMenuHtml, type MenuHtmlAuthoring, } from "./menu-html.js";
 export { resolveForLocation, resolveMenuDoc, type ResolveTargetHrefFn, type ResolvedTargetHref, type ResolveForLocationDeps, type ResolveForLocationServiceInput, type ResolveForLocationRequired, type ResolveForLocationOptional, } from "./resolver.js";
 export { rebuildNavLocationBindings, type RebuildNavLocationBindingsDeps, type RebuildNavLocationBindingsResult, } from "./reconcile.js";
 /** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */

package/dist/navigation/index.js

@@ -17,6 +17,8 @@ export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, menuVersionConflictEr
  * `check:boundaries` blocks either host-side call site from doing so.
  */
 export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, isAllowedHref, ALLOWED_HREF_SHAPES_DESCRIPTION, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuVersionConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, } from "./menu-service.js";
+/** HTML mode (2026-10-08): validation/normalization for a menu's author-written markup. */
+export { MAX_MENU_HTML_LENGTH, isMenuHtmlAuthoring, menuHtmlInputProblem, mergeMenuHtml, } from "./menu-html.js";
 export { resolveForLocation, resolveMenuDoc, } from "./resolver.js";
 export { rebuildNavLocationBindings, } from "./reconcile.js";
 /** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */

package/dist/navigation/menu-html.d.ts

@@ -0,0 +1,31 @@
+import type { NavMenuDoc, NavMenuMode } from "./types.js";
+/** Same ceiling HTML-mode forms use. */
+export declare const MAX_MENU_HTML_LENGTH = 200000;
+/** The optional HTML-mode fields a create/update write may carry. */
+export interface MenuHtmlAuthoring {
+    mode?: NavMenuMode | undefined;
+    html?: string | undefined;
+}
+/**
+ * Whether a write authors raw HTML, and so needs the host's raw-HTML permission. Switching back to
+ * items without sending markup does not author anything (forms apply the same rule to "builder").
+ * @complexity O(1).
+ */
+export declare function isMenuHtmlAuthoring({ mode, html }: MenuHtmlAuthoring, _optional?: Record<string, never>): boolean;
+/**
+ * Why a write's `mode`/`html` is invalid, or `null` when it is fine. A message rather than a throw so
+ * `menu-service.ts` raises its own `MenuValidationError` without this file importing it back.
+ * @complexity O(1).
+ */
+export declare function menuHtmlInputProblem({ mode, html }: MenuHtmlAuthoring, _optional?: Record<string, never>): string | null;
+/**
+ * The doc's `mode`/`html` after a valid write: submitted values win, omitted ones keep what is
+ * stored, and a menu that never used HTML mode gets neither key, so its stored doc (and publish
+ * hash) is unchanged. Call {@link menuHtmlInputProblem} first.
+ * @complexity O(h) in the submitted html length (one parse + serialize).
+ */
+export declare function mergeMenuHtml({ input, existing }: {
+    input: MenuHtmlAuthoring;
+    existing?: Pick<NavMenuDoc, "mode" | "html"> | undefined;
+}, _optional?: Record<string, never>): Pick<NavMenuDoc, "mode" | "html">;
+//# sourceMappingURL=menu-html.d.ts.map

package/dist/navigation/menu-html.js

@@ -0,0 +1,53 @@
+/**
+ * @file HTML mode for a menu (2026-10-08): the author writes the menu's markup by hand instead of
+ * building an item tree, so it can be styled however they want.
+ *
+ * Same trust model as HTML-mode forms (`forms/html/html-authoring.ts`) and HTML Pages: the markup is
+ * admin/owner-trusted and NOT sanitized. Hosts gate it behind their raw-HTML permission (Tovu binds
+ * `pages.edit_html`, the one forms use); this module only validates and normalizes. parse5 balances
+ * the fragment so a stray `</nav>` or an unclosed `<div>` cannot close or swallow the theme element
+ * the menu renders inside.
+ *
+ * Both modes' data live side by side in the doc: switching mode never deletes the other one, so an
+ * author can flip back and find their items (or their HTML) still there.
+ */
+import { parseFragment, serialize } from "parse5";
+/** Same ceiling HTML-mode forms use. */
+export const MAX_MENU_HTML_LENGTH = 200_000;
+/**
+ * Whether a write authors raw HTML, and so needs the host's raw-HTML permission. Switching back to
+ * items without sending markup does not author anything (forms apply the same rule to "builder").
+ * @complexity O(1).
+ */
+export function isMenuHtmlAuthoring({ mode, html }, _optional = {}) {
+    return html !== undefined || mode === "html";
+}
+/** Balance the fragment; scripts and authored styling stay as written (trusted markup). */
+function normalizeMenuHtml(html) {
+    return serialize(parseFragment(html));
+}
+/**
+ * Why a write's `mode`/`html` is invalid, or `null` when it is fine. A message rather than a throw so
+ * `menu-service.ts` raises its own `MenuValidationError` without this file importing it back.
+ * @complexity O(1).
+ */
+export function menuHtmlInputProblem({ mode, html }, _optional = {}) {
+    if (mode !== undefined && mode !== "items" && mode !== "html")
+        return "mode must be 'items' or 'html'";
+    if (html !== undefined && (typeof html !== "string" || html.length > MAX_MENU_HTML_LENGTH)) {
+        return `html must be a string of at most ${MAX_MENU_HTML_LENGTH} characters`;
+    }
+    return null;
+}
+/**
+ * The doc's `mode`/`html` after a valid write: submitted values win, omitted ones keep what is
+ * stored, and a menu that never used HTML mode gets neither key, so its stored doc (and publish
+ * hash) is unchanged. Call {@link menuHtmlInputProblem} first.
+ * @complexity O(h) in the submitted html length (one parse + serialize).
+ */
+export function mergeMenuHtml({ input, existing }, _optional = {}) {
+    const mode = input.mode ?? existing?.mode;
+    const html = input.html !== undefined ? normalizeMenuHtml(input.html) : existing?.html;
+    return { ...(mode !== undefined ? { mode } : {}), ...(html !== undefined ? { html } : {}) };
+}
+//# sourceMappingURL=menu-html.js.map

package/dist/navigation/menu-service.d.ts

@@ -2,7 +2,7 @@ import type { Clock, IdGenerator, UUID } from "@jini-ai/core/primitives";
 import type { OutboxPort } from "../core/ports.js";
 import type { MenuRepoPort } from "./repo.memory.js";
 import type { NavLocationBindingRepoPort } from "./ports.js";
-import { type NavItemNode, type NavLocationBindingRow, type NavLocationKey, type NavMenuEntry } from "./types.js";
+import { type NavItemNode, type NavLocationBindingRow, type NavLocationKey, type NavMenuEntry, type NavMenuMode } from "./types.js";
 export declare class MenuNotFoundError extends Error {
     constructor({ message }: {
         message: string;
@@ -147,6 +147,9 @@ export interface CreateMenuServiceInput {
     slug: string;
     /** Optional initial tree; defaults to an empty menu. Items must carry ids. */
     items?: readonly NavItemNode[] | undefined;
+    /** HTML mode (`menu-html.ts`). The host gates raw HTML behind its own permission first. */
+    mode?: NavMenuMode | undefined;
+    html?: string | undefined;
 }
 export interface CreateMenuRequired {
     deps: CreateMenuDeps;
@@ -188,8 +191,11 @@ export interface UpdateMenuTreeServiceInput {
     expectedVersion: number;
     title?: string | undefined;
     slug?: string | undefined;
-    /** The full replacement tree (whole-tree edit). */
-    items: readonly NavItemNode[];
+    /** The full replacement tree (whole-tree edit). Omitted keeps the stored tree (an HTML-only edit). */
+    items?: readonly NavItemNode[] | undefined;
+    /** HTML mode (`menu-html.ts`); omitted keeps the stored value. The host gates raw HTML first. */
+    mode?: NavMenuMode | undefined;
+    html?: string | undefined;
 }
 export interface UpdateMenuTreeRequired {
     deps: UpdateMenuTreeDeps;

package/dist/navigation/menu-service.js

@@ -24,6 +24,7 @@ import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
  * through the injected repo ports (`deps`).
  */
 import { assertEntityLive } from "../core/entity-liveness.js";
+import { menuHtmlInputProblem, mergeMenuHtml } from "./menu-html.js";
 import { NAV_DOC_TYPE, } from "./types.js";
 // ---------------------------------------------------------------------------
 // Outbox event publication — each mutating function below
@@ -281,6 +282,13 @@ function assertValidTitleAndSlug(title, slug) {
         throw new MenuValidationError({ message: "slug must use lowercase letters, numbers, and dashes" });
     }
 }
+/** Validated, merged HTML-mode doc fields — `menu-html.ts`'s problem check raised as this file's own error. */
+function menuHtmlFields({ input, existing }) {
+    const problem = menuHtmlInputProblem(input);
+    if (problem)
+        throw new MenuValidationError({ message: problem });
+    return mergeMenuHtml({ input, existing });
+}
 /**
  * Creates a new `menu` entry in `published` status with no location
  * assignments. Rejects a duplicate slug within the workspace.
@@ -305,13 +313,14 @@ export async function createMenu(required, optional = {}) {
     if (duplicate)
         throw new MenuConflictError({ message: `slug '${slug}' already exists` });
     const items = validateAndCloneTree({ items: input.items ?? [] }, optional.limits);
+    const htmlFields = menuHtmlFields({ input });
     const menu = {
         id: deps.idGen.newId(),
         workspaceId: input.workspaceId,
         slug,
         title,
         status: "published",
-        doc: { type: NAV_DOC_TYPE, version: 1, items },
+        doc: { type: NAV_DOC_TYPE, version: 1, items, ...htmlFields },
         locations: [],
         updatedAt: kernelNowIso({ clock: deps.clock }),
         version: 1,
@@ -407,15 +416,18 @@ export async function updateMenuTree(required, optional = {}) {
             throw new MenuConflictError({ message: `slug '${slug}' already exists` });
         }
     }
-    const items = carryForwardEntryHints({
+    const items = input.items === undefined ? existing.doc.items : carryForwardEntryHints({
         previous: existing.doc.items,
         next: validateAndCloneTree({ items: input.items }, optional.limits),
     });
+    // Every writer (admin, agent tool, publish repoint, reverters) comes through here, so the stored
+    // HTML-mode fields are carried forward unless this write sets them — an items-only save never drops them.
+    const htmlFields = menuHtmlFields({ input, existing: existing.doc });
     const menu = {
         ...existing,
         title,
         slug,
-        doc: { type: NAV_DOC_TYPE, version: existing.doc.version, items },
+        doc: { type: NAV_DOC_TYPE, version: existing.doc.version, items, ...htmlFields },
         updatedAt: kernelNowIso({ clock: deps.clock }),
         version: existing.version + 1,
     };

package/dist/navigation/tool-registrations.d.ts

@@ -19,6 +19,11 @@ export interface MenusToolDeps {
     outbox: OutboxPort;
     menuRepo: MenuRepoPort;
     navLocationBindingRepo: NavLocationBindingRepoPort;
+    /**
+     * The host's raw-HTML permission (Tovu: `pages.edit_html`, the one HTML-mode forms use). A write
+     * carrying menu HTML is checked against it on top of the menu permission; unset, HTML menus are refused.
+     */
+    rawHtmlPermission?: string | undefined;
 }
 /**
  * This wiring layer's OWN risk classification, authored from what each handler below actually

package/dist/navigation/tool-registrations.js

@@ -15,6 +15,7 @@ import { buildDomainRegistrations, indexCatalogById, requireInputRecord, require
 import { requireToolPermission } from "../core/tools/index.js";
 import { menusAgentToolCatalog } from "./agent-tools.js";
 import { assignLocation, createMenu, MenuNotFoundError, MenuValidationError, updateMenuTree } from "./menu-service.js";
+import { isMenuHtmlAuthoring } from "./menu-html.js";
 const CATALOG_BY_ID = indexCatalogById({ catalog: menusAgentToolCatalog });
 /**
  * This wiring layer's OWN risk classification, authored from what each handler below actually
@@ -54,10 +55,30 @@ function toMenuToolView(menu) {
         title: menu.title,
         status: menu.status,
         items: JSON.parse(JSON.stringify(menu.doc.items)),
+        ...(menu.doc.mode !== undefined ? { mode: menu.doc.mode } : {}),
+        ...(menu.doc.html !== undefined ? { html: menu.doc.html } : {}),
         locations: [...menu.locations],
         version: menu.version,
     };
 }
+/** A write's HTML-mode fields as sent; `menu-service.ts` validates their values. */
+function htmlAuthoring(input) {
+    return {
+        ...(input.mode !== undefined ? { mode: input.mode } : {}),
+        ...(input.html !== undefined ? { html: input.html } : {}),
+    };
+}
+/**
+ * Raw HTML is the host's trust boundary (HTML Pages, HTML-mode forms), so a write that authors menu
+ * HTML also needs that permission. Checked before the write, like forms' `prepareFormAuthoring`.
+ */
+async function requireHtmlAuthoringPermission({ routeDeps, principalId, authoring, menuId }) {
+    if (!isMenuHtmlAuthoring(authoring))
+        return;
+    if (!routeDeps.rawHtmlPermission)
+        throw new ToolInputError({ message: "HTML menus are not enabled on this site" });
+    await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId, permission: routeDeps.rawHtmlPermission }, { entityType: "menu", ...(menuId ? { entityId: menuId } : {}) });
+}
 function menusDeps(routeDeps) {
     return { repo: routeDeps.menuRepo, clock: routeDeps.clock, idGen: routeDeps.idGen, outbox: routeDeps.outbox };
 }
@@ -82,6 +103,8 @@ export function buildMenusRegistrations(routeDeps) {
             if (input.items !== undefined && !Array.isArray(input.items)) {
                 throw new ToolInputError({ message: "'items' must be an array of nav items" });
             }
+            const authoring = htmlAuthoring(input);
+            await requireHtmlAuthoringPermission({ routeDeps, principalId: ctx.principal.id, authoring });
             return withSchemaOnRejection({ toolId: "menus_create_menu", catalog: CATALOG_BY_ID, isShapeRejection: ({ error }) => isMenusShapeRejection(error), fn: async () => {
                     const { menu } = await createMenu({
                         deps: menusDeps(routeDeps),
@@ -90,6 +113,7 @@ export function buildMenusRegistrations(routeDeps) {
                             title: requireString({ input: input, key: "title" }),
                             slug: requireString({ input: input, key: "slug" }),
                             items: Array.isArray(input.items) ? input.items : undefined,
+                            ...authoring,
                         },
                     });
                     return { menu: toMenuToolView(menu) };
@@ -99,8 +123,13 @@ export function buildMenusRegistrations(routeDeps) {
             const input = requireInputRecord({ input: ctx.input });
             const menuId = requireString({ input: input, key: "menuId" });
             await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "admin.menus.update" }, { entityType: "menu", entityId: menuId });
-            if (!Array.isArray(input.items))
-                throw new Error("'items' (array) is required");
+            const authoring = htmlAuthoring(input);
+            if (input.items === undefined && authoring.mode === undefined && authoring.html === undefined) {
+                throw new Error("'items' (array), 'html' or 'mode' is required");
+            }
+            if (input.items !== undefined && !Array.isArray(input.items))
+                throw new Error("'items' must be an array of nav items");
+            await requireHtmlAuthoringPermission({ routeDeps, principalId: ctx.principal.id, authoring, menuId });
             return withSchemaOnRejection({ toolId: "menus_update_menu_tree", catalog: CATALOG_BY_ID, isShapeRejection: ({ error }) => isMenusShapeRejection(error), fn: async () => {
                     const { menu } = await updateMenuTree({
                         deps: menusDeps(routeDeps),
@@ -111,6 +140,7 @@ export function buildMenusRegistrations(routeDeps) {
                             title: typeof input.title === "string" ? input.title : undefined,
                             slug: typeof input.slug === "string" ? input.slug : undefined,
                             items: input.items,
+                            ...authoring,
                         },
                     });
                     return { menu: toMenuToolView(menu) };

package/dist/navigation/types.d.ts

@@ -123,7 +123,13 @@ export interface NavMenuDoc {
     /** Doc-schema version, so the validator can migrate shapes later. */
     readonly version: number;
     readonly items: readonly NavItemNode[];
+    /** What renders at the menu's marker; absent means `"items"`. See `menu-html.ts`. */
+    readonly mode?: NavMenuMode | undefined;
+    /** Author-written HTML for `"html"` mode, kept even while the menu renders its items. */
+    readonly html?: string | undefined;
 }
+/** `"items"` renders the item tree; `"html"` renders the author's own markup (`menu-html.ts`). */
+export type NavMenuMode = "items" | "html";
 export type MenuStatus = "draft" | "published" | "trash";
 /**
  * A typed read model over a `type='menu'` entries row (universal

package/dist/widgets/resolvers/menu.d.ts

@@ -38,5 +38,13 @@ export interface MenuResolverDeps {
     /** Host routing injection; callers without it retain the diagnostic placeholder documented above. */
     resolveTargetHref?: ResolveTargetHrefFn;
 }
+/**
+ * Resolve menu widgets through navigation's read model: stored HTML or resolved items by doc mode.
+ * HTML is trusted and balanced by navigation's save path (`mergeMenuHtml`), like static menus;
+ * forwarding it adds no second parser or sanitization policy. Read failures propagate to dispatch.
+ * @param deps - Navigation read/resolution ports and host routing/public-filter policy.
+ * @returns A resolver producing mode-specific menu IR, or existing typed config/target failures.
+ * @complexity One read per instance; item resolution/filtering scales with the selected item trees.
+ */
 export declare function createMenuResolver(deps: MenuResolverDeps, _optional?: Record<string, never>): WidgetResolver;
 //# sourceMappingURL=menu.d.ts.map

package/dist/widgets/resolvers/menu.js

@@ -9,6 +9,14 @@ function toMenuItemProps(items, publicOnly) {
     }) : items;
     return visible;
 }
+/**
+ * Resolve menu widgets through navigation's read model: stored HTML or resolved items by doc mode.
+ * HTML is trusted and balanced by navigation's save path (`mergeMenuHtml`), like static menus;
+ * forwarding it adds no second parser or sanitization policy. Read failures propagate to dispatch.
+ * @param deps - Navigation read/resolution ports and host routing/public-filter policy.
+ * @returns A resolver producing mode-specific menu IR, or existing typed config/target failures.
+ * @complexity One read per instance; item resolution/filtering scales with the selected item trees.
+ */
 export function createMenuResolver(deps, _optional = {}) {
     const resolveTargetHref = deps.resolveTargetHref ?? DEFAULT_RESOLVE_TARGET_HREF;
     return {
@@ -25,14 +33,21 @@ export function createMenuResolver(deps, _optional = {}) {
                     results.set(instance.id, { ok: false, reason: "target-disabled" });
                     continue;
                 }
-                const items = await deps.menus.resolveMenuDoc({
-                    doc: menu.doc,
-                    context: { workspaceId: context.workspaceId },
-                    resolveTargetHref,
-                });
+                let props;
+                if (menu.doc.mode === "html") {
+                    props = { title: menu.title, mode: "html", html: menu.doc.html ?? "" };
+                }
+                else {
+                    const items = await deps.menus.resolveMenuDoc({
+                        doc: menu.doc,
+                        context: { workspaceId: context.workspaceId },
+                        resolveTargetHref,
+                    });
+                    props = { title: menu.title, items: toMenuItemProps(items, deps.publicOnly === true) };
+                }
                 results.set(instance.id, {
                     ok: true,
-                    ir: { componentId: "menu", props: { title: menu.title, items: toMenuItemProps(items, deps.publicOnly === true) } },
+                    ir: { componentId: "menu", props },
                     dependencyKeys: [menu.id],
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/cms",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Content-model capability for Jini-hosted products: framework-free contracts, ports, and domain services in `/core` and per-domain subpaths; Node-bound adapters in domain-specific subpaths.",
   "license": "Apache-2.0",
   "repository": {
@@ -319,9 +319,9 @@
     "@types/better-sqlite3": "^7.6.13",
     "@electric-sql/pglite": "0.5.8",
     "jsdom": "^25.0.1",
-    "@jini-ai/core": "0.4.2",
     "@jini-ai/http-kit": "0.4.1",
-    "@jini-ai/db": "0.3.1"
+    "@jini-ai/db": "0.3.1",
+    "@jini-ai/core": "0.4.2"
   },
   "dependencies": {
     "@jini-ai/core": "^0.4.2"

package/dist/http/settings/cms-adapter.d.ts

@@ -1,20 +0,0 @@
-import { type SettingsWriteServiceDeps, type SettingsRepoPort } from "../../settings/index.js";
-import type { SettingsService, SettingsPermissions, SettingsChangeFeed } from "./contracts.js";
-/** Keep the CMS write chokepoint while translating its permission vocabulary to host policy. */
-/** Bind the CMS ledger and write chokepoint without copying their domain logic.
- * Effective reads scan definitions and resolve each namespace key; mutations inherit CMS transactions/errors.
- * @complexity O(1) setup. Per operation: O(definitions + keys) reads, or O(batch size) writes.
- * @example createCmsSettingsService({ deps: cmsPorts, permissions });
- */
-export declare function createCmsSettingsService(required: {
-    deps: SettingsWriteServiceDeps;
-    permissions: SettingsPermissions;
-}): SettingsService;
-/** Adapt the ledger through CMS tenant/principal disclosure rules, returning names and cursors only.
- * @complexity O(1) setup; collect is O(page size), with namespace lookup per visible revision.
- * @example createCmsSettingsChangeFeed({ repo });
- */
-export declare function createCmsSettingsChangeFeed(required: {
-    repo: SettingsRepoPort;
-}): SettingsChangeFeed;
-//# sourceMappingURL=cms-adapter.d.ts.map

package/dist/http/settings/cms-adapter.js

@@ -1,124 +0,0 @@
-import { getEffective, resolveDefinition, set, clear, resetNamespace, registerDefinitions, NON_REGISTER_DEFINITION_OPS, parseNonRegisterDefinitionOp, collectChangedNamespaces, } from "../../settings/index.js";
-/** Keep the CMS write chokepoint while translating its permission vocabulary to host policy. */
-/** Bind the CMS ledger and write chokepoint without copying their domain logic.
- * Effective reads scan definitions and resolve each namespace key; mutations inherit CMS transactions/errors.
- * @complexity O(1) setup. Per operation: O(definitions + keys) reads, or O(batch size) writes.
- * @example createCmsSettingsService({ deps: cmsPorts, permissions });
- */
-export function createCmsSettingsService(required) {
-    const { deps: original, permissions } = required;
-    const permissionMap = new Map([
-        ["settings.definitions.manage", permissions.manageDefinitions],
-        ["settings.global.write", permissions.writeGlobal],
-        ["settings.workspace.write", permissions.writeWorkspace],
-        ["settings.user.self.write", permissions.writeUserSelf],
-        ["settings.user.write", permissions.writeUserOther],
-        ["settings.reset.global", permissions.reset.global],
-        ["settings.reset.workspace", permissions.reset.workspace],
-        ["settings.reset.user", permissions.reset.user],
-    ]);
-    const deps = { ...original,
-        authorize: (input) => {
-            const permission = permissionMap.get(input.permission);
-            if (permission === undefined)
-                return Promise.resolve({ allowed: false, reason: "unknown_settings_permission" });
-            return original.authorize({ ...input, permission });
-        },
-    };
-    const repo = deps.repo;
-    const listDefinitions = async ({ workspaceId }) => {
-        const [platform, workspace] = await Promise.all([
-            repo.listActiveDefinitions({ workspaceId: null }), repo.listActiveDefinitions({ workspaceId }),
-        ]);
-        return [...platform, ...workspace];
-    };
-    return {
-        listDefinitions,
-        effective: async ({ namespace, workspaceId, principalId }) => {
-            const defs = await listDefinitions({ workspaceId });
-            const keys = new Set(defs.filter((d) => d.namespace === namespace).map((d) => d.key));
-            const data = [];
-            for (const key of keys) {
-                const result = await getEffective({ repo }, { namespace, key, scopeContext: { workspaceId, principalId } });
-                if (result)
-                    data.push({ key, value: result.value, sourceLayer: result.sourceLayer, defVersion: result.defVersion });
-            }
-            return data;
-        },
-        raw: async ({ namespace, key, workspaceId, principalId }) => {
-            const definition = await resolveDefinition({ repo }, { namespace, key, workspaceId });
-            if (!definition)
-                return null;
-            const settingId = definition.settingId;
-            const records = await Promise.all([
-                repo.getGlobalValue(settingId), repo.getWorkspaceValue({ workspaceId, settingId }),
-                principalId ? repo.getUserValue({ workspaceId, principalId, settingId }) : Promise.resolve(null),
-            ]);
-            const values = records.map((r) => r?.state === "set" ? r.valueJson : null);
-            return { key: `${namespace}.${key}`, global: values[0], workspace: values[1], user: values[2], default: definition.defaultValue };
-        },
-        set: (input) => set({ deps, input }),
-        clear: (input) => clear({ deps, input }),
-        reset: async (input) => {
-            const definitions = await repo.listActiveDefinitions({ workspaceId: input.scope === "global" ? null : (input.workspaceId ?? input.authWorkspaceId ?? null) });
-            const keys = definitions.filter((d) => d.namespace === input.namespace).map((d) => d.key);
-            return resetNamespace({ deps, input }, keys);
-        },
-        definitions: ({ items, callerPrincipalId, authWorkspaceId }) => applyDefinitions({ deps, items, callerPrincipalId, authWorkspaceId }),
-    };
-}
-/** Preserve register batching and ordered non-register writes over existing CMS operation contracts.
- * Unknown operations return their name. Earlier non-register writes are not rolled back by later failures.
- * @complexity O(item count) time/space plus CMS effects; this batch is not atomic.
- */
-async function applyDefinitions(required) {
-    const { deps, items, callerPrincipalId, authWorkspaceId } = required;
-    const toRegister = [];
-    const applied = [];
-    for (const raw of items) {
-        const item = raw;
-        const op = String(item.op ?? "register");
-        const namespace = String(item.namespace ?? "");
-        const key = String(item.key ?? "");
-        const ownerKind = item.ownerKind;
-        const workspaceId = ownerKind === "site" ? authWorkspaceId : null;
-        const defaultValue = (item.defaultJson ?? null);
-        if (op === "register") {
-            toRegister.push({ namespace, key, ownerKind, workspaceId, schema: item.schemaJson,
-                defaultValue, scopes: Number(item.scopes), secret: Boolean(item.secret ?? false) });
-        }
-        else {
-            const parsedOp = parseNonRegisterDefinitionOp({ op });
-            if (!parsedOp)
-                return { unknownOp: op };
-            const opItem = { namespace, key, ownerKind, workspaceId, defaultJson: defaultValue,
-                ...(item.newNamespace === undefined ? {} : { newNamespace: item.newNamespace }),
-                ...(item.newKey === undefined ? {} : { newKey: item.newKey }),
-                ...(item.schemaJson === undefined ? {} : { schemaJson: item.schemaJson }),
-                ...(item.coercionJson === undefined ? {} : { coercionJson: item.coercionJson }),
-            };
-            await NON_REGISTER_DEFINITION_OPS[parsedOp]({ ctx: { deps, callerPrincipalId, authWorkspaceId }, item: opItem });
-        }
-        applied.push({ key: `${namespace}.${key}`, op, status: "applied" });
-    }
-    if (toRegister.length)
-        await registerDefinitions({ deps, input: { definitions: toRegister, callerPrincipalId, authWorkspaceId } });
-    return { applied };
-}
-/** Adapt the ledger through CMS tenant/principal disclosure rules, returning names and cursors only.
- * @complexity O(1) setup; collect is O(page size), with namespace lookup per visible revision.
- * @example createCmsSettingsChangeFeed({ repo });
- */
-export function createCmsSettingsChangeFeed(required) {
-    const { repo } = required;
-    return {
-        head: () => repo.maxRevisionSeq(),
-        collect: async ({ sinceSeq, limit, viewer }) => {
-            const revisions = await repo.listRevisionsSince({ sinceSeq, limit, workspaceId: viewer.workspaceId });
-            // Resolve afresh each batch: a rename must never leave a stale namespace cached forever.
-            const batch = await collectChangedNamespaces({ revisions, viewer, resolveNamespace: async ({ settingId }) => (await repo.findDefinitionBySettingId({ settingId }))?.namespace ?? null });
-            return { ...batch, examinedCount: revisions.length };
-        },
-    };
-}
-//# sourceMappingURL=cms-adapter.js.map