Home screen, dock, and launcher

After sign-in the web app shows a home screen: pages of app tiles, folders, and widgets on a cell grid, a status line, and the controls that move between apps. This page explains the home screen in webapp/js/home.js, the PC dock in webapp/js/app-wheel.js, the floating button and the app switcher, the duplicate-home button in webapp/js/tiles.js, and the touch rules in webapp/js/touch-gate.js. Widgets are on home widgets; the grid size per device is on device classes.

In short¶

• The home screen is a horizontal pager. Every page is a grid of COLS by ROWS cells, and every item has explicit cell coordinates (webapp/js/home.js:49-79).
• A new account starts with an empty home screen except the permanent Apps library tile (webapp/js/home.js:696-707).
• On a PC with room for it, a dock shows the user's pinned apps and the running apps; pins are stored in the user account (webapp/js/app-wheel.js:1-26, webapp/js/home.js:977-1022).
• A floating button returns to the home screen on a single tap and opens the app switcher on a double tap (webapp/js/home.js:2993-3014).
• The + button (tiles.duplicate) splits the window into up to four independent home screens on the pc device class only; a phone or tablet has no split screen (webapp/js/tiles.js:1-11, webapp/js/tiles.js:60-64).

How it works¶

Pages and items¶

state.pages is a list of pages; each page is a list of items of type app, folder, or widget, with col and row (webapp/js/home.js:502-504). Saved coordinates are kept when they still fit. Anything out of bounds or overlapping is moved to the first free cell, and empty pages are removed (webapp/js/home.js:575-595, webapp/js/home.js:621-710). A full page overflows onto the next page, which is created when needed (webapp/js/home.js:1-11, webapp/js/home.js:2015-2027).

reconcile() keeps a tile only while its app is installed. A tile of an app that lost its licence stays in the layout and is hidden at render time, so it returns to the same place on renewal (webapp/js/home.js:621-635). Folders with fewer than two apps dissolve into loose tiles (webapp/js/home.js:672-689).

Gestures on the home screen¶

Long-pressing an app tile asks whether to remove it from the home screen; the app stays in the Apps library. A permanent app cannot be removed (webapp/js/home.js:782-791).

Status line and banners¶

The status line shows the time, the short date, and the current language code, refreshed every second (webapp/js/home.js:104-140). Its buttons open search, the assistant app, and Settings › Notifications (webapp/js/home.js:142-165). The language chip opens a menu of every language in the manifest (webapp/js/home.js:167-215). A licence in grace or read-only state adds a banner above the home screen (webapp/js/home.js:476-500).

Apps library¶

The Apps library is a menu app: it opens as a transient screen and is not added to the running apps (webapp/js/home.js:2448-2465). It lists every app the user may see with search and lets the user add or remove home tiles (webapp/js/home.js:2600-2766). Its catalogue manifest marks it permanent and dock_fixed (src/cluster_erp/modules/app_store/catalog.json:49-60).

Dock on PC¶

initAppWheel mounts the dock only when the pointer can hover, is fine, the window is at least 900 px wide, and the page is not inside a duplicated tile (webapp/js/app-wheel.js:87-93, webapp/js/device-class.js:16-20). The dock shows:

1. apps marked dock_fixed in the catalogue, first and immovable;
2. the user's pins, stored under the UI-state key dock_pins;
3. running apps that are not pinned, while they run;
4. the floating button, when the user docked it (webapp/js/home.js:1049-1085).

The dock can be dragged to the left, right, top, or bottom edge, and auto-hide is an opt-in from its context menu. Both are saved under the UI-state key launcher (webapp/js/app-wheel.js:9-17, webapp/js/app-wheel.js:158-161, webapp/js/app-wheel.js:563-567). Inside an open app the dock always tucks away, except while the Apps library is open (webapp/js/app-wheel.js:55-62). Its menu offers pin, unpin, close, and close all; closing all runs the same reset as the switcher's close (webapp/js/home.js:4535-4552).

Floating button and app switcher¶

The floating button is created only in the top window (webapp/js/home.js:2942-2960). It can be dragged and snaps to the nearest side; its position is kept in local storage under cluster_float_btn (webapp/js/home.js:2936, webapp/js/home.js:2962-2991).

The button is hidden only when it is docked and a dock exists; on phones, tablets, narrow windows, and split panes it always stays (webapp/js/home.js:1040-1047). The switcher shows a card per running app with a thumbnail, resumes an app at its last view, closes one app, or closes all (webapp/js/home.js:3249-3426). Split panes report their running apps to the top window by postMessage on the channel cluster-tasks, so one switcher covers all panes (webapp/js/home.js:3097-3220).

Duplicate-home button and tiles¶

The + button (tiles.duplicate) is shown on the home screen of the top window only, on the pc device class only, and removed inside a tile (webapp/js/main.js:38, webapp/js/tiles.js:124-149). syncDupHome hides the button on a phone or tablet, marks the document with body.no-tiles, and collapses an active split when the device class leaves pc (webapp/js/tiles.js:130-137, webapp/js/tiles.js:148); addTile refuses outside the pc class (webapp/js/tiles.js:63-64). Each press adds a tile, up to four including the base home. A tile is a same-origin frame of the app itself with a draggable divider; each tile has a minimum width of 260 px (webapp/js/tiles.js:10-108). Logout collapses all tiles (webapp/js/main.js:166). Theme, density, accessibility, and language changes reach every tile through storage events (webapp/js/prefs.js:116-125, webapp/js/a11y.js:90-105, webapp/js/i18n.js:63-71).

The project's written engineering rules state that the + exists on the PC class only and, where it exists, is always in front and never hidden. The style sheet places it above the dock band (webapp/css/tiles.css:5-12). On narrow windows the app content and the module tab bar reserve the bottom-right corner for it only while the document is not marked body.no-tiles (webapp/css/app.css:5264-5271, webapp/css/gen.css:5166-5173).

Touch gate¶

createTouchGate(e, opts) gives drag surfaces in app bundles one rule: a mouse drags at once, a finger must hold for 450 ms first, and a finger that moves before that scrolls the nearest scroll container (webapp/js/touch-gate.js:1-40). Bundles receive it through the platform context (webapp/js/custom-widgets.js:57-60). The home screen uses its own version with the same 450 ms hold (webapp/js/home.js:80-82).

Why it is built this way¶

• Empty start: the comment in webapp/js/home.js:696-705 states that a fresh account has no prepared tiles, widgets, or dock pins, and that the Apps library tile is the one guaranteed gateway to the catalogue.
• Licence lapses keep the layout: the comment in webapp/js/home.js:622-624 states that an expiring licence must not destroy the user's arrangement.
• Single tap delay: the comment in webapp/js/home.js:3017-3021 states that a stale single-tap intent once sent a freshly opened app back to the home screen, so any other touch cancels it.

Rules and boundaries¶

• Layout, dock pins, dock edge, auto-hide, and the docked state of the floating button belong to the user account. See user UI state.
• The project's written engineering rules state that the PC experience is the launcher and that the mobile and tablet design is defined separately. See device classes.
• Browser tests: web-client/_e2e_app_wheel.mjs, web-client/_e2e_dock_pins.mjs, web-client/_e2e_dock_close_all.mjs, web-client/_e2e_switcher.mjs, web-client/_e2e_switcher_dock.mjs, web-client/_e2e_dup_home_tiles.mjs, web-client/_e2e_mobile_home.mjs, web-client/_e2e_mobile_app.mjs, web-client/_e2e_widget_move.mjs.

Interaction with other parts¶

• The app catalogue and states come from the app store module; see module apps and app scope.
• Settings › Home Screen (settings.home_screen) shows page, app, folder, and widget counts and resets the layout (webapp/js/home.js:3746-3785).

Limits and open points¶

• The switcher test header describes a hold to open the switcher (web-client/_e2e_switcher.mjs); the button code opens it on a double tap (webapp/js/home.js:2999-3007).
• The number of tiles and their widths are not saved; webapp/js/tiles.js makes no storage call, so a reload shows one home screen.

Terms introduced¶

Related pages¶

• Web app platform
• Home widgets
• Device classes
• User UI state
• Module apps and app scope

Verified against commit c0d3217 on 2026-11-14.