first commit

2026-08-05 19:25:11 -04:00
commit 642f9cb39f
1 changed files with 62 additions and 0 deletions
@@ -0,0 +1,62 @@
+# hangul-overview-latin
+
+GNOME Shell extension. When the Activities Overview opens, it flips ibus-hangul's
+`InputMode` property to Latin so overview search accepts Latin text immediately.
+The input source stays `hangul` — only the mode changes, so nothing needs to be
+switched back afterwards.
+
+Private extension. Not published to extensions.gnome.org.
+
+## Layout
+
+    hangul-overview-latin@timothykim.net/   source (metadata.json, extension.js)
+    *.shell-extension.zip                   packed build output
+    plan.md                                 design notes
+
+## Installed as
+
+A symlink from the extensions directory into this repo:
+
+    ~/.local/share/gnome-shell/extensions/hangul-overview-latin@timothykim.net
+        -> <this repo>/hangul-overview-latin@timothykim.net
+
+Editing the source therefore edits the installed extension. The catch: moving,
+renaming, or deleting this repo silently breaks the extension. To make the
+install independent of the repo, replace the symlink with a real copy:
+
+    rm ~/.local/share/gnome-shell/extensions/hangul-overview-latin@timothykim.net
+    gnome-extensions install --force hangul-overview-latin@timothykim.net.shell-extension.zip
+
+## Install on another machine
+
+    gnome-extensions install hangul-overview-latin@timothykim.net.shell-extension.zip
+    gnome-extensions enable hangul-overview-latin@timothykim.net
+
+Then log out and back in. Wayland cannot restart GNOME Shell in place, so a new
+or changed extension only takes effect on the next login.
+
+## Rebuild the zip after editing
+
+    gnome-extensions pack hangul-overview-latin@timothykim.net/ --force
+
+## Maintenance
+
+`metadata.json` declares `"shell-version": ["50"]`. On the next GNOME major
+upgrade the extension is flagged out of date and stops loading. Fix by adding
+the new version to that array, then logging out and back in:
+
+    "shell-version": ["50", "51"]
+
+The APIs it uses (`Main.overview`, `getInputSourceManager()`,
+`getIBusManager().activateProperty()`) are internal Shell APIs and can change
+between releases, so re-test after a major upgrade rather than assuming the
+version bump alone is enough.
+
+## Checking whether it is running
+
+    gnome-extensions info hangul-overview-latin@timothykim.net
+
+This reports `State: INACTIVE` whenever the screen is locked, which is normal:
+the extension does not declare the `unlock-dialog` session mode, so GNOME
+suspends it on the lock screen and resumes it on unlock. Check it from an
+unlocked session, where it should read `ACTIVE`.