Update FF theme to align with Node-RED 5.0.0-beta-5

[n-lark]

Update FF theme to align with Node-RED 5.0-beta-5

Node-RED 5.0-beta-5 builds are now deployed on Staging (not pre-staging)

Current theme clashes

With the new Node-RED 5.0-beta-5 theme, we need to make some adjustments to the flowfuse theme.

Considerations

• Current custom theme embeds some links in the toolbars - we will want to keep those.
• When you pop out node-RED into a new window, we need to keep the links to go back to FF in the header.
• Should we ditch our theme for light/dark and use the new built in themes? If we do, need to remove our option to change theme from settings.
• We will not want to merge this until Node-RED beta is live - since it could mess with existing stylez.

From Ben:

FYI, this NR5.0 Stack is just a snapshot in time running 2.29.1 nr-launcher and themes, it won't auto update to follow the head of it's dependent projects, but I can respin when ever needed

[n-lark]

Node-RED Theme Cleanup

Problem

FlowFuse ships custom forge-light / forge-dark Node-RED theme plugins. Node-RED 5 ships its own native light/dark toggle — but our custom themes register as node-red-theme plugins, which hides the built-in light/dark themes. The work to fix that is under UX: create mechanism for themes to provide multiple variants #5534

Our theme plugins also carry forge-common.js — the script that injects the FlowFuse menu items (About FlowFuse, FlowFuse Application link, logo/logout intercept). Any fix has to keep that working.

Goal

• Drop FF theme CSS (forge-light, forge-dark)
• Use Node-RED's native light/dark
• Keep forge-common.js menu behavior
• Only apply on Node-RED 5+ (gate by version)

Core constraint

Node-RED only serves a plugin's scripts array if it's a type: 'node-red-theme' plugin set as the active theme. Plain plugins can register scripts, but NR never exposes them to the editor.

So dropping our theme plugin also drops forge-common.js. Something has to change to separate the two.

Options

#	Approach	Upstream NR work	FF-side work	Fit
1	Stub theme plugin — empty variants, carries forge-common.js scripts	#5625 Variants API (already planned)	Reshape one plugin, delete CSS	Weak — plugin is registered as a "theme" but provides no theming; just carries scripts
2	Separate upstream change: allow non-theme plugins to serve scripts/css	Small new PR	Split forge-common.js into standalone flowfuse-menu plugin	Clean separation — but broadens the editor-script surface: today only the active theme plugin can inject JS; this lets any installed plugin do it. Might be SUS.
3	editorTheme.page.scripts config path in generated settings.js	None	Ship a second file to pass FF settings as globals	Works but awkward plumbing

How Option 3 works

Node-RED has a second way to load scripts into the editor, independent of the plugin system: any path listed under editorTheme.page.scripts in settings.js gets served to the browser (theme.js:267-276).

So without any upstream NR change, nr-launcher could generate a settings.js like:

editorTheme: {
    // no `theme:` key — native dark toggle stays visible
    page: {
        scripts: ['/path/to/forge-common.js']
    }
}

forge-common.js loads, menu items appear, no theme plugin involved, native light/dark toggle works.

The awkward part: forge-common.js currently reads projectURL and launcherVersion from RED.settings['forge-light'] — values that only reach the browser today because the theme plugin exports them. Without the plugin, we'd need to ship a second generated file (e.g. forge-runtime.js) that sets those values as globals on window, and list both files in editorTheme.page.scripts. Two files and manual global plumbing instead of the clean RED.settings[pluginId] mechanism.

Recommendation

Option 1 if we want the smallest upstream surface — we're already doing UX: create mechanism for themes to provide multiple variants node-red/node-red#5534
Option 2 if we want the cleanest architecture — small additional upstream PR.

Both require a version gate so the behavior only kicks in on Node-RED 5+.

Version gate

options.versions['node-red'] is already read at launcher startup (packages/nr-launcher/index.js:91-97). Pipe it through runtimeSettings.js and skip the FF theme registration when major ≥ 5.

Call to make

Is "empty variants" a legitimate shape in the UX: create mechanism for themes to provide multiple variants node-red/node-red#5534, or an anti-pattern?

• Legitimate → Option 1 is the easiest path.
• Anti-pattern → go with Option 2 (one extra small NR PR).

[knolleary]

Another requirement to factor in. We have OEM user who applies their own theme plugin that has a hard requirement to not have any node-red/flowfuse mention.

The current FF theme plugin approach for the customisations works for them as they provide their own plugin so none of our FF menu items etc get added. If we were to move that out of the theme plugin to a hard coded settings thing, this customer would require a way to disable it.

I will think more on what we need to do for theme plugins to work nicely with this.

[knolleary]

I have outlined how we'll support theme plugins with multiple light/dark themes here: node-red/node-red#5534 (comment)

In summary, the theme will declare the colour schemes it includes, and the editor will do the right thing with that information.

[n-lark]

NR5 forge theme — details & test plan

Currently moved this work into BLOCKED since we do not want to move on this until Node-RED 5.0 is out in the wild.

A new forge Node-RED 5+ theme plugin lives alongside the legacy forge-light / forge-dark plugins. NR<5 stacks keep the legacy path untouched; NR5+ stacks route through forge.

PRs

Repo	PR	Title
FlowFuse/nr-launcher	#533	[7100] Update FF theme to align with Node-RED 5.0.0-beta-5
FlowFuse/device-agent	#626	[7100] Update FF theme to align with Node-RED 5.0.0-beta-5
FlowFuse/flowfuse	#7185	[7100] Update FF theme to align with Node-RED 5.0.0

Related upstream

• Node-RED PR: [5696] editorTheme.header.title: long values clip without ellipsis, and misalign when header.url is set node-red/node-red#5697

What changed

See summary of files changed

Area	File	Change	Description
Plugin	nr-launcher/lib/theme/forge/forge.js	add	Declares schemes: ['light','dark']. No monacoOptions (schemes API doesn't switch them per-scheme).
Plugin	nr-launcher/lib/theme/forge/forge-common.js	add	Menu script. Vs legacy: reads RED.settings['forge']; loose .red-ui-header-logo a selector; navigateTo keys off context.isEmbedded.
Plugin	nr-launcher/lib/theme/forge/forge.css	add	Minimal: --red-ui-header-height: 45px, title font-weight: 600, #usermenu-item-fflv styling, FF logo SVG overlay on the header <img> (CSS background trick from the legacy theme). Drops FF colors / scrollbars / Cascadia Code.
Registration	nr-launcher/package.json	modify	Register forge plugin (hosted instances).
Registration	nr-launcher/lib/theme/package.json	modify	Register forge plugin (devices via @flowfuse/nr-theme).
Server	nr-launcher/lib/launcher.js	modify	Pipe nodeRedVersion into this.settings.
Server	nr-launcher/lib/runtimeSettings.js	modify	Theme mapping: forge-light/forge-dark/forge → forge on NR5+; forge → forge-light on NR<5; others pass through.
Server	device-agent/lib/launcher.js	modify	Same gate at device-agent settings generation (NR version from this.snapshot?.modules?.['node-red']).
Frontend	flowfuse/frontend/src/utils/instanceVersion.ts	add	Shared isInstanceOnNR5Plus(target) helper — accepts instance and device shapes.
Frontend	flowfuse/frontend/src/pages/admin/Template/sections/Editor.vue	modify	defaultThemes computed: single FlowFuse → forge on NR5+ instance settings; legacy Light / Dark elsewhere. Custom typing always allowed.
Frontend	flowfuse/frontend/src/pages/instance/Settings/Editor.vue	modify	getSettings() lazy-normalizes forge-light/forge-dark → forge on NR5+ load. No change indicator; DB migrates on next save.
Frontend	flowfuse/frontend/src/pages/{instance,device}/Editor/index.vue	modify	Pass :is-nr5-plus to DrawerTrigger.
Frontend	flowfuse/frontend/src/components/immersive-editor/DrawerTrigger.vue	modify	isNr5Plus prop shifts top to clear NR5's shorter header (110px default / 55px fullscreen).
Test	flowfuse/test/unit/frontend/utils/instanceVersion.spec.js	add	Vitest coverage of the helper.

Untouched (deliberate): nr-launcher/lib/theme/forge-light/, forge-dark/, common/forge-common.{js,css}, and flowfuse/forge/lib/templates.js — default theme: 'forge-light' is fine, runtime gate handles NR5+ migration.

---

Test plan

✅ All tests passed!

NR5+ instance

• Restart instance → var/projects/<id>/settings.js has theme: 'forge' (regardless of stored value).
• Editor: NR5 native scheme selector visible; Auto/Light/Dark recolors via nr-theme-dark.
• Main menu: About FlowFuse, FlowFuse Application (top-level nav, not iframe-internal), FlowFuse Launcher v (non-clickable).
• Header: 45px tall, FF logo (red SVG mark) shown via CSS overlay, title at font-weight: 600.
• Logo / Title / logout clicks navigate the parent window correctly.
• Favicon: FF favicon. RED.settings.forge populated in DevTools.
• Popout window: same behavior — FF Application link still navigates to FF.
• Drawer trigger: positioned at top: 110px default / 55px fullscreen. Same on the device editor.

Intentional visual deltas (vs legacy)

• NR5 native colors (not FF blue-purple), shorter header, no red border, no FF logo, NR's default Monaco theme, native scrollbars.
• Title alignment / ellipsis / tooltip is broken until the NR5 upstream fix lands.

NR<5 instance (must be pixel-identical to today)

• Stored forge-light / forge-dark → settings.js unchanged → legacy plugin loads.
• Stored forge (e.g. from a future template) → runtime gate maps to forge-light.
• Drawer trigger keeps legacy positions (70px / 10px).

Devices

• Device on NR5+ snapshot → device-agent's local settings.json has theme: 'forge'; NR loads the new plugin; visual changes (45px header, title weight 600, FF menu items in sidemenu) appear in the editor.
• Device on NR<5 snapshot → theme reverts to 'forge-light' (or passes through for custom values).

Known limitation (pre-existing, not addressed here): click handlers on the device editor's header logo / "FlowFuse Application" menu item / logout do nothing. The forge plugin (and the legacy theme before it) wires these via postMessage to the parent FF window, but the device editor's wrapper component (RemoteInstanceEditorWrapper.vue) doesn't listen for those messages, and device-agent's editorTheme doesn't set header.url so the logo isn't even an <a>. Both predate this PR; fixing them is a separate scoped change.

Admin & UI

• Admin → Templates → Editor: dropdown shows FlowFuse Light / FlowFuse Dark. Custom typing accepted.
• Instance Settings → Editor on NR5+: dropdown shows single FlowFuse → forge. Custom typing accepted (OEM themes work).
• Instance Settings → Editor on NR<5: dropdown shows Light / Dark (current behavior).
• Lazy migration: open NR5+ instance settings with stored forge-light/forge-dark → input shows forge, no change indicator. DB migrates only on next save.

OEM

• Third-party theme plugin (e.g. node-red-contrib-theme-midnight-red) set as theme: NR loads the OEM plugin, no FF menu items, OEM theme renders. Same on devices. Dropdown stays editable so OEM value can be modified from the UI.

---

Ship plan

Non-breaking. NR<5 stacks, OEM themes, and legacy device snapshots all keep their current behavior — every change is additive and the runtime gate only fires on NR5+. All three PRs need to be live for the full NR5+ experience; until then, NR5+ falls back to partial states.

Order caveat: don't deploy FlowFuse/flowfuse to production before FlowFuse/nr-launcher is live — the lazy migration writes theme: 'forge' to the DB, and the launcher needs to know what forge is or NR5+ editors regress.

Hold the customer-facing NR5 push until Node-RED 5 GA — visual changes are easier to defend against a stable upstream.