@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/localize-unity-project/scripts/L10nBatchProcessor.cs

@@ -0,0 +1,191 @@
+using UnityEngine;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine.UI;
+using UnityEditor.Events;
+using UnityEngine.Events;
+using UnityEngine.Localization.Components;
+using System.Collections.Generic;
+using System.Linq;
+using TMPro;
+
+/// <summary>
+/// Batch-processes all scenes in the project, attaching LocalizeStringEvent components
+/// to every text element whose content matches a key in the provided mapping.
+///
+/// Covers BOTH legacy UnityEngine.UI.Text and TextMeshPro (TMP_Text, which is the base of
+/// TextMeshProUGUI and TextMeshPro). Walking only one of the two is the usual mistake and it
+/// fails silently: measured on a real project, FindObjectsByType&lt;Text&gt; found 1 component
+/// while FindObjectsByType&lt;TMP_Text&gt; found 13, so a Text-only pass reports success having
+/// localized almost nothing.
+///
+/// LocalizeAll() modifies and saves every scene under Assets/, so it enforces its own safeguards
+/// in code rather than relying on the caller: it refuses to run in batch mode, asks the user to
+/// save or discard unsaved scene changes, and shows a blocking confirmation dialog listing the
+/// scenes it will rewrite. Nothing is written unless the user clicks the confirm button.
+/// It also reports what it did NOT convert; see the return value of LocalizeHierarchy.
+/// </summary>
+public static class L10nBatchProcessor
+{
+    /// <summary>Localizes every scene. Returns the labels that matched no mapping entry.</summary>
+    public static List<string> LocalizeAll(Dictionary<string, string> mapping, string table)
+    {
+        var unmatched = new List<string>();
+
+        // Scope the search to Assets/. An unscoped FindAssets searches the whole project INCLUDING
+        // read-only packages, so it returns package test scenes and this loop then tries to open,
+        // dirty and save assets it must not touch. Measured on a real project: unscoped found 20
+        // scenes where the project has 1, and all 19 extras were inside read-only packages
+        // (com.unity.addressables test fixtures).
+        var scenePaths = AssetDatabase.FindAssets("t:Scene", new[] { "Assets" })
+            .Select(guid => AssetDatabase.GUIDToAssetPath(guid))
+            .ToList();
+
+        // The safeguards live here, in the code path that does the writes, so skipping a
+        // sentence in the documentation cannot skip them.
+        //
+        // 1. Batch mode: EditorUtility.DisplayDialog returns true without showing anything when
+        //    the Editor runs headless, which would turn the confirmation below into a no-op.
+        if (Application.isBatchMode)
+        {
+            throw new System.InvalidOperationException(
+                "L10nBatchProcessor.LocalizeAll rewrites every scene and needs a user to confirm it " +
+                "in an interactive Editor. It does not run in batch mode.");
+        }
+
+        // 2. Unsaved work: OpenScene(..., Single) below closes whatever is open. Let the user save
+        //    or discard it first; Cancel aborts the whole run.
+        if (!EditorSceneManager.SaveCurrentModifiedScenesIfUserWantsTo())
+        {
+            throw new System.OperationCanceledException(
+                "Localization batch cancelled: the open scenes have unsaved changes.");
+        }
+
+        // 3. Explicit confirmation of the destructive write, naming what will change.
+        const int listed = 10;
+        var preview = string.Join("\n", scenePaths.Take(listed));
+        if (scenePaths.Count > listed)
+        {
+            preview += $"\n... and {scenePaths.Count - listed} more";
+        }
+        var confirmed = EditorUtility.DisplayDialog(
+            "Localize all scenes?",
+            $"This opens {scenePaths.Count} scene(s) under Assets/, attaches LocalizeStringEvent " +
+            $"components to matching text, and saves each scene. It cannot be undone from here; " +
+            $"use version control to revert.\n\n{preview}",
+            $"Localize {scenePaths.Count} scene(s)",
+            "Cancel");
+        if (!confirmed)
+        {
+            throw new System.OperationCanceledException("Localization batch cancelled by the user.");
+        }
+
+        // Restore the user's scene layout afterwards, so the batch doesn't leave them looking at
+        // whichever scene happened to be processed last.
+        var originalSetup = EditorSceneManager.GetSceneManagerSetup();
+        try
+        {
+            foreach (var path in scenePaths)
+            {
+                var scene = EditorSceneManager.OpenScene(path, OpenSceneMode.Single);
+                unmatched.AddRange(LocalizeHierarchy(mapping, table, path));
+                EditorSceneManager.MarkSceneDirty(scene);
+                EditorSceneManager.SaveScene(scene);
+            }
+        }
+        finally
+        {
+            // An untitled scene has no path to reopen, so only restore a layout made of saved scenes.
+            if (originalSetup.Length > 0 && originalSetup.All(s => !string.IsNullOrEmpty(s.path)))
+            {
+                EditorSceneManager.RestoreSceneManagerSetup(originalSetup);
+            }
+        }
+        return unmatched;
+    }
+
+    /// <summary>
+    /// Wires the open scene. Returns "scene :: object :: text" for every label that was found
+    /// but matched no mapping entry, so partial coverage is reported rather than silent.
+    /// </summary>
+    static List<string> LocalizeHierarchy(
+        Dictionary<string, string> mapping, string table, string scenePath)
+    {
+        var unmatched = new List<string>();
+
+        // Both component families. TMP_Text is abstract and covers TextMeshProUGUI and TextMeshPro.
+        var labels = new List<Component>();
+        labels.AddRange(Object.FindObjectsByType<Text>(
+            FindObjectsInactive.Include, FindObjectsSortMode.None));
+        labels.AddRange(Object.FindObjectsByType<TMP_Text>(
+            FindObjectsInactive.Include, FindObjectsSortMode.None));
+
+        // Longest key first. A label reading "NO ITEMS FOUND" must bind to that key rather
+        // than to a shorter "NO" that is a substring of it -- the case SKILL.md's mapping
+        // guidance calls out. Dictionary enumeration order is unspecified, so without this
+        // the binding is not just wrong but irreproducible; and because the loop below breaks
+        // on the first hit and marks the label matched, a mis-binding never surfaces in the
+        // unmatched report. Sorted once here rather than once per label.
+        var ordered = mapping.OrderByDescending(e => e.Key.Length).ToList();
+
+        foreach (var label in labels)
+        {
+            // Read the current string from whichever family this component belongs to.
+            var current = label is Text legacy ? legacy.text : ((TMP_Text)label).text;
+            if (string.IsNullOrEmpty(current)) continue;
+
+            var matched = false;
+            foreach (var kvp in ordered)
+            {
+                if (!current.Contains(kvp.Key)) continue;
+
+                var lse = label.gameObject.GetComponent<LocalizeStringEvent>()
+                    ?? label.gameObject.AddComponent<LocalizeStringEvent>();
+                lse.StringReference = new UnityEngine.Localization.LocalizedString(table, kvp.Value);
+
+                // Wire the listener through the public UnityEventTools API. The persistent-call
+                // fields could be written directly through SerializedObject instead, but those
+                // are private serialized names with no compatibility guarantee, and it isn't
+                // necessary. A delegate to the component's public `text` setter, handed to
+                // AddPersistentListener, produces the same serialized call: target = the
+                // component, method = set_text, mode = EventDefined (dynamic).
+                //
+                // The setter has no C# method-group name, so the delegate is built by name.
+                // That is reflection over a *public* member, which is fine; reaching for the
+                // private m_* fields would not be. `set_text` is public on both Text and
+                // TMP_Text, so the same call works for either target.
+                var setText = (UnityAction<string>)System.Delegate.CreateDelegate(
+                    typeof(UnityAction<string>), label, "set_text");
+
+                for (int i = lse.OnUpdateString.GetPersistentEventCount() - 1; i >= 0; i--)
+                {
+                    UnityEventTools.RemovePersistentListener(lse.OnUpdateString, i);
+                }
+                UnityEventTools.AddPersistentListener(lse.OnUpdateString, setText);
+
+                // AddPersistentListener leaves the call at RuntimeOnly, which means the label does
+                // NOT update when the locale changes in the Editor: correct in a build, dormant
+                // while authoring, and it stays dormant through a save and reload. Set the state
+                // explicitly. SetPersistentListenerState is public API on UnityEventBase.
+                // Verified on Unity 6000.5.8f1: without this the listener never fires in Edit mode.
+                var callIndex = lse.OnUpdateString.GetPersistentEventCount() - 1;
+                lse.OnUpdateString.SetPersistentListenerState(
+                    callIndex, UnityEventCallState.EditorAndRuntime);
+
+                EditorUtility.SetDirty(lse);
+                matched = true;
+                break;
+            }
+
+            // A label the mapping never covered is a coverage gap the caller has to see.
+            // Reporting "localized 12" while silently leaving 9 untouched is the failure mode
+            // this return value exists to prevent.
+            if (!matched)
+            {
+                unmatched.Add($"{scenePath} :: {label.gameObject.name} :: \"{current}\"");
+            }
+        }
+
+        return unmatched;
+    }
+}

package/skills/localize-unity-project/scripts/LocalizedFontAsset.cs

@@ -0,0 +1,18 @@
+using UnityEngine;
+using TMPro;
+using UnityEngine.Localization;
+using UnityEngine.Localization.Components;
+
+/// <summary>
+/// Swaps a TMP_Text font based on the active locale using an Asset Table.
+/// Add to any GameObject with a TMP_Text that needs locale-specific fonts (e.g., CJK).
+/// </summary>
+[AddComponentMenu("Localization/Asset/Localized Font Asset")]
+public class LocalizedFontAsset : LocalizedAssetBehaviour<TMP_FontAsset, LocalizedTmpFont>
+{
+    protected override void UpdateAsset(TMP_FontAsset font)
+    {
+        var tmp = GetComponent<TMP_Text>();
+        if (tmp != null) tmp.font = font;
+    }
+}

package/skills/manage-sprite-atlas/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: manage-sprite-atlas
+description: Manages SpriteAtlas assets through a prebuild pipeline, covering master and variant atlases, packing settings, and platform overrides. Use when asked to create or optimize sprite atlases.
+---
+
+# Unity SpriteAtlas V2
+
+Provides *editor-safe* procedural knowledge for scripting atlases in Unity projects. **V2 enforces strict separation between editor authoring and runtime access.**
+
+> ⚠ **Critical V2 Principle**: `SpriteAtlas` is **runtime-only**. `SpriteAtlasAsset` is **editor-only**. Never mix contexts. Always use V2.
+
+## 🚨 CRITICAL: Required Checks and User Inputs Before Implementation
+
+**ALWAYS perform these checks and ask these questions BEFORE generating any code:**
+
+### Read the shipped resources before writing code (REQUIRED)
+
+This skill ships working C# under `resources/`, and the atlas code that goes wrong is almost always
+code written without reading it first. Open the files for the path you are taking, then write.
+
+| Taking this path | Read first |
+|---|---|
+| Any atlas work at all | [resources/authoringvsruntime.cs](resources/authoringvsruntime.cs), [references/common-errors.md](references/common-errors.md) |
+| Prebuild generation (the default) | [resources/spriteatlasprebuildgenerator.cs](resources/spriteatlasprebuildgenerator.cs), [resources/enablespritepacking.cs](resources/enablespritepacking.cs), [resources/savespriteatlasasset.cs](resources/savespriteatlasasset.cs) |
+| Option B, Addressables late-binding | [resources/buildaddressablespostprocess.cs](resources/buildaddressablespostprocess.cs), [resources/spriteatlaslatebinding.cs](resources/spriteatlaslatebinding.cs), [resources/handlelatebinding.cs](resources/handlelatebinding.cs) |
+| Anything that might use an older API | [resources/deprecatedmethods.cs](resources/deprecatedmethods.cs), [resources/dontscriptspriteatlasineditor.cs](resources/dontscriptspriteatlasineditor.cs), [resources/dontpackinruntimebuilds.cs](resources/dontpackinruntimebuilds.cs) |
+
+`resources/` holds 38 files in all, covering custom packers, variants, platform settings, and
+runtime access. Browse the directory when your task is not in the table above rather than inventing
+an approach. Reaching for the API from memory instead of reading these is the single most common
+cause of an atlas that imports cleanly and then does nothing at runtime.
+
+### 0. Check for Existing Scripts (REQUIRED FIRST STEP)
+
+**BEFORE generating any code, scan the project for existing SpriteAtlas scripts generated by this skill.**
+
+Search for files containing the identifier: `// [UNITY-SKILL:SPRITEATLAS]`
+
+**If existing scripts are found, ALWAYS ask the user with this format:**
+
+> "I found existing SpriteAtlas scripts in your project:
+>
+> **Prebuild Generator:**
+> - `Assets/Editor/SpriteAtlas/SpriteAtlasPrebuildGenerator.cs`
+>
+> **Addressables Builder:**
+> - `Assets/Editor/SpriteAtlas/BuildAddressablesPostprocess.cs`
+>
+> **Runtime Loader:**
+> - `Assets/Scripts/SpriteAtlas/SpriteAtlasLateBinding.cs`
+>
+> What would you like to do?"
+
+**Then present options:**
+
+- **Option A: Update existing scripts** (Recommended if requirements changed)
+  - Regenerates scripts at existing paths
+  - Preserves file locations
+  - Updates to latest version
+  - ⚠ May overwrite custom modifications
+
+- **Option B: Create new scripts with different names**
+  - Generates alongside existing scripts
+  - Allows multiple atlas configurations
+  - Original scripts remain unchanged
+  - You'll need to specify new names/paths
+
+- **Option C: Abort (keep existing unchanged)**
+  - No code generation
+  - No changes to project
+  - Use this if you want to keep current setup
+
+**User Choice Handling:**
+
+- **If A chosen**: Regenerate at existing paths, increment version to 2.0.1+
+- **If B chosen**: Ask for new script names (e.g., "SpriteAtlasPrebuild_Custom.cs"), then generate
+- **If C chosen**: Stop immediately, inform user no changes were made
+
+### 1. Delivery Mechanism (REQUIRED)
+
+Before generating code, ask "How do you want to deliver the sprite atlases?" and read [delivery-mechanism.md](references/delivery-mechanism.md) to compare the two answers. It covers Built-in data against Addressables late-binding, with the trade-offs and the use cases that fit each.
+
+### 2. SpritePacker Mode (REQUIRED)
+
+**Enable Sprite Packer mode before creating atlases, then read the setting back and confirm it took.**
+Use the code in [resources/enablespritepacking.cs](resources/enablespritepacking.cs); it sets
+`EditorSettings.spritePackerMode` and configures the importer's packing settings.
+
+This is the step that decides whether the atlas you produce is real. `Disabled` is the zero value of
+`SpritePackerMode`, so any project where nobody has set it carries packing **Disabled**, and an atlas
+created while it is Disabled still imports, still shows up as an asset, and still looks finished, but
+can never pack. Unity says so in the Inspector: *"Sprite Atlas packing is disabled"*. Nothing else in
+the workflow fails, so an atlas shipped this way reads as a success. Do not assume a project is
+already configured: read the value.
+
+So do not treat "I set it" as done. After setting it, read `EditorSettings.spritePackerMode` back,
+confirm it is **not** `Disabled`, and report the value you actually read. If you cannot read it back,
+say so rather than assuming the write landed.
+
+**DO NOT edit meta files DIRECTLY.**
+
+## 🚨 CRITICAL: Default Approach is Prebuild Generation
+
+**ALWAYS use `IPreprocessBuildWithReport` to automatically generate or update SpriteAtlases during the build pipeline.** This is the DEFAULT and REQUIRED approach unless the user EXPLICITLY requests manual authoring.
+
+### ❌ DO NOT Create Manual Menu Item Scripts
+
+**NEVER create scripts with `[MenuItem]` attributes for atlas generation unless explicitly requested.** The prebuild approach eliminates the need for manual clicks. **Only use manual authoring for**: Hand-optimized layouts, specific sprite arrangements, or editor preview requirements. See [Advanced: Manual Authoring](#advanced-manual-authoring).
+
+## 🚨 CRITICAL: Sprite Source Location Restriction
+
+**ONLY add sprites from the project's Assets folder. NEVER add sprites from Unity built-in assets, packages, or external locations.** Unity built-in assets cannot be packed into SpriteAtlas, and package assets may cause import/dependency issues.
+
+## Critical V2 Architecture
+
+Read [v2-architecture.md](references/v2-architecture.md) before writing any atlas code, so editor authoring and runtime access stay in their own contexts. It gives the component-per-context table and the invalid-to-correct pairs behind most cross-context errors.
+
+## Core V2 Workflow (Reference Only - Use Prebuild Instead)
+
+> 🚨 **IMPORTANT**: This workflow is shown for reference only. **ALWAYS implement this inside `IPreprocessBuildWithReport.OnPreprocessBuild()`** rather than in manual scripts. See [Quick Start](#quick-start-automated-prebuild-generation-default-approach).
+
+## Prerequisites
+
+- Unity 6000.3 or later
+- Basic understanding of Unity's asset import pipeline
+- Familiarity with editor scripting for atlas authoring
+
+## Quick Start: Automated Prebuild Generation (DEFAULT APPROACH)
+
+### Overview
+
+**This is the PRIMARY and DEFAULT way to create SpriteAtlases.** Implement `IPreprocessBuildWithReport` to automatically generate or update SpriteAtlases before each build based on categorization rules. No manual menu clicks required.
+
+### Workflow Steps
+
+**Step 1: Ask User for Delivery Mechanism**
+
+Before generating code, ask: "How do you want to deliver the sprite atlases: (A) Built-in data or (B) Late-binding via Addressables?"
+
+**Step 2: Create Prebuild Script**
+
+Create this script in an Editor folder. Customize based on user's delivery choice:
+
+### Option A: Built-in Data (Immediate Loading)
+
+Built-in Data (Immediate Loading)
+
+### Option B: Late-Binding via Addressables (On-Demand Loading)
+
+> 🚨 **CRITICAL ENFORCEMENT**: When user chooses Addressables, you MUST generate ALL THREE scripts below. Never generate just one or two - all three are required for Addressables delivery to work.
+
+**Required Scripts (ALL THREE MANDATORY):**
+
+1. **Prebuild script** (IPreprocessBuildWithReport) - Generates atlases, creates Addressables entries
+2. **Build Addressables script** (IPostprocessBuildWithReport) - Builds Addressables content bundles
+3. **Late-binding runtime loader** (MonoBehaviour) - Handles on-demand loading at runtime
+
+See [references/addressables-delivery.md](references/addressables-delivery.md) for complete implementation.
+
+#### Complete Workflow
+
+Read [complete-workflow.md](references/complete-workflow.md) for the end-to-end flow, including the categorization rules and build steps that follow it. It traces the branch from the existing-script check through the Option A or Option B script set.
+
+### Common Categorization Patterns
+
+**By Folder Structure:**
+```csharp
+GenerateAtlasByFolder("Assets/Art/UI/Buttons", "Assets/Atlases/UI_Buttons.spriteatlasv2");
+GenerateAtlasByFolder("Assets/Art/UI/Icons", "Assets/Atlases/UI_Icons.spriteatlasv2");
+GenerateAtlasByFolder("Assets/Art/Characters/Player", "Assets/Atlases/Player.spriteatlasv2");
+```
+
+**By Naming Convention:**
+```csharp
+GenerateAtlasByNaming("Assets/Art", "icon_", "Assets/Atlases/Icons.spriteatlasv2");
+GenerateAtlasByNaming("Assets/Art", "bg_", "Assets/Atlases/Backgrounds.spriteatlasv2");
+```
+
+### Variant Generation in Prebuild
+
+Generate variant atlases for different resolutions.
+
+## Advanced: Manual Authoring (NOT Default - Use Only When Explicitly Requested)
+
+Read [advanced-manual-authoring.md](references/advanced-manual-authoring.md) only when the user explicitly asks for manual control, custom sprite ordering, or an editor preview. It lists when manual authoring applies and when it does not, then points at the full patterns.
+
+## Key Requirements (V2-Specific)
+
+Read [key-requirements.md](references/key-requirements.md) before writing atlas code and again before declaring the work done. It is the V2 checklist, covering script tagging, `includeInBuild`, the two-step importer pattern, `.spriteatlasv2`, and platform formats.
+
+## Detailed Reference
+
+- **Addressables Delivery**: [references/addressables-delivery.md](references/addressables-delivery.md) - Complete late-binding setup with Addressables
+- **Manual Authoring**: [references/manual-authoring.md](references/manual-authoring.md) - Manual patterns (NOT default - use only when explicitly requested)
+- **Common Errors**: [references/common-errors.md](references/common-errors.md) - Invalid patterns and API corrections
+- **API Reference**: [references/api.md](references/api.md) - Complete V2 class documentation
+- **Custom Packing**: [references/custom-packing.md](references/custom-packing.md) - `ScriptablePacker` implementation
+- **Best Practices**: [references/best-practices.md](references/best-practices.md) - Optimization and common pitfalls
+
+## Namespaces
+
+Read [namespaces.md](references/namespaces.md) when a type does not resolve, because `UnityEditor.U2D` and `UnityEngine.U2D` hold different V2 types. It gives the exact `using` blocks for editor and runtime scripts.

package/skills/manage-sprite-atlas/references/addressables-delivery.md

@@ -0,0 +1,58 @@
+# Late-Binding via Addressables (On-Demand Loading)
+
+This approach creates SpriteAtlases that are NOT included in the build and are instead loaded on-demand via the Addressables system.
+
+## When to Use
+
+- DLC content, optional features, large assets, downloadable content
+- Level-specific sprites (100+ levels)
+- Localized UI sprites (multiple languages)
+- Character skins or cosmetics
+- Any content that can be loaded asynchronously
+
+## Prerequisites
+
+1. Install Addressables package: `com.unity.addressables`
+2. Initialize Addressables in your project (Window > Asset Management > Addressables > Groups)
+
+## 🚨 REQUIRED: Three Scripts for Addressables Delivery
+
+When using Addressables, you MUST create all three scripts:
+
+1. **Prebuild Script** - Generates atlases and creates Addressables entries (IPreprocessBuildWithReport)
+2. **Build Addressables Script** - Builds Addressables content as build step (IPostprocessBuildWithReport)
+3. **Late-Binding Runtime Loader** - Loads atlases at runtime via SpriteAtlasManager
+
+## Script 1: Prebuild Atlas Generator with Addressables
+
+See [resources/spriteatlasprebuildgenerator.cs](../resources/spriteatlasprebuildgenerator.cs).
+
+## Script 2: Build Addressables Content (REQUIRED)
+
+This script runs AFTER atlas generation to build the Addressables content bundle.
+
+See [resources/buildaddressablespostprocess.cs](../resources/buildaddressablespostprocess.cs).
+
+## Script 3: Late-Binding Runtime Loader (REQUIRED)
+
+This script handles automatic on-demand loading of atlases via SpriteAtlasManager callbacks.
+
+See [resources/spriteatlaslatebinding.cs](../resources/spriteatlaslatebinding.cs).
+
+## Setup Instructions
+
+1. **Create all three scripts** in your Editor folder (Scripts 1 & 2) and runtime folder (Script 3)
+2. **Add SpriteAtlasLateBinding to scene**: Attach to a persistent GameObject in your first scene
+3. **Build your project**: Atlases will be generated, addressables will be built automatically
+4. **Runtime**: Sprites automatically trigger atlas loading on first access
+
+## Key Points
+
+1. **🚨 All three scripts are REQUIRED** - Missing any will break Addressables delivery
+2. **includeInBuild = false**: This is critical for Addressables delivery
+3. **Automatic Addressables setup**: The prebuild script creates addressable entries automatically
+4. **Build Addressables as postprocess step**: Script 2 ensures content bundles are built
+5. **Late-binding via SpriteAtlasManager**: Script 3 handles on-demand loading automatically
+6. **Address naming**: Uses the atlas filename as the address (e.g., "UI_Atlas")
+7. **Async loading**: Runtime loading is asynchronous and automatic
+8. **Resource management**: Handles automatically release all atlases on destroy

package/skills/manage-sprite-atlas/references/advanced-manual-authoring.md

@@ -0,0 +1,19 @@
+# Advanced: Manual Authoring (NOT Default - Use Only When Explicitly Requested)
+
+> ⚠ **WARNING**: Manual authoring is NOT the default approach. Only use these patterns when the user EXPLICITLY requests manual control or editor preview during development.
+
+> 🚨 **DEFAULT APPROACH**: Use prebuild generation with `IPreprocessBuildWithReport` instead. See [Quick Start](../SKILL.md#quick-start-automated-prebuild-generation-default-approach).
+
+**Manual authoring is appropriate ONLY for:**
+- Hand-optimized sprite layouts where exact positioning matters
+- Custom sprite ordering requirements
+- Editor preview during authoring workflow
+- Explicitly requested by user
+
+**DO NOT use manual authoring when:**
+- User asks to "create sprite atlas" (use prebuild)
+- User asks to "optimize sprites" (use prebuild)
+- User asks for automated workflow (use prebuild)
+- No specific manual control requirement mentioned
+
+For complete manual authoring patterns including master atlas creation, variant creation, and runtime loading, see [references/manual-authoring.md](manual-authoring.md).