dazscript-framework 1.0.7 → 1.0.9

package/README.md

@@ -299,6 +299,16 @@ Custom action icons are selected from `action(...)` metadata and sibling image f
 
 `scriptname.action.png` is the installed custom action icon. Daz Studio uses the same action icon for menu and toolbar placements. `scriptname.png` is the preferred script/content icon fallback. `scriptname.dsa.png` is a legacy fallback kept for older projects and will be removed in a future breaking release.
 
+Setup dialog header assets are optional and are discovered beside `src/Setup.dsa.ts`:
+
+1. `src/Setup.header.png`
+2. `src/Setup.png`
+3. `src/Setup.dsa.png` legacy fallback
+
+Header text can be placed in `src/Setup.header.html`, `src/Setup.header.md`, or `src/Setup.header.txt`, with `src/Setup.html`, `src/Setup.md`, and `src/Setup.txt` as script-named fallbacks. The installer generator embeds that text into `Setup.dsa.ts`, so Daz Studio does not need to read the text file at setup time. The setup dialog renders the header body with `DzTextBrowser` rich text support; no Markdown conversion is performed. The image remains a deployed PNG asset and is resolved relative to the generated setup script at runtime.
+
+The same layout is available to custom dialogs through `add.header({ imagePath, html, text, height, imageWidth }).build()`. Use `html` for rich text, or `text` for escaped plain text.
+
 This replaces the older `Install.dsa.ts` / `Uninstall.dsa.ts` pattern. The installer generator removes those legacy files if they exist.
 
 ### Setup Keyboard Shortcuts

package/dist/scripts/install-generator.js

@@ -276,6 +276,48 @@ function toPosix(filePath) {
   return filePath.replace(/\\/g, '/');
 }
 
+function resolveSetupHeaderImage(workdir) {
+  const candidates = [
+    path.join(workdir, 'src', 'Setup.header.png'),
+    path.join(workdir, 'src', 'Setup.png'),
+    path.join(workdir, 'src', 'Setup.dsa.png'),
+  ];
+  const match = candidates.find((candidate) => fs.existsSync(candidate));
+  return match ? `./${path.basename(match)}` : undefined;
+}
+
+function resolveSetupHeaderTextFile(workdir) {
+  const candidates = [
+    path.join(workdir, 'src', 'Setup.header.html'),
+    path.join(workdir, 'src', 'Setup.header.md'),
+    path.join(workdir, 'src', 'Setup.header.txt'),
+    path.join(workdir, 'src', 'Setup.html'),
+    path.join(workdir, 'src', 'Setup.md'),
+    path.join(workdir, 'src', 'Setup.txt'),
+  ];
+
+  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
+}
+
+function loadSetupHeader(workdir) {
+  const header = {};
+  const imagePath = resolveSetupHeaderImage(workdir);
+  const textFile = resolveSetupHeaderTextFile(workdir);
+
+  if (imagePath) {
+    header.headerImagePath = imagePath;
+  }
+
+  if (textFile) {
+    const text = fs.readFileSync(textFile, 'utf8').trim();
+    if (text) {
+      header.headerText = text;
+    }
+  }
+
+  return header;
+}
+
 function resolveShortcutFile(workdir, config) {
   const configuredPath =
     config.keyboardShortcutsPath ||
@@ -340,6 +382,7 @@ function generateInstallerFiles(workdir, options) {
     settingsPath,
     bundleName,
     shortcutBackupPath: `${appDataPath}/Installer/keyboard-shortcuts-backup.json`,
+    ...loadSetupHeader(workdir),
   };
   if (shortcutData.shortcuts && shortcutData.shortcuts.length > 0) {
     setupOptions.shortcuts = shortcutData.shortcuts;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dazscript-framework",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "author": "Freddy Diaz",
   "license": "MPL-2.0",
   "description": "",

package/src/dialog/builders/dialog-header-builder.ts

@@ -0,0 +1,72 @@
+import LayoutBuilder from './layout-builder'
+import { createWidget } from './widget-builder'
+import { WidgetBuilderContext } from './widgets-builder'
+
+export type DialogHeaderOptions = {
+    image?: Pixmap
+    imagePath?: string
+    imageWidth?: number
+    height?: number
+    html?: string
+    text?: string
+}
+
+const escapeHtml = (value: string): string =>
+    value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;')
+        .replace(/\r?\n/g, '<br>')
+
+export class DialogHeaderBuilder {
+    constructor(
+        private readonly context: WidgetBuilderContext,
+        private readonly options: DialogHeaderOptions
+    ) { }
+
+    build(): DzHBoxLayout {
+        const height = this.options.height ?? 96
+        const imageWidth = this.options.imageWidth ?? height
+        const html = this.options.html ?? (
+            typeof this.options.text === 'string'
+                ? escapeHtml(this.options.text)
+                : ''
+        )
+
+        return LayoutBuilder
+            .create(this.context)
+            .direction('horizontal')
+            .build(() => {
+                this.buildImage(height, imageWidth)
+                this.buildText(html, height)
+            }) as DzHBoxLayout
+    }
+
+    private buildImage(height: number, imageWidth: number): void {
+        const pixmap = this.options.image ?? (
+            this.options.imagePath ? new Pixmap(this.options.imagePath) : null
+        )
+        if (!pixmap) return
+
+        createWidget(this.context).build(DzLabel, (label) => {
+            label.pixmap = pixmap
+            label.scaledContents = true
+            label.setFixedWidth(imageWidth)
+            label.setFixedHeight(height)
+        })
+    }
+
+    private buildText(html: string, height: number): void {
+        if (!html) return
+
+        createWidget(this.context).build(DzTextBrowser, (textBrowser) => {
+            textBrowser.html = html
+            textBrowser.readOnly = true
+            textBrowser.lineWrapMode = DzTextEdit.WidgetWidth
+            textBrowser.wordWrapMode = DzTextEdit.WordWrap
+            textBrowser.setFixedHeight(height)
+        })
+    }
+}

package/src/dialog/builders/widgets-builder.ts

@@ -4,6 +4,7 @@ import CheckBoxBuilder from './checkbox-builder'
 import ColorPickerBuilder from './color-picker-builder'
 import { ComboBoxBuilder } from './combo-box-builder'
 import { ComboEditBuilder } from './combo-edit-builder'
+import { DialogHeaderBuilder, DialogHeaderOptions } from './dialog-header-builder'
 import GroupBoxBuilder from './groupbox-builder'
 import LabelBuilder from './label-builder'
 import LayoutBuilder, { LayoutOrientation } from './layout-builder'
@@ -63,6 +64,10 @@ export class WidgetsBuilder {
         return new LabelBuilder(this.context).text(text)
     }
 
+    header(options: DialogHeaderOptions): DialogHeaderBuilder {
+        return new DialogHeaderBuilder(this.context, options)
+    }
+
     button(text?: string): ButtonBuilder {
         return new ButtonBuilder(this.context).text(text)
     }

package/src/helpers/action-helper.ts

@@ -1,58 +1,11 @@
 import { debug, warn } from '@dsf/common/log'
 import { mainWindow } from '@dsf/core/global'
 import { isGUID } from './string-helper'
+export { normalizeShortcut } from './shortcut-helper'
+import { normalizeShortcut } from './shortcut-helper'
 
 const actionMgr = mainWindow.getActionMgr()
 
-const shortcutTokenMap: { [key: string]: string } = {
-    'CTRL': 'Ctrl',
-    'CONTROL': 'Ctrl',
-    'SHIFT': 'Shift',
-    'ALT': 'Alt',
-    'OPTION': 'Alt',
-    'WIN': 'Win',
-    'WINDOWS': 'Win',
-    'CMD': 'Win',
-    'COMMAND': 'Win',
-    'SPACE': 'Space',
-    'HOME': 'Home',
-    'END': 'End',
-    'INS': 'Ins',
-    'INSERT': 'Ins',
-    'DEL': 'Del',
-    'DELETE': 'Del',
-    'TAB': 'Tab',
-    'BACKSPACE': 'Backspace',
-    'COMMA': 'Comma',
-    'PERIOD': 'Period',
-    'PLUS': 'Plus',
-    'MINUS': 'Minus',
-    'PGUP': 'PgUp',
-    'PAGEUP': 'PgUp',
-    'PGDOWN': 'PgDn',
-    'PGDN': 'PgDn',
-    'LEFT': 'Left',
-    'RIGHT': 'Right',
-    'UP': 'Up',
-    'DOWN': 'Down',
-}
-
-export const normalizeShortcut = (shortcut: string): string => {
-    if (!shortcut) return ''
-
-    return shortcut
-        .split('+')
-        .map(part => part.trim())
-        .filter(Boolean)
-        .map(part => {
-            if (part.length === 1) return part.toUpperCase()
-
-            const key = part.toUpperCase()
-            return shortcutTokenMap[key] || part
-        })
-        .join('+')
-}
-
 export const getActionShortcut = (name: string): string => {
     const action = findAction(name)
     if (!action) return ''
@@ -184,7 +137,7 @@ export const findActionsForShortcut = (shortcut: string): DzAction[] => {
     return result
 }
 
-export const clearActionShorcut = (name: string) => {
+export const clearActionShortcut = (name: string) => {
     let action = findAction(name)
     if (!action) return
     if (isCustomAction(action)) {
@@ -195,6 +148,8 @@ export const clearActionShorcut = (name: string) => {
     }
 }
 
+export const clearActionShorcut = clearActionShortcut
+
 export const getActionPixmap = (action: string, icon: string, maxSize?: number): Pixmap | null => {
     try {
         if (!action) return null;

package/src/helpers/custom-action-helper.ts

@@ -280,6 +280,12 @@ const removeUnderlyingCustomAction = (actionName: string | null | undefined) =>
     const index = actionMgr.findCustomAction(actionName)
     if (index < 0) return
 
+    const shortcut = String(actionMgr.getCustomActionShortcut(index) ?? '').trim()
+    if (shortcut) {
+        actionMgr.setCustomActionShortcut(index, '')
+        debug(`Action ${actionName} shortcut cleared before removal`)
+    }
+
     actionMgr.removeCustomAction(index)
     debug(`Action ${actionName} removed`)
 }

package/src/helpers/custom-action-installer-entries.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { getCanonicalInstallerEntry, toActionKey } from './custom-action-installer-entries'
+
+const entries = [
+    { action: { text: 'Power Menu - Main Actions', filePath: './Power Menu Actions.dsa' }, effectiveShortcut: '' },
+    { action: { text: 'Power Menu', filePath: './Power Menu.dsa' }, effectiveShortcut: '' },
+]
+
+describe('setup installer entries', () => {
+    it('builds an empty key for missing action data instead of throwing', () => {
+        expect(toActionKey(undefined)).toBe('')
+    })
+
+    it('resolves row data back to the canonical installer entry', () => {
+        const rowCopy = {
+            action: { text: 'Power Menu', filePath: './Power Menu.dsa' },
+            effectiveShortcut: 'F12'
+        }
+
+        const canonical = getCanonicalInstallerEntry(entries, rowCopy)
+
+        expect(canonical).toBe(entries[1])
+    })
+
+    it('falls back to the displayed action text when row data is not an installer entry', () => {
+        const canonical = getCanonicalInstallerEntry(entries, { value: null }, 'Power Menu')
+
+        expect(canonical).toBe(entries[1])
+    })
+
+    it('ignores row data with an invalid action property before falling back to displayed text', () => {
+        const canonical = getCanonicalInstallerEntry(entries, { action: true }, 'Power Menu')
+
+        expect(canonical).toBe(entries[1])
+    })
+
+    it('prefers displayed row text over attached row data', () => {
+        const staleRowData = {
+            action: { text: 'Power Menu - Main Actions', filePath: './Power Menu Actions.dsa' },
+            effectiveShortcut: ''
+        }
+
+        const canonical = getCanonicalInstallerEntry(entries, staleRowData, 'Power Menu')
+
+        expect(canonical).toBe(entries[1])
+    })
+
+    it('returns null when neither row data nor displayed text identify an installer entry', () => {
+        const canonical = getCanonicalInstallerEntry(entries, { action: true }, 'Missing')
+
+        expect(canonical).toBeNull()
+    })
+})

package/src/helpers/custom-action-installer-entries.ts

@@ -0,0 +1,58 @@
+import type { CustomAction } from '@dsf/core/custom-action'
+
+export type InstallerActionEntry = {
+    action: CustomAction
+}
+
+const isActionLike = (value: any): value is CustomAction =>
+    Boolean(value && (typeof value.filePath !== 'undefined' || typeof value.text !== 'undefined'))
+
+export const toActionKey = (action?: CustomAction | null): string =>
+    String(action?.filePath ?? action?.text ?? '')
+
+const findByDisplayedText = <TEntry extends InstallerActionEntry>(
+    entries: TEntry[],
+    displayedText: string
+): TEntry | null => {
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i]
+        if (String(entry.action.text ?? '') === displayedText) return entry
+    }
+
+    return null
+}
+
+const findByActionKey = <TEntry extends InstallerActionEntry>(
+    entries: TEntry[],
+    key: string
+): TEntry | null => {
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i]
+        if (toActionKey(entry.action) === key) return entry
+    }
+
+    return null
+}
+
+export const asInstallerActionEntry = <TEntry extends InstallerActionEntry>(value: any): TEntry | null => {
+    if (isActionLike(value?.action)) return value as TEntry
+    if (isActionLike(value?.value?.action)) return value.value as TEntry
+    return null
+}
+
+export const getCanonicalInstallerEntry = <TEntry extends InstallerActionEntry>(
+    entries: TEntry[],
+    value: any,
+    displayedActionText?: string
+): TEntry | null => {
+    const displayedText = String(displayedActionText ?? '')
+    const displayedMatch = findByDisplayedText(entries, displayedText)
+    if (displayedMatch) return displayedMatch
+
+    const candidate = asInstallerActionEntry<TEntry>(value)
+
+    if (!candidate || !isActionLike(candidate.action)) return null
+
+    const key = toActionKey(candidate.action)
+    return findByActionKey(entries, key) ?? candidate
+}

package/src/helpers/custom-action-installer-helper.ts

@@ -11,6 +11,9 @@ import CustomSet from '@dsf/lib/set'
 import { TreeNode } from '@dsf/lib/tree-node'
 import { promptKeyboardShortcut } from '@dsf/shared/set-keyboard-shortcut'
 import { readFromFile, saveToFile } from './file-helper'
+import { getCanonicalInstallerEntry, toActionKey } from './custom-action-installer-entries'
+import { canResetSetupShortcut, getDisplayedSetupShortcut, resetSetupShortcut, setSetupShortcut, updateShortcutOverrideState } from './custom-action-installer-shortcuts'
+import { getScriptPath } from './script-helper'
 
 type InstallerEntry = {
     action: CustomAction
@@ -29,6 +32,10 @@ type InstallerEntry = {
 type SetupDialogOptions = {
     settingsPath: string
     bundleName?: string
+    headerImagePath?: string
+    headerImageWidth?: number
+    headerHeight?: number
+    headerText?: string
     shortcuts?: ActionAccelerator[]
     shortcutsSourcePath?: string
     shortcutBackupPath?: string
@@ -70,9 +77,7 @@ type SetupSelection = {
     shortcuts: ShortcutEntry[]
 }
 
-const OVERRIDE_MARKER = '[ovr]'
-
-const toKey = (action: CustomAction): string => String(action.filePath ?? action.text ?? '')
+const toKey = toActionKey
 
 const toTreeNode = (entry: InstallerEntry): TreeNode<InstallerEntry> =>
     new TreeNode(String(entry.action.text), toKey(entry.action), entry)
@@ -96,16 +101,15 @@ const getSetupDialogOptions = (options: string | SetupDialogOptions): SetupDialo
 const getShortcutBackupPath = (options: SetupDialogOptions): string =>
     `${App.getAppDataPath()}/${options.shortcutBackupPath ?? `${options.settingsPath}/keyboard-shortcuts-backup.json`}`
 
-const getDisplayedShortcut = (entry: InstallerEntry): string => {
-    if (!entry.isShortcutOverridden) return entry.effectiveShortcut
-    return entry.effectiveShortcut
-        ? `${entry.effectiveShortcut} ${OVERRIDE_MARKER}`
-        : OVERRIDE_MARKER
-}
+const hasSetupHeader = (options: SetupDialogOptions): boolean =>
+    Boolean(options.headerImagePath || options.headerText)
+
+const resolveSetupAssetPath = (filePath: string | null | undefined): string => {
+    const value = String(filePath ?? '').replace(/\\/g, '/')
+    if (!value) return ''
+    if (value.indexOf(':') >= 0 || value.charAt(0) === '/') return value
 
-const updateOverrideState = (entry: InstallerEntry) => {
-    entry.isShortcutOverridden = Boolean(entry.installedActionName) &&
-        normalizeShortcut(entry.installedShortcut) !== normalizeShortcut(entry.defaultShortcut)
+    return `${getScriptPath()}/${value.replace(/^\.\//, '')}`
 }
 
 const buildEntries = (actions: CustomAction[]): InstallerEntry[] => {
@@ -132,7 +136,7 @@ const buildEntries = (actions: CustomAction[]): InstallerEntry[] => {
                 installedActionName: String(installed.customAction?.name ?? '')
             }
 
-            updateOverrideState(entry)
+            updateShortcutOverrideState(entry)
             return entry
         })
 }
@@ -192,9 +196,9 @@ class InstallerSelectionDialog extends BasicDialog {
     constructor(
         private readonly entries: InstallerEntry[],
         private readonly shortcutEntries: ShortcutEntry[],
-        bundleName?: string
+        private readonly options: SetupDialogOptions
     ) {
-        super(bundleName ? `${bundleName} Setup` : 'Setup Scripts', 'dsfSetupScripts')
+        super(options.bundleName ? `${options.bundleName} Setup` : 'Setup Scripts', 'dsfSetupScripts')
         this.items$ = new Observable(entries.map(toTreeNode))
         this.shortcutItems$ = new Observable(shortcutEntries.map(toShortcutTreeNode))
     }
@@ -226,17 +230,20 @@ class InstallerSelectionDialog extends BasicDialog {
     private buildScriptsTab(): void {
         const add = this.add
 
-        add.label('Choose which scripts to install, then use the columns to review their shortcut, menu, and toolbar targets.')
-            .wordWrap()
-            .build()
+        if (hasSetupHeader(this.options)) {
+            this.buildHeader()
+        } else {
+            add.label('Choose which scripts to install, then use the columns to review their shortcut, menu, and toolbar targets.')
+                .wordWrap()
+                .build()
+        }
         add.group('Search').horizontal().build(() => {
             add.edit()
                 .value(this.keywords$)
                 .focus()
                 .placeholder('Search actions...')
                 .toolTip('Search by action name, description, path, shortcut, or available targets.')
-            add.button('Select All').clicked(() => this.setVisibleSelections(true))
-            add.button('Deselect All').clicked(() => this.setVisibleSelections(false))
+            add.button('Clear').clicked(() => this.keywords$.value = '')
         })
 
         add.group('Scripts')
@@ -269,7 +276,7 @@ class InstallerSelectionDialog extends BasicDialog {
                         return [
                             '',
                             String(entry.action.text ?? ''),
-                            getDisplayedShortcut(entry),
+                            getDisplayedSetupShortcut(entry),
                             String(entry.action.description ?? ''),
                             String(entry.action.menuPath ?? ''),
                             getDisplayedToolbar(entry),
@@ -291,6 +298,25 @@ class InstallerSelectionDialog extends BasicDialog {
                         listView.allColumnsShowFocus = true
                     })
             })
+        add.group().horizontal().build((layout) => {
+            layout.addStretch()
+            add.button('Select All').clicked(() => this.setVisibleSelections(true))
+            add.button('Deselect All').clicked(() => this.setVisibleSelections(false))
+        })
+    }
+
+    private buildHeader(): void {
+        const add = this.add
+        const height = this.options.headerHeight ?? 96
+        const imageWidth = this.options.headerImageWidth ?? height
+        const headerText = String(this.options.headerText ?? 'Choose which scripts to install, then use the columns to review their shortcut, menu, and toolbar targets.')
+
+        add.header({
+            imagePath: resolveSetupAssetPath(this.options.headerImagePath),
+            imageWidth,
+            height,
+            html: headerText
+        }).build()
     }
 
     private buildShortcutsTab(): void {
@@ -304,8 +330,7 @@ class InstallerSelectionDialog extends BasicDialog {
                 .value(this.shortcutKeywords$)
                 .placeholder('Search shortcuts...')
                 .toolTip('Search by action name, current shortcut, new shortcut, status, or conflicts.')
-            add.button('Select All').clicked(() => this.setVisibleShortcutSelections(true))
-            add.button('Deselect All').clicked(() => this.setVisibleShortcutSelections(false))
+            add.button('Clear').clicked(() => this.shortcutKeywords$.value = '')
         })
 
         add.group('Keyboard Shortcuts')
@@ -358,12 +383,20 @@ class InstallerSelectionDialog extends BasicDialog {
                         listView.allColumnsShowFocus = true
                     })
             })
+        add.group().horizontal().build((layout) => {
+            layout.addStretch()
+            add.button('Select All').clicked(() => this.setVisibleShortcutSelections(true))
+            add.button('Deselect All').clicked(() => this.setVisibleShortcutSelections(false))
+        })
     }
 
     private buildContextMenu(listView: DzListView, listItem: DzListViewItem | null): DzPopupMenu {
-        const entry = listItem ? getDataItem<InstallerEntry>(listItem) : null
+        debug(`[Setup] context menu row input ${this.describeListItem('item', listItem)} ${this.describeListItem('selected', listView.selectedItem())} ${this.describeListItem('current', listView.currentItem())}`)
+        const contextItem = this.getContextListItem(listView, listItem)
+        const entry = contextItem ? this.getCanonicalEntry(getDataItem<InstallerEntry>(contextItem), contextItem) : null
+        debug(`[Setup] context menu row resolved item="${this.safeListItemText(contextItem, 1)}" entry="${entry?.action?.text ?? ''}"`)
         const canSetShortcut = Boolean(entry)
-        const canResetShortcut = Boolean(entry?.installedActionName && entry?.isShortcutOverridden)
+        const canResetShortcut = Boolean(entry && canResetSetupShortcut(entry))
 
         const items = [
             {
@@ -391,31 +424,77 @@ class InstallerSelectionDialog extends BasicDialog {
         })
     }
 
+    private getContextListItem(listView: DzListView, listItem: any): DzListViewItem | null {
+        if (this.isListViewItem(listItem)) return listItem
+
+        const selectedItem = listView.selectedItem()
+        if (this.isListViewItem(selectedItem)) return selectedItem
+
+        const currentItem = listView.currentItem()
+        if (this.isListViewItem(currentItem)) return currentItem
+
+        return null
+    }
+
+    private isListViewItem(value: any): value is DzListViewItem {
+        return Boolean(value && typeof value.text === 'function')
+    }
+
+    private describeListItem(label: string, value: any): string {
+        if (!value) return `${label}=null`
+
+        const hasTextFunction = typeof value.text === 'function'
+        const text0 = this.safeListItemText(value, 0)
+        const text1 = this.safeListItemText(value, 1)
+        const text2 = this.safeListItemText(value, 2)
+        const hasDataFunction = typeof value.getDataItem === 'function'
+        let dataText = ''
+
+        if (hasDataFunction) {
+            const data = getDataItem<any>(value)
+            dataText = String(data?.action?.text ?? data?.value?.action?.text ?? '')
+        }
+
+        return `${label} type=${typeof value} textFn=${hasTextFunction} text0="${text0}" text1="${text1}" text2="${text2}" dataFn=${hasDataFunction} data="${dataText}"`
+    }
+
+    private safeListItemText(value: any, column: number): string {
+        try {
+            if (!value || typeof value.text !== 'function') return ''
+            return String(value.text(column) ?? '')
+        } catch (error) {
+            return `[error:${String(error)}]`
+        }
+    }
+
+    private getCanonicalEntry(entry: InstallerEntry | null, listItem?: DzListViewItem | null): InstallerEntry | null {
+        return getCanonicalInstallerEntry(this.entries, entry, listItem?.text(1))
+    }
+
     private setShortcut(entry: InstallerEntry) {
+        if (!entry?.action) {
+            debug('[Setup] shortcut set ignored because the selected row did not resolve to an installer entry')
+            return
+        }
+
         const actionName = entry.installedActionName || toKey(entry.action)
         const actionLabel = String(entry.action.text ?? entry.action.filePath ?? actionName)
         const shortcut = promptKeyboardShortcut(actionLabel, actionName, entry.effectiveShortcut)
         if (shortcut == null) return
 
-        if (entry.installedActionName) {
-            setActionShortcut(entry.installedActionName, shortcut)
-            entry.installedShortcut = normalizeShortcut(shortcut)
-            entry.effectiveShortcut = entry.installedShortcut
-            updateOverrideState(entry)
-        } else {
-            entry.effectiveShortcut = normalizeShortcut(shortcut)
-        }
+        const previousShortcut = entry.effectiveShortcut
+        setSetupShortcut(entry, shortcut)
+        debug(`[Setup] shortcut queued action="${entry.action.text}" installed=${Boolean(entry.installedActionName)} previous="${previousShortcut}" next="${entry.effectiveShortcut}" custom=${entry.isShortcutOverridden}`)
 
         this.refreshListEvent$.trigger()
     }
 
     private resetDefaultShortcut(entry: InstallerEntry) {
-        if (!entry.installedActionName || !entry.isShortcutOverridden) return
+        if (!canResetSetupShortcut(entry)) return
 
-        setActionShortcut(entry.installedActionName, entry.defaultShortcut)
-        entry.installedShortcut = normalizeShortcut(entry.defaultShortcut)
-        entry.effectiveShortcut = entry.installedShortcut
-        updateOverrideState(entry)
+        const previousShortcut = entry.effectiveShortcut
+        resetSetupShortcut(entry)
+        debug(`[Setup] shortcut reset queued action="${entry.action.text}" previous="${previousShortcut}" default="${entry.defaultShortcut}"`)
         this.refreshListEvent$.trigger()
     }
 
@@ -514,7 +593,7 @@ class InstallerSelectionDialog extends BasicDialog {
 const runDialog = (actions: CustomAction[], options: SetupDialogOptions): SetupSelection | null => {
     const entries = buildEntries(actions)
     const shortcutEntries = buildShortcutEntries(options.shortcuts)
-    const dialog = new InstallerSelectionDialog(entries, shortcutEntries, options.bundleName)
+    const dialog = new InstallerSelectionDialog(entries, shortcutEntries, options)
     return dialog.ok() ? dialog.getSelections() : null
 }
 
@@ -565,7 +644,7 @@ export const showSetupCustomActionsDialog = (actions: CustomAction[], options: s
     const selectedToolbarActions: CustomAction[] = []
 
     progress('Setting Up Scripts', selections.actions, (selection) => {
-        debug(`[Setup] ${selection.selected ? 'install' : 'remove'} "${selection.action.text}"`)
+        debug(`[Setup] ${selection.selected ? 'install' : 'remove'} "${selection.action.text}" shortcut="${selection.effectiveShortcut}" custom=${selection.isShortcutOverridden}`)
 
         if (selection.supportsToolbar && selection.action.toolbar) {
             touchedToolbarNames.add(selection.action.toolbar)
@@ -574,7 +653,7 @@ export const showSetupCustomActionsDialog = (actions: CustomAction[], options: s
         if (selection.selected) {
             const customAction = applyCustomActionTargets({
                 ...selection.action,
-                shortcut: selection.effectiveShortcut
+                shortcut: ''
             }, {
                 menu: selection.supportsMenu,
                 toolbar: selection.supportsToolbar
@@ -582,6 +661,12 @@ export const showSetupCustomActionsDialog = (actions: CustomAction[], options: s
                 deferToolbar: true
             })
 
+            if (customAction) {
+                setActionShortcut(String(customAction.name), selection.effectiveShortcut)
+                const appliedShortcut = getActionShortcut(String(customAction.name))
+                debug(`[Setup] applied shortcut "${appliedShortcut}" to "${selection.action.text}" after install`)
+            }
+
             if (customAction && selection.supportsToolbar && selection.action.toolbar) {
                 selectedToolbarActions.push(customAction)
             }

package/src/helpers/custom-action-installer-shortcuts.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+import {
+    canResetSetupShortcut,
+    getDisplayedSetupShortcut,
+    resetSetupShortcut,
+    setSetupShortcut,
+    updateShortcutOverrideState
+} from './custom-action-installer-shortcuts'
+
+const shortcutState = (overrides: Partial<ReturnType<typeof baseState>> = {}) => ({
+    ...baseState(),
+    ...overrides
+})
+
+const baseState = () => ({
+    installedActionName: '',
+    installedShortcut: '',
+    defaultShortcut: '',
+    effectiveShortcut: '',
+    isShortcutOverridden: false
+})
+
+describe('setup shortcut state', () => {
+    it('stores pending shortcuts for actions that are not installed yet', () => {
+        const entry = shortcutState()
+
+        setSetupShortcut(entry, 'F12')
+
+        expect(entry.effectiveShortcut).toBe('F12')
+        expect(entry.installedShortcut).toBe('')
+        expect(entry.isShortcutOverridden).toBe(false)
+        expect(canResetSetupShortcut(entry)).toBe(true)
+    })
+
+    it('marks installed shortcuts that differ from the default as custom', () => {
+        const entry = shortcutState({
+            installedActionName: 'installed-guid',
+            defaultShortcut: '',
+            installedShortcut: ''
+        })
+
+        setSetupShortcut(entry, 'F12')
+
+        expect(entry.installedShortcut).toBe('F12')
+        expect(entry.effectiveShortcut).toBe('F12')
+        expect(entry.isShortcutOverridden).toBe(true)
+        expect(getDisplayedSetupShortcut(entry)).toBe('F12 [custom]')
+        expect(canResetSetupShortcut(entry)).toBe(true)
+    })
+
+    it('resets installed custom shortcuts to the default', () => {
+        const entry = shortcutState({
+            installedActionName: 'installed-guid',
+            defaultShortcut: 'Ctrl+P',
+            installedShortcut: 'F12',
+            effectiveShortcut: 'F12',
+            isShortcutOverridden: true
+        })
+
+        resetSetupShortcut(entry)
+
+        expect(entry.installedShortcut).toBe('Ctrl+P')
+        expect(entry.effectiveShortcut).toBe('Ctrl+P')
+        expect(entry.isShortcutOverridden).toBe(false)
+        expect(canResetSetupShortcut(entry)).toBe(false)
+    })
+
+    it('resets pending shortcuts without inventing an installed shortcut', () => {
+        const entry = shortcutState({
+            defaultShortcut: '',
+            installedShortcut: '',
+            effectiveShortcut: 'F12'
+        })
+
+        resetSetupShortcut(entry)
+
+        expect(entry.installedShortcut).toBe('')
+        expect(entry.effectiveShortcut).toBe('')
+        expect(entry.isShortcutOverridden).toBe(false)
+        expect(canResetSetupShortcut(entry)).toBe(false)
+    })
+
+    it('displays custom marker when installed shortcut was changed outside setup', () => {
+        const entry = shortcutState({
+            installedActionName: 'installed-guid',
+            defaultShortcut: '',
+            installedShortcut: 'F12',
+            effectiveShortcut: 'F12'
+        })
+
+        updateShortcutOverrideState(entry)
+
+        expect(getDisplayedSetupShortcut(entry)).toBe('F12 [custom]')
+    })
+})

package/src/helpers/custom-action-installer-shortcuts.ts

@@ -0,0 +1,49 @@
+import { normalizeShortcut } from '@dsf/helpers/shortcut-helper'
+
+export const CUSTOM_SHORTCUT_MARKER = '[custom]'
+
+export type InstallerShortcutState = {
+    installedActionName: string
+    installedShortcut: string
+    defaultShortcut: string
+    effectiveShortcut: string
+    isShortcutOverridden: boolean
+}
+
+export const updateShortcutOverrideState = (entry: InstallerShortcutState): void => {
+    entry.isShortcutOverridden = Boolean(entry.installedActionName) &&
+        normalizeShortcut(entry.installedShortcut) !== normalizeShortcut(entry.defaultShortcut)
+}
+
+export const getDisplayedSetupShortcut = (entry: InstallerShortcutState): string => {
+    if (!entry.isShortcutOverridden) return entry.effectiveShortcut
+
+    return entry.effectiveShortcut
+        ? `${entry.effectiveShortcut} ${CUSTOM_SHORTCUT_MARKER}`
+        : CUSTOM_SHORTCUT_MARKER
+}
+
+export const canResetSetupShortcut = (entry: InstallerShortcutState): boolean =>
+    normalizeShortcut(entry.effectiveShortcut) !== normalizeShortcut(entry.defaultShortcut)
+
+export const setSetupShortcut = (entry: InstallerShortcutState, shortcut: string): void => {
+    const normalizedShortcut = normalizeShortcut(shortcut)
+
+    if (entry.installedActionName) {
+        entry.installedShortcut = normalizedShortcut
+    }
+
+    entry.effectiveShortcut = normalizedShortcut
+    updateShortcutOverrideState(entry)
+}
+
+export const resetSetupShortcut = (entry: InstallerShortcutState): void => {
+    const defaultShortcut = normalizeShortcut(entry.defaultShortcut)
+
+    if (entry.installedActionName) {
+        entry.installedShortcut = defaultShortcut
+    }
+
+    entry.effectiveShortcut = defaultShortcut
+    updateShortcutOverrideState(entry)
+}

package/src/helpers/shortcut-helper.ts

@@ -0,0 +1,48 @@
+const shortcutTokenMap: { [key: string]: string } = {
+    'CTRL': 'Ctrl',
+    'CONTROL': 'Ctrl',
+    'SHIFT': 'Shift',
+    'ALT': 'Alt',
+    'OPTION': 'Alt',
+    'WIN': 'Win',
+    'WINDOWS': 'Win',
+    'CMD': 'Win',
+    'COMMAND': 'Win',
+    'SPACE': 'Space',
+    'HOME': 'Home',
+    'END': 'End',
+    'INS': 'Ins',
+    'INSERT': 'Ins',
+    'DEL': 'Del',
+    'DELETE': 'Del',
+    'TAB': 'Tab',
+    'BACKSPACE': 'Backspace',
+    'COMMA': 'Comma',
+    'PERIOD': 'Period',
+    'PLUS': 'Plus',
+    'MINUS': 'Minus',
+    'PGUP': 'PgUp',
+    'PAGEUP': 'PgUp',
+    'PGDOWN': 'PgDn',
+    'PGDN': 'PgDn',
+    'LEFT': 'Left',
+    'RIGHT': 'Right',
+    'UP': 'Up',
+    'DOWN': 'Down',
+}
+
+export const normalizeShortcut = (shortcut: string): string => {
+    if (!shortcut) return ''
+
+    return shortcut
+        .split('+')
+        .map(part => part.trim())
+        .filter(Boolean)
+        .map(part => {
+            if (part.length === 1) return part.toUpperCase()
+
+            const key = part.toUpperCase()
+            return shortcutTokenMap[key] || part
+        })
+        .join('+')
+}

package/src/scripts/install-generator.test.ts

@@ -29,6 +29,10 @@ const writePng = (projectDir: string, fileName: string): void => {
     fs.writeFileSync(path.join(projectDir, 'src', fileName), 'png')
 }
 
+const writeText = (projectDir: string, fileName: string, content: string): void => {
+    fs.writeFileSync(path.join(projectDir, 'src', fileName), content)
+}
+
 const generateSetup = (projectDir: string): string => {
     const previousCwd = process.cwd()
     process.chdir(projectDir)
@@ -103,3 +107,69 @@ describe('install generator action icons', () => {
         expect(setup).not.toContain('"icon": "custom-icon.dsa.png"')
     })
 })
+
+describe('install generator setup header', () => {
+    it('uses the explicit setup header image before the generic setup image', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writePng(projectDir, 'Setup.header.png')
+        writePng(projectDir, 'Setup.png')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerImagePath":"./Setup.header.png"')
+        expect(setup).not.toContain('"headerImagePath":"./Setup.png"')
+    })
+
+    it('falls back to the generic setup image when no explicit header image exists', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writePng(projectDir, 'Setup.png')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerImagePath":"./Setup.png"')
+    })
+
+    it('falls back to the setup script image when no header image exists', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writePng(projectDir, 'Setup.dsa.png')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerImagePath":"./Setup.dsa.png"')
+    })
+
+    it('embeds setup header markdown text into generated setup options', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writeText(projectDir, 'Setup.header.md', 'Header line\n\nSecond line\n')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerText":"Header line\\n\\nSecond line"')
+    })
+
+    it('prefers setup header html over markdown text', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writeText(projectDir, 'Setup.header.html', '<h2>HTML Header</h2>')
+        writeText(projectDir, 'Setup.header.md', '# Markdown Header')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerText":"<h2>HTML Header</h2>"')
+        expect(setup).not.toContain('# Markdown Header')
+    })
+
+    it('falls back to setup script markdown when no header text file exists', () => {
+        const projectDir = makeProject()
+        writeScript(projectDir, 'render-tools')
+        writeText(projectDir, 'Setup.md', 'Setup markdown fallback')
+
+        const setup = generateSetup(projectDir)
+
+        expect(setup).toContain('"headerText":"Setup markdown fallback"')
+    })
+})

package/src/shared/set-keyboard-shortcut-conflicts.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { clearShortcutConflicts } from './set-keyboard-shortcut-conflicts'
+
+describe('clearShortcutConflicts', () => {
+    it('clears conflicting actions without clearing the target action', () => {
+        const cleared: string[] = []
+
+        clearShortcutConflicts('target-action', [
+            { name: 'target-action', text: 'Target' } as DzAction,
+            { name: 'old-owner', text: 'Old Owner' } as DzAction,
+            { name: 'other-owner', text: 'Other Owner' } as DzAction
+        ], (name) => {
+            cleared.push(name)
+        })
+
+        expect(cleared).toEqual(['old-owner', 'other-owner'])
+    })
+})

package/src/shared/set-keyboard-shortcut-conflicts.ts

@@ -0,0 +1,14 @@
+export type ShortcutConflict = {
+    name: string
+}
+
+export const clearShortcutConflicts = (
+    actionName: string,
+    conflicts: ShortcutConflict[],
+    clearShortcut: (name: string) => void
+): void => {
+    conflicts.forEach((action) => {
+        if (!action || action.name === actionName) return
+        clearShortcut(action.name)
+    })
+}

package/src/shared/set-keyboard-shortcut.ts

@@ -1,9 +1,10 @@
 import { BasicDialog } from '@dsf/dialog/basic-dialog';
 import { debug } from '@dsf/common/log';
-import { findAction, findActionsForShortcut, getActionShortcut, normalizeShortcut, setActionShortcut } from '@dsf/helpers/action-helper';
+import { clearActionShortcut, findActionsForShortcut, getActionShortcut, normalizeShortcut, setActionShortcut } from '@dsf/helpers/action-helper';
 import { contains } from '@dsf/helpers/array-helper';
 import { confirm } from '@dsf/helpers/message-box-helper';
 import { Observable } from '@dsf/lib/observable';
+import { clearShortcutConflicts } from './set-keyboard-shortcut-conflicts';
 
 class KeyboardShortcutModel {
     actionLabel: string
@@ -157,6 +158,7 @@ export const promptKeyboardShortcut = (actionLabel: string, actionName: string,
         const conflictText = conflicts.map(action => action.text || action.name).join(', ')
         const response = confirm(`"${model.shortcut.value}" is already assigned to: ${conflictText}\n\nReplace it?`)
         if (!response.ok) return null
+        clearShortcutConflicts(actionName, conflicts, clearActionShortcut)
     }
 
     return model.shortcut.value