From f9fe12bff3ff203edae64a6eba1ad95dc4f43645 Mon Sep 17 00:00:00 2001
From: Quynn Bell <quynnbell@protonmail.com>
Date: Mon, 12 Oct 2026 10:33:10 -0700
Subject: [PATCH 1/7] feat(header): add initial structure for WordPress-style
 header navigation modules

- Add base.nav, a nav bar that collapses to a dropdown or overlay below a chosen width
- Add base.nav-item, a menu entry that nests to build submenus
- Let a menu item be a link or a static label that toggles its submenu
- Add the module contract fields they rely on: instanceCss, canvasCss, canvasViewportWidth, number presets and select icons
- Header navigation: this is the core feature, and every later commit on the branch builds on it
---
 src/core/module-engine/propertySchema.ts      |   8 +
 src/core/module-engine/types.ts               |  28 ++
 src/modules/base/index.ts                     |   4 +
 src/modules/base/nav-item/NavItemEditor.tsx   |  62 +++++
 .../nav-item/__tests__/navItem.render.test.ts | 248 ++++++++++++++++++
 src/modules/base/nav-item/content.ts          |  24 ++
 src/modules/base/nav-item/icons.ts            |   7 +
 src/modules/base/nav-item/index.ts            |  97 +++++++
 src/modules/base/nav-item/navItemCss.ts       | 127 +++++++++
 src/modules/base/nav-item/navItemRuntimeJs.ts |  51 ++++
 src/modules/base/nav-item/props.ts            |  14 +
 src/modules/base/nav/NavEditor.tsx            |  75 ++++++
 .../base/nav/__tests__/nav.render.test.ts     | 190 ++++++++++++++
 src/modules/base/nav/icons.ts                 |  23 ++
 src/modules/base/nav/index.ts                 | 139 ++++++++++
 src/modules/base/nav/navCss.ts                | 138 ++++++++++
 src/modules/base/nav/navRuntimeJs.ts          |  54 ++++
 src/modules/base/nav/props.ts                 |  60 +++++
 src/modules/base/shared/navCollapse.ts        |  29 ++
 19 files changed, 1378 insertions(+)
 create mode 100644 src/modules/base/nav-item/NavItemEditor.tsx
 create mode 100644 src/modules/base/nav-item/__tests__/navItem.render.test.ts
 create mode 100644 src/modules/base/nav-item/content.ts
 create mode 100644 src/modules/base/nav-item/icons.ts
 create mode 100644 src/modules/base/nav-item/index.ts
 create mode 100644 src/modules/base/nav-item/navItemCss.ts
 create mode 100644 src/modules/base/nav-item/navItemRuntimeJs.ts
 create mode 100644 src/modules/base/nav-item/props.ts
 create mode 100644 src/modules/base/nav/NavEditor.tsx
 create mode 100644 src/modules/base/nav/__tests__/nav.render.test.ts
 create mode 100644 src/modules/base/nav/icons.ts
 create mode 100644 src/modules/base/nav/index.ts
 create mode 100644 src/modules/base/nav/navCss.ts
 create mode 100644 src/modules/base/nav/navRuntimeJs.ts
 create mode 100644 src/modules/base/nav/props.ts
 create mode 100644 src/modules/base/shared/navCollapse.ts

diff --git a/src/core/module-engine/propertySchema.ts b/src/core/module-engine/propertySchema.ts
index c71cc6947..682a0ab9f 100644
--- a/src/core/module-engine/propertySchema.ts
+++ b/src/core/module-engine/propertySchema.ts
@@ -80,6 +80,12 @@ const PropertyControlOptionSchema = Type.Object(
   {
     label: Type.String({ minLength: 1 }),
     value: Type.Unknown(),
+    /**
+     * Inline SVG markup for this option. When any option of a `select` has
+     * one, the control renders as an icon button row with `label` as each
+     * button's tooltip and accessible name. Sanitised with `sanitizeSvg`.
+     */
+    iconSvg: Type.Optional(Type.String()),
   },
   { additionalProperties: false },
 )
@@ -111,6 +117,8 @@ export const PropertyControlSchema = Type.Recursive((Self) => Type.Union([
       max: Type.Optional(Type.Number()),
       step: Type.Optional(Type.Number()),
       unit: Type.Optional(Type.String()),
+      /** Suggested values shown as buttons under the field. Any number is still accepted. */
+      presets: Type.Optional(Type.Array(Type.Number())),
     },
     { additionalProperties: false },
   ),
diff --git a/src/core/module-engine/types.ts b/src/core/module-engine/types.ts
index f99294fea..405d5faac 100644
--- a/src/core/module-engine/types.ts
+++ b/src/core/module-engine/types.ts
@@ -85,6 +85,12 @@ export interface RenderOutput {
    * The publisher deduplicates across all instances (one CSS block per module type).
    */
   css?: string
+  /**
+   * Optional CSS that depends on this instance's props (e.g. a media query at
+   * an author-chosen width). Deduplicated by content, not by module type.
+   * Prop-independent rules belong in `css`.
+   */
+  instanceCss?: string
   /**
    * Optional vanilla-JS runtime for this module TYPE, deduplicated per
    * moduleId exactly like `css` and served as an external per-module asset
@@ -158,6 +164,13 @@ export interface ModuleComponentProps<
    * See `inlineEditableElementProps` in `@modules/base/shared/inlineText`.
    */
   inlineEdit?: InlineEditBinding
+  /**
+   * Pixel width of the breakpoint frame this component renders in (e.g. 375
+   * for mobile), so it can mimic responsive behavior. `undefined` when the
+   * render path does not provide it (e.g. sandboxed plugin modules, agent
+   * snapshot rendering).
+   */
+  canvasViewportWidth?: number
 }
 
 /**
@@ -399,6 +412,21 @@ export interface ModuleDefinition<
    */
   component: ComponentType<ModuleComponentProps<TProps>>
 
+  /**
+   * Optional stylesheet for `component`. The canvas never loads
+   * `render().css`, so a module that wants its published rules in the canvas
+   * repeats them here.
+   *
+   * Injected into every canvas frame after the reset and framework CSS and
+   * before class and user CSS, the same order the publisher uses. Use the
+   * published selectors so author classes override it as they do when
+   * published.
+   *
+   * Trusted modules only. A plugin module's component renders in a sandbox
+   * frame that this stylesheet never reaches.
+   */
+  canvasCss?: string
+
   /**
    * Optional dependency-backed editor runtime. When present, the canvas renders
    * this module in a sandboxed iframe with an import map built from the module's
diff --git a/src/modules/base/index.ts b/src/modules/base/index.ts
index 2d8ceed63..5eb3b98f0 100644
--- a/src/modules/base/index.ts
+++ b/src/modules/base/index.ts
@@ -31,6 +31,10 @@ import './svg'
 import './button'
 import './link'
 
+// Navigation modules
+import './nav'
+import './nav-item'
+
 // Form modules
 import './forms'
 
diff --git a/src/modules/base/nav-item/NavItemEditor.tsx b/src/modules/base/nav-item/NavItemEditor.tsx
new file mode 100644
index 000000000..9bfc2fcd6
--- /dev/null
+++ b/src/modules/base/nav-item/NavItemEditor.tsx
@@ -0,0 +1,62 @@
+/**
+ * base.nav-item editor preview component.
+ *
+ * Component-only file so React Fast Refresh can hot-patch edits without
+ * re-running module registration.
+ *
+ * Renders the same elements and classes as render(). Styling comes from the
+ * module's `canvasCss` (NAV_ITEM_CANVAS_CSS). A submenu opens while this item
+ * or a node inside it is selected. The toggle buttons do nothing, because
+ * module JS never runs in the canvas.
+ */
+import React from 'react'
+import type { ModuleComponentProps } from '@core/module-engine'
+import { cn } from '@ui/cn'
+import { anchorRel } from '@modules/base/shared/anchorTarget'
+import { htmlAttributesForReact } from '@core/htmlAttributes'
+import { navItemHasSubmenu, navItemIsLink } from './content'
+import { NAV_ITEM_CARET_SVG } from './icons'
+import type { NavItemStoredProps } from './props'
+
+const caret = (
+  <span className="instatic-nav-item__toggle-icon" aria-hidden="true" dangerouslySetInnerHTML={{ __html: NAV_ITEM_CARET_SVG }} />
+)
+
+export const NavItemEditor: React.FC<ModuleComponentProps<NavItemStoredProps>> = ({
+  props, children, mcClassName, nodeWrapperProps,
+}) => {
+  const childCount = Array.isArray(children) ? children.length : children != null ? 1 : 0
+  const hasSubmenu = navItemHasSubmenu(childCount)
+  const isLink = navItemIsLink(props.isLink)
+  const htmlAttrs = htmlAttributesForReact(props.htmlAttributes)
+  const label = props.label || 'Menu item'
+
+  return (
+    <li {...nodeWrapperProps} {...htmlAttrs} className={cn('instatic-nav-item', mcClassName)}>
+      {isLink ? (
+        <a
+          className="instatic-nav-item__link"
+          href={props.href || '#'}
+          target={props.target}
+          rel={anchorRel(props.target) ?? undefined}
+        >
+          {label}
+        </a>
+      ) : hasSubmenu ? (
+        <button type="button" className="instatic-nav-item__link" tabIndex={-1}>{label}{caret}</button>
+      ) : (
+        <span className="instatic-nav-item__link">{label}</span>
+      )}
+      {hasSubmenu ? (
+        <>
+          {isLink ? (
+            <button type="button" className="instatic-nav-item__toggle" tabIndex={-1} aria-hidden="true">{caret}</button>
+          ) : null}
+          <ul className="instatic-nav-item__submenu">
+            {children}
+          </ul>
+        </>
+      ) : null}
+    </li>
+  )
+}
diff --git a/src/modules/base/nav-item/__tests__/navItem.render.test.ts b/src/modules/base/nav-item/__tests__/navItem.render.test.ts
new file mode 100644
index 000000000..2ddc9e55f
--- /dev/null
+++ b/src/modules/base/nav-item/__tests__/navItem.render.test.ts
@@ -0,0 +1,248 @@
+import { afterEach, describe, expect, it } from 'bun:test'
+import { NavItemModule } from '../index'
+import { NAV_ITEM_COLLAPSED_INDENTS, navItemCollapseCss } from '../navItemCss'
+import { NAV_ITEM_RUNTIME_JS } from '../navItemRuntimeJs'
+
+const baseProps = {
+  label: 'About',
+  isLink: true,
+  href: '/about',
+  target: '_self' as const,
+  htmlAttributes: {},
+}
+
+const childHtml = '<li class="instatic-nav-item">Team</li>'
+
+describe('base.nav-item render', () => {
+  it('renders a plain link li when childless', () => {
+    const { html } = NavItemModule.render(baseProps as never, [])
+    expect(html).toBe('<li class="instatic-nav-item"><a class="instatic-nav-item__link" href="/about" target="_self">About</a></li>')
+  })
+
+  it('renders a link, a caret toggle, and the submenu when it has children', () => {
+    const { html } = NavItemModule.render(baseProps as never, [childHtml])
+    expect(html).toBe(
+      '<li class="instatic-nav-item" data-instatic-nav-item-state="closed">'
+      + '<a class="instatic-nav-item__link" href="/about" target="_self">About</a>'
+      + '<button type="button" class="instatic-nav-item__toggle" data-instatic-nav-item-toggle aria-expanded="false" aria-label="Toggle submenu">'
+      + '<span class="instatic-nav-item__toggle-icon" aria-hidden="true">'
+      + '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M6 9l6 6 6-6"/></svg>'
+      + '</span></button>'
+      + `<ul class="instatic-nav-item__submenu">${childHtml}</ul>`
+      + '</li>',
+    )
+  })
+
+  it('omits the caret/sub-menu entirely when childless', () => {
+    const { html } = NavItemModule.render(baseProps as never, [])
+    expect(html).not.toContain('data-instatic-nav-item-state')
+    expect(html).not.toContain('data-instatic-nav-item-toggle')
+    expect(html).not.toContain('instatic-nav-item__submenu')
+  })
+
+  it('prefixes every class it emits', () => {
+    const { html, css } = NavItemModule.render(baseProps as never, [childHtml])
+    const htmlClasses = Array.from(html.matchAll(/class="([^"]+)"/g)).flatMap((match) => match[1].split(' '))
+    const cssClasses = Array.from(css!.matchAll(/\.([a-z][\w-]*)/g)).map((match) => match[1])
+    for (const name of [...htmlClasses, ...cssClasses]) expect(name).toStartWith('instatic-nav-item')
+  })
+
+  it('collapses an unsafe href scheme to "#" via safeUrl', () => {
+    const { html } = NavItemModule.render({ ...baseProps, href: 'javascript:alert(1)' } as never, [])
+    expect(html).toContain('href="#"')
+  })
+
+  it('adds rel="noopener noreferrer" for target=_blank, omits rel for target=_self', () => {
+    const blank = NavItemModule.render({ ...baseProps, target: '_blank' } as never, [])
+    expect(blank.html).toContain('rel="noopener noreferrer"')
+
+    const self = NavItemModule.render({ ...baseProps, target: '_self' } as never, [])
+    expect(self.html).not.toContain('rel=')
+  })
+
+  it('renders htmlAttributes onto the <li> root, not the <a>', () => {
+    const { html } = NavItemModule.render(
+      { ...baseProps, htmlAttributes: { 'data-testid': 'nav-item-1' } } as never,
+      [],
+    )
+    expect(html).toBe(
+      '<li class="instatic-nav-item" data-testid="nav-item-1"><a class="instatic-nav-item__link" href="/about" target="_self">About</a></li>',
+    )
+  })
+
+  it('keeps every media query out of the static css and ships a load-guarded JS runtime', () => {
+    const { css, js } = NavItemModule.render(baseProps as never, [])
+    expect(css).not.toContain('@media')
+    expect(js).toContain('window.__instaticNavItemRuntimeLoaded')
+  })
+
+  it('shows the submenu caret at every width, beside the label', () => {
+    const { css } = NavItemModule.render(baseProps as never, [])
+    expect(css).toMatch(/\.instatic-nav-item__toggle \{\s+display: inline-flex;/)
+    expect(navItemCollapseCss(768)).not.toContain('.instatic-nav-item__toggle {')
+  })
+
+  it('paints the desktop submenu from the menu background, with no hardcoded colour', () => {
+    const { css } = NavItemModule.render(baseProps as never, [])
+    expect(`${css}${navItemCollapseCss(768)}`).not.toMatch(/#[0-9a-f]{3,8}\b/i)
+    expect(css).toMatch(
+      /\.instatic-nav-item > \.instatic-nav-item__submenu \{[^}]*background-color: var\(--instatic-nav-menu-bg, Canvas\);/,
+    )
+  })
+
+  it('scopes its collapsed rules by the ancestor nav and its collapse width', () => {
+    // base.nav-item's render() never sees its parent nav's props, so base.nav
+    // emits this block for its own width.
+    const css = navItemCollapseCss(913)
+    expect(css).toContain('@media (max-width: 913px)')
+    expect(css).toContain('.instatic-nav[data-instatic-nav-collapse="913"] .instatic-nav-item > .instatic-nav-item__submenu')
+    // The submenu drops to its own row so the caret stays beside the label.
+    expect(css).toContain('flex-wrap: wrap;')
+    expect(css).toContain('flex-basis: 100%;')
+  })
+
+  it('indents each nested level of a collapsed menu on its links, one step deeper per submenu', () => {
+    const css = navItemCollapseCss(913)
+    const scope = '.instatic-nav[data-instatic-nav-collapse="913"]'
+    const submenu = ' .instatic-nav-item__submenu'
+    expect(NAV_ITEM_COLLAPSED_INDENTS).toEqual([28, 44, 60])
+    expect(css).toContain(`${scope}${submenu} .instatic-nav-item__link {\n    padding-left: 28px;\n  }`)
+    expect(css).toContain(`${scope}${submenu}${submenu} .instatic-nav-item__link {\n    padding-left: 44px;\n  }`)
+    expect(css).toContain(`${scope}${submenu}${submenu}${submenu} .instatic-nav-item__link {\n    padding-left: 60px;\n  }`)
+    // The indent is on the link. Padding the list would stop a nested row
+    // from spanning the full menu width.
+    expect(css).not.toMatch(/__submenu \{[^}]*padding-left/)
+    // Deeper selectors come later, so a deeper level overrides a shallower one.
+    expect(css.indexOf('padding-left: 28px')).toBeLessThan(css.indexOf('padding-left: 44px'))
+    expect(css.indexOf('padding-left: 44px')).toBeLessThan(css.indexOf('padding-left: 60px'))
+  })
+
+  it('css and js are prop-independent (required by per-moduleId dedup, first-render-wins)', () => {
+    const a = NavItemModule.render(baseProps as never, [])
+    const b = NavItemModule.render({ ...baseProps, label: 'Different', href: '/x', isLink: false } as never, ['<li>x</li>'])
+    expect(a.css).toBe(b.css)
+    expect(a.js).toBe(b.js)
+  })
+})
+
+describe('base.nav-item with the link turned off', () => {
+  const unlinked = { ...baseProps, isLink: false }
+
+  it('makes the label of an item with a submenu the toggle button itself', () => {
+    const { html } = NavItemModule.render(unlinked as never, [childHtml])
+    expect(html).not.toContain('<a ')
+    expect(html).not.toContain('href=')
+    expect(html).toContain(
+      '<li class="instatic-nav-item" data-instatic-nav-item-state="closed">'
+      + '<button type="button" class="instatic-nav-item__link" data-instatic-nav-item-toggle aria-expanded="false">About'
+      + '<span class="instatic-nav-item__toggle-icon" aria-hidden="true">',
+    )
+    // One toggle, named by the label: no second caret button.
+    expect(html.match(/data-instatic-nav-item-toggle/g)).toHaveLength(1)
+    expect(html).not.toContain('aria-label="Toggle submenu"')
+  })
+
+  it('renders a childless unlinked item as plain text', () => {
+    const { html } = NavItemModule.render(unlinked as never, [])
+    expect(html).toBe('<li class="instatic-nav-item"><span class="instatic-nav-item__link">About</span></li>')
+  })
+
+  it('stays a link for a node stored before the prop existed', () => {
+    const { isLink: _isLink, ...legacyProps } = baseProps
+    const { html } = NavItemModule.render(legacyProps as never, [])
+    expect(html).toContain('<a class="instatic-nav-item__link" href="/about"')
+  })
+
+  it('puts an "Enable link" toggle under the label, hiding Link and Target while it is off', () => {
+    expect(Object.keys(NavItemModule.schema).slice(0, 4)).toEqual(['label', 'isLink', 'href', 'target'])
+    expect(NavItemModule.schema.href).toEqual({ type: 'url', label: 'Link', condition: { field: 'isLink', notEq: false } })
+    expect(NavItemModule.schema.isLink.type).toBe('toggle')
+    expect(NavItemModule.schema.isLink.label).toBe('Enable link')
+    expect(NavItemModule.defaults.isLink).toBe(true)
+    expect(NavItemModule.schema.target.condition).toEqual({ field: 'isLink', notEq: false })
+  })
+
+  it('lets a toggle open its submenu at any width, not only when collapsed', () => {
+    const { css } = NavItemModule.render(unlinked as never, [childHtml])
+    expect(css).toContain(
+      '.instatic-nav-item[data-instatic-nav-item-state="open"] > .instatic-nav-item__submenu {\n  display: flex;',
+    )
+  })
+})
+
+describe('base.nav-item runtime', () => {
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  function mountMenu() {
+    const pricing = NavItemModule.render({ ...baseProps, label: 'Pricing', href: '/pricing' } as never, []).html
+    const nested = NavItemModule.render({ ...baseProps, label: 'More', isLink: false } as never, [pricing]).html
+    const products = NavItemModule.render({ ...baseProps, label: 'Products', isLink: false } as never, [nested]).html
+    const company = NavItemModule.render({ ...baseProps, label: 'Company' } as never, [pricing]).html
+    document.body.innerHTML = `<nav><ul>${products}${company}</ul></nav><p id="outside">Outside</p>`
+    // The load guard makes a second evaluation a no-op, as on a real page.
+    new Function(NAV_ITEM_RUNTIME_JS)()
+    const [productsItem, moreItem] = Array.from(document.querySelectorAll<HTMLElement>('.instatic-nav-item'))
+    const companyItem = document.querySelector<HTMLElement>('nav > ul > .instatic-nav-item:last-child')!
+    const toggleOf = (item: HTMLElement) => item.querySelector<HTMLElement>(':scope > [data-instatic-nav-item-toggle]')!
+    const stateOf = (item: HTMLElement) => item.getAttribute('data-instatic-nav-item-state')
+    return { productsItem, moreItem, companyItem, toggleOf, stateOf }
+  }
+
+  it('toggles the submenu when an unlinked label is clicked, and mirrors it in aria-expanded', () => {
+    const { productsItem, toggleOf, stateOf } = mountMenu()
+    const label = toggleOf(productsItem)
+    expect(label.tagName).toBe('BUTTON')
+    expect(label.textContent).toBe('Products')
+
+    label.click()
+    expect(stateOf(productsItem)).toBe('open')
+    expect(label.getAttribute('aria-expanded')).toBe('true')
+
+    label.click()
+    expect(stateOf(productsItem)).toBe('closed')
+    expect(label.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('toggles from the caret of a linked item, leaving the link itself alone', () => {
+    const { companyItem, toggleOf, stateOf } = mountMenu()
+    companyItem.querySelector<HTMLElement>(':scope > a')!.addEventListener('click', (event) => event.preventDefault())
+    companyItem.querySelector<HTMLElement>(':scope > a')!.click()
+    expect(stateOf(companyItem)).toBe('closed')
+
+    toggleOf(companyItem).click()
+    expect(stateOf(companyItem)).toBe('open')
+  })
+
+  it('keeps ancestors open when a nested toggle is clicked', () => {
+    const { productsItem, moreItem, toggleOf, stateOf } = mountMenu()
+    toggleOf(productsItem).click()
+    toggleOf(moreItem).click()
+    expect(stateOf(productsItem)).toBe('open')
+    expect(stateOf(moreItem)).toBe('open')
+    // aria-expanded stays on each item's own toggle.
+    expect(toggleOf(productsItem).getAttribute('aria-expanded')).toBe('true')
+  })
+
+  it('closes an open item when a sibling toggle or anything outside it is clicked', () => {
+    const { productsItem, companyItem, toggleOf, stateOf } = mountMenu()
+    toggleOf(productsItem).click()
+    toggleOf(companyItem).click()
+    expect(stateOf(productsItem)).toBe('closed')
+    expect(stateOf(companyItem)).toBe('open')
+
+    document.getElementById('outside')!.click()
+    expect(stateOf(companyItem)).toBe('closed')
+    expect(toggleOf(companyItem).getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('closes every open item on Escape', () => {
+    const { productsItem, moreItem, toggleOf, stateOf } = mountMenu()
+    toggleOf(productsItem).click()
+    toggleOf(moreItem).click()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }))
+    expect(stateOf(productsItem)).toBe('closed')
+    expect(stateOf(moreItem)).toBe('closed')
+  })
+})
diff --git a/src/modules/base/nav-item/content.ts b/src/modules/base/nav-item/content.ts
new file mode 100644
index 000000000..3eb076ebe
--- /dev/null
+++ b/src/modules/base/nav-item/content.ts
@@ -0,0 +1,24 @@
+/**
+ * Element decisions for base.nav-item, shared by render() and the editor
+ * component.
+ *
+ * Kept in a non-component `.ts` file so the editor component can import it
+ * without breaking React Fast Refresh.
+ */
+
+/**
+ * A nav-item renders its submenu toggle and submenu list only when it has
+ * children. A childless item is a plain <li><a>.
+ */
+export function navItemHasSubmenu(childCount: number): boolean {
+  return childCount > 0
+}
+
+/**
+ * Whether the label is a link. When it is not, the label of an item with a
+ * submenu is the submenu toggle itself. A node stored before the prop existed
+ * is a link.
+ */
+export function navItemIsLink(value: unknown): boolean {
+  return value !== false
+}
diff --git a/src/modules/base/nav-item/icons.ts b/src/modules/base/nav-item/icons.ts
new file mode 100644
index 000000000..e3f6c3d25
--- /dev/null
+++ b/src/modules/base/nav-item/icons.ts
@@ -0,0 +1,7 @@
+/**
+ * Inline SVG caret for the nav-item submenu toggle button. Embedded directly
+ * because vendored pixel-art-icons cannot be inlined into publisher HTML.
+ * Shared by render() and NavItemEditor.tsx.
+ */
+export const NAV_ITEM_CARET_SVG =
+  '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M6 9l6 6 6-6"/></svg>'
diff --git a/src/modules/base/nav-item/index.ts b/src/modules/base/nav-item/index.ts
new file mode 100644
index 000000000..efe83739c
--- /dev/null
+++ b/src/modules/base/nav-item/index.ts
@@ -0,0 +1,97 @@
+/**
+ * base.nav-item: a nestable navigation entry.
+ *
+ * Renders `<li><a>label</a></li>`. An item with children is a submenu: it
+ * also renders a toggle button and a `<ul>` around the children. Items nest
+ * to any depth.
+ *
+ * With the "Link" prop off the label is not an <a>. On an item with a submenu
+ * the label is the toggle button.
+ */
+import type { ModuleDefinition } from '@core/module-engine'
+import { registry } from '@core/module-engine'
+import { Value } from '@core/utils/typeboxHelpers'
+import { Bulletlist2SharpIcon } from 'pixel-art-icons/icons/bulletlist-2-sharp'
+import { safeUrl } from '@modules/base/utils/escape'
+import { ANCHOR_TARGET_OPTIONS, anchorRel } from '@modules/base/shared/anchorTarget'
+import {
+  htmlAttributesControl,
+} from '@modules/base/shared/htmlAttributes'
+import { htmlAttributesAttr } from '@core/publisher'
+import { navItemHasSubmenu, navItemIsLink } from './content'
+import { NAV_ITEM_CARET_SVG } from './icons'
+import { NAV_ITEM_CANVAS_CSS, NAV_ITEM_CSS } from './navItemCss'
+import { NAV_ITEM_RUNTIME_JS } from './navItemRuntimeJs'
+import { NavItemEditor } from './NavItemEditor'
+import { NavItemPropsSchema, type NavItemStoredProps } from './props'
+
+export const NavItemModule: ModuleDefinition<NavItemStoredProps> = {
+  id: 'base.nav-item',
+  name: 'Menu Item',
+  description: 'A navigation link. Nest more Menu Items inside to build a submenu.',
+  category: 'Navigation',
+  version: '1.0.0',
+  icon: Bulletlist2SharpIcon,
+  trusted: true,
+  canHaveChildren: true,
+
+  schema: {
+    label: { type: 'text', label: 'Label' },
+    isLink: {
+      type: 'toggle',
+      label: 'Enable link',
+      description: 'Turn off to make this item a static label. On an item with a submenu, clicking the label then opens the submenu instead of following the link.',
+    },
+    // `notEq: false` keeps Link and Target visible on a node stored before `isLink` existed.
+    href: { type: 'url', label: 'Link', condition: { field: 'isLink', notEq: false } },
+    target: {
+      type: 'select',
+      label: 'Target',
+      options: [...ANCHOR_TARGET_OPTIONS],
+      condition: { field: 'isLink', notEq: false },
+    },
+    htmlAttributes: htmlAttributesControl(),
+  },
+
+  propsSchema: NavItemPropsSchema,
+
+  defaults: Value.Create(NavItemPropsSchema),
+
+  component: NavItemEditor,
+
+  canvasCss: NAV_ITEM_CANVAS_CSS,
+
+  htmlTag: 'li',
+
+  render: (props, renderedChildren) => {
+    const attrs = htmlAttributesAttr(props.htmlAttributes)
+    const label = String(props.label ?? '')
+    const hasSubmenu = navItemHasSubmenu(renderedChildren.length)
+    const caret = `<span class="instatic-nav-item__toggle-icon" aria-hidden="true">${NAV_ITEM_CARET_SVG}</span>`
+    const toggleAttrs = 'data-instatic-nav-item-toggle aria-expanded="false"'
+
+    let labelHtml: string
+    if (navItemIsLink(props.isLink)) {
+      const rel = anchorRel(props.target)
+      const relAttr = rel ? ` rel="${rel}"` : ''
+      labelHtml = `<a class="instatic-nav-item__link" href="${safeUrl(props.href)}" target="${String(props.target)}"${relAttr}>${label}</a>`
+      if (hasSubmenu) {
+        labelHtml += `<button type="button" class="instatic-nav-item__toggle" ${toggleAttrs} aria-label="Toggle submenu">${caret}</button>`
+      }
+    } else if (hasSubmenu) {
+      // Not a link: the label itself is the submenu toggle.
+      labelHtml = `<button type="button" class="instatic-nav-item__link" ${toggleAttrs}>${label}${caret}</button>`
+    } else {
+      labelHtml = `<span class="instatic-nav-item__link">${label}</span>`
+    }
+
+    const html = hasSubmenu
+      ? `<li class="instatic-nav-item" data-instatic-nav-item-state="closed"${attrs}>${labelHtml}`
+        + `<ul class="instatic-nav-item__submenu">${renderedChildren.join('')}</ul></li>`
+      : `<li class="instatic-nav-item"${attrs}>${labelHtml}</li>`
+
+    return { html, css: NAV_ITEM_CSS, js: NAV_ITEM_RUNTIME_JS }
+  },
+}
+
+registry.registerOrReplace(NavItemModule)
diff --git a/src/modules/base/nav-item/navItemCss.ts b/src/modules/base/nav-item/navItemCss.ts
new file mode 100644
index 000000000..cfef25f48
--- /dev/null
+++ b/src/modules/base/nav-item/navItemCss.ts
@@ -0,0 +1,127 @@
+/**
+ * CSS for base.nav-item.
+ *
+ * NAV_ITEM_CSS: static rules, emitted once per module type. A submenu opens
+ * on hover, on keyboard focus, or when its toggle is open.
+ * navItemCollapseCss(width): the collapsed accordion, where only the toggle
+ * opens a submenu. Emitted by base.nav, which owns the width.
+ * NAV_ITEM_CANVAS_CSS: the module's `canvasCss`, the same rules with the
+ * canvas selectors. See shared/navCollapse.ts.
+ */
+import { NAV_CANVAS_COLLAPSED, NAV_CANVAS_OPEN } from '@modules/base/shared/navCollapse'
+
+const NAV_ITEM_OPEN = '[data-instatic-nav-item-state="open"]'
+
+/** Left padding of a link in the collapsed layout, by submenu depth. */
+export const NAV_ITEM_COLLAPSED_INDENTS = [28, 44, 60]
+
+function navItemStaticCss(open: string): string {
+  return `
+.instatic-nav-item {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+.instatic-nav-item__link {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 12px;
+  color: inherit;
+  text-decoration: none;
+}
+button.instatic-nav-item__link {
+  background: none;
+  border: 0;
+  font: inherit;
+  cursor: pointer;
+}
+.instatic-nav-item__toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: 0;
+  padding: 6px 8px;
+  margin-left: -4px;
+  cursor: pointer;
+  color: inherit;
+}
+.instatic-nav-item__toggle-icon {
+  display: inline-flex;
+  width: 14px;
+  height: 14px;
+  transition: transform 0.15s ease;
+}
+.instatic-nav-item__submenu {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.instatic-nav-item > .instatic-nav-item__submenu {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  min-width: 180px;
+  display: none;
+  flex-direction: column;
+  background-color: var(--instatic-nav-menu-bg, Canvas);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
+  z-index: 20;
+}
+.instatic-nav-item:hover > .instatic-nav-item__submenu,
+.instatic-nav-item:focus-within > .instatic-nav-item__submenu,
+.instatic-nav-item${open} > .instatic-nav-item__submenu {
+  display: flex;
+}
+.instatic-nav-item .instatic-nav-item > .instatic-nav-item__submenu {
+  top: 0;
+  left: 100%;
+}
+`
+}
+
+/** The accordion layout for items inside the nav matched by `scope`. An item matching `open` shows its submenu. */
+function navItemCollapseRules(scope: string, open: string): string {
+  // Nested levels indent their links, not the list, so each row and its
+  // background still span the full width of the menu.
+  const indents = NAV_ITEM_COLLAPSED_INDENTS.map((indent, depth) => `
+  ${scope}${' .instatic-nav-item__submenu'.repeat(depth + 1)} .instatic-nav-item__link {
+    padding-left: ${indent}px;
+  }`).join('')
+
+  return `
+  ${scope} .instatic-nav-item {
+    flex-wrap: wrap;
+    width: 100%;
+  }
+  ${scope} .instatic-nav-item > .instatic-nav-item__submenu {
+    position: static;
+    display: none;
+    flex-basis: 100%;
+    min-width: 0;
+    box-shadow: none;
+    background-color: transparent;
+  }${indents}
+  ${scope} .instatic-nav-item:hover > .instatic-nav-item__submenu,
+  ${scope} .instatic-nav-item:focus-within > .instatic-nav-item__submenu {
+    display: none;
+  }
+  ${scope} .instatic-nav-item${open} > .instatic-nav-item__submenu {
+    display: flex;
+  }
+  ${scope} .instatic-nav-item${open} > * > .instatic-nav-item__toggle-icon {
+    transform: rotate(180deg);
+  }`
+}
+
+export function navItemCollapseCss(width: number): string {
+  return `
+@media (max-width: ${width}px) {${navItemCollapseRules(`.instatic-nav[data-instatic-nav-collapse="${width}"]`, NAV_ITEM_OPEN)}
+}`
+}
+
+export const NAV_ITEM_CSS = navItemStaticCss(NAV_ITEM_OPEN)
+
+export const NAV_ITEM_CANVAS_CSS = `${navItemStaticCss(NAV_CANVAS_OPEN)}${navItemCollapseRules(NAV_CANVAS_COLLAPSED, NAV_CANVAS_OPEN)}
+`
diff --git a/src/modules/base/nav-item/navItemRuntimeJs.ts b/src/modules/base/nav-item/navItemRuntimeJs.ts
new file mode 100644
index 000000000..904a69633
--- /dev/null
+++ b/src/modules/base/nav-item/navItemRuntimeJs.ts
@@ -0,0 +1,51 @@
+/**
+ * Module-JS runtime for base.nav-item: the submenu toggle.
+ *
+ * A self-contained IIFE with a load guard, bound through document-level
+ * event delegation (the RenderOutput.js contract).
+ *
+ * The toggle is the caret button beside a linked label, or the label itself
+ * when the item is not a link. Collapsed, it drives the accordion. On
+ * desktop it pins a dropdown open, where hover and focus also open it
+ * through CSS.
+ *
+ * Escape or a click outside an open item closes it. A click in a nested item
+ * is inside its ancestors, so they stay open.
+ *
+ * Independent of base.nav's runtime: a toggle click is inside the <nav>, so
+ * base.nav's outside-click handler ignores it.
+ */
+export const NAV_ITEM_RUNTIME_JS = `(() => {
+  if (window.__instaticNavItemRuntimeLoaded) return;
+  window.__instaticNavItemRuntimeLoaded = true;
+
+  var TOGGLE_SELECTOR = '[data-instatic-nav-item-toggle]';
+  var ITEM_SELECTOR = '.instatic-nav-item';
+  var OPEN_SELECTOR = ITEM_SELECTOR + '[data-instatic-nav-item-state="open"]';
+
+  function setOpen(item, open) {
+    item.setAttribute('data-instatic-nav-item-state', open ? 'open' : 'closed');
+    var toggle = item.querySelector(':scope > ' + TOGGLE_SELECTOR);
+    if (toggle) toggle.setAttribute('aria-expanded', open ? 'true' : 'false');
+  }
+
+  document.addEventListener('click', function (event) {
+    var target = event.target;
+    var toggle = target && target.closest ? target.closest(TOGGLE_SELECTOR) : null;
+    var item = toggle ? toggle.closest(ITEM_SELECTOR) : null;
+    var openItems = document.querySelectorAll(OPEN_SELECTOR);
+    for (var i = 0; i < openItems.length; i++) {
+      if (openItems[i] !== item && !openItems[i].contains(target)) setOpen(openItems[i], false);
+    }
+    if (!item) return;
+    event.preventDefault();
+    setOpen(item, item.getAttribute('data-instatic-nav-item-state') !== 'open');
+  });
+
+  document.addEventListener('keydown', function (event) {
+    if (event.key !== 'Escape') return;
+    var openItems = document.querySelectorAll(OPEN_SELECTOR);
+    for (var i = 0; i < openItems.length; i++) setOpen(openItems[i], false);
+  });
+})();
+`
diff --git a/src/modules/base/nav-item/props.ts b/src/modules/base/nav-item/props.ts
new file mode 100644
index 000000000..314bda8ee
--- /dev/null
+++ b/src/modules/base/nav-item/props.ts
@@ -0,0 +1,14 @@
+import { Type, type Static } from '@core/utils/typeboxHelpers'
+import { AnchorTargetSchema } from '@modules/base/shared/anchorTarget'
+import { HtmlAttributesPropSchemaOptions } from '@modules/base/shared/htmlAttributes'
+
+export const NavItemPropsSchema = Type.Object({
+  label: Type.String({ default: 'Menu item' }),
+  /** Off: the label opens this item's submenu instead of following `href`. */
+  isLink: Type.Boolean({ default: true }),
+  href: Type.String({ default: '#' }),
+  target: AnchorTargetSchema,
+  htmlAttributes: Type.Record(Type.String(), Type.String(), HtmlAttributesPropSchemaOptions),
+})
+
+export type NavItemStoredProps = Static<typeof NavItemPropsSchema>
diff --git a/src/modules/base/nav/NavEditor.tsx b/src/modules/base/nav/NavEditor.tsx
new file mode 100644
index 000000000..a48fc0219
--- /dev/null
+++ b/src/modules/base/nav/NavEditor.tsx
@@ -0,0 +1,75 @@
+/**
+ * base.nav editor preview component.
+ *
+ * Component-only file so React Fast Refresh can hot-patch edits without
+ * re-running module registration.
+ *
+ * Renders the same elements, classes, and data attributes as render().
+ * Styling comes from the module's `canvasCss` (NAV_CANVAS_CSS).
+ *
+ * When canvasViewportWidth is at or below the collapseBreakpoint prop, the
+ * nav gets `data-instatic-nav-canvas="collapsed"`. The collapsed menu opens
+ * while the nav or a node inside it is selected. The toggle button does
+ * nothing, because module JS never runs in the canvas.
+ */
+import React from 'react'
+import type { ModuleComponentProps } from '@core/module-engine'
+import { cn } from '@ui/cn'
+import { htmlAttributesForReact } from '@core/htmlAttributes'
+import { CanvasModulePlaceholder } from '@ui/components/CanvasModulePlaceholder'
+import { DockSolidIcon } from 'pixel-art-icons/icons/dock-solid'
+import { resolveNavCollapseWidth } from '@modules/base/shared/navCollapse'
+import { navToggleIconSvg } from './icons'
+import { resolveNavCollapsedStyle, resolveNavColor, type NavStoredProps } from './props'
+
+export const NavEditor: React.FC<ModuleComponentProps<NavStoredProps>> = ({
+  props, children, mcClassName, nodeWrapperProps, canvasViewportWidth,
+}) => {
+  const htmlAttrs = htmlAttributesForReact(props.htmlAttributes)
+  const hasChildren = React.Children.count(children) > 0
+  const collapseWidth = resolveNavCollapseWidth(props.collapseBreakpoint)
+  const iconColor = resolveNavColor(props.toggleIconColor)
+  const menuBackground = resolveNavColor(props.menuBackground)
+  // Unknown viewport (e.g. agent snapshot rendering) renders the desktop row.
+  const isCollapsed = canvasViewportWidth !== undefined && canvasViewportWidth <= collapseWidth
+
+  return (
+    <nav
+      {...nodeWrapperProps}
+      {...htmlAttrs}
+      className={cn('instatic-nav', mcClassName)}
+      aria-label={props.ariaLabel || undefined}
+      data-instatic-nav-canvas={isCollapsed ? 'collapsed' : undefined}
+      data-instatic-nav-mode={resolveNavCollapsedStyle(props.collapsedStyle)}
+      data-instatic-nav-align={props.menuAlign ?? 'start'}
+    >
+      <button
+        type="button"
+        className="instatic-nav__toggle"
+        style={iconColor ? { color: iconColor } : undefined}
+        tabIndex={-1}
+        aria-hidden="true"
+      >
+        <span
+          className="instatic-nav__toggle-icon"
+          dangerouslySetInnerHTML={{ __html: navToggleIconSvg(props.toggleIcon) }}
+        />
+        <span className="instatic-nav__toggle-label">{props.toggleLabel || 'Menu'}</span>
+      </button>
+      <ul
+        className="instatic-nav__menu"
+        style={menuBackground ? ({ '--instatic-nav-menu-bg': menuBackground } as React.CSSProperties) : undefined}
+      >
+        {hasChildren ? children : (
+          <li className="instatic-nav__empty">
+            <CanvasModulePlaceholder
+              variant="inline"
+              icon={<DockSolidIcon size={16} color="currentColor" />}
+              label="Add Menu Item nodes"
+            />
+          </li>
+        )}
+      </ul>
+    </nav>
+  )
+}
diff --git a/src/modules/base/nav/__tests__/nav.render.test.ts b/src/modules/base/nav/__tests__/nav.render.test.ts
new file mode 100644
index 000000000..746b55b66
--- /dev/null
+++ b/src/modules/base/nav/__tests__/nav.render.test.ts
@@ -0,0 +1,190 @@
+import { describe, expect, it } from 'bun:test'
+import { NavModule } from '../index'
+
+const baseProps = {
+  ariaLabel: 'Primary navigation',
+  toggleLabel: 'Menu',
+  collapseBreakpoint: 768,
+  collapsedStyle: 'dropdown' as const,
+  menuBackground: '',
+  toggleIcon: 'horizontal-lines' as const,
+  toggleIconColor: '',
+  menuAlign: 'start' as const,
+  htmlAttributes: {},
+}
+
+describe('base.nav render', () => {
+  it('renders the hamburger toggle + empty menu with zero children', () => {
+    const { html } = NavModule.render(baseProps as never, [])
+    expect(html).toBe(
+      '<nav class="instatic-nav" data-instatic-nav data-instatic-nav-state="closed" data-instatic-nav-collapse="768" data-instatic-nav-mode="dropdown" data-instatic-nav-align="start" aria-label="Primary navigation">'
+      + '<button type="button" class="instatic-nav__toggle" data-instatic-nav-toggle aria-expanded="false">'
+      + '<span class="instatic-nav__toggle-icon" aria-hidden="true">'
+      + '<svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M4 6h16M4 12h16M4 18h16"/></svg>'
+      + '</span>'
+      + '<span class="instatic-nav__toggle-label">Menu</span>'
+      + '</button>'
+      + '<ul class="instatic-nav__menu"></ul>'
+      + '</nav>',
+    )
+  })
+
+  it('joins renderedChildren verbatim inside the menu list', () => {
+    const { html } = NavModule.render(baseProps as never, [
+      '<li class="instatic-nav-item">A</li>',
+      '<li class="instatic-nav-item">B</li>',
+    ])
+    expect(html).toContain('<ul class="instatic-nav__menu"><li class="instatic-nav-item">A</li><li class="instatic-nav-item">B</li></ul>')
+  })
+
+  it('omits aria-label entirely when empty', () => {
+    const { html } = NavModule.render({ ...baseProps, ariaLabel: '' } as never, [])
+    expect(html).not.toContain('aria-label')
+  })
+
+  it('renders htmlAttributes onto the <nav> root', () => {
+    const { html } = NavModule.render(
+      { ...baseProps, htmlAttributes: { 'data-testid': 'site-nav' } } as never,
+      [],
+    )
+    expect(html).toContain('data-testid="site-nav"')
+  })
+
+  it('stamps the configured collapseBreakpoint and menuAlign as data attributes', () => {
+    const { html } = NavModule.render({ ...baseProps, collapseBreakpoint: 1024, menuAlign: 'center' } as never, [])
+    expect(html).toContain('data-instatic-nav-collapse="1024"')
+    expect(html).toContain('data-instatic-nav-align="center"')
+  })
+
+  it('stamps the configured collapsedStyle as the nav mode', () => {
+    const { html } = NavModule.render({ ...baseProps, collapsedStyle: 'overlay' } as never, [])
+    expect(html).toContain('data-instatic-nav-mode="overlay"')
+  })
+
+  it('renders the configured toggle icon glyph', () => {
+    const paths = {
+      'horizontal-lines': 'M4 6h16M4 12h16M4 18h16',
+      'vertical-lines': 'M6 4v16M12 4v16M18 4v16',
+      chevron: 'M6 9l6 6 6-6',
+      meatball: 'M5 12h.01M12 12h.01M19 12h.01',
+    }
+    for (const [toggleIcon, path] of Object.entries(paths)) {
+      const { html } = NavModule.render({ ...baseProps, toggleIcon } as never, [])
+      expect(html).toContain(`<path d="${path}"/>`)
+    }
+  })
+
+  it('falls back to dropdown + horizontal lines for a node stored before those props existed', () => {
+    const { collapsedStyle: _style, toggleIcon: _icon, ...legacyProps } = baseProps
+    const { html } = NavModule.render(legacyProps as never, [])
+    expect(html).toContain('data-instatic-nav-mode="dropdown"')
+    expect(html).toContain('<path d="M4 6h16M4 12h16M4 18h16"/>')
+  })
+
+  it('offers every toggle icon in the picker with its glyph and name', () => {
+    const control = NavModule.schema.toggleIcon
+    if (control.type !== 'select') throw new Error('toggleIcon must be a select control')
+    expect(control.options.map((option) => option.label)).toEqual([
+      'Horizontal lines', 'Vertical lines', 'Chevron', 'Meatball',
+    ])
+    for (const option of control.options) expect(option.iconSvg).toContain('<svg')
+  })
+
+  it('lets the menu list fill the nav so menuAlign has free space to distribute', () => {
+    const { css } = NavModule.render(baseProps as never, [])
+    expect(css).toMatch(/\.instatic-nav__menu \{\s+flex: 1 1 auto;/)
+    expect(css).toContain('[data-instatic-nav-align="end"] > .instatic-nav__menu {\n  justify-content: flex-end;')
+  })
+
+  it('keeps every media query out of the static css and ships a load-guarded JS runtime', () => {
+    const { css, js } = NavModule.render(baseProps as never, [])
+    expect(css).not.toContain('@media')
+    expect(js).toContain('window.__instaticNavRuntimeLoaded')
+  })
+
+  it('emits the collapse rules for any typed width through instanceCss, for itself and nested Menu Items', () => {
+    const { html, instanceCss } = NavModule.render({ ...baseProps, collapseBreakpoint: 913 } as never, [])
+    expect(html).toContain('data-instatic-nav-collapse="913"')
+    expect(instanceCss).toContain('@media (max-width: 913px)')
+    expect(instanceCss).toContain('.instatic-nav[data-instatic-nav-collapse="913"][data-instatic-nav-mode="dropdown"] > .instatic-nav__menu')
+    expect(instanceCss).toContain('.instatic-nav[data-instatic-nav-collapse="913"][data-instatic-nav-mode="overlay"] > .instatic-nav__menu')
+    expect(instanceCss).toContain('.instatic-nav[data-instatic-nav-collapse="913"] .instatic-nav-item > .instatic-nav-item__submenu')
+  })
+
+  it('opens the collapsed menu from the state attribute the runtime sets, and locks page scroll under an open overlay', () => {
+    const { instanceCss } = NavModule.render(baseProps as never, [])
+    expect(instanceCss).toContain(
+      '.instatic-nav[data-instatic-nav-collapse="768"][data-instatic-nav-state="open"] > .instatic-nav__menu {\n    display: flex;',
+    )
+    expect(instanceCss).toContain(
+      'html:has(.instatic-nav[data-instatic-nav-collapse="768"][data-instatic-nav-mode="overlay"][data-instatic-nav-state="open"]) {\n    overflow: hidden;',
+    )
+  })
+
+  it('accepts a width stored as a numeric string and falls back to 768 for junk', () => {
+    expect(NavModule.render({ ...baseProps, collapseBreakpoint: '1024' } as never, []).html)
+      .toContain('data-instatic-nav-collapse="1024"')
+    expect(NavModule.render({ ...baseProps, collapseBreakpoint: 'wide' } as never, []).html)
+      .toContain('data-instatic-nav-collapse="768"')
+  })
+
+  it('instanceCss depends on the collapse width alone', () => {
+    const a = NavModule.render(baseProps as never, [])
+    const b = NavModule.render(
+      { ...baseProps, menuAlign: 'end', collapsedStyle: 'overlay', menuBackground: '#000000', toggleIcon: 'chevron' } as never,
+      [],
+    )
+    expect(a.instanceCss).toBe(b.instanceCss)
+  })
+
+  it('offers collapse presets on a free-form number control', () => {
+    const control = NavModule.schema.collapseBreakpoint
+    if (control.type !== 'number') throw new Error('collapseBreakpoint must be a number control')
+    expect(control.presets).toEqual([640, 768, 1024])
+  })
+
+  it('carries the menu background on the menu list in both collapsed styles, and nothing when empty', () => {
+    for (const collapsedStyle of ['dropdown', 'overlay']) {
+      const { html } = NavModule.render({ ...baseProps, collapsedStyle, menuBackground: '#112233' } as never, [])
+      expect(html).toContain('<ul class="instatic-nav__menu" style="--instatic-nav-menu-bg:#112233">')
+    }
+    expect(NavModule.render(baseProps as never, []).html).toContain('<ul class="instatic-nav__menu">')
+  })
+
+  it('drops a menu background that carries extra declarations', () => {
+    const { html } = NavModule.render(
+      { ...baseProps, menuBackground: 'red;position:absolute' } as never,
+      [],
+    )
+    expect(html).toContain('<ul class="instatic-nav__menu">')
+  })
+
+  it('paints its collapsed panels from the menu background, with no hardcoded colour', () => {
+    const { css, instanceCss } = NavModule.render(baseProps as never, [])
+    const sheet = `${css}${instanceCss}`
+    expect(sheet).not.toMatch(/#[0-9a-f]{3,8}\b/i)
+    for (const mode of ['dropdown', 'overlay']) {
+      const rule = new RegExp(
+        `\\[data-instatic-nav-mode="${mode}"\\] > \\.instatic-nav__menu \\{[^}]*background-color: var\\(--instatic-nav-menu-bg, Canvas\\);`,
+      )
+      expect(sheet).toMatch(rule)
+    }
+  })
+
+  it('colours the menu icon through the toggle button, and inherits when empty', () => {
+    const coloured = NavModule.render({ ...baseProps, toggleIconColor: '#ff0000' } as never, [])
+    expect(coloured.html).toContain('data-instatic-nav-toggle aria-expanded="false" style="color:#ff0000">')
+    const inherited = NavModule.render(baseProps as never, [])
+    expect(inherited.html).toContain('data-instatic-nav-toggle aria-expanded="false">')
+  })
+
+  it('css and js are prop-independent (required by per-moduleId dedup, first-render-wins) even across different collapseBreakpoint/menuAlign values', () => {
+    const a = NavModule.render(baseProps as never, [])
+    const b = NavModule.render(
+      { ...baseProps, ariaLabel: 'Different', collapseBreakpoint: 1024, menuAlign: 'end', collapsedStyle: 'overlay', toggleIcon: 'chevron' } as never,
+      ['<li>x</li>'],
+    )
+    expect(a.css).toBe(b.css)
+    expect(a.js).toBe(b.js)
+  })
+})
diff --git a/src/modules/base/nav/icons.ts b/src/modules/base/nav/icons.ts
new file mode 100644
index 000000000..c0a64bda3
--- /dev/null
+++ b/src/modules/base/nav/icons.ts
@@ -0,0 +1,23 @@
+/**
+ * Inline SVG glyphs for the nav toggle button. Embedded directly because
+ * vendored pixel-art-icons cannot be inlined into publisher HTML. Shared by
+ * render(), the "Menu icon" picker, and NavEditor.tsx.
+ */
+function strokeIcon(path: string, strokeWidth = 2): string {
+  return `<svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="${strokeWidth}" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="${path}"/></svg>`
+}
+
+export const NAV_TOGGLE_ICONS = [
+  { value: 'horizontal-lines', label: 'Horizontal lines', svg: strokeIcon('M4 6h16M4 12h16M4 18h16') },
+  { value: 'vertical-lines', label: 'Vertical lines', svg: strokeIcon('M6 4v16M12 4v16M18 4v16') },
+  { value: 'chevron', label: 'Chevron', svg: strokeIcon('M6 9l6 6 6-6') },
+  // Zero-length segments with round caps draw as dots.
+  { value: 'meatball', label: 'Meatball', svg: strokeIcon('M5 12h.01M12 12h.01M19 12h.01', 3) },
+] as const
+
+export type NavToggleIcon = (typeof NAV_TOGGLE_ICONS)[number]['value']
+
+/** Unknown values (a node stored before the prop existed) fall back to the first glyph. */
+export function navToggleIconSvg(value: unknown): string {
+  return (NAV_TOGGLE_ICONS.find((icon) => icon.value === value) ?? NAV_TOGGLE_ICONS[0]).svg
+}
diff --git a/src/modules/base/nav/index.ts b/src/modules/base/nav/index.ts
new file mode 100644
index 000000000..8835f232b
--- /dev/null
+++ b/src/modules/base/nav/index.ts
@@ -0,0 +1,139 @@
+/**
+ * base.nav: collapsible navigation wrapper.
+ *
+ * Renders a <nav> with a menu toggle button and a <ul> of children. Nested
+ * base.nav-item nodes are the menu, so the page tree is the menu structure.
+ * Below the configured width it collapses into a dropdown or full-screen
+ * overlay, driven by its own CSS and module-JS runtime. Works anywhere on the
+ * page, not only in a header.
+ */
+import type { ModuleDefinition } from '@core/module-engine'
+import { registry } from '@core/module-engine'
+import { Value } from '@core/utils/typeboxHelpers'
+import { DockSolidIcon } from 'pixel-art-icons/icons/dock-solid'
+import {
+  htmlAttributesControl,
+} from '@modules/base/shared/htmlAttributes'
+import { htmlAttributesAttr } from '@core/publisher'
+import { NAV_COLLAPSE_PRESETS, resolveNavCollapseWidth } from '@modules/base/shared/navCollapse'
+import { navItemCollapseCss } from '@modules/base/nav-item/navItemCss'
+import { NAV_TOGGLE_ICONS, navToggleIconSvg } from './icons'
+import { NAV_CANVAS_CSS, NAV_CSS, navCollapseCss } from './navCss'
+import { NAV_RUNTIME_JS } from './navRuntimeJs'
+import { NavEditor } from './NavEditor'
+import {
+  NAV_COLLAPSED_STYLES,
+  NAV_MENU_ALIGNMENTS,
+  NavPropsSchema,
+  resolveNavCollapsedStyle,
+  resolveNavColor,
+  type NavStoredProps,
+} from './props'
+
+export const NavModule: ModuleDefinition<NavStoredProps> = {
+  id: 'base.nav',
+  name: 'Header Navigation',
+  description: 'A collapsible nav bar. Nest Menu Item nodes inside to build the menu.',
+  category: 'Navigation',
+  version: '1.0.0',
+  icon: DockSolidIcon,
+  trusted: true,
+  canHaveChildren: true,
+
+  schema: {
+    ariaLabel: {
+      type: 'text',
+      label: 'Accessible name',
+      description: 'Read by screen readers to tell this landmark apart from other nav regions on the page (e.g. a footer nav).',
+    },
+    toggleLabel: {
+      type: 'text',
+      label: 'Menu button label',
+      description: 'Screen-reader-only text for the collapsed menu button.',
+    },
+    collapseBreakpoint: {
+      type: 'number',
+      label: 'Collapse below',
+      description: 'Viewport width at which the menu button takes over from the normal row. Pick a preset or type any width; 0 never collapses.',
+      min: 0,
+      unit: 'px',
+      presets: NAV_COLLAPSE_PRESETS,
+    },
+    collapsedStyle: {
+      type: 'select',
+      label: 'Collapsed menu',
+      description: 'Dropdown opens a panel under the nav. Overlay covers the whole screen.',
+      options: NAV_COLLAPSED_STYLES.map((value) => ({
+        value,
+        label: value === 'dropdown' ? 'Dropdown' : 'Overlay',
+      })),
+    },
+    menuBackground: {
+      type: 'color',
+      label: 'Menu background',
+      description: "Background of the collapsed menu and of submenus. Leave empty to use the browser's default page background.",
+    },
+    toggleIcon: {
+      type: 'select',
+      label: 'Menu icon',
+      options: NAV_TOGGLE_ICONS.map(({ value, label, svg }) => ({ value, label, iconSvg: svg })),
+    },
+    toggleIconColor: {
+      type: 'color',
+      label: 'Menu icon color',
+      description: 'Leave empty to use the surrounding text color.',
+    },
+    menuAlign: {
+      type: 'select',
+      label: 'Menu alignment',
+      description: 'Where the menu items sit inside the nav bar. When collapsed, where the menu button sits.',
+      layout: 'inline',
+      options: NAV_MENU_ALIGNMENTS.map((value) => ({
+        value,
+        label: value === 'start' ? 'Start' : value === 'center' ? 'Center' : 'End',
+      })),
+    },
+    htmlAttributes: htmlAttributesControl(),
+  },
+
+  propsSchema: NavPropsSchema,
+
+  defaults: Value.Create(NavPropsSchema),
+
+  component: NavEditor,
+
+  canvasCss: NAV_CANVAS_CSS,
+
+  htmlTag: 'nav',
+
+  render: (props, renderedChildren) => {
+    const attrs = htmlAttributesAttr(props.htmlAttributes)
+    const ariaLabel = String(props.ariaLabel ?? '')
+    const toggleLabel = String(props.toggleLabel ?? '')
+    const ariaLabelAttr = ariaLabel ? ` aria-label="${ariaLabel}"` : ''
+    const collapseBreakpoint = resolveNavCollapseWidth(props.collapseBreakpoint)
+    const menuAlign = String(props.menuAlign ?? 'start')
+    const collapsedStyle = resolveNavCollapsedStyle(props.collapsedStyle)
+    const menuBackground = resolveNavColor(props.menuBackground)
+    const iconColor = resolveNavColor(props.toggleIconColor)
+    const toggleStyleAttr = iconColor ? ` style="color:${iconColor}"` : ''
+    // On the list, not the <nav>: submenus inside it inherit the property.
+    const menuStyleAttr = menuBackground ? ` style="--instatic-nav-menu-bg:${menuBackground}"` : ''
+
+    const html =
+      `<nav class="instatic-nav" data-instatic-nav data-instatic-nav-state="closed" data-instatic-nav-collapse="${collapseBreakpoint}" data-instatic-nav-mode="${collapsedStyle}" data-instatic-nav-align="${menuAlign}"${attrs}${ariaLabelAttr}>`
+      + `<button type="button" class="instatic-nav__toggle" data-instatic-nav-toggle aria-expanded="false"${toggleStyleAttr}>`
+      +   `<span class="instatic-nav__toggle-icon" aria-hidden="true">${navToggleIconSvg(props.toggleIcon)}</span>`
+      +   `<span class="instatic-nav__toggle-label">${toggleLabel}</span>`
+      + `</button>`
+      + `<ul class="instatic-nav__menu"${menuStyleAttr}>${renderedChildren.join('')}</ul>`
+      + `</nav>`
+
+    // Collapse rules at this instance's width, for the nav and its Menu Items.
+    const instanceCss = navCollapseCss(collapseBreakpoint) + navItemCollapseCss(collapseBreakpoint)
+
+    return { html, css: NAV_CSS, instanceCss, js: NAV_RUNTIME_JS }
+  },
+}
+
+registry.registerOrReplace(NavModule)
diff --git a/src/modules/base/nav/navCss.ts b/src/modules/base/nav/navCss.ts
new file mode 100644
index 000000000..95e4e35e0
--- /dev/null
+++ b/src/modules/base/nav/navCss.ts
@@ -0,0 +1,138 @@
+/**
+ * CSS for base.nav.
+ *
+ * NAV_CSS: static rules, emitted once per module type.
+ * navCollapseCss(width): the collapsed layout, emitted through `instanceCss`.
+ * NAV_CANVAS_CSS: the module's `canvasCss`, the same rules with the canvas
+ * selectors. See shared/navCollapse.ts.
+ *
+ * Menu panels read their background from `--instatic-nav-menu-bg`, which
+ * render() sets from the "Menu background" prop. Unset, they use the `Canvas`
+ * system colour.
+ */
+import { NAV_CANVAS_COLLAPSED, NAV_CANVAS_OPEN } from '@modules/base/shared/navCollapse'
+
+const NAV_OPEN = '[data-instatic-nav-state="open"]'
+
+/** The collapsed layout for the nav matched by `scope`, opened when it also matches `open`. */
+function navCollapseRules(scope: string, open: string): string {
+  return `
+  ${scope} > .instatic-nav__toggle {
+    display: inline-flex;
+  }
+  ${scope}[data-instatic-nav-align="center"] {
+    justify-content: center;
+  }
+  ${scope}[data-instatic-nav-align="end"] {
+    justify-content: flex-end;
+  }
+  ${scope} > .instatic-nav__menu {
+    display: none;
+    flex-direction: column;
+    align-items: stretch;
+    gap: 0;
+    width: 100%;
+  }
+  ${scope}${open} > .instatic-nav__menu {
+    display: flex;
+  }
+  ${scope}[data-instatic-nav-mode="dropdown"] > .instatic-nav__menu {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    width: auto;
+    min-width: max(100%, 200px);
+    background-color: var(--instatic-nav-menu-bg, Canvas);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
+    z-index: 30;
+  }
+  ${scope}[data-instatic-nav-mode="dropdown"][data-instatic-nav-align="end"] > .instatic-nav__menu {
+    left: auto;
+    right: 0;
+  }
+  ${scope}[data-instatic-nav-mode="overlay"] > .instatic-nav__menu {
+    position: fixed;
+    inset: 0;
+    width: auto;
+    box-sizing: border-box;
+    padding: 64px 24px 24px;
+    overflow-y: auto;
+    background-color: var(--instatic-nav-menu-bg, Canvas);
+    z-index: 1000;
+  }
+  ${scope}[data-instatic-nav-mode="overlay"]${open} > .instatic-nav__toggle {
+    position: relative;
+    z-index: 1001;
+  }`
+}
+
+export function navCollapseCss(width: number): string {
+  const scope = `.instatic-nav[data-instatic-nav-collapse="${width}"]`
+  return `
+@media (max-width: ${width}px) {${navCollapseRules(scope, NAV_OPEN)}
+  html:has(${scope}[data-instatic-nav-mode="overlay"]${NAV_OPEN}) {
+    overflow: hidden;
+  }
+}`
+}
+
+export const NAV_CSS = `
+.instatic-nav {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+.instatic-nav__toggle {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  background: none;
+  border: 0;
+  padding: 8px;
+  cursor: pointer;
+  color: inherit;
+}
+.instatic-nav__toggle-icon {
+  display: inline-flex;
+  width: 20px;
+  height: 20px;
+}
+.instatic-nav__toggle-label {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+.instatic-nav__menu {
+  flex: 1 1 auto;
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  gap: 8px;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.instatic-nav[data-instatic-nav-align="center"] > .instatic-nav__menu {
+  justify-content: center;
+}
+.instatic-nav[data-instatic-nav-align="end"] > .instatic-nav__menu {
+  justify-content: flex-end;
+}
+`
+
+// A canvas frame is as tall as the whole page, so the published `inset: 0`
+// overlay would cover every other node. Cap it at one viewport height.
+export const NAV_CANVAS_CSS = `${NAV_CSS}${navCollapseRules(NAV_CANVAS_COLLAPSED, NAV_CANVAS_OPEN)}
+  ${NAV_CANVAS_COLLAPSED}[data-instatic-nav-mode="overlay"] > .instatic-nav__menu {
+    inset: 0 0 auto;
+    height: 100vh;
+  }
+`
diff --git a/src/modules/base/nav/navRuntimeJs.ts b/src/modules/base/nav/navRuntimeJs.ts
new file mode 100644
index 000000000..0c98c4591
--- /dev/null
+++ b/src/modules/base/nav/navRuntimeJs.ts
@@ -0,0 +1,54 @@
+/**
+ * Module-JS runtime for base.nav: opens and closes the collapsed menu.
+ *
+ * A self-contained IIFE with a load guard, bound through document-level
+ * event delegation (the RenderOutput.js contract).
+ *
+ * Handlers find their nav with .closest(), so several base.nav instances on
+ * one page stay independent.
+ */
+export const NAV_RUNTIME_JS = `(() => {
+  if (window.__instaticNavRuntimeLoaded) return;
+  window.__instaticNavRuntimeLoaded = true;
+
+  var NAV_SELECTOR = '[data-instatic-nav]';
+  var TOGGLE_SELECTOR = '[data-instatic-nav-toggle]';
+
+  function setOpen(nav, open) {
+    nav.setAttribute('data-instatic-nav-state', open ? 'open' : 'closed');
+    var toggle = nav.querySelector(TOGGLE_SELECTOR);
+    if (toggle) toggle.setAttribute('aria-expanded', open ? 'true' : 'false');
+  }
+
+  document.addEventListener('click', function (event) {
+    var target = event.target;
+    var toggle = target && target.closest ? target.closest(TOGGLE_SELECTOR) : null;
+    if (toggle) {
+      var nav = toggle.closest(NAV_SELECTOR);
+      if (nav) setOpen(nav, nav.getAttribute('data-instatic-nav-state') !== 'open');
+      return;
+    }
+    var link = target && target.closest ? target.closest('a[href]') : null;
+    var openNavs = document.querySelectorAll(NAV_SELECTOR + '[data-instatic-nav-state="open"]');
+    for (var i = 0; i < openNavs.length; i++) {
+      var openNav = openNavs[i];
+      if (!openNav.contains(target)) {
+        setOpen(openNav, false); // outside click
+      } else if (link && openNav.contains(link)) {
+        setOpen(openNav, false); // link clicked inside
+      }
+    }
+  });
+
+  document.addEventListener('keydown', function (event) {
+    if (event.key !== 'Escape') return;
+    var openNavs = document.querySelectorAll(NAV_SELECTOR + '[data-instatic-nav-state="open"]');
+    for (var i = 0; i < openNavs.length; i++) {
+      var openNav = openNavs[i];
+      setOpen(openNav, false);
+      var toggle = openNav.querySelector(TOGGLE_SELECTOR);
+      if (toggle) toggle.focus();
+    }
+  });
+})();
+`
diff --git a/src/modules/base/nav/props.ts b/src/modules/base/nav/props.ts
new file mode 100644
index 000000000..7992ce858
--- /dev/null
+++ b/src/modules/base/nav/props.ts
@@ -0,0 +1,60 @@
+import { Type, type Static } from '@core/utils/typeboxHelpers'
+import { HtmlAttributesPropSchemaOptions } from '@modules/base/shared/htmlAttributes'
+import { NAV_COLLAPSE_DEFAULT } from '@modules/base/shared/navCollapse'
+import { NAV_TOGGLE_ICONS } from './icons'
+
+/** Viewport width in px at or below which the nav collapses. */
+export const NavCollapseBreakpointSchema = Type.Number({ default: NAV_COLLAPSE_DEFAULT, minimum: 0 })
+
+export const NAV_MENU_ALIGNMENTS = ['start', 'center', 'end'] as const
+export const NavMenuAlignSchema = Type.Union(
+  NAV_MENU_ALIGNMENTS.map((align) => Type.Literal(align)),
+  { default: 'start' },
+)
+
+/**
+ * How the collapsed menu opens: `dropdown` is a panel anchored under the nav,
+ * `overlay` covers the whole viewport.
+ */
+export const NAV_COLLAPSED_STYLES = ['dropdown', 'overlay'] as const
+export type NavCollapsedStyle = (typeof NAV_COLLAPSED_STYLES)[number]
+export const NavCollapsedStyleSchema = Type.Union(
+  NAV_COLLAPSED_STYLES.map((style) => Type.Literal(style)),
+  { default: 'dropdown' },
+)
+
+export const NavToggleIconSchema = Type.Union(
+  NAV_TOGGLE_ICONS.map((icon) => Type.Literal(icon.value)),
+  { default: 'horizontal-lines' },
+)
+
+export const NavPropsSchema = Type.Object({
+  ariaLabel: Type.String({ default: 'Primary navigation' }),
+  toggleLabel: Type.String({ default: 'Menu' }),
+  collapseBreakpoint: NavCollapseBreakpointSchema,
+  collapsedStyle: NavCollapsedStyleSchema,
+  /** Background of the collapsed menu and of submenus. Empty uses the `Canvas` system colour. */
+  menuBackground: Type.String({ default: '' }),
+  toggleIcon: NavToggleIconSchema,
+  /** Empty inherits the surrounding text colour. */
+  toggleIconColor: Type.String({ default: '' }),
+  menuAlign: NavMenuAlignSchema,
+  htmlAttributes: Type.Record(Type.String(), Type.String(), HtmlAttributesPropSchemaOptions),
+})
+
+export type NavStoredProps = Static<typeof NavPropsSchema>
+
+/** Unknown values (a node stored before the prop existed) fall back to `dropdown`. */
+export function resolveNavCollapsedStyle(value: unknown): NavCollapsedStyle {
+  return value === 'overlay' ? 'overlay' : 'dropdown'
+}
+
+/**
+ * An authored colour as a value safe to place in a `style` attribute.
+ * Returns null when it is empty or is not a plain colour (hex, rgb()/hsl(),
+ * var(--token), or a keyword), so a stored value cannot add declarations.
+ */
+export function resolveNavColor(value: unknown): string | null {
+  const color = String(value ?? '').trim()
+  return /^[\w#(),.%/\s-]+$/.test(color) ? color : null
+}
diff --git a/src/modules/base/shared/navCollapse.ts b/src/modules/base/shared/navCollapse.ts
new file mode 100644
index 000000000..5850d45ad
--- /dev/null
+++ b/src/modules/base/shared/navCollapse.ts
@@ -0,0 +1,29 @@
+/**
+ * Collapse settings shared by base.nav and base.nav-item.
+ *
+ * The collapse width is a base.nav prop, so base.nav emits the collapse rules
+ * for itself and its Menu Items through `instanceCss`, scoped by
+ * `[data-instatic-nav-collapse="<width>"]`.
+ *
+ * Both modules build those rules from a `scope` selector (which nav is
+ * collapsed) and an `open` selector (what counts as opened). The canvas runs
+ * no module JS and no media queries at the frame's width, so `canvasCss`
+ * reuses the same rules with the two canvas selectors below.
+ */
+export const NAV_COLLAPSE_PRESETS = [640, 768, 1024]
+export const NAV_COLLAPSE_DEFAULT = 768
+
+/** Canvas `scope`: NavEditor stamps this on a nav in a frame at or below its collapse width. */
+export const NAV_CANVAS_COLLAPSED = '.instatic-nav[data-instatic-nav-canvas="collapsed"]'
+
+/**
+ * Canvas `open`: the element or a node inside it is selected. Selection
+ * replaces the toggle click, so nested Menu Items stay editable.
+ */
+export const NAV_CANVAS_OPEN = ':is([data-canvas-selected="true"], :has([data-canvas-selected="true"]))'
+
+/** Rounds to a whole pixel width. Negative or non-numeric values use the default. 0 never collapses. */
+export function resolveNavCollapseWidth(value: unknown): number {
+  const width = Math.round(Number(value))
+  return Number.isFinite(width) && width >= 0 ? width : NAV_COLLAPSE_DEFAULT
+}

From 4cb5b51002b6b306aabbf23f0dab68944f641981 Mon Sep 17 00:00:00 2001
From: Quynn Bell <quynnbell@protonmail.com>
Date: Mon, 12 Oct 2026 10:34:09 -0700
Subject: [PATCH 2/7] feat(publisher): emit per-instance module CSS

- Collect instanceCss from render() and deduplicate it by content
- Header navigation: lets the nav publish the media query at its own collapse width, so a published menu actually collapses
---
 src/__tests__/publisher/render.test.ts | 30 ++++++++++++++++++++++++++
 src/core/publisher/renderNode.ts       |  8 +++++++
 2 files changed, 38 insertions(+)

diff --git a/src/__tests__/publisher/render.test.ts b/src/__tests__/publisher/render.test.ts
index 7f7fddf3d..b52bb4988 100644
--- a/src/__tests__/publisher/render.test.ts
+++ b/src/__tests__/publisher/render.test.ts
@@ -242,6 +242,36 @@ describe('renderNode', () => {
     expect(acc.cssMap.get('base.text')).toBe('h1,h2,h3,h4,h5,h6 { font-family: sans-serif; }')
   })
 
+  it('collects instanceCss by content, so same props share a block and different props each get one', () => {
+    const widthRegistry = makeRegistry({
+      'test.width': makeModule('test.width', {
+        render: (props) => ({
+          html: '<div></div>',
+          css: '.w { display: flex; }',
+          instanceCss: `@media (max-width: ${String(props.width)}px) { .w { display: none; } }`,
+        }),
+      }),
+      'test.box': makeModule('test.box', {
+        canHaveChildren: true,
+        render: (_props, children) => ({ html: `<div>${children.join('')}</div>` }),
+      }),
+    })
+    const page = makePage({
+      root: { moduleId: 'test.box', props: {}, children: ['a', 'b', 'c'] },
+      a: { moduleId: 'test.width', props: { width: 600 } },
+      b: { moduleId: 'test.width', props: { width: 600 } },
+      c: { moduleId: 'test.width', props: { width: 900 } },
+    })
+    const acc = makeAccumulators()
+    render('root', { page, site, registry: widthRegistry, breakpointId: undefined }, acc)
+    const sheet = Array.from(acc.cssMap.values())
+    expect(sheet).toEqual([
+      '.w { display: flex; }',
+      '@media (max-width: 600px) { .w { display: none; } }',
+      '@media (max-width: 900px) { .w { display: none; } }',
+    ])
+  })
+
   it('returns empty string for missing nodeId', () => {
     const page = makePage({ root: { moduleId: 'base.text', props: {} } })
     const c = ctx(page)
diff --git a/src/core/publisher/renderNode.ts b/src/core/publisher/renderNode.ts
index e54aec67e..becf93afa 100644
--- a/src/core/publisher/renderNode.ts
+++ b/src/core/publisher/renderNode.ts
@@ -170,6 +170,14 @@ function renderStandardNode(
     acc.cssMap.set(node.moduleId, sanitizeModuleCSS(output.css))
   }
 
+  // Instance CSS: keyed by content so instances with different props all emit.
+  if (output.instanceCss) {
+    const instanceKey = `${node.moduleId}\n${output.instanceCss}`
+    if (!acc.cssMap.has(instanceKey)) {
+      acc.cssMap.set(instanceKey, sanitizeModuleCSS(output.instanceCss))
+    }
+  }
+
   // JS dedup — one entry per moduleId, mirroring CSS. No escaping needed:
   // module JS is served as an external file (`/_instatic/module-js/<id>.js`),
   // never inlined into the document.

From ca0449a873b04eb03c92423c821771a4f7d66bfa Mon Sep 17 00:00:00 2001
From: Quynn Bell <quynnbell@protonmail.com>
Date: Mon, 12 Oct 2026 10:35:47 -0700
Subject: [PATCH 3/7] feat(editor): add number presets and icon options to
 property controls

- Show presets as one-click buttons under a number field
- Render a select whose options carry an icon as an icon button row
- Sanitize the icon markup, since a plugin schema can supply it
- Expose both options through the plugin SDK control builders
- Header navigation: gives the nav its "Collapse below" width presets and its "Menu icon" picker
---
 .../numberPresetsAndSelectIcons.test.tsx      | 135 ++++++++++++++++++
 .../site/property-controls/NumberControl.tsx  |  49 +++++--
 .../PropertyControlRenderer.tsx               |   1 +
 .../site/property-controls/SelectControl.tsx  |  40 ++++++
 .../property-controls/controls.module.css     |  20 +++
 src/core/plugin-sdk/builders/controls.ts      |   4 +-
 src/core/plugin-sdk/modules.ts                |   4 +-
 7 files changed, 235 insertions(+), 18 deletions(-)
 create mode 100644 src/__tests__/property-controls/numberPresetsAndSelectIcons.test.tsx

diff --git a/src/__tests__/property-controls/numberPresetsAndSelectIcons.test.tsx b/src/__tests__/property-controls/numberPresetsAndSelectIcons.test.tsx
new file mode 100644
index 000000000..394011a1f
--- /dev/null
+++ b/src/__tests__/property-controls/numberPresetsAndSelectIcons.test.tsx
@@ -0,0 +1,135 @@
+/**
+ * Two schema-driven control variants:
+ *   - a `number` control with `presets` shows one-click preset buttons under
+ *     the field, which still accepts any number
+ *   - a `select` control whose options carry `iconSvg` renders as an icon
+ *     button row instead of a dropdown.
+ */
+import { afterEach, describe, expect, it } from 'bun:test'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { PropertyControlRenderer } from '@site/property-controls/PropertyControlRenderer'
+import type { PropertyControl } from '@core/module-engine'
+
+afterEach(cleanup)
+
+const ICON_A = '<svg viewBox="0 0 24 24"><path d="M4 6h16"/></svg>'
+const ICON_B = '<svg viewBox="0 0 24 24"><path d="M6 4v16"/></svg>'
+
+function renderControl(control: PropertyControl, value: unknown) {
+  const changes: Array<[string, unknown]> = []
+  const view = render(
+    <PropertyControlRenderer
+      propKey="myProp"
+      control={control}
+      value={value}
+      onChange={(key, next) => changes.push([key, next])}
+    />,
+  )
+  return { changes, ...view }
+}
+
+describe('number control presets', () => {
+  const control: PropertyControl = { type: 'number', label: 'Collapse below', presets: [640, 768, 1024] }
+
+  it('renders one button per preset, in order, next to the number field', () => {
+    renderControl(control, 768)
+    const group = screen.getByRole('group', { name: 'Collapse below presets' })
+    const buttons = Array.from(group.querySelectorAll('button'))
+    expect(buttons.map((button) => button.textContent)).toEqual(['640', '768', '1024'])
+    expect(screen.getByRole('spinbutton')).toHaveProperty('value', '768')
+  })
+
+  it('marks the preset matching the current value as pressed, and none for a custom value', () => {
+    const { unmount } = renderControl(control, 768)
+    const pressed = () =>
+      Array.from(screen.getByRole('group').querySelectorAll('button[aria-pressed="true"]')).map((b) => b.textContent)
+    expect(pressed()).toEqual(['768'])
+    unmount()
+
+    renderControl(control, 913)
+    expect(pressed()).toEqual([])
+  })
+
+  it('writes the preset as a number when its button is clicked', () => {
+    const { changes } = renderControl(control, 768)
+    fireEvent.click(screen.getByRole('button', { name: '1024' }))
+    expect(changes).toEqual([['myProp', 1024]])
+  })
+
+  it('still accepts any typed number', () => {
+    const { changes } = renderControl(control, 768)
+    fireEvent.change(screen.getByRole('spinbutton'), { target: { value: '913' } })
+    expect(changes).toEqual([['myProp', 913]])
+  })
+
+  it('renders no preset group when the control has no presets', () => {
+    renderControl({ type: 'number', label: 'Width' }, 10)
+    expect(screen.queryByRole('group')).toBeNull()
+    renderControl({ type: 'number', label: 'Width', presets: [] }, 10)
+    expect(screen.queryByRole('group')).toBeNull()
+  })
+})
+
+describe('select control icon row', () => {
+  const control: PropertyControl = {
+    type: 'select',
+    label: 'Menu icon',
+    options: [
+      { value: 'horizontal-lines', label: 'Horizontal lines', iconSvg: ICON_A },
+      { value: 'vertical-lines', label: 'Vertical lines', iconSvg: ICON_B },
+    ],
+  }
+
+  it('renders an icon button per option instead of a dropdown, named by the option label', () => {
+    const { container } = renderControl(control, 'horizontal-lines')
+    expect(container.querySelector('select')).toBeNull()
+    const first = screen.getByRole('button', { name: 'Horizontal lines' })
+    const second = screen.getByRole('button', { name: 'Vertical lines' })
+    expect(first.querySelector('svg path')?.getAttribute('d')).toBe('M4 6h16')
+    expect(second.querySelector('svg path')?.getAttribute('d')).toBe('M6 4v16')
+    expect(first.getAttribute('aria-pressed')).toBe('true')
+    expect(second.getAttribute('aria-pressed')).toBe('false')
+  })
+
+  it('writes the clicked option value', () => {
+    const { changes } = renderControl(control, 'horizontal-lines')
+    fireEvent.click(screen.getByRole('button', { name: 'Vertical lines' }))
+    expect(changes).toEqual([['myProp', 'vertical-lines']])
+  })
+
+  it('writes the original value type, not its string form', () => {
+    const numeric: PropertyControl = {
+      type: 'select',
+      label: 'Columns',
+      options: [
+        { value: 1, label: 'One', iconSvg: ICON_A },
+        { value: 2, label: 'Two', iconSvg: ICON_B },
+      ],
+    }
+    const { changes } = renderControl(numeric, 1)
+    fireEvent.click(screen.getByRole('button', { name: 'Two' }))
+    expect(changes).toEqual([['myProp', 2]])
+  })
+
+  it('sanitises the icon markup, since a plugin schema can supply it', () => {
+    const hostile: PropertyControl = {
+      type: 'select',
+      label: 'Icon',
+      options: [{ value: 'a', label: 'A', iconSvg: '<svg onload="alert(1)"><script>alert(1)</script><path d="M0 0"/></svg>' }],
+    }
+    const { container } = renderControl(hostile, 'a')
+    expect(container.querySelector('script')).toBeNull()
+    expect(container.innerHTML).not.toContain('onload')
+    expect(container.querySelector('svg path')).not.toBeNull()
+  })
+
+  it('keeps the dropdown when no option has an icon', () => {
+    const plain: PropertyControl = {
+      type: 'select',
+      label: 'Target',
+      options: [{ value: '_self', label: 'Same tab' }, { value: '_blank', label: 'New tab' }],
+    }
+    const { container } = renderControl(plain, '_self')
+    expect(container.querySelector('select')).not.toBeNull()
+  })
+})
diff --git a/src/admin/pages/site/property-controls/NumberControl.tsx b/src/admin/pages/site/property-controls/NumberControl.tsx
index c69b44fe7..9fd1d3073 100644
--- a/src/admin/pages/site/property-controls/NumberControl.tsx
+++ b/src/admin/pages/site/property-controls/NumberControl.tsx
@@ -1,6 +1,8 @@
 import type { ControlProps } from './shared'
 import { Input } from '@ui/components/Input'
 import { ControlRow } from '@ui/components/ControlRow'
+import { SegmentedControl } from '@ui/components/SegmentedControl'
+import styles from './controls.module.css'
 import controlRowStyles from '@ui/components/ControlRow/ControlRow.module.css'
 
 interface NumberControlProps extends ControlProps<number> {
@@ -8,6 +10,8 @@ interface NumberControlProps extends ControlProps<number> {
   max?: number
   step?: number
   unit?: string
+  /** Suggested values offered as buttons under the field. */
+  presets?: number[]
 }
 
 export function NumberControl({
@@ -19,10 +23,28 @@ export function NumberControl({
   max,
   step = 1,
   unit,
+  presets,
   isOverride,
   disabled,
   layout,
 }: NumberControlProps) {
+  const input = (
+    <Input
+      id={`ctrl-${propKey}`}
+      type="number"
+      value={value ?? 0}
+      min={min}
+      max={max}
+      step={step}
+      disabled={disabled}
+      fieldSize="sm"
+      onChange={(e) => {
+        const v = e.target.valueAsNumber
+        if (!isNaN(v)) onChange(propKey, v)
+      }}
+    />
+  )
+
   return (
     <ControlRow
       propKey={propKey}
@@ -32,20 +54,19 @@ export function NumberControl({
       disabled={disabled}
       labelSuffix={unit ? <span className={controlRowStyles.labelUnit}>{unit}</span> : undefined}
     >
-      <Input
-        id={`ctrl-${propKey}`}
-        type="number"
-        value={value ?? 0}
-        min={min}
-        max={max}
-        step={step}
-        disabled={disabled}
-        fieldSize="sm"
-        onChange={(e) => {
-          const v = e.target.valueAsNumber
-          if (!isNaN(v)) onChange(propKey, v)
-        }}
-      />
+      {presets && presets.length > 0 ? (
+        <div className={styles.numberWithPresets}>
+          {input}
+          <SegmentedControl
+            aria-label={`${label ?? propKey} presets`}
+            value={presets.includes(value) ? String(value) : undefined}
+            options={presets.map((preset) => ({ value: String(preset), label: String(preset) }))}
+            onChange={(next) => onChange(propKey, Number(next))}
+            disabled={disabled}
+            fullWidth
+          />
+        </div>
+      ) : input}
     </ControlRow>
   )
 }
diff --git a/src/admin/pages/site/property-controls/PropertyControlRenderer.tsx b/src/admin/pages/site/property-controls/PropertyControlRenderer.tsx
index 4bcaae772..6ec595bbb 100644
--- a/src/admin/pages/site/property-controls/PropertyControlRenderer.tsx
+++ b/src/admin/pages/site/property-controls/PropertyControlRenderer.tsx
@@ -164,6 +164,7 @@ export function PropertyControlRenderer({
           max={control.max}
           step={control.step}
           unit={control.unit}
+          presets={control.presets}
         />
       )
       break
diff --git a/src/admin/pages/site/property-controls/SelectControl.tsx b/src/admin/pages/site/property-controls/SelectControl.tsx
index 64b0f3855..c9186f2d1 100644
--- a/src/admin/pages/site/property-controls/SelectControl.tsx
+++ b/src/admin/pages/site/property-controls/SelectControl.tsx
@@ -1,12 +1,17 @@
 import { useEffect } from 'react'
 import type { ControlProps } from './shared'
 import { Select } from '@ui/components/Select'
+import { SegmentedControl } from '@ui/components/SegmentedControl'
 import { ControlRow } from '@ui/components/ControlRow'
 import { useEditorPreference } from '@site/preferences/editorPreferences'
+import { sanitizeSvg } from '@core/sanitize'
+import styles from './controls.module.css'
 
 interface SelectOption {
   label: string
   value: unknown
+  /** Inline SVG markup. When any option has one, the control is an icon row. */
+  iconSvg?: string
 }
 
 interface SelectControlProps extends ControlProps<unknown> {
@@ -47,6 +52,41 @@ export function SelectControl({
     if (!hoverPreviewEnabled) onClearPreview?.()
   }, [hoverPreviewEnabled, onClearPreview])
 
+  if (options.some((opt) => opt.iconSvg)) {
+    return (
+      <ControlRow
+        propKey={propKey}
+        label={label}
+        layout={layout}
+        isOverride={isOverride}
+        disabled={disabled}
+      >
+        <SegmentedControl
+          aria-label={label}
+          value={String(value ?? '')}
+          disabled={disabled}
+          fullWidth
+          options={options.map((opt) => ({
+            value: String(opt.value),
+            ariaLabel: opt.label,
+            tooltip: opt.label,
+            // Sanitised: a plugin module's schema can supply this markup.
+            icon: (
+              <span
+                className={styles.selectOptionIcon}
+                dangerouslySetInnerHTML={{ __html: sanitizeSvg(opt.iconSvg) }}
+              />
+            ),
+          }))}
+          onChange={(next) => {
+            const matched = options.find((o) => String(o.value) === next)
+            onChange(propKey, matched !== undefined ? matched.value : next)
+          }}
+        />
+      </ControlRow>
+    )
+  }
+
   return (
     <ControlRow
       propKey={propKey}
diff --git a/src/admin/pages/site/property-controls/controls.module.css b/src/admin/pages/site/property-controls/controls.module.css
index 4a3d29758..bb89c3d7f 100644
--- a/src/admin/pages/site/property-controls/controls.module.css
+++ b/src/admin/pages/site/property-controls/controls.module.css
@@ -389,3 +389,23 @@
 .groupChildren {
     padding: var(--space-m) 0 0 var(--space-m);
 }
+
+/* Icon drawn inside a segment when a select's options carry `iconSvg`. */
+.selectOptionIcon {
+    display: inline-flex;
+    width: 16px;
+    height: 16px;
+}
+
+.selectOptionIcon svg {
+    width: 100%;
+    height: 100%;
+}
+
+/* Number field with a row of preset buttons under it. */
+.numberWithPresets {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+    width: 100%;
+}
diff --git a/src/core/plugin-sdk/builders/controls.ts b/src/core/plugin-sdk/builders/controls.ts
index 201e8d67d..4be37c0d5 100644
--- a/src/core/plugin-sdk/builders/controls.ts
+++ b/src/core/plugin-sdk/builders/controls.ts
@@ -16,7 +16,7 @@
  */
 import type { PluginPropertyControl } from '../modules'
 
-type SelectOption<T> = { label: string; value: T }
+type SelectOption<T> = { label: string; value: T; iconSvg?: string }
 
 export const control = {
   text(label: string, options: { placeholder?: string; description?: string } = {}): PluginPropertyControl {
@@ -32,7 +32,7 @@ export const control = {
 
   number(
     label: string,
-    options: { min?: number; max?: number; step?: number; unit?: string; description?: string } = {},
+    options: { min?: number; max?: number; step?: number; unit?: string; presets?: number[]; description?: string } = {},
   ): PluginPropertyControl {
     return { type: 'number', label, ...options }
   },
diff --git a/src/core/plugin-sdk/modules.ts b/src/core/plugin-sdk/modules.ts
index c91f30b51..ba9221356 100644
--- a/src/core/plugin-sdk/modules.ts
+++ b/src/core/plugin-sdk/modules.ts
@@ -29,9 +29,9 @@ export type PluginPropertyControl = PluginPropertyControlBase &
   (
     | { type: 'text'; placeholder?: string }
     | { type: 'textarea'; rows?: number; placeholder?: string }
-    | { type: 'number'; min?: number; max?: number; step?: number; unit?: string }
+    | { type: 'number'; min?: number; max?: number; step?: number; unit?: string; presets?: number[] }
     | { type: 'color'; format?: 'hex' | 'rgba' }
-    | { type: 'select'; options: Array<{ label: string; value: unknown }> }
+    | { type: 'select'; options: Array<{ label: string; value: unknown; iconSvg?: string }> }
     | { type: 'toggle' }
     | { type: 'image' }
     | { type: 'url' }

From 35f6826d51e9a3afcea5bbd6a935f40b710f02f1 Mon Sep 17 00:00:00 2001
From: Quynn Bell <quynnbell@protonmail.com>
Date: Mon, 12 Oct 2026 10:37:26 -0700
Subject: [PATCH 4/7] feat(canvas): preview the navigation menu as it publishes

- Pass the breakpoint frame width to module editor components
- Inject a module's canvasCss where the publisher puts module CSS
- Author classes now override module styles in the canvas the same way they do when published
- Header navigation: the menu collapses in narrow frames and keeps its padding and indents in the editor
---
 .../canvas/navCanvasPreview.test.tsx          | 255 ++++++++++++++++++
 .../pages/site/canvas/BreakpointFrame.tsx     |   6 +-
 src/admin/pages/site/canvas/CanvasContexts.ts |   5 +
 .../pages/site/canvas/CanvasLiveSurface.tsx   |   6 +-
 .../pages/site/canvas/ClassStyleInjector.tsx  |  13 +-
 src/admin/pages/site/canvas/NodeRenderer.tsx  |   4 +-
 src/admin/pages/site/canvas/canvasClassCss.ts |  38 ++-
 7 files changed, 312 insertions(+), 15 deletions(-)
 create mode 100644 src/__tests__/canvas/navCanvasPreview.test.tsx

diff --git a/src/__tests__/canvas/navCanvasPreview.test.tsx b/src/__tests__/canvas/navCanvasPreview.test.tsx
new file mode 100644
index 000000000..1900d3d5b
--- /dev/null
+++ b/src/__tests__/canvas/navCanvasPreview.test.tsx
@@ -0,0 +1,255 @@
+/**
+ * Canvas preview of base.nav / base.nav-item.
+ *
+ * Covers the two canvas contracts those modules rely on:
+ *   - `canvasViewportWidth` reaches a module's editor component with the
+ *     width of the breakpoint frame it renders in
+ *   - a module's `canvasCss` is injected at the published cascade position
+ *     (after the reset, before class CSS, inside `@layer user-authored`), so
+ *     author CSS overrides it the way it does on a published page.
+ */
+import { beforeEach, describe, expect, it } from 'bun:test'
+import { cleanup, render } from '@testing-library/react'
+import { useEditorStore } from '@site/store/store'
+import { BreakpointFrame } from '@site/canvas/BreakpointFrame'
+import { collectModuleCanvasCss, generateCanvasClassCSS } from '@site/canvas/canvasClassCss'
+import { registry, type AnyModuleDefinition } from '@core/module-engine'
+import { PUBLISHER_RESET_CSS } from '@core/publisher'
+import { classKindSelector, type StyleRule } from '@core/page-tree'
+import { NAV_CANVAS_CSS, NAV_CSS } from '@modules/base/nav/navCss'
+import { NAV_ITEM_CANVAS_CSS, NAV_ITEM_CSS, navItemCollapseCss } from '@modules/base/nav-item/navItemCss'
+import { waitForCanvasFrameDocument, waitForCanvasNodeInFrame } from './iframeCanvasQuery'
+import '@modules/base'
+
+beforeEach(() => {
+  cleanup()
+  useEditorStore.setState({
+    site: null,
+    selectedNodeId: null,
+    selectedNodeIds: [],
+    hoveredNodeId: null,
+    activeDocument: null,
+    activePageId: null,
+    activeBreakpointId: 'desktop',
+  })
+})
+
+function buildNavPage(collapseBreakpoint: number) {
+  const store = useEditorStore.getState()
+  const site = store.createSite('Nav Preview')
+  const rootId = site.pages[0].rootNodeId
+  const navId = store.insertNode('base.nav', { collapseBreakpoint }, rootId)
+  const itemId = store.insertNode('base.nav-item', { label: 'Products' }, navId)
+  const childId = store.insertNode('base.nav-item', { label: 'Pricing' }, itemId)
+  return { navId, itemId, childId }
+}
+
+function renderFrame(id: string, width: number) {
+  return render(
+    <BreakpointFrame
+      page={useEditorStore.getState().site!.pages[0]}
+      breakpoint={{ id, label: id, width, icon: 'smartphone' }}
+      isActive
+      onActivate={() => {}}
+    />,
+  )
+}
+
+describe('canvasViewportWidth', () => {
+  it('collapses the nav in a frame at or below its collapse width', async () => {
+    const { navId } = buildNavPage(768)
+    renderFrame('mobile', 375)
+    const nav = await waitForCanvasNodeInFrame('mobile', navId)
+    expect(nav.getAttribute('data-instatic-nav-canvas')).toBe('collapsed')
+  })
+
+  it('treats a frame exactly as wide as the collapse width as collapsed, like max-width', async () => {
+    const { navId } = buildNavPage(768)
+    renderFrame('tablet', 768)
+    const nav = await waitForCanvasNodeInFrame('tablet', navId)
+    expect(nav.getAttribute('data-instatic-nav-canvas')).toBe('collapsed')
+  })
+
+  it('keeps the desktop row in a frame wider than the collapse width', async () => {
+    const { navId } = buildNavPage(768)
+    renderFrame('desktop', 1280)
+    const nav = await waitForCanvasNodeInFrame('desktop', navId)
+    expect(nav.hasAttribute('data-instatic-nav-canvas')).toBe(false)
+  })
+})
+
+describe('nav canvas markup', () => {
+  it('uses the published classes and data attributes, with no inline layout styles', async () => {
+    const { navId, itemId, childId } = buildNavPage(768)
+    renderFrame('mobile', 375)
+    const nav = await waitForCanvasNodeInFrame('mobile', navId)
+    const item = await waitForCanvasNodeInFrame('mobile', itemId)
+    const child = await waitForCanvasNodeInFrame('mobile', childId)
+
+    expect(nav.classList.contains('instatic-nav')).toBe(true)
+    expect(nav.getAttribute('data-instatic-nav-mode')).toBe('dropdown')
+    expect(nav.getAttribute('data-instatic-nav-align')).toBe('start')
+    // An inline style would beat any class the author puts on the node.
+    expect(nav.hasAttribute('style')).toBe(false)
+    expect(nav.querySelector('.instatic-nav__menu')?.hasAttribute('style')).toBe(false)
+    expect(nav.querySelector('.instatic-nav__toggle')?.hasAttribute('style')).toBe(false)
+
+    expect(item.classList.contains('instatic-nav-item')).toBe(true)
+    expect(item.hasAttribute('style')).toBe(false)
+    expect(item.querySelector(':scope > a.instatic-nav-item__link')?.textContent).toBe('Products')
+    expect(item.querySelector(':scope > .instatic-nav-item__submenu')?.contains(child)).toBe(true)
+  })
+
+  it('carries the menu background as a custom property on the menu list only', async () => {
+    const { navId } = buildNavPage(768)
+    useEditorStore.getState().updateNodeProps(navId, { menuBackground: '#112233' })
+    renderFrame('mobile', 375)
+    const nav = await waitForCanvasNodeInFrame('mobile', navId)
+    const menu = nav.querySelector<HTMLElement>('.instatic-nav__menu')
+    expect(menu?.style.getPropertyValue('--instatic-nav-menu-bg')).toBe('#112233')
+    expect(nav.hasAttribute('style')).toBe(false)
+  })
+
+  it('renders an unlinked parent label as the toggle button, not an anchor', async () => {
+    const { itemId } = buildNavPage(768)
+    useEditorStore.getState().updateNodeProps(itemId, { isLink: false })
+    renderFrame('mobile', 375)
+    const item = await waitForCanvasNodeInFrame('mobile', itemId)
+    expect(item.querySelector(':scope > a')).toBeNull()
+    const label = item.querySelector(':scope > button.instatic-nav-item__link')
+    expect(label?.textContent).toBe('Products')
+    expect(label?.querySelector('.instatic-nav-item__toggle-icon')).not.toBeNull()
+    expect(item.querySelector(':scope > .instatic-nav-item__toggle')).toBeNull()
+  })
+})
+
+describe('module canvasCss', () => {
+  const className = 'author_card'
+  const authorClass: StyleRule = {
+    id: className,
+    name: className,
+    kind: 'class',
+    selector: classKindSelector(className),
+    order: 0,
+    styles: { padding: '40px' },
+    contextStyles: {},
+    createdAt: 0,
+    updatedAt: 0,
+  }
+
+  it('sits after the reset and before class CSS, the position module CSS has when published', () => {
+    const css = generateCanvasClassCSS(
+      { [className]: authorClass }, [], [], null, null, null, null, null,
+      { moduleCss: '.module-marker { padding: 8px; }' },
+    )
+    const reset = css.indexOf(PUBLISHER_RESET_CSS)
+    const moduleRule = css.indexOf('.module-marker')
+    const classRule = css.indexOf(`.${className}`)
+    expect(reset).toBe(0)
+    expect(moduleRule).toBeGreaterThan(reset)
+    expect(classRule).toBeGreaterThan(moduleRule)
+  })
+
+  it('regenerates when the module CSS changes', () => {
+    const classes = { [className]: authorClass }
+    const breakpoints: never[] = []
+    const conditions: never[] = []
+    const first = generateCanvasClassCSS(classes, breakpoints, conditions, null, null, null, null, null, { moduleCss: '.a {}' })
+    const second = generateCanvasClassCSS(classes, breakpoints, conditions, null, null, null, null, null, { moduleCss: '.b {}' })
+    expect(first).toContain('.a {}')
+    expect(second).toContain('.b {}')
+    expect(second).not.toContain('.a {}')
+  })
+
+  it('collects canvasCss from trusted modules only', () => {
+    const base = registry.get('base.nav')
+    const modules = [
+      { ...base, id: 'test.trusted', trusted: true, canvasCss: '.trusted {}' },
+      { ...base, id: 'test.plugin', trusted: false, canvasCss: '.plugin {}' },
+      { ...base, id: 'test.none', trusted: true, canvasCss: undefined },
+    ] as AnyModuleDefinition[]
+    expect(collectModuleCanvasCss(modules)).toBe('.trusted {}')
+  })
+
+  it('registers the nav stylesheets on their modules', () => {
+    expect(registry.get('base.nav').canvasCss).toBe(NAV_CANVAS_CSS)
+    expect(registry.get('base.nav-item').canvasCss).toBe(NAV_ITEM_CANVAS_CSS)
+  })
+
+  it('injects them into the frame inside the author layer, never the unlayered chrome sheet', async () => {
+    buildNavPage(768)
+    renderFrame('mobile', 375)
+    const doc = await waitForCanvasFrameDocument('mobile')
+    const classSheet = doc.getElementById('mc-classes')?.textContent ?? ''
+    expect(classSheet.startsWith('@layer user-authored {')).toBe(true)
+    expect(classSheet).toContain('.instatic-nav-item__link {')
+    expect(classSheet).toContain('.instatic-nav[data-instatic-nav-canvas="collapsed"] > .instatic-nav__menu {')
+    expect(classSheet).not.toContain('@layer instatic-module-preview')
+
+    const chromeSheet = doc.getElementById('instatic-editor-chrome')?.textContent ?? ''
+    expect(chromeSheet).not.toContain('instatic-nav')
+  })
+})
+
+describe('nav canvas stylesheet', () => {
+  const collapsed = '.instatic-nav[data-instatic-nav-canvas="collapsed"]'
+  const selected = ':is([data-canvas-selected="true"], :has([data-canvas-selected="true"]))'
+
+  it('starts with the published static CSS, verbatim', () => {
+    expect(NAV_CANVAS_CSS.startsWith(NAV_CSS)).toBe(true)
+  })
+
+  it('applies the published collapse rules to a collapsed frame instead of a media query', () => {
+    expect(NAV_CANVAS_CSS).not.toContain('@media')
+    expect(NAV_CANVAS_CSS).toContain(`${collapsed} > .instatic-nav__toggle {\n    display: inline-flex;`)
+    expect(NAV_CANVAS_CSS).toContain(`${collapsed}[data-instatic-nav-mode="dropdown"] > .instatic-nav__menu {`)
+    expect(NAV_CANVAS_CSS).toContain(`${collapsed}[data-instatic-nav-mode="overlay"] > .instatic-nav__menu {`)
+  })
+
+  it('closes the collapsed menu and opens it while the nav or a node inside it is selected', () => {
+    expect(NAV_CANVAS_CSS).toContain(`${collapsed} > .instatic-nav__menu {\n    display: none;`)
+    expect(NAV_CANVAS_CSS).toContain(`${collapsed}${selected} > .instatic-nav__menu {\n    display: flex;`)
+    // Module JS never runs in the canvas, so nothing keys on its state attribute.
+    expect(NAV_CANVAS_CSS).not.toContain('data-instatic-nav-state')
+  })
+
+  it('caps the overlay at one viewport height so it cannot cover the whole page frame', () => {
+    expect(NAV_CANVAS_CSS).toContain(
+      `${collapsed}[data-instatic-nav-mode="overlay"] > .instatic-nav__menu {\n    inset: 0 0 auto;\n    height: 100vh;`,
+    )
+  })
+
+  it('never scroll-locks the frame document', () => {
+    expect(NAV_CANVAS_CSS).not.toContain('html:has(')
+  })
+})
+
+describe('nav-item canvas stylesheet', () => {
+  const collapsed = '.instatic-nav[data-instatic-nav-canvas="collapsed"]'
+  const selected = ':is([data-canvas-selected="true"], :has([data-canvas-selected="true"]))'
+  const publishedOpen = '[data-instatic-nav-item-state="open"]'
+
+  it('is the published CSS with the canvas selectors swapped in', () => {
+    const published = NAV_ITEM_CSS + navItemCollapseCss(768)
+    const expected = published
+      .replace('\n@media (max-width: 768px) {', '')
+      .replace(/\n\}$/, '')
+      .replaceAll('.instatic-nav[data-instatic-nav-collapse="768"]', collapsed)
+      .replaceAll(publishedOpen, selected)
+    expect(NAV_ITEM_CANVAS_CSS.trimEnd()).toBe(expected)
+  })
+
+  it('keeps the link padding and the per-level indents the published page has', () => {
+    expect(NAV_ITEM_CANVAS_CSS).toContain('.instatic-nav-item__link {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  padding: 8px 12px;')
+    expect(NAV_ITEM_CANVAS_CSS).toContain(
+      `${collapsed} .instatic-nav-item__submenu .instatic-nav-item__link {\n    padding-left: 28px;`,
+    )
+  })
+
+  it('opens a submenu while its item or a node inside it is selected', () => {
+    expect(NAV_ITEM_CANVAS_CSS).toContain(`.instatic-nav-item${selected} > .instatic-nav-item__submenu {\n  display: flex;`)
+    expect(NAV_ITEM_CANVAS_CSS).toContain(
+      `${collapsed} .instatic-nav-item${selected} > .instatic-nav-item__submenu {\n    display: flex;`,
+    )
+  })
+})
diff --git a/src/admin/pages/site/canvas/BreakpointFrame.tsx b/src/admin/pages/site/canvas/BreakpointFrame.tsx
index 2c3ca3557..10eb0d727 100644
--- a/src/admin/pages/site/canvas/BreakpointFrame.tsx
+++ b/src/admin/pages/site/canvas/BreakpointFrame.tsx
@@ -23,7 +23,7 @@ import type { TemplateRenderDataContext } from '@core/templates/dynamicBindings'
 import { CanvasComposedTree } from './CanvasComposedTree'
 import { BreakpointSelectionOverlay } from './BreakpointSelectionOverlay'
 import { PeerPresenceOverlay } from './PeerPresenceOverlay'
-import { CanvasBreakpointContext, CanvasTemplateContext } from './CanvasContexts'
+import { CanvasBreakpointContext, CanvasBreakpointWidthContext, CanvasTemplateContext } from './CanvasContexts'
 import { IframeFrameSurface, type IframeFrameSurfaceHandle } from './IframeFrameSurface'
 import type { InjectableRuntimeScript } from './useRuntimeScriptBuild'
 import { Button } from '@ui/components/Button'
@@ -231,7 +231,9 @@ export function BreakpointFrame({
         >
           <CanvasTemplateContext.Provider value={templateContext}>
             <CanvasBreakpointContext.Provider value={breakpoint.id}>
-              <CanvasComposedTree page={page} />
+              <CanvasBreakpointWidthContext.Provider value={breakpoint.width}>
+                <CanvasComposedTree page={page} />
+              </CanvasBreakpointWidthContext.Provider>
             </CanvasBreakpointContext.Provider>
           </CanvasTemplateContext.Provider>
         </IframeFrameSurface>
diff --git a/src/admin/pages/site/canvas/CanvasContexts.ts b/src/admin/pages/site/canvas/CanvasContexts.ts
index 98de4fad6..4c3dc5cc2 100644
--- a/src/admin/pages/site/canvas/CanvasContexts.ts
+++ b/src/admin/pages/site/canvas/CanvasContexts.ts
@@ -24,6 +24,11 @@ export const CanvasViewportActionsContext =
   createContext<CanvasViewportActionsContextValue | null>(null)
 
 export const CanvasBreakpointContext = createContext<string | undefined>(undefined)
+/**
+ * Pixel width of the rendering breakpoint frame (e.g. 375 for mobile). Passed
+ * to modules as canvasViewportWidth.
+ */
+export const CanvasBreakpointWidthContext = createContext<number | undefined>(undefined)
 export const CanvasTemplateContext = createContext<TemplateRenderDataContext | undefined>(undefined)
 /** Final srcDoc document owned by the nearest IframeFrameSurface. */
 export const CanvasDocumentContext = createContext<Document | null>(null)
diff --git a/src/admin/pages/site/canvas/CanvasLiveSurface.tsx b/src/admin/pages/site/canvas/CanvasLiveSurface.tsx
index fa919f046..51d09a500 100644
--- a/src/admin/pages/site/canvas/CanvasLiveSurface.tsx
+++ b/src/admin/pages/site/canvas/CanvasLiveSurface.tsx
@@ -40,7 +40,7 @@ import type { Breakpoint, Page } from '@core/page-tree'
 import type { TemplateRenderDataContext } from '@core/templates/dynamicBindings'
 import { CanvasComposedTree } from './CanvasComposedTree'
 import { BreakpointSelectionOverlay } from './BreakpointSelectionOverlay'
-import { CanvasBreakpointContext, CanvasTemplateContext } from './CanvasContexts'
+import { CanvasBreakpointContext, CanvasBreakpointWidthContext, CanvasTemplateContext } from './CanvasContexts'
 import { IframeFrameSurface, type IframeFrameSurfaceHandle } from './IframeFrameSurface'
 import type { InjectableRuntimeScript } from './useRuntimeScriptBuild'
 import { CanvasFrameSkeleton } from '@admin/shared/CanvasFrameSkeleton'
@@ -176,7 +176,9 @@ export function CanvasLiveSurface({
             >
               <CanvasTemplateContext.Provider value={templateContext}>
                 <CanvasBreakpointContext.Provider value={activeBreakpoint.id}>
-                  <CanvasComposedTree page={page} />
+                  <CanvasBreakpointWidthContext.Provider value={activeBreakpoint.width}>
+                    <CanvasComposedTree page={page} />
+                  </CanvasBreakpointWidthContext.Provider>
                 </CanvasBreakpointContext.Provider>
               </CanvasTemplateContext.Provider>
             </IframeFrameSurface>
diff --git a/src/admin/pages/site/canvas/ClassStyleInjector.tsx b/src/admin/pages/site/canvas/ClassStyleInjector.tsx
index f62234b76..4714cb1a1 100644
--- a/src/admin/pages/site/canvas/ClassStyleInjector.tsx
+++ b/src/admin/pages/site/canvas/ClassStyleInjector.tsx
@@ -47,9 +47,11 @@ import {
   treeShakeStyleRulesBySignature,
   usedStyleRuleIdSignature,
 } from '@core/publisher'
+import { registry } from '@core/module-engine'
 import { useResponsiveEditorMediaAssets } from '@admin/pages/media/hooks/useResponsiveBackgroundStyle'
 import { selectorStatePseudo } from '@site/cssStatePseudo'
 import {
+  collectModuleCanvasCss,
   generateAmbientPlaceholderSuppressionCSS,
   generateCanvasClassCSS,
   generateForcedStateCSS,
@@ -116,6 +118,8 @@ export function ClassStyleInjector({ targetDocument, viewport }: ClassStyleInjec
   const previewClassStyles = useEditorStore((s) => s.previewClassStyles)
   const activeClassId = useEditorStore((s) => s.activeClassId)
   const selectedNodeId = useEditorStore((s) => s.selectedNodeId)
+  // A string, so the effect below only re-runs when the content changes.
+  const moduleCanvasCss = collectModuleCanvasCss(registry.list())
   const canvasClasses = treeShakeStyleRulesBySignature(
     classes ?? EMPTY_STYLE_RULES,
     usedClassIdSignature,
@@ -153,11 +157,15 @@ export function ClassStyleInjector({ targetDocument, viewport }: ClassStyleInjec
       frameworkSpacing,
       frameworkPreferences,
       fonts,
-      { mediaAssets: responsiveMediaAssets, mediaSignature: responsiveMediaSignature },
+      {
+        mediaAssets: responsiveMediaAssets,
+        mediaSignature: responsiveMediaSignature,
+        moduleCss: moduleCanvasCss,
+      },
     )
     // Wrap in a named cascade layer so editor-chrome CSS (unlayered, from
     // EditorChromeInjector) always wins over author CSS regardless of specificity.
-    // The publisher reset, framework CSS, and class rules are all inside the layer;
+    // The publisher reset, framework CSS, module canvas CSS, and class rules are all inside the layer;
     // their relative cascade among themselves is preserved (source order + specificity
     // within the layer). User CSS (also @layer user-authored) still wins over the
     // zero-specificity :where() publisher reset — same as before.
@@ -184,6 +192,7 @@ export function ClassStyleInjector({ targetDocument, viewport }: ClassStyleInjec
     fonts,
     responsiveMediaAssets,
     responsiveMediaSignature,
+    moduleCanvasCss,
   ])
 
   // Preview overlay — a higher-specificity rule emitted while a user is
diff --git a/src/admin/pages/site/canvas/NodeRenderer.tsx b/src/admin/pages/site/canvas/NodeRenderer.tsx
index 2a373d49f..d3a309467 100644
--- a/src/admin/pages/site/canvas/NodeRenderer.tsx
+++ b/src/admin/pages/site/canvas/NodeRenderer.tsx
@@ -34,7 +34,7 @@ import type { PageNode } from '@core/page-tree'
 import { WarningDiamondSolidIcon } from 'pixel-art-icons/icons/warning-diamond-solid'
 import { ErrorBoundary } from '@ui/components/ErrorBoundary'
 import { ModuleSandboxFrame } from './ModuleSandboxFrame'
-import { CanvasBreakpointContext, CanvasSelectionContext, CanvasTemplateContext } from './CanvasContexts'
+import { CanvasBreakpointContext, CanvasBreakpointWidthContext, CanvasSelectionContext, CanvasTemplateContext } from './CanvasContexts'
 import {
   addEditorFormPreviewProps,
   resolveEditorFormPreviewState,
@@ -61,6 +61,7 @@ export const NodeRenderer = memo(function NodeRenderer({ nodeId }: NodeRendererP
   // Uses selectActiveCanvasPage (Task #438) so VC canvas mode works alongside page mode.
   const node = useEditorStore((s) => selectActiveCanvasPage(s)?.nodes[nodeId] ?? null)
   const breakpointId = use(CanvasBreakpointContext)
+  const canvasViewportWidth = use(CanvasBreakpointWidthContext)
   const templateContext = use(CanvasTemplateContext)
 
   // Per-node selection/hover subscriptions (Perf fix — Contribution #495).
@@ -444,6 +445,7 @@ export const NodeRenderer = memo(function NodeRenderer({ nodeId }: NodeRendererP
           mcClassName={mcClassName}
           nodeWrapperProps={effectiveWrapperProps}
           inlineEdit={inlineEditBinding}
+          canvasViewportWidth={canvasViewportWidth}
         >
           {isInlineEditing ? undefined : children}
         </ComponentType>
diff --git a/src/admin/pages/site/canvas/canvasClassCss.ts b/src/admin/pages/site/canvas/canvasClassCss.ts
index 886aa4069..9790a9ce6 100644
--- a/src/admin/pages/site/canvas/canvasClassCss.ts
+++ b/src/admin/pages/site/canvas/canvasClassCss.ts
@@ -11,6 +11,7 @@ import { generateFontsCss } from '@core/fonts'
 import { styleRuleSelector } from '@core/page-tree'
 import type { StyleRule, ConditionDef } from '@core/page-tree'
 import type { SiteFontsSettings } from '@core/fonts'
+import type { AnyModuleDefinition } from '@core/module-engine'
 import type {
   FrameworkColorSettings,
   FrameworkPreferencesSettings,
@@ -18,8 +19,21 @@ import type {
   FrameworkTypographySettings,
 } from '@core/framework-schema'
 
-interface CanvasResponsiveCssOptions extends ResponsiveCssOptions {
+interface CanvasClassCssOptions extends ResponsiveCssOptions {
   mediaSignature?: string
+  /** Module canvas stylesheets. See `collectModuleCanvasCss`. */
+  moduleCss?: string
+}
+
+/**
+ * Join the `canvasCss` of every trusted module. Untrusted (plugin) modules
+ * are skipped: their preview renders in a sandbox frame this never reaches,
+ * and the string is injected unsanitised.
+ */
+export function collectModuleCanvasCss(modules: AnyModuleDefinition[]): string {
+  return modules
+    .flatMap((mod) => (mod.trusted && mod.canvasCss ? [mod.canvasCss.trim()] : []))
+    .join('\n\n')
 }
 
 function buildCanvasClassCSS(
@@ -31,7 +45,7 @@ function buildCanvasClassCSS(
   frameworkSpacing?: FrameworkSpacingSettings | null,
   frameworkPreferences?: FrameworkPreferencesSettings | null,
   fonts?: SiteFontsSettings | null,
-  responsiveOptions: CanvasResponsiveCssOptions = {},
+  options: CanvasClassCssOptions = {},
 ): string {
   const blocks: string[] = []
 
@@ -58,11 +72,17 @@ function buildCanvasClassCSS(
   })
   if (frameworkCss) blocks.push(frameworkCss)
 
+  // Module canvas CSS sits where `publishPage()` puts module CSS: after the
+  // reset and framework CSS, before the class registry. A class on a node
+  // then wins a specificity tie against its module's rules, as it does when
+  // published.
+  if (options.moduleCss) blocks.push(options.moduleCss)
+
   // The registry CSS is the publisher's own generator — the canvas ships the
   // exact bytes a publish would (rule order, condition/viewport cascade, and
   // sanitized raw @keyframes rules included), so the preview cannot drift
   // from the published output.
-  const classCss = generateClassCSS(classes, breakpoints, conditions, responsiveOptions)
+  const classCss = generateClassCSS(classes, breakpoints, conditions, options)
   if (classCss) blocks.push(classCss)
 
   return blocks.join('\n\n')
@@ -75,7 +95,7 @@ type CanvasClassCssGenerator = typeof buildCanvasClassCSS
  *
  * Every breakpoint-frame `ClassStyleInjector` regenerates this CSS with the
  * SAME store-snapshot inputs in the same commit — the generation is pure and
- * all inputs are Mutative-immutable, so comparing the 8 argument identities
+ * all inputs are Mutative-immutable or strings, so comparing the argument identities
  * is exact: frames 2..N (and any re-run with unchanged inputs) return the
  * cached string instead of re-sorting and re-emitting the whole registry.
  *
@@ -96,7 +116,7 @@ export function createCanvasClassCssMemo(
     frameworkSpacing,
     frameworkPreferences,
     fonts,
-    responsiveOptions = {},
+    options = {},
   ) => {
     const inputs = [
       classes,
@@ -107,7 +127,8 @@ export function createCanvasClassCssMemo(
       frameworkSpacing,
       frameworkPreferences,
       fonts,
-      responsiveOptions.mediaSignature,
+      options.mediaSignature,
+      options.moduleCss,
     ]
     const prev = lastInputs
     if (prev && inputs.every((value, i) => Object.is(value, prev[i]))) {
@@ -122,7 +143,7 @@ export function createCanvasClassCssMemo(
       frameworkSpacing,
       frameworkPreferences,
       fonts,
-      responsiveOptions,
+      options,
     )
     lastInputs = inputs
     return lastCss
@@ -131,7 +152,8 @@ export function createCanvasClassCssMemo(
 
 /**
  * Generate the canvas class-registry CSS (publisher reset + fonts +
- * framework root CSS + the publisher's `generateClassCSS` output).
+ * framework root CSS + module canvas CSS + the publisher's
+ * `generateClassCSS` output).
  * Identity-memoized — see `createCanvasClassCssMemo`.
  */
 export const generateCanvasClassCSS: CanvasClassCssGenerator = createCanvasClassCssMemo()

From fecca3d8cc985a728caba7bc1e2b85acf88f71c5 Mon Sep 17 00:00:00 2001
From: Quynn Bell <quynnbell@protonmail.com>
Date: Mon, 12 Oct 2026 10:38:06 -0700
Subject: [PATCH 5/7] fix(editor): let URL fields be typed into and take
 relative links

- Keep what is being typed instead of snapping back on every keystroke
- Accept /paths, #fragments and ?queries
- Accept tel: and sms:, which the publisher already allows
- Header navigation: a Menu Item's Link field could not be typed into or point at a page section
---
 .../urlControlTyping.test.tsx                 | 90 +++++++++++++++++++
 src/__tests__/utils/urlValidation.test.ts     | 48 +++++++++-
 .../site/property-controls/UrlControl.tsx     | 23 +++--
 src/core/utils/urlValidation.ts               | 28 ++++--
 4 files changed, 175 insertions(+), 14 deletions(-)
 create mode 100644 src/__tests__/property-controls/urlControlTyping.test.tsx

diff --git a/src/__tests__/property-controls/urlControlTyping.test.tsx b/src/__tests__/property-controls/urlControlTyping.test.tsx
new file mode 100644
index 000000000..3a4311f4b
--- /dev/null
+++ b/src/__tests__/property-controls/urlControlTyping.test.tsx
@@ -0,0 +1,90 @@
+/**
+ * UrlControl — typing a URL.
+ *
+ * Only valid URLs are stored, and a URL is invalid at almost every keystroke
+ * on the way to being complete. The field must therefore keep showing what is
+ * being typed instead of snapping back to the stored value.
+ */
+import { afterEach, describe, expect, it } from 'bun:test'
+import { useState } from 'react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { UrlControl } from '@site/property-controls/UrlControl'
+
+afterEach(cleanup)
+
+/** Holds the prop the way the editor store does: the control only sees stored values. */
+function Harness({ initial, stored }: { initial: string; stored: string[] }) {
+  const [value, setValue] = useState(initial)
+  return (
+    <UrlControl
+      propKey="href"
+      label="Link"
+      value={value}
+      onChange={(_key, next) => {
+        stored.push(next)
+        setValue(next)
+      }}
+    />
+  )
+}
+
+function setup(initial = '') {
+  const stored: string[] = []
+  render(<Harness initial={initial} stored={stored} />)
+  const field = () => screen.getByRole<HTMLInputElement>('textbox')
+  const type = (text: string) => fireEvent.change(field(), { target: { value: text } })
+  return { stored, field, type }
+}
+
+describe('UrlControl typing', () => {
+  it('keeps each keystroke in the field while the URL is still incomplete', () => {
+    const { stored, field, type } = setup()
+    for (const partial of ['h', 'ht', 'http', 'https:', 'https://']) {
+      type(partial)
+      expect(field().value).toBe(partial)
+    }
+    expect(stored).toEqual([])
+    expect(screen.getByRole('alert').textContent).toBe('Invalid URL')
+  })
+
+  it('stores the URL and clears the error once it becomes valid', () => {
+    const { stored, field, type } = setup()
+    type('https://')
+    type('https://e')
+    expect(stored).toEqual(['https://e'])
+    expect(field().value).toBe('https://e')
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+
+  it('accepts a typed site-relative link', () => {
+    const { stored, field, type } = setup()
+    type('/')
+    type('/about')
+    type('#pricing')
+    expect(stored).toEqual(['/', '/about', '#pricing'])
+    expect(field().value).toBe('#pricing')
+  })
+
+  it('leaves the stored URL untouched while a replacement is being typed', () => {
+    const { stored, field, type } = setup('https://example.com')
+    type('exam')
+    expect(field().value).toBe('exam')
+    expect(stored).toEqual([])
+  })
+
+  it('drops an unfinished draft on blur and shows the stored URL again', () => {
+    const { stored, field, type } = setup('https://example.com')
+    type('exam')
+    fireEvent.blur(field())
+    expect(field().value).toBe('https://example.com')
+    expect(screen.queryByRole('alert')).toBeNull()
+    expect(stored).toEqual([])
+  })
+
+  it('stores an emptied field, so a link can be removed', () => {
+    const { stored, field, type } = setup('https://example.com')
+    type('')
+    expect(stored).toEqual([''])
+    expect(field().value).toBe('')
+  })
+})
diff --git a/src/__tests__/utils/urlValidation.test.ts b/src/__tests__/utils/urlValidation.test.ts
index 4e93c491c..526957995 100644
--- a/src/__tests__/utils/urlValidation.test.ts
+++ b/src/__tests__/utils/urlValidation.test.ts
@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'bun:test'
 import { isValidUrl, isValidImageUrl } from '@core/utils/urlValidation'
+import { isSafeUrl } from '@core/html-sanitize'
 
 // ---------------------------------------------------------------------------
 // isValidUrl
@@ -28,6 +29,20 @@ describe('isValidUrl', () => {
     it('accepts mailto:', () => {
       expect(isValidUrl('mailto:user@example.com')).toBe(true)
     })
+
+    it('accepts tel: and sms:, which the publisher also keeps in an href', () => {
+      expect(isValidUrl('tel:+15551234567')).toBe(true)
+      expect(isValidUrl('TEL:+15551234567')).toBe(true)
+      expect(isValidUrl('sms:+15551234567')).toBe(true)
+      expect(isValidUrl('sms:+15551234567?body=Hello')).toBe(true)
+    })
+
+    it('accepts every scheme the publisher lets through, so no publishable link is unenterable', () => {
+      for (const url of ['https://a.test', 'http://a.test', 'mailto:a@a.test', 'tel:+1555', 'sms:+1555']) {
+        expect(isSafeUrl(url)).toBe(true)
+        expect(isValidUrl(url)).toBe(true)
+      }
+    })
   })
 
   describe('rejected protocols', () => {
@@ -65,14 +80,43 @@ describe('isValidUrl', () => {
       expect(isValidUrl('not a url')).toBe(false)
     })
 
-    it('rejects relative paths', () => {
-      expect(isValidUrl('/relative/path')).toBe(false)
+    it('rejects a bare word, which is a typo or an unfinished URL far more often than a relative link', () => {
+      expect(isValidUrl('about')).toBe(false)
+      expect(isValidUrl('h')).toBe(false)
+      expect(isValidUrl('example.com')).toBe(false)
     })
 
     it('rejects protocol-relative URLs', () => {
       expect(isValidUrl('//example.com')).toBe(false)
     })
   })
+
+  describe('site-relative links', () => {
+    it('accepts a root path, with or without query and fragment', () => {
+      expect(isValidUrl('/')).toBe(true)
+      expect(isValidUrl('/relative/path')).toBe(true)
+      expect(isValidUrl('/pricing?plan=pro#faq')).toBe(true)
+    })
+
+    it('accepts a fragment, a query, and dot paths', () => {
+      expect(isValidUrl('#')).toBe(true)
+      expect(isValidUrl('#pricing')).toBe(true)
+      expect(isValidUrl('?page=2')).toBe(true)
+      expect(isValidUrl('./sibling')).toBe(true)
+      expect(isValidUrl('../parent')).toBe(true)
+    })
+
+    it('rejects one containing whitespace', () => {
+      expect(isValidUrl('/about us')).toBe(false)
+      expect(isValidUrl('# pricing')).toBe(false)
+    })
+
+    it('still rejects a script scheme hidden behind leading whitespace or control characters', () => {
+      expect(isValidUrl(' javascript:alert(1)')).toBe(false)
+      expect(isValidUrl('\tjavascript:alert(1)')).toBe(false)
+      expect(isValidUrl('/\njavascript:alert(1)')).toBe(false)
+    })
+  })
 })
 
 // ---------------------------------------------------------------------------
diff --git a/src/admin/pages/site/property-controls/UrlControl.tsx b/src/admin/pages/site/property-controls/UrlControl.tsx
index b9e101551..cbc58ac1d 100644
--- a/src/admin/pages/site/property-controls/UrlControl.tsx
+++ b/src/admin/pages/site/property-controls/UrlControl.tsx
@@ -14,7 +14,7 @@ const EMPTY_PAGES: { id: string; title: string; slug: string }[] = []
 
 /**
  * URL property control with two modes:
- *   - URL  — free-text external/relative URL (validated by isValidUrl).
+ *   - URL  — free-text absolute or site-relative URL (validated by isValidUrl).
  *   - Page — pick an existing CMS page; stored as a dynamic `cms:page:<id>`
  *            reference that the publisher resolves to the page's current path,
  *            so the link survives slug renames.
@@ -28,7 +28,12 @@ export function UrlControl({
   disabled,
   layout,
 }: ControlProps<string>) {
-  const [error, setError] = useState(false)
+  // What is being typed while it is not yet a valid URL. A URL is invalid at
+  // almost every keystroke on the way to being complete, and only valid
+  // values are stored, so the field shows this draft instead of the stored
+  // value until the two agree. null = show the stored value.
+  const [draft, setDraft] = useState<string | null>(null)
+  const error = draft !== null
   const pages = useEditorStore((s) => s.site?.pages ?? EMPTY_PAGES)
 
   const current = String(value ?? '')
@@ -37,9 +42,12 @@ export function UrlControl({
 
   const handleUrlChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const v = e.target.value
-    const valid = isValidUrl(v)
-    setError(!valid)
-    if (valid) onChange(propKey, v)
+    if (isValidUrl(v)) {
+      setDraft(null)
+      onChange(propKey, v)
+    } else {
+      setDraft(v)
+    }
   }
 
   const handlePagePick = (e: React.ChangeEvent<HTMLSelectElement>) => {
@@ -50,7 +58,7 @@ export function UrlControl({
   }
 
   // In URL mode never show a page-ref token in the text field — it isn't a URL.
-  const urlFieldValue = isPageRef(current) ? '' : current
+  const urlFieldValue = draft ?? (isPageRef(current) ? '' : current)
   const selectedPageId = ref?.pageId ?? ''
 
   const pageOptions = [
@@ -106,6 +114,9 @@ export function UrlControl({
             disabled={disabled}
             fieldSize="sm"
             onChange={handleUrlChange}
+            // An unfinished draft was never stored. Leaving the field drops
+            // it, so the field never shows a value the node does not have.
+            onBlur={() => setDraft(null)}
             invalid={error}
           />
         )}
diff --git a/src/core/utils/urlValidation.ts b/src/core/utils/urlValidation.ts
index 117616d27..0182a1e71 100644
--- a/src/core/utils/urlValidation.ts
+++ b/src/core/utils/urlValidation.ts
@@ -12,7 +12,7 @@
  * scheme is — they differ only in which schemes they accept.
  *
  * Allowlists:
- *   isValidUrl()       — https, http, mailto
+ *   isValidUrl()       — https, http, mailto, tel, sms, site-relative links
  *   isValidImageUrl()  — https, http, data:image/* (inline base64 images)
  */
 
@@ -40,19 +40,35 @@ function parses(v: string): boolean {
   }
 }
 
+/**
+ * A link within the site: a root path (`/about`), a fragment (`#pricing`), a
+ * query (`?page=2`), or a dot path (`./a`, `../a`). No whitespace.
+ *
+ * Narrower than what `isSafeUrl()` lets through at export time. A bare word
+ * (`about`) is also a relative URL, but here it is far more likely a typo or
+ * a URL still being typed, and `//host` is left out because it reads as a
+ * path while leaving the site.
+ */
+const SITE_RELATIVE_URL = /^(?:\/(?!\/)|#|\?|\.\.?\/)\S*$/
+
+/** Every scheme `isSafeUrl()` keeps in a published href, so a link the publisher emits can also be entered. */
+const LINK_SCHEMES = new Set(['https:', 'http:', 'mailto:', 'tel:', 'sms:'])
+
 /**
  * Returns true if `v` is a safe general-purpose URL for storing in site
  * props (e.g. a link href, a button href).
  *
- * Allows:  https:, http:, mailto:
- * Rejects: javascript:, data:, ftp:, blob:, custom schemes, schemeless values,
- *          and malformed absolute URLs (`http://`, `https://exa mple.com`)
+ * Allows:  https:, http:, mailto:, tel:, sms:, and site-relative links (`/about`,
+ *          `#pricing`, `?page=2`, `./a`, `../a`)
+ * Rejects: javascript:, data:, ftp:, blob:, custom schemes, bare words,
+ *          protocol-relative `//host`, and malformed absolute URLs
+ *          (`http://`, `https://exa mple.com`)
  */
 export function isValidUrl(v: string): boolean {
   if (!v) return true
   const scheme = urlScheme(v)
-  if (scheme !== 'https:' && scheme !== 'http:' && scheme !== 'mailto:') return false
-  return parses(v)
+  if (scheme === null) return SITE_RELATIVE_URL.test(v)
+  return LINK_SCHEMES.has(scheme) && parses(v)
 }
 
 /**

From 1c3478c878018361fddb0e1a6d7ad3c2e3ffcf91 Mon Sep 17 00:00:00 2001
From: Quynn Bell <quynnbell@protonmail.com>
Date: Mon, 12 Oct 2026 10:38:33 -0700
Subject: [PATCH 6/7] fix(editor): move the data binding button off the toggle
 switch

- Place the button to the left of the switch on toggle controls
- It sat on top of the switch thumb on hover
- Header navigation: found on the Menu Item's "Enable link" toggle, which the button was covering
---
 .../bindingAffordancePosition.test.tsx        | 94 +++++++++++++++++++
 .../DynamicBindingControl.module.css          |  9 ++
 .../DynamicBindingControl.tsx                 |  1 +
 3 files changed, 104 insertions(+)
 create mode 100644 src/__tests__/property-controls/bindingAffordancePosition.test.tsx

diff --git a/src/__tests__/property-controls/bindingAffordancePosition.test.tsx b/src/__tests__/property-controls/bindingAffordancePosition.test.tsx
new file mode 100644
index 000000000..8ed8f6b46
--- /dev/null
+++ b/src/__tests__/property-controls/bindingAffordancePosition.test.tsx
@@ -0,0 +1,94 @@
+/**
+ * Data-binding affordance — position on toggle controls.
+ *
+ * The `{}` button sits in the control's top-right corner. A toggle row ends in
+ * a switch whose thumb occupies exactly that corner, so on toggles the button
+ * must move to the left of the switch instead of covering it.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { readFileSync } from 'fs'
+import { cleanup, render, screen } from '@testing-library/react'
+import { DynamicBindingControl } from '@site/property-controls/DynamicBindingControl'
+import { clearDataMetaCache } from '@admin/shared/DataBindingPicker/cache'
+import type { PropertyControl } from '@core/module-engine'
+
+const BINDING_CSS = readFileSync(
+  new URL('../../admin/pages/site/property-controls/DynamicBindingControl/DynamicBindingControl.module.css', import.meta.url),
+  'utf8',
+)
+const SWITCH_CSS = readFileSync(
+  new URL('../../ui/components/Switch/Switch.module.css', import.meta.url),
+  'utf8',
+)
+
+const originalFetch = globalThis.fetch
+
+beforeEach(() => {
+  clearDataMetaCache()
+  globalThis.fetch = (async () =>
+    new Response(JSON.stringify({ meta: { tables: [] } }), { status: 200 })) as unknown as typeof fetch
+})
+
+afterEach(() => {
+  cleanup()
+  clearDataMetaCache()
+  globalThis.fetch = originalFetch
+})
+
+function renderAffordance(control: PropertyControl) {
+  render(
+    <DynamicBindingControl propKey="myProp" label="My prop" control={control} onSet={() => {}} onClear={() => {}}>
+      <input aria-label="My prop" />
+    </DynamicBindingControl>,
+  )
+  return screen.getByRole('button', { name: 'Bind My prop' })
+}
+
+/** The declarations of the first rule whose selector is exactly `selector`. */
+function ruleBody(css: string, selector: string): string {
+  const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const match = new RegExp(`(?:^|\\})\\s*${escaped}\\s*\\{([^}]*)\\}`, 'm').exec(css.replace(/\/\*[\s\S]*?\*\//g, ''))
+  if (!match) throw new Error(`No rule for ${selector}`)
+  return match[1]
+}
+
+function px(body: string, property: string): number {
+  const match = new RegExp(`(?:^|[;\\s])${property}:\\s*(\\d+)px`).exec(body)
+  if (!match) throw new Error(`No px value for ${property}`)
+  return Number(match[1])
+}
+
+const BESIDE_SWITCH = '.affordanceBtn[data-placement="beside-switch"]'
+
+describe('binding affordance position', () => {
+  it('marks the button as beside the switch on a toggle control', () => {
+    const button = renderAffordance({ type: 'toggle', label: 'My prop' })
+    expect(button.getAttribute('data-placement')).toBe('beside-switch')
+  })
+
+  it('keeps the corner position on every other bindable control', () => {
+    const others: PropertyControl[] = [
+      { type: 'text', label: 'My prop' },
+      { type: 'url', label: 'My prop' },
+      { type: 'number', label: 'My prop' },
+      { type: 'image', label: 'My prop' },
+    ]
+    for (const control of others) {
+      const button = renderAffordance(control)
+      expect(button.hasAttribute('data-placement')).toBe(false)
+      cleanup()
+    }
+  })
+
+  it('offsets the marked button by more than the switch is wide, so the two cannot overlap', () => {
+    const switchWidth = px(ruleBody(SWITCH_CSS, '.track'), 'width')
+    const offset = px(ruleBody(BINDING_CSS, BESIDE_SWITCH), 'right')
+    expect(offset).toBeGreaterThan(switchWidth)
+  })
+
+  it('would overlap the switch at the default corner position, which is why toggles need the offset', () => {
+    expect(px(ruleBody(BINDING_CSS, '.affordanceBtn'), 'right')).toBeLessThan(
+      px(ruleBody(SWITCH_CSS, '.track'), 'width'),
+    )
+  })
+})
diff --git a/src/admin/pages/site/property-controls/DynamicBindingControl/DynamicBindingControl.module.css b/src/admin/pages/site/property-controls/DynamicBindingControl/DynamicBindingControl.module.css
index fad292c55..bc04ec1eb 100644
--- a/src/admin/pages/site/property-controls/DynamicBindingControl/DynamicBindingControl.module.css
+++ b/src/admin/pages/site/property-controls/DynamicBindingControl/DynamicBindingControl.module.css
@@ -19,6 +19,15 @@
     border-radius: var(--radius-sm);
 }
 
+/*
+ * A toggle row ends in a 38px switch, whose thumb sits exactly where the
+ * default corner position would put the button. Sit to the left of it.
+ */
+.affordanceBtn[data-placement="beside-switch"] {
+    top: 5px;
+    right: 44px;
+}
+
 .affordanceWrapper:hover .affordanceBtn,
 .affordanceWrapper:focus-within .affordanceBtn {
     opacity: 0.7;
diff --git a/src/admin/pages/site/property-controls/DynamicBindingControl/DynamicBindingControl.tsx b/src/admin/pages/site/property-controls/DynamicBindingControl/DynamicBindingControl.tsx
index 68e6a03fc..70368bb14 100644
--- a/src/admin/pages/site/property-controls/DynamicBindingControl/DynamicBindingControl.tsx
+++ b/src/admin/pages/site/property-controls/DynamicBindingControl/DynamicBindingControl.tsx
@@ -189,6 +189,7 @@ export function DynamicBindingControl({
           size="xs"
           iconOnly
           className={styles.affordanceBtn}
+          data-placement={control.type === 'toggle' ? 'beside-switch' : undefined}
           aria-label={insertMode ? `Insert binding for ${label}` : `Bind ${label}`}
           aria-expanded={pickerOpen}
           tooltip={insertMode ? 'Insert data token' : 'Bind to data field'}

From 985e5bbc233e9745517dcdfa4396627fda1f5f7e Mon Sep 17 00:00:00 2001
From: Quynn Bell <quynnbell@protonmail.com>
Date: Mon, 12 Oct 2026 10:39:09 -0700
Subject: [PATCH 7/7] docs(modules): document the navigation modules and new
 module options

- Add a guide to building a menu with base.nav and base.nav-item
- Document instanceCss, canvasCss and canvasViewportWidth
- Document number presets, select icons and the URL field rules
- Header navigation: the docs for the feature and for each piece added to support it
---
 docs/editor.md                           |  2 +-
 docs/features/canvas-iframe-per-frame.md |  4 +-
 docs/features/modules.md                 | 75 ++++++++++++++++++++++++
 docs/features/plugin-system.md           |  2 +
 docs/reference/module-engine.md          | 10 +++-
 5 files changed, 89 insertions(+), 4 deletions(-)

diff --git a/docs/editor.md b/docs/editor.md
index 8ed3fdb9b..f8e5e73bd 100644
--- a/docs/editor.md
+++ b/docs/editor.md
@@ -426,7 +426,7 @@ Each iframe `<head>` receives five `<style>` elements (three from `ClassStyleInj
 | Element | Injector | Cascade layer | Contents |
 |---|---|---|---|
 | `<style id="instatic-editor-chrome">` | `EditorChromeInjector` | **unlayered** | Editor-only chrome: placeholder, slot-instance, list placeholder, unknown-module fallback |
-| `<style id="mc-classes">` | `ClassStyleInjector` | `@layer user-authored` | Publisher reset + framework CSS + class registry CSS |
+| `<style id="mc-classes">` | `ClassStyleInjector` | `@layer user-authored` | Publisher reset + framework CSS + module `canvasCss` + class registry CSS |
 | `<style id="mc-classes-preview">` | `ClassStyleInjector` | `@layer user-authored` | Higher-specificity preview rule while a property control is hovered; empty for state-pseudo rules |
 | `<style id="mc-classes-force-state">` | `ClassStyleInjector` | `@layer user-authored` | Forced state preview: paints the active state-pseudo rule onto the selected node via a doubled `[data-node-id]` selector |
 | `<style id="mc-user-styles">` | `UserStylesheetInjector` | `@layer user-authored` | User-uploaded stylesheets (verbatim, unscoped) |
diff --git a/docs/features/canvas-iframe-per-frame.md b/docs/features/canvas-iframe-per-frame.md
index 201ea3355..afb560080 100644
--- a/docs/features/canvas-iframe-per-frame.md
+++ b/docs/features/canvas-iframe-per-frame.md
@@ -38,7 +38,7 @@ IframeFrameSurface
   <iframe srcDoc="<!doctype html><html>…">
     (inside iframe document, via createPortal)
     ├── EditorChromeInjector   (head: unlayered editor chrome CSS)
-    ├── ClassStyleInjector     (head: @layer user-authored — publisher reset + class registry)
+    ├── ClassStyleInjector     (head: @layer user-authored — publisher reset + module canvasCss + class registry)
     ├── UserStylesheetInjector (head: @layer user-authored — user-uploaded stylesheets)
     ├── {children}             (body: React node tree via NodeRenderer)
     └── RuntimeScriptInjector (body: opt-in runtime scripts when "Run scripts" is on)
@@ -124,7 +124,7 @@ Five `<style>` elements are injected per iframe (three from `ClassStyleInjector`
 | Injector | `id` attribute | Cascade layer | Purpose |
 |---|---|---|---|
 | `EditorChromeInjector` | `instatic-editor-chrome` | **unlayered** | Editor chrome: placeholder, slot-instance, unknown-module styles. Copies safe required design tokens from parent `:root` onto iframe `:root`. The editor UI font, admin text-size tokens, and admin spacing tokens are forwarded as **chrome-namespaced** `--chrome-font-sans`, `--chrome-text-*`, and `--chrome-space-*` aliases, not as `--font-sans`, `--text-*`, or `--space-*`, because the injector is unlayered and would otherwise clobber the site's own Framework tokens. |
-| `ClassStyleInjector` | `mc-classes` | `@layer user-authored` | Publisher reset + framework CSS + class registry CSS |
+| `ClassStyleInjector` | `mc-classes` | `@layer user-authored` | Publisher reset + framework CSS + module `canvasCss` + class registry CSS, in the order `publishPage()` emits them |
 | `ClassStyleInjector` | `mc-classes-preview` | `@layer user-authored` | Higher-specificity preview rule (doubled selector) while a property control is hovered. Empty for state-pseudo rules — those use `mc-classes-force-state` instead. |
 | `ClassStyleInjector` | `mc-classes-force-state` | `@layer user-authored` | Force-paints the active state-pseudo rule (`.btn:hover`, `.card:focus`, etc.) onto the selected node via a doubled `[data-node-id]` selector so the state is visible/editable without physically triggering it. Mirrors the full `contextStyles` emission per breakpoint and condition. |
 | `UserStylesheetInjector` | `mc-user-styles` | `@layer user-authored` | User-uploaded stylesheets (verbatim, unscoped) |
diff --git a/docs/features/modules.md b/docs/features/modules.md
index b61509d49..702d69816 100644
--- a/docs/features/modules.md
+++ b/docs/features/modules.md
@@ -41,6 +41,8 @@ src/modules/base/
 ├── outlet/              — base.outlet (Content Outlet — template content slot)
 ├── button/              — base.button (anchor.ts — element-decision leaf)
 ├── link/                — base.link (content.ts — children/text fallback leaf)
+├── nav/                 — base.nav (nav bar that collapses to a dropdown or overlay, icons.ts/navCss.ts/navRuntimeJs.ts leaves)
+├── nav-item/            — base.nav-item (nestable menu entries, linked or submenu-toggle labels, content.ts/navItemCss.ts/navItemRuntimeJs.ts leaves)
 ├── image/               — base.image
 ├── svg/                 — base.svg (inline sanitized SVG)
 ├── video/               — base.video (youtube.ts — ID parse + embed URL leaf)
@@ -136,6 +138,9 @@ interface ModuleDefinition<TProps extends Record<string, unknown>> {
   /** React component for the editor canvas live preview. */
   component: React.ComponentType<ModuleComponentProps<TProps>>
 
+  /** Optional stylesheet for `component`. Trusted modules only. See "Canvas stylesheet". */
+  canvasCss?: string
+
   /**
    * Optional dependency-backed editor runtime. When present, the canvas renders
    * this module in a sandboxed iframe with an import map built from the module's
@@ -157,6 +162,10 @@ interface ModuleDefinition<TProps extends Record<string, unknown>> {
 
 Constraint #179: **`render()` is pure** — no DOM, no React, no side effects. Inputs in, strings out.
 
+`render()` may also return `instanceCss`. This is CSS that depends on that instance's props, which `css` cannot carry because only the first instance's `css` is kept per moduleId. The publisher deduplicates `instanceCss` by content, so instances producing the same string share one block. Keep it to the prop-dependent rules. Example: `base.nav` emits the media query for its author-chosen collapse width this way, for itself and the Menu Items nested inside it.
+
+Plugin modules cannot return `instanceCss`. The plugin module adapter (`src/core/plugins/moduleAdapter.ts`) forwards only `html`, `css`, and `js` from a plugin's `render()`, so any other field is dropped. A plugin module that needs per-instance styling writes the value into its `html` (a `style` attribute or a custom property) and keeps the rules that read it in `css`.
+
 `render()` may also return `js` next to `html`/`css` — an optional vanilla-JS runtime for the module TYPE, deduplicated per moduleId (like CSS) and served as an external file at `/_instatic/module-js/<moduleId>.js` on published pages. Authoring contract: a self-contained IIFE; bind via document-level event delegation (hole fragments insert into the DOM after load); idempotent; no load-order assumptions; no framework runtimes. Size discipline in the spirit of the ~1 KB hole runtime — the ~8 KB form runtime is the ceiling, not the norm. Module JS never executes in the admin canvas: the canvas renders React editor components, never published render() output.
 
 ---
@@ -198,6 +207,12 @@ schema: PropertySchema = {
 | `svg`       | Inline SVG editor                                         | SVG markup string               |
 | `group`     | Collapsible section header (visual grouping only)         | — (no data shape change)        |
 
+A `number` control may carry `presets` (an array of numbers). They render as one-click buttons under the field, which still accepts any number. Example: `base.nav`'s "Collapse below" width.
+
+A `select` option may carry `iconSvg` (inline SVG markup). When any option has one, the control renders as an icon button row (`<SegmentedControl>`) with each option's `label` as its tooltip, instead of a dropdown. The markup is passed through `sanitizeSvg` before rendering. Example: `base.nav`'s "Menu icon" picker.
+
+A `url` control has two modes: **URL** (free text) and **Page** (pick a CMS page, stored as a `cms:page:<id>` reference that survives slug renames). In URL mode the field accepts `https:`, `http:`, `mailto:`, `tel:`, and `sms:` URLs, and site-relative links: a root path (`/about`), a fragment (`#pricing`), a query (`?page=2`), or a dot path (`./a`, `../a`). It rejects every other scheme, a bare word such as `about` or `example.com`, and protocol-relative `//host`. The rule is `isValidUrl` in `src/core/utils/urlValidation.ts`. While the text is not yet valid the field keeps what is being typed and shows "Invalid URL"; the prop is written once the text is valid, and leaving the field drops an unfinished entry.
+
 `PropertyControl` is a discriminated union — `propertySchema.ts` has the full schema.
 
 ### Conditional controls
@@ -324,9 +339,28 @@ interface ModuleComponentProps<TProps> {
    * undefined outside the editor (publisher, plugin sandbox preview).
    */
   nodeWrapperProps?: NodeWrapperProps
+  /** Set only while this node is being inline-edited in this frame. See canvas-iframe-per-frame.md → "Inline text editing". */
+  inlineEdit?:       InlineEditBinding
+  /**
+   * Pixel width of the breakpoint frame this component renders in (375 in a
+   * mobile frame). undefined outside the editor, for sandboxed plugin modules,
+   * and in agent snapshot rendering.
+   */
+  canvasViewportWidth?: number
 }
 ```
 
+`canvasViewportWidth` exists because a media query in the canvas matches the iframe, and module CSS and JS from `render()` never run there. A component that changes layout at a width compares the prop against that width itself. Treat `undefined` as "render the default layout". Example: `NavEditor` marks the nav collapsed when `canvasViewportWidth <= collapseBreakpoint`.
+
+### Canvas stylesheet (`canvasCss`)
+
+The canvas never loads `render().css`. Most editor components do not need it: they render the same elements and are styled by the author's classes. A component whose preview needs real rules (an ancestor's state, `:has()`, hover) declares them in `canvasCss` on the module definition.
+
+- **Where it lands.** `ClassStyleInjector` collects `canvasCss` from every trusted module (`collectModuleCanvasCss`) and puts it in each frame's `mc-classes` sheet, inside `@layer user-authored`: after the publisher reset and framework CSS, before class registry CSS and user stylesheets. That is the position `publishPage()` gives module CSS, so an author's class or a global `a { … }` rule wins or loses against the module exactly as it does when published.
+- **Write the published selectors.** Use the same class names and specificity as `render().css`. Do not style the preview with inline `style` props: an inline style beats every author class in the canvas and none when published. A dynamic custom property that `render()` also emits is fine.
+- **Share the rules.** Build both sheets from one function when the canvas differs only in what triggers a rule. `base.nav` and `base.nav-item` generate their collapse rules from a `scope` selector and an `open` selector (`nav/navCss.ts`, `nav-item/navItemCss.ts`). Published, those are the `[data-instatic-nav-collapse="<width>"]` attribute inside a media query and the state attribute module JS sets. In the canvas they are `[data-instatic-nav-canvas="collapsed"]`, which `NavEditor` stamps from `canvasViewportWidth`, and "this node or a node inside it is selected" (`shared/navCollapse.ts`).
+- **Trusted modules only.** A plugin module's component renders in a sandbox frame this stylesheet never reaches, and the string is injected unsanitised, so `canvasCss` on an untrusted module is ignored.
+
 **Spreading `nodeWrapperProps` is mandatory.** Every module editor component must spread `nodeWrapperProps` onto its root JSX element and apply `mcClassName` as the class. Without this the node is invisible to the editor's interaction layer (selection, hover, keyboard). Example:
 
 ```tsx
@@ -458,6 +492,47 @@ Modules don't need to know — they just receive resolved props.
 
 At render time, `resolveDynamicProps(...)` substitutes the bound value. Used inside loops (the entry stack supplies `currentEntry`) and inside entry templates (the published row supplies `currentEntry`).
 
+### Build a navigation menu
+
+A menu is one `base.nav` (Header Navigation) with `base.nav-item` (Menu Item) nodes inside it. Nest Menu Items inside a Menu Item to make a submenu, to any depth. The page tree is the menu structure.
+
+`base.nav` props:
+
+| Prop                 | Panel label       | Effect |
+|----------------------|-------------------|--------|
+| `ariaLabel`          | Accessible name   | `aria-label` on the `<nav>`. Omitted when empty. |
+| `toggleLabel`        | Menu button label | Screen-reader-only text for the collapsed menu button. |
+| `collapseBreakpoint` | Collapse below    | Viewport width in px at or below which the menu button replaces the row. `0` never collapses. |
+| `collapsedStyle`     | Collapsed menu    | `dropdown` (panel under the nav) or `overlay` (covers the screen). |
+| `menuBackground`     | Menu background   | Background of the collapsed menu and of submenus. Empty uses the `Canvas` system colour: the browser's page background for the active colour scheme, not the site's body colour. Set it on a site with a dark background. |
+| `toggleIcon`         | Menu icon         | Glyph on the menu button. |
+| `toggleIconColor`    | Menu icon color   | Empty inherits the surrounding text colour. |
+| `menuAlign`          | Menu alignment    | Where the items sit in the bar. Collapsed, where the menu button sits. |
+
+`base.nav-item` props:
+
+| Prop     | Panel label | Effect |
+|----------|-------------|--------|
+| `label`  | Label       | The item text. |
+| `isLink` | Enable link | On by default. Off makes the item a static label and hides Link and Target. The stored `href` is kept for turning it back on. |
+| `href`   | Link        | A `url` control: a URL or a CMS page. |
+| `target` | Target      | Same tab or new tab. |
+
+What `isLink` renders:
+
+| `isLink` | Has a submenu | Label element | Submenu toggle |
+|----------|---------------|---------------|----------------|
+| on       | no            | `<a>`         | none |
+| on       | yes           | `<a>`         | a separate caret `<button>` beside the label |
+| off      | yes           | `<button>`    | the label itself: clicking it opens the submenu |
+| off      | no            | `<span>`      | none |
+
+Turn `isLink` off for a parent item that only groups a submenu, so that a tap on the label opens the submenu and does not navigate.
+
+A submenu opens on hover or keyboard focus at desktop widths, and from its toggle at every width. Escape or a click outside an open item closes it.
+
+Every class the two modules emit starts with `instatic-nav`, so author CSS can target them without colliding with site classes.
+
 ---
 
 ## Forbidden patterns
diff --git a/docs/features/plugin-system.md b/docs/features/plugin-system.md
index d07fa28f4..f36bdc6d5 100644
--- a/docs/features/plugin-system.md
+++ b/docs/features/plugin-system.md
@@ -604,6 +604,8 @@ See [docs/features/publisher.md](publisher.md) for the full three-layer pipeline
 
 ### Module JS on published pages — requires `frontend.assets`
 
+A plugin module's `render()` returns `html`, `css`, and optionally `js`. Nothing else crosses: `moduleAdapter.ts` drops `instanceCss`, and a plugin module has no `canvasCss`, because both are first-party module features that bypass sanitisation or the sandbox frame.
+
 A plugin module's `render()` may return `js` (see `PluginRenderOutput`). It crosses the QuickJS boundary string-typed (non-strings are dropped by the VM normalizer) and is then gated host-side in `moduleAdapter.ts`: unless the plugin's **granted** permissions include `frontend.assets` — the same authority that already controls script tags via `frontend.assets[]` — the `js` is dropped with one `console.warn` per module. Enforcement always checks `grantedPermissions`, never the declared `permissions` array. With the grant, the JS is deduped per moduleId and served at `/_instatic/module-js/<moduleId>.js` on pages that use the module. Manifest format is unchanged.
 
 ### Frontend assets — requires `frontend.assets`
diff --git a/docs/reference/module-engine.md b/docs/reference/module-engine.md
index 21142596f..7fbc1e9e0 100644
--- a/docs/reference/module-engine.md
+++ b/docs/reference/module-engine.md
@@ -88,7 +88,7 @@ That's the whole feature loop: module picker, Properties Panel, publisher, CSS d
 
 ```ts
 render: (props: TProps, renderedChildren: string[]) => RenderOutput
-// RenderOutput = { html: string; css?: string }
+// RenderOutput = { html: string; css?: string; instanceCss?: string; js?: string }
 ```
 
 ### `props` is trusted (after escaping)
@@ -150,6 +150,12 @@ The `schema` field maps prop keys to `PropertyControl` descriptors. Full union i
 | `svg`       | Inline SVG editor                                 | SVG markup string        |
 | `group`     | Collapsible section (visual grouping, no data)    | — (children record)      |
 
+A `number` control may carry `presets` (an array of numbers). They render as one-click buttons under the field, which still accepts any number. Example: `base.nav`'s "Collapse below" width.
+
+A `select` option may carry `iconSvg` (inline SVG markup). When any option has one, the control renders as an icon button row (`<SegmentedControl>`) with each option's `label` as its tooltip, instead of a dropdown. The markup is passed through `sanitizeSvg` before rendering. Example: `base.nav`'s "Menu icon" picker.
+
+A `url` control accepts `https:`, `http:`, `mailto:`, `tel:`, and `sms:` URLs and site-relative links (`/about`, `#pricing`, `?page=2`, `./a`, `../a`). Bare words and protocol-relative `//host` are rejected. This input rule (`isValidUrl`) is narrower than the publisher's `isSafeUrl`, which also lets through any other schemeless value. Detail: [docs/features/modules.md](../features/modules.md) → "Control types".
+
 ### Conditional controls
 
 ```ts
@@ -241,6 +247,8 @@ export const HeadingEditor: React.FC<ModuleComponentProps<HeadingProps>> = ({
 - Apply `mcClassName` as the root element's class. Without it the author's CSS class rules don't apply in the canvas.
 - Produce the same DOM structure as `render()` — canvas selection geometry, drop-target detection, and dimension measurement assume parity.
 - `nodeWrapperProps` is `undefined` outside the editor (publisher, plugin preview). Components that check for its presence can render a plain published element when it's absent.
+- `canvasViewportWidth` is the pixel width of the breakpoint frame the component renders in. Use it when the layout changes at a width, because a media query in the canvas matches the iframe and module CSS never loads there. It is `undefined` for sandboxed plugin modules and agent snapshot rendering.
+- Do not style the preview with inline `style` props. They beat every author class in the canvas and none when published. Put the rules in the module's `canvasCss`, which the canvas injects where the publisher puts module CSS. Trusted modules only. See [docs/features/modules.md](../features/modules.md) → "Canvas stylesheet".
 - **`*Editor.tsx` must only export React components.** Exporting utilities, types, or constants from the editor file breaks React Fast Refresh HMR — Vite can only hot-patch a component file when every export is a component.
 
 ### Sharing logic between `index.ts` and `*Editor.tsx`