@hnode/tidy 0.0.0-stage → 0.19.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/NOTICE ADDED
@@ -0,0 +1,23 @@
1
+ Tidy — Window tiling for GNOME
2
+ Copyright (C) 2026 hojin-v
3
+
4
+ SPDX-License-Identifier: GPL-3.0-or-later
5
+
6
+ Tidy is free software: you can redistribute it and/or modify it under the
7
+ terms of the GNU General Public License as published by the Free Software
8
+ Foundation, either version 3 of the License, or (at your option) any later
9
+ version.
10
+
11
+ Tidy is distributed in the hope that it will be useful, but WITHOUT ANY
12
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
13
+ FOR A PARTICULAR PURPOSE. See the GNU General Public License for details.
14
+
15
+ You should have received a copy of the GNU General Public License along
16
+ with this program in the LICENSE file. If not, see
17
+ https://www.gnu.org/licenses/.
18
+
19
+ This notice applies to the source code and documentation in this repository
20
+ unless a file states otherwise. GNOME, Mutter, GTK and other system
21
+ dependencies remain subject to their respective licenses.
22
+
23
+ Source: https://github.com/hojin-v/Tidy
package/README.md CHANGED
@@ -1,3 +1,210 @@
1
- # Temporary Holding Version
1
+ # Tidy
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [한국어](README.md) · [English](docs/README.en.md)
4
+
5
+ Window tiling for GNOME
6
+
7
+ 창을 화면 위로 끌어 배치를 고르고, 단축키로 모니터 사이를 이동하세요.
8
+ Ubuntu GNOME에서 창을 나누고 정렬하는 확장입니다.
9
+
10
+ ![GNOME](https://img.shields.io/badge/GNOME-46%E2%80%9350-4a86cf)
11
+ ![Session](https://img.shields.io/badge/session-Wayland-555555)
12
+ ![Languages](https://img.shields.io/badge/languages-KO%20%7C%20EN-555555)
13
+ [![npm](https://img.shields.io/npm/v/@hnode/tidy)](https://www.npmjs.com/package/@hnode/tidy)
14
+ [![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green)](LICENSE)
15
+
16
+ [Install](#install) · [Features](#features) · [Quick Start](#quick-start) · [Shortcuts](#shortcuts) · [Uninstall](#uninstall)
17
+
18
+ ## Overview
19
+
20
+ Tidy는 GNOME Shell에서 실행되는 창 배치 확장입니다. 여러 모니터를 사용할 때도 화면 상단 안쪽에서 배치 선택기를 열고, 그림으로 표시된 칸에 창을 놓을 수 있습니다.
21
+
22
+ <img src="docs/preview.png" alt="무채색 배치 그림으로 구성된 Tidy 상단 선택기" width="760">
23
+
24
+ 설정 화면과 메뉴는 시스템 언어를 따릅니다. 한국어와 영어를 지원하며, 그 외 언어에서는 영어로 표시합니다.
25
+
26
+ ## Features
27
+
28
+ | 기능 | 동작 |
29
+ | --- | --- |
30
+ | 상단 배치 선택기 | 창을 상단 중앙으로 끌어 원하는 칸에 놓습니다. 6가지 배치를 한 행으로 표시합니다. |
31
+ | 최대화 버튼 선택기 | 최대화·복원 버튼에 마우스를 잠시 올리면 3열 × 2행 선택기가 열립니다. 설정에서 켜고 끌 수 있습니다. |
32
+ | 가장자리 배치 | 중앙 외 상단은 최대화, 왼쪽·오른쪽 가장자리는 절반 배치로 동작합니다. |
33
+ | 창 보기 연동 | Super로 창 보기와 한 행 선택기를 함께 엽니다. 창 미리보기를 배치 칸에 끌어 놓습니다. Super+A 앱 목록에서는 선택기를 숨깁니다. |
34
+ | 사용자 지정 단축키 | Super+Alt 조합으로 절반·¼·⅓·⅔ 배치를 지정하고 단축키를 바꿀 수 있습니다. |
35
+ | 다중 모니터 | 같은 방향키를 반복하면 해당 방향의 모니터로 이동합니다. 선택기 크기도 모니터에 맞춰 조절합니다. |
36
+ | 함께 크기 조절 | 타일 창의 공유 경계를 끌면 맞닿은 창을 함께 조절합니다. 기본값은 켬입니다. |
37
+ | 남은 공간 채우기 | 빈 영역에 실행 중인 앱 아이콘을 표시해 다음 창을 고릅니다. 기본값은 끔입니다. |
38
+ | 크기와 간격 설정 | 일반 선택기와 창 보기 선택기의 크기, 창 사이 간격을 조절합니다. |
39
+
40
+ 선택기의 100%는 이전 버전의 115% 크기입니다. 기존에 저장한 크기는 새 기준으로 환산합니다. 상하 분할과 전체화면 카드는 제거하고, 동일한 너비의 3열 오른쪽에 **¼ · ½ · ¼** 배치를 제공합니다. 최대화 단축키와 화면 상단 가장자리의 최대화 동작은 계속 사용할 수 있습니다. 자동 크기 조절은 16인치 내장 화면의 기준 크기를 유지하며, 32인치 외장 화면에서는 이전 자동 크기의 약 80%를 새 100%로 사용합니다.
41
+
42
+ 최대화 버튼 선택기는 약 0.35초 대기 후 열리며, 칸을 클릭하면 해당 창을 배치합니다. 바깥으로 마우스를 옮기거나 Esc를 누르면 닫힙니다. 실제 버튼의 접근성 정보를 사용하므로, 버튼 정보를 제공하지 않는 자체 제목 표시줄에서는 표시되지 않습니다. 영어·한국어 최대화·복원 버튼을 지원하며, Brave의 ‘복구’ 버튼과 중첩된 제목 표시줄도 감지합니다.
43
+
44
+ ## Platform Support
45
+
46
+ | 환경 | 상태 |
47
+ | --- | --- |
48
+ | Ubuntu 26.04 · GNOME 50.1 · Wayland | 독립 GNOME 세션의 실제 Wayland 창과 가상 모니터 2개로 검증 |
49
+ | GNOME 46–49 | 호환 버전으로 선언되어 있으나 실기 검증 전 |
50
+ | X11 | 실기 검증 전 |
51
+ | KDE · Xfce · Windows · macOS | 지원 대상 아님 |
52
+
53
+ 실행에는 시스템 Python 3와 PyGObject, GJS, GTK 4/libadwaita가 필요합니다. npm 명령에는 Node.js 18 이상이 필요하며, 소스에서 직접 빌드할 때는 `glib-compile-schemas`도 필요합니다. 설치된 GNOME 확장은 Node.js나 npm 프로세스를 띄우지 않습니다.
54
+
55
+ ## Install
56
+
57
+ ### npm
58
+
59
+ 패키지 이름은 **`@hnode/tidy`**, 실행 명령은 **`tidy`**입니다. npm 공개 후 다음 명령으로 패키지와 GNOME 확장을 설치합니다.
60
+
61
+ ```bash
62
+ npm install -g @hnode/tidy
63
+ tidy install
64
+ ```
65
+
66
+ 전역 설치 없이 한 번의 명령으로 설치할 수도 있습니다.
67
+
68
+ ```bash
69
+ npx @hnode/tidy@latest install
70
+ ```
71
+
72
+ `tidy doctor`로 시스템 요구 사항을 확인하고, `tidy --help`로 명령 목록을 볼 수 있습니다. `tidy install`은 sudo 없이 현재 GNOME 사용자로 실행하세요. npm 패키지 설치만으로 데스크톱 설정이 바뀌지는 않습니다.
73
+
74
+ **처음 설치하고 다시 로그인하면 자동으로 동작합니다. 매번 터미널에서 실행할 필요가 없습니다.** 설정은 앱 목록의 **Tidy**나 상단 격자 아이콘에서 열 수 있습니다.
75
+
76
+ ### Source
77
+
78
+ 저장소를 내려받아 직접 설치할 수도 있습니다.
79
+
80
+ ```bash
81
+ git clone https://github.com/hojin-v/Tidy.git
82
+ cd Tidy
83
+ /usr/bin/python3 scripts/manage.py install
84
+ ```
85
+
86
+ Git 대신 [Download ZIP](https://github.com/hojin-v/Tidy/archive/refs/heads/main.zip)으로 받아 압축을 푼 폴더에서 마지막 명령을 실행해도 됩니다. 설치는 사용자 계정으로 진행합니다.
87
+
88
+ **최초 설치 후 로그아웃하고 다시 로그인하면 자동 활성화됩니다.** 이후 앱 목록의 **Tidy** 또는 상단 패널의 격자 아이콘에서 설정을 엽니다.
89
+
90
+ 설치에 필요한 도구도 설치 위치에 복사합니다. **설치가 완료되면 다운로드한 ZIP과 소스 폴더, npm 캐시를 삭제해도 됩니다.** 첫 재로그인 전에 원본 폴더를 삭제해도 자동 적용됩니다.
91
+
92
+ ## Quick Start
93
+
94
+ 1. 창의 제목 표시줄을 잡으면 상단에 선택기 인식 영역이 얇게 나타납니다.
95
+ 2. 그 영역으로 끌면 선택기가 펼쳐지고 창이 작은 미리보기로 줄어듭니다. 원하는 배치 칸으로 포인터를 옮깁니다.
96
+ 3. 마우스를 놓으면 창을 배치합니다. 빈 곳에서 놓으면 취소합니다.
97
+
98
+ **Super**를 누르면 창 보기와 한 행 배치 선택기가 함께 열립니다. **Super+A**로 앱 목록을 열면 선택기와 배치 미리보기를 숨기고, 창 보기로 돌아오면 다시 표시합니다. 창 미리보기를 원하는 칸에 끌어 놓거나, 칸을 클릭해 원래 포커스된 창을 배치할 수 있습니다. 검색은 글자를 입력할 때 나타납니다.
99
+
100
+ 창 보기에서는 창 미리보기를 잡고 움직이는 즉시 작아지며, 놓거나 취소하면 원래 크기로 돌아옵니다. 배치 칸에 놓으면 작은 미리보기에서 배치 위치로 이어집니다.
101
+
102
+ 남은 공간의 창 선택 옵션을 켰다면 빈 영역의 앱 아이콘을 선택하세요. 현재 창이나 다른 영역을 클릭하거나 Esc를 누르면 추가 배치 없이 마칩니다.
103
+
104
+ 선택기는 Ubuntu Dock의 애니메이션 시간과 곡선을 따라 상단에서 미끄러져 나옵니다. 선택 영역을 벗어나면 창이 원래 크기로 돌아오며, 놓으면 작은 미리보기에서 배치 위치로 이어집니다.
105
+
106
+ 배치 미리보기는 선택기와 같은 차콜·회색 톤의 은은한 테두리와 옅은 반투명 음영, 부드러운 그림자로 표시합니다. 좌우·상단 가장자리에서도 같은 영역에 머무르는 동안 안정적으로 유지됩니다.
107
+
108
+ ## Shortcuts
109
+
110
+ 배치 단축키는 **Super+Alt** 조합으로 통일되어 있습니다. 설정의 **단축키** 탭에서 바꿀 수 있습니다.
111
+
112
+ | 단축키 | 동작 |
113
+ | --- | --- |
114
+ | Super | 창 보기와 배치 선택기 열기 / 닫기 |
115
+ | Super + A | GNOME 앱 목록 전환 · 배치 선택기는 숨김 |
116
+ | Super + Alt + ← / → | 왼쪽 / 오른쪽 절반 배치. 같은 방향 반복 시 다음 모니터로 이동하며 양 끝에서는 반대편 끝으로 순환 |
117
+ | Super + Alt + ↑ / ↓ | 위쪽 / 아래쪽 절반 배치. 같은 방향 반복 시 위·아래 모니터로 이동하며 양 끝에서는 반대편 끝으로 순환 |
118
+ | Super + Alt + Enter | 최대화 / 이전 크기·배치로 복귀 |
119
+ | Super + Alt + U / I / J / K | 왼쪽 위 / 오른쪽 위 / 왼쪽 아래 / 오른쪽 아래 ¼ |
120
+ | Super + Alt + D / F / G | 왼쪽 / 가운데 / 오른쪽 ⅓ |
121
+ | Super + Alt + E / T | 왼쪽 / 오른쪽 ⅔ |
122
+ | Super + Alt + C | 가운데 ¾ 크기 |
123
+ | Super + Alt + Space | 배치 선택기 열기 |
124
+ | Super + Alt + N | 다음 모니터로 이동 |
125
+
126
+ 가장 왼쪽 모니터의 왼쪽 절반에서 **Super+Alt+←**를 누르면 가장 오른쪽 모니터의 오른쪽 절반으로 이동합니다. 가장 오른쪽의 오른쪽 절반에서 **Super+Alt+→**를 누르면 가장 왼쪽의 왼쪽 절반으로 이동합니다. 순환할 때는 창이 가장자리로 나갔다가 반대쪽에서 들어오는 모션을 사용합니다. 모니터가 하나면 순환하지 않습니다.
127
+
128
+ 위쪽 절반에서 **Super+Alt+↑**를 한 번 더 누르면 위 모니터의 아래쪽 절반으로 이동하고, 아래쪽 절반에서 **Super+Alt+↓**를 한 번 더 누르면 아래 모니터의 위쪽 절반으로 이동합니다. 맨 위·맨 아래에서도 반대편 끝으로 순환합니다.
129
+
130
+ ## Settings
131
+
132
+ 앱 목록의 **Tidy** 또는 **상단 격자 아이콘 → 설정 및 단축키…**에서 변경합니다. 설정은 즉시 반영됩니다.
133
+
134
+ - **기존 Super+방향키 창 배치 끄기**: GNOME 기본 배치 단축키를 끕니다. 해제하거나 Tidy를 종료하면 기존 단축키를 복원합니다.
135
+ - **모니터에 맞춰 선택기 크기 자동 조절**: 내장 화면을 기준으로 큰 외장 모니터의 선택기를 적당히 키웁니다. 기본값은 켬입니다.
136
+ - **배치 선택기 크기 / 창 보기 선택기 크기**: 기본 크기는 같으며, 창 보기의 크기를 별도로 조절할 수 있습니다.
137
+ - **선택기 너비에 인식 범위 맞추기**: 기본값은 켬입니다. 모니터별 선택기 너비에 맞춰 인식 영역과 드래그 안내를 조절합니다. 끄면 기존 사용자 지정 너비를 사용합니다.
138
+ - **남은 공간의 창 선택**: 배치 후 빈 영역에 앱 아이콘을 표시합니다. 기본값은 끔입니다.
139
+ - **최대화 버튼에 마우스를 올리면 배치 선택기 표시**: 최대화·복원 버튼에서 선택기를 엽니다. 기본값은 켬이며 상단 드래그 선택기와 별도로 끌 수 있습니다.
140
+
141
+ CLI에서도 설정이나 상태를 확인할 수 있습니다.
142
+
143
+ ```bash
144
+ tidy prefs
145
+ tidy status
146
+ ```
147
+
148
+ CLI 없이 설치된 관리 도구를 직접 실행할 수도 있습니다. 원본 소스 폴더는 필요하지 않습니다.
149
+
150
+ ```bash
151
+ tidy_manager="${XDG_DATA_HOME:-$HOME/.local/share}/gnome-shell/extensions/winubun@winubun.local/scripts/manage.py"
152
+ /usr/bin/python3 "$tidy_manager" prefs
153
+ /usr/bin/python3 "$tidy_manager" status
154
+ ```
155
+
156
+ ## Update
157
+
158
+ npm 패키지를 갱신한 뒤 확장에 적용합니다. `tidy update`는 현재 설치된 npm 패키지 버전을 적용합니다.
159
+
160
+ ```bash
161
+ npm install -g @hnode/tidy@latest
162
+ tidy update
163
+ ```
164
+
165
+ 전역 설치를 사용하지 않았다면 `npx @hnode/tidy@latest install`을 다시 실행하세요. 소스 설치는 새 소스를 받아 설치 명령을 다시 실행합니다.
166
+
167
+ ```bash
168
+ git pull --ff-only
169
+ /usr/bin/python3 scripts/manage.py install
170
+ ```
171
+
172
+ 확장 코드의 버전이 바뀌면 로그아웃 후 다시 로그인하세요. GNOME은 로그인 중 불러온 JavaScript를 캐시하므로 확장을 껐다 켜는 것만으로는 새 코드가 적용되지 않습니다. 기존 설정과 단축키는 유지합니다.
173
+
174
+ ## Uninstall
175
+
176
+ 확장을 먼저 제거하고 npm CLI를 제거합니다.
177
+
178
+ ```bash
179
+ tidy uninstall
180
+ npm uninstall -g @hnode/tidy
181
+ ```
182
+
183
+ npx로 설치했다면 `npx @hnode/tidy@latest uninstall`을 사용하세요. **npm 패키지만 제거해도 GNOME 확장은 계속 설치된 상태로 남습니다.**
184
+
185
+ CLI가 없어도 어느 폴더에서든 설치된 도구로 제거할 수 있습니다.
186
+
187
+ ```bash
188
+ /usr/bin/python3 "${XDG_DATA_HOME:-$HOME/.local/share}/gnome-shell/extensions/winubun@winubun.local/scripts/manage.py" uninstall
189
+ ```
190
+
191
+ 확장과 앱 실행기를 제거하고, 변경했던 GNOME 설정과 기존 타일링 확장 상태를 복원합니다. Tidy의 사용자 설정과 단축키는 재설치를 위해 보관합니다.
192
+
193
+ 기존 타일링 확장의 사용자 설치본을 삭제하여 현재 세션에서 인식되지 않는 경우, 남아 있는 시스템 원본을 다음 로그인에 활성화하도록 설정하고 Tidy 제거를 완료합니다. 이 경우 출력 안내에 따라 다시 로그인하세요. 이전 확장이 시스템에서도 제거됐다면 재설치하지 않습니다.
194
+
195
+ 경로의 `winubun`은 기존 설정과 고정한 실행기의 호환성을 위해 유지한 내부 이름입니다.
196
+
197
+ ## Notes
198
+
199
+ - **Ubuntu Tiling Assistant**가 켜져 있으면 설치 도구가 원래 상태를 기록하고 비활성화합니다. `uninstall` 시 복원합니다. 확장 앱에서 Tidy만 끄면 Tiling Assistant는 중지 상태로 남습니다.
200
+ - 확장 관리자의 X는 확장 오류를 뜻합니다. `gnome-extensions info tiling-assistant@ubuntu.com`과 Shell 로그로 실제 상태를 확인하세요. Ubuntu Tiling Assistant의 중복 초기화나 해제 실패로 남은 동작은 해당 확장의 복구가 필요합니다. Tidy와 동시에 켜지 않도록 관리하세요.
201
+ - 앱이 요구하는 최소 창 크기나 터미널의 크기 단위 때문에 작은 칸에 정확히 맞지 않을 수 있습니다. 전체 화면 앱과 이동·크기 변경을 허용하지 않는 창은 배치 대상에서 제외합니다.
202
+ - 문제를 신고할 때는 GNOME 버전, Wayland/X11 여부, 모니터 배치와 재현 순서를 [Issues](https://github.com/hojin-v/Tidy/issues)에 남겨 주세요.
203
+
204
+ 개발 명령, 테스트 범위와 진단 경로는 [Development](docs/DEVELOPMENT.md), npm 게시 절차는 [Releasing](docs/RELEASING.md)에서 확인할 수 있습니다.
205
+
206
+ ## License
207
+
208
+ Copyright © 2026 hojin-v. **GNU GPL v3.0 or later**로 배포합니다.
209
+
210
+ 라이선스 전문은 [LICENSE](LICENSE), 프로젝트 고지는 [NOTICE](NOTICE)를 참고하세요.
package/bin/tidy.js ADDED
@@ -0,0 +1,97 @@
1
+ #!/usr/bin/env node
2
+ import {spawnSync} from 'node:child_process';
3
+ import {existsSync, readFileSync, realpathSync} from 'node:fs';
4
+ import {homedir} from 'node:os';
5
+ import {dirname, join} from 'node:path';
6
+ import {fileURLToPath} from 'node:url';
7
+ import {createTranslator} from '../lib/i18nCore.js';
8
+
9
+ const root = dirname(dirname(fileURLToPath(import.meta.url)));
10
+ const metadata = JSON.parse(readFileSync(join(root, 'metadata.json'), 'utf8'));
11
+ const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
12
+ const catalogs = JSON.parse(readFileSync(join(root, 'lib/translations.json'), 'utf8'));
13
+ const commands = ['install', 'update', 'uninstall', 'prefs', 'status', 'doctor'];
14
+
15
+ export function main({args = process.argv.slice(2), env = process.env, platform = process.platform,
16
+ uid = process.getuid?.(), packageRoot = root, run = spawnSync, out = console.log, error = console.error} = {}) {
17
+ const languages = env.LANGUAGE?.split(':') ?? [env.LC_ALL || env.LC_MESSAGES || env.LANG || 'C'];
18
+ const _ = createTranslator(catalogs, languages);
19
+ const help = () => out(_('Tidy · Window tiling for GNOME\n\nUsage: tidy <command>\n\n install Install Tidy for the current user\n update Install this package version of Tidy\n uninstall Remove Tidy and restore desktop settings\n prefs Open settings and shortcuts\n status Show the installed extension status\n doctor Check system requirements\n\nInstall: npx @hnode/tidy@latest install\nAfter installation, log out and back in once.'));
20
+ if (!args.length || args[0] === 'help' || args.includes('--help') || args.includes('-h')) {
21
+ help();
22
+ return 0;
23
+ }
24
+ if (args.length === 1 && ['--version', '-v'].includes(args[0])) {
25
+ out(manifest.version);
26
+ return 0;
27
+ }
28
+ if (args.length !== 1 || !commands.includes(args[0])) {
29
+ error(_('Unknown command. Run tidy --help.'));
30
+ return 2;
31
+ }
32
+ if (platform !== 'linux') {
33
+ error(_('Tidy requires Linux with GNOME Shell 46–50.'));
34
+ return 1;
35
+ }
36
+ const command = args[0];
37
+ if (uid === 0 && command !== 'doctor') {
38
+ error(_('Run Tidy as your desktop user, without sudo.'));
39
+ return 1;
40
+ }
41
+ const installing = ['install', 'update'].includes(command);
42
+ const fullCheck = installing || command === 'doctor';
43
+ const python = 'import gi; from gi.repository import Gio, GLib' + (fullCheck ?
44
+ "; gi.require_version('Gtk', '4.0'); gi.require_version('Adw', '1'); from gi.repository import Gtk, Adw" : '');
45
+ const options = {encoding: 'utf8', env: {...env, PYTHONDONTWRITEBYTECODE: '1'}};
46
+ const check = run('/usr/bin/python3', ['-c', python], options);
47
+ if (check.error || check.status !== 0) {
48
+ error(_('System Python with PyGObject is required. For installation and settings, GTK 4 and libadwaita are also required.'));
49
+ error('sudo apt install python3 python3-gi gjs gir1.2-gtk-4.0 gir1.2-adw-1');
50
+ if (check.stderr?.trim()) error(check.stderr.trim());
51
+ return 1;
52
+ }
53
+ if (fullCheck) {
54
+ const gjs = run('gjs', ['--version'], options);
55
+ const shell = run('gnome-shell', ['--version'], options);
56
+ const version = shell.stdout?.trim().match(/(\d+)(?:\.\d+)*$/)?.[1];
57
+ if (gjs.error || gjs.status !== 0 || shell.error || shell.status !== 0 || !metadata['shell-version'].includes(version)) {
58
+ error(_('Tidy requires GJS and GNOME Shell 46–50. Run this command in your GNOME desktop session.'));
59
+ return 1;
60
+ }
61
+ if (command === 'doctor') {
62
+ out(_('System requirements are available.'));
63
+ out(shell.stdout.trim());
64
+ out(gjs.stdout.trim());
65
+ return 0;
66
+ }
67
+ }
68
+ const installed = join(env.XDG_DATA_HOME || join(homedir(), '.local/share'),
69
+ 'gnome-shell/extensions', metadata.uuid, 'scripts/manage.py');
70
+ if (['prefs', 'status'].includes(command) && !existsSync(installed)) {
71
+ error(_('Tidy is not installed. Run tidy install first.'));
72
+ return 1;
73
+ }
74
+ const manager = installing || !existsSync(installed) ? join(packageRoot, 'scripts/manage.py') : installed;
75
+ const parameters = [manager, installing ? 'install' : command];
76
+ if (installing) {
77
+ const archive = join(packageRoot, 'dist', `${metadata.uuid}.shell-extension.zip`);
78
+ if (!existsSync(archive)) {
79
+ error(_('The bundled extension is missing. Reinstall @hnode/tidy, or run npm run build from the source checkout.'));
80
+ return 1;
81
+ }
82
+ parameters.push('--archive', archive);
83
+ }
84
+ const result = run('/usr/bin/python3', parameters, {...options, stdio: 'inherit'});
85
+ if (result.error) {
86
+ error(result.error.message);
87
+ return 1;
88
+ }
89
+ if (result.signal) {
90
+ error(_('Tidy was interrupted.'));
91
+ return 1;
92
+ }
93
+ return result.status ?? 1;
94
+ }
95
+
96
+ if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
97
+ process.exitCode = main();
@@ -0,0 +1,82 @@
1
+ # Development
2
+
3
+ [한국어 안내](../README.md) · [English guide](README.en.md)
4
+
5
+ Tidy는 GNOME Shell 확장과 설치·복구를 담당하는 Python 도구로 구성됩니다. 설치 및 실행에 npm 패키지는 필요하지 않습니다.
6
+
7
+ ## Build and checks
8
+
9
+ 순수 계산 테스트와 JavaScript 구문 검사에는 Node.js가 필요합니다. 스키마 검사와 패키지 생성에는 `glib-compile-schemas`, 설치·복구 테스트에는 시스템 Python의 PyGObject와 GJS가 필요합니다.
10
+
11
+ ```bash
12
+ npm test
13
+ npm run check
14
+ /usr/bin/python3 -m unittest discover -s tests -p 'test_*.py'
15
+ /usr/bin/python3 scripts/manage.py build
16
+ npm run test:package
17
+ ```
18
+
19
+ 빌드 결과는 `dist/winubun@winubun.local.shell-extension.zip`입니다. 런타임 소스, 컴파일한 스키마, 설치·복구 도구와 GPL 라이선스 파일을 포함합니다.
20
+
21
+ npm 배포 이름은 `@hnode/tidy`이고 실행 파일은 `bin/tidy.js`입니다. `npm pack`은 `prepack`에서 확장 ZIP을 빌드합니다. 사용자 설치 시에는 이 ZIP을 사용하므로 npm 패키지 경로가 읽기 전용이어도 됩니다. 게시 절차와 tarball 검증은 [Releasing](RELEASING.md)을 참고하세요.
22
+
23
+ ```bash
24
+ GSETTINGS_BACKEND=memory GSETTINGS_SCHEMA_DIR="$PWD/schemas" gjs -m tests/lease-smoke.js
25
+ /usr/bin/python3 scripts/test-shell.py
26
+ ```
27
+
28
+ Shell 통합 테스트는 GNOME 50의 `gnome-shell-test-tool`과 가상 모니터를 지원하는 그래픽 환경이 필요합니다. 별도 D-Bus, 런타임 디렉터리, 설정 저장소와 헤드리스 Wayland 세션에서 동작합니다.
29
+
30
+ Ubuntu Dock이 설치된 환경에서는 `TIDY_TEST_UBUNTU_DOCK=1 /usr/bin/python3 scripts/test-shell.py`로 Tidy 활성화 후 앱 표시 버튼이 교체되는 경우도 확인합니다. 선택기는 교체된 버튼과 관계없이 Super+A 앱 목록에서 숨겨져야 합니다.
31
+
32
+ ## Test coverage
33
+
34
+ - 화면 분할 경계, 창 사이 간격, 음수 좌표와 방향별 모니터 탐색
35
+ - 한국어·영어 설정 화면과 실제 가상 키보드 입력, 사용자 지정 단축키
36
+ - 배치 애니메이션의 실제 시작 위치·크기, 연속 배치와 모니터 간 이동
37
+ - 양 끝 모니터의 순환 이동, 모니터별 클리핑을 적용한 나가기·들어오기 모션과 연속 입력 정리
38
+ - 실제 가상 모니터를 위아래로 재배치한 상태에서 상하 단축키 이동·순환과 원래 모니터 구성 복원
39
+ - 좌우·상단 미리보기의 연속 표시·불투명도 유지, 선택기 옵션을 켜거나 꺼도 동일한 표시와 취소
40
+ - 최대화·복귀, 창·앱 보기의 드래그 배치와 화면 전환
41
+ - 모니터별 선택기 크기, 고해상도 배율, 타일 창의 공유 경계 조절
42
+ - Ubuntu Dock 설정을 따르는 선택기 슬라이드, 드래그 안내와 선택기 너비에 맞춘 감지 영역
43
+ - 실제 창 크기를 유지하는 축소 미리보기, 이동 추적·취소와 배치 애니메이션 연결
44
+ - 창·앱 보기의 드래그 즉시 축소, 포인터 고정·복귀와 작은 상태에서의 배치 전환
45
+ - 남은 공간의 앱 선택, 빈 곳 클릭·Esc 취소와 최소화된 창 복원
46
+ - 원본 소스 폴더를 삭제한 뒤 설치 도구 실행·설정 복구·제거
47
+ - 제거 전 확장 종료 확인, 기존 확장 복원 상태 검증과 삭제된 사용자 확장의 시스템 원본을 다음 로그인에 복원
48
+ - npm tarball 전역 설치, 읽기 전용 패키지, CLI 언어·의존성 검사와 설치된 복구 도구 연결
49
+ - 확장 재활성화·빠른 켜기/끄기, 예약 작업 취소와 데스크톱 설정 복원
50
+ - 상단 한 행 선택기와 최대화 버튼 3열 × 2행 선택기의 개별 배치·클릭·드래그
51
+ - Super+A 앱 목록에서 선택기·드롭 영역·추가 검색 여백 해제와 창 보기 복귀
52
+ - 중첩된 Chromium 제목 표시줄, 한국어 ‘복구’ 버튼, 창 그림자를 포함한 접근성 좌표 변환
53
+
54
+ 접근성 조회 회귀 검사는 `gjs -m tests/maximizeButton-smoke.js`로 실행합니다. 실제 Brave 검사는 `TIDY_BRAVE_BINARY`에 실행 파일을 지정하고 `python3 scripts/test-shell.py --brave-only`로 실행합니다. 별도 프로필·GTK 3 제목 표시줄·정적 `data:` 페이지를 사용하며, 테스트용 버튼 설정 모듈을 만들 C 컴파일러와 GTK 3 런타임이 필요합니다. Snap 내부 바이너리를 직접 사용하는 환경의 테스트에 한해 `TIDY_BRAVE_TEST_NO_SANDBOX=1`을 지정할 수 있으며, 실제 사용자 브라우저의 설정이나 실행 인자는 바꾸지 않습니다.
55
+
56
+ 헤드리스 백엔드에서는 실제 마우스 제스처 대신 잡기 신호·포인터 좌표·Shell 드래그 콜백을 주입합니다. 실제 마우스 조작은 데스크톱에서 별도로 확인해야 합니다. GNOME 46–49와 X11은 실기 검증 전입니다.
57
+
58
+ ## Diagnostics
59
+
60
+ 기본 경로이며 XDG 디렉터리 설정을 따릅니다.
61
+
62
+ | 경로 | 용도 |
63
+ | --- | --- |
64
+ | `~/.local/share/gnome-shell/extensions/winubun@winubun.local/` | 확장과 설치된 관리 도구 |
65
+ | `~/.local/share/applications/winubun.desktop` | Tidy 실행기 |
66
+ | `~/.local/state/winubun/launcher.log` | 실행 오류 |
67
+ | `~/.local/state/winubun/preferences.log` | 설정 앱 로그 |
68
+ | `~/.local/state/winubun/handover.json` | 기존 타일링 확장 복원 기록 |
69
+
70
+ ```bash
71
+ gnome-shell --version
72
+ gnome-extensions info winubun@winubun.local
73
+ journalctl --user -b --no-pager -g 'Tidy|winubun|JS ERROR'
74
+ ```
75
+
76
+ GNOME은 세션 중 읽은 확장 JavaScript를 캐시합니다. 실행 코드 업데이트 시 `metadata.json`의 버전을 올리고 다시 로그인해 검증하세요. Python 설치 도구만 바뀐 경우에는 확장 코드 버전을 그대로 유지할 수 있습니다.
77
+
78
+ ## References
79
+
80
+ - [GNOME extension anatomy](https://gjs.guide/extensions/overview/anatomy.html)
81
+ - [GNOME extension preferences](https://gjs.guide/extensions/development/preferences.html)
82
+ - [Mutter window API](https://gnome.pages.gitlab.gnome.org/mutter/meta/class.Window.html)
@@ -0,0 +1,209 @@
1
+ # Tidy
2
+
3
+ [한국어](../README.md) · [English](README.en.md)
4
+
5
+ Window tiling for GNOME
6
+
7
+ Drag a window to the top of a monitor, choose a layout, and move between monitors with keyboard shortcuts.
8
+ Tidy adds flexible window arrangement to Ubuntu GNOME.
9
+
10
+ ![GNOME](https://img.shields.io/badge/GNOME-46%E2%80%9350-4a86cf)
11
+ ![Session](https://img.shields.io/badge/session-Wayland-555555)
12
+ ![Languages](https://img.shields.io/badge/languages-KO%20%7C%20EN-555555)
13
+ [![npm](https://img.shields.io/npm/v/@hnode/tidy)](https://www.npmjs.com/package/@hnode/tidy)
14
+ [![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green)](../LICENSE)
15
+
16
+ [Install](#install) · [Features](#features) · [Quick Start](#quick-start) · [Shortcuts](#shortcuts) · [Uninstall](#uninstall)
17
+
18
+ ## Overview
19
+
20
+ Tidy is a GNOME Shell extension for arranging windows. Its layout picker opens inside the top-center area of each monitor, making it easier to use across multiple displays.
21
+
22
+ <img src="preview.png" alt="Tidy's top layout picker with grayscale layout diagrams" width="760">
23
+
24
+ The interface follows your desktop language. Korean and English are supported; other languages fall back to English.
25
+
26
+ ## Features
27
+
28
+ | Feature | Behavior |
29
+ | --- | --- |
30
+ | Top layout picker | Drop a window into one of six layouts arranged in a single row. |
31
+ | Maximize button picker | Hover over maximize or restore to open a three-column, two-row picker below the button. Can be disabled in settings. |
32
+ | Edge snapping | Other top edges maximize; left and right edges tile halves. |
33
+ | Overview integration | Press Super to open window overview and the single-row picker together. The picker is hidden in the Super+A application grid. |
34
+ | Custom shortcuts | Use Super+Alt for halves, quarters, thirds and two-thirds; customize the bindings in settings. |
35
+ | Multiple monitors | Repeat an arrow shortcut to move to the monitor in that direction, including above and below. Picker size adapts to each monitor. |
36
+ | Linked resizing | Drag shared boundaries to resize adjacent tiled windows together. Enabled by default. |
37
+ | Optional snap assist | Choose running app icons inside empty regions to fill the remaining space. Disabled by default. |
38
+ | Size and spacing | Adjust picker sizes and window gaps, including a separate overview picker size. |
39
+
40
+ The 100% picker size now matches the previous 115% size. Saved sizes are converted to the new reference. Top/bottom and maximize cards are removed, and a **¼ · ½ · ¼** layout sits immediately to the right of equal thirds. Maximize shortcuts and top-edge maximization remain available. Automatic sizing preserves the 16-inch built-in reference; on a 32-inch external monitor, the new 100% matches approximately 80% of the previous automatic size.
41
+
42
+ The maximize button picker waits about 350 milliseconds before opening. Click a cell to arrange that window, move away or press Esc to dismiss. It uses actual accessibility button information and supports English and Korean maximize/restore labels, including Brave’s Korean restore control and nested titlebar containers; custom titlebars that do not expose these controls are skipped. The option defaults to on and is independent of top-edge dragging.
43
+
44
+ ## Platform Support
45
+
46
+ | Environment | Status |
47
+ | --- | --- |
48
+ | Ubuntu 26.04 · GNOME 50.1 · Wayland | Tested with real Wayland windows and two virtual monitors in an isolated GNOME session |
49
+ | GNOME 46–49 | Declared compatible; not yet tested on those versions |
50
+ | X11 | Not yet tested |
51
+ | KDE · Xfce · Windows · macOS | Outside the supported platform |
52
+
53
+ Runtime requirements: system Python 3 with PyGObject, GJS, and GTK 4/libadwaita. npm commands require Node.js 18 or later. Building from source also requires `glib-compile-schemas`. The installed GNOME extension does not run a Node.js or npm process.
54
+
55
+ ## Install
56
+
57
+ ### npm
58
+
59
+ The package is **`@hnode/tidy`** and the command is **`tidy`**. Once published to npm, install the package and register the GNOME extension:
60
+
61
+ ```bash
62
+ npm install -g @hnode/tidy
63
+ tidy install
64
+ ```
65
+
66
+ Or install without keeping a global npm package:
67
+
68
+ ```bash
69
+ npx @hnode/tidy@latest install
70
+ ```
71
+
72
+ Use `tidy doctor` to check system requirements and `tidy --help` to list commands. Run `tidy install` as your GNOME desktop user, without sudo. Installing the npm package alone does not change desktop settings.
73
+
74
+ **After the initial installation and logout/login, Tidy starts automatically. You do not need a terminal for daily use.** Open settings from **Tidy** in the app list or the top-panel grid icon.
75
+
76
+ ### Source
77
+
78
+ You can also download the repository and install directly:
79
+
80
+ ```bash
81
+ git clone https://github.com/hojin-v/Tidy.git
82
+ cd Tidy
83
+ /usr/bin/python3 scripts/manage.py install
84
+ ```
85
+
86
+ Alternatively, use [Download ZIP](https://github.com/hojin-v/Tidy/archive/refs/heads/main.zip), extract it, and run the last command from that folder. Installation runs under your user account.
87
+
88
+ **Log out and back in after the first installation.** Tidy activates automatically. Open its settings from **Tidy** in the application list or the grid icon in the top panel.
89
+
90
+ All runtime tools are copied into the installation. **You can delete the downloaded ZIP, source folder and npm cache after installation succeeds**, even before the first logout/login.
91
+
92
+ ## Quick Start
93
+
94
+ 1. Grab a window by its title bar. A thin hint appears at the top of the monitor.
95
+ 2. Drag into that area to reveal the layouts and shrink the window into a small preview. Move the pointer onto the desired layout cell.
96
+ 3. Release to tile the window. Release over empty space to cancel.
97
+
98
+ Press **Super** to open window overview and the single-row layout picker together. **Super+A** hides the picker and previews while the application grid is open; returning to window overview restores them. Drag a window preview into a cell, or click a cell to place the previously focused window. Search appears when you type.
99
+
100
+ Window previews shrink as soon as you start dragging in window overview, and return to their original size on release or cancellation. Dropping a window into a layout continues directly from the miniature to its final placement.
101
+
102
+ With snap assist enabled, select an app icon in an empty region to tile its window there. Click the current window or another area, or press Esc, to finish without any additional placements.
103
+
104
+ The picker slides down using Ubuntu Dock's animation duration and curve. Leaving the selection area restores the window's size; dropping onto a cell animates directly from the miniature to its destination.
105
+
106
+ Placement previews share the picker's charcoal and gray theme, with a soft outline, subtle translucent fill and gentle shadow. They remain stable while you hold a window at a side or top edge.
107
+
108
+ ## Shortcuts
109
+
110
+ Placement shortcuts consistently use **Super+Alt**. Change them in the **Shortcuts** tab.
111
+
112
+ | Shortcut | Action |
113
+ | --- | --- |
114
+ | Super | Open / close GNOME's overview and the layout picker |
115
+ | Super + A | Toggle GNOME's application grid |
116
+ | Super + Alt + ← / → | Tile to the left / right half; repeat to move in that direction, wrapping at the outer edges |
117
+ | Super + Alt + ↑ / ↓ | Tile to the top / bottom half; repeat to move above / below, wrapping at the outer edges |
118
+ | Super + Alt + Enter | Maximize / restore the previous size and placement |
119
+ | Super + Alt + U / I / J / K | Top-left / top-right / bottom-left / bottom-right quarter |
120
+ | Super + Alt + D / F / G | Left / center / right third |
121
+ | Super + Alt + E / T | Left / right two-thirds |
122
+ | Super + Alt + C | Centered three-quarter size |
123
+ | Super + Alt + Space | Open the layout picker |
124
+ | Super + Alt + N | Move to the next monitor |
125
+
126
+ From the left half of the leftmost monitor, **Super+Alt+←** wraps to the right half of the rightmost monitor. From the right half of the rightmost monitor, **Super+Alt+→** wraps to the left half of the leftmost monitor. The window slides out through one outer edge and enters through the opposite edge. A single monitor does not wrap.
127
+
128
+ From a top half, repeat **Super+Alt+↑** to enter the upper monitor's bottom half. From a bottom half, repeat **Super+Alt+↓** to enter the lower monitor's top half. At the topmost or bottommost edge, movement wraps to the opposite outer edge with the same sliding motion.
129
+
130
+ ## Settings
131
+
132
+ Open **Tidy** from the application list, or choose **Settings and shortcuts…** from the top-panel grid icon. Changes take effect immediately.
133
+
134
+ - **Disable native Super+arrow tiling** disables GNOME's original tiling shortcuts. Turning it off or disabling Tidy restores them.
135
+ - **Adapt picker size to each monitor** keeps the built-in display as the baseline and gently enlarges the picker on larger external displays. Enabled by default.
136
+ - **Layout picker size / Overview picker size** default to equal sizes. The overview picker has its own relative size setting.
137
+ - **Match activation width to picker** keeps the activation area and drag hint aligned with the picker on each monitor. Enabled by default; turn it off to use your custom width.
138
+ - **Choose windows for the remaining space** shows running app icons in empty layout regions. Disabled by default.
139
+
140
+ Open settings or check status from the CLI:
141
+
142
+ ```bash
143
+ tidy prefs
144
+ tidy status
145
+ ```
146
+
147
+ You can also use the installed management tool directly. The source folder is not needed:
148
+
149
+ ```bash
150
+ tidy_manager="${XDG_DATA_HOME:-$HOME/.local/share}/gnome-shell/extensions/winubun@winubun.local/scripts/manage.py"
151
+ /usr/bin/python3 "$tidy_manager" prefs
152
+ /usr/bin/python3 "$tidy_manager" status
153
+ ```
154
+
155
+ ## Update
156
+
157
+ Update the npm package, then apply its extension version. `tidy update` installs the version bundled with the currently installed npm package:
158
+
159
+ ```bash
160
+ npm install -g @hnode/tidy@latest
161
+ tidy update
162
+ ```
163
+
164
+ For npx installations, rerun `npx @hnode/tidy@latest install`. For source installations, download the latest source and rerun the installer:
165
+
166
+ ```bash
167
+ git pull --ff-only
168
+ /usr/bin/python3 scripts/manage.py install
169
+ ```
170
+
171
+ Log out and back in when the extension code version changes. GNOME caches JavaScript for the session, so toggling the extension does not reload it. Existing settings and shortcuts are preserved.
172
+
173
+ ## Uninstall
174
+
175
+ Remove the extension first, then the npm CLI:
176
+
177
+ ```bash
178
+ tidy uninstall
179
+ npm uninstall -g @hnode/tidy
180
+ ```
181
+
182
+ For npx installations, use `npx @hnode/tidy@latest uninstall`. **Removing only the npm package leaves the GNOME extension installed.**
183
+
184
+ Without the CLI, run the installed tool from any directory:
185
+
186
+ ```bash
187
+ /usr/bin/python3 "${XDG_DATA_HOME:-$HOME/.local/share}/gnome-shell/extensions/winubun@winubun.local/scripts/manage.py" uninstall
188
+ ```
189
+
190
+ This removes the extension and application launcher and restores the GNOME settings and competing tiling-extension state that Tidy changed. Tidy's custom settings and shortcuts are kept for reinstallation.
191
+
192
+ If removing a user-installed tiling extension made its UUID unavailable in the current session, the uninstaller enables any remaining system copy for the next login and completes Tidy removal. Log out and back in when prompted. An extension removed from the system entirely is not reinstalled.
193
+
194
+ The `winubun` path is a stable internal name retained for compatibility with existing settings and pinned launchers.
195
+
196
+ ## Notes
197
+
198
+ - If **Ubuntu Tiling Assistant** is enabled, the installer records its state and disables it. `uninstall` restores it. Disabling only Tidy in GNOME's extension manager leaves Tiling Assistant disabled.
199
+ - Application minimum sizes and terminal resize increments can prevent an exact fit. Fullscreen windows and windows that disallow movement or resizing are excluded.
200
+ - An X in the extension manager indicates an extension error. Check `gnome-extensions info tiling-assistant@ubuntu.com` and the Shell logs for its actual state. Duplicate initialization or failed cleanup in Ubuntu Tiling Assistant requires repairing that extension. Keep it disabled while using Tidy.
201
+ - When reporting a problem in [Issues](https://github.com/hojin-v/Tidy/issues), include your GNOME version, Wayland/X11 session, monitor arrangement and reproduction steps.
202
+
203
+ See [Development](DEVELOPMENT.md) for development commands, test coverage and diagnostic paths, and [Releasing](RELEASING.md) for npm publication.
204
+
205
+ ## License
206
+
207
+ Copyright © 2026 hojin-v. Distributed under **GNU GPL v3.0 or later**.
208
+
209
+ See [LICENSE](../LICENSE) for the full terms and [NOTICE](../NOTICE) for the project notice.