Macros 2.0 (v0.5.2) - Onboarding for new Macro Engine (#4955) * Macros 2.0 [Feature] - Add onboarding popup for experimental macro engine features - Add `onbordingExperimentalMacroEngine()` function in MacroDiagnostics.js to detect and prompt users about experimental features - Detect experimental macro features in `substituteParamsLegacy()`: {{if}}, scoped macros, macro flags, variable shorthands, nested macros - Add feature detection in autocomplete parser for macro flags, variable shorthands, and leading whitespace * Fix typo: rename `onbording` to `onboarding` throughout macro diagnostics system * Add `void` operator to async onboarding calls and fix typo in comment - Add `void` operator to all `onboardingExperimentalMacroEngine()` calls to explicitly discard Promise return values - Fix typo in MacroDiagnostics.js comment: "hat" → "that" * Fix typo in experimental macro engine onboarding popup: "anytime time" → "any time" --------- Co-authored-by: Cohee <18619528+Cohee1207@users.noreply.github.com>

e40b31b06d20122c14714351cdf9ac39d65691a4

Wolfsblvt <wolfsblvt@gmail.com>

Signed

Parents: b453fdc5d86898c9e64343c7541be49391b8d0fa

public/script.js+15 -0 Viewed

 import { MacroEnvBuilder } from './scripts/macros/engine/MacroEnvBuilder.js';
 import { MacroEngine } from './scripts/macros/engine/MacroEngine.js';
 import { addChatBackupsBrowser } from './scripts/chat-backups.js';
+import { onboardingExperimentalMacroEngine } from './scripts/macros/engine/MacroDiagnostics.js';
 // API OBJECT FOR EXTERNAL WIRING
 globalThis.SillyTavern = {

         });
+    }
+    // Try to roughly detect experimental macro features to show the onboarding if needed.
+    // This does not have to be 100% accurate, only best effort what we can quickly check.
+    // Only do this if the warning wasn't shown yet, to prevent needless regex checks.
+    if (accountStorage.getItem('slash_command_experimental_engine_warning_shown') !== 'true') {
+        let feature = /** @type {string|null} */ (null);
+        if (/{{\s*if/.test(content)) feature = '{{if}} macro';
+        else if (/{{\s*\//.test(content)) feature = 'scoped macro';
+        else if (/{{\s*[!?~#/]/.test(content)) feature = 'macro flags';
+        else if (/{{\s*[.$]/.test(content)) feature = 'variable shorthands';
+        else if (/\{\{(?:(?!\}\}).)*\{\{(?=[\s\S]*?\}\}[\s\S]*?\}\})/.test(content)) feature = 'nested macro';
+        if (feature) void onboardingExperimentalMacroEngine(feature);
+    }
     const environment = {};
     if (typeof _original === 'string') {

public/scripts/autocomplete/EnhancedMacroAutoCompleteOption.js+11 -0 Viewed

 import { enumIcons } from '../slash-commands/SlashCommandCommonEnumsProvider.js';
 import { ValidFlagSymbols } from '../macros/engine/MacroFlags.js';
 import { MACRO_VARIABLE_SHORTHAND_PATTERN } from '../macros/engine/MacroLexer.js';
+import { onboardingExperimentalMacroEngine } from '../macros/engine/MacroDiagnostics.js';
 /** @typedef {import('../macros/engine/MacroRegistry.js').MacroDefinition} MacroDefinition */

@@ -1093,6 +1094,10 @@ export function parseMacroContext(macroText, cursorOffset) {
1093	}	1094	}
1094	}	1095	}
1095		1096
		1097	if (flags.length > 0) {
		1098	void onboardingExperimentalMacroEngine('macro flags');
		1099	}
		1100
1096	// Check for variable shorthand prefix (. or $)	1101	// Check for variable shorthand prefix (. or $)
1097	// These trigger variable expression mode instead of regular macro parsing	1102	// These trigger variable expression mode instead of regular macro parsing
1098	/** @type {'.'\|'$'\|null} */	1103	/** @type {'.'\|'$'\|null} */

         // For invalid trailing chars, none of the typing flags will be true
         const isOperatorComplete = (variableOperator === '++' || variableOperator === '--');
+        void onboardingExperimentalMacroEngine('variable shorthands');
         // Return early for variable shorthand - different structure than regular macros
         return {
             fullText: macroText,

     const leftPadding = macroText.match(/^\s+/)?.[0] ?? '';
+    if (leftPadding) {
+        void onboardingExperimentalMacroEngine('leading whitespace');
+    }
     // Clean identifier: strip trailing colons (for partial :: typing)
     let cleanIdentifier = identifierOnly.replace(/:+$/, '');

public/scripts/macros/engine/MacroDiagnostics.js+47 -0 Viewed

 /** @typedef {import('chevrotain').ILexingError} ILexingError */
 /** @typedef {import('chevrotain').IRecognitionException} IRecognitionException */
+import { saveSettingsDebounced } from '/script.js';
+import { t } from '/scripts/i18n.js';
+import { Popup, POPUP_RESULT } from '/scripts/popup.js';
+import { power_user } from '/scripts/power-user.js';
+import { accountStorage } from '/scripts/util/AccountStorage.js';
+import { SimpleMutex } from '/scripts/util/SimpleMutex.js';
 /**
  * @typedef {Object} MacroErrorContext
  * @property {string} [macroName]

  * @typedef {MacroErrorContext & { message: string, error?: any }} MacroLogOptions
  */
+// Use mutex here so even on parallel usage without awaiting the popup, this will only show up once.
+export const onboardingExperimentalMacroEngineMutex = new SimpleMutex(onboardingExperimentalMacroEngineUnsafe);
+/**
+ * Onboards the user to use the experimental macro engine.
+ * Asks the user to enable it if they haven't already.
+ *
+ * @param {string|null} feature - The feature that requires the experimental macro engine, or null if not applicable or unknown.
+ * @returns {Promise<void>} - A promise that resolves when the user has been onboarded.
+ */
+export const onboardingExperimentalMacroEngine = onboardingExperimentalMacroEngineMutex.update.bind(onboardingExperimentalMacroEngineMutex);
+async function onboardingExperimentalMacroEngineUnsafe(feature = null) {
+    // Show a popup once telling a user that they are using experimental features that only work with the new engine.
+    // Ask them if they want to turn the experimental engine on.
+    if (power_user.experimental_macro_engine) return;
+    // If already shown, do not show again
+    const shown = accountStorage.getItem('slash_command_experimental_engine_warning_shown');
+    if (shown === 'true') return;
+    const result = await Popup.show.confirm(t`Experimental Macro Engine`, `
+        <p>${t`You are using experimental macro features that require the new macro engine.`}</p>
+        ${feature ? `<div class="info-block hint">
+                <span>${t`Recognized Feature: `}<strong>${feature}</strong></span>
+            </div>` : ''}
+        <p>${t`For more information on the new macro engine, visit the <br />${`<a href="https://docs.sillytavern.app/usage/core-concepts/macros/">${t`Macro Documentation`}</a>`}.`}</p>
+        <p>${t`You can enable the engine any time under:<br />${t`User Settings`} → ${t`Experimental Macro Engine`}`}</p>
+        <p>${t`Would you like to enable it now?`}</p>`);
+    if (result == POPUP_RESULT.AFFIRMATIVE) {
+        power_user.experimental_macro_engine = true;
+        $('#experimental_macro_engine').prop('checked', power_user.experimental_macro_engine);
+        saveSettingsDebounced();
+    }
+    // Only show this once
+    accountStorage.setItem('slash_command_experimental_engine_warning_shown', 'true');
+}
 /**
  * Creates an error representing a runtime macro invocation problem (such as
  * arity or type mismatches). These errors are intended to be caught by the

public/scripts/slash-commands/SlashCommandParser.js+5 -0 Viewed

 import { AutoCompleteOption } from '../autocomplete/AutoCompleteOption.js';
 import { chat_metadata } from '/script.js';
 import { extension_settings } from '../extensions.js';
+import { onboardingExperimentalMacroEngine } from '../macros/engine/MacroDiagnostics.js';
 /** @typedef {import('./SlashCommand.js').NamedArgumentsCapture} NamedArgumentsCapture */
 /** @typedef {import('./SlashCommand.js').NamedArguments} NamedArguments */

                         resultStart = conditionStartInText + macroNameStart;
+                    }
+                    await onboardingExperimentalMacroEngine('{{if}} macro');
                     const result = new AutoCompleteNameResult(
                         resultIdentifier,
                         resultStart,

                         scopedMacroName: scopedMacro.name,
                     };
+                    await onboardingExperimentalMacroEngine('scoped macros');
                     // Only show the scoped macro's details - no list of other macros
                     // This creates a "details only" view showing the scoped arg being typed
                     const macroDef = macroSystem.registry.getPrimaryMacro(scopedMacro.name);