flexdesk 0.14.1 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flexdesk",
-    "version": "0.14.1",
+    "version": "0.15.1",
     "description": "A tiling window manager and widget set for desktop-class web applications. Zero runtime dependencies.",
     "license": "MIT",
     "repository": {

package/src/host/host.js

@@ -19,7 +19,8 @@ export const HOST_CONTRACT = Object.freeze({
     window: Object.freeze({
         required: Object.freeze(['chrome', 'minimize', 'close', 'isMaximized', 'setMaximized',
                                  'isFullscreen', 'toggleFullscreen', 'getBounds', 'setBounds']),
-        optional: Object.freeze(['startNativeDrag']),
+        // `chrome()` answers 'native' or 'custom', or a promise of one.
+        optional: Object.freeze(['startNativeDrag', 'startNativeResize']),
     }),
     dialogs: Object.freeze({ required: Object.freeze(['saveFile']), optional: Object.freeze([]) }),
     state:   Object.freeze({ required: Object.freeze(['read', 'write']), optional: Object.freeze([]) }),

package/src/host/photino_host.js

@@ -99,6 +99,10 @@ export function createPhotinoTransport({ external, timeoutMs = 10000, onEvent =
  * @param {number} [opts.timeoutMs=10000]
  * @param {(name: string, value: any) => void} [opts.onEvent]
  * @param {object} [opts.logger=console]
+ * @param {'auto'|'native'|'custom'} [opts.chrome='auto']  who draws the window's
+ *        title bar and borders. `auto` asks the native side once (`host.describe`,
+ *        its `frame` field), the first time somebody needs to know; `native`
+ *        or `custom` fixes the answer without asking. See photino_host.md.
  * @param {object|null} [opts.window]   replace the window capability, or `null` to leave it out
  * @param {object|null} [opts.dialogs]  replace the dialogs capability, or `null` to leave it out
  * @param {object|null} [opts.state]    replace the state capability, or `null` to leave it out
@@ -110,6 +114,7 @@ export function createPhotinoHost(opts = {}) {
         timeoutMs = 10000,
         onEvent = null,
         logger = console,
+        chrome = 'auto',
     } = opts;
     if (!isPhotinoWindow(external)) return NULL_HOST;
 
@@ -121,11 +126,32 @@ export function createPhotinoHost(opts = {}) {
     };
     const fire = (cap, op, ...args) => { void soft(null, cap, op, ...args); };
 
+    // Who draws the frame. Asked once and remembered: a string once known, the
+    // pending question before that. A native side that predates `frame`, or
+    // doesn't answer within 3 s, has native chrome.
+    let frame = chrome === 'custom' || chrome === 'native' ? chrome : null;
+    let asking = null;
+    const askFrame = () => {
+        if (frame) return frame;
+        asking ??= request('host', 'describe', [], { wait: 3000 })
+            .then((d) => (d && d.frame === 'custom' ? 'custom' : 'native'), () => 'native')
+            .then((f) => { frame = f; return f; });
+        return asking;
+    };
+    // A drag or resize handed to the OS: the reply comes when the mouse is
+    // released, however long that takes. Refused (a native side without the op,
+    // or a window with native chrome) means "not handled": the caller does it in JS.
+    const gesture = async (op, ...args) => {
+        try { await request('window', op, args, { wait: 0 }); return true; }
+        catch (e) { return false; }
+    };
+
     const defaults = {
         window: {
-            // Photino draws a decorated, native window on every OS: FlexDesk's
-            // own min/max/close buttons would be a second set.
-            chrome: () => 'native',
+            // 'native' (the OS draws the frame: FlexDesk's own buttons would be
+            // a second set) or 'custom' (the native side made the window
+            // frameless). A promise until the native side has said which.
+            chrome: () => askFrame(),
             minimize: () => { fire('window', 'minimize'); },
             close: () => { fire('window', 'close'); },
             isMaximized: async () => (await soft(false, 'window', 'isMaximized')) === true,
@@ -137,6 +163,8 @@ export function createPhotinoHost(opts = {}) {
                 if (!b || typeof b !== 'object') return null;
                 return { x: b.x, y: b.y, width: b.width, height: b.height };
             },
+            startNativeDrag: () => gesture('startDrag'),
+            startNativeResize: (edge) => gesture('startResize', String(edge || '')),
             // Not async, like pywebview's: a rAF hot path during a drag; nobody awaits.
             setBounds({ x = null, y = null, width = null, height = null } = {}) {
                 fire('window', 'setBounds', { x, y, width, height });

package/src/host/photino_host.md

@@ -28,6 +28,7 @@ host → page   {"event": "window.maximizedChanged", "value": true}
 
 | `cap.op` | `args` | reply `value` | Photino |
 |---|---|---|---|
+| `host.describe` | `[]` | `{frame: "native" \| "custom", …}` | asked once, for `chrome()` (see below) |
 | `window.minimize` | `[]` | anything | `Minimized = true` |
 | `window.close` | `[]` | anything | `Close()` |
 | `window.isMaximized` | `[]` | `bool` | `Maximized` |
@@ -36,13 +37,65 @@ host → page   {"event": "window.maximizedChanged", "value": true}
 | `window.toggleFullscreen` | `[]` | `bool`, the state now | `FullScreen = !FullScreen` |
 | `window.getBounds` | `[]` | `{x, y, width, height}` | `Location`, `Size` |
 | `window.setBounds` | `[{x, y, width, height}]`, any of them `null` = leave alone | anything | `Location`, `Size` |
+| `window.startDrag` | `[]` | anything, **after mouse-up** | custom chrome only: the OS move loop (below) |
+| `window.startResize` | `[edge]`: `n` `s` `e` `w` `ne` `nw` `se` `sw` | anything, **after mouse-up** | custom chrome only: the OS size loop (below) |
 | `dialogs.saveFile` | `[{data, filename, kind}]` | see below | `ShowSaveFile(...)` + write |
 | `state.read` | `[key]` | the stored value, or `null` | a file per key |
 | `state.write` | `[key, value]` | `true` | a file per key |
 
-`window.chrome()` is answered by the adapter itself (`'native'`): Photino draws a
-native title bar, so FlexDesk draws no buttons of its own. `startNativeDrag` is
-not offered.
+## Native or custom chrome
+
+A FlexDesk app runs in one of three ways, and the page needs no switch for it:
+
+| | title bar and borders | `chrome()` | FlexDesk draws |
+|---|---|---|---|
+| a browser tab | the browser's | (no Photino host) | nothing |
+| a Photino window, native frame | the OS's | `'native'` | nothing |
+| a Photino window, custom frame | none: the page's top bar | `'custom'` | buttons, resize handles, drag |
+
+`window.chrome()` asks the native side once, with `host.describe`, the first
+time it's called (that is `WindowChromeController.initialize()`). It resolves
+`'custom'` when the reply's `frame` is `"custom"`, and `'native'` for anything
+else: no `frame` field, an `ok: false`, no answer within 3 s. An app that knows
+already can say so: `createPhotinoHost({ chrome: 'custom' })` or `'native'`
+answers without asking.
+
+**What the native side does for a custom frame (Windows).** Don't use
+Photino's `SetChromeless(true)`: that makes a bare popup window, with no
+snapping, no Win+arrows, no shadow and square corners, and Photino then reports
+it as fullscreen. Keep the normal window and stop drawing its frame:
+
+1. After the window exists, add `WS_CAPTION | WS_THICKFRAME | WS_MINIMIZEBOX |
+   WS_MAXIMIZEBOX | WS_SYSMENU` to its style, and subclass it
+   (`SetWindowSubclass`). These styles are what make Windows treat it as a
+   normal window: Aero Snap, Win+arrows, the shadow, the rounded corners on
+   Windows 11.
+2. In the subclass, answer `WM_NCCALCSIZE` (with `wParam` true) with `0`, so
+   the whole window is client area and nothing of the frame is drawn. While
+   maximised (`IsZoomed`), set the proposed rect to the monitor's work area
+   first: a maximised window is larger than the monitor by the frame's
+   thickness, and the taskbar must stay visible.
+3. Answer `WM_NCACTIVATE` with `DefSubclassProc(h, msg, wParam, -1)`, so
+   Windows repaints no caption on activation.
+4. `DwmExtendFrameIntoClientArea` with a top margin of 1 keeps DWM drawing
+   the shadow. `DWMWA_WINDOW_CORNER_PREFERENCE = DWMWCP_ROUND` asks for the
+   rounded corners.
+5. Call `SetWindowPos(..., SWP_FRAMECHANGED | SWP_NOMOVE | SWP_NOSIZE |
+   SWP_NOZORDER)` to apply it.
+
+The WebView covers the whole window, so the window never sees the mouse. That
+is what `startDrag` and `startResize` are for. The page asks when the mouse
+goes down on its top bar or on a resize handle. On the window's thread, call
+`ReleaseCapture()`, then `SendMessage(hwnd, WM_NCLBUTTONDOWN, hit, cursor)`
+with `HTCAPTION` for a drag, or `HTTOP` / `HTBOTTOM` / `HTLEFT` / `HTRIGHT` /
+`HTTOPLEFT` / … for the edge. Windows then runs its own move or size loop,
+exactly as for a click on a real caption or border, and `SendMessage` returns
+when the mouse is released. Reply then. The page waits without a timeout, and a
+reply of `ok: false` makes it move or resize the window from JS instead.
+
+`describe`'s reply says `frame: "custom"` only when all of this was done. A
+Photino window on Linux or macOS keeps its native frame and says `"native"`, or
+leaves `frame` out.
 
 **`dialogs.saveFile`.** `kind` is the file type the caller is saving, `'csv'`
 or `'png'` today. `data` is the file's text for `csv` and the file's bytes,

package/src/tiling/tile_breadcrumb.js

@@ -238,14 +238,18 @@ function _renderInto(container, segments) {
         const isLast = i === segments.length - 1;
         if (isLast || !seg.onClick) {
             li.classList.add('twm-topbar-breadcrumb__item--current');
+            // The current level, for assistive technology; the title carries
+            // the full label once a host's CSS truncates it (Tables BUG-0109).
+            li.setAttribute('aria-current', 'page');
             li.innerHTML = `
                 <span class="material-symbols-outlined twm-topbar-breadcrumb__icon">${_esc(seg.icon)}</span>
-                <span class="twm-topbar-breadcrumb__current">${_esc(seg.label)}</span>
+                <span class="twm-topbar-breadcrumb__current" title="${_esc(seg.label)}">${_esc(seg.label)}</span>
             `;
         } else {
             const btn = document.createElement('button');
             btn.className = 'twm-topbar-breadcrumb__link';
             btn.type = 'button';
+            btn.title = String(seg.label ?? '');
             btn.innerHTML = `
                 <span class="material-symbols-outlined twm-topbar-breadcrumb__icon">${_esc(seg.icon)}</span>
                 <span>${_esc(seg.label)}</span>

package/src/ui/controllers/window_chrome_controller.js

@@ -8,10 +8,29 @@
  * - F11 fullscreen toggle
  *
  * Talks to the embedder ONLY through a Host's `window` capability
- * (see ui/js/host/host.js). A host with no `window` capability — a browser
+ * (see src/host/host.js). A host with no `window` capability — a browser
  * tab, a VS Code webview, the standalone demo — is legal: we simply don't
  * install custom chrome. That degraded path is also the production path on
  * Linux, macOS and `--browser`, where the OS/browser draws the title bar.
+ *
+ * THREE MODES, decided by `host.window.chrome()` (which may answer with a
+ * promise: the Photino host asks its native side): a browser tab and a window
+ * with native chrome get NOTHING from this class (no handles, no buttons, no
+ * body class), and only a window that answers `custom` gets the chrome.
+ *
+ * NATIVE GESTURES. A host that offers `startNativeDrag()` and
+ * `startNativeResize(edge)` gets drags on the top bar and presses on the
+ * resize handles handed to the OS, which brings snapping and a resize that
+ * keeps up with the pointer. A host without them gets the JS move and resize
+ * over getBounds/setBounds.
+ *
+ * @param {object} [opts]
+ * @param {object} [opts.host]          a Host; only its `window` capability is used
+ * @param {string|Element} [opts.topBar='.twm-global-top-bar']  the bar that drags the window
+ * @param {string|Element} [opts.controls]  where to draw minimise/maximise/close when
+ *        the page has no `#win-minimize`/`#win-maximize`/`#win-close` of its own
+ *        (default: the top bar's `.twm-bar-right`, else the top bar itself)
+ * @param {string} [opts.noDrag]        more selectors that never start a drag
  */
 
 const SUPPORTS_POINTER = typeof window !== 'undefined' && 'onpointerdown' in window;
@@ -20,9 +39,13 @@ const MIN_HEIGHT = 350;
 const DRAG_THRESHOLD = 4;
 
 export class WindowChromeController {
-    constructor({ eventBus, logger, host } = {}) {
+    constructor({ eventBus, logger, host, topBar = '.twm-global-top-bar', controls = null, noDrag = '' } = {}) {
         this.eventBus = eventBus;
         this.logger = logger || console;
+        this._topBarOpt = topBar;
+        this._controlsOpt = controls;
+        this._noDrag = noDrag;
+        this._createdControls = null;
 
         // The host's window capability, or null. Never throw on a missing
         // one — see the class comment.
@@ -40,17 +63,22 @@ export class WindowChromeController {
     /**
      * Initialize the window chrome controller
      */
-    initialize() {
-        if (this._disposed) return;
+    async initialize() {
+        if (this._disposed) return false;
 
-        if (!this.win || this.win.chrome() !== 'custom') {
+        let chrome = 'native';
+        try { chrome = this.win ? await this.win.chrome() : 'native'; } catch (_) { chrome = 'native'; }
+        if (this._disposed) return false;
+        if (chrome !== 'custom') {
             // Native window decorations (Linux/macOS) or the browser already
             // provide a title bar + window controls; our custom chrome would be
             // a redundant second set. Skip it entirely.
             this.logger.info?.('[WindowChrome] Native/browser chrome detected — custom window chrome disabled');
-            return;
+            return false;
         }
 
+        document.body.classList.add('twm-custom-chrome');
+        this.#createWindowControls();
         this.#wireWindowButtons();
         this.#createResizeHandles();
         this.#wireTopBarDrag();
@@ -59,6 +87,47 @@ export class WindowChromeController {
         this.#initializeState();
         
         this.logger.info?.('[WindowChrome] Initialized');
+        return true;
+    }
+
+    /** An element from a selector or an element; null when there is none. */
+    #resolve(target, within = document) {
+        if (!target) return null;
+        if (typeof target !== 'string') return target;
+        return within.querySelector(target);
+    }
+
+    /**
+     * Draw minimise, maximise/restore and close, unless the page has its own
+     * `#win-*` buttons (EcoSim's markup), which are then wired instead.
+     */
+    #createWindowControls() {
+        if (document.getElementById('win-minimize') || document.getElementById('win-close')) return;
+        const bar = this.#resolve(this._topBarOpt);
+        const host = this.#resolve(this._controlsOpt)
+            || bar?.querySelector('.twm-bar-right')
+            || bar;
+        if (!host) return;
+        const box = document.createElement('div');
+        box.className = 'twm-window-controls';
+        const button = (id, icon, label, extra = '') => {
+            const b = document.createElement('button');
+            b.type = 'button';
+            b.id = id;
+            b.className = `twm-window-controls__btn${extra}`;
+            b.setAttribute('aria-label', label);
+            b.title = label;
+            const i = document.createElement('span');
+            i.className = 'material-symbols-outlined';
+            i.textContent = icon;
+            b.appendChild(i);
+            box.appendChild(b);
+        };
+        button('win-minimize', 'remove', 'Minimize');
+        button('win-maximize', 'check_box_outline_blank', 'Maximize');
+        button('win-close', 'close', 'Close', ' twm-window-controls__btn--close');
+        host.appendChild(box);
+        this._createdControls = box;
     }
 
     /**
@@ -110,6 +179,7 @@ export class WindowChromeController {
         const tooltipText = isMax ? 'Restore' : 'Maximize';
         window.LatexTooltip?.set(maxBtn, tooltipText);
         maxBtn.setAttribute('aria-label', tooltipText);
+        maxBtn.title = tooltipText;
         
         document.body.classList.toggle('twm-window-maximized', isMax);
     }
@@ -188,8 +258,23 @@ export class WindowChromeController {
 
         let activePointerId = null;
 
+        const EDGE = {
+            right: 'e', left: 'w', top: 'n', bottom: 's',
+            cornerBR: 'se', cornerBL: 'sw', cornerTR: 'ne', cornerTL: 'nw',
+        };
+
         const startDrag = async (e) => {
+            if (e.button != null && e.button !== 0) return;
             e.preventDefault();
+            // ── Native resize: the OS runs its own size loop (it blocks until
+            // mouse-up), so the edge stays under the pointer. ──
+            if (this.win.startNativeResize) {
+                this.resizingActive = true;
+                let handled = false;
+                try { handled = await this.win.startNativeResize(EDGE[mode]); } catch (_) { handled = false; }
+                this.resizingActive = false;
+                if (handled) return;
+            }
             this.resizingActive = true;
             startX = e.clientX;
             startY = e.clientY;
@@ -313,10 +398,18 @@ export class WindowChromeController {
      * Setup top bar dragging for window movement
      */
     #wireTopBarDrag() {
-        this.topBar = document.querySelector('.twm-global-top-bar');
+        this.topBar = this.#resolve(this._topBarOpt);
         if (!this.topBar) return;
 
-        const NO_DRAG_SELECTOR = '.no-drag, button, input, select, textarea, .menu-item, .menu-dropdown, .window-controls, .panel-toggles, .global-search-dropdown';
+        // What never starts a drag: anything you can click or type into. An
+        // embedder adds its own with `noDrag`. (`.window-controls` and
+        // `.panel-toggles` are kept for EcoSim-shaped markup.)
+        const NO_DRAG_SELECTOR = [
+            '.no-drag', 'button', 'a', 'input', 'select', 'textarea', 'label',
+            '[role="button"]', '[role="menuitem"]', '[role="tab"]', '[contenteditable="true"]',
+            '.twm-window-controls', '.window-controls', '.panel-toggles',
+            this._noDrag,
+        ].filter(Boolean).join(', ');
 
         let dragging = false;
         let startSX = 0, startSY = 0, startX = null, startY = null, winW = 0, winH = 0;
@@ -533,8 +626,7 @@ export class WindowChromeController {
         // Double-click to toggle maximize (only on blank surfaces)
         const dblClickHandler = async (e) => {
             // Skip maximize if double-click is on interactive elements
-            const interactiveSelector = 'button, input, select, textarea, a, [role="button"], [role="menuitem"], .menu-bar, .fl-bar, .fl-item, .global-search-wrapper, .panel-toggle-btn';
-            if (e.target.closest(interactiveSelector)) {
+            if (isInteractiveTarget(e.target)) {
                 return;
             }
 
@@ -646,13 +738,16 @@ export class WindowChromeController {
         });
         this._disposers = [];
 
-        // Remove resize handles
+        // Remove resize handles, and the buttons this drew
         Object.values(this.handles).forEach(handle => {
             if (handle && handle.parentNode) {
                 handle.parentNode.removeChild(handle);
             }
         });
         this.handles = {};
+        this._createdControls?.remove();
+        this._createdControls = null;
+        document.body.classList.remove('twm-custom-chrome', 'twm-window-maximized', 'window-fullscreen');
 
         this.logger.info?.('[WindowChrome] Disposed');
     }