@qxuken/kui 0.1.0-alpha.39 → 0.1.0-alpha.40

package/CHANGELOG.md

@@ -21,6 +21,95 @@ listed under both (backlog F61, from the alpha.12 field reports: the list
 is what the release knows it broke, and a fix it did not think of as one
 was the first bare bump to break an app in five releases).
 
+## 0.1.0-alpha.40 (2026-10-07)
+
+**What breaks.**
+
+- Rust: `InputEvent` gains `Open(Vec<String>)`, so an exhaustive `match`
+  on it needs an arm.
+
+C stays at ABI 25 (`kui_input_open` is a new function) and the Node wire
+at v21.
+
+### Added
+
+- **The documents the OS asks the app to open reach it** (backlog F124,
+  from kawoosh). The Finder's Open With, a file dropped on the Dock icon,
+  `open -a YourApp file`, a double-click on a document type the bundle's
+  `Info.plist` declares (`CFBundleDocumentTypes`): AppKit hands every one
+  to the application delegate's `application:openURLs:`, which winit's
+  delegate does not answer, so they went nowhere. The macOS runner adds
+  it to winit's delegate class once per process, and the app hears
+  `{kind:"open", paths}` on the root — file-system paths, one event per
+  request, asked for or not. A launch's documents, which AppKit sends
+  before any window exists and leaves out of the arguments, wait for the
+  main window and arrive on its first turn; while the app runs they
+  arrive at once. A delegate class that already answers documents (an
+  app's own override) is left alone. Headless and for a host with its
+  own window: `InputEvent::Open(paths)`, C `kui_input_open`, Node
+  `ctx.openDocuments(paths)` (`OpenMsg` in `CoreMsg`). Windows and Linux
+  hand documents over in the process's arguments, and nothing sends it
+  there.
+
+**What you can delete.** An `NSApplicationDelegate` method added or
+swizzled by hand onto winit's delegate to hear a Finder open, and the
+queue that held a launch's paths until a window existed to show them.
+
+### Native verification
+
+The by-hand round alpha.6 introduced (backlog R4), on 2026-10-07 — the
+one round after the alpha.39 tag: the documents the OS asks the app to
+open (F124) — with a regression pass over it first: the diff read whole,
+each claim probed before anything changed. The probes ran in a window,
+since the half that can break is AppKit's: a scratch app on the
+release tree's `kui-native`, bare and in an ad-hoc-signed bundle
+declaring `public.data` (`LSHandlerRank` `Alternate`). `open -a` at
+launch handed over both documents in one `open` event, `argv` the
+executable alone; two `open -a` calls into the running instance arrived
+as two events, in order, each with its request's paths in their order.
+And the one thing an added `application:openURLs:` could have started
+that F124's own checks did not look at: AppKit taking the process's
+arguments for documents once the delegate answers them
+(`NSTreatUnknownArgumentsAsOpen`). A binary run from a terminal with a
+path, a subcommand, a missing file and a flag, bare and as the bundle's
+own executable, even with `-NSTreatUnknownArgumentsAsOpen YES`, heard
+no `open` — so an app that reads its arguments and hears `open` too
+does not open a file twice. The non-macOS side (`pump_open_documents`
+without `macos_open`) is clean under clippy for `x86_64-pc-windows-msvc`.
+Nothing was filed. This round ran on the Mac alone; Windows and Linux
+did not run it for this tag.
+
+**macOS 27.0.1 on an M3 Pro MacBook Pro, rustc 1.99.0 (the toolchain
+CI runs), Node 25.6.0, nu 0.116.1**, on the release commit's tree.
+`cargo fmt --all --check` and `cargo clippy --workspace --all-targets
+--features kui-core/conformance -- -D warnings` are clean, and so is
+`cargo audit --deny warnings`. `cargo test --workspace --features
+kui-core/conformance`: **1822 tests over 137 suites, 0 failed** (4
+ignored). The C round, `cbuild --run`, passes its five checks; the
+corpus passes its **57 scenes** in four adapters, the `drop` scene now
+ending with two documents opened; the ABI is **25**. Node's `node --test
+test.mjs` under `KUI_CONFORMANCE_REQUIRED=1`: **211 of 211**. `npm run
+gen` leaves no diff, the examples typecheck and their lockfile installs,
+the headless round passes all **35 drives**, the book builds and
+`scripts/book-examples.nu --check` passes.
+
+**The windowed round**, `smoke -- --node`, three times over — twice
+before the version bump, once on the release tree: **51 Rust examples
+and the eleven Node examples, each on both bases, 120 frames each, every
+one exiting 0** — 124 windows, eight at a time, in 32.3, 32.5 and
+38.8 s — and `counter`, `host`, `c_panel` and `lua_panel` by hand under
+`KUI_SMOKE_FRAMES=120`, each exiting 0 with nothing on stderr: **128
+windows over five hosts.** The AX audit: **106/106**, the audited window
+raised to the front by its pid first, and no warning on the fixture's
+stderr. F124 itself was seen in kawoosh's window before the merge, built
+against the branch by path.
+
+**The bench guard** against the alpha.39 tag: **green**, none of the 8
+guarded rows more than 10% slower — every one between −3.2% and +3.5%
+(the worst guarded run-to-run spread 1.3%) — and no row of the run more
+than 4.7% slower (`frame_1k_paths_animating`, a frame F124 does not
+reach). `README.md`'s table is kept as it was.
+
 ## 0.1.0-alpha.39 (2026-10-06)
 
 **What breaks.**

package/howto.md

@@ -750,6 +750,35 @@ drive, and `dropTarget()` is what a driver answers the OS with.
 [`drop` payload](props.md#events) ·
 [`examples/rust/features/drop.rs`](../examples/rust/features/drop.rs)
 
+### How do I hear the documents the OS opens: Finder's Open With, the Dock icon?
+
+Handle `{kind:"open", paths}` in `update` (Rust `on_event`, C's event
+callback): it arrives on the root, asked for or not, with the file-system
+paths of the documents the Finder's Open With, a file dropped on the Dock
+icon, `open -a YourApp file.rs` or a double-click handed the app. The
+macOS runner hears them from the application delegate's
+`application:openURLs:` — at launch, where AppKit sends them before the
+window exists and puts none in the arguments, the paths wait for the main
+window and arrive on its first turn; while the app runs, at once. One
+`open` per request, several paths when the user opened several.
+
+The app's bundle has to say it opens documents, or the Finder will not
+offer it: an `Info.plist` with `CFBundleDocumentTypes`, one entry per
+kind — `LSItemContentTypes` the UTIs (`public.plain-text`,
+`public.source-code`, `public.data` for anything), `CFBundleTypeRole`
+`Editor` or `Viewer`, and `LSHandlerRank` `Alternate` to be listed in Open
+With without taking the type's double-click from its owner (`Default` or
+`Owner` to take it). Re-register a bundle you rebuilt in place with
+`lsregister -f YourApp.app` if the Finder still has the old list.
+
+On Windows and Linux the documents are in the process's arguments (a
+file association, a `.desktop` file's `%F`), and nothing sends `open`.
+Headless, `ctx.openDocuments(paths)` (C `kui_input_open`, Rust
+`InputEvent::Open`) is the drive.
+
+[`open` payload](props.md#events) ·
+[alpha.40 `### Added`](CHANGELOG.md#010-alpha40-2026-10-07)
+
 ### How do I have global shortcuts and a Tab ring at once?
 
 Put the keymap on an `onKey` sink that encloses the controls: a focused

package/index.d.ts

@@ -368,6 +368,18 @@ export type SystemMsg = {
  *  A font the app loads itself raises none. */
 export type FontsMsg = { kind: 'fonts' };
 
+/** The OS asked the app to open these documents (backlog F124): the
+ *  Finder's Open With, a file dropped on the Dock icon, `open -a`, a
+ *  double-click on a document type the app's Info.plist declares
+ *  (`CFBundleDocumentTypes`). Delivered on the root whether or not the app
+ *  asked — at launch, once the window is open, and while it runs. `paths`
+ *  are file-system paths. macOS only: Windows and Linux hand documents over
+ *  in `process.argv`. `ctx.openDocuments(paths)` is the headless drive. */
+export type OpenMsg = {
+  kind: 'open';
+  paths: string[];
+};
+
 /** A declared window opened, or closed — because nothing declares it any
  *  more, or because the user closed it. A window the user closed stays
  *  closed while it is still declared (a declaration reopens a window only
@@ -496,7 +508,8 @@ export type CoreMsg =
   | SoundMsg
   | AccessMsg
   | ChangeMsg
-  | FilesMsg;
+  | FilesMsg
+  | OpenMsg;
 
 /** A stock slider's proposal (docs/adr/0034-stock-controls-over-the-roles.md):
  *  the core turned a press, a drag, an arrow, a Page key, Home / End or an
@@ -2161,6 +2174,14 @@ export declare class Ctx {
    * asked it is dropped.
    */
   answerFiles(paths: Array<string>): void
+  /**
+   * The OS asked the app to open these documents (backlog F124) — the
+   * Finder's Open With, a file dropped on the Dock icon, `open -a`: the
+   * app hears `{kind:"open", paths}` on the root whether or not it
+   * asked; none is nothing. A `KuiWindow` on macOS hears it from the
+   * runner; this is the headless drive.
+   */
+  openDocuments(paths: Array<string>): void
   /**
    * The dragged files released at (`x`, `y`): the zone there hears
    * `{kind:"drop", phase:"drop", paths, x, y, tag}` and no `leave`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qxuken/kui",
-  "version": "0.1.0-alpha.39",
+  "version": "0.1.0-alpha.40",
   "description": "kui for Node: JSX views lowered into the kui IR, Elm-style messages as data",
   "license": "MIT",
   "repository": {

package/props.md

@@ -202,6 +202,7 @@ one field. The payload shapes:
 | hover | `{ kind: "hover", phase: "enter" \| "leave", by: "pointer" \| "content", tag }` | The pointer entered or left an `onHover` node — also when a new frame moved it under a still cursor. `by` says which (backlog DX20): `pointer` when the pointer moved or left the window, `content` when it stayed and what is under it changed — a list scrolled by the wheel or the keys, a row that grew, a float that opened. A picker whose selection follows the pointer ignores `content`, or the rows sliding under a still pointer as the keys scroll the list drag the selection with them. |
 | drop | `{ kind: "drop", phase: "enter" \| "move" \| "leave" \| "drop", paths: string[], x, y, tag }` | Files dragged in from the OS over an `onDrop` node (`docs/adr/0031-a-drop-zone-is-a-row-and-the-files-are-an-event.md`): `enter` when they come over the zone, `move` while they move over it (never twice for one point), `leave` when they go to another zone, to no zone or out of the window, `drop` when they land — and no `leave` after a `drop`. `paths` are the OS paths as strings; `x`/`y` the pointer in logical viewport coordinates, absent on `leave`. The zone is the topmost one under the pointer by paint order; a node inside it is its, and a node that is no zone is looked past (an overlay shown on `enter` does not end the hover). Nothing is re-resolved when a frame lands: only the driver's next report moves the files, so a zone the view stops declaring hears its `leave` then. |
 | files | `{ kind: "files", paths: string[], tag }` | A file dialog's answer (backlog C51): what an Open, Save or folder dialog asked for with `requestFiles` / `request_files` / `kui_request_files` picked — the OS paths, as a `drop` carries them — or no paths when the user cancelled. `tag` is the dialog's own. It reaches whoever asked: the host, or the extension whose fill asked; one dialog is out at a time. |
+| open | `{ kind: "open", paths: string[] }` on the root | The OS asked the app to open documents (backlog F124): the Finder's Open With, a file dropped on the Dock icon, `open -a App file`, a double-click on a document of a type the app's `Info.plist` declares under `CFBundleDocumentTypes`. Delivered to the host on the root whether or not anything asked — unlike `files`, which answers an ask. `paths` are file-system paths as strings; a URL of a scheme the app registers is not one, and is not carried (room is left for a `urls` beside `paths`). The macOS runner sends it at launch — held until the main window has opened, since AppKit hands the documents over before it exists and puts none in the arguments — and while the app runs; a host driving its own window sends it as input (`openDocuments`, `kui_input_open`, `InputEvent::Open`). Windows and Linux pass documents in the process's arguments instead, and nothing sends it there. |
 | layout | `{ kind: "layout", x, y, w, h, parent: { x, y, w, h }, scale, tag }` | The rect layout gave an `onLayout` node (logical px, viewport coords, after scrolling and easing): on its first frame and whenever it changes, never on a frame that left it alone. `scale` is physical px per logical px at the node — `w × scale` by `h × scale` is how many pixels to render for it before `updateImage` (the frame's scale today; where a zoom would compose in). |
 | resize | `{ kind: "resize", width, height, scale }` | The viewport changed size or DPI (logical px, delivered to the host on the root): the window less the devtools' dock while the panel is docked (`docs/adr/0024`), so a dock coming, going or being dragged is a resize too. `KuiWindow.size()` queries the same numbers, before the first frame as well (backlog F43). The first frame establishes the viewport rather than reporting it, so a dock present at launch posts none. |
 | window | `{ kind: "window", phase: "opened" \| "closed" \| "focused" \| "blurred", name, id }` | A declared window opened (the diff queued its `Open`) or closed — because nothing declares it any more, or because the user closed it, in which case it stays closed while still declared: stop declaring `name`, then declare it again to reopen. `id` is what its events carry; the event itself is on the root of whichever window's frame noticed. `focused` and `blurred` are this window gaining and losing the keyboard (backlog DX18) — `env.focused` changing, as the driver reports it — so an app that saves on blur or re-reads the clipboard on return hears it once instead of diffing `env.focused` every frame. |
@@ -631,7 +632,7 @@ binding is a row with its three other cells, or a red test.
 | `Core::set_time` | `kui_set_time` | `Ctx.setTime` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The clock the tweens read; a window's runner sets it from the display. |
 | `Core::env` | `kui_env_set` and its four siblings, `ENV_FIELDS`' C column | `Ctx.setEnv` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The host facts written in (the `env` field); a `KuiWindow`'s runner writes its own. |
 | `Ui::env` | *none: C is the host, so it writes the facts and has no reading (`ENV_FIELDS`)* | `env` | `env`, the view's argument | The facts read back, `ENV_FIELDS` row for row. |
-| `Core::handle_input` | `kui_input_cursor` … `kui_input_access`, one per `InputEvent` | `Ctx.cursor` … `Ctx.access`, one per `InputEvent`; a `KuiWindow` refuses injection | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | Pointer, wheel, key, text, IME, assistive and OS file-drag input; a wheel gesture's latching is `scroll_gesture` (`kui_input_scroll_gesture`, `Ctx.scrollGesture`, backlog F107); `press` / `release` are a click by label (`kui_input_press`, `Ctx.press`); the file drag is `drag_files` / `drop_files` / `drag_cancel` (ADR 0031); a file dialog's answer is `answer_files` (`kui_input_files`, `Ctx.answerFiles`, backlog C51). |
+| `Core::handle_input` | `kui_input_cursor` … `kui_input_access`, one per `InputEvent` | `Ctx.cursor` … `Ctx.access`, one per `InputEvent`; a `KuiWindow` refuses injection | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | Pointer, wheel, key, text, IME, assistive and OS file-drag input; a wheel gesture's latching is `scroll_gesture` (`kui_input_scroll_gesture`, `Ctx.scrollGesture`, backlog F107); `press` / `release` are a click by label (`kui_input_press`, `Ctx.press`); the file drag is `drag_files` / `drop_files` / `drag_cancel` (ADR 0031); a file dialog's answer is `answer_files` (`kui_input_files`, `Ctx.answerFiles`, backlog C51); the documents the OS asked the app to open are `InputEvent::Open` (`kui_input_open`, `Ctx.openDocuments`, backlog F124). |
 | `Core::modifiers` | `kui_input_modifiers` | `Ctx.modifiers` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The modifier state, reported on its own when the OS does (backlog AR22). |
 | `Core::release_held_keys` | `kui_release_held_keys` | `Ctx.setEnv({focused: false})` releases, as losing the keyboard does for every driver (ADR 0020) | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | Lets go of every key the focused sink holds. |
 | `Core::set_subpixel_text` | `kui_set_subpixel_text` | *none: a Node host never paints: the renderer behind `KuiWindow` is the runner's, and a headless `Ctx` has none* | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | LCD subpixel coverage for outline glyphs, for a renderer that blends per channel. |