Add edit=true to aether:// to open imports in the editor

A theme link can now carry edit=true to load its colors and wallpaper into
the Aether editor instead of applying or installing them. Nothing is written
to disk until the user clicks Apply, so it's the safe way to ship a palette as
a starting point rather than a finished theme. edit overrides silent and
as_omarchy_theme.

Backend: extract the shared stage-into-state logic from ConfirmExternalImport
so the new OpenExternalImportInEditor reuses it (stage + emit, no apply). The
URL handler routes edit/omarchy/silent/default through a single precedence
switch. The confirm dialog is parameterized on the edit flag (heading, body,
button, action).

Author: bjarneo

cli/url_handler.go

@@ -98,6 +98,9 @@ func runHandleURL(args []string, templatesFS embed.FS) int {
 	if v := strings.ToLower(q.Get("silent")); v == "true" || v == "1" || v == "yes" {
 		imp.Silent = true
 	}
+	if v := strings.ToLower(q.Get("edit")); v == "true" || v == "1" || v == "yes" {
+		imp.Edit = true
+	}
 	if v := q.Get("as_omarchy_theme"); v != "" {
 		if !safeThemeName.MatchString(v) {
 			fmt.Fprintf(os.Stderr, "Error: as_omarchy_theme must match [A-Za-z0-9][A-Za-z0-9_.-]* (got %q)\n", v)
@@ -111,17 +114,23 @@ func runHandleURL(args []string, templatesFS embed.FS) int {
 		return 1
 	}
 
-	// Omarchy install: drop files into ~/.config/omarchy/themes/<name>/ and
-	// run omarchy-theme-set. Always silent — installing into a system
-	// location is the consent action by the publisher.
-	if imp.OmarchyThemeName != "" {
+	// Routing precedence, highest first:
+	//   edit    — fall through to the GUI pending-import path below (load the
+	//             assets into the editor, apply nothing). Safest action, so it
+	//             wins over silent / as_omarchy_theme.
+	//   omarchy — install into ~/.config/omarchy/themes/<name>/ and run
+	//             omarchy-theme-set. Always silent: installing into a system
+	//             location is the publisher's consent action.
+	//   silent  — apply directly in this process, no GUI, no dialog. Matches
+	//             `aether --import-colors-toml`; first-party flows only, since
+	//             any web page can construct silent URLs.
+	//   default — stage and hand off to the GUI confirm dialog (below).
+	switch {
+	case imp.Edit:
+		// fall through to pending.Write + GUI handoff below
+	case imp.OmarchyThemeName != "":
 		return runOmarchyInstall(&imp, templatesFS)
-	}
-
-	// Silent mode: apply directly in this process, no GUI, no dialog.
-	// Matches `aether --import-colors-toml` semantics — first-party flows
-	// only, since any web page can construct silent URLs.
-	if imp.Silent {
+	case imp.Silent:
 		return runSilentApply(&imp, templatesFS)
 	}
 

docs/web-handler.md

@@ -17,9 +17,10 @@ aether://apply?<param>=<https-url>[&<param>=<https-url>...]
 | `wallpaper` | URL to an image | Sets the wallpaper (no re-extraction, even when used alone) |
 | `mode` | `light` or `dark` | Forces Aether into light or dark mode before applying. Omit to fall back to the colors.toml's own `mode = "..."` field, then to the current setting. |
 | `silent` | `true` | Skips the confirm dialog and applies immediately. Use with care: any web page can construct this URL. |
+| `edit` | `true` | Opens the colors and wallpaper in the Aether editor without applying. Nothing is written to disk until the user clicks Apply. Overrides `silent` and `as_omarchy_theme`. |
 | `as_omarchy_theme` | theme name | Installs into `~/.config/omarchy/themes/<name>/` and runs `omarchy-theme-set <name>`. Always silent. Name must match `[A-Za-z0-9][A-Za-z0-9_.-]*`. |
 
-`external_theme` and `colors` are mutually exclusive; `external_theme` wins when both are present. `wallpaper` can be combined with either, or used alone. `mode` and `silent` can be combined with any of the above.
+`external_theme` and `colors` are mutually exclusive; `external_theme` wins when both are present. `wallpaper` can be combined with either, or used alone. `mode` and `silent` can be combined with any of the above. `edit` takes precedence over `silent` and `as_omarchy_theme`: if `edit=true` is present, the import always opens in the editor instead of applying or installing.
 
 ## Examples
 
@@ -59,6 +60,12 @@ Install as a named Omarchy theme and activate it:
 aether://apply?colors=https://themes.example.com/nord/colors.toml&wallpaper=https://themes.example.com/nord/wp.jpg&as_omarchy_theme=nord
 ```
 
+Open in the editor to tweak before applying (nothing is written until you click Apply):
+
+```
+aether://apply?colors=https://themes.example.com/nord/colors.toml&wallpaper=https://themes.example.com/nord/wp.jpg&edit=true
+```
+
 ## HTML button
 
 ```html
@@ -109,6 +116,14 @@ Wallpaper-only silent links preserve the current palette by reading the existing
 
 The trade-off is real, though: any web page can produce a silent-apply link. Only mark links silent inside flows where the user has already opted in to the theme they're about to install (your own theme gallery, an in-app catalog), and prefer the default interactive flow for third-party content.
 
+### `edit=true` — open in the editor without applying
+
+`edit=true` is the opposite of `silent`: instead of applying, the import loads the palette and wallpaper into the Aether editor and switches to the editor tab. Nothing is written to disk, no target apps are touched, and the Omarchy themes directory is untouched. The user reviews the palette in the confirm dialog, clicks "Open in editor", tweaks colors or adjustments, then applies manually when ready.
+
+It's the safest action, so it wins over the auto-apply flags: a link with both `edit=true` and `silent=true` (or `as_omarchy_theme=...`) opens in the editor and ignores the others. Use it for "customize this theme" buttons where the published palette is a starting point rather than a finished product.
+
+The launch/IPC handoff is the same as the default interactive flow: if the GUI is running it's notified over IPC, otherwise it's launched and picks up the staged import on startup.
+
 ## What's not supported
 
 - Other actions. Only `apply` is recognized; `aether://save?...`, `aether://preview?...`, etc. return an error.

external_import.go

@@ -34,6 +34,7 @@ type ExternalImportPreview struct {
 	Wallpaper        string   `json:"wallpaper,omitempty"`
 	ThemeName        string   `json:"theme_name,omitempty"`
 	Mode             string   `json:"mode,omitempty"` // "light" | "dark" | ""
+	Edit             bool     `json:"edit"`           // load into the editor without applying (aether://...&edit=true)
 }
 
 // loadPendingImport reads the staged file, stores it in memory, and emits
@@ -72,6 +73,7 @@ func (a *App) buildPreview(imp *pending.Import) ExternalImportPreview {
 		HasWallpaper:     imp.Wallpaper != "",
 		Wallpaper:        imp.Wallpaper,
 		Mode:             imp.Mode,
+		Edit:             imp.Edit,
 	}
 
 	if imp.ExternalTheme != "" {
@@ -107,11 +109,14 @@ func (a *App) GetPendingExternalImport() *ExternalImportPreview {
 	return &preview
 }
 
-// ConfirmExternalImport applies the staged assets verbatim: the colors.toml
-// (or external_theme JSON) becomes the palette without re-extracting, and
-// the wallpaper is set as the background. Auto-extraction is intentionally
-// skipped — the user already trusts the source.
-func (a *App) ConfirmExternalImport() error {
+// stageImportIntoState consumes the pending import and writes its assets into
+// the app state: the colors.toml (or external_theme JSON) becomes the palette
+// verbatim (no re-extraction — the user trusts the source), the wallpaper is set
+// as the background, and light/dark mode is resolved. It pushes an undo snapshot
+// and clears the handoff file, but does NOT apply the theme to disk or emit to
+// the frontend; callers decide whether to apply (ConfirmExternalImport) or just
+// load it for editing (OpenExternalImportInEditor).
+func (a *App) stageImportIntoState() error {
 	a.pending.mu.Lock()
 	imp := a.pending.curr
 	a.pending.curr = nil
@@ -190,6 +195,17 @@ func (a *App) ConfirmExternalImport() error {
 		}
 	}
 
+	return nil
+}
+
+// ConfirmExternalImport stages the pending assets into the editor state and then
+// applies the theme to all configured target apps. Used by the confirm dialog's
+// Apply button.
+func (a *App) ConfirmExternalImport() error {
+	if err := a.stageImportIntoState(); err != nil {
+		return err
+	}
+
 	result, err := a.writer.ApplyTheme(a.state, theme.DefaultApplySettings())
 	if err != nil {
 		return fmt.Errorf("apply: %w", err)
@@ -201,6 +217,19 @@ func (a *App) ConfirmExternalImport() error {
 	return nil
 }
 
+// OpenExternalImportInEditor loads the staged assets into the editor without
+// applying them: the palette, extended colors, wallpaper, and light/dark mode
+// become the current editing state and are pushed to the frontend, but nothing
+// is written to disk. Backs the aether://...&edit=true flow so a user can tweak
+// an imported theme and apply it manually when ready.
+func (a *App) OpenExternalImportInEditor() error {
+	if err := a.stageImportIntoState(); err != nil {
+		return err
+	}
+	a.emitIPCStateChanged()
+	return nil
+}
+
 // CancelExternalImport drops the staged import without touching theme state.
 func (a *App) CancelExternalImport() {
 	a.pending.mu.Lock()

frontend/src/lib/components/ExternalImportDialog.svelte

@@ -1,12 +1,13 @@
 <script lang="ts">
     import Modal from '$lib/components/shared/Modal.svelte';
-    import {showToast} from '$lib/stores/ui.svelte';
+    import {showToast, setActiveTab} from '$lib/stores/ui.svelte';
     import {
         loadFullImage,
         getCachedFullImage,
     } from '$lib/stores/imagecache.svelte';
     import {
         ConfirmExternalImport,
+        OpenExternalImportInEditor,
         CancelExternalImport,
         GetPendingExternalImport,
     } from '../../../wailsjs/go/main/App';
@@ -22,11 +23,14 @@
         wallpaper?: string;
         theme_name?: string;
         mode?: string;
+        edit?: boolean;
     };
 
     let preview = $state<Preview | null>(null);
     let wallpaperDataUrl = $state('');
     let isApplying = $state(false);
+    // edit=true imports load into the editor instead of applying.
+    let isEdit = $derived(!!preview?.edit);
 
     onMount(() => {
         // The backend emits this on startup when a staged file is present,
@@ -87,17 +91,27 @@
         }
     });
 
-    async function handleApply() {
+    // edit=true links load the colors + wallpaper into the editor without
+    // applying, so the user can tweak before hitting Apply themselves. Any
+    // other link applies the theme immediately on confirm.
+    async function handleConfirm() {
         if (!preview) return;
+        const edit = isEdit; // snapshot before the await nulls preview
         isApplying = true;
         try {
-            await ConfirmExternalImport();
-            showToast('Applied');
+            if (edit) {
+                await OpenExternalImportInEditor();
+                setActiveTab('editor');
+                showToast('Loaded into editor');
+            } else {
+                await ConfirmExternalImport();
+                showToast('Applied');
+            }
             preview = null;
         } catch (err) {
-            showToast('Failed to apply');
+            showToast(edit ? 'Failed to load' : 'Failed to apply');
             // eslint-disable-next-line no-console
-            console.error('external-import apply:', err);
+            console.error('external-import confirm:', err);
         } finally {
             isApplying = false;
         }
@@ -116,13 +130,15 @@
 <Modal
     open={preview !== null}
     onclose={handleCancel}
-    onenter={handleApply}
+    onenter={handleConfirm}
     panelClass="w-[420px]"
     z="z-50"
 >
     {#if preview}
         <h3 class="text-fg-primary mb-1 text-[13px] font-medium">
-            Apply theme from web?
+            {isEdit
+                ? 'Open theme from web in editor?'
+                : 'Apply theme from web?'}
         </h3>
         <p class="text-fg-dimmed mb-3 text-[10px] uppercase tracking-wider">
             {assetKind()}
@@ -163,8 +179,13 @@
         </p>
 
         <p class="text-fg-dimmed mb-4 text-[10px]">
-            Aether will replace your palette and background. Only apply from
-            sources you trust.
+            {#if isEdit}
+                Aether will load these colors and wallpaper into the editor.
+                Nothing is applied until you click Apply.
+            {:else}
+                Aether will replace your palette and background. Only apply from
+                sources you trust.
+            {/if}
         </p>
 
         <div class="flex justify-end gap-2">
@@ -177,10 +198,14 @@
             </button>
             <button
                 class="bg-accent hover:bg-accent-hover text-accent-fg px-3 py-1.5 text-[11px] font-medium disabled:opacity-50"
-                onclick={handleApply}
+                onclick={handleConfirm}
                 disabled={isApplying}
             >
-                {isApplying ? 'Applying...' : 'Apply'}
+                {#if isEdit}
+                    {isApplying ? 'Opening...' : 'Open in editor'}
+                {:else}
+                    {isApplying ? 'Applying...' : 'Apply'}
+                {/if}
             </button>
         </div>
     {/if}

frontend/wailsjs/go/main/App.d.ts

@@ -110,6 +110,8 @@ export function LoadBlueprint(arg1: string): Promise<void>;
 
 export function LoadOmarchyThemes(): Promise<Array<omarchy.Theme>>;
 
+export function OpenExternalImportInEditor(): Promise<void>;
+
 export function OpenFileDialog(): Promise<string>;
 
 export function PreviewExtractColors(

frontend/wailsjs/go/main/App.js

@@ -174,6 +174,10 @@ export function LoadOmarchyThemes() {
     return window['go']['main']['App']['LoadOmarchyThemes']();
 }
 
+export function OpenExternalImportInEditor() {
+    return window['go']['main']['App']['OpenExternalImportInEditor']();
+}
+
 export function OpenFileDialog() {
     return window['go']['main']['App']['OpenFileDialog']();
 }

frontend/wailsjs/go/models.ts

@@ -216,6 +216,7 @@ export namespace main {
         wallpaper?: string;
         theme_name?: string;
         mode?: string;
+        edit: boolean;
 
         static createFrom(source: any = {}) {
             return new ExternalImportPreview(source);
@@ -231,6 +232,7 @@ export namespace main {
             this.wallpaper = source['wallpaper'];
             this.theme_name = source['theme_name'];
             this.mode = source['mode'];
+            this.edit = source['edit'];
         }
     }
     export class ExtractFromImagesResult {

internal/pending/pending.go

@@ -22,6 +22,7 @@ type Import struct {
 	Wallpaper        string `json:"wallpaper,omitempty"`
 	Mode             string `json:"mode,omitempty"`               // "light" | "dark" — empty leaves the current setting alone
 	Silent           bool   `json:"silent,omitempty"`             // skip the confirm dialog and apply immediately
+	Edit             bool   `json:"edit,omitempty"`               // load colors + wallpaper into the editor without applying (overrides silent/omarchy)
 	OmarchyThemeName string `json:"omarchy_theme_name,omitempty"` // install as ~/.config/omarchy/themes/<name>/ and run omarchy-theme-set
 	SourceURL        string `json:"source_url,omitempty"`
 	Timestamp        int64  `json:"ts,omitempty"`