From 66f1174fc5a9704cd44d79fb3d748d86f0cead10 Mon Sep 17 00:00:00 2001 From: Leandro Rodrigues Date: Tue, 8 Sep 2026 17:19:49 -0300 Subject: [PATCH] feat: update Aurora Shell for GNOME 51 --- .prettierrc | 3 +- AGENTS.md | 130 ++----- CONTRIBUTING.md | 47 +-- CREDITS.md | 39 +-- Containerfile | 2 +- README.md | 51 +-- data/po/pt_BR.po | 138 ++++---- ....shell.extensions.aurora-shell.gschema.xml | 44 +-- docs/README.md | 25 +- docs/architecture.md | 94 ++--- docs/development.md | 46 +-- docs/extension-review.md | 80 ++--- docs/module-reference.md | 56 ++- docs/modules.md | 61 +--- docs/releases.md | 55 +-- docs/testing.md | 67 ++-- docs/troubleshooting.md | 63 +--- metadata.json | 2 +- src/capture/annotationCanvas.ts | 33 +- src/capture/captureToolbar.ts | 28 +- src/capture/captureToolbarPositioner.ts | 30 +- src/capture/captureTools.ts | 50 ++- src/clipboard/clipboardPanel.ts | 30 +- src/desktop/trayIcons/trayContainer.ts | 43 ++- src/desktop/trayIcons/trayIconItem.ts | 27 +- src/dev/calendarRemindersDevTool.ts | 224 ++++++++++++ src/dev/devTool.ts | 26 +- src/dev/devToolUi.ts | 3 +- src/dev/dockDevTool.ts | 2 +- src/dev/meetingClockDevTool.ts | 182 ---------- src/device/device.ts | 2 +- src/dock/externalStorageIcon.ts | 20 +- src/dock/hotArea.ts | 77 ++--- src/dock/motion/iconMotionController.ts | 12 +- src/dock/motion/pressInteraction.ts | 2 +- src/dock/trashIcon.ts | 20 +- src/moduleCatalog.ts | 4 +- .../calendarReminderController.ts | 231 +++++++++++++ .../calendarReminders.manifest.ts | 54 +++ .../calendarReminders.ts} | 159 ++++++--- .../calendarRemindersLogic.ts} | 150 ++------ .../calendarRemindersPill.ts} | 10 +- .../calendarServerBackend.ts | 8 +- .../evolutionReminderBackend.ts | 91 +++++ .../evolutionReminderParser.ts | 46 +++ .../meetingClock/meetingAlertController.ts | 269 --------------- .../meetingClock/meetingClock.manifest.ts | 62 ---- src/panel/lockKeyIndicators.ts | 2 +- src/panel/volumeMixer/volumeMixer.ts | 5 +- src/privacy/privacyPanel.ts | 15 +- src/registry.ts | 4 +- src/shared/clockPill.ts | 5 +- src/shared/httpUrlExtractor.internal.ts | 230 ------------- src/shared/ui/dashVisibility.ts | 1 + src/shared/ui/dashWindowPreviews.ts | 17 +- ...ng-clock.scss => _calendar-reminders.scss} | 8 +- src/styles/stylesheet-dark.scss | 2 +- src/styles/stylesheet-light.scss | 2 +- .../clipboard/scenarios/panelEnvironment.js | 3 +- tests/shell/dev/devTool.test.js | 20 +- tests/shell/dev/scenarios/trayAndClocks.js | 86 ++++- tests/shell/dock/dock.test.js | 64 ++++ tests/shell/moduleManager.test.js | 2 +- .../calendarReminders.test.js | 324 ++++++++++++++++++ .../clock/meetingClock/meetingClock.test.js | 124 ------- .../clock/weatherClock/weatherClock.test.js | 34 +- .../calendarRemindersLogic.test.ts | 126 +++++++ .../evolutionReminderParser.test.ts | 53 +++ .../meetingClock/meetingClockLogic.test.ts | 274 --------------- tests/unit/project/egoPolicy.test.ts | 31 ++ tests/unit/registry.test.ts | 2 +- tests/unit/shared/httpUrlExtractor.test.ts | 122 ------- 72 files changed, 2064 insertions(+), 2390 deletions(-) create mode 100644 src/dev/calendarRemindersDevTool.ts delete mode 100644 src/dev/meetingClockDevTool.ts create mode 100644 src/panel/clock/calendarReminders/calendarReminderController.ts create mode 100644 src/panel/clock/calendarReminders/calendarReminders.manifest.ts rename src/panel/clock/{meetingClock/meetingClock.ts => calendarReminders/calendarReminders.ts} (53%) rename src/panel/clock/{meetingClock/meetingClockLogic.ts => calendarReminders/calendarRemindersLogic.ts} (58%) rename src/panel/clock/{meetingClock/meetingClockPill.ts => calendarReminders/calendarRemindersPill.ts} (93%) rename src/panel/clock/{meetingClock => calendarReminders}/calendarServerBackend.ts (92%) create mode 100644 src/panel/clock/calendarReminders/evolutionReminderBackend.ts create mode 100644 src/panel/clock/calendarReminders/evolutionReminderParser.ts delete mode 100644 src/panel/clock/meetingClock/meetingAlertController.ts delete mode 100644 src/panel/clock/meetingClock/meetingClock.manifest.ts delete mode 100644 src/shared/httpUrlExtractor.internal.ts rename src/styles/{_meeting-clock.scss => _calendar-reminders.scss} (52%) create mode 100644 tests/shell/panel/clock/calendarReminders/calendarReminders.test.js delete mode 100644 tests/shell/panel/clock/meetingClock/meetingClock.test.js create mode 100644 tests/unit/panel/clock/calendarReminders/calendarRemindersLogic.test.ts create mode 100644 tests/unit/panel/clock/calendarReminders/evolutionReminderParser.test.ts delete mode 100644 tests/unit/panel/clock/meetingClock/meetingClockLogic.test.ts delete mode 100644 tests/unit/shared/httpUrlExtractor.test.ts diff --git a/.prettierrc b/.prettierrc index d25d5c4..63cdba4 100644 --- a/.prettierrc +++ b/.prettierrc @@ -3,5 +3,6 @@ "tabWidth": 2, "trailingComma": "all", "semi": true, - "printWidth": 100 + "printWidth": 100, + "proseWrap": "never" } diff --git a/AGENTS.md b/AGENTS.md index b5382f7..952b799 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,9 +6,7 @@ ## Validation After Changes -After a change to code under `src/`, always follow these rules to ensure quality while being efficient. -For documentation, workflow, metadata, translation, or other non-`src/` changes, do not run `just validate` -or `just shexli` unless the task specifically requires that validation. +After a change to code under `src/`, always follow these rules to ensure quality while being efficient. For documentation, workflow, metadata, translation, or other non-`src/` changes, do not run `just validate` or `just shexli` unless the task specifically requires that validation. 1. **Run `just validate`** — type-checks the source, lints, and checks formatting. Fix any reported errors. 2. **Run `just shexli`** — packages the extension and runs the extensions.gnome.org static analyzer on the generated ZIP. Review every finding. Some `warning` or `manual_review` findings can be false positives or accepted GNOME-review tradeoffs, but they must be called out explicitly; fix any real regression before finishing. @@ -132,16 +130,12 @@ export const manifest: ModuleManifest = { }; ``` -2. Export the `Module` implementation class from its behavior file. Keep preference metadata out of - that implementation. -3. Add the manifest to `moduleCatalog.ts` in display order and associate its class factory in - `registry.ts`. +2. Export the `Module` implementation class from its behavior file. Keep preference metadata out of that implementation. +3. Add the manifest to `moduleCatalog.ts` in display order and associate its class factory in `registry.ts`. 4. Add every declared module, option, and internal setting key to the GSettings schema. 5. Add unit and Shell integration coverage as appropriate. -`registry.test.ts` checks the catalog/factory relationship through the TypeScript AST. -`schema.test.ts` structurally validates that every catalog setting is present in the XML and -that no stale schema setting remains. +`registry.test.ts` checks the catalog/factory relationship through the TypeScript AST. `schema.test.ts` structurally validates that every catalog setting is present in the XML and that no stale schema setting remains. ### Prefs sections @@ -170,34 +164,14 @@ Per the GNOME review guidelines, clipboard-related keyboard shortcuts must not s - Constants: `UPPER_CASE` - Keep `enable()` and `disable()` symmetric. - Read settings through `this.context.settings`. Importing `Main`/`Shell`/`St` directly is fine — keep heavy algorithms in shell-free pure files so they stay unit-testable. -- Optimize refactors for human readability, not line count. Do not compress control flow, callback bodies, - object literals, or several operations onto one line merely to shorten a file. -- Visually separate guard clauses, state preparation, actor mutation, animation, scheduling, and cleanup - with blank lines. Keep local constants next to the logical block that consumes them; avoid unexplained - aliases in the middle of a stateful method. -- Do not add pass-through methods that only forward the same arguments to a stored function or object. - Expose a meaningful domain operation, return the required callable directly, or keep the call at its - natural owner. -- Do not add production getters, comments, or other API surface solely to expose private state to tests. - Keep repeated integration-test lookup and assertion logic in `tests/shell/support/`, and exercise the - runtime through an existing meaningful boundary. -- Comments must explain a non-obvious reason, constraint, or contract. Remove comments that merely - restate a symbol name, type annotation, or the operations visible in the code. -- Do not hide lifecycle invariants behind optional chaining with fallback values, such as - `owner?.value ?? default` or `owner?.operation() ?? false`. At public boundaries, guard the inactive - state explicitly and access stable fields directly during synchronous work. Reserve optional - property access for genuinely optional external data; make cleanup decisions explicit. -- Do not create a local alias for an instance field merely to shorten `this._field`, repeat the same - name, or satisfy nullable type narrowing during synchronous work. Guard the field explicitly and - use it directly when it cannot change inside the block. A snapshot of an instance field is justified - only when it transfers ownership before the field is cleared or captures the exact resource across - an `await` or asynchronous callback. A local result is also appropriate for a genuinely dynamic - lookup or computation that must remain stable; directly reading `this._field` is not such a lookup. - Name identity captures explicitly, such as `scheduledRetry` or `activeRequest`, so the reason is - visible. -- Before finishing a refactor, review every newly created or substantially edited file as prose: expand - dense one-line branches and loops, remove redundant wrappers, and make lifecycle ownership obvious - without requiring the reader to infer it from implementation details. +- Optimize refactors for human readability, not line count. Do not compress control flow, callback bodies, object literals, or several operations onto one line merely to shorten a file. +- Visually separate guard clauses, state preparation, actor mutation, animation, scheduling, and cleanup with blank lines. Keep local constants next to the logical block that consumes them; avoid unexplained aliases in the middle of a stateful method. +- Do not add pass-through methods that only forward the same arguments to a stored function or object. Expose a meaningful domain operation, return the required callable directly, or keep the call at its natural owner. +- Do not add production getters, comments, or other API surface solely to expose private state to tests. Keep repeated integration-test lookup and assertion logic in `tests/shell/support/`, and exercise the runtime through an existing meaningful boundary. +- Comments must explain a non-obvious reason, constraint, or contract. Remove comments that merely restate a symbol name, type annotation, or the operations visible in the code. +- Do not hide lifecycle invariants behind optional chaining with fallback values, such as `owner?.value ?? default` or `owner?.operation() ?? false`. At public boundaries, guard the inactive state explicitly and access stable fields directly during synchronous work. Reserve optional property access for genuinely optional external data; make cleanup decisions explicit. +- Do not create a local alias for an instance field merely to shorten `this._field`, repeat the same name, or satisfy nullable type narrowing during synchronous work. Guard the field explicitly and use it directly when it cannot change inside the block. A snapshot of an instance field is justified only when it transfers ownership before the field is cleared or captures the exact resource across an `await` or asynchronous callback. A local result is also appropriate for a genuinely dynamic lookup or computation that must remain stable; directly reading `this._field` is not such a lookup. Name identity captures explicitly, such as `scheduledRetry` or `activeRequest`, so the reason is visible. +- Before finishing a refactor, review every newly created or substantially edited file as prose: expand dense one-line branches and loops, remove redundant wrappers, and make lifecycle ownership obvious without requiring the reader to infer it from implementation details. ## Human Review Quality Bar @@ -214,62 +188,27 @@ Changes intended for the production extension must follow both: Apply these rules during implementation and review: -- Target only the Shell versions declared in `metadata.json`. Do not add speculative compatibility - branches, `typeof method === 'function'` checks, or optional calls for methods guaranteed by those - versions. For real multi-version support, follow the - [official port guide](https://gjs.guide/extensions/upgrading/gnome-shell.html). -- Do not wrap deterministic lifecycle methods such as `destroy()`, `connect()`, `disconnect()`, - `disconnectObject()`, `abort()`, `GLib.Source.remove()`, or `Gio.DBusConnection.unregister_object()` - in defensive `try`/`catch`. Catch failures only at operations whose contract can genuinely fail, - such as I/O, parsing, D-Bus calls, subprocesses, and asynchronous result propagation. -- Never invoke a callable value with direct optional-call syntax. It hides why the callback may be - absent. Call guaranteed functions directly and use an explicit boundary guard when a callable - value is legitimately optional. -- Do not add `_enabled`, `_destroyed`, or similar lifecycle flags when owned references, cancellables, - or the underlying GObject lifecycle already express the state. After destruction, the owner must - clear its reference and must not call the instance again. -- In widget `destroy()` overrides, remove GLib sources and timeouts first, disconnect signals next, - release owned children and references after that, and call `super.destroy()` last. A widget must - override its own `destroy()` method instead of connecting its own `destroy` signal for cleanup; - observing the destruction of an external actor is valid when the observer owns that connection. -- Every signal, GLib source, cancellable, child actor, menu, Soup session, and other resource created - by a component must be cleaned up by that same component. Never spread initialization and cleanup - ownership across unrelated classes. -- When a repeatable operation creates a timeout, remove or replace its prior source immediately next - to the new source creation. Do not separate replacement and creation into distant methods or blocks. -- Keep `extension.ts` minimal. Keep `enable()` and `disable()` adjacent, symmetric, and limited to - lifecycle orchestration; avoid aliases that merely forward lifecycle calls. Never ship empty, - placeholder, or partially implemented lifecycle methods. -- Split large features into cohesive, single-responsibility modules. Extract repeated logic into - helpers instead of copying blocks. Modules imported by both Shell and preferences must remain free - of `St`, `Clutter`, `Gtk`, `Gdk`, and `Adw`; keep process-specific UI under clearly named runtime or - `preferences/` directories. -- Keep the extension's schema ID in `metadata.json` as `settings-schema` and call `this.getSettings()` - without repeating the schema ID in source code. -- Use `St.Icon` or `icon_name` for Shell UI and `Gtk.Image` for preferences. Do not use Unicode emoji - as icons or ASCII strings as progress indicators; use Shell widgets such as `BarLevel` or `St.Bin`. -- Keep generated JavaScript lines at 200 characters or fewer. Prefer self-explanatory names and remove - comments that restate syntax or translate the following statement into prose. -- Avoid subprocesses in the Shell process. Prefer D-Bus for system services and move heavy work to a - separate application. If a subprocess is unavoidable, document why D-Bus is not practical and keep - invocation local, explicit, cancellable, and free of shell interpretation. -- Review every Shexli finding. Fix real ownership/lifecycle defects and record accepted manual-review - findings or analyzer false positives in `docs/extension-review.md`. - -- Never invoke `disconnectObject` defensively on objects that do not own that signal connection - contract. +- Target only the Shell versions declared in `metadata.json`. Do not add speculative compatibility branches, `typeof method === 'function'` checks, or optional calls for methods guaranteed by those versions. For real multi-version support, follow the [official port guide](https://gjs.guide/extensions/upgrading/gnome-shell.html). +- Do not wrap deterministic lifecycle methods such as `destroy()`, `connect()`, `disconnect()`, `disconnectObject()`, `abort()`, `GLib.Source.remove()`, or `Gio.DBusConnection.unregister_object()` in defensive `try`/`catch`. Catch failures only at operations whose contract can genuinely fail, such as I/O, parsing, D-Bus calls, subprocesses, and asynchronous result propagation. +- Never invoke a callable value with direct optional-call syntax. It hides why the callback may be absent. Call guaranteed functions directly and use an explicit boundary guard when a callable value is legitimately optional. +- Do not add `_enabled`, `_destroyed`, or similar lifecycle flags when owned references, cancellables, or the underlying GObject lifecycle already express the state. After destruction, the owner must clear its reference and must not call the instance again. +- In widget `destroy()` overrides, remove GLib sources and timeouts first, disconnect signals next, release owned children and references after that, and call `super.destroy()` last. A widget must override its own `destroy()` method instead of connecting its own `destroy` signal for cleanup; observing the destruction of an external actor is valid when the observer owns that connection. +- Every signal, GLib source, cancellable, child actor, menu, Soup session, and other resource created by a component must be cleaned up by that same component. Never spread initialization and cleanup ownership across unrelated classes. +- When a repeatable operation creates a timeout, remove or replace its prior source immediately next to the new source creation. Do not separate replacement and creation into distant methods or blocks. +- Keep `extension.ts` minimal. Keep `enable()` and `disable()` adjacent, symmetric, and limited to lifecycle orchestration; avoid aliases that merely forward lifecycle calls. Never ship empty, placeholder, or partially implemented lifecycle methods. +- Split large features into cohesive, single-responsibility modules. Extract repeated logic into helpers instead of copying blocks. Modules imported by both Shell and preferences must remain free of `St`, `Clutter`, `Gtk`, `Gdk`, and `Adw`; keep process-specific UI under clearly named runtime or `preferences/` directories. +- Keep the extension's schema ID in `metadata.json` as `settings-schema` and call `this.getSettings()` without repeating the schema ID in source code. +- Use `St.Icon` or `icon_name` for Shell UI and `Gtk.Image` for preferences. Do not use Unicode emoji as icons or ASCII strings as progress indicators; use Shell widgets such as `BarLevel` or `St.Bin`. +- Keep generated JavaScript lines at 200 characters or fewer. Prefer self-explanatory names and remove comments that restate syntax or translate the following statement into prose. +- Avoid subprocesses in the Shell process. Prefer D-Bus for system services and move heavy work to a separate application. If a subprocess is unavoidable, document why D-Bus is not practical and keep invocation local, explicit, cancellable, and free of shell interpretation. +- Review every Shexli finding. Fix real ownership/lifecycle defects and record accepted manual-review findings or analyzer false positives in `docs/extension-review.md`. + +- Never invoke `disconnectObject` defensively on objects that do not own that signal connection contract. - Do not ship fake behavior. If a UI label, schema description, README entry, or module subtitle says a feature is wired to NetworkManager, ModemManager, UPower, sensors, widgets, or GNOME internals, the code must actually call the relevant API or clearly describe itself as a fallback. - Keep runtime capability checks honest. Hardware-specific modules must detect missing services/devices at runtime and stay inactive or degrade explicitly. -- Capture the return of `GObject.registerClass` and derive its instance type with - `InstanceType` when a registered class accepts custom constructor arguments. - Do not add decorators or generic construction/casting helpers around GObject classes. -- Do not scatter `as unknown as ...` casts through feature modules. Represent real GIR or GNOME Shell - declaration gaps with narrow module augmentations under `src/types/`; when TypeScript cannot augment a - static constructor, isolate that constructor signature at its single call site. -- Avoid the nullish coalescing operators `??` and `??=`. Prefer explicit guards, default parameters, - destructuring defaults, or clearly named state preparation so reviewers can see why a value may be - absent and when a fallback applies. Preserve the absence value returned by the source API unless a - boundary contract explicitly requires normalization. +- Capture the return of `GObject.registerClass` and derive its instance type with `InstanceType` when a registered class accepts custom constructor arguments. Do not add decorators or generic construction/casting helpers around GObject classes. +- Do not scatter `as unknown as ...` casts through feature modules. Represent real GIR or GNOME Shell declaration gaps with narrow module augmentations under `src/types/`; when TypeScript cannot augment a static constructor, isolate that constructor signature at its single call site. +- Avoid the nullish coalescing operators `??` and `??=`. Prefer explicit guards, default parameters, destructuring defaults, or clearly named state preparation so reviewers can see why a value may be absent and when a fallback applies. Preserve the absence value returned by the source API unless a boundary contract explicitly requires normalization. - Do not leave placeholder helpers, legacy duplicates, or unused compatibility functions after a refactor. Remove dead code instead of keeping it “just in case”. - Keep strings and metadata truthful and synchronized across `*.manifest.ts`, `moduleCatalog.ts`, schema XML, README/architecture docs, and `.po` files when strings change. - Search for obvious generated-code artifacts before finishing: broken joined words in docs, stale project names, obsolete env vars, and UI descriptions that exceed what is implemented. @@ -277,11 +216,8 @@ Apply these rules during implementation and review: ### Clean code and AI slop -- Avoid generic helpers and speculative abstractions. Names must express domain behavior: `handleMonitorsChanged` - is fine because it names the event, `handleEvent` or `processData` are not. Preserve established terms such as - `ModuleManager` when they describe real ownership. -- Keep important lifecycle behavior visible at concrete entrypoints. Do not leave an entrypoint empty - merely to hide its primary `enable()`/`disable()` orchestration behind inheritance. +- Avoid generic helpers and speculative abstractions. Names must express domain behavior: `handleMonitorsChanged` is fine because it names the event, `handleEvent` or `processData` are not. Preserve established terms such as `ModuleManager` when they describe real ownership. +- Keep important lifecycle behavior visible at concrete entrypoints. Do not leave an entrypoint empty merely to hide its primary `enable()`/`disable()` orchestration behind inheritance. ## Logging Style diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c06b209..e32d31a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,10 @@ # Contributing to Aurora Shell -Understand every change you submit. Keep pull requests focused and include results reviewers can -reproduce. +Understand every change you submit. Keep pull requests focused and include results reviewers can reproduce. ## Start with an issue and branch -Search existing issues and pull requests before opening a duplicate. For a behavior change, describe -the current result, expected result, GNOME Shell version, and reproduction steps. Small documentation -or obvious fixes may go directly to a pull request; discuss broad UI, architecture, settings, or -compatibility changes before implementation. +Search existing issues and pull requests before opening a duplicate. For a behavior change, describe the current result, expected result, GNOME Shell version, and reproduction steps. Small documentation or obvious fixes may go directly to a pull request; discuss broad UI, architecture, settings, or compatibility changes before implementation. Branch from current `main`: @@ -18,18 +14,13 @@ git pull --ff-only git switch -c fix/short-description ``` -Keep one feature, fix, or refactor per pull request. Bug fixes target `main`; released branches -receive separate backport pull requests through the process in -[Releases and backports](docs/releases.md#backports). +Keep one feature, fix, or refactor per pull request. Bug fixes target `main`; released branches receive separate backport pull requests through the process in [Releases and backports](docs/releases.md#backports). ## Make the change -Read [Architecture](docs/architecture.md) before changing lifecycle, metadata, preferences, device -policy, or package boundaries. Use the [module guide](docs/modules.md) for module work. +Read [Architecture](docs/architecture.md) before changing lifecycle, metadata, preferences, device policy, or package boundaries. Use the [module guide](docs/modules.md) for module work. -Add a regression check that fails without a non-trivial fix. Prefer a Node unit test for pure logic -and a targeted Shell test for GNOME behavior. Do not add speculative abstractions, dependencies, or -tests unrelated to the changed contract. +Add a regression check that fails without a non-trivial fix. Prefer a Node unit test for pure logic and a targeted Shell test for GNOME behavior. Do not add speculative abstractions, dependencies, or tests unrelated to the changed contract. ## Choose validation @@ -40,14 +31,9 @@ just validate just test unit ``` -Add `just package check` for build/package changes, a targeted `just test shell …` for Shell behavior, -and `just shexli` for EGO-facing, clipboard, subprocess, or package-content changes. Use Toolbox when -the host lacks the project GNOME environment or the change crosses Shell infrastructure. +Add `just package check` for build/package changes, a targeted `just test shell …` for Shell behavior, and `just shexli` for EGO-facing, clipboard, subprocess, or package-content changes. Use Toolbox when the host lacks the project GNOME environment or the change crosses Shell infrastructure. -Record commands and results in the pull request. For user-visible behavior, include a focused -screenshot or screen recording when it proves the result better than logs. For a bug, include the -before/after reproduction. Do not claim a check you did not run; state environment blockers and the -exact error. +Record commands and results in the pull request. For user-visible behavior, include a focused screenshot or screen recording when it proves the result better than logs. For a bug, include the before/after reproduction. Do not claim a check you did not run; state environment blockers and the exact error. ## Commits @@ -57,9 +43,7 @@ Use [Conventional Commits](https://www.conventionalcommits.org/) for the subject [optional scope][!]: ``` -Use a standard type such as `feat`, `fix`, `docs`, `refactor`, `test`, `build`, `ci`, or `chore`. -Keep the whole subject under 72 characters, omit the trailing period, and keep each commit reviewable -and revertible. Explain motivation and non-obvious tradeoffs in the body, not a summary of the diff. +Use a standard type such as `feat`, `fix`, `docs`, `refactor`, `test`, `build`, `ci`, or `chore`. Keep the whole subject under 72 characters, omit the trailing period, and keep each commit reviewable and revertible. Explain motivation and non-obvious tradeoffs in the body, not a summary of the diff. ```text fix(clipboard): preserve card focus behavior @@ -68,8 +52,7 @@ Reveal card actions when hover leaves a pinned item and keep short cards at a stable height. Add Shell coverage for both cases. ``` -Mark an incompatible contract with `!` and a `BREAKING CHANGE:` footer. Do not rewrite public release -tags or hide a breaking settings change in a normal fix. +Mark an incompatible contract with `!` and a `BREAKING CHANGE:` footer. Do not rewrite public release tags or hide a breaking settings change in a normal fix. ## Pull requests @@ -80,19 +63,13 @@ A pull request should answer four questions: 3. What compatibility, teardown, privacy, or regression risk remains? 4. Which commands and manual artifacts demonstrate the result? -Keep the branch current, respond to review with code or evidence, and wait for the CI gate. Reviewers -may ask for a smaller change when unrelated work obscures the behavior under review. +Keep the branch current, respond to review with code or evidence, and wait for the CI gate. Reviewers may ask for a smaller change when unrelated work obscures the behavior under review. ## AI-assisted contributions -AI tools may assist, but the human contributor owns every line and claim. Review generated changes -against the local GNOME Shell version and the -[GNOME Extensions review guidelines](https://gjs.guide/extensions/review-guidelines/review-guidelines.html). -Remove imaginary APIs, redundant code, prompt-like comments, and claims without test evidence. +AI tools may assist, but the human contributor owns every line and claim. Review generated changes against the local GNOME Shell version and the [GNOME Extensions review guidelines](https://gjs.guide/extensions/review-guidelines/review-guidelines.html). Remove imaginary APIs, redundant code, prompt-like comments, and claims without test evidence. -You must be able to explain the control flow, resource ownership, failure behavior, and test choice. -Disclose material AI assistance when project or employer policy requires it. Never upload secrets, -private user data, or code you are not authorized to share to an external service. +You must be able to explain the control flow, resource ownership, failure behavior, and test choice. Disclose material AI assistance when project or employer policy requires it. Never upload secrets, private user data, or code you are not authorized to share to an external service. ## Documentation map diff --git a/CREDITS.md b/CREDITS.md index 8cbfe13..c3561b2 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -4,9 +4,7 @@ Aurora Shell stands on the work of the wider GNOME community. This file records ## Bluetooth-Battery-Meter -The animated Bluetooth icons used by the **Bluetooth Menu** module come from -[**maniacx/Bluetooth-Battery-Meter**](https://github.com/maniacx/Bluetooth-Battery-Meter). -Huge thanks to [@maniacx](https://github.com/maniacx) for the great work. +The animated Bluetooth icons used by the **Bluetooth Menu** module come from [**maniacx/Bluetooth-Battery-Meter**](https://github.com/maniacx/Bluetooth-Battery-Meter). Huge thanks to [@maniacx](https://github.com/maniacx) for the great work. Icons (`data/icons/hicolor/scalable/actions/`): @@ -17,43 +15,26 @@ Icons (`data/icons/hicolor/scalable/actions/`): - `bbm-bluetooth-disconnecting-animated-symbolic.svg` - `bbm-bluetooth-disconnecting-1-symbolic.svg` … `bbm-bluetooth-disconnecting-4-symbolic.svg` -These icons remain the work of their original author and are used under the terms of the -Bluetooth-Battery-Meter project's license. +These icons remain the work of their original author and are used under the terms of the Bluetooth-Battery-Meter project's license. ## XWayland Indicator -The **XWayland Indicator** module is inspired by -[**swsnr/gnome-shell-extension-xwayland-indicator**](https://codeberg.org/swsnr/gnome-shell-extension-xwayland-indicator/). -Thanks to [@swsnr](https://codeberg.org/swsnr) for the original idea of surfacing which -windows run under XWayland. +The **XWayland Indicator** module is inspired by [**swsnr/gnome-shell-extension-xwayland-indicator**](https://codeberg.org/swsnr/gnome-shell-extension-xwayland-indicator/). Thanks to [@swsnr](https://codeberg.org/swsnr) for the original idea of surfacing which windows run under XWayland. ## Weather Clock -The **Weather Clock** module is inspired by -[**CleoMenezesJr/weather-oclock**](https://github.com/CleoMenezesJr/weather-oclock). -Thanks to [@CleoMenezesJr](https://github.com/CleoMenezesJr) for the GNOME Weather clock -integration pattern. +The **Weather Clock** module is inspired by [**CleoMenezesJr/weather-oclock**](https://github.com/CleoMenezesJr/weather-oclock). Thanks to [@CleoMenezesJr](https://github.com/CleoMenezesJr) for the GNOME Weather clock integration pattern. -## Meeting Clock +## Calendar Reminders -The **Meeting Clock** module is inspired by -[**danmoz/meetingtime**](https://github.com/danmoz/meetingtime). -Thanks to [@danmoz](https://github.com/danmoz) for the meeting reminder behavior and -calendar-driven workflow. +The **Calendar Reminders** module is inspired by [**danmoz/meetingtime**](https://github.com/danmoz/meetingtime). Thanks to [@danmoz](https://github.com/danmoz) for the meeting reminder behavior and calendar-driven workflow. + +Native Evolution reminders use the `reminders-past` approach demonstrated by [**donnybeelo/gnome-extensions-calendar-reminders**](https://github.com/donnybeelo/gnome-extensions-calendar-reminders). Thanks to [@donnybeelo](https://github.com/donnybeelo) for documenting that flow. ## Capture Tools -The annotation workflow in **Capture Tools** is inspired by -[**AlexanderVanhee/gradia-capture**](https://github.com/AlexanderVanhee/gradia-capture), and its -local screenshot OCR workflow is inspired by -[**SamkitJain660/Shotzy**](https://github.com/SamkitJain660/Shotzy). The custom symbolic SVGs under -`data/icons/hicolor/scalable/actions/` are copied from Gradia Capture and redistributed under -GPL-3.0. The toolbar integration, annotation canvas, export, and OCR implementation are otherwise -independent. +The annotation workflow in **Capture Tools** is inspired by [**AlexanderVanhee/gradia-capture**](https://github.com/AlexanderVanhee/gradia-capture), and its local screenshot OCR workflow is inspired by [**SamkitJain660/Shotzy**](https://github.com/SamkitJain660/Shotzy). The custom symbolic SVGs under `data/icons/hicolor/scalable/actions/` are copied from Gradia Capture and redistributed under GPL-3.0. The toolbar integration, annotation canvas, export, and OCR implementation are otherwise independent. ## Dock Motion -The Dock motion recipes and controller behavior are adapted from -[**Orsso/d2d-companion**](https://github.com/Orsso/d2d-companion), version `v0.1.0-beta.1` -(commit `33eef1d2ddc4678c46d015a4a2c276d4177901df`). The adapted source is redistributed -under GPL-2.0-or-later and is combined with Aurora Shell under GPL-3.0-only. +The Dock motion recipes and controller behavior are adapted from [**Orsso/d2d-companion**](https://github.com/Orsso/d2d-companion), version `v0.1.0-beta.1` (commit `33eef1d2ddc4678c46d015a4a2c276d4177901df`). The adapted source is redistributed under GPL-2.0-or-later and is combined with Aurora Shell under GPL-3.0-only. diff --git a/Containerfile b/Containerfile index a666d4f..f6d3c39 100644 --- a/Containerfile +++ b/Containerfile @@ -1,4 +1,4 @@ -ARG FEDORA_VERSION=44 +ARG FEDORA_VERSION=45 FROM registry.fedoraproject.org/fedora-toolbox:${FEDORA_VERSION} diff --git a/README.md b/README.md index 1091fa0..f168876 100644 --- a/README.md +++ b/README.md @@ -4,40 +4,30 @@ # Aurora Shell -Aurora Shell is a GNOME Shell 50 extension with 22 optional desktop features in one preferences -window. It runs inside GNOME Shell and supports no other desktop environment. +Aurora Shell brings optional desktop features to GNOME Shell, from dock and panel controls to appearance, window behavior, and clipboard tools. Choose which modules to enable and configure them in one preferences window. -Supported Shell versions are listed in `metadata.json`. Shell internals change between GNOME -releases, so do not force-install Aurora Shell on an unlisted version. Some modules also depend on -services that may be absent: GNOME Weather for Weather Clock, Tesseract for Capture Tools OCR, and -Vela for Vela VPN Quick Settings. +Supported GNOME Shell versions are listed in [metadata.json](metadata.json). Shell internals change between GNOME releases, so do not force-install Aurora Shell on an unlisted version. Some modules also depend on services that may be absent: GNOME Weather for Weather Clock, Tesseract for Capture Tools OCR, and Vela for Vela VPN Quick Settings. Aurora Shell is licensed under GPL-3.0-only. See [LICENSE](LICENSE) and [CREDITS.md](CREDITS.md). ## Install -The recommended build is published on -[extensions.gnome.org](https://extensions.gnome.org/extension/9389/aurora-shell/). +The recommended build is published on [extensions.gnome.org](https://extensions.gnome.org/extension/9389/aurora-shell/). -To install a release asset manually, download -`aurora-shell@luminusos.github.io.shell-extension.zip` from the -[GitHub releases page](https://github.com/luminusOS/aurora-shell/releases), then run: +To install a release asset manually, download `aurora-shell@luminusos.github.io.shell-extension.zip` from the [GitHub releases page](https://github.com/luminusOS/aurora-shell/releases), then run: ```bash gnome-extensions install --force aurora-shell@luminusos.github.io.shell-extension.zip gnome-extensions enable aurora-shell@luminusos.github.io ``` -Log out and back in if the extension is not available in the current Shell session. Open the -Extensions app or run `gnome-extensions prefs aurora-shell@luminusos.github.io` to configure modules. +Log out and back in if the extension is not available in the current Shell session. Open the Extensions app or run `gnome-extensions prefs aurora-shell@luminusos.github.io` to configure modules. -Release assets also include a `.development.shell-extension.zip` package with contributor tools for -development and QA sessions. +Release assets also include a `.development.shell-extension.zip` package with contributor tools for development and QA sessions. ## Update or remove -Install a newer ZIP with the same `--force` command. Existing GSettings values remain in the -extension schema unless you reset them explicitly. +Install a newer ZIP with the same `--force` command. Existing GSettings values remain in the extension schema unless you reset them explicitly. Disable or remove Aurora Shell with: @@ -50,28 +40,20 @@ See [Troubleshooting](docs/troubleshooting.md) when installation, loading, or a ## Modules -All modules can be toggled independently. Most are enabled by default; Auto Theme Switcher and Vela -VPN Quick Settings are opt-in. +All modules can be toggled independently. Most are enabled by default; Auto Theme Switcher and Vela VPN Quick Settings are opt-in. -- **Dock and panel:** Dock, Aurora Menu, Power Menu Avatar, Volume Mixer, Low Battery Percentage, - Lock Key Indicators, Bluetooth Menu, Weather Clock, Meeting Clock, and Tray Icons. +- **Dock and panel:** Dock, Aurora Menu, Power Menu Avatar, Volume Mixer, Low Battery Percentage, Lock Key Indicators, Bluetooth Menu, Weather Clock, Calendar Reminders, and Tray Icons. - **Appearance:** Theme Changer, Icon Weave, App Search Tooltip, and Auto Theme Switcher. -- **Behavior:** Skip Overview on Login, Pip On Top, Focus Launched Windows, Capture Tools, XWayland - Indicator, and Vela VPN Quick Settings. +- **Behavior:** Skip Overview on Login, Pip On Top, Focus Launched Windows, Capture Tools, XWayland Indicator, and Vela VPN Quick Settings. - **Privacy and clipboard:** Privacy and Clipboard History. -Low Battery Percentage temporarily enables GNOME's native percentage display while a battery is -discharging below 30%. It does not override a percentage display that the user enabled. Vela VPN -Quick Settings routes the Shell VPN toggle through Vela's D-Bus API; its optional GNOME Shell -fallback is also disabled by default. +Low Battery Percentage temporarily enables GNOME's native percentage display while a battery is discharging below 30%. It does not override a percentage display that the user enabled. Vela VPN Quick Settings routes the Shell VPN toggle through Vela's D-Bus API; its optional GNOME Shell fallback is also disabled by default. -The [module reference](docs/module-reference.md) records every module key, default, dependency, -runtime policy, and implementation/test location. +The [module reference](docs/module-reference.md) records every module key, default, dependency, runtime policy, and implementation/test location. ## Develop -Development requires Node.js 20 or newer, Yarn 4, `just`, and the GNOME 50 development/runtime tools -used by the selected test path. +Follow the [development guide](docs/development.md) to set up the required tools and choose a test environment. The Yarn version is pinned in [package.json](package.json), and [Containerfile](Containerfile) defines the GNOME development environment used by CI and Toolbox. Project commands use `just`. ```bash just deps @@ -80,11 +62,8 @@ just test unit just package check ``` -Start with the [documentation index](docs/README.md). It links to architecture, the edit-run-debug -loop, module authoring, test selection, troubleshooting, and releases. Contributions follow -[CONTRIBUTING.md](CONTRIBUTING.md). +Start with the [documentation index](docs/README.md). It links to architecture, the edit-run-debug loop, module authoring, test selection, troubleshooting, and releases. Contributions follow [CONTRIBUTING.md](CONTRIBUTING.md). ## Credits -Aurora Shell incorporates or adapts work from the GNOME extension community. The complete source, -license, and inspiration record is in [CREDITS.md](CREDITS.md). +Aurora Shell incorporates or adapts work from the GNOME extension community. The complete source, license, and inspiration record is in [CREDITS.md](CREDITS.md). diff --git a/data/po/pt_BR.po b/data/po/pt_BR.po index 109eb05..bc28fee 100644 --- a/data/po/pt_BR.po +++ b/data/po/pt_BR.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: aurora-shell\n" "Report-Msgid-Bugs-To: https://github.com/luminusOS/aurora-shell/issues\n" -"POT-Creation-Date: 2026-08-30 09:40-0300\n" +"POT-Creation-Date: 2026-09-06 17:06-0300\n" "PO-Revision-Date: 2026-07-16 09:20-0300\n" "Last-Translator: Aurora Shell Contributors\n" "Language-Team: Portuguese (Brazil)\n" @@ -101,23 +101,23 @@ msgstr "Marcador numerado" msgid "Move toolbar" msgstr "Mover barra de ferramentas" -#: dist/capture/captureToolbar.js:63 +#: dist/capture/captureToolbar.js:78 msgid "Annotation color" msgstr "Cor da anotação" -#: dist/capture/captureToolbar.js:81 +#: dist/capture/captureToolbar.js:96 msgid "Annotation width" msgstr "Espessura da anotação" -#: dist/capture/captureToolbar.js:90 +#: dist/capture/captureToolbar.js:105 msgid "Undo" msgstr "Desfazer" -#: dist/capture/captureToolbar.js:93 +#: dist/capture/captureToolbar.js:108 msgid "Clear annotations" msgstr "Limpar anotações" -#: dist/capture/captureTools.js:225 +#: dist/capture/captureTools.js:223 msgid "Type annotation text" msgstr "Digite o texto da anotação" @@ -263,7 +263,7 @@ msgid "Search…" msgstr "Pesquisar…" #: dist/desktop/trayIcons/backgroundAppsSource.js:112 -#: dist/dock/externalStorageIcon.js:97 dist/dock/trashIcon.js:108 +#: dist/dock/externalStorageIcon.js:91 dist/dock/trashIcon.js:102 msgid "Open" msgstr "Abrir" @@ -469,15 +469,15 @@ msgstr "Equilibrado" msgid "Expressive" msgstr "Expressivo" -#: dist/dock/externalStorageIcon.js:97 +#: dist/dock/externalStorageIcon.js:91 msgid "Mount and Open" msgstr "Montar e abrir" -#: dist/dock/externalStorageIcon.js:101 +#: dist/dock/externalStorageIcon.js:95 msgid "Eject" msgstr "Ejetar" -#: dist/dock/externalStorageIcon.js:101 +#: dist/dock/externalStorageIcon.js:95 msgid "Unmount" msgstr "Desmontar" @@ -495,7 +495,7 @@ msgstr "Falha ao ejetar “%s”" msgid "Trash" msgstr "Lixeira" -#: dist/dock/trashIcon.js:111 +#: dist/dock/trashIcon.js:105 msgid "Empty Trash" msgstr "Esvaziar lixeira" @@ -675,97 +675,83 @@ msgstr "" "Mostra o nível da bateria e ícones animados no painel de Configurações " "Rápidas do Bluetooth" -#: dist/panel/clock/meetingClock/meetingAlertController.js:118 -msgid "Meeting starting soon" -msgstr "Reunião começará em breve" +#: dist/panel/clock/calendarReminders/calendarReminderController.js:76 +msgid "Calendar reminder" +msgstr "Lembrete do calendário" -#: dist/panel/clock/meetingClock/meetingAlertController.js:127 -msgid "Join" -msgstr "Participar" +#: dist/panel/clock/calendarReminders/calendarReminderController.js:77 +msgid "Calendar event" +msgstr "Evento do calendário" -#: dist/panel/clock/meetingClock/meetingAlertController.js:129 +#: dist/panel/clock/calendarReminders/calendarReminderController.js:86 +msgid "Open Calendar" +msgstr "Abrir Calendário" + +#: dist/panel/clock/calendarReminders/calendarReminderController.js:89 msgid "Snooze" msgstr "Adiar" -#: dist/panel/clock/meetingClock/meetingAlertController.js:130 -msgid "Dismiss" -msgstr "Dispensar" - -#: dist/panel/clock/meetingClock/meetingAlertController.js:132 -msgid "Ignore" -msgstr "Ignorar" +#: dist/panel/clock/calendarReminders/calendarReminderController.js:171 +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:8 +msgid "Calendar Reminders" +msgstr "Lembretes do calendário" -#: dist/panel/clock/meetingClock/meetingAlertController.js:189 -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:8 -msgid "Meeting Clock" -msgstr "Relógio de reuniões" +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:9 +msgid "Shows upcoming events next to the clock and notifies calendar reminders" +msgstr "Mostra os próximos eventos ao lado do relógio e notifica os lembretes do calendário" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:9 -msgid "Shows upcoming calendar events next to the clock" -msgstr "Mostra os próximos eventos do calendário ao lado do relógio" +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:13 +msgid "Notifications" +msgstr "Notificações" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:13 -msgid "Meeting Alerts" -msgstr "Alertas de reunião" +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:14 +msgid "Show calendar reminders as notifications" +msgstr "Mostrar lembretes do calendário como notificações" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:14 -msgid "Show a notification when a meeting is about to start" -msgstr "Mostra uma notificação quando uma reunião está prestes a começar" +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:19 +msgid "Force Reminder at Event Start" +msgstr "Forçar lembrete no início do evento" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:19 -msgid "Alert Lead Time (minutes)" -msgstr "Antecedência do alerta (minutos)" +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:20 +msgid "Always notify when a timed event starts, even after an earlier reminder" +msgstr "Sempre notificar quando um evento com horário começar, mesmo após um lembrete anterior" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:20 -msgid "Minutes before a meeting starts to show the alert" -msgstr "Minutos antes do início da reunião para mostrar o alerta" - -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:27 +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:25 msgid "Snooze Duration (minutes)" msgstr "Duração do adiamento (minutos)" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:28 +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:26 msgid "Minutes to wait before showing a snoozed alert again" msgstr "Minutos de espera antes de mostrar novamente um alerta adiado" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:35 -msgid "Alert Events Without Links" -msgstr "Alertar eventos sem links" - -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:36 -msgid "Show meeting alerts for calendar events that do not include a join link" -msgstr "" -"Mostra alertas de reunião para eventos do calendário que não incluem um link " -"para participar" - -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:41 +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:33 msgid "Panel Reveal Interval (minutes)" msgstr "Intervalo de revelação do painel (minutos)" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:42 -msgid "Minutes between automatic Meeting Clock slide reveals in the panel" +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:34 +msgid "Minutes between automatic Calendar Reminders slide reveals in the panel" msgstr "" -"Minutos entre as revelações automáticas deslizantes do Relógio de reuniões " -"no painel" +"Minutos entre as revelações automáticas deslizantes dos Lembretes do " +"calendário no painel" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:49 +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:41 msgid "Panel Lookahead (minutes)" msgstr "Antecedência do painel (minutos)" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:50 +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:42 msgid "" "Maximum minutes before an event starts for it to appear in the panel clock" msgstr "" "Máximo de minutos antes do início de um evento para ele aparecer no relógio " "do painel" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:57 +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:49 msgid "Hide All-Day Events" msgstr "Ocultar eventos de dia inteiro" -#: dist/panel/clock/meetingClock/meetingClock.manifest.js:58 -msgid "Exclude all-day events from the clock and alerts" -msgstr "Exclui eventos de dia inteiro do relógio e dos alertas" +#: dist/panel/clock/calendarReminders/calendarReminders.manifest.js:50 +msgid "Exclude all-day events from the panel clock" +msgstr "Excluir eventos de dia inteiro do relógio do painel" #: dist/panel/clock/weatherClock/weatherClock.manifest.js:8 msgid "Weather Clock" @@ -824,17 +810,17 @@ msgstr "Nenhum áudio em reprodução" msgid "Volume changed" msgstr "Volume alterado" -#: dist/panel/volumeMixer/volumeMixer.js:77 +#: dist/panel/volumeMixer/volumeMixer.js:76 msgid "Sound Settings" msgstr "Configurações de som" -#: dist/panel/volumeMixer/volumeMixer.js:95 -#: dist/panel/volumeMixer/volumeMixer.js:117 +#: dist/panel/volumeMixer/volumeMixer.js:94 +#: dist/panel/volumeMixer/volumeMixer.js:116 #: dist/panel/volumeMixer/volumeMixer.manifest.js:8 msgid "Volume Mixer" msgstr "Mixer de Volume" -#: dist/panel/volumeMixer/volumeMixer.js:127 +#: dist/panel/volumeMixer/volumeMixer.js:126 msgid "Sound Output" msgstr "Saída de som" @@ -1075,7 +1061,7 @@ msgstr "" "Oculta o conteúdo do painel durante o compartilhamento de tela; mostra " "apenas o indicador de compartilhamento" -#: dist/shared/ui/dashWindowPreviews.js:307 +#: dist/shared/ui/dashWindowPreviews.js:308 msgid "Close" msgstr "Fechar" @@ -1112,6 +1098,12 @@ msgstr "Alternador de Tema" msgid "Monitors and synchronizes GNOME color scheme" msgstr "Monitora e sincroniza o esquema de cores do GNOME" +#~ msgid "Dismiss" +#~ msgstr "Dispensar" + +#~ msgid "Ignore" +#~ msgstr "Ignorar" + #~ msgid "Restore" #~ msgstr "Restaurar" diff --git a/data/schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml b/data/schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml index f2d16e5..5baa6b7 100644 --- a/data/schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml +++ b/data/schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml @@ -302,9 +302,9 @@ Enable Lock Key Indicators module Shows Caps Lock and Num Lock indicators in the top panel - + true - Enable Meeting Clock module + Enable Calendar Reminders module Shows upcoming calendar events next to the clock @@ -317,44 +317,38 @@ Show Weather Clock after the clock Place the weather indicator after the clock instead of before it - + true - Enable Meeting Clock alerts - Show a notification when a meeting is about to start + Enable calendar reminders + Show calendar reminders as notifications - - - 1 - Meeting Clock alert lead time - Minutes before a meeting starts to show the alert + + false + Force reminder at event start + Always notify when a timed event starts, even without a configured alarm or after an earlier reminder - + 5 - Meeting Clock snooze duration + Calendar Reminders snooze duration Minutes to wait before showing a snoozed alert again - - false - Alert events without meeting links - Show Meeting Clock alerts for calendar events that do not include a join link - - + 5 - Meeting Clock panel reveal interval - Minutes between automatic Meeting Clock slide reveals in the panel + Calendar Reminders panel reveal interval + Minutes between automatic Calendar Reminders slide reveals in the panel - + 60 - Meeting Clock panel lookahead + Calendar Reminders panel lookahead Maximum minutes before an event starts for it to appear in the panel clock - + true - Hide all-day events in Meeting Clock - Exclude all-day events from the clock and alerts + Hide all-day events in Calendar Reminders + Exclude all-day events from the panel clock true diff --git a/docs/README.md b/docs/README.md index 8eb9c01..29b9d87 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,17 +2,16 @@ Choose the page that matches the job you need to do. -| Goal | Start here | -| --------------------------------------------------------------------- | ---------------------------------------------------- | -| Understand the runtime and ownership model | [Architecture](architecture.md) | -| Set up a checkout and run an edit-test-debug loop | [Development](development.md) | -| Add or maintain a module | [Module guide](modules.md) | -| Check a module's key, default, dependency, or test location | [Module reference](module-reference.md) | -| Choose the smallest useful test | [Testing](testing.md) | -| Diagnose installation, logs, Toolbox, OCR, Vela, or capability gating | [Troubleshooting](troubleshooting.md) | -| Prepare a nightly, release candidate, stable release, or backport | [Releases](releases.md) | -| Review the production ZIP for extensions.gnome.org | [GNOME Extensions review notes](extension-review.md) | -| Prepare a contribution | [Contributing](../CONTRIBUTING.md) | +| Goal | Start here | +| --- | --- | +| Understand the runtime and ownership model | [Architecture](architecture.md) | +| Set up a checkout and run an edit-test-debug loop | [Development](development.md) | +| Add or maintain a module | [Module guide](modules.md) | +| Check a module's key, default, dependency, or test location | [Module reference](module-reference.md) | +| Choose the smallest useful test | [Testing](testing.md) | +| Diagnose installation, logs, Toolbox, OCR, Vela, or capability gating | [Troubleshooting](troubleshooting.md) | +| Prepare a nightly, release candidate, stable release, or backport | [Releases](releases.md) | +| Review the production ZIP for extensions.gnome.org | [GNOME Extensions review notes](extension-review.md) | +| Prepare a contribution | [Contributing](../CONTRIBUTING.md) | -The root [README](../README.md) covers installation, removal, compatibility, and the user-facing -module summary. Implementation details live in these pages. +The root [README](../README.md) covers installation, removal, compatibility, and the user-facing module summary. Implementation details live in these pages. diff --git a/docs/architecture.md b/docs/architecture.md index f216482..79d6f7b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,7 +1,6 @@ # Architecture -Aurora Shell has two installed entry points and two development-only layers. Preferences code must -not import Shell libraries, and production packages must not carry contributor tools. +Aurora Shell has two installed entry points and two development-only layers. Preferences code must not import Shell libraries, and production packages must not carry contributor tools. ## Components and process boundaries @@ -41,13 +40,9 @@ flowchart LR DEV --> ED ``` -`src/extension.ts` creates and stops `ShellRuntime`. `src/prefs.ts` runs separately under GTK/Adwaita -and reads only catalog metadata plus GSettings. GTK and Adw belong in preferences; Clutter, Meta, -Shell, and St belong in the Shell process. +`src/extension.ts` creates and stops `ShellRuntime`. `src/prefs.ts` runs separately under GTK/Adwaita and reads only catalog metadata plus GSettings. GTK and Adw belong in preferences; Clutter, Meta, Shell, and St belong in the Shell process. -`src/extension.dev.ts` is the development entry point. It starts the same `ShellRuntime` and adds -DevTool only when `AURORA_DEVTOOLS=1`. Package inspection ensures the production ZIP uses the normal -entry point and omits development files. +`src/extension.dev.ts` is the development entry point. It starts the same `ShellRuntime` and adds DevTool only when `AURORA_DEVTOOLS=1`. Package inspection ensures the production ZIP uses the normal entry point and omits development files. ## Startup, reconciliation, and shutdown @@ -79,32 +74,20 @@ For each catalog definition, reconciliation combines two facts: 1. The module's GSettings switch is enabled. 2. `moduleSupportsRuntime()` accepts the active display roles and probed capabilities. -A module factory or `enable()` failure is logged, and the manager asks a constructed instance to -disable. Later modules continue only when that cleanup returns normally; a cleanup or disable -exception is surfaced and stops the current reconciliation or shutdown pass. `ModuleManager` removes -an active instance from its map before calling `disable()`, so a later reconciliation can attempt a -clean enable. Module `disable()` methods must therefore tolerate partial enable and repeated -lifecycle cycles without throwing. +A module factory or `enable()` failure is logged, and the manager asks a constructed instance to disable. Later modules continue only when that cleanup returns normally; a cleanup or disable exception is surfaced and stops the current reconciliation or shutdown pass. `ModuleManager` removes an active instance from its map before calling `disable()`, so a later reconciliation can attempt a clean enable. Module `disable()` methods must therefore tolerate partial enable and repeated lifecycle cycles without throwing. ## Device snapshots, display roles, and capabilities -`DefaultDeviceService` produces a snapshot from Shell monitor data, input presence, backlight, -orientation sensors, ModemManager, and D-Bus name ownership. A snapshot contains: +`DefaultDeviceService` produces a snapshot from Shell monitor data, input presence, backlight, orientation sensors, ModemManager, and D-Bus name ownership. A snapshot contains: - device class: `phone`, `tablet`, `laptop`, `desktop`, or `unknown`; - input mode: `touch`, `pointer`, `keyboard`, `mixed`, or `unknown`; - logical monitor geometry, scale, orientation, built-in status, and role; -- probed capabilities: `touch`, `accelerometer`, `light-sensor`, `proximity-sensor`, `cellular`, and - `backlight`. +- probed capabilities: `touch`, `accelerometer`, `light-sensor`, `proximity-sensor`, `cellular`, and `backlight`. -External monitors have the `desktop` role. A built-in monitor is `mobile` on a phone or tablet, -`desktop` on a laptop or desktop, and otherwise `unknown`. Until mobile-specific module surfaces are -registered, a mobile-only topology also receives the desktop fallback role. Mixed topologies retain -both roles. +External monitors have the `desktop` role. A built-in monitor is `mobile` on a phone or tablet, `desktop` on a laptop or desktop, and otherwise `unknown`. Until mobile-specific module surfaces are registered, a mobile-only topology also receives the desktop fallback role. Mixed topologies retain both roles. -Manifest runtime policy defaults to desktop role and session scope. A `requires` list is conjunctive: -every named capability must exist. The current catalog does not declare capability requirements, so -modules that depend on an optional service handle absence inside their own lifecycle. +Manifest runtime policy defaults to desktop role and session scope. A `requires` list is conjunctive: every named capability must exist. The current catalog does not declare capability requirements, so modules that depend on an optional service handle absence inside their own lifecycle. ## One metadata flow @@ -122,40 +105,29 @@ flowchart LR G --> T ``` -- The manifest owns the stable module key, settings switch, section, labels, options, internal - settings, and runtime policy. +- The manifest owns the stable module key, settings switch, section, labels, options, internal settings, and runtime policy. - `MODULE_CATALOG` owns user-visible order and is safe to import from preferences. - `registry.ts` is the only manifest-key-to-factory map. - The schema owns value types and defaults. No generator copies data between these files. - `prefs.ts` selects a native preferences row from each option type. - `registry.test.ts` and `project/schema.test.ts` parse the TypeScript and XML to reject drift. -See the [module guide](modules.md) for the change sequence and the -[module reference](module-reference.md) for the current catalog. +See the [module guide](modules.md) for the change sequence and the [module reference](module-reference.md) for the current catalog. ## Resource ownership -GNOME review rules require everything created or connected during `enable()` to be undone during -`disable()`. Aurora Shell uses two ownership styles: +GNOME review rules require everything created or connected during `enable()` to be undone during `disable()`. Aurora Shell uses two ownership styles: -- `LifecycleScope` owns signal handlers and explicit cleanup callbacks for one enable cycle. It - disposes callbacks in reverse registration order and is idempotent. -- Widgets and domain objects own their child actors, cancellables, D-Bus subscriptions, and other - resources, then release them from `destroy()` or the module's `disable()`. +- `LifecycleScope` owns signal handlers and explicit cleanup callbacks for one enable cycle. It disposes callbacks in reverse registration order and is idempotent. +- Widgets and domain objects own their child actors, cancellables, D-Bus subscriptions, and other resources, then release them from `destroy()` or the module's `disable()`. -`ManagedSource` and `ManagedTimeout` bind replaceable GLib sources to a lifecycle scope. Direct -resources remain explicit when the local owner is clearer. Never rely on a callback eventually -returning `GLib.SOURCE_REMOVE`; GNOME requires active sources to be removed during disable. +`ManagedSource` and `ManagedTimeout` bind replaceable GLib sources to a lifecycle scope. Direct resources remain explicit when the local owner is clearer. Never rely on a callback eventually returning `GLib.SOURCE_REMOVE`; GNOME requires active sources to be removed during disable. -The outer teardown order is manager lifecycle subscriptions, active modules in reverse order, -device service, context, then icon search paths. This reverses startup and avoids callbacks into -already-destroyed dependencies. +The outer teardown order is manager lifecycle subscriptions, active modules in reverse order, device service, context, then icon search paths. This reverses startup and avoids callbacks into already-destroyed dependencies. ## Tests and package flow -Pure calculations and structural contracts run under Node in `tests/unit`. GNOME Shell behavior runs -as `.test.js` scripts under `gnome-shell-test-tool` in `tests/shell`. The production package is used -for normal Shell tests; the development package is tested separately with `AURORA_DEVTOOLS=1`. +Pure calculations and structural contracts run under Node in `tests/unit`. GNOME Shell behavior runs as `.test.js` scripts under `gnome-shell-test-tool` in `tests/shell`. The production package is used for normal Shell tests; the development package is tested separately with `AURORA_DEVTOOLS=1`. ```mermaid flowchart LR @@ -175,35 +147,29 @@ flowchart LR CI --> ART[release artifacts] ``` -Toolbox uses the same `Containerfile` inputs as CI. The CI runner adds a private runtime directory, -system D-Bus, and logind/GDM mocks before running the production and DevTool suites. See -[Testing](testing.md) for the selection matrix and runner diagnostics. +Toolbox uses the same `Containerfile` inputs as CI. The CI runner adds a private runtime directory, system D-Bus, and logind/GDM mocks before running the production and DevTool suites. See [Testing](testing.md) for the selection matrix and runner diagnostics. ## Architectural invariants -- Importing an entry point or constructing the extension creates no Shell objects or signal - connections; work begins in `enable()`. +- Importing an entry point or constructing the extension creates no Shell objects or signal connections; work begins in `enable()`. - Preferences never import Shell-only libraries or runtime module implementations. - Every catalog key has exactly one registry factory and one schema switch. - Every manifest option or internal setting has exactly one schema key. -- A factory or enable failure with successful cleanup does not prevent later modules from starting; - a thrown cleanup or disable error stops the current manager pass. +- A factory or enable failure with successful cleanup does not prevent later modules from starting; a thrown cleanup or disable error stops the current manager pass. - Every enable cycle has a complete, repeatable disable path. -- Production and development packages use the same runtime; only the development entry point adds - DevTool. -- Production packages contain reviewable JavaScript, schemas, translations, styles, licenses, and - required assets, not TypeScript or build tooling. +- Production and development packages use the same runtime; only the development entry point adds DevTool. +- Production packages contain reviewable JavaScript, schemas, translations, styles, licenses, and required assets, not TypeScript or build tooling. ## Change impact map -| Change | Inspect and update | Minimum evidence | -| ---------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------- | -| New or renamed module | manifest, catalog, registry, schema, module reference | registry, schema, and documentation tests | -| New option | manifest and schema; preferences only for a new option type | schema and relevant unit test | -| Module lifecycle or Shell UI | implementation, owner teardown, Shell test | unit test where logic is pure; targeted Shell test | -| Device role or capability | `src/device`, runtime policy consumers, module manager | device and module-manager unit tests; affected Shell test | -| Preferences rendering | manifest metadata and `src/prefs.ts` | unit/validation plus manual preferences check | -| Build or package contents | scripts, entry points, package inspection | `just package check` and Shexli | -| Workflow or release behavior | workflow YAML and release runbook | actionlint through CI workflow checks; dry-run/review evidence | +| Change | Inspect and update | Minimum evidence | +| --- | --- | --- | +| New or renamed module | manifest, catalog, registry, schema, module reference | registry, schema, and documentation tests | +| New option | manifest and schema; preferences only for a new option type | schema and relevant unit test | +| Module lifecycle or Shell UI | implementation, owner teardown, Shell test | unit test where logic is pure; targeted Shell test | +| Device role or capability | `src/device`, runtime policy consumers, module manager | device and module-manager unit tests; affected Shell test | +| Preferences rendering | manifest metadata and `src/prefs.ts` | unit/validation plus manual preferences check | +| Build or package contents | scripts, entry points, package inspection | `just package check` and Shexli | +| Workflow or release behavior | workflow YAML and release runbook | actionlint through CI workflow checks; dry-run/review evidence | Use [Testing](testing.md) to expand the minimum evidence when a change crosses more than one row. diff --git a/docs/development.md b/docs/development.md index 2834f23..5e41403 100644 --- a/docs/development.md +++ b/docs/development.md @@ -2,8 +2,7 @@ ## Set up the checkout -Aurora Shell needs Node.js 20 or newer, Yarn 4, `just`, and GNOME 50 build/runtime tools. Clone the -repository, install the locked JavaScript dependencies, and confirm the source contracts: +Aurora Shell needs Node.js 20 or newer, Yarn 4, `just`, and GNOME 51 build/runtime tools. Clone the repository, install the locked JavaScript dependencies, and confirm the source contracts: ```bash git clone https://github.com/luminusOS/aurora-shell.git @@ -13,16 +12,14 @@ just validate just test unit ``` -`just deps` uses Yarn's immutable mode, so a lockfile mismatch fails instead of rewriting the -dependency graph. +`just deps` uses Yarn's immutable mode, so a lockfile mismatch fails instead of rewriting the dependency graph. ## Edit, validate, run, debug Use one short loop for most work: 1. Find the owning module and its manifest through [Module reference](module-reference.md). -2. Change the runtime code and the smallest observable test. Update the manifest/schema only when - the settings contract changes. +2. Change the runtime code and the smallest observable test. Update the manifest/schema only when the settings contract changes. 3. Run the targeted Node or Shell test described in [Testing](testing.md). 4. Run `just validate` and `just test unit` before widening the check. 5. Install or start the development runtime only when the behavior needs visual inspection. @@ -39,25 +36,20 @@ Or build, install, and start an isolated GNOME Shell devkit session: just run ``` -The development package uses `extension.dev.ts` and enables DevTool only when the launcher supplies -`AURORA_DEVTOOLS=1`. It is separate from the production ZIP. To run the same session in Toolbox: +The development package uses `extension.dev.ts` and enables DevTool only when the launcher supplies `AURORA_DEVTOOLS=1`. It is separate from the production ZIP. To run the same session in Toolbox: ```bash just toolbox create just toolbox run ``` -For stylesheet work, `just watch` recompiles SCSS on changes. It does not reload the extension or -run tests. +For stylesheet work, `just watch` recompiles SCSS on changes. It does not reload the extension or run tests. -Read recent Aurora messages with `just logs`. Module logs include an owning prefix; start from the -first error rather than later teardown noise. [Troubleshooting](troubleshooting.md) covers common -load, Toolbox, OCR, Vela, and capability cases. +Read recent Aurora messages with `just logs`. Module logs include an owning prefix; start from the first error rather than later teardown noise. [Troubleshooting](troubleshooting.md) covers common load, Toolbox, OCR, Vela, and capability cases. ## Build and package -`just build` compiles TypeScript and Sass, copies schemas and metadata, and compiles translations -into `dist/`. Packaging adds GNOME's extension bundle step: +`just build` compiles TypeScript and Sass, copies schemas and metadata, and compiles translations into `dist/`. Packaging adds GNOME's extension bundle step: ```bash just package production @@ -65,17 +57,13 @@ just package development just package check ``` -`just package check` builds both variants and verifies their contents and entry points. The -production ZIP is the EGO/release artifact; the development ZIP exists for contributors and its -DevTool integration test. +`just package check` builds both variants and verifies their contents and entry points. The production ZIP is the EGO/release artifact; the development ZIP exists for contributors and its DevTool integration test. -Use `just clean` to remove `dist/`. `just clean all` also removes `node_modules`, so the next build -needs `just deps`. +Use `just clean` to remove `dist/`. `just clean all` also removes `node_modules`, so the next build needs `just deps`. ## Test in the right environment -Node tests need no Shell process. Host Shell tests need `gnome-shell-test-tool` and the services -expected by the feature. Toolbox provides the project's containerized GNOME environment: +Node tests need no Shell process. Host Shell tests need `gnome-shell-test-tool` and the services expected by the feature. Toolbox provides the project's containerized GNOME environment: ```bash just toolbox test tests/shell/desktop/trayIcons/trayIcons.test.js @@ -83,12 +71,9 @@ just toolbox test just toolbox test-dev ``` -Set `AURORA_TOOLBOX_IMAGE` to use a prebuilt/local image and `AURORA_TOOLBOX_NAME` to select another -container. The default name is `aurora-shell-devel`. +Set `AURORA_TOOLBOX_IMAGE` to use a prebuilt/local image and `AURORA_TOOLBOX_NAME` to select another container. The default name is `aurora-shell-devel`. -CI derives its image name from `Containerfile`, the first `shell-version` in `metadata.json`, and a -hash of the container inputs. A new GNOME generation therefore requires coordinated metadata, GIR -type dependency, and `FEDORA_VERSION` changes. +CI derives its image name from `Containerfile`, the first `shell-version` in `metadata.json`, and a hash of the container inputs. A new GNOME generation therefore requires coordinated metadata, GIR type dependency, and `FEDORA_VERSION` changes. ## Before review @@ -101,9 +86,6 @@ just package check just shexli ``` -Add the relevant targeted Shell test, and use `just toolbox test` for lifecycle, infrastructure, or -cross-module changes. Documentation-only work does not need Shell tests. +Add the relevant targeted Shell test, and use `just toolbox test` for lifecycle, infrastructure, or cross-module changes. Documentation-only work does not need Shell tests. -Shexli scans the generated production ZIP. Review every location against -[GNOME Extensions review notes](extension-review.md); an existing rule ID does not approve a new -occurrence. +Shexli scans the generated production ZIP. Review every location against [GNOME Extensions review notes](extension-review.md); an existing rule ID does not approve a new occurrence. diff --git a/docs/extension-review.md b/docs/extension-review.md index c5583fe..be692f4 100644 --- a/docs/extension-review.md +++ b/docs/extension-review.md @@ -1,37 +1,27 @@ # GNOME Extensions review notes -This page maps current Shexli findings to their source owners for manual review of the production -ZIP. It applies the -[GNOME Extensions review guidelines](https://gjs.guide/extensions/review-guidelines/review-guidelines.html) -to the current Shexli output; it is not a replacement for that output or a rule-ID allowlist. +This page maps current Shexli findings to their source owners for manual review of the production ZIP. It applies the [GNOME Extensions review guidelines](https://gjs.guide/extensions/review-guidelines/review-guidelines.html) to the current Shexli output; it is not a replacement for that output or a rule-ID allowlist. ## Current baseline -On 2026-08-28, `just shexli` ran successfully inside the `aurora-shell-devel` Toolbox against -`aurora-shell@luminusos.github.io.shell-extension.zip` and reported five findings: zero errors, four -warnings, and one manual-review item. +On 2026-09-08, the production ZIP reported six findings: one version-validation error, four warnings, and one manual-review item. The installed Shexli entry point could not import its package, and tree-sitter 0.26 crashed during analysis. The complete scan used `uvx --python 3.13 --from shexli --with 'tree-sitter==0.25.2' shexli dist/target/aurora-shell@luminusos.github.io.shell-extension.zip --format json`; its output is retained in `dist/shexli-calendar-reminders.json`. These tool dependencies are isolated from the project. -| Rule | Classification | Affected files or owners | Decision | -| ----------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `EGO-A-005` | Expected manual review | `capture/captureOcrSession.js`, `capture/screenshotCapture.js`, `clipboard/clipboardHistory.js`, `clipboard/clipboardMonitor.js` | Accepted for the declared local clipboard features below. | -| `EGO-X-006` | Accepted warning for current logger | `core/logger.js` | `lookupByURL(import.meta.url)` obtains this extension's name and UUID for structured logging inside a shared module that has no Extension instance. It creates no object or lifecycle state. Revisit if GNOME provides a context-free structured logging identity or logger context is refactored. | -| `EGO-L-002` | Ownership-indirection false positive | `clipboard/clipboardItem.js`, `dock/externalStorageIcon.js`, `dock/trashIcon.js`, `panel/clock/meetingClock/meetingClockPill.js` | Owners release menus, monitors, cancellables, operations, and widgets before or through actor-tree destruction. | -| `EGO-L-005` | Actor/owner lifetime false positive | `clipboard/clipboardItem.js`, `dock/externalStorageIcon.js`, `dock/trashIcon.js`, `panel/clock/meetingClock/meetingClockPill.js` | Child actor references die with `super.destroy()`; Meeting Clock destroys its widget and the module drops the pill owner. | -| `EGO-L-003` | Lifecycle-indirection false positive | Capture Tools, Clipboard, Tray Icons, Aurora Menu, Bluetooth, clocks, Lock Keys, Low Battery, Volume Mixer, App Search Tooltip, Privacy, and themes | Signals are owned by `LifecycleScope`, `connectObject()`, widget destruction, or an explicit backend/manager `destroy()`. | +| Rule | Classification | Affected files or owners | Decision | +| --- | --- | --- | --- | +| `EGO-A-005` | Expected manual review | `capture/captureOcrSession.js`, `capture/screenshotCapture.js`, `clipboard/clipboardHistory.js`, `clipboard/clipboardMonitor.js` | Accepted for the declared local clipboard features below. | +| `EGO-X-006` | Accepted warning for current logger | `core/logger.js` | `lookupByURL(import.meta.url)` obtains this extension's name and UUID for structured logging inside a shared module that has no Extension instance. It creates no object or lifecycle state. Revisit if GNOME provides a context-free structured logging identity or logger context is refactored. | +| `EGO-L-002` | Ownership-indirection false positive | `clipboard/clipboardItem.js`, `desktop/trayIcons/trayContainer.js`, `dock/externalStorageIcon.js`, `dock/trashIcon.js`, `panel/clock/calendarReminders/calendarRemindersPill.js`, `privacy/privacyPanel.js` | Owners release menus, monitors, cancellables, operations, and widgets before or through actor-tree destruction. TrayContainer attaches its scroll controller with `add_action()` and destroys the owning actor; Privacy Panel removes its motion controller from the panel and clears the reference on disable. | +| `EGO-L-005` | Actor/owner lifetime false positive | `clipboard/clipboardItem.js`, `desktop/trayIcons/trayContainer.js`, `dock/externalStorageIcon.js`, `dock/trashIcon.js`, `panel/clock/calendarReminders/calendarRemindersPill.js` | Child actor and action references are released with their owning actor; Calendar Reminders destroys its widget and the module drops the pill owner. | +| `EGO-L-003` | Lifecycle-indirection false positive | Capture Tools, Clipboard, Tray Icons, Aurora Menu, Bluetooth, clocks, Lock Keys, Low Battery, Volume Mixer, App Search Tooltip, Privacy, and themes | Signals are owned by `LifecycleScope`, `connectObject()`, widget destruction, or an explicit backend/manager `destroy()`. | +| `EGO-M-004` | Analyzer version ceiling | `metadata.json` | Shexli 0.2.1 rejects every major version above 50 in `analyzer/rules/metadata.py`. The project deliberately targets GNOME 51 and tests it in the GNOME 51 Toolbox. Keep the declared target; this scan cannot certify its version field until the analyzer supports it. | -Do not copy these decisions to a new line automatically. A future scan is accepted only after the -reported source owner, teardown path, and package behavior are traced again. +Do not copy these decisions to a new line automatically. A future scan is accepted only after the reported source owner, teardown path, and package behavior are traced again. ## Clipboard declaration -Aurora Shell intentionally accesses the clipboard in Clipboard History and Capture Tools. -`metadata.json` describes both uses, states that data remains local, and records that Clipboard -History has no default shortcut. This satisfies the guideline that clipboard access be declared. +Aurora Shell intentionally accesses the clipboard in Clipboard History and Capture Tools. `metadata.json` describes both uses, states that data remains local, and records that Clipboard History has no default shortcut. This satisfies the guideline that clipboard access be declared. -Clipboard History reads and stores clipboard content locally so the user can browse and restore it. -Capture Tools writes the requested screenshot or recognized text to the clipboard. Neither feature -shares clipboard or OCR data with a third party. A web search occurs only after an explicit user -action and uses the configured provider. +Clipboard History reads and stores clipboard content locally so the user can browse and restore it. Capture Tools writes the requested screenshot or recognized text to the clipboard. Neither feature shares clipboard or OCR data with a third party. A web search occurs only after an explicit user action and uses the configured provider. Any new clipboard call requires all of the following evidence before acceptance: @@ -42,53 +32,29 @@ Any new clipboard call requires all of the following evidence before acceptance: ## Subprocess review -Capture Tools invokes the local `tesseract` executable only after an OCR action. It uses -`Gio.Subprocess.new()` with an argument vector, supports cancellation and forced termination, and -does not package a binary or transmit the image. A companion service would add installation and -lifecycle work without changing this local, user-triggered boundary, so the direct subprocess is an -accepted exception. +Capture Tools invokes the local `tesseract` executable only after an OCR action. It uses `Gio.Subprocess.new()` with an argument vector, supports cancellation and forced termination, and does not package a binary or transmit the image. A companion service would add installation and lifecycle work without changing this local, user-triggered boundary, so the direct subprocess is an accepted exception. The direct subprocess calls below use argument vectors and follow direct user actions: - Aurora Menu runs user-configured commands only after they are selected. -- Its Extensions item selects the first installed manager from `gnome-extensions-app`, - `gnome-shell-extension-prefs`, or `flatpak run com.mattjakeman.ExtensionManager`. +- Its Extensions item selects the first installed manager from `gnome-extensions-app`, `gnome-shell-extension-prefs`, or `flatpak run com.mattjakeman.ExtensionManager`. - Volume Mixer opens `gnome-control-center sound` from its Sound Settings item. -- Background Apps requests the application's quit action first and uses `flatpak kill ` only - as the fallback for a user-selected Quit action. +- Background Apps requests the application's quit action first and uses `flatpak kill ` only as the fallback for a user-selected Quit action. -Trash asks Gio to open `trash:///`. Its file-manager fallback creates a `Gio.AppInfo` from the -Shell-provided executable after `GLib.shell_quote()` and passes the fixed Trash URI to -`launch_uris()`. No user-controlled command text enters that command-line string. +Trash asks Gio to open `trash:///`. Its file-manager fallback creates a `Gio.AppInfo` from the Shell-provided executable after `GLib.shell_quote()` and passes the fixed Trash URI to `launch_uris()`. No user-controlled command text enters that command-line string. -Aurora Shell packages no executable binary and invokes no command through a shell. A new subprocess -must document why a GNOME API cannot perform the job, how arguments are separated, who terminates -it, and what user action starts it. +Aurora Shell packages no executable binary and invokes no command through a shell. A new subprocess must document why a GNOME API cannot perform the job, how arguments are separated, who terminates it, and what user action starts it. ## Lifecycle findings -`LifecycleScope` records signal disconnections and cleanup callbacks, disposes them in reverse -order, and is idempotent. `ManagedSource` and `ManagedTimeout` bind replaceable GLib sources to that -scope. This indirection accounts for the current `EGO-L-003` findings and for main-loop sources that -Shexli does not report. +`LifecycleScope` records signal disconnections and cleanup callbacks, disposes them in reverse order, and is idempotent. `ManagedSource` and `ManagedTimeout` bind replaceable GLib sources to that scope. This indirection accounts for the current `EGO-L-003` findings and for main-loop sources that Shexli does not report. -Actor-owning classes use their `destroy()` methods as the boundary. Clipboard Item releases its menu -before `super.destroy()` destroys the card tree. Trash and External Storage release menus, monitors, -cancellables, operations, and signals before their final actor destruction. Meeting Clock Pill -unregisters and destroys its widget, after which the module drops the pill owner. These paths account -for the current `EGO-L-002` and `EGO-L-005` locations. +Actor-owning classes use their `destroy()` methods as the boundary. Clipboard Item releases its menu before `super.destroy()` destroys the card tree. Trash and External Storage release menus, monitors, cancellables, operations, and signals before their final actor destruction. Calendar Reminders Pill unregisters and destroys its widget, after which the module drops the pill owner. These paths account for the current `EGO-L-002` and `EGO-L-005` locations. -A future lifecycle finding is accepted only when the concrete owner can be named and a disable or -destroy path demonstrably releases it. “LifecycleScope is used elsewhere” is not evidence. +A future lifecycle finding is accepted only when the concrete owner can be named and a disable or destroy path demonstrably releases it. “LifecycleScope is used elsewhere” is not evidence. ## Package policy -The production ZIP is the only artifact submitted to extensions.gnome.org. It targets only the Shell -versions in `metadata.json`, includes the schema XML, `LICENSE`, and `CREDITS.md`, and excludes -developer tooling. The separately named development ZIP exists for DevTool tests and contributor -sessions. +The production ZIP is the only artifact submitted to extensions.gnome.org. It targets only the Shell versions in `metadata.json`, includes the schema XML, `LICENSE`, and `CREDITS.md`, and excludes developer tooling. The separately named development ZIP exists for DevTool tests and contributor sessions. -Re-run `just shexli` after any change to runtime code, metadata, schemas, package contents, -clipboard/subprocess behavior, or ownership. Preserve the complete command output as location-level -evidence; update this summary with the date, totals, every rule, affected owners, and evidence for -each classification. +Re-run `just shexli` after any change to runtime code, metadata, schemas, package contents, clipboard/subprocess behavior, or ownership. Preserve the complete command output as location-level evidence; update this summary with the date, totals, every rule, affected owners, and evidence for each classification. diff --git a/docs/module-reference.md b/docs/module-reference.md index 909bd7a..1f85723 100644 --- a/docs/module-reference.md +++ b/docs/module-reference.md @@ -1,34 +1,30 @@ # Module reference -This table follows `MODULE_CATALOG` order. “On” and “off” are the GSettings defaults for a fresh -schema. Every current module uses desktop role and session scope; none declares a runtime capability -requirement. A module may still wait for an optional Shell surface or service before attaching UI. +This table follows `MODULE_CATALOG` order. “On” and “off” are the GSettings defaults for a fresh schema. Every current module uses desktop role and session scope; none declares a runtime capability requirement. A module may still wait for an optional Shell surface or service before attaching UI. -| Key | Setting and default | Behavior and dependency | Implementation and primary test | -| ------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | -| `no-overview` | `module-no-overview`: on | Opens the desktop instead of Overview at Shell startup. | `src/patches/noOverview.ts`; `tests/shell/patches/noOverview.test.js` | -| `pip-on-top` | `module-pip-on-top`: on | Keeps detected picture-in-picture windows above other windows across workspaces. | `src/patches/pipOnTop.ts`; `tests/shell/patches/pipOnTop.test.js` | -| `focus-launched-windows` | `module-focus-launched-windows`: on | Activates any window that emits Shell's `window-demands-attention` signal instead of leaving its attention notification. | `src/patches/focusLaunchedWindows.ts`; registry/schema tests | -| `capture-tools` | `module-capture-tools`: on | Adds annotation and export controls to GNOME's screenshot UI. Optional OCR invokes local Tesseract only after the user requests it; web search uses the configured provider. | `src/capture/`; `tests/shell/capture/captureTools.test.js` | -| `theme-changer` | `module-theme-changer`: on | Watches and synchronizes GNOME's color-scheme state. | `src/theme/themeChanger.ts`; `tests/shell/theme/themeChanger.test.js` | -| `dock` | `module-dock`: on | Replaces the overview dash presentation with a configurable edge dock, auto-hide/intellihide, optional previews, Trash, and removable storage. Depends on GNOME Shell dash, layout, window, and volume APIs. | `src/dock/`; `tests/shell/dock/dock.test.js` | -| `aurora-menu` | `module-aurora-menu`: on | Adds a panel menu for recent items, system locations, applications, and user-configured commands. Commands run only when selected. | `src/panel/auroraMenu.ts`; `tests/shell/panel/auroraMenu.test.js` | -| `power-menu-avatar` | `module-power-menu-avatar`: on | Adds the current user's avatar and name to the existing Quick Settings power menu. Waits for the private Shell menu surface. | `src/panel/powerMenuAvatar.ts`; `tests/shell/panel/powerMenuAvatar.test.js` | -| `volume-mixer` | `module-volume-mixer`: on | Adds per-application audio streams to Quick Settings and opens GNOME Sound Settings on request. Depends on Shell audio controls. | `src/panel/volumeMixer/`; `tests/shell/panel/volumeMixer/volumeMixer.test.js` | -| `low-battery-percentage` | `module-low-battery-percentage`: on | Enables GNOME's native percentage display while a battery is discharging below 30%, then restores only the value it managed. Depends on UPower and `org.gnome.desktop.interface`. | `src/panel/lowBatteryPercentage.ts`; registry/schema tests | -| `lock-key-indicators` | `module-lock-key-indicators`: on | Shows Caps Lock and Num Lock state in the panel. Depends on Shell keyboard state. | `src/panel/lockKeyIndicators.ts`; registry/schema tests | -| `xwayland-indicator` | `module-xwayland-indicator`: on | Adds an X11 badge to XWayland windows in Alt+Tab. | `src/patches/xwaylandIndicator.ts`; `tests/shell/patches/xwaylandIndicator.test.js` | -| `privacy` | `module-privacy`: on | Optionally enables Do Not Disturb and hides panel content while screen sharing. Depends on Shell screen-sharing state and GNOME notification settings. | `src/privacy/`; `tests/shell/privacy/` | -| `icon-weave` | `module-icon-weave`: on | Matches untracked windows to installed applications in memory to repair missing icons. | `src/patches/iconWeave.ts`; unit scoring/registry tests and `tests/shell/patches/iconWeave.test.js` | -| `app-search-tooltip` | `module-app-search-tooltip`: on | Shows an application's name when its overview search result is hovered. | `src/patches/appSearchTooltip.ts`; `tests/shell/patches/appSearchTooltip.test.js` | -| `vela-vpn-quick-settings` | `module-vela-vpn-quick-settings`: off | Routes VPN toggle activation through Vela's D-Bus control API. GNOME Shell fallback is separately opt-in and is used only when the Vela service or API is unavailable. | `src/patches/velaVpnQuickSettings.ts`; `tests/shell/patches/velaVpnQuickSettings.test.js` | -| `auto-theme-switcher` | `module-auto-theme-switcher`: off | Changes the configured color scheme at the light and dark times. | `src/theme/autoThemeSwitcher.ts`; `tests/shell/theme/autoThemeSwitcher.test.js` | -| `bluetooth-menu` | `module-bluetooth-menu`: on | Adds battery levels and animated device icons to Bluetooth Quick Settings. Depends on Shell's Bluetooth indicator and device data. | `src/panel/bluetoothMenu/`; `tests/shell/panel/bluetoothMenu/bluetoothMenu.test.js` | -| `weather-clock` | `module-weather-clock`: on | Places GNOME Weather beside the panel clock. It remains inactive when the GNOME Weather schema or data is unavailable. | `src/panel/clock/weatherClock/`; unit logic test and `tests/shell/panel/clock/weatherClock/weatherClock.test.js` | -| `meeting-clock` | `module-meeting-clock`: on | Shows upcoming calendar events beside the clock and can alert, snooze, filter all-day events, and include events without join links. Depends on Shell calendar sources. | `src/panel/clock/meetingClock/`; unit logic test and `tests/shell/panel/clock/meetingClock/meetingClock.test.js` | -| `tray-icons` | `module-tray-icons`: on | Adds SNI and background-app icons with limits, attention handling, deduplication, recoloring, and optional Quick Settings hiding. Depends on Shell status notifier and background-app surfaces. | `src/desktop/trayIcons/`; unit state/layout tests and `tests/shell/desktop/trayIcons/` | -| `clipboard-history` | `module-clipboard-history`: on | Stores clipboard entries locally for search, pinning, and restoration. Auto-paste requires a focused Wayland text-input-v3 field; the open shortcut is unset by default. | `src/clipboard/`; `tests/shell/clipboard/clipboardHistory.test.js` | +| Key | Setting and default | Behavior and dependency | Implementation and primary test | +| --- | --- | --- | --- | +| `no-overview` | `module-no-overview`: on | Opens the desktop instead of Overview at Shell startup. | `src/patches/noOverview.ts`; `tests/shell/patches/noOverview.test.js` | +| `pip-on-top` | `module-pip-on-top`: on | Keeps detected picture-in-picture windows above other windows across workspaces. | `src/patches/pipOnTop.ts`; `tests/shell/patches/pipOnTop.test.js` | +| `focus-launched-windows` | `module-focus-launched-windows`: on | Activates any window that emits Shell's `window-demands-attention` signal instead of leaving its attention notification. | `src/patches/focusLaunchedWindows.ts`; registry/schema tests | +| `capture-tools` | `module-capture-tools`: on | Adds annotation and export controls to GNOME's screenshot UI. Optional OCR invokes local Tesseract only after the user requests it; web search uses the configured provider. | `src/capture/`; `tests/shell/capture/captureTools.test.js` | +| `theme-changer` | `module-theme-changer`: on | Watches and synchronizes GNOME's color-scheme state. | `src/theme/themeChanger.ts`; `tests/shell/theme/themeChanger.test.js` | +| `dock` | `module-dock`: on | Replaces the overview dash presentation with a configurable edge dock, auto-hide/intellihide, optional previews, Trash, and removable storage. Depends on GNOME Shell dash, layout, window, and volume APIs. | `src/dock/`; `tests/shell/dock/dock.test.js` | +| `aurora-menu` | `module-aurora-menu`: on | Adds a panel menu for recent items, system locations, applications, and user-configured commands. Commands run only when selected. | `src/panel/auroraMenu.ts`; `tests/shell/panel/auroraMenu.test.js` | +| `power-menu-avatar` | `module-power-menu-avatar`: on | Adds the current user's avatar and name to the existing Quick Settings power menu. Waits for the private Shell menu surface. | `src/panel/powerMenuAvatar.ts`; `tests/shell/panel/powerMenuAvatar.test.js` | +| `volume-mixer` | `module-volume-mixer`: on | Adds per-application audio streams to Quick Settings and opens GNOME Sound Settings on request. Depends on Shell audio controls. | `src/panel/volumeMixer/`; `tests/shell/panel/volumeMixer/volumeMixer.test.js` | +| `low-battery-percentage` | `module-low-battery-percentage`: on | Enables GNOME's native percentage display while a battery is discharging below 30%, then restores only the value it managed. Depends on UPower and `org.gnome.desktop.interface`. | `src/panel/lowBatteryPercentage.ts`; registry/schema tests | +| `lock-key-indicators` | `module-lock-key-indicators`: on | Shows Caps Lock and Num Lock state in the panel. Depends on Shell keyboard state. | `src/panel/lockKeyIndicators.ts`; registry/schema tests | +| `xwayland-indicator` | `module-xwayland-indicator`: on | Adds an X11 badge to XWayland windows in Alt+Tab. | `src/patches/xwaylandIndicator.ts`; `tests/shell/patches/xwaylandIndicator.test.js` | +| `privacy` | `module-privacy`: on | Optionally enables Do Not Disturb and hides panel content while screen sharing. Depends on Shell screen-sharing state and GNOME notification settings. | `src/privacy/`; `tests/shell/privacy/` | +| `icon-weave` | `module-icon-weave`: on | Matches untracked windows to installed applications in memory to repair missing icons. | `src/patches/iconWeave.ts`; unit scoring/registry tests and `tests/shell/patches/iconWeave.test.js` | +| `app-search-tooltip` | `module-app-search-tooltip`: on | Shows an application's name when its overview search result is hovered. | `src/patches/appSearchTooltip.ts`; `tests/shell/patches/appSearchTooltip.test.js` | +| `vela-vpn-quick-settings` | `module-vela-vpn-quick-settings`: off | Routes VPN toggle activation through Vela's D-Bus control API. GNOME Shell fallback is separately opt-in and is used only when the Vela service or API is unavailable. | `src/patches/velaVpnQuickSettings.ts`; `tests/shell/patches/velaVpnQuickSettings.test.js` | +| `auto-theme-switcher` | `module-auto-theme-switcher`: off | Changes the configured color scheme at the light and dark times. | `src/theme/autoThemeSwitcher.ts`; `tests/shell/theme/autoThemeSwitcher.test.js` | +| `bluetooth-menu` | `module-bluetooth-menu`: on | Adds battery levels and animated device icons to Bluetooth Quick Settings. Depends on Shell's Bluetooth indicator and device data. | `src/panel/bluetoothMenu/`; `tests/shell/panel/bluetoothMenu/bluetoothMenu.test.js` | +| `weather-clock` | `module-weather-clock`: on | Places GNOME Weather beside the panel clock. It remains inactive when the GNOME Weather schema or data is unavailable. | `src/panel/clock/weatherClock/`; unit logic test and `tests/shell/panel/clock/weatherClock/weatherClock.test.js` | +| `calendar-reminders` | `module-calendar-reminders`: on | Shows upcoming calendar events beside the clock and delivers configured Evolution reminders with Open Calendar and Snooze actions. Optional forced reminders also notify at the start of timed events, even after an earlier reminder. All-day filtering applies to the panel; forced reminders exclude all-day events. Depends on Shell calendar sources and Evolution for configured reminders. | `src/panel/clock/calendarReminders/`; unit logic tests and `tests/shell/panel/clock/calendarReminders/calendarReminders.test.js` | +| `tray-icons` | `module-tray-icons`: on | Adds SNI and background-app icons with limits, attention handling, deduplication, recoloring, and optional Quick Settings hiding. Depends on Shell status notifier and background-app surfaces. | `src/desktop/trayIcons/`; unit state/layout tests and `tests/shell/desktop/trayIcons/` | +| `clipboard-history` | `module-clipboard-history`: on | Stores clipboard entries locally for search, pinning, and restoration. Auto-paste requires a focused Wayland text-input-v3 field; the open shortcut is unset by default. | `src/clipboard/`; `tests/shell/clipboard/clipboardHistory.test.js` | -Option types, defaults, and labels live in each manifest and the GSettings schema. Use the -[module guide](modules.md) when changing them; the documentation test requires this table's keys to -match the catalog exactly. +Option types, defaults, and labels live in each manifest and the GSettings schema. Use the [module guide](modules.md) when changing them; the documentation test requires this table's keys to match the catalog exactly. diff --git a/docs/modules.md b/docs/modules.md index a7ecbd5..77199fb 100644 --- a/docs/modules.md +++ b/docs/modules.md @@ -1,13 +1,10 @@ # Add and maintain a module -A module is one manifest, one runtime factory, and one reversible lifecycle. Start in the functional -directory that owns the behavior; do not add a new framework or directory for a single feature. +A module is one manifest, one runtime factory, and one reversible lifecycle. Start in the functional directory that owns the behavior; do not add a new framework or directory for a single feature. ## 1. Write the manifest -Create `feature.manifest.ts` beside the implementation. Manifests may import types and the shared -gettext helper, but no GNOME Shell UI libraries. Preferences imports every manifest in a separate -process. +Create `feature.manifest.ts` beside the implementation. Manifests may import types and the shared gettext helper, but no GNOME Shell UI libraries. Preferences imports every manifest in a separate process. ```typescript import type { ModuleManifest } from '~/module.ts'; @@ -22,11 +19,9 @@ export const manifest: ModuleManifest = { }; ``` -`key` identifies the runtime factory and documentation entry. `settingsKey` is the master switch. -Choose one existing section: `dock-panel`, `appearance`, `behavior`, or `privacy-clipboard`. +`key` identifies the runtime factory and documentation entry. `settingsKey` is the master switch. Choose one existing section: `dock-panel`, `appearance`, `behavior`, or `privacy-clipboard`. -Runtime policy is optional. Its defaults are `{ roles: ['desktop'], scope: 'session' }`. Add policy -only when the feature differs from that default: +Runtime policy is optional. Its defaults are `{ roles: ['desktop'], scope: 'session' }`. Add policy only when the feature differs from that default: ```typescript runtime: { @@ -36,35 +31,25 @@ runtime: { }, ``` -The manager runs a module only when at least one declared role is active and every declared -capability is present. If a dependency is an optional application or D-Bus service rather than a -device capability, keep the module loadable and handle absence locally. +The manager runs a module only when at least one declared role is active and every declared capability is present. If a dependency is an optional application or D-Bus service rather than a device capability, keep the module loadable and handle absence locally. ## 2. Declare options and schema defaults -Add user-facing options to `options`. Supported types are defined by `ModuleOption` in -`src/module.ts` and rendered by `src/prefs.ts`. Reuse one of them before adding preferences code. +Add user-facing options to `options`. Supported types are defined by `ModuleOption` in `src/module.ts` and rendered by `src/prefs.ts`. Reuse one of them before adding preferences code. -Each option `key`, each time option's `hourKey` and `minuteKey`, and each `internalSettings` entry -must have a matching key in -`data/schemas/org.gnome.shell.extensions.aurora-shell.gschema.xml`. The schema is the source of types -and defaults. Use `module-` for the master switch and `-