The browser SDK for apps that run inside the workspace.global webdesktop: a product that stays a standalone web app on its own origin, and inside a workspace follows the desktop's theme and language, names its window, and opens and saves files on the workspace's drives.

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.

Use

import { connectWorkspace } from '@workspace.global/appsdk';

// null when the app runs standalone: then nothing changes.
const workspace = await connectWorkspace({ origins: ['https://workspace.global'] });

if (workspace) {
  applyTheme(workspace.theme.bright);
  workspace.onTheme((themeArg) => applyTheme(themeArg.bright));
  workspace.onLocale((localeArg) => setLanguage(localeArg));
  workspace.setTitle('Documents');

  // The workspace's Open dialog: null when cancelled.
  const file = await workspace.openFile({ accept: ['.pdf', '.xml'] });
  if (file) await importReceipt(new File([file.data], file.name, { type: file.mime }));

  // The workspace's Save dialog: null when cancelled, throws when the save fails.
  const saved = await workspace.saveFile({ name: 'EXTF_Buchungsstapel.csv', mime: 'text/csv', data: csvBytes });

  // Files the member opens with this app from Files ("Open with").
  workspace.onOpenFile((fileArg) => importReceipt(new File([fileArg.data], fileArg.name, { type: fileArg.mime })));
}

Member
`connectWorkspace({ origins, timeoutMs?, window? })`	The connection, or null when the app is not framed (at once), framed by another origin (at once), or the parent does not answer within `timeoutMs` (3 s). The same window always gets the same connection.
`origin`	The workspace's origin.
`theme`, `onTheme(fn)`	`{ bright, accent }`, and its changes.
`locale`, `onLocale(fn)`	The workspace's language (`de-DE`), null until it has said, and its changes.
`setTitle(title)`	Shown after the app's name in the window's title bar.
`setDirty(dirty)`	Marks the window as having unsaved changes.
`requestFocus()`	Brings the window forward.
`openFile({ accept? })`	The workspace's Open dialog → `{ name, path, mime, data }` or null. A second call while it is open gets the same answer.
`saveFile({ name, mime?, data })`	The workspace's Save dialog → `{ name, path }` or null; `data` is an `ArrayBuffer`, a typed array or a `Blob`. Saves run one at a time.
`onOpenFile(fn)`	Files opened with the app; those that came before the first handler are handed to it at once.
`close()`	Stops listening.

How it talks to the workspace

It speaks the webdesktop's frame protocol 2 (TWgFrameMessage, wgFrameProtocolVersion), the same messages as the Craft apps' shim, but explicitly: nothing in the app's page is wrapped or intercepted.

Origins. Messages go to the workspace's exact origin, never '*', and only messages from the parent window on that origin are taken. The parent's origin comes from location.ancestorOrigins or the referrer where the browser tells it, and must be one of origins; otherwise ready goes to each allowed origin, and the browser delivers it to the parent's only.
Handshake. The app says ready (with protocol: 2); the workspace's first theme from an allowed origin connects. The webdesktop sends theme and locale on load and again on ready, so an app that connects late still gets them.
Saves always ask for a place (saveAs: true): an app's exports are new files and must never replace the file its window opened last.

What the app does on its side

Framing. Allow exactly the workspace origins in frame-ancestors, and drop X-Frame-Options, which cannot name several origins. Pass the same list as origins.
Manifest. Serve a workspace.app.json (see the webdesktop's readme, External apps): id, name, icon, entry on the same origin, and fileTypes for "Open with".
Sessions. The app's page runs as a third party inside the workspace: cookies the app set when it was opened on its own are not there. In browsers that partition third-party storage, a session cookie set inside the frame needs SameSite=None; Secure; Partitioned, and sign-in through an identity provider that refuses framing goes through a popup. See the webdesktop's readme.plan.md for the single sign-on design.
Downloads. In a workspace, offer "Save to workspace" through saveFile, and fetch downloads inside the frame: a new tab is a different cookie partition.

Development

pnpm install
pnpm test   # build, then the Node tests against a stand-in parent window

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.

readme.md

@workspace.global/appsdk