# OmaRest research notes

Research checked 2026-08-22.

## Reference project

[Cat Gatekeeper](https://github.com/zokuzoku/cat-gatekeeper) is a browser
extension that displays a break screen after too much time on selected sites.
The linked repository now contains an earlier MIT-licensed version and warns
that its assets are not covered by that license.

The [current source repository](https://github.com/zokuzoku/cat-gatekeeper-source)
states that:

- the current source is published for transparency and security review;
- it is source-available, not open source;
- copying, modification, and redistribution are not permitted except by its
  license; and
- the official cat-video assets are proprietary and not included.

Its browser manifest installs content scripts on HTTP and HTTPS pages. That is
how it can measure selected websites and modify the page. An Omarchy/Quickshell
plugin cannot obtain the active tab URL from Firefox or Chromium merely by
observing a Wayland window.

## Clean-room product boundary

OmaRest may reuse the general, unprotectable idea of encouraging a break. It
must not copy implementation details from the current source, visual assets,
text, brand identity, or distinctive presentation.

The initial product should observe applications using Hyprland's public IPC:

- subscribe to active-window changes rather than repeatedly polling;
- identify applications by stable window class, with title matching only as an
  optional advanced rule;
- count foreground time using a monotonic clock;
- pause counting while the session is locked, the display is idle, or the
  configured application is not focused; and
- persist summaries, not browsing content.

## Domain-aware future option

Website rules require a companion Firefox/Chromium extension. The narrowest
acceptable bridge would send only `{browser, domain, focused, timestamp}` over
native messaging. It should never send complete URLs, page titles, or history
unless the user explicitly opts in.

This extension is deliberately outside the MVP because it adds browser-store
distribution, native-host installation, permissions review, and a second
security boundary.

## Omarchy fit

Use a multi-kind shell plugin:

- `service` for timers, Hyprland event observation, and state;
- a service-owned overlay for the intervention; and
- `bar-widget` with an anchored popup for status and configuration.

Omarchy plugins run as unsandboxed code in the long-lived shell process. Keep
parsing and accounting in small testable JavaScript models, bound subprocess
output, and avoid shell-string construction.