@hnode/tidy 0.0.0-stage → 0.18.1
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/LICENSE +674 -0
- package/NOTICE +23 -0
- package/README.md +200 -2
- package/bin/tidy.js +97 -0
- package/dist/winubun@winubun.local.shell-extension.zip +0 -0
- package/docs/DEVELOPMENT.md +74 -0
- package/docs/README.en.md +201 -0
- package/docs/RELEASING.md +59 -0
- package/docs/assist-preview.png +0 -0
- package/docs/preview.png +0 -0
- package/lib/i18nCore.js +15 -0
- package/lib/translations.json +120 -0
- package/metadata.json +15 -0
- package/package.json +52 -4
- package/scripts/i18n.py +23 -0
- package/scripts/manage.py +263 -0
- package/scripts/recover.js +6 -0
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,201 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Tidy
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[한국어](README.md) · [English](docs/README.en.md)
|
|
4
|
+
|
|
5
|
+
Window tiling for GNOME
|
|
6
|
+
|
|
7
|
+
창을 화면 위로 끌어 배치를 고르고, 단축키로 모니터 사이를 이동하세요.
|
|
8
|
+
Windows의 Snap Layouts와 macOS의 Magnet에서 익숙한 창 배치를 Ubuntu GNOME에서 사용할 수 있습니다.
|
|
9
|
+
|
|
10
|
+

|
|
11
|
+

|
|
12
|
+

|
|
13
|
+
[](https://www.npmjs.com/package/@hnode/tidy)
|
|
14
|
+
[](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
|
+
| 상단 배치 선택기 | 창을 상단 중앙으로 끌어 원하는 칸에 놓습니다. 7가지 레이아웃을 제공합니다. |
|
|
31
|
+
| 가장자리 배치 | 중앙 외 상단은 최대화, 왼쪽·오른쪽 가장자리는 절반 배치로 동작합니다. |
|
|
32
|
+
| 창·앱 보기 연동 | Super로 기존 창·앱 보기와 선택기를 함께 열고, 창 미리보기를 배치 칸에 끌어 놓습니다. |
|
|
33
|
+
| 사용자 지정 단축키 | Super+Alt 조합으로 절반·¼·⅓·⅔ 배치를 지정하고 단축키를 바꿀 수 있습니다. |
|
|
34
|
+
| 다중 모니터 | 같은 방향키를 반복하면 해당 방향의 모니터로 이동합니다. 선택기 크기도 모니터에 맞춰 조절합니다. |
|
|
35
|
+
| 함께 크기 조절 | 타일 창의 공유 경계를 끌면 맞닿은 창을 함께 조절합니다. 기본값은 켬입니다. |
|
|
36
|
+
| 남은 공간 채우기 | 빈 영역에 실행 중인 앱 아이콘을 표시해 다음 창을 고릅니다. 기본값은 끔입니다. |
|
|
37
|
+
| 크기와 간격 설정 | 일반 선택기와 창·앱 보기 선택기의 크기, 창 사이 간격을 조절합니다. |
|
|
38
|
+
|
|
39
|
+
## Platform Support
|
|
40
|
+
|
|
41
|
+
| 환경 | 상태 |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| Ubuntu 26.04 · GNOME 50.1 · Wayland | 독립 GNOME 세션의 실제 Wayland 창과 가상 모니터 2개로 검증 |
|
|
44
|
+
| GNOME 46–49 | 호환 버전으로 선언되어 있으나 실기 검증 전 |
|
|
45
|
+
| X11 | 실기 검증 전 |
|
|
46
|
+
| KDE · Xfce · Windows · macOS | 지원 대상 아님 |
|
|
47
|
+
|
|
48
|
+
실행에는 시스템 Python 3와 PyGObject, GJS, GTK 4/libadwaita가 필요합니다. npm 명령에는 Node.js 18 이상이 필요하며, 소스에서 직접 빌드할 때는 `glib-compile-schemas`도 필요합니다. 설치된 GNOME 확장은 Node.js나 npm 프로세스를 띄우지 않습니다.
|
|
49
|
+
|
|
50
|
+
## Install
|
|
51
|
+
|
|
52
|
+
### npm
|
|
53
|
+
|
|
54
|
+
패키지 이름은 **`@hnode/tidy`**, 실행 명령은 **`tidy`**입니다. npm 공개 후 다음 명령으로 패키지와 GNOME 확장을 설치합니다.
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npm install -g @hnode/tidy
|
|
58
|
+
tidy install
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
전역 설치 없이 한 번의 명령으로 설치할 수도 있습니다.
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npx @hnode/tidy@latest install
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`tidy doctor`로 시스템 요구 사항을 확인하고, `tidy --help`로 명령 목록을 볼 수 있습니다. `tidy install`은 sudo 없이 현재 GNOME 사용자로 실행하세요. npm 패키지 설치만으로 데스크톱 설정이 바뀌지는 않습니다.
|
|
68
|
+
|
|
69
|
+
**처음 설치하고 다시 로그인하면 자동으로 동작합니다. 매번 터미널에서 실행할 필요가 없습니다.** 설정은 앱 목록의 **Tidy**나 상단 격자 아이콘에서 열 수 있습니다.
|
|
70
|
+
|
|
71
|
+
### Source
|
|
72
|
+
|
|
73
|
+
저장소를 내려받아 직접 설치할 수도 있습니다.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
git clone https://github.com/hojin-v/Tidy.git
|
|
77
|
+
cd Tidy
|
|
78
|
+
/usr/bin/python3 scripts/manage.py install
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Git 대신 [Download ZIP](https://github.com/hojin-v/Tidy/archive/refs/heads/main.zip)으로 받아 압축을 푼 폴더에서 마지막 명령을 실행해도 됩니다. 설치는 사용자 계정으로 진행합니다.
|
|
82
|
+
|
|
83
|
+
**최초 설치 후 로그아웃하고 다시 로그인하면 자동 활성화됩니다.** 이후 앱 목록의 **Tidy** 또는 상단 패널의 격자 아이콘에서 설정을 엽니다.
|
|
84
|
+
|
|
85
|
+
설치에 필요한 도구도 설치 위치에 복사합니다. **설치가 완료되면 다운로드한 ZIP과 소스 폴더, npm 캐시를 삭제해도 됩니다.** 첫 재로그인 전에 원본 폴더를 삭제해도 자동 적용됩니다.
|
|
86
|
+
|
|
87
|
+
## Quick Start
|
|
88
|
+
|
|
89
|
+
1. 창의 제목 표시줄을 잡으면 상단에 선택기 인식 영역이 얇게 나타납니다.
|
|
90
|
+
2. 그 영역으로 끌면 선택기가 펼쳐지고 창이 작은 미리보기로 줄어듭니다. 원하는 배치 칸으로 포인터를 옮깁니다.
|
|
91
|
+
3. 마우스를 놓으면 창을 배치합니다. 빈 곳에서 놓으면 취소합니다.
|
|
92
|
+
|
|
93
|
+
**Super**를 누르면 기존 창·앱 보기와 배치 선택기가 함께 열립니다. 창 미리보기를 원하는 칸에 끌어 놓거나, 칸을 클릭해 원래 포커스된 창을 배치할 수 있습니다. 검색은 글자를 입력할 때 나타납니다.
|
|
94
|
+
|
|
95
|
+
창·앱 보기에서는 창 미리보기와 앱 아이콘을 잡고 움직이는 즉시 작아지며, 놓거나 취소하면 원래 크기로 돌아옵니다. 선택기 표시를 꺼도 이 모션은 동작합니다. 배치 칸에 놓으면 작은 미리보기에서 배치 위치로 이어집니다.
|
|
96
|
+
|
|
97
|
+
남은 공간의 창 선택 옵션을 켰다면 빈 영역의 앱 아이콘을 선택하세요. 현재 창이나 다른 영역을 클릭하거나 Esc를 누르면 추가 배치 없이 마칩니다.
|
|
98
|
+
|
|
99
|
+
선택기는 Ubuntu Dock의 애니메이션 시간과 곡선을 따라 상단에서 미끄러져 나옵니다. 선택 영역을 벗어나면 창이 원래 크기로 돌아오며, 놓으면 작은 미리보기에서 배치 위치로 이어집니다.
|
|
100
|
+
|
|
101
|
+
배치 미리보기는 선택기와 같은 차콜·회색 톤의 은은한 테두리와 옅은 반투명 음영, 부드러운 그림자로 표시합니다. 좌우·상단 가장자리에서도 같은 영역에 머무르는 동안 안정적으로 유지됩니다.
|
|
102
|
+
|
|
103
|
+
## Shortcuts
|
|
104
|
+
|
|
105
|
+
배치 단축키는 **Super+Alt** 조합으로 통일되어 있습니다. 설정의 **단축키** 탭에서 바꿀 수 있습니다.
|
|
106
|
+
|
|
107
|
+
| 단축키 | 동작 |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| Super | 기존 창·앱 보기와 배치 선택기 열기 / 닫기 |
|
|
110
|
+
| Super + A | GNOME 앱 목록 전환 |
|
|
111
|
+
| Super + Alt + ← / → | 왼쪽 / 오른쪽 절반 배치. 같은 방향 반복 시 다음 모니터로 이동하며 양 끝에서는 반대편 끝으로 순환 |
|
|
112
|
+
| Super + Alt + ↑ / ↓ | 위쪽 / 아래쪽 절반 배치. 같은 방향 반복 시 위·아래 모니터로 이동하며 양 끝에서는 반대편 끝으로 순환 |
|
|
113
|
+
| Super + Alt + Enter | 최대화 / 이전 크기·배치로 복귀 |
|
|
114
|
+
| Super + Alt + U / I / J / K | 왼쪽 위 / 오른쪽 위 / 왼쪽 아래 / 오른쪽 아래 ¼ |
|
|
115
|
+
| Super + Alt + D / F / G | 왼쪽 / 가운데 / 오른쪽 ⅓ |
|
|
116
|
+
| Super + Alt + E / T | 왼쪽 / 오른쪽 ⅔ |
|
|
117
|
+
| Super + Alt + C | 가운데 ¾ 크기 |
|
|
118
|
+
| Super + Alt + Space | 배치 선택기 열기 |
|
|
119
|
+
| Super + Alt + N | 다음 모니터로 이동 |
|
|
120
|
+
|
|
121
|
+
가장 왼쪽 모니터의 왼쪽 절반에서 **Super+Alt+←**를 누르면 가장 오른쪽 모니터의 오른쪽 절반으로 이동합니다. 가장 오른쪽의 오른쪽 절반에서 **Super+Alt+→**를 누르면 가장 왼쪽의 왼쪽 절반으로 이동합니다. 순환할 때는 창이 가장자리로 나갔다가 반대쪽에서 들어오는 모션을 사용합니다. 모니터가 하나면 순환하지 않습니다.
|
|
122
|
+
|
|
123
|
+
위쪽 절반에서 **Super+Alt+↑**를 한 번 더 누르면 위 모니터의 아래쪽 절반으로 이동하고, 아래쪽 절반에서 **Super+Alt+↓**를 한 번 더 누르면 아래 모니터의 위쪽 절반으로 이동합니다. 맨 위·맨 아래에서도 반대편 끝으로 순환합니다.
|
|
124
|
+
|
|
125
|
+
## Settings
|
|
126
|
+
|
|
127
|
+
앱 목록의 **Tidy** 또는 **상단 격자 아이콘 → 설정 및 단축키…**에서 변경합니다. 설정은 즉시 반영됩니다.
|
|
128
|
+
|
|
129
|
+
- **기존 Super+방향키 창 배치 끄기**: GNOME 기본 배치 단축키를 끕니다. 해제하거나 Tidy를 종료하면 기존 단축키를 복원합니다.
|
|
130
|
+
- **모니터에 맞춰 선택기 크기 자동 조절**: 내장 화면을 기준으로 큰 외장 모니터의 선택기를 적당히 키웁니다. 기본값은 켬입니다.
|
|
131
|
+
- **배치 선택기 크기 / 창·앱 보기 선택기 크기**: 기본 크기는 같으며, 창·앱 보기의 크기를 별도로 조절할 수 있습니다.
|
|
132
|
+
- **선택기 너비에 인식 범위 맞추기**: 기본값은 켬입니다. 모니터별 선택기 너비에 맞춰 인식 영역과 드래그 안내를 조절합니다. 끄면 기존 사용자 지정 너비를 사용합니다.
|
|
133
|
+
- **남은 공간의 창 선택**: 배치 후 빈 영역에 앱 아이콘을 표시합니다. 기본값은 끔입니다.
|
|
134
|
+
|
|
135
|
+
CLI에서도 설정이나 상태를 확인할 수 있습니다.
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
tidy prefs
|
|
139
|
+
tidy status
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
CLI 없이 설치된 관리 도구를 직접 실행할 수도 있습니다. 원본 소스 폴더는 필요하지 않습니다.
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
tidy_manager="${XDG_DATA_HOME:-$HOME/.local/share}/gnome-shell/extensions/winubun@winubun.local/scripts/manage.py"
|
|
146
|
+
/usr/bin/python3 "$tidy_manager" prefs
|
|
147
|
+
/usr/bin/python3 "$tidy_manager" status
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## Update
|
|
151
|
+
|
|
152
|
+
npm 패키지를 갱신한 뒤 확장에 적용합니다. `tidy update`는 현재 설치된 npm 패키지 버전을 적용합니다.
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
npm install -g @hnode/tidy@latest
|
|
156
|
+
tidy update
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
전역 설치를 사용하지 않았다면 `npx @hnode/tidy@latest install`을 다시 실행하세요. 소스 설치는 새 소스를 받아 설치 명령을 다시 실행합니다.
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
git pull --ff-only
|
|
163
|
+
/usr/bin/python3 scripts/manage.py install
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
확장 코드의 버전이 바뀌면 로그아웃 후 다시 로그인하세요. GNOME은 로그인 중 불러온 JavaScript를 캐시하므로 확장을 껐다 켜는 것만으로는 새 코드가 적용되지 않습니다. 기존 설정과 단축키는 유지합니다.
|
|
167
|
+
|
|
168
|
+
## Uninstall
|
|
169
|
+
|
|
170
|
+
확장을 먼저 제거하고 npm CLI를 제거합니다.
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
tidy uninstall
|
|
174
|
+
npm uninstall -g @hnode/tidy
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
npx로 설치했다면 `npx @hnode/tidy@latest uninstall`을 사용하세요. **npm 패키지만 제거해도 GNOME 확장은 계속 설치된 상태로 남습니다.**
|
|
178
|
+
|
|
179
|
+
CLI가 없어도 어느 폴더에서든 설치된 도구로 제거할 수 있습니다.
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
/usr/bin/python3 "${XDG_DATA_HOME:-$HOME/.local/share}/gnome-shell/extensions/winubun@winubun.local/scripts/manage.py" uninstall
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
확장과 앱 실행기를 제거하고, 변경했던 GNOME 설정과 기존 타일링 확장 상태를 복원합니다. Tidy의 사용자 설정과 단축키는 재설치를 위해 보관합니다.
|
|
186
|
+
|
|
187
|
+
경로의 `winubun`은 기존 설정과 고정한 실행기의 호환성을 위해 유지한 내부 이름입니다.
|
|
188
|
+
|
|
189
|
+
## Notes
|
|
190
|
+
|
|
191
|
+
- **Ubuntu Tiling Assistant**가 켜져 있으면 설치 도구가 원래 상태를 기록하고 비활성화합니다. `uninstall` 시 복원합니다. 확장 앱에서 Tidy만 끄면 Tiling Assistant는 중지 상태로 남습니다.
|
|
192
|
+
- 앱이 요구하는 최소 창 크기나 터미널의 크기 단위 때문에 작은 칸에 정확히 맞지 않을 수 있습니다. 전체 화면 앱과 이동·크기 변경을 허용하지 않는 창은 배치 대상에서 제외합니다.
|
|
193
|
+
- 문제를 신고할 때는 GNOME 버전, Wayland/X11 여부, 모니터 배치와 재현 순서를 [Issues](https://github.com/hojin-v/Tidy/issues)에 남겨 주세요.
|
|
194
|
+
|
|
195
|
+
개발 명령, 테스트 범위와 진단 경로는 [Development](docs/DEVELOPMENT.md), npm 게시 절차는 [Releasing](docs/RELEASING.md)에서 확인할 수 있습니다.
|
|
196
|
+
|
|
197
|
+
## License
|
|
198
|
+
|
|
199
|
+
Copyright © 2026 hojin-v. **GNU GPL v3.0 or later**로 배포합니다.
|
|
200
|
+
|
|
201
|
+
라이선스 전문은 [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();
|
|
Binary file
|
|
@@ -0,0 +1,74 @@
|
|
|
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
|
+
## Test coverage
|
|
31
|
+
|
|
32
|
+
- 화면 분할 경계, 창 사이 간격, 음수 좌표와 방향별 모니터 탐색
|
|
33
|
+
- 한국어·영어 설정 화면과 실제 가상 키보드 입력, 사용자 지정 단축키
|
|
34
|
+
- 배치 애니메이션의 실제 시작 위치·크기, 연속 배치와 모니터 간 이동
|
|
35
|
+
- 양 끝 모니터의 순환 이동, 모니터별 클리핑을 적용한 나가기·들어오기 모션과 연속 입력 정리
|
|
36
|
+
- 실제 가상 모니터를 위아래로 재배치한 상태에서 상하 단축키 이동·순환과 원래 모니터 구성 복원
|
|
37
|
+
- 좌우·상단 미리보기의 연속 표시·불투명도 유지, 선택기 옵션을 켜거나 꺼도 동일한 표시와 취소
|
|
38
|
+
- 최대화·복귀, 창·앱 보기의 드래그 배치와 화면 전환
|
|
39
|
+
- 모니터별 선택기 크기, 고해상도 배율, 타일 창의 공유 경계 조절
|
|
40
|
+
- Ubuntu Dock 설정을 따르는 선택기 슬라이드, 드래그 안내와 선택기 너비에 맞춘 감지 영역
|
|
41
|
+
- 실제 창 크기를 유지하는 축소 미리보기, 이동 추적·취소와 배치 애니메이션 연결
|
|
42
|
+
- 창·앱 보기의 드래그 즉시 축소, 포인터 고정·복귀와 작은 상태에서의 배치 전환
|
|
43
|
+
- 남은 공간의 앱 선택, 빈 곳 클릭·Esc 취소와 최소화된 창 복원
|
|
44
|
+
- 원본 소스 폴더를 삭제한 뒤 설치 도구 실행·설정 복구·제거
|
|
45
|
+
- npm tarball 전역 설치, 읽기 전용 패키지, CLI 언어·의존성 검사와 설치된 복구 도구 연결
|
|
46
|
+
- 확장 재활성화, 예약 작업 취소와 데스크톱 설정 복원
|
|
47
|
+
|
|
48
|
+
헤드리스 백엔드에서는 실제 마우스 제스처 대신 잡기 신호·포인터 좌표·Shell 드래그 콜백을 주입합니다. 실제 마우스 조작은 데스크톱에서 별도로 확인해야 합니다. GNOME 46–49와 X11은 실기 검증 전입니다.
|
|
49
|
+
|
|
50
|
+
## Diagnostics
|
|
51
|
+
|
|
52
|
+
기본 경로이며 XDG 디렉터리 설정을 따릅니다.
|
|
53
|
+
|
|
54
|
+
| 경로 | 용도 |
|
|
55
|
+
| --- | --- |
|
|
56
|
+
| `~/.local/share/gnome-shell/extensions/winubun@winubun.local/` | 확장과 설치된 관리 도구 |
|
|
57
|
+
| `~/.local/share/applications/winubun.desktop` | Tidy 실행기 |
|
|
58
|
+
| `~/.local/state/winubun/launcher.log` | 실행 오류 |
|
|
59
|
+
| `~/.local/state/winubun/preferences.log` | 설정 앱 로그 |
|
|
60
|
+
| `~/.local/state/winubun/handover.json` | 기존 타일링 확장 복원 기록 |
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
gnome-shell --version
|
|
64
|
+
gnome-extensions info winubun@winubun.local
|
|
65
|
+
journalctl --user -b --no-pager -g 'Tidy|winubun|JS ERROR'
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
GNOME은 세션 중 읽은 확장 JavaScript를 캐시합니다. 실행 코드 업데이트 시 `metadata.json`의 버전을 올리고 다시 로그인해 검증하세요. Python 설치 도구만 바뀐 경우에는 확장 코드 버전을 그대로 유지할 수 있습니다.
|
|
69
|
+
|
|
70
|
+
## References
|
|
71
|
+
|
|
72
|
+
- [GNOME extension anatomy](https://gjs.guide/extensions/overview/anatomy.html)
|
|
73
|
+
- [GNOME extension preferences](https://gjs.guide/extensions/development/preferences.html)
|
|
74
|
+
- [Mutter window API](https://gnome.pages.gitlab.gnome.org/mutter/meta/class.Window.html)
|
|
@@ -0,0 +1,201 @@
|
|
|
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 brings familiar ideas from Windows Snap Layouts and macOS Magnet to Ubuntu GNOME.
|
|
9
|
+
|
|
10
|
+

|
|
11
|
+

|
|
12
|
+

|
|
13
|
+
[](https://www.npmjs.com/package/@hnode/tidy)
|
|
14
|
+
[](../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 a cell in one of seven layouts. |
|
|
31
|
+
| Edge snapping | Other top edges maximize; left and right edges tile halves. |
|
|
32
|
+
| Overview integration | Press Super to open GNOME's overview and the picker together, then drag a window preview onto a layout. |
|
|
33
|
+
| Custom shortcuts | Use Super+Alt for halves, quarters, thirds and two-thirds; customize the bindings in settings. |
|
|
34
|
+
| Multiple monitors | Repeat an arrow shortcut to move to the monitor in that direction, including above and below. Picker size adapts to each monitor. |
|
|
35
|
+
| Linked resizing | Drag shared boundaries to resize adjacent tiled windows together. Enabled by default. |
|
|
36
|
+
| Optional snap assist | Choose running app icons inside empty regions to fill the remaining space. Disabled by default. |
|
|
37
|
+
| Size and spacing | Adjust picker sizes and window gaps, including a separate overview picker size. |
|
|
38
|
+
|
|
39
|
+
## Platform Support
|
|
40
|
+
|
|
41
|
+
| Environment | Status |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| Ubuntu 26.04 · GNOME 50.1 · Wayland | Tested with real Wayland windows and two virtual monitors in an isolated GNOME session |
|
|
44
|
+
| GNOME 46–49 | Declared compatible; not yet tested on those versions |
|
|
45
|
+
| X11 | Not yet tested |
|
|
46
|
+
| KDE · Xfce · Windows · macOS | Outside the supported platform |
|
|
47
|
+
|
|
48
|
+
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.
|
|
49
|
+
|
|
50
|
+
## Install
|
|
51
|
+
|
|
52
|
+
### npm
|
|
53
|
+
|
|
54
|
+
The package is **`@hnode/tidy`** and the command is **`tidy`**. Once published to npm, install the package and register the GNOME extension:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npm install -g @hnode/tidy
|
|
58
|
+
tidy install
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Or install without keeping a global npm package:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npx @hnode/tidy@latest install
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
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.
|
|
68
|
+
|
|
69
|
+
**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.
|
|
70
|
+
|
|
71
|
+
### Source
|
|
72
|
+
|
|
73
|
+
You can also download the repository and install directly:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
git clone https://github.com/hojin-v/Tidy.git
|
|
77
|
+
cd Tidy
|
|
78
|
+
/usr/bin/python3 scripts/manage.py install
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
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.
|
|
82
|
+
|
|
83
|
+
**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.
|
|
84
|
+
|
|
85
|
+
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.
|
|
86
|
+
|
|
87
|
+
## Quick Start
|
|
88
|
+
|
|
89
|
+
1. Grab a window by its title bar. A thin hint appears at the top of the monitor.
|
|
90
|
+
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.
|
|
91
|
+
3. Release to tile the window. Release over empty space to cancel.
|
|
92
|
+
|
|
93
|
+
Press **Super** to open the native window/app overview and the layout picker together. Drag a window preview into a cell, or click a cell to place the previously focused window. Search appears when you type.
|
|
94
|
+
|
|
95
|
+
Window previews and app icons shrink as soon as you start dragging anywhere in the overview, and return to their original size on release or cancellation. This also works with the overview picker disabled. Dropping a window into a layout continues directly from the miniature to its final placement.
|
|
96
|
+
|
|
97
|
+
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.
|
|
98
|
+
|
|
99
|
+
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.
|
|
100
|
+
|
|
101
|
+
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.
|
|
102
|
+
|
|
103
|
+
## Shortcuts
|
|
104
|
+
|
|
105
|
+
Placement shortcuts consistently use **Super+Alt**. Change them in the **Shortcuts** tab.
|
|
106
|
+
|
|
107
|
+
| Shortcut | Action |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| Super | Open / close GNOME's overview and the layout picker |
|
|
110
|
+
| Super + A | Toggle GNOME's application grid |
|
|
111
|
+
| Super + Alt + ← / → | Tile to the left / right half; repeat to move in that direction, wrapping at the outer edges |
|
|
112
|
+
| Super + Alt + ↑ / ↓ | Tile to the top / bottom half; repeat to move above / below, wrapping at the outer edges |
|
|
113
|
+
| Super + Alt + Enter | Maximize / restore the previous size and placement |
|
|
114
|
+
| Super + Alt + U / I / J / K | Top-left / top-right / bottom-left / bottom-right quarter |
|
|
115
|
+
| Super + Alt + D / F / G | Left / center / right third |
|
|
116
|
+
| Super + Alt + E / T | Left / right two-thirds |
|
|
117
|
+
| Super + Alt + C | Centered three-quarter size |
|
|
118
|
+
| Super + Alt + Space | Open the layout picker |
|
|
119
|
+
| Super + Alt + N | Move to the next monitor |
|
|
120
|
+
|
|
121
|
+
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.
|
|
122
|
+
|
|
123
|
+
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.
|
|
124
|
+
|
|
125
|
+
## Settings
|
|
126
|
+
|
|
127
|
+
Open **Tidy** from the application list, or choose **Settings and shortcuts…** from the top-panel grid icon. Changes take effect immediately.
|
|
128
|
+
|
|
129
|
+
- **Disable native Super+arrow tiling** disables GNOME's original tiling shortcuts. Turning it off or disabling Tidy restores them.
|
|
130
|
+
- **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.
|
|
131
|
+
- **Layout picker size / Overview picker size** default to equal sizes. The overview picker has its own relative size setting.
|
|
132
|
+
- **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.
|
|
133
|
+
- **Choose windows for the remaining space** shows running app icons in empty layout regions. Disabled by default.
|
|
134
|
+
|
|
135
|
+
Open settings or check status from the CLI:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
tidy prefs
|
|
139
|
+
tidy status
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
You can also use the installed management tool directly. The source folder is not needed:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
tidy_manager="${XDG_DATA_HOME:-$HOME/.local/share}/gnome-shell/extensions/winubun@winubun.local/scripts/manage.py"
|
|
146
|
+
/usr/bin/python3 "$tidy_manager" prefs
|
|
147
|
+
/usr/bin/python3 "$tidy_manager" status
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## Update
|
|
151
|
+
|
|
152
|
+
Update the npm package, then apply its extension version. `tidy update` installs the version bundled with the currently installed npm package:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
npm install -g @hnode/tidy@latest
|
|
156
|
+
tidy update
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
For npx installations, rerun `npx @hnode/tidy@latest install`. For source installations, download the latest source and rerun the installer:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
git pull --ff-only
|
|
163
|
+
/usr/bin/python3 scripts/manage.py install
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
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.
|
|
167
|
+
|
|
168
|
+
## Uninstall
|
|
169
|
+
|
|
170
|
+
Remove the extension first, then the npm CLI:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
tidy uninstall
|
|
174
|
+
npm uninstall -g @hnode/tidy
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
For npx installations, use `npx @hnode/tidy@latest uninstall`. **Removing only the npm package leaves the GNOME extension installed.**
|
|
178
|
+
|
|
179
|
+
Without the CLI, run the installed tool from any directory:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
/usr/bin/python3 "${XDG_DATA_HOME:-$HOME/.local/share}/gnome-shell/extensions/winubun@winubun.local/scripts/manage.py" uninstall
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
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.
|
|
186
|
+
|
|
187
|
+
The `winubun` path is a stable internal name retained for compatibility with existing settings and pinned launchers.
|
|
188
|
+
|
|
189
|
+
## Notes
|
|
190
|
+
|
|
191
|
+
- 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.
|
|
192
|
+
- Application minimum sizes and terminal resize increments can prevent an exact fit. Fullscreen windows and windows that disallow movement or resizing are excluded.
|
|
193
|
+
- 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.
|
|
194
|
+
|
|
195
|
+
See [Development](DEVELOPMENT.md) for development commands, test coverage and diagnostic paths, and [Releasing](RELEASING.md) for npm publication.
|
|
196
|
+
|
|
197
|
+
## License
|
|
198
|
+
|
|
199
|
+
Copyright © 2026 hojin-v. Distributed under **GNU GPL v3.0 or later**.
|
|
200
|
+
|
|
201
|
+
See [LICENSE](../LICENSE) for the full terms and [NOTICE](../NOTICE) for the project notice.
|