@workspace.global/catalog

@workspace.global/catalog is the web-component catalog of the workspace.global webdesktop: a desktop that runs in the browser, with a top bar, windows that move, resize and snap, a dock, a launcher, a lock screen and the core apps. The webdesktop app (workspace.global/webdesktop) is built from these components; the WebAssembly Craft apps run inside its windows.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @workspace.global/catalog

The components are built with @design.estate/dees-element 4 and follow the Dees light/dark theme.

What It Provides

Element	What it is
wg-desktop	The shell: top bar, desk, windows, dock and launcher, driven by a list of app manifests
wg-topbar	Workspace switcher, the focused app's menus, search, notifications with do not disturb, lock, clock, account
wg-window	Title bar with the app's toolbar and the window controls, resize edges, drag and snap
wg-dock, wg-launcher, wg-menu	Dock with running dots, search over apps and recent items, frosted menus
wg-lockscreen	Clock and password or passkey sign-in; it reports unlock, the app verifies
wg-app-files, wg-app-mail, wg-app-notes, wg-app-calendar, wg-app-terminal	Files with details pane, three-pane Mail, block-editing Notes, Day/Week/Month Calendar, Terminal with session tabs
wg-app-browser, wg-app-photos, wg-app-settings, wg-app-calculator	Browser with tabs and a mock page (it loads no sites), Photos library, Settings, Calculator
wg-app-frame	A sandboxed iframe for apps that ship as their own bundle, such as the WebAssembly Craft apps

WgWindowManager holds the window state without any DOM (open windows back to front, geometry, snap, minimized), so it can be tested and persisted on its own.

Usage

import { wgCoreApps, type IWgAppManifest } from '@workspace.global/catalog';

const apps: IWgAppManifest[] = [
  ...wgCoreApps,
  { id: 'pdfcraft', name: 'PdfCraft', icon: 'document', kind: 'frame', entry: '/apps/pdfcraft/index.html', pinned: true },
];

const desktop = document.createElement('wg-desktop');
desktop.apps = apps;
desktop.user = { name: 'Ada', email: 'ada@example.com' };
desktop.addEventListener('layout-change', (event) => save(event.detail.layout));
desktop.addEventListener('lock', () => showLockScreen());
document.body.append(desktop);

wg-desktop takes apps, workspaces, workspaceId, user, notifications, recent, desktopIcons, layout (restored when set), accent, showSidebars, showIcons and dnd. It reports layout-change, prefs-change, notifications-change, workspace-change, lock, sign-out, workspace-action, account-action and edit-action.

Menu shortcuts are shown as labels only; the browser keeps most of them.

Apps

An app is an element app (a custom element registered in the page) or a frame app (a page at entry, run in a sandboxed iframe):

interface IWgAppManifest {
  id: string;
  name: string;
  icon: TWgIconName | string; // an icon name, or an image URL starting with /, ./ or http
  kind: 'element' | 'frame';
  tagName?: string;           // element apps
  entry?: string;             // frame apps
  defaultSize?: { w: number; h: number };
  minSize?: { w: number; h: number };
  pinned?: boolean;           // keep it in the dock
  keywords?: string[];        // extra launcher search words
}

A frame app's repository ships this object as workspace.app.json next to its index.html.

Element apps

Extend WgAppElement. The desktop sets sidebar and workspaceName; return title-bar controls from renderToolbar() (start follows the title, end sits before the window controls) and use wg-toolbar-button in them. The toolbar renders in the window's shadow root, so controls that need hover or touch styles bring a small <style> block with class names prefixed by the app (wgcal-, wg-mail-):

@customElement('my-app')
export class MyApp extends WgAppElement {
  protected renderToolbar() {
    return { end: html`<wg-toolbar-button icon="plus" label="New" @click=${() => this.add()}></wg-toolbar-button>` };
  }
}

Frame apps

The frame runs with sandbox="allow-scripts allow-same-origin allow-forms allow-downloads allow-popups". Messages use postMessage and carry wg: 1:

Direction	Message
desktop → app	{ wg: 1, type: 'theme', bright: boolean, accent: string } on load and on every theme change
app → desktop	{ wg: 1, type: 'title', title: string }: shown after the app's name in the title bar
app → desktop	{ wg: 1, type: 'focus' }: brings the window forward

A frame app served from the webdesktop's own origin can lift its sandbox, because it has both allow-scripts and allow-same-origin. Serve third-party apps from a separate origin.

The window keeps the frame in the DOM while it is minimized or other windows open, close or change order, so a WebAssembly instance survives everything but its own window's close.

The core apps work on demo content passed through properties (messages, notes, events, items, photos, settings, …) and report what would reach a server as events (mail-action, note-change, calendar-action, file-action, photos-action, settings-change, browser-navigate, terminal-action), so the webdesktop can connect each one to @workspace.global/app without changing the catalog. The apps follow the window's width with container queries: a narrow window shows the compact look of the Desktop artboard, a wide one the full app.

Development

pnpm install
pnpm run watch   # wcctools dev: the catalog at http://localhost:<port>/wcctools/
pnpm test        # build, Node tests of the window manager, Chromium tests of the desktop

The catalog's Pages section has the whole desktop with demo data, and the lock screen.

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.