flexdesk 0.17.3 → 0.17.5

package/docs/components/tiles.md

@@ -0,0 +1,210 @@
+# Dashboard tiles
+
+> **Package:** `@flexdesk/tiles` · [All docs](../README.md)
+
+A draggable, resizable widget grid: the tile base class, the grid, a widget registry, layout persistence, chart and KPI tiles, list and people tiles, the figure tile every Plotly tile draws through, and a form for a tile's settings.
+
+Two different things in FlexDesk are called "tiles". `@flexdesk/wm` tiles the *window* (see [Shell and navigation](shell.md)); `@flexdesk/tiles` is this dashboard *widget grid*.
+
+**On this page**
+
+- [Layouts are keyed by whatever you key them by](#layouts-are-keyed-by-whatever-you-key-them-by)
+- [Chart and KPI tiles (0.13.0)](#chart-and-kpi-tiles-0130)
+- [Figure tiles: one override, the draw is the base's (0.17.0)](#figure-tiles-one-override-the-draw-is-the-bases-0170)
+- [List and people tiles, and one scope for the board (0.16.1)](#list-and-people-tiles-and-one-scope-for-the-board-0161)
+- [A tile's settings as a form: `mountTileConfigForm` (0.17.0)](#a-tiles-settings-as-a-form-mounttileconfigform-0170)
+
+## Layouts are keyed by whatever you key them by
+
+`@flexdesk/tiles` stores layouts under keys **you** choose and resolves a starting
+layout through a callback **you** supply:
+
+```js
+import { configureLayoutPersistence } from '@flexdesk/tiles';
+
+configureLayoutPersistence({
+    layoutsKey: 'myapp.layouts',                          // default: 'twm.tiles.layouts'
+    resolveTemplate: (ctx) => pickTemplate(ctx) ?? null,  // null => empty grid
+});
+```
+
+**Configure it before anything reads it.** The store is a singleton; built before
+you supply your key, it is built with the default, and every layout your users have
+saved becomes silently invisible. That is a data-loss bug that raises no error, so
+the configuration step is explicit rather than lazy.
+
+A layout is keyed by *something* — a document, a user, a run — and the library has
+no opinion about which. It calls that a `contextId`.
+
+## Chart and KPI tiles (0.13.0)
+
+`@flexdesk/tiles` ships two widgets: `flexdesk.chart` (line, bar, area, scatter,
+pie, donut, funnel, histogram — Plotly, so `setPlotlySource` first) and
+`flexdesk.kpi` (one number, a label and an optional delta; plain DOM, no Plotly).
+Nothing registers at import — call `registerChartTiles()` (idempotent). You hand
+a tile **already-computed** series; turning records into series is yours:
+
+```js
+import { registerChartTiles } from '@flexdesk/tiles';
+registerChartTiles();
+const chart = grid.addTile('flexdesk.chart', { x: 0, y: 0, w: 6, h: 4 },
+                           { chart_type: 'line', title: 'Burndown', unit: 'pts' });
+chart.onPointClick = ({ customdata }) => openItem(customdata);
+chart.setData({
+    series: [
+        { x: days, y: remaining, name: 'Remaining', interpolation: 'step', customdata: ids },
+        { x: days, y: ideal, name: 'Ideal', lineStyle: 'dashed' },
+    ],
+    markers: [{ x: today, label: 'Today' }],   // vertical lines
+    note: 'From 41 stories',                    // a line under the figure
+});
+grid.addTile('flexdesk.kpi', { x: 6, y: 0, w: 3, h: 2 }, { title: 'Open', unit: 'bugs' })
+    .setData({ value: 42, reference: 37 });     // ▲ +5 bugs
+```
+
+`setData(null)` or an empty series is the empty state, and it releases any figure
+still drawing. A pie takes `{labels, values}`, a histogram `{values}`. The config
+(`chart_type`, `title`, `unit`, …) round-trips through `getLayout()`/`setLayout()`.
+`buildOverlayShapes` gained `verticalLines: [{x, label?, color?, lineStyle?}]` for
+the same marker outside a tile.
+
+A chart tile's **Download PNG** (0.14.1) goes through the grid's `host`
+(`new TileGrid({ host })`): with `dialogs`, the native Save dialog — a save
+toasts where the file went, a cancel says nothing — and with no host, or a
+`saveFile` that answers null, the browser download it always was.
+
+## Figure tiles: one override, the draw is the base's (0.17.0)
+
+`FigureTile` is the base every Plotly tile draws through — `ChartTile` is one.
+A subclass overrides **one** method, `figure(data)`, answering
+`{traces, layout?, config?, frames?}` or `null`, synchronously:
+
+```js
+import { FigureTile, registerWidget } from '@flexdesk/tiles';
+import { buildHistogramTrace } from '@flexdesk/charts';
+
+class SpreadTile extends FigureTile {
+    static TYPE = 'myapp.spread';
+    static TITLE = 'Spread';
+    figure(data) {
+        if (!data?.values?.length) return null;          // the empty state
+        return { traces: [buildHistogramTrace({ x: data.values })], layout: { margin: { t: 8 } } };
+    }
+}
+registerWidget(SpreadTile);
+```
+
+The base awaits `ensurePlotly()` (so a page using `setPlotlySource` draws on
+first view, and data that changes while Plotly loads draws once), draws through
+`createChart` with `scrollZoom` and the mode bar off (`config` goes over that),
+adds `frames`, and discards a draw that lands after a newer one. `null` is the
+empty state with `static EMPTY_MESSAGE` — call `this.showEmpty(why)` yourself
+first to say why. A `figure()` that throws, or a draw that fails, is the error
+state plus `tile:render-failed {tileId, message}`. Loading, empty, error and
+`dispose()` purge the figure; a resize that settles relayouts it once. The ⋯
+menu is `TileBase`'s entries plus **Download PNG** (through `host.dialogs`, as
+above); extend it with `[...super.menuItems(), …]` and route your actions
+through `_onMenuAction`, calling `super` for the rest. **Expand** opens
+`openRawTracesWindow` with the last figure drawn (`getExpandData()`), and
+`onPointClick({customdata, point, tile})` — an option or a property — hears a
+click on a mark. `setData(data)` feeds one tile; `null` clears it.
+
+`ChartTile` is now a `FigureTile`: its menu stays Download PNG alone, and its
+header gains the Expand button.
+
+## List and people tiles, and one scope for the board (0.16.1)
+
+Two more widgets, registered by `registerListTiles()` (idempotent, nothing at
+import). Like the chart tile they take **rows you have already worked out**;
+what they own is what every list on a board needs: the count ("7 of 12"), the
+line that says what empty means, a button in the bar, a click, the keyboard and
+a right-click menu per row.
+
+```js
+import { registerListTiles, createScopePicker } from '@flexdesk/tiles';
+registerListTiles();
+const late = grid.addTile('flexdesk.list', { x: 0, y: 0, w: 12, h: 4 },
+                          { title: 'Overdue', empty_text: 'Nothing is late.', max_rows: 0 });
+late.onRowActivate = ({ row, event }) => open(row.key, { modified: event.ctrlKey });
+late.rowMenu = ({ row }) => [{ label: 'Open', icon: 'open_in_new', action: 'open' }];
+late.onRowMenuAction = ({ action, row }) => { /* … */ };
+late.onAction = () => openAsList();
+late.setData({
+    rows: [{ key: '7', icon: 'task', lead: 'TASK-0007', title: 'Sign-off',
+             cells: [{ text: 'priya' }, { text: '9 days late', tone: 'danger' }] }],
+    action: { label: 'Open as a list', icon: 'list' },
+});
+grid.addTile('flexdesk.people', { x: 0, y: 4, w: 6, h: 4 }, { title: 'Who has what' })
+    .setData({ people: [{ key: '', name: 'Nobody', muted: true, count: 2,
+                          pills: [{ text: '2 undated', tone: 'muted' }] }] });
+```
+
+- A row is `role="button"`: click, Enter and Space call `onRowActivate` with the
+  event; Up/Down/Home/End move. Right-click, the context-menu key and Shift+F10
+  open the row's menu (`showContextMenu`'s items; none means no menu). A row
+  carries `data-row-key`; `rowsDraggable` makes rows draggable.
+- `{rows: []}` keeps the bar and says `empty` (or `config.empty_text`) where the
+  rows would be; `setData(null)` is the empty state. Text is always text.
+- `tone` (`danger`, `warning`, `ok`, `muted`) picks a colour only; `className`
+  on a row or a cell is yours, added as it is.
+- `groupByPerson(items, personOf)` groups for a people tile, most first.
+
+**One scope for the whole board.** `createScopePicker({options, value, onChange})`
+is a row of buttons, one pressed. `grid.setScope(value)` (or
+`new TileGrid({ scope, onScopeChange })`) hands the value to every tile as
+`tile.scope` and `tile.onScopeChange(scope)`, a tile added later starts with
+it, a grid with a data source reloads its tiles, and the grid's `onScopeChange`
+is told. What a scope means is yours; it is not part of the layout.
+
+## A tile's settings as a form: `mountTileConfigForm` (0.17.0)
+
+`getConfigSchema()` answers `{fields}`; `mountTileConfigForm` draws them, so a
+config panel is no longer a control written by hand per field:
+
+```js
+import { mountTileConfigForm, openTileConfig } from '@flexdesk/tiles';
+const form = mountTileConfigForm(host, {
+    schema: tile.getConfigSchema(),
+    config: tile.config,                       // defaults filled by mergeWithDefaults
+    data,                                      // what getFieldOptions reads for dynamic options
+    onChange: (key, value, config) => tile.update(undefined, config),
+    renderers: { variable: ({ field, value, data, readonly, commit }) => myPicker(...) },
+});
+form.getValues(); form.setValues(next); form.isValid(); form.focusFirstInvalid();
+form.flush(); form.dispose();
+```
+
+- A field is `{key, type, label?, description?, default?, required?, readonly?,
+  min?, max?, step?, options?, visibleWhen?}`. Without a `label` the field is
+  called by its `key`, on its label and in its error messages. Every `FieldTypes` entry has a
+  control (text, number, checkbox, select, multiselect, color, range); any other
+  `type` needs a renderer, which answers an element or
+  `{element, setValue?, dispose?}` and calls `commit(value)` on an edit.
+- An edit is checked by `validateField`. An invalid one shows its error under the
+  field and is **not applied**; a valid one calls `onChange` with the field's key.
+  `isValid()` is false while a shown row has an error; `focusFirstInvalid()`
+  focuses the first such row's control (a renderer's element, or the first
+  focusable element inside it) and answers whether there was one.
+- `commitOn: 'input'` (the default) checks text, number, range and colour
+  controls on every keystroke; `commitOn: 'change'` checks them once the edit is
+  finished (blur, Enter, a released slider), for an `onChange` that is expensive.
+  `flush()` commits an edit typed but not yet finished.
+- `visibleWhen: {field, in: [...]}` (or `{field, equals}`) hides the row, never
+  rebuilds the form, so the control being typed into keeps its focus.
+- A field with no `key` throws. **The built-in tiles' schemas now use `key` and
+  `description`** (they said `name` and `help`, which `validateConfig` and
+  `mergeWithDefaults` never read: BUG-0021). A consumer that read `field.name`
+  or `field.help` from them reads `field.key` and `field.description`.
+
+The grid's cogwheel emits `grid:config-modal-show`, which now also carries the
+grid's `data`. Nothing listens unless you ask:
+`openTileConfig(eventBus, {mode: 'slide-out', host})` shows the form in a
+`SlideOutPanel` over `host` and saves every finished, valid edit (it runs the
+form with `commitOn: 'change'`, so typing a title is one save, not one per
+keystroke; closing the panel saves an edit still being typed);
+`{mode: 'modal'}` (the default) saves on Save, and refuses Save while a field
+shows an error (the modal stays open and the first invalid field is focused). A request that arrives while a
+modal is open is ignored. It answers a function that unsubscribes and closes the
+slide-out; an open modal is left to the user, keeps its form and still saves on
+Save. A renderer's `commit` on a `readonly` field applies nothing and answers
+`{valid: false, error}`.

package/docs/components/wizard.md

@@ -0,0 +1,54 @@
+# Wizard
+
+> **Package:** `@flexdesk/widgets` · [All docs](../README.md)
+
+A multi-step flow: a step indicator, a body slot and a footer with Cancel, Back and Next (Finish on the last step). Mount it inline in your page, or open it in a modal `ManagedWindow`.
+
+## A step wizard: `Wizard` (0.17.0)
+
+`new Wizard({ steps, data, onFinish, onCancel, labels })` (in `@flexdesk/widgets`)
+draws a multi-step flow: a step indicator, a body slot and a footer with Cancel,
+Back and Next (Finish on the last step). Mount it inline with `mount(el)`, or in a
+modal `ManagedWindow` with `openInWindow({ id, title, ... })`.
+
+```js
+const wizard = new Wizard({
+    data: { file: null },
+    steps: [
+        { id: 'source', label: 'Source', icon: 'upload_file',
+          render(bodyEl, ctx) {            // once per visit; may return a cleanup function
+              const input = picker(bodyEl);
+              input.onchange = () => { ctx.data.file = input.files[0]; ctx.revalidate(); };
+          },
+          canAdvance: (ctx) => ctx.data.file
+              ? { ok: true } : { ok: false, hint: 'Choose a file first' } },
+        { id: 'review', label: 'Review', render: (bodyEl, ctx) => review(bodyEl, ctx.data) },
+    ],
+    onFinish: async (ctx) => api.import(ctx.data),   // a rejection marks the step as error
+    onCancel: () => {},
+});
+wizard.openInWindow({ id: 'import', title: 'Import' });
+```
+
+- **Gating.** While the current step's `canAdvance(ctx)` answers `{ok: false, hint}`,
+  Next is disabled and the hint is shown in the footer. `revalidate()` (also
+  `ctx.revalidate()`) asks again and redraws the indicator and the footer; it never
+  re-renders the body, so an input keeps its focus and its value.
+- **Steps** are drawn done / current / upcoming / error, joined by a connector. A
+  done step is a button that jumps back to it; an upcoming step is inert, so the
+  only way forward is Next.
+- **Moves.** `next()`, `back()` and `goTo(idOrIndex)` (back to any earlier step, or
+  forward one step through the gate) resolve `true` when they moved.
+  `setStepState(id, 'error' | null, message)` marks or clears a step.
+- **Finish.** On the last step Next reads Finish and calls `onFinish(ctx)`. Until
+  it settles every button is disabled and moves, cancels and closes are refused,
+  not queued. Resolved, the wizard closes; rejected, the step is marked as error
+  and the rejection's message is shown, and Finish can be pressed again.
+- **Cancel** (the button, `cancel()`, or the window's close button and Escape)
+  closes the wizard and calls `onCancel(ctx)` exactly once. `dispose()` tears it
+  down without calling either callback.
+
+Every transition goes through a core `StateMachine` (`step`, `finishing`,
+`finished`, `cancelled`; pass `eventBus` to see its `fsm:*` events). `ctx` is
+`{data, step, index, revalidate, next, back, goTo, setStepState}`, with `data`
+the object you passed.

package/docs/concepts/building-and-packaging.md

@@ -0,0 +1,33 @@
+# Build and packaging
+
+> **Files:** `build.mjs`, `dist/`, the `exports` map in `package.json` · [All docs](../README.md)
+
+## Build
+
+```bash
+npm install
+npm run build      # -> dist/
+```
+
+`dist/` is committed. The packaging decision is *prebuilt dist*: this repo owns the
+build so that a consumer with no bundler can load the library through a plain import
+map. See `.gitignore` — it says so there too, because it is the kind of thing someone
+"tidies up" later.
+
+### The `development` condition resolves in the installed package (0.17.1)
+
+Every JavaScript entry in the `exports` map has two conditions: `import`, the
+prebuilt bundle under `dist/`, and `development`, the source barrel at the
+package root (`core.js`, `host.js`, `wm.js`, `widgets.js`, `charts.js`,
+`tiles.js`, `editor.js`, `canvas.js`, `flow.js`), which re-exports `src/`.
+Up to 0.17.0 those nine barrels were missing from `files`, so the published
+package did not contain them and a resolver that took the `development` branch
+(`require.resolve` under `--conditions=development`, for one) got a path to
+nothing. From 0.17.1 they ship, beside the `src/` they import.
+
+Nothing about which file an `import` resolves to has changed: `import` is
+listed first, so an ES import still gets `dist/`, with or without the
+`development` condition.
+
+A suite (`tests/exports_packed.test.mjs`) runs `npm pack --dry-run` and fails
+if any target of any condition in the `exports` map is not in the tarball.

package/docs/concepts/domain-neutrality.md

@@ -0,0 +1,110 @@
+# Domain neutrality: your names, keys and globals
+
+> **Packages:** `@flexdesk/core`, `@flexdesk/widgets`, `@flexdesk/editor`, `@flexdesk/charts`, `@flexdesk/tiles` · [All docs](../README.md)
+
+FlexDesk was extracted from [EcoAgent](https://github.com/nor-os/EcoAgent), a macroeconomic simulation platform, and it knows nothing about economics: no application vocabulary, and no import of anything application-specific, in any shipped file. For you that means everything with a name is yours to choose. Storage keys, theme names, drag MIME types and export file names are options with generic defaults, and nothing reads an application's globals. The two sections here list what you can set and where.
+
+## Storage keys and names are yours (0.17.0)
+
+Every localStorage key FlexDesk writes is an option, and so is each name in the
+table below that it registers where other code can see it, except the last row:
+the tile tab MIME is fixed. The defaults are FlexDesk's own; pass yours at boot,
+before the first read:
+
+| What | Default | Set it with |
+|---|---|---|
+| Settings (the `getSetting`/`setSetting` binding) | `'flexdesk.settings.v1'` | `configureSettings({ storageKey })` from `@flexdesk/core` |
+| ManagedWindow geometry | `'flexdesk.managedWindows.v1'` | `ManagedWindow.configure({ storageKey })` from `@flexdesk/widgets` |
+| Saved tile layouts | `'twm.tiles.layouts'` | `configureLayoutPersistence({ layoutsKey })` from `@flexdesk/tiles` |
+| Saved tile configurations | `'twm.tiles.configs'` | `configureLayoutPersistence({ configsKey })` from `@flexdesk/tiles` |
+| Built-in Monaco themes | `'flexdesk-dark'`, `'flexdesk-light'` | `setEditorThemeNames({ dark, light })` from `@flexdesk/editor` |
+| MIME type of a dragged editor tab | `'application/x-flexdesk-tab'` | `setTabDragMime(mime)` from `@flexdesk/editor` |
+| Chart PNG export file name | `'chart'` (saved as `chart.png`) | `setChartExportFilename(name)` from `@flexdesk/charts` |
+| `LoggingService` service name on each entry | `'flexdesk'` | `new LoggingService({ name })` from `@flexdesk/core` |
+| MIME type of a dragged tile tab | `'application/x-twm-tile-tab'` | fixed: not an option; read it as `TILE_TAB_MIME` (or `TileRenderer.TAB_MIME`) from `@flexdesk/wm` |
+
+```js
+import { configureSettings } from '@flexdesk/core';
+import { ManagedWindow } from '@flexdesk/widgets';
+import { setEditorThemeNames, setTabDragMime } from '@flexdesk/editor';
+import { setChartExportFilename } from '@flexdesk/charts';
+
+configureSettings({ storageKey: 'myapp.settings.v1' });
+ManagedWindow.configure({ storageKey: 'myapp.windows.v1' });
+setEditorThemeNames({ dark: 'myapp-dark', light: 'myapp-light' });
+setTabDragMime('application/x-myapp-tab');
+setChartExportFilename('myapp_chart');
+```
+
+Each default is exported beside its setter (`DEFAULT_SETTINGS_STORAGE_KEY`,
+`DEFAULT_WINDOW_STORAGE_KEY`, `DEFAULT_EDITOR_THEME_NAMES`,
+`DEFAULT_TAB_DRAG_MIME`, `DEFAULT_CHART_EXPORT_FILENAME`), and each setter has a
+getter (`getSettingsStorageKey()`, `ManagedWindow.storageKey`,
+`getEditorThemeNames()`, `getTabDragMime()`, `getChartExportFilename()`). An
+embedder that passes nothing gets the defaults silently: nothing is logged.
+
+- **Settings** are read lazily: importing `@flexdesk/core` touches no storage,
+  and the binding reads its key on the first `getSetting`/`setSetting`/reset.
+  `registerSettings()` and `registerSettingsEventBus()` may come before or after
+  `configureSettings()`. Configured after the binding was in use, it moves: values
+  return to their defaults, are reloaded from the new key, and one
+  `settings:changed` (`path: null`) is emitted. The old key is not touched. A
+  private store from `createSettingsStore()` moves the same way with
+  `store.setStorageKey(key)` (and answers `store.getStorageKey()`).
+- **ManagedWindow** reads geometry when a window is first shown; configure it
+  before the first `show()`.
+- **Editor themes**: a factory starts on the dark name current when it is
+  created, and `init()` defines the built-in themes under the names current
+  then. An app with a theme of its own defines it with `monaco.editor.defineTheme`
+  and passes its name to `factory.setTheme(name)`.
+- **The tab MIME** is read at drag time by every `NotebookTabBar` and
+  `EditorPane`, so the two always agree.
+
+**Upgrading from 0.16.** The old defaults were one application's names:
+`'ecosim.settings.v1'`, `'ecosim.managedWindows.v1'`, `'ecosim-dark'` /
+`'ecosim-light'`, `'application/x-ecosim-tab'`, `'ecosim_chart'` and the log
+service name `'ecosim'`. If your users have settings or window geometry saved
+under the old keys, pass those keys explicitly and nothing is lost:
+
+```js
+configureSettings({ storageKey: 'ecosim.settings.v1' });
+ManagedWindow.configure({ storageKey: 'ecosim.managedWindows.v1' });
+```
+
+Code that called `factory.setTheme('ecosim-light')` now calls
+`factory.setTheme(getEditorThemeNames().light)` (or names the themes back with
+`setEditorThemeNames`), and code that read `'application/x-ecosim-tab'` off a drag
+reads `getTabDragMime()`.
+
+## No application globals: the gallery picker and plot-window events (0.17.0)
+
+Nothing under `src/` outside `src/host` reads `window.pywebview` or an
+application's global; `tests/no_app_globals.test.mjs` pins it, with the toast
+helpers ([Notifications](../components/notifications.md#notifications-notificationcenter)) and these two:
+
+**`mountGalleryPicker(el, { entries | host, kind, ... })`** takes its entries from
+`entries`, or else from the host's optional `gallery` capability:
+`host.gallery.list(kind)` answers `[{id, kind, label, description?, fields?}]`
+(or a promise of them). Neither shipped adapter advertises it; add your own:
+
+```js
+const host = createHost({ ...createPywebviewHost({ bridgeRef }),
+                          gallery: { list: (kind) => myBackend.starters(kind) } });
+await mountGalleryPicker(el, { host, kind: 'report', onChange });
+```
+
+With neither `entries` nor the capability, the picker shows its `emptyLabel`
+and logs one warning; a `list` that throws does the same. Until 0.17.0 it
+called one application's bridge method.
+
+**`PlotPopoutWindow({ streamEvents })`** names the bus events a live data
+source emits, next to `refreshEvent`: `{ delta, complete }`. The window
+redraws on each while live update is on. There are no default names: without
+`streamEvents`, or for a name left out or given as `null`, nothing is listened
+for, and the window updates through `refreshEvent` and explicit calls only.
+
+```js
+openPlotPopoutWindow({ id, title, plotConfig, getResults, services,
+                       refreshEvent: 'run:finished',
+                       streamEvents: { delta: 'sim:delta', complete: 'sim:done' } });
+```

package/docs/concepts/host-port.md

@@ -0,0 +1,137 @@
+# Host port
+
+> **Package:** `@flexdesk/host` · [All docs](../README.md)
+
+## The host port
+
+FlexDesk never touches `pywebview`, `fetch`, `localStorage` or the filesystem. It
+asks a **Host**, and you supply one. `createHost({...})` validates the capabilities
+you pass and freezes the result; anything you leave out is simply absent, and the
+library degrades rather than throwing.
+
+```js
+createHost({
+    state:   { read, write },              // layout persistence
+    dialogs: { saveFile, openFile? },      // optional — CSV export falls back to a Blob;
+                                           // openFile (itself optional) to pickFile()
+    window:  { minimize, maximize, ... },  // optional — no native chrome buttons without it
+    gallery: { list },                     // optional (0.17.0) — mountGalleryPicker's entries
+})
+```
+
+`NULL_HOST` is a valid host with nothing behind it.
+
+Two adapters ship ready-made. `createPywebviewHost()` speaks to a pywebview
+window, and `createPhotinoHost()` (0.14.0) to a Photino.NET window over
+`window.external.sendMessage` / `receiveMessage`:
+
+```js
+import { createPhotinoHost } from '@flexdesk/host';
+
+// In a browser tab this is NULL_HOST. Keep a capability of your own by passing
+// it in, or leave one out with null.
+const host = createPhotinoHost({ state: myServerState, onEvent: (name, value) => {} });
+```
+
+`dialogs.saveFile` falls back to a Blob download when the window refuses, and
+the messages the C# side has to answer are in
+[`src/host/photino_host.md`](../../src/host/photino_host.md).
+
+**The dialogs a pywebview bridge answers.** `createPywebviewHost()` calls these
+methods on `window.pywebview.api`, positionally. Each is optional: a missing
+one makes its capability answer `null`, and FlexDesk degrades.
+
+| Bridge method | Arguments | Reply | Behind |
+|---|---|---|---|
+| `save_file_dialog` | `(data, filename, kind)`: the file's text (`csv`) or base64 bytes (`png`), the suggested name, the type | `{ok: true, path}` \| `{ok: false, cancelled: true}` \| `{ok: false, error}` | `dialogs.saveFile` |
+| `read_file_dialog` (0.17.0) | `(accept, kind, encoding)`: a list of extensions or MIME types to filter by (`['.json']`, may be empty), a label for the filter or `null`, and `'text'` or `'base64'` | `{ok: true, name, path, text}` (`'text'`, read as UTF-8) or `{ok: true, name, path, data}` (`'base64'`, the bytes) \| `{ok: false, cancelled: true}` \| `{ok: false, error}` | `dialogs.openFile` |
+
+### Opening a file: `pickFile` (0.17.0)
+
+```js
+import { pickFile } from '@flexdesk/host';
+
+const r = await pickFile(host, { accept: ['.json'], kind: 'json' });   // encoding: 'text' (default) or 'base64'
+if (r.ok) load(JSON.parse(r.text));
+else if (r.error) toast(r.error);                                     // r.cancelled: say nothing
+```
+
+`pickFile(host, {accept, kind, encoding})` takes `accept` as a list or as a
+comma-separated string (`'.json,.csv'`); the host always receives the list
+(`['.json', '.csv']`). It asks the host's
+`dialogs.openFile` first, a new optional member of `dialogs`: a host whose
+`dialogs` has only `saveFile` is still complete. Without it, or when it
+answers `null` (no dialog behind it), a transient hidden
+`<input type="file">` opens the browser's chooser, so the same call works in a
+browser tab, under `NULL_HOST`. Either way it resolves one of
+
+```
+{ok: true, name, path?, text}      encoding 'text'
+{ok: true, name, path?, data}      encoding 'base64': the file's bytes
+{ok: false, cancelled: true}       the user closed the chooser
+{ok: false, error}                 show it
+```
+
+`path` comes only from a native host. The pywebview adapter maps `openFile` to
+`read_file_dialog(accept, kind, encoding)` (the table above); the Photino
+adapter sends `dialogs.openFile`, documented in
+[`photino_host.md`](../../src/host/photino_host.md). The browser chooser reports a
+cancel through the input's `cancel` event, which every current engine fires.
+
+### A window with its own chrome (0.15.0)
+
+The same app runs three ways, and the page needs no switch for it:
+
+| | title bar and borders | FlexDesk draws |
+|---|---|---|
+| a browser tab | the browser's | nothing |
+| a Photino window, native frame | the OS's | nothing |
+| a Photino window, custom frame | none: your top bar is the title bar | minimise / maximise / close, resize handles, drag |
+
+```js
+import { WindowChromeController } from '@flexdesk/widgets';
+
+new WindowChromeController({
+    host,                                  // createPhotinoHost(), or any Host
+    topBar: '.my-top-bar',                 // drags the window (default .twm-global-top-bar)
+    controls: '.my-top-bar .right',        // where the three buttons go (default: the bar's .twm-bar-right)
+    noDrag: '.my-search',                  // more that never starts a drag
+}).initialize();                           // resolves true only with custom chrome
+```
+
+`host.window.chrome()` decides. The Photino host asks its native side once
+(`host.describe`, its `frame` field) and answers `'custom'` only when the
+window was made frameless, so a browser tab and a native-frame window get no
+handles, no buttons and no CSS. With custom chrome, a drag on the top bar and
+a press on a resize handle go to the host's `startNativeDrag()` /
+`startNativeResize(edge)`. On Windows the native side hands them to the OS,
+so the window snaps, takes Win+arrows and resizes like any other.
+[`photino_host.md`](../../src/host/photino_host.md) has the native half: keep the
+frame styles, return the whole window from `WM_NCCALCSIZE`, start gestures with
+`WM_NCLBUTTONDOWN`. Don't use Photino's `SetChromeless`, which loses all of that.
+
+### Links out, and the browser's right-click menu (0.16.0)
+
+In a native window a `target="_blank"` link or a `window.open()` opens nothing,
+or a bare popup with no way back. Hand them to the system browser instead:
+
+```js
+import { routeExternalLinks } from '@flexdesk/host';
+import { suppressNativeContextMenu } from '@flexdesk/widgets';
+
+routeExternalLinks({ host });    // a no-op without host.shell, so call it anywhere
+suppressNativeContextMenu();     // only your own menus, plus the native one in text
+```
+
+`routeExternalLinks` sends http(s) and mailto links that leave the app (a
+`_blank` target, another origin, a middle click) and external `window.open`
+calls to `host.shell.openExternal(url)`. That is a new optional host
+capability, which `createPhotinoHost()` offers as `shell.openExternal`. If the
+native side refuses, the original `window.open` runs. In a browser tab the
+host has no `shell`, and nothing changes.
+
+`suppressNativeContextMenu` prevents the browser's or webview's own menu (Back,
+Reload, Print, Inspect) on any right-click that no handler claimed with
+`preventDefault()`. It keeps the native menu in editable text and on selected
+text, where Paste and Copy are the point, and wherever `allow(event)` says so.
+Both calls return `{ dispose }`.

package/docs/concepts/packages-and-entry-points.md

@@ -0,0 +1,32 @@
+# Packages and entry points
+
+> **Install:** see the [quickstart](../quickstart.md) · **Component pages:** [docs index](../README.md#components) · [All docs](../README.md)
+
+## Nine entry points
+
+Because someone who wants a DataTable should not have to download a window
+manager, and neither of them should drag in a plotting engine or a code editor.
+
+| Entry | Size | What is in it |
+|---|---|---|
+| `@flexdesk/core` | 30 kB | Event bus, settings store, logging, state machine, state guard |
+| `@flexdesk/host` | 5 kB | The [host port](host-port.md) |
+| `@flexdesk/wm` | 166 kB | Tiling window manager: tabs, splits, desktops, command palette, taxonomy, `createShell()` |
+| `@flexdesk/widgets` | 192 kB | DataTable, modals, managed windows, toasts, trees, panels, context menus, menu bars, a document outline, progress, a conversation view |
+| `@flexdesk/charts` | 26 kB | Plotly wrapper, chart types, subplot layouts, downsampling, a plot grid, a plot-config editor, plot windows, injected series transforms |
+| `@flexdesk/tiles` | 67 kB | Draggable/resizable widget grid, tile base class, widget registry, layout persistence, figure, chart and KPI tiles |
+| `@flexdesk/editor` | 62 kB | Monaco loader + factory, multi-file tab bar, search, split panes, undo manager |
+| `@flexdesk/canvas` | 14 kB | The canvas kernel: a pannable, zoomable surface, the edge router, a generic graph layer ([Flow editors](../components/flow-editors.md#flow-editors)) |
+| `@flexdesk/flow` | 381 kB | The flow-editor kit and the canvas, outline and lane editors ([Flow editors](../components/flow-editors.md#flow-editors)) |
+
+The sizes of `@flexdesk/canvas` and `@flexdesk/flow` are the entry files as
+`node build.mjs` reported them for the flow editors' integration build; like
+every entry they also import shared chunks. The other rows are older figures.
+
+They share code through chunks, so importing two of them does **not** give you two
+event buses — and therefore not two copies of every module-level singleton. A test
+asserts each kernel symbol is defined exactly once across the whole `dist/`.
+
+Two different things here are called "tiles", which is unfortunate but honest to
+the code: `@flexdesk/wm` tiles the *window*; `@flexdesk/tiles` is a dashboard
+*widget grid*.

package/docs/concepts/peer-dependencies.md

@@ -0,0 +1,42 @@
+# Peer dependencies: Plotly and Monaco
+
+> **Used by:** [Charts](../components/charts.md), [Editor](../components/editor.md), the chart and figure [tiles](../components/tiles.md) · [All docs](../README.md)
+
+## Peer dependencies
+
+`@flexdesk/charts` needs Plotly (4.4 MB). `@flexdesk/editor` needs Monaco (14 MB).
+Neither is bundled, and **neither is guessed at**:
+
+```js
+import { setPlotlySource } from '@flexdesk/charts';
+import { setMonacoBasePath, setDefaultLanguage } from '@flexdesk/editor';
+
+setPlotlySource('/vendor/plotly/plotly.min.js');
+setMonacoBasePath('/vendor/monaco');
+setDefaultLanguage('my-dsl');              // default: 'plaintext'
+```
+
+There is deliberately **no default path**. A hardcoded `'vendor/monaco'` is one
+application's directory layout, and for everyone else it is a 404 that surfaces as
+an editor which silently never appears. `initMonaco()` throws instead.
+
+`getEditorFactory()` and `initMonaco()` **reject** when no path was set, when
+`vs/loader.js` fails to load, or when Monaco's AMD loader reports an error, so a
+consumer can show a message instead of waiting forever. What happens next
+depends on which of those it was:
+
+- **`vs/loader.js` failed to load** (a 404, a wrong path): not sticky. Fix the
+  path (`setMonacoBasePath`, or pass it to `initMonaco`) and the next call
+  tries again.
+- **Monaco's AMD loader reported an error** (`vs/editor/editor.main` or a
+  dependency failed): **final for the page**. Monaco's loader caches the failed
+  module and has no way to forget it, so every later call rejects with that
+  same first error, whatever path it is given. Fix the path and reload.
+
+Loading is shared: if you call `initMonaco(path)` yourself, `getEditorFactory()`
+uses that load and needs no `setMonacoBasePath()`. `monacoReady` only ever
+resolves — it is the "Monaco has arrived" signal, not the place to learn that
+an attempt failed.
+
+If you already load Plotly yourself (a `<script>` tag that sets `window.Plotly`),
+the chart loader short-circuits and you can skip `setPlotlySource`.