@jini-ai/cms 0.5.4 → 0.5.6

package/dist/media/image-transformer.sharp.js

@@ -151,7 +151,10 @@ export class SharpImageTransformer {
                     fit: input.params.fit ?? "cover",
                 });
             }
-            pipeline = pipeline.toFormat(input.params.format);
+            // JPEG cannot carry alpha; explicit white avoids libvips' black background for logos.
+            if (input.params.format === "jpeg")
+                pipeline = pipeline.flatten({ background: "#ffffff" });
+            pipeline = pipeline.toFormat(input.params.format, input.params.quality === undefined ? undefined : { quality: input.params.quality });
             const outBuffer = await pipeline.toBuffer();
             return {
                 bytes: new Uint8Array(outBuffer),

package/dist/media/media-service.d.ts

@@ -27,6 +27,10 @@ export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
  * `routes/site/media-rendition.ts`). This widens the SAME advisory,
  * client-declared-string check item 4 above already discloses as untrusted —
  * no new ingress hardening was added for video.
+ *
+ * Audio (owner-approved mediawidget, 2026-10-10/11) follows that same original-byte
+ * lifecycle. Only formats recognized by the shared sniffer are allowed; no image
+ * transform is requested for them.
  */
 export declare const DEFAULT_ALLOWED_MIME_TYPES: ReadonlySet<string>;
 /**

package/dist/media/media-service.js

@@ -100,6 +100,10 @@ function formatMaxUploadBytesAsMb(bytes) {
  * `routes/site/media-rendition.ts`). This widens the SAME advisory,
  * client-declared-string check item 4 above already discloses as untrusted —
  * no new ingress hardening was added for video.
+ *
+ * Audio (owner-approved mediawidget, 2026-10-10/11) follows that same original-byte
+ * lifecycle. Only formats recognized by the shared sniffer are allowed; no image
+ * transform is requested for them.
  */
 export const DEFAULT_ALLOWED_MIME_TYPES = new Set([
     "image/jpeg",
@@ -109,6 +113,10 @@ export const DEFAULT_ALLOWED_MIME_TYPES = new Set([
     "image/avif",
     "video/mp4",
     "video/webm",
+    "audio/wav",
+    "audio/mpeg",
+    "audio/flac",
+    "audio/mp4",
 ]);
 /**
  * Enforces the "settable-once-from-absent" write-once rule for

package/dist/media/node.d.ts

@@ -1,5 +1,5 @@
 /** Node-bound media adapters; hosts supply the filesystem and optional codecs. */
 export { LocalFsBlobStore, type LocalFsBlobStoreDeps } from "./blob-store.fs.js";
 export { SharpImageTransformer, ImageTransformUnavailableError, ImageSourceCorruptError } from "./image-transformer.sharp.js";
-export { createFfmpegVideoFrameExtractor, findVideoBinaries, runLowPriorityVideoProcess, type VideoBinaries, type VideoBinaryFinder, type VideoProcessRunner, } from './video-frames.ffmpeg.js';
+export { createFfmpegVideoFrameExtractor, createVideoExtractionLock, findVideoBinaries, runLowPriorityVideoProcess, type VideoExtractionLock, type VideoBinaries, type VideoBinaryFinder, type VideoProcessRunner, } from './video-frames.ffmpeg.js';
 //# sourceMappingURL=node.d.ts.map

package/dist/media/node.js

@@ -2,5 +2,5 @@
 export { LocalFsBlobStore } from "./blob-store.fs.js";
 export { SharpImageTransformer, ImageTransformUnavailableError, ImageSourceCorruptError } from "./image-transformer.sharp.js";
 // Video previews: policy/port plus a bounded optional-host codec adapter.
-export { createFfmpegVideoFrameExtractor, findVideoBinaries, runLowPriorityVideoProcess, } from './video-frames.ffmpeg.js';
+export { createFfmpegVideoFrameExtractor, createVideoExtractionLock, findVideoBinaries, runLowPriorityVideoProcess, } from './video-frames.ffmpeg.js';
 //# sourceMappingURL=node.js.map

package/dist/media/transform-registry.js

@@ -26,7 +26,7 @@ export async function registerTransform(required, _optional = {}) {
     const owner = input.owner.trim();
     if (!owner)
         throw new TransformValidationError({ message: "owner is required" });
-    assertValidTransformParams({ format: input.params.format }, { width: input.params.width, height: input.params.height, fit: input.params.fit });
+    assertValidTransformParams({ format: input.params.format }, { width: input.params.width, height: input.params.height, fit: input.params.fit, quality: input.params.quality });
     return withTransformRegistryLock({ key: `${input.workspaceId}:${name}`, criticalSection: async () => {
             const existingVersions = await deps.transformRepo.listByName({ workspaceId: input.workspaceId, name });
             const currentMaxVersion = existingVersions.reduce((max, row) => Math.max(max, row.version), 0);

package/dist/media/transform-types.d.ts

@@ -41,6 +41,8 @@ export interface TransformParams {
     height?: number | undefined;
     fit?: TransformFit | undefined;
     format: TransformFormat;
+    /** Encoder quality, 1–100; omitted preserves the codec default. */
+    quality?: number | undefined;
 }
 /**
  * `transform_registry` sidecar row. Identity is

package/dist/media/transform-types.js

@@ -45,6 +45,9 @@ export function assertValidTransformParams(required, optional = {}) {
             throw new TransformValidationError({ message: `transform params.${key} must be an integer between 1 and ${MAX_TRANSFORM_DIMENSION_PX}` });
         }
     }
+    if (params.quality !== undefined && (!Number.isInteger(params.quality) || params.quality < 1 || params.quality > 100)) {
+        throw new TransformValidationError({ message: "transform params.quality must be an integer between 1 and 100" });
+    }
     if (params.fit !== undefined && !(params.width && params.height)) {
         throw new TransformValidationError({ message: "transform params.fit requires both width and height" });
     }

package/dist/media/video-frames.ffmpeg.d.ts

@@ -5,7 +5,10 @@ export interface VideoBinaries {
     readonly ffmpeg: string;
     readonly ffprobe: string;
 }
-export type VideoBinaryFinder = (required: Record<string, never>, optional: Record<string, never>) => Promise<VideoBinaries | undefined>;
+export type VideoBinaryFinder = (required: Record<string, never>, optional: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+}) => Promise<VideoBinaries | undefined>;
 export type VideoProcessRunner = (required: {
     command: string;
     args: readonly string[];
@@ -31,7 +34,17 @@ export declare const runLowPriorityVideoProcess: ({ command, args, spawnProcess,
     maxOutputBytes: number;
     signal?: AbortSignal;
 }) => Promise<Uint8Array>;
-export declare function createFfmpegVideoFrameExtractor({ findBinaries, runProcess, nowMs }: {
+export interface VideoExtractionLock {
+    /** Synchronous acquisition prevents races before the first awaited probe. */
+    tryAcquire(required: Record<string, never>, optional: Record<string, never>): (() => void) | undefined;
+}
+/** A host may share this lock across its adapters to enforce a decoder budget.
+ * Returns a synchronous try-acquire port; release follows decoder cleanup. @complexity O(1). */
+export declare function createVideoExtractionLock(_required: Record<string, never>, _optional?: Record<string, never>): VideoExtractionLock;
+export declare function createFfmpegVideoFrameExtractor({ findBinaries, runProcess, nowMs, lock, env, platform }: {
+    lock?: VideoExtractionLock;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
     findBinaries?: VideoBinaryFinder;
     runProcess?: VideoProcessRunner;
     nowMs?: (required: Record<string, never>, optional: Record<string, never>) => number;

package/dist/media/video-frames.ffmpeg.js

@@ -13,9 +13,9 @@ class VideoProcessError extends Error {
         this.reason = reason;
     }
 }
-async function executable(required, { configured } = {}) {
+async function executable(required, { configured, env = process.env } = {}) {
     const candidates = configured ? [configured] : [
-        ...(process.env['PATH'] ?? '').split(delimiter).filter(isAbsolute).map(directory => join(directory, required.name)),
+        ...(env['PATH'] ?? '').split(delimiter).filter(isAbsolute).map(directory => join(directory, required.name)),
         join('/opt/homebrew/bin', required.name), join('/usr/local/bin', required.name), join('/usr/bin', required.name),
     ];
     for (const candidate of candidates) {
@@ -32,12 +32,12 @@ async function executable(required, { configured } = {}) {
 }
 /** Discovery never executes a version/probe command. Configured paths are host configuration,
  * never tool arguments, and all subprocesses (including ffprobe) still go through nice. */
-export const findVideoBinaries = async (_required, _optional) => {
-    if (process.platform === 'win32')
+export const findVideoBinaries = async (_required, { env = process.env, platform = process.platform } = {}) => {
+    if (platform === 'win32')
         return undefined; // Never silently omit the low-priority guarantee.
-    const nice = await executable({ name: 'nice' }, {});
-    const ffmpeg = await executable({ name: 'ffmpeg' }, { configured: process.env['FFMPEG_PATH'] });
-    const ffprobe = await executable({ name: 'ffprobe' }, { configured: process.env['FFPROBE_PATH'] });
+    const nice = await executable({ name: 'nice' }, { env });
+    const ffmpeg = await executable({ name: 'ffmpeg' }, { configured: env['FFMPEG_PATH'], env });
+    const ffprobe = await executable({ name: 'ffprobe' }, { configured: env['FFPROBE_PATH'], env });
     return nice && ffmpeg && ffprobe ? { nice, ffmpeg, ffprobe } : undefined;
 };
 /** detached creates a group including nice and its eventual executable; killing the group prevents
@@ -99,25 +99,40 @@ export const runLowPriorityVideoProcess = async ({ command, args, spawnProcess =
             abort();
     });
 };
+/** A host may share this lock across its adapters to enforce a decoder budget.
+ * Returns a synchronous try-acquire port; release follows decoder cleanup. @complexity O(1). */
+export function createVideoExtractionLock(_required, _optional = {}) {
+    let extracting = false;
+    return { tryAcquire() {
+            if (extracting)
+                return undefined;
+            extracting = true;
+            let released = false;
+            return () => { if (!released) {
+                released = true;
+                extracting = false;
+            } };
+        } };
+}
 // Shared across ALL adapter instances: a second catalog/tenant cannot run a second ffmpeg in this
 // process. Fail busy instead of holding arbitrary numbers of uploaded videos in a pending queue.
-let extracting = false;
+const defaultExtractionLock = createVideoExtractionLock({});
 const UNAVAILABLE = 'video preview unavailable on this host (nice, ffmpeg and ffprobe are required).';
 // Eight amortizes process/seek overhead while bounding expensive source decoders to
 // one eighth of the 64-frame maximum. Thread caps alone do not bound decoder memory.
 // This is a decoder-count limit, not a measured host RSS guarantee.
 const SOURCE_BATCH_SIZE = 8;
 const localInputFlags = ['-threads', '1', '-protocol_whitelist', 'file', '-format_whitelist', 'mov,matroska,webm'];
-export function createFfmpegVideoFrameExtractor({ findBinaries = findVideoBinaries, runProcess = runLowPriorityVideoProcess, nowMs = () => performance.now() }, _optional = {}) {
+export function createFfmpegVideoFrameExtractor({ findBinaries = findVideoBinaries, runProcess = runLowPriorityVideoProcess, nowMs = () => performance.now(), lock = defaultExtractionLock, env, platform }, _optional = {}) {
     return { extract: async ({ bytes }, options) => {
             if (bytes.byteLength > VIDEO_MAX_INPUT_BYTES)
                 return { ok: false, reason: 'too-large', message: `Video preview input exceeds ${VIDEO_MAX_INPUT_BYTES} bytes.` };
             const type = sniffContentType({ bytes });
             if (type !== 'video/mp4' && type !== 'video/webm')
                 return { ok: false, reason: 'invalid', message: 'Video preview requires stored MP4 or WebM bytes.' };
-            if (extracting)
+            const release = lock.tryAcquire({}, {});
+            if (!release)
                 return { ok: false, reason: 'busy', message: 'Video preview is busy. Try again after the current extraction finishes.' };
-            extracting = true;
             const deadline = nowMs({}, {}) + VIDEO_EXTRACTION_TIMEOUT_MS;
             let directory;
             try {
@@ -125,7 +140,7 @@ export function createFfmpegVideoFrameExtractor({ findBinaries = findVideoBinari
                     throw new VideoProcessError('canceled', 'Video preview canceled.');
                 if (options.layout !== undefined && options.layout !== 'frames' && options.layout !== 'sheet')
                     throw new VideoProcessError('invalid', 'Video layout must be frames or sheet.');
-                const binaries = await findBinaries({}, {});
+                const binaries = await findBinaries({}, { ...(env ? { env } : {}), ...(platform ? { platform } : {}) });
                 if (!binaries)
                     return { ok: false, reason: 'unavailable', message: UNAVAILABLE };
                 directory = await mkdtemp(join(tmpdir(), 'video-preview-'));
@@ -253,7 +268,7 @@ export function createFfmpegVideoFrameExtractor({ findBinaries = findVideoBinari
                     return { ok: false, reason: 'invalid', message: 'Video preview temporary files could not be removed.' };
                 }
                 finally {
-                    extracting = false;
+                    release();
                 }
             }
         } };

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/dropdown.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Dropdown navigation (`"variant":"dropdown"` menus), following the APG disclosure-navigation
+ * pattern: a branch item carries a server-rendered `<button class="jini-menu-toggle" aria-expanded
+ * aria-controls>` pointing at its child `<ul id>`, and the root `<ul>` carries `data-jini-dropdown`.
+ * No `role="menu"` and no `aria-haspopup` — those make screen readers announce a menu and expect
+ * menubar keys, which site nav should not imitate.
+ *
+ * The toggles are real buttons in the markup (not injected by JS), so without JS Tab still reaches
+ * them and a theme's `:focus-within` CSS opens the panel. {@link MENU_DROPDOWN_SCRIPT} adds
+ * `jini-menu-js` to each root so a theme can switch that fallback off once JS owns the open state
+ * (otherwise Escape could not close a panel while focus sits on its toggle).
+ */
+/** A branch item's toggle. Split form (default): an empty button labelled "`label` submenu" that sits
+ *  after the item's link. `asLabel`: the button IS the item's label (a link-less parent), and carries
+ *  `menu-item-label` so theme scripts that read `.menu-item-label` treat it as an inert parent.
+ *  @complexity O(n) over `label`. */
+export declare function renderMenuToggle({ controlsId, label }: {
+    controlsId: string;
+    label: string;
+}, { asLabel }?: {
+    asLabel?: boolean;
+}): string;
+/**
+ * The inline script behind every `[data-jini-dropdown]` menu ({@link injectMenuDropdownScript} adds it
+ * once per page). State lives in `li.jini-menu-open` and the toggle's `aria-expanded`.
+ * - click on a toggle opens/closes its item (mouse, touch tap, Enter/Space); any click or focus
+ *   elsewhere closes every open item that does not contain the target (siblings, click-outside,
+ *   tabbing out). Closing an item closes its open descendants too.
+ * - Escape closes the nearest open item around the focus and returns focus to its toggle.
+ * - ArrowDown on a toggle opens it and focuses the submenu's first link/button; ArrowDown/ArrowUp
+ *   inside a submenu move between sibling items; ArrowLeft/ArrowRight on a top-level item move between
+ *   top-level items. No wrap at either end. Handled arrows `preventDefault` so the page does not scroll.
+ * Hover stays pure theme CSS and never touches `aria-expanded`.
+ */
+export declare const MENU_DROPDOWN_SCRIPT = "(function(){\n  var roots=document.querySelectorAll('[data-jini-dropdown]');\n  for(var i=0;i<roots.length;i++)roots[i].classList.add('jini-menu-js');\n  function inMenu(el){return el&&el.closest&&el.closest('[data-jini-dropdown]')?el:null;}\n  function toggleOf(li){return li.querySelector(':scope > .jini-menu-toggle');}\n  function panelOf(li){var b=toggleOf(li);return b?document.getElementById(b.getAttribute('aria-controls')):null;}\n  function first(li){return li?li.querySelector('a[href], button'):null;}\n  function setOpen(li,open){\n  var items=open?[li]:[li].concat(Array.prototype.slice.call(li.querySelectorAll('li.jini-menu-open')));\n  for(var i=0;i<items.length;i++){items[i].classList[open?'add':'remove']('jini-menu-open');var b=toggleOf(items[i]);if(b)b.setAttribute('aria-expanded',open?'true':'false');}\n  }\n  function closeAll(keep){\n  var open=document.querySelectorAll('[data-jini-dropdown] li.jini-menu-open');\n  for(var i=0;i<open.length;i++)if(!(keep&&keep.nodeType===1&&open[i].contains(keep)))setOpen(open[i],false);\n  }\n  document.addEventListener('focusin',function(e){closeAll(e.target);});\n  document.addEventListener('click',function(e){\n  closeAll(e.target);\n  var b=inMenu(e.target)?e.target.closest('.jini-menu-toggle'):null;\n  if(b)setOpen(b.parentNode,b.getAttribute('aria-expanded')!=='true');\n  });\n  document.addEventListener('keydown',function(e){\n  var t=inMenu(e.target);if(!t)return;\n  if(e.key==='Escape'){var o=t.closest('li.jini-menu-open');if(o){setOpen(o,false);toggleOf(o).focus();}return;}\n  var li=t.closest('li'),next=null;if(!li)return;\n  var top=li.parentNode.hasAttribute('data-jini-dropdown');\n  if(e.key==='ArrowDown'&&t.classList.contains('jini-menu-toggle')){closeAll(li);setOpen(li,true);var p=panelOf(li);next=p?first(p):null;}\n  else if(!top&&e.key==='ArrowDown')next=first(li.nextElementSibling);\n  else if(!top&&e.key==='ArrowUp')next=first(li.previousElementSibling);\n  else if(top&&e.key==='ArrowRight')next=first(li.nextElementSibling);\n  else if(top&&e.key==='ArrowLeft')next=first(li.previousElementSibling);\n  else return;\n  e.preventDefault();\n  if(next)next.focus();\n  });\n  })();";
+/** Adds the one inline dropdown script before `</body>` when the page carries a `data-jini-dropdown`
+ *  menu and does not already have the script. @complexity O(n). */
+export declare function injectMenuDropdownScript({ html }: {
+    html: string;
+}, _optional?: Record<string, never>): string;
+//# sourceMappingURL=dropdown.d.ts.map

package/dist/navigation/dropdown.js

@@ -0,0 +1,85 @@
+/**
+ * Dropdown navigation (`"variant":"dropdown"` menus), following the APG disclosure-navigation
+ * pattern: a branch item carries a server-rendered `<button class="jini-menu-toggle" aria-expanded
+ * aria-controls>` pointing at its child `<ul id>`, and the root `<ul>` carries `data-jini-dropdown`.
+ * No `role="menu"` and no `aria-haspopup` — those make screen readers announce a menu and expect
+ * menubar keys, which site nav should not imitate.
+ *
+ * The toggles are real buttons in the markup (not injected by JS), so without JS Tab still reaches
+ * them and a theme's `:focus-within` CSS opens the panel. {@link MENU_DROPDOWN_SCRIPT} adds
+ * `jini-menu-js` to each root so a theme can switch that fallback off once JS owns the open state
+ * (otherwise Escape could not close a panel while focus sits on its toggle).
+ */
+const SCRIPT_MARKER = 'data-jini-menu-dropdown-script';
+function escapeAttribute(value) {
+    return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** A branch item's toggle. Split form (default): an empty button labelled "`label` submenu" that sits
+ *  after the item's link. `asLabel`: the button IS the item's label (a link-less parent), and carries
+ *  `menu-item-label` so theme scripts that read `.menu-item-label` treat it as an inert parent.
+ *  @complexity O(n) over `label`. */
+export function renderMenuToggle({ controlsId, label }, { asLabel = false } = {}) {
+    const id = escapeAttribute(controlsId);
+    const text = escapeAttribute(label);
+    return asLabel
+        ? `<button type="button" class="menu-item-label jini-menu-toggle" aria-expanded="false" aria-controls="${id}">${text}</button>`
+        : `<button type="button" class="jini-menu-toggle" aria-expanded="false" aria-controls="${id}" aria-label="${text} submenu"></button>`;
+}
+/**
+ * The inline script behind every `[data-jini-dropdown]` menu ({@link injectMenuDropdownScript} adds it
+ * once per page). State lives in `li.jini-menu-open` and the toggle's `aria-expanded`.
+ * - click on a toggle opens/closes its item (mouse, touch tap, Enter/Space); any click or focus
+ *   elsewhere closes every open item that does not contain the target (siblings, click-outside,
+ *   tabbing out). Closing an item closes its open descendants too.
+ * - Escape closes the nearest open item around the focus and returns focus to its toggle.
+ * - ArrowDown on a toggle opens it and focuses the submenu's first link/button; ArrowDown/ArrowUp
+ *   inside a submenu move between sibling items; ArrowLeft/ArrowRight on a top-level item move between
+ *   top-level items. No wrap at either end. Handled arrows `preventDefault` so the page does not scroll.
+ * Hover stays pure theme CSS and never touches `aria-expanded`.
+ */
+export const MENU_DROPDOWN_SCRIPT = `(function(){
+  var roots=document.querySelectorAll('[data-jini-dropdown]');
+  for(var i=0;i<roots.length;i++)roots[i].classList.add('jini-menu-js');
+  function inMenu(el){return el&&el.closest&&el.closest('[data-jini-dropdown]')?el:null;}
+  function toggleOf(li){return li.querySelector(':scope > .jini-menu-toggle');}
+  function panelOf(li){var b=toggleOf(li);return b?document.getElementById(b.getAttribute('aria-controls')):null;}
+  function first(li){return li?li.querySelector('a[href], button'):null;}
+  function setOpen(li,open){
+  var items=open?[li]:[li].concat(Array.prototype.slice.call(li.querySelectorAll('li.jini-menu-open')));
+  for(var i=0;i<items.length;i++){items[i].classList[open?'add':'remove']('jini-menu-open');var b=toggleOf(items[i]);if(b)b.setAttribute('aria-expanded',open?'true':'false');}
+  }
+  function closeAll(keep){
+  var open=document.querySelectorAll('[data-jini-dropdown] li.jini-menu-open');
+  for(var i=0;i<open.length;i++)if(!(keep&&keep.nodeType===1&&open[i].contains(keep)))setOpen(open[i],false);
+  }
+  document.addEventListener('focusin',function(e){closeAll(e.target);});
+  document.addEventListener('click',function(e){
+  closeAll(e.target);
+  var b=inMenu(e.target)?e.target.closest('.jini-menu-toggle'):null;
+  if(b)setOpen(b.parentNode,b.getAttribute('aria-expanded')!=='true');
+  });
+  document.addEventListener('keydown',function(e){
+  var t=inMenu(e.target);if(!t)return;
+  if(e.key==='Escape'){var o=t.closest('li.jini-menu-open');if(o){setOpen(o,false);toggleOf(o).focus();}return;}
+  var li=t.closest('li'),next=null;if(!li)return;
+  var top=li.parentNode.hasAttribute('data-jini-dropdown');
+  if(e.key==='ArrowDown'&&t.classList.contains('jini-menu-toggle')){closeAll(li);setOpen(li,true);var p=panelOf(li);next=p?first(p):null;}
+  else if(!top&&e.key==='ArrowDown')next=first(li.nextElementSibling);
+  else if(!top&&e.key==='ArrowUp')next=first(li.previousElementSibling);
+  else if(top&&e.key==='ArrowRight')next=first(li.nextElementSibling);
+  else if(top&&e.key==='ArrowLeft')next=first(li.previousElementSibling);
+  else return;
+  e.preventDefault();
+  if(next)next.focus();
+  });
+  })();`;
+/** Adds the one inline dropdown script before `</body>` when the page carries a `data-jini-dropdown`
+ *  menu and does not already have the script. @complexity O(n). */
+export function injectMenuDropdownScript({ html }, _optional = {}) {
+    if (!html.includes('data-jini-dropdown') || html.includes(SCRIPT_MARKER))
+        return html;
+    const script = `<script ${SCRIPT_MARKER}>${MENU_DROPDOWN_SCRIPT}</script>`;
+    const bodyClose = html.lastIndexOf('</body>');
+    return bodyClose === -1 ? html + script : html.slice(0, bodyClose) + script + html.slice(bodyClose);
+}
+//# sourceMappingURL=dropdown.js.map

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,8 +26,12 @@ 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";
+/** Dropdown menus (2026-10-11): toggle markup + the inline keyboard/touch script (see `dropdown.ts`). */
+export { renderMenuToggle, injectMenuDropdownScript, MENU_DROPDOWN_SCRIPT } from "./dropdown.js";
 /** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */
 export { menusAgentToolCatalog, } from "./agent-tools.js";
 /**

package/dist/navigation/index.js

@@ -17,8 +17,12 @@ 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";
+/** Dropdown menus (2026-10-11): toggle markup + the inline keyboard/touch script (see `dropdown.ts`). */
+export { renderMenuToggle, injectMenuDropdownScript, MENU_DROPDOWN_SCRIPT } from "./dropdown.js";
 /** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */
 export { menusAgentToolCatalog, } from "./agent-tools.js";
 /**

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,
     };