gesso-framework 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,201 @@
 # gesso-framework
 
+## 0.4.0
+
+### Minor Changes
+
+- **The browser shells post OS file drops.** The `fileDrop` message, its shape and
+  the session that turns it into an ordinary drag have existed since drop targets
+  did, and nothing posted one: a zone accepting `gesso/files` could be written and
+  never reached.
+
+  `attachFileDrop` is the shell half, shared by `createApp`'s worker shell and
+  `createSyncApp`'s single-thread one because it is the same four DOM events
+  either way. It answers drags that carry files and no others, prevents the
+  default on every `dragover` (which is what tells a browser the drop is wanted)
+  and on `drop` (or the tab is replaced by the file), and reads the bytes before
+  posting the drop. The worker shell transfers the buffers rather than copying
+  them; a drop whose files cannot be read is reported as a leave, so no zone stays
+  lit waiting. `GessoRuntime.applyFileDrop` hands the message to the tree's drag
+  session.
+
+  The core half was wrong in a way no spec could have caught: `applyFileDrop` began
+  a drag with the files of `enter` and, on `drop`, only moved it, so a zone
+  received the payload the drag started with. A browser lets a page see the _types_
+  of dragged files and nothing else until they are let go, so that payload has
+  empty names and no bytes — every file dropped from a desktop would have arrived
+  unopenable. The spec that covered it sent the same files on both phases, which is
+  the one shape a browser never produces. It now sends what one does.
+
+- **`interceptKey`, for a shortcut the app takes from the browser.**
+  `interceptFind` cancelled one browser default so an app's own find bar could
+  have Ctrl+F. An app with a Save of its own needs the same for Ctrl+S, or
+  Chrome's "Save page as" opens over it, and one with an Open for Ctrl+O.
+
+  The shell has to decide before the worker has heard of the key, so the decision
+  stays the application's and is made on the main thread: a predicate over the
+  `KeyboardEvent`, which can say "Ctrl or Cmd" in one line where a list could not.
+  The key is still forwarded; only the browser's default is cancelled. The
+  single-thread shell needs nothing, since its platform adapter already cancels
+  whatever the app's own listener claimed.
+
+- **Files through the shell — open, save, reopen, recent.** A picker, a download
+  and a `FileSystemFileHandle` are all the window's, so an application in a render
+  worker could read a dropped file and do nothing else with files at all.
+  `ShellService` now asks the shell, in the shape a popup and a storage request
+  already have: a request with an id, and one `ShellFileResult` back on every path.
+
+  ```
+  openFiles    showOpenFilePicker, or a file input where there is none
+  saveFile     to a handle (Save), a picker (Save As), or a download
+  reopenFile   a remembered file, asking permission again if it lapsed
+  recentFiles  the remembered files, most recently used first
+  forgetFile   stop remembering one
+  ```
+
+  A handle crosses as a number. The `FileSystemFileHandle` is not plain data, so
+  the shell keeps it — in IndexedDB, which can hold one — and a number handed out
+  yesterday still names yesterday's file, which is the whole of how "recent files"
+  survives a reload. The same file picked twice is one entry (`isSameEntry`, not
+  identity), and past fifty the least recently used is let go. What does not
+  survive a reload is the permission, and asking needs a gesture, so reopening
+  belongs in a click handler as much as a picker does.
+
+  `cancelled` is its own outcome because closing a picker is a decision, not a
+  failure; `denied` is the browser refusing; `unsupported` is a shell with no way
+  to do it. Without the File System Access API files come back with `handle` null
+  and a save is a download, and the answer says so rather than leaving the
+  application to feature-test.
+
+  `saveFile` takes bytes as well as text, for a file that is not text — a zip, an
+  image. Bytes cross the barrier on the way out as they already do on the way in,
+  in `ShellFile.bytes`, and are written to the handle, the picked file or the
+  download in place of the text when given.
+
+### Patch Changes
+
+- **A key typed before the editing proxy has focus keeps its text.** The proxy
+  takes DOM focus when the worker reports a focused editable, a round trip; a key
+  typed in that gap reaches the canvas, and the text it would have made never
+  exists.
+
+  The `keyDown` message now says whether it came through the proxy (`textFollows`),
+  and a key that did not is inserted by the runtime when an editable has the focus.
+
+  Typing a word quickly into a spreadsheet cell the first letter opens kept only
+  the first letter.
+
+- **A shell request made while the root is built is held, not dropped.** The root
+  is built in the runtime's constructor, so a component that reads a stored
+  preference as it mounts asked before `onShellRequest` could have been called,
+  and the request went nowhere — for a storage or file request, a promise that
+  never settled.
+
+  The runtime now holds what is asked before a listener attaches, up to 256, and
+  hands it over when one does.
+
+  Found by a spreadsheet's status-bar figures that never came back after a reload.
+
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - gesso-core@0.4.0
+
+## 0.3.0
+
+### Minor Changes
+
+- 025321a: **Breaking: the single-thread configuration is `createSyncApp`.** `createApp` now
+  builds the worker configuration and nothing else.
+
+  ```diff
+  -createApp(AppRoot).useChannel(Catalog, { source }).mountSync('#app');
+  +createSyncApp(AppRoot).useChannel(Catalog, { source }).mountSync('#app');
+  ```
+
+  Nothing else changes: same builder, same methods, same `mountSync`. The worker
+  form, `createApp({ renderWorker })` and the form `gesso-vite-plugin` writes, is
+  untouched, so an application that mounts into a render worker needs no edit.
+  `createApp` given a component throws and names `createSyncApp`, because the fix
+  is one identifier and a message that does not say which one turns a rename into
+  an afternoon.
+
+  The reason is what it costs on the wire. `createApp` took either the options or
+  a root component, and the overload that took a component reached
+  `GessoAppBuilder` → `GessoApp` → `GessoRuntime`: the layout engine, both
+  renderers and the hit-tester, statically, in every shell. A bundler cannot see
+  which half of one function a given call reaches, so every worker application
+  shipped the whole engine to the thread whose entire job is to create a canvas
+  and forward input.
+
+  Measured on the smallest honest shell, built from source:
+
+  |        | raw      | gzipped  |
+  | ------ | -------- | -------- |
+  | before | 662.9 kB | 169.3 kB |
+  | after  | 46.2 kB  | 12.3 kB  |
+
+  And on a real application, gessosheet's shell: 524.9 kB to 152.9 kB raw, 152.7 kB
+  to 45.0 kB gzipped. `check-bundle-size.ts` holds the line in CI with a budget and
+  with a look for Canvas2D calls in the shell's bytes, because the number alone
+  would pass a build that kept the rasterizer and got lucky.
+
+  Two names cost one line in the configuration that was always the exception, and
+  take 120 kB off the main thread of every other kind.
+
+- 025321a: **`fanOut`, for when every node wants its own slice.** One source, N things on
+  screen, each reading one part of it: a grid, a timeline, a log viewer all arrive
+  at this shape, and the natural spelling does not scale. A pipe per slice runs N
+  pipelines on every emission whatever changed, and RxJS removes an observer from a
+  Subject by scanning its list, so tearing down a window of N is quadratic.
+
+  `fanOut(source, read, { initial })` holds one subscription for the whole registry
+  and hands out a stable cell per key. Its `changed` hint is where a frame is won: a
+  source that knows which keys a patch touched reads only those. Ten thousand live
+  keys, measured against a pipe per key: mount 29.8 ms to 10.7 ms, teardown 9.7 ms
+  to 3.7 ms, and one key changing 2.2 ms to 0.1 ms.
+
+  Reach for it when N is large _and each emission touches few of them_. A source
+  that republishes its whole window on every scroll gets the cheaper mount and
+  teardown and nothing from `changed`, because every key really did change.
+
+  It compares by reference where `select` and `derive` compare by content, which is
+  the opposite default for the opposite reason: those run once per emission and this
+  runs once per live key per emission. And a registry that has grown past a couple
+  of thousand keys having released none of them says so once, because `release` is
+  the caller's and forgetting it is the one thing here that goes wrong silently.
+
+  **`tabStop`, which is `tabindex="-1"`.** Focusable, reachable by a press and by
+  `focus()`, skipped by the Tab cycle. `focusable` only ever answered "may this node
+  hold focus", which is the wrong question for a container: `UiFocusManager.settleScope`
+  blurred when a scope held nothing focusable, so a `Dialog` whose content is a
+  sentence handed the keyboard to nothing and could not be dismissed with Escape.
+  `settleScope` now falls back to the scope root before blurring, and `Dialog` sets
+  `focusable: true, tabStop: false` on its body. Both halves are needed and neither
+  is enough alone.
+
+  **`borders()`, a border per edge, as paint.** `borderWidth` is one number and
+  `borderColor` one colour, so a node could not have a heavy bottom edge and a
+  hairline top. A border here is paint-only and a decoration is already a coloured
+  rectangle in the node's own paint pass, so four edges are four draw instances and
+  no extra nodes. `DecorationBox` gains `right` and `bottom` to put them: any two of
+  near edge, size and far edge fix an axis, which is CSS's rule for an absolutely
+  positioned box, and the only one that can express a side edge spanning between two
+  horizontal ones.
+
+  **`menuBarStep`, a menu bar's keyboard, as a peer of `Menu`.** `Menu` traps focus,
+  which is right for a popup opened by a button and wrong for a bar: with focus in
+  the panel, ArrowLeft cannot reach the bar to move to the menu next door, and that
+  is most of what makes a bar a bar. A pure function, generic in the command type,
+  that returns null for a key it does not claim, so a bar can still be tabbed out of.
+
+### Patch Changes
+
+- Updated dependencies [025321a]
+- Updated dependencies [025321a]
+  - gesso-core@0.3.0
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -70,7 +70,7 @@ The shell spawns both workers, joins them with one `MessageChannel`, hands each
 
 A component body runs **once**, and an `Observable` binds straight into the retained graph. So there is no re-render pass, no virtual DOM diff, no `useEffect`, and no base class to extend for your state. Component identity _is_ node identity, so there is no second reconciler.
 
-Single-thread mode exists for tests, headless rendering and environments without `OffscreenCanvas`: `createApp(NotesApp).useChannel(Notes, { source }).mountSync('#app')`. Channels resolve in-process there, so the same contract runs with no ports.
+Single-thread mode exists for tests, headless rendering and environments without `OffscreenCanvas`: `createSyncApp(NotesApp).useChannel(Notes, { source }).mountSync('#app')`. Channels resolve in-process there, so the same contract runs with no ports.
 
 ## Entry points